@sixthsummit/ship-api 0.0.0-stage → 4.1.1

package/lib/modules/outbox/routes.ts

@@ -0,0 +1,219 @@
+import type {
+  AuthenticatedAccount,
+  AuthProvider,
+} from "@sixthsummit/ship-api/app/auth/AuthProvider";
+import type { AppEnv } from "@sixthsummit/ship-api/http/app/createApp";
+import { createModuleApp } from "@sixthsummit/ship-api/http/app/createApp";
+import { NotFoundError } from "@sixthsummit/ship-api/http/errors/NotFoundError";
+import { requireAuth } from "@sixthsummit/ship-api/http/middleware/requireAuth";
+import { requirePermission } from "@sixthsummit/ship-api/http/middleware/requirePermission";
+import { validate } from "@sixthsummit/ship-api/http/utils/validate";
+import type { Hono, Schema } from "hono";
+import type { BlankSchema } from "hono/types";
+import { z } from "zod";
+
+import type { OutboxDrainer } from "./OutboxDrainer.js";
+import { OUTBOX_PERMISSIONS } from "./permissions.js";
+import type { OutboxEvent } from "./schema.js";
+import type { OutboxEventService } from "./services/OutboxEventService.js";
+
+/**
+ * v4 outbox routes — `defineOutboxRoutes(app, deps)`.
+ *
+ * Wires:
+ *
+ *   GET    /outbox          list events (filterable)
+ *   GET    /outbox/stats    per-status counts
+ *   GET    /outbox/count    total count
+ *   GET    /outbox/:id      single event
+ *   POST   /outbox/drain    admin: trigger a drain pass
+ *   POST   /outbox/recover  admin: reset stale processing
+ *
+ * Drain + recover are POST (mutating actions), gated by the admin
+ * `outbox:drain` / `outbox:recover` permissions. Drain returns the
+ * structured per-pass result so the operator sees what just
+ * happened. Read-only endpoints sit behind `outbox:read`.
+ *
+ * Drain by default does *one pass*. Pass `?untilEmpty=true` to flush
+ * the entire queue (catch-up after an outage). `batchSize` is also
+ * tunable via query param.
+ */
+
+export interface OutboxRoutesDeps<TAccount extends AuthenticatedAccount = AuthenticatedAccount> {
+  service: OutboxEventService;
+  drainer: OutboxDrainer;
+  provider: AuthProvider<TAccount>;
+}
+
+const idParam = z.object({
+  id: z.string().uuid(),
+});
+
+const listQuery = z
+  .object({
+    search: z.string().min(1).optional(),
+    eventType: z.string().min(1).optional(),
+    status: z.enum(["pending", "processing", "published", "failed"]).optional(),
+    page: z.coerce.number().int().positive().default(1),
+    perPage: z.coerce.number().int().positive().max(200).default(50),
+  })
+  .strict();
+
+const drainBody = z
+  .object({
+    batchSize: z.number().int().positive().max(500).optional(),
+    untilEmpty: z.boolean().optional(),
+  })
+  .strict();
+
+const recoverBody = z
+  .object({
+    /** Threshold in ms; rows in 'processing' older than this get reset. */
+    staleThresholdMs: z.number().int().positive().optional(),
+  })
+  .strict();
+
+/**
+ * ⚠️ FOOT-GUN: do NOT thread one shared `app` through several modules'
+ * `defineXxxRoutes` calls — it accumulates one giant Hono route-type and
+ * detonates `tsc` (TS2589) at scale. Prefer {@link buildOutboxApp} mounted via
+ * `root.route("/", buildOutboxApp(deps))`. This raw form is kept for advanced
+ * composition.
+ */
+// Generic over Hono's schema param `S` so an already-chained app keeps its
+// previously registered route types — `Hono<AppEnv>` here would widen them
+// away. See defineAccountsRoutes for the full rationale.
+export function defineOutboxRoutes<
+  TAccount extends AuthenticatedAccount = AuthenticatedAccount,
+  S extends Schema = BlankSchema,
+>(app: Hono<AppEnv, S>, deps: OutboxRoutesDeps<TAccount>) {
+  const auth = requireAuth({ provider: deps.provider });
+
+  return app
+    .get(
+      "/outbox",
+      auth,
+      requirePermission(OUTBOX_PERMISSIONS.outboxRead),
+      validate("query", listQuery),
+      async (c) => {
+        const q = c.req.valid("query");
+        const offset = (q.page - 1) * q.perPage;
+        const where: Record<string, unknown> = {};
+        if (q.eventType) where.eventType = q.eventType;
+        if (q.status) where.status = q.status;
+        const result = await deps.service.list({
+          search: q.search,
+          where: Object.keys(where).length > 0 ? where : undefined,
+          limit: q.perPage,
+          offset,
+        });
+        const sanitized = (result.rows as OutboxEvent[]).map(summarizeEvent);
+        return c.json(
+          {
+            rows: sanitized,
+            total: result.total,
+            page: q.page,
+            perPage: q.perPage,
+          },
+          200,
+        );
+      },
+    )
+    .get("/outbox/stats", auth, requirePermission(OUTBOX_PERMISSIONS.outboxRead), async (c) => {
+      const stats = await deps.service.getStatistics();
+      return c.json(stats, 200);
+    })
+    .get(
+      "/outbox/count",
+      auth,
+      requirePermission(OUTBOX_PERMISSIONS.outboxRead),
+      validate("query", listQuery),
+      async (c) => {
+        const q = c.req.valid("query");
+        const where: Record<string, unknown> = {};
+        if (q.eventType) where.eventType = q.eventType;
+        if (q.status) where.status = q.status;
+        const count = await deps.service.count({
+          where: Object.keys(where).length > 0 ? where : undefined,
+        });
+        return c.json({ count }, 200);
+      },
+    )
+    .get(
+      "/outbox/:id",
+      auth,
+      requirePermission(OUTBOX_PERMISSIONS.outboxRead),
+      validate("param", idParam),
+      async (c) => {
+        const { id } = c.req.valid("param");
+        const event = (await deps.service.get(id)) as OutboxEvent | null;
+        if (!event) throw new NotFoundError("Outbox event not found");
+        return c.json(summarizeEvent(event), 200);
+      },
+    )
+    .post(
+      "/outbox/drain",
+      auth,
+      requirePermission(OUTBOX_PERMISSIONS.outboxDrain),
+      validate("json", drainBody),
+      async (c) => {
+        const body = c.req.valid("json");
+        const result = body.untilEmpty
+          ? await deps.drainer.runUntilEmpty({ batchSize: body.batchSize })
+          : await deps.drainer.runOnce({ batchSize: body.batchSize });
+        return c.json(result, 200);
+      },
+    )
+    .post(
+      "/outbox/recover",
+      auth,
+      requirePermission(OUTBOX_PERMISSIONS.outboxRecover),
+      validate("json", recoverBody),
+      async (c) => {
+        const body = c.req.valid("json");
+        const result = await deps.service.recoverStaleProcessing(body.staleThresholdMs);
+        return c.json(result, 200);
+      },
+    );
+}
+
+/**
+ * Build the outbox module as its own sub-app, ready to mount on the root with
+ * `root.route("/", buildOutboxApp(deps))`. Canonical wiring — see
+ * {@link buildAccountsApp} for the rationale. Routes are tagged under the
+ * `outbox` module in `/dev/routes` / `list_routes`.
+ */
+export function buildOutboxApp<TAccount extends AuthenticatedAccount = AuthenticatedAccount>(
+  deps: OutboxRoutesDeps<TAccount>,
+) {
+  return defineOutboxRoutes(createModuleApp("outbox"), deps);
+}
+
+/**
+ * Strip the heavy `payload` from list-view responses so admin UIs
+ * don't transfer megabytes of event bodies just to render a status
+ * dashboard. Single-event endpoint returns the full row including
+ * payload.
+ */
+function summarizeEvent(event: OutboxEvent) {
+  return {
+    id: event.id,
+    eventId: event.eventId,
+    eventType: event.eventType,
+    eventVersion: event.eventVersion,
+    aggregateType: event.aggregateType,
+    aggregateId: event.aggregateId,
+    ownerUserId: event.ownerUserId,
+    tenantId: event.tenantId,
+    correlationId: event.correlationId,
+    status: event.status,
+    publishAttempts: event.publishAttempts,
+    nextAttemptAt: event.nextAttemptAt,
+    publishedAt: event.publishedAt,
+    lastError: event.lastError,
+    occurredAt: event.occurredAt,
+    createdAt: event.createdAt,
+    updatedAt: event.updatedAt,
+    payload: event.payload,
+  };
+}

package/lib/modules/outbox/schema.ts

@@ -0,0 +1,207 @@
+import { baseFields } from "@sixthsummit/ship-api/app/db/baseFields";
+import { sql } from "drizzle-orm";
+import {
+  index,
+  integer,
+  jsonb,
+  pgEnum,
+  pgTable,
+  text,
+  timestamp,
+  uuid,
+  varchar,
+} from "drizzle-orm/pg-core";
+
+/**
+ * v4 transactional outbox table — ports v3's `OutboxEvent` TypeORM
+ * entity. Implements the outbox pattern: domain operations write
+ * events to this table inside the same transaction as the business
+ * data; a separate worker drains pending rows and publishes to
+ * downstream systems (queue, webhook, log, etc.) with at-least-once
+ * delivery and exponential backoff on failure.
+ *
+ * Key v4 differences from v3:
+ *
+ *   - `id` switches from `bigint identity` to `uuid` for consistency
+ *     with the rest of the v4 framework. FIFO ordering uses the
+ *     `(created_at, event_id)` index instead of monotonic bigint
+ *     incrementing.
+ *
+ *   - `status` becomes a Postgres `pgEnum` instead of a raw text
+ *     column. Type-checked at the SQL boundary; cheaper indexes than
+ *     text comparison.
+ *
+ *   - Partial indexes preserved for the hot drain queries — the
+ *     `pending` index covers only rows that haven't been published,
+ *     and the `processing` index covers only in-flight rows. Both
+ *     are tiny relative to the full table and stay fast as the
+ *     published-events table grows.
+ *
+ *   - Audit columns (`createdAt` / `updatedAt` / `deletedAt` /
+ *     `createdBy` / `updatedBy`) standardized via `baseFields`. v3
+ *     had createdAt + updatedAt only; v4 uniformity is worth the
+ *     extra (nullable) columns.
+ *
+ * The v3 `Job` entity + JobController + job-queue subsystem are
+ * intentionally NOT ported. v4's BullMQ machinery (`defineJob` +
+ * `JobRegistry` from alpha-2 step 12) is the canonical job substrate;
+ * porting v3's competing TypeORM-backed queue would create two
+ * conflicting source-of-truth queues. Migration guide: move each
+ * v3 Job processor to a `defineJob({ queue, name, processor })` call.
+ */
+
+export const outboxEventStatus = pgEnum("outbox_event_status", [
+  "pending",
+  "processing",
+  "published",
+  "failed",
+]);
+
+export const outboxEvents = pgTable(
+  "outbox_events",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+
+    /**
+     * External identifier for the event — the value downstream
+     * consumers see. Distinct from `id` to allow re-publishing the
+     * same logical event under a new row when a permanent failure
+     * gets manually resolved.
+     */
+    eventId: uuid("event_id").notNull().defaultRandom(),
+
+    /**
+     * Domain event type ("account.created", "post.published", ...).
+     * Matches the consumer's `EventType` discriminated union.
+     */
+    eventType: text("event_type").notNull(),
+
+    /** Schema version for the payload. Bump when the payload shape changes. */
+    eventVersion: integer("event_version").notNull().default(1),
+
+    /** When the domain operation occurred (may differ from `createdAt`). */
+    occurredAt: timestamp("occurred_at", { withTimezone: true }).notNull().default(sql`now()`),
+
+    /** Aggregate type (entity-class identifier) the event belongs to. */
+    aggregateType: text("aggregate_type"),
+
+    /** Aggregate id within `aggregateType`. UUID-shaped string for v4. */
+    aggregateId: uuid("aggregate_id"),
+
+    /** Owner of the aggregate (typically `accounts.id`). */
+    ownerUserId: uuid("owner_user_id"),
+
+    /**
+     * Multi-tenant scoping (A2-1: `uuid` to match `RequestContext.tenantId` and
+     * every other v4 id). Nullable — the outbox also carries system/global
+     * events with no tenant. No FK: the outbox module doesn't own a `tenants`
+     * table, and system events legitimately have a null tenant.
+     */
+    tenantId: uuid("tenant_id"),
+
+    /**
+     * Stable key for upstream-deduplication. Set by the producer when
+     * the same logical event might be enqueued twice (idempotency
+     * boundary).
+     */
+    dedupeKey: text("dedupe_key"),
+
+    /** Trace correlation id — flows through to downstream telemetry. */
+    correlationId: varchar("correlation_id", { length: 255 }),
+
+    /** Event payload. Consumer-shaped JSON. */
+    payload: jsonb("payload").$type<Record<string, unknown>>().notNull(),
+
+    /** Lifecycle state — see the `outboxEventStatus` enum. */
+    status: outboxEventStatus("status").notNull().default("pending"),
+
+    /** Number of publish attempts that have been made (incl. failed). */
+    publishAttempts: integer("publish_attempts").notNull().default(0),
+
+    /** When the next retry should fire. Null when not scheduled. */
+    nextAttemptAt: timestamp("next_attempt_at", { withTimezone: true }),
+
+    /** When the publish succeeded. Null until then. */
+    publishedAt: timestamp("published_at", { withTimezone: true }),
+
+    /** Last failure message (truncated to a reasonable length by callers). */
+    lastError: text("last_error"),
+
+    /** Maximum number of attempts before giving up and marking failed. */
+    maxRetries: integer("max_retries").notNull().default(10),
+
+    /** When the most recent attempt started. */
+    startedAt: timestamp("started_at", { withTimezone: true }),
+
+    ...baseFields,
+  },
+  (table) => [
+    // Hot drain query: rows pending or processing that haven't been
+    // published yet, ordered by next-attempt → created. Partial index
+    // stays small relative to the full table even after years of
+    // published events accumulate.
+    index("outbox_events_pending_ix")
+      .on(table.nextAttemptAt, table.createdAt)
+      .where(sql`status IN ('pending','processing') AND published_at IS NULL`),
+    index("outbox_events_type_ix").on(table.eventType, table.createdAt),
+    index("outbox_events_owner_ix").on(table.ownerUserId),
+    index("outbox_events_status_ix").on(table.status),
+    // Stale-processing recovery: only rows in processing state. Tiny
+    // index — most events don't get stuck in processing.
+    index("outbox_events_processing_ix")
+      .on(table.startedAt)
+      .where(sql`status = 'processing'`),
+    // Aggregate-scoped lookups (e.g., "all events for this account").
+    index("outbox_events_aggregate_ix").on(table.aggregateType, table.aggregateId),
+  ],
+);
+
+export type OutboxEvent = typeof outboxEvents.$inferSelect;
+export type NewOutboxEvent = typeof outboxEvents.$inferInsert;
+export type OutboxEventStatus = (typeof outboxEventStatus.enumValues)[number];
+
+// ─── Status helpers (pure functions) ──────────────────────────────────
+//
+// v3 had these as instance methods on the TypeORM entity class. v4
+// rows are plain objects; status logic moves to module-level pure
+// functions the service / drain worker calls on the row.
+
+/**
+ * True when a pending event is ready to publish: status is `pending`,
+ * no publishedAt set, and (if scheduled) the next-attempt time has
+ * passed. The drain query also filters by index — this helper is for
+ * service-layer assertions and tests.
+ */
+export function isReadyForPublish(
+  event: Pick<OutboxEvent, "status" | "publishedAt" | "nextAttemptAt">,
+  now: Date = new Date(),
+): boolean {
+  if (event.status !== "pending") return false;
+  if (event.publishedAt) return false;
+  if (event.nextAttemptAt && event.nextAttemptAt > now) return false;
+  return true;
+}
+
+export function hasExhaustedRetries(
+  event: Pick<OutboxEvent, "publishAttempts" | "maxRetries">,
+): boolean {
+  return event.publishAttempts >= event.maxRetries;
+}
+
+/**
+ * Compute the next-attempt time using exponential backoff with jitter.
+ * `baseMs * 2^(attempts - 1)` capped at `maxMs`. Used by the drain
+ * worker when a publish fails and the event is still under the retry
+ * budget.
+ */
+export function computeNextAttempt(
+  attempts: number,
+  baseMs: number = 1_000,
+  maxMs: number = 60 * 60 * 1_000,
+): Date {
+  const exponential = baseMs * 2 ** Math.max(0, attempts - 1);
+  const capped = Math.min(exponential, maxMs);
+  // ±20% jitter to avoid thundering-herd on retries.
+  const jittered = capped * (0.8 + Math.random() * 0.4);
+  return new Date(Date.now() + jittered);
+}

package/lib/modules/outbox/services/OutboxEventService.ts

@@ -0,0 +1,223 @@
+import { DrizzleEntityService } from "@sixthsummit/ship-api/app/services/DrizzleEntityService";
+// eslint-disable-next-line @typescript-eslint/no-restricted-imports -- the drainer needs row-level locking + atomic `sql` status transitions that QueryOptions can't express
+import { and, asc, eq, isNull, lte, or, sql } from "drizzle-orm";
+import {
+  computeNextAttempt,
+  type OutboxEvent,
+  type OutboxEventStatus,
+  outboxEvents,
+} from "../schema.js";
+
+/**
+ * v4 `OutboxEventService` — extends `DrizzleEntityService` for CRUD
+ * + the outbox-specific lifecycle transitions the drain worker needs.
+ *
+ * Surface inherited from the base:
+ *   - `get` / `getAll` / `list` / `count` / `create` / `update` /
+ *     `delete` with soft-delete + audit-column auto-stamping.
+ *
+ * Domain-specific methods added here:
+ *
+ *   - `findReadyToPublish(limit)` — paginated query of rows where
+ *     status='pending' AND publishedAt IS NULL AND
+ *     (nextAttemptAt IS NULL OR nextAttemptAt <= now). FIFO ordered
+ *     by `(createdAt, id)`. Driven by the drain worker.
+ *
+ *   - `claimForProcessing(ids[])` — atomic status transition from
+ *     'pending' to 'processing' for the listed ids, incrementing
+ *     `publishAttempts` and stamping `startedAt`. Returns only the
+ *     ids that actually transitioned (compete with concurrent drain
+ *     workers safely).
+ *
+ *   - `markPublished(id)` — terminal success transition.
+ *
+ *   - `markFailed(id, error)` — terminal failure (no more retries).
+ *     Used by the drain worker when `hasExhaustedRetries()` is true
+ *     after a failure.
+ *
+ *   - `markForRetry(id, error, attempts)` — non-terminal failure;
+ *     reverts status to 'pending', stamps `lastError`, and schedules
+ *     `nextAttemptAt` via the exponential-backoff helper.
+ *
+ *   - `recoverStaleProcessing(staleThresholdMs)` — admin tooling:
+ *     finds rows stuck in 'processing' for longer than the threshold
+ *     (worker died mid-publish) and resets them to 'pending' so the
+ *     next drain picks them up.
+ *
+ * The drain orchestration logic itself (loop, batching, error
+ * handling, observability) lands in a separate `OutboxDrainer` class
+ * in a follow-up commit; the service only owns DB transitions.
+ */
+export class OutboxEventService extends DrizzleEntityService<
+  typeof outboxEvents,
+  { outboxEvents: typeof outboxEvents }
+> {
+  protected getTable() {
+    return outboxEvents;
+  }
+
+  protected override getDefaultSearchFields(): readonly string[] {
+    return ["eventType", "correlationId"];
+  }
+
+  /**
+   * Read up to `limit` rows that are ready to publish, ordered FIFO.
+   * The pending partial index covers this query.
+   */
+  async findReadyToPublish(limit: number = 100, now: Date = new Date()): Promise<OutboxEvent[]> {
+    const rows = await this.db
+      .select()
+      .from(outboxEvents)
+      .where(
+        and(
+          eq(outboxEvents.status, "pending"),
+          isNull(outboxEvents.publishedAt),
+          or(isNull(outboxEvents.nextAttemptAt), lte(outboxEvents.nextAttemptAt, now)),
+        ),
+      )
+      .orderBy(asc(outboxEvents.createdAt), asc(outboxEvents.id))
+      .limit(limit);
+    return rows as OutboxEvent[];
+  }
+
+  /**
+   * Atomically transition the listed rows from 'pending' to
+   * 'processing'. Increments publishAttempts and stamps startedAt.
+   * Returns only the ids that actually transitioned — concurrent
+   * drain workers compete safely; whichever worker's UPDATE wins gets
+   * the row.
+   */
+  async claimForProcessing(ids: readonly string[]): Promise<string[]> {
+    if (ids.length === 0) return [];
+    const now = new Date();
+    const rows = await this.db
+      .update(outboxEvents)
+      .set({
+        status: "processing",
+        startedAt: now,
+        publishAttempts: sql`${outboxEvents.publishAttempts} + 1`,
+        updatedAt: now,
+      } as never)
+      .where(
+        and(
+          // Inline as one IN clause to avoid one update-per-id round trip.
+          sql`${outboxEvents.id} = ANY(ARRAY[${sql.join(
+            ids.map((id) => sql`${id}`),
+            sql`, `,
+          )}]::uuid[])`,
+          eq(outboxEvents.status, "pending"),
+        ),
+      )
+      .returning({ id: outboxEvents.id as never });
+    return (rows as Array<{ id: string }>).map((r) => r.id);
+  }
+
+  async markPublished(id: string): Promise<OutboxEvent | null> {
+    const now = new Date();
+    const [row] = await this.db
+      .update(outboxEvents)
+      .set({
+        status: "published",
+        publishedAt: now,
+        lastError: null,
+        nextAttemptAt: null,
+        updatedAt: now,
+      } as never)
+      .where(eq(outboxEvents.id, id))
+      .returning();
+    return (row as OutboxEvent | undefined) ?? null;
+  }
+
+  async markFailed(id: string, error: string): Promise<OutboxEvent | null> {
+    const now = new Date();
+    const [row] = await this.db
+      .update(outboxEvents)
+      .set({
+        status: "failed",
+        lastError: truncateError(error),
+        nextAttemptAt: null,
+        updatedAt: now,
+      } as never)
+      .where(eq(outboxEvents.id, id))
+      .returning();
+    return (row as OutboxEvent | undefined) ?? null;
+  }
+
+  /**
+   * Non-terminal failure: schedule a retry with exponential backoff
+   * and revert status to 'pending' so the next drain picks it up.
+   * Caller owns the attempt-counting logic — typically calls
+   * `markForRetry` only when `hasExhaustedRetries(event)` is false.
+   */
+  async markForRetry(id: string, error: string, attempts: number): Promise<OutboxEvent | null> {
+    const now = new Date();
+    const nextAt = computeNextAttempt(attempts);
+    const [row] = await this.db
+      .update(outboxEvents)
+      .set({
+        status: "pending",
+        lastError: truncateError(error),
+        nextAttemptAt: nextAt,
+        publishedAt: null,
+        updatedAt: now,
+      } as never)
+      .where(eq(outboxEvents.id, id))
+      .returning();
+    return (row as OutboxEvent | undefined) ?? null;
+  }
+
+  /**
+   * Admin tooling — find rows stuck in 'processing' beyond the
+   * threshold and reset them to 'pending' so the next drain picks
+   * them up. Returns the count reset (callers report it).
+   */
+  async recoverStaleProcessing(
+    staleThresholdMs: number = 30 * 60 * 1_000,
+  ): Promise<{ recovered: number }> {
+    const cutoff = new Date(Date.now() - staleThresholdMs);
+    const now = new Date();
+    const rows = await this.db
+      .update(outboxEvents)
+      .set({
+        status: "pending",
+        startedAt: null,
+        nextAttemptAt: now,
+        updatedAt: now,
+      } as never)
+      .where(and(eq(outboxEvents.status, "processing"), lte(outboxEvents.startedAt, cutoff)))
+      .returning({ id: outboxEvents.id as never });
+    return { recovered: (rows as Array<{ id: string }>).length };
+  }
+
+  /**
+   * Aggregate counts by status — used by the stats endpoint and by
+   * monitoring dashboards. Returns 0 for missing buckets so the
+   * shape stays stable.
+   */
+  async getStatistics(): Promise<Record<OutboxEventStatus, number>> {
+    const rows = (await this.db
+      .select({
+        status: outboxEvents.status,
+        count: sql<number>`count(*)::int`,
+      })
+      .from(outboxEvents)
+      .groupBy(outboxEvents.status)) as Array<{
+      status: OutboxEventStatus;
+      count: number;
+    }>;
+    const stats: Record<OutboxEventStatus, number> = {
+      pending: 0,
+      processing: 0,
+      published: 0,
+      failed: 0,
+    };
+    for (const row of rows) stats[row.status] = row.count;
+    return stats;
+  }
+}
+
+const MAX_ERROR_LENGTH = 4096;
+function truncateError(message: string): string {
+  if (message.length <= MAX_ERROR_LENGTH) return message;
+  return message.slice(0, MAX_ERROR_LENGTH - 3) + "...";
+}

package/lib/observability/logger.d.ts

@@ -0,0 +1,30 @@
+import pino, { type Logger } from "pino";
+export { getRequestContext, type RequestContext, runWithRequestContext, setRequestContextField, } from "../app/context/RequestContext.js";
+export interface CreateLoggerOptions {
+    /** Override log level. Defaults to `LOG_LEVEL` env then `"info"`. */
+    level?: pino.Level;
+    /**
+     * Custom destination (anything pino accepts: a stream, a file path via
+     * `pino.destination`, a sonic-boom instance, or any object with a `write`
+     * method). Useful for tests.
+     */
+    destination?: pino.DestinationStream;
+    /**
+     * Force pino-pretty mode regardless of env. Set `false` to force ND-JSON
+     * in dev (e.g., when running under a log-aggregating supervisor).
+     */
+    pretty?: boolean;
+    /**
+     * Extra redaction paths to *add* to the framework defaults. Use this for
+     * domain-specific secret keys (e.g., third-party webhook signatures).
+     */
+    extraRedactPaths?: readonly string[];
+}
+export declare function createLogger(opts?: CreateLoggerOptions): Logger;
+/**
+ * Default framework-wide logger. Most callsites should import this and either
+ * use it directly or call `logger.child({ module: "<name>" })` for a scoped
+ * sub-logger.
+ */
+export declare const logger: Logger;
+//# sourceMappingURL=logger.d.ts.map

package/lib/observability/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/observability/logger.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,EAAE,EAAE,KAAK,MAAM,EAAsB,MAAM,MAAM,CAAC;AAM7D,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,kCAAkC,CAAC;AAmD1C,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC;IACnB;;;;OAIG;IACH,WAAW,CAAC,EAAE,IAAI,CAAC,iBAAiB,CAAC;IACrC;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AA0BD,wBAAgB,YAAY,CAAC,IAAI,GAAE,mBAAwB,GAAG,MAAM,CA0BnE;AAED;;;;GAIG;AACH,eAAO,MAAM,MAAM,EAAE,MAAuB,CAAC"}