Skip to content

Papermark is the open-source DocSend alternative and secure data rooms with built-in analytics and custom domains.

8.1 KB
Raw Blame
import type { NextRequest } from "next/server";

import { Axiom } from "@axiomhq/js";
import { waitUntil } from "@vercel/functions";

import type { ErrorCode } from "@/lib/api/errors";

// One structured event per public-API request. Metadata only — never request
// bodies, query values, or path-param values — so it's safe to ship to an
// analytics sink without a PII review.
export interface ApiUsageEvent {
  /** Correlates this log line with the response's `x-request-id` header. */
  request_id: string;
  timestamp: string;
  /** Null when auth failed before a token resolved (e.g. bad/missing bearer). */
  team_id: string | null;
  token_id: string | null;
  user_id: string | null;
  subject_type: string | null;
  /** How the token was issued: `dashboard` | `oauth`. */
  source: string | null;
  plan: string | null;
  /** `live` | `test`. */
  mode: string | null;
  /** Which caller: `cli` | `mcp` | `mcp-remote` | `api` (raw) | `other`. */
  client: string;
  client_version: string | null;
  /** MCP host the agent runs in (claude.ai, cursor, …); null for non-MCP. */
  client_host: string | null;
  method: string;
  /** Route template, e.g. `/api/v1/links/:id` — never the populated path. */
  route: string;
  status: number;
  duration_ms: number;
  /** Scopes the endpoint required (what permission the call exercised). */
  scopes_required: string[];
  /** Error code on failure, else null. */
  error_code: ErrorCode | null;
}

// Bounded, log-injection-safe label: lowercased, charset-restricted, capped.
// Returns null for empty/invalid input so we never emit blanks.
function sanitizeLabel(
  raw: string | null | undefined,
  maxLen = 40,
): string | null {
  if (!raw) return null;
  const cleaned = raw
    .trim()
    .toLowerCase()
    .replace(/[^a-z0-9._-]/g, "")
    .slice(0, maxLen);
  return cleaned || null;
}

/**
 * Derive the calling client and its version/host from the identification
 * headers the CLI and MCP servers send. Falls back to `api` for raw HTTP
 * callers that send no `x-papermark-client`.
 */
export function readClientIdentity(req: NextRequest): {
  client: string;
  client_version: string | null;
  client_host: string | null;
} {
  return {
    client: sanitizeLabel(req.headers.get("x-papermark-client")) ?? "api",
    client_version: sanitizeLabel(
      req.headers.get("x-papermark-client-version"),
      32,
    ),
    client_host:
      req.headers.get("x-papermark-client-host")?.trim().slice(0, 120) || null,
  };
}

/**
 * Turn the populated request path into a low-cardinality route template by
 * swapping each matched dynamic segment value for `:key`, e.g.
 * `/api/v1/links/abc123` → `/api/v1/links/:id`. Best-effort: good enough for
 * grouping in analytics without threading route metadata through the app.
 */
export function routeTemplate(
  pathname: string,
  params: Record<string, string>,
): string {
  let out = pathname;
  for (const [key, value] of Object.entries(params)) {
    if (!value) continue;
    out = out.split(`/${value}`).join(`/:${key}`);
  }
  return out;
}

// --- Sinks -----------------------------------------------------------------
// Axiom via the official @axiomhq/js client (handles region + batching);
// PostHog via a plain keepalive fetch. Both inert until their env is set.

const AXIOM_TOKEN = process.env.AXIOM_TOKEN;
const AXIOM_DATASET = process.env.AXIOM_DATASET;
// AXIOM_EDGE: region edge domain, e.g. `eu-central-1.aws.edge.axiom.co`; unset → US.
const AXIOM_EDGE = process.env.AXIOM_EDGE;

const axiom =
  AXIOM_TOKEN && AXIOM_DATASET
    ? new Axiom({
        token: AXIOM_TOKEN,
        ...(AXIOM_EDGE ? { edge: AXIOM_EDGE } : {}),
      })
    : null;

// Reuses the app's existing project key; posts to the PostHog EU region
// (matches the browser proxy target in lib/middleware/posthog.ts).
const POSTHOG_KEY = process.env.NEXT_PUBLIC_POSTHOG_KEY;
const POSTHOG_HOST = "https://eu.i.posthog.com";

function hasSinkConfigured(): boolean {
  return Boolean(axiom || POSTHOG_KEY);
}

// Raw request events → Axiom. `_time` marks the event timestamp; the flush is
// wrapped in waitUntil so the batched event survives a post-response
// serverless freeze (off-Vercel it just runs in the background).
function sendToAxiom(event: ApiUsageEvent): void {
  if (!axiom || !AXIOM_DATASET) return;
  try {
    axiom.ingest(AXIOM_DATASET, [{ _time: event.timestamp, ...event }]);
    // .catch before waitUntil: a flush rejection is async, so the try/catch
    // here (sync only) wouldn't swallow it.
    waitUntil(axiom.flush().catch(() => {}));
  } catch {
    // never let a sink break a request
  }
}

/**
 * Await delivery of any queued Axiom events. No-op when Axiom isn't
 * configured. Useful for graceful shutdown and for scripts/tests that emit
 * events and need to guarantee they land before the process exits.
 */
export async function flushUsage(): Promise<void> {
  if (axiom) await axiom.flush();
}

// Higher-level product view → PostHog, attributed to the team via group
// analytics. Only team-attributed requests are sent (anonymous auth failures
// have no team to group under and would just be noise here).
async function sendToPostHog(event: ApiUsageEvent): Promise<void> {
  if (!POSTHOG_KEY || !event.team_id) return;
  await fetch(`${POSTHOG_HOST}/capture/`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      api_key: POSTHOG_KEY,
      event: "api_request",
      distinct_id: `team:${event.team_id}`,
      timestamp: event.timestamp,
      properties: {
        $groups: { team: event.team_id },
        client: event.client,
        client_version: event.client_version,
        client_host: event.client_host,
        method: event.method,
        route: event.route,
        status: event.status,
        duration_ms: event.duration_ms,
        plan: event.plan,
        source: event.source,
        mode: event.mode,
        error_code: event.error_code,
        $insert_id: event.request_id,
      },
    }),
    keepalive: true,
  });
}

/**
 * Emit a usage event. Fire-and-forget and fully self-contained: never throws,
 * never blocks the response. Fans out to Axiom + PostHog when configured and
 * falls back to a structured stdout line otherwise (or in development, or when
 * API_USAGE_STDOUT=1) so events are never silently dropped.
 */
export function emitApiUsage(event: ApiUsageEvent): void {
  try {
    sendToAxiom(event);
    // waitUntil so the delivery fetch survives a post-response serverless
    // freeze — keepalive alone doesn't guarantee completion in the Node runtime.
    waitUntil(sendToPostHog(event).catch(() => {}));

    if (
      !hasSinkConfigured() ||
      process.env.NODE_ENV !== "production" ||
      process.env.API_USAGE_STDOUT === "1"
    ) {
      console.log(`[api-usage] ${JSON.stringify(event)}`);
    }
  } catch {
    // Logging must never break a request.
  }
}

export interface LogApiRequestInput {
  req: NextRequest;
  params: Record<string, string>;
  requestId: string;
  startedAt: number;
  status: number;
  scopesRequired: readonly string[];
  errorCode?: ErrorCode | null;
  token?: {
    tokenId: string;
    userId: string;
    teamId: string;
    subjectType: string;
    source: string;
    mode: string;
  } | null;
  plan?: string | null;
}

/** Assemble an {@link ApiUsageEvent} from request context and emit it. */
export function logApiRequest(input: LogApiRequestInput): void {
  const { req, params, token } = input;
  const identity = readClientIdentity(req);
  emitApiUsage({
    request_id: input.requestId,
    timestamp: new Date().toISOString(),
    team_id: token?.teamId ?? null,
    token_id: token?.tokenId ?? null,
    user_id: token?.userId ?? null,
    subject_type: token?.subjectType ?? null,
    source: token?.source ?? null,
    plan: input.plan ?? null,
    mode: token?.mode ?? null,
    client: identity.client,
    client_version: identity.client_version,
    client_host: identity.client_host,
    method: req.method,
    route: routeTemplate(req.nextUrl.pathname, params),
    status: input.status,
    duration_ms: Math.max(0, Date.now() - input.startedAt),
    scopes_required: [...input.scopesRequired],
    error_code: input.errorCode ?? null,
  });
}