Documenso Observability

// src/observability/documenso-metrics.ts
import { Documenso } from "@documenso/sdk-typescript";

interface Metrics {
  requestCount: number;
  errorCount: number;
  totalLatencyMs: number;
  errorsByStatus: Record<number, number>;
}

const metrics: Metrics = {
  requestCount: 0,
  errorCount: 0,
  totalLatencyMs: 0,
  errorsByStatus: {},
};

export function createInstrumentedClient(): Documenso {
  const client = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });

  return new Proxy(client, {
    get(target, prop) {
      const value = (target as any)[prop];
      if (typeof value === "object" && value !== null) {
        return new Proxy(value, {
          get(innerTarget, method) {
            const fn = (innerTarget as any)[method];
            if (typeof fn !== "function") return fn;

            return async (...args: any[]) => {
              const start = Date.now();
              metrics.requestCount++;

              try {
                const result = await fn.apply(innerTarget, args);
                metrics.totalLatencyMs += Date.now() - start;
                return result;
              } catch (err: any) {
                metrics.errorCount++;
                const status = err.statusCode ?? 0;
                metrics.errorsByStatus[status] = (metrics.errorsByStatus[status] || 0) + 1;
                metrics.totalLatencyMs += Date.now() - start;
                throw err;
              }
            };
          },
        });
      }
      return value;
    },
  });
}

// Expose metrics for Prometheus scraping
export function getMetrics() {
  return {
    ...metrics,
    avgLatencyMs: metrics.requestCount > 0
      ? Math.round(metrics.totalLatencyMs / metrics.requestCount)
      : 0,
    errorRate: metrics.requestCount > 0
      ? (metrics.errorCount / metrics.requestCount * 100).toFixed(2) + "%"
      : "0%",
  };
}

// src/observability/logger.ts
import { createLogger, format, transports } from "winston";

const logger = createLogger({
  level: process.env.LOG_LEVEL ?? "info",
  format: format.combine(
    format.timestamp(),
    format.json()
  ),
  defaultMeta: { service: "documenso-integration" },
  transports: [
    new transports.Console(),
    // Add file or cloud transport for production
  ],
});

// Log Documenso operations with structured context
export function logDocumensoOperation(
  operation: string,
  documentId?: number,
  extra?: Record<string, any>
) {
  logger.info("documenso_operation", {
    operation,
    documentId,
    ...extra,
  });
}

// Log errors with full context
export function logDocumensoError(
  operation: string,
  error: any,
  documentId?: number
) {
  logger.error("documenso_error", {
    operation,
    documentId,
    statusCode: error.statusCode,
    message: error.message,
    // Never log API keys
  });
}

// src/api/health.ts
import { Documenso } from "@documenso/sdk-typescript";

interface HealthStatus {
  status: "healthy" | "degraded" | "unhealthy";
  latencyMs: number;
  message: string;
}

async function checkDocumensoHealth(): Promise<HealthStatus> {
  const client = new Documenso({ apiKey: process.env.DOCUMENSO_API_KEY! });
  const start = Date.now();

  try {
    await client.documents.findV0({ page: 1, perPage: 1 });
    const latencyMs = Date.now() - start;

    if (latencyMs > 5000) {
      return { status: "degraded", latencyMs, message: "High latency" };
    }
    return { status: "healthy", latencyMs, message: "OK" };
  } catch (err: any) {
    return {
      status: "unhealthy",
      latencyMs: Date.now() - start,
      message: `${err.statusCode ?? "unknown"}: ${err.message}`,
    };
  }
}

// Express endpoint
app.get("/health/documenso", async (req, res) => {
  const health = await checkDocumensoHealth();
  const httpStatus = health.status === "healthy" ? 200 : health.status === "degraded" ? 200 : 503;
  res.status(httpStatus).json(health);
});

// src/api/metrics.ts
import { getMetrics } from "../observability/documenso-metrics";

app.get("/metrics/documenso", (req, res) => {
  const m = getMetrics();
  res.type("text/plain").send(`
# HELP documenso_requests_total Total API requests
# TYPE documenso_requests_total counter
documenso_requests_total ${m.requestCount}

# HELP documenso_errors_total Total API errors
# TYPE documenso_errors_total counter
documenso_errors_total ${m.errorCount}

# HELP documenso_avg_latency_ms Average request latency
# TYPE documenso_avg_latency_ms gauge
documenso_avg_latency_ms ${m.avgLatencyMs}
  `.trim());
});

// Track webhook delivery success/failure
const webhookMetrics = {
  received: 0,
  processed: 0,
  failed: 0,
  byEvent: {} as Record<string, number>,
};

app.post("/webhooks/documenso", async (req, res) => {
  webhookMetrics.received++;
  const { event } = req.body;
  webhookMetrics.byEvent[event] = (webhookMetrics.byEvent[event] || 0) + 1;

  res.status(200).json({ received: true });

  try {
    await processWebhookEvent(req.body);
    webhookMetrics.processed++;
  } catch (err) {
    webhookMetrics.failed++;
    logDocumensoError("webhook_processing", err);
  }
});

// Expose webhook metrics
app.get("/metrics/webhooks", (req, res) => {
  res.json(webhookMetrics);
});

# alerting-rules.yml (Prometheus)
groups:
  - name: documenso
    rules:
      - alert: DocumensoHighErrorRate
        expr: rate(documenso_errors_total[5m]) / rate(documenso_requests_total[5m]) > 0.05
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Documenso error rate above 5%"

      - alert: DocumensoUnhealthy
        expr: up{job="documenso-health"} == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "Documenso health check failing"

      - alert: DocumensoHighLatency
        expr: documenso_avg_latency_ms > 5000
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "Documenso average latency above 5s"