@venturekit-pro/audit 0.0.0-dev.20260602192622

package/dist/query.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Read helpers over the `audit_events` table.
+ *
+ * Pure audit — no domain aggregation. The package can:
+ *   - `listEvents()`                 — paginated newest-first list.
+ *   - `countEvents()`                — count matching events, with an
+ *                                       optional per-prefix breakdown.
+ *   - `monthlyEventCounts()`          — events per month, optionally
+ *                                       per-prefix split. Useful for
+ *                                       "activity volume" dashboards.
+ *
+ * Anything more specific (cost-in-USD, payment totals, token usage,
+ * etc.) belongs in the package that owns that concern. The audit
+ * package only references those via `correlation_id` / `target_id`.
+ */
+import type { AuditEvent, EventCount, Querier } from './types.js';
+export interface ListEventsArgs {
+    tenantId: string;
+    /** Filter by `kind` (exact match). */
+    kind?: string;
+    /** Filter by `kind` prefix (matches every event whose kind starts with the value). */
+    kindPrefix?: string;
+    /** Filter by target row. Pass both `targetType` AND `targetId`. */
+    targetType?: string;
+    targetId?: string;
+    /** Filter by `correlationId`. */
+    correlationId?: string;
+    /** Filter by `actorType`. */
+    actorType?: string;
+    /** Filter by `status`. */
+    status?: string;
+    /** Page size; default 50, capped at 500. */
+    limit?: number;
+    /**
+     * `id` boundary; rows with `id < beforeId` (strictly older when
+     * sorted by created_at DESC) are returned. Stable cursor; works
+     * even when many rows share the same `created_at`.
+     */
+    beforeId?: string;
+}
+/**
+ * Paginated event list, newest first.
+ */
+export declare function listEvents(querier: Querier, args: ListEventsArgs): Promise<AuditEvent[]>;
+export interface CountEventsArgs {
+    tenantId: string;
+    kind?: string;
+    kindPrefix?: string;
+    targetType?: string;
+    targetId?: string;
+    correlationId?: string;
+    actorType?: string;
+    status?: string;
+    /** Inclusive lower bound on `created_at`. */
+    since?: Date;
+    /** Exclusive upper bound on `created_at`. */
+    until?: Date;
+    /**
+     * Optional kind-prefixes to split the count by. Each prefix is
+     * matched as `kind LIKE '<prefix>%'`. Empty / omitted = no split,
+     * only `count`.
+     */
+    byKindPrefix?: string[];
+}
+/**
+ * Count events matching the filter, optionally split by kind-prefix.
+ *
+ * The package's only aggregation surface — domain-specific rollups
+ * (cost, payment totals, token usage) live in their own packages.
+ */
+export declare function countEvents(querier: Querier, args: CountEventsArgs): Promise<EventCount>;
+export interface MonthlyEventCountsArgs {
+    tenantId: string;
+    /**
+     * Number of trailing months to return (current month + the last
+     * `monthCount - 1`). Default 12, capped at 36.
+     */
+    monthCount?: number;
+    /** Optional kind-prefixes to split each month's count by. */
+    byKindPrefix?: string[];
+}
+export interface MonthlyCountBucket extends EventCount {
+    /** ISO date (`YYYY-MM-01`) for the start of the bucket's month. */
+    month: string;
+}
+/**
+ * Events per trailing month — empty months emit a zero row so the
+ * consumer can render a flat chart without gap handling.
+ */
+export declare function monthlyEventCounts(querier: Querier, args: MonthlyEventCountsArgs): Promise<MonthlyCountBucket[]>;
+//# sourceMappingURL=query.d.ts.map

package/dist/query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAoElE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,cAAc,GACnB,OAAO,CAAC,UAAU,EAAE,CAAC,CAiBvB;AAID,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,IAAI,CAAC;IACb,6CAA6C;IAC7C,KAAK,CAAC,EAAE,IAAI,CAAC;IACb;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,eAAe,GACpB,OAAO,CAAC,UAAU,CAAC,CAoBrB;AAID,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,kBAAmB,SAAQ,UAAU;IACpD,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAyB/B"}

package/dist/query.js

@@ -0,0 +1,169 @@
+/**
+ * Read helpers over the `audit_events` table.
+ *
+ * Pure audit — no domain aggregation. The package can:
+ *   - `listEvents()`                 — paginated newest-first list.
+ *   - `countEvents()`                — count matching events, with an
+ *                                       optional per-prefix breakdown.
+ *   - `monthlyEventCounts()`          — events per month, optionally
+ *                                       per-prefix split. Useful for
+ *                                       "activity volume" dashboards.
+ *
+ * Anything more specific (cost-in-USD, payment totals, token usage,
+ * etc.) belongs in the package that owns that concern. The audit
+ * package only references those via `correlation_id` / `target_id`.
+ */
+// ─── Internal helpers ──────────────────────────────────────────────────
+/**
+ * Validate a prefix list: non-empty strings, deduplicated, no SQL
+ * pattern characters. We embed prefixes as SQL identifiers (not
+ * parameters) because `FILTER (WHERE kind LIKE $N)` would emit a
+ * dynamic column per row otherwise, which we don't want.
+ */
+function normalizePrefixes(prefixes) {
+    if (!prefixes || prefixes.length === 0)
+        return [];
+    const out = new Set();
+    for (const raw of prefixes) {
+        if (typeof raw !== 'string' || raw.length === 0)
+            continue;
+        // Reject LIKE-significant characters so a caller can't smuggle
+        // wildcard semantics into the rollup. A trailing dot is the
+        // expected pattern (`'order.'` matches `'order.refunded'` etc).
+        if (/[%_\\']/.test(raw)) {
+            throw new Error(`[audit/query] Invalid prefix '${raw}' — must not contain %, _, \\ or '`);
+        }
+        out.add(raw);
+    }
+    return Array.from(out);
+}
+function toNumber(v) {
+    if (v === null || v === undefined)
+        return 0;
+    const n = typeof v === 'number' ? v : Number(v);
+    return Number.isFinite(n) ? n : 0;
+}
+function rowToCount(row, prefixes) {
+    const byKindPrefix = {};
+    prefixes.forEach((p, i) => {
+        byKindPrefix[p] = Math.trunc(toNumber(row?.[`split_${i}`]));
+    });
+    return {
+        count: Math.trunc(toNumber(row?.count)),
+        byKindPrefix,
+    };
+}
+/**
+ * Build the SELECT clause for a count query, adding one
+ * `COUNT(...) FILTER (WHERE kind LIKE 'prefix%')` column per
+ * requested prefix.
+ */
+function buildCountSelect(prefixes, rowAlias = '') {
+    const prefix = rowAlias ? `${rowAlias}.` : '';
+    const baseCols = `COUNT(${prefix}id) AS "count"`;
+    if (prefixes.length === 0)
+        return baseCols;
+    const splitCols = prefixes.map((p, i) => `,\n  COUNT(${prefix}id) FILTER (WHERE ${prefix}kind LIKE '${p}%') AS "split_${i}"`);
+    return baseCols + splitCols.join('');
+}
+/**
+ * Paginated event list, newest first.
+ */
+export async function listEvents(querier, args) {
+    const { conditions, params } = buildEventFilter(args);
+    const limit = Math.min(Math.max(args.limit ?? 50, 1), 500);
+    if (args.beforeId !== undefined) {
+        params.push(args.beforeId);
+        conditions.push(`id < $${params.length}`);
+    }
+    params.push(limit);
+    return querier(`SELECT * FROM audit_events
+       WHERE ${conditions.join(' AND ')}
+       ORDER BY created_at DESC, id DESC
+       LIMIT $${params.length}`, params);
+}
+/**
+ * Count events matching the filter, optionally split by kind-prefix.
+ *
+ * The package's only aggregation surface — domain-specific rollups
+ * (cost, payment totals, token usage) live in their own packages.
+ */
+export async function countEvents(querier, args) {
+    const { conditions, params } = buildEventFilter(args);
+    if (args.since) {
+        params.push(args.since);
+        conditions.push(`created_at >= $${params.length}`);
+    }
+    if (args.until) {
+        params.push(args.until);
+        conditions.push(`created_at < $${params.length}`);
+    }
+    const prefixes = normalizePrefixes(args.byKindPrefix);
+    const rows = await querier(`SELECT ${buildCountSelect(prefixes)}
+       FROM audit_events
+      WHERE ${conditions.join(' AND ')}`, params);
+    return rowToCount(rows[0], prefixes);
+}
+/**
+ * Events per trailing month — empty months emit a zero row so the
+ * consumer can render a flat chart without gap handling.
+ */
+export async function monthlyEventCounts(querier, args) {
+    const monthCount = Math.max(1, Math.min(args.monthCount ?? 12, 36));
+    const prefixes = normalizePrefixes(args.byKindPrefix);
+    const rows = await querier(`WITH months AS (
+       SELECT generate_series(
+         date_trunc('month', now()) - (($2::int - 1) * interval '1 month'),
+         date_trunc('month', now()),
+         interval '1 month'
+       ) AS month_start
+     )
+     SELECT
+       to_char(months.month_start, 'YYYY-MM-DD') AS "month",
+       ${buildCountSelect(prefixes, 'a')}
+     FROM months
+     LEFT JOIN audit_events a
+       ON  a.tenant_id  = $1
+       AND a.created_at >= months.month_start
+       AND a.created_at <  months.month_start + interval '1 month'
+     GROUP BY months.month_start
+     ORDER BY months.month_start ASC`, [args.tenantId, monthCount]);
+    return rows.map((r) => ({ month: r.month, ...rowToCount(r, prefixes) }));
+}
+function buildEventFilter(args) {
+    const conditions = ['tenant_id = $1'];
+    const params = [args.tenantId];
+    if (args.kind !== undefined) {
+        params.push(args.kind);
+        conditions.push(`kind = $${params.length}`);
+    }
+    if (args.kindPrefix !== undefined) {
+        if (/[%_\\']/.test(args.kindPrefix)) {
+            throw new Error(`[audit/query] Invalid kindPrefix '${args.kindPrefix}' — must not contain %, _, \\ or '`);
+        }
+        params.push(`${args.kindPrefix}%`);
+        conditions.push(`kind LIKE $${params.length}`);
+    }
+    if (args.targetType !== undefined) {
+        params.push(args.targetType);
+        conditions.push(`target_type = $${params.length}`);
+    }
+    if (args.targetId !== undefined) {
+        params.push(args.targetId);
+        conditions.push(`target_id = $${params.length}`);
+    }
+    if (args.correlationId !== undefined) {
+        params.push(args.correlationId);
+        conditions.push(`correlation_id = $${params.length}`);
+    }
+    if (args.actorType !== undefined) {
+        params.push(args.actorType);
+        conditions.push(`actor_type = $${params.length}`);
+    }
+    if (args.status !== undefined) {
+        params.push(args.status);
+        conditions.push(`status = $${params.length}`);
+    }
+    return { conditions, params };
+}
+//# sourceMappingURL=query.js.map

package/dist/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../src/query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,0EAA0E;AAE1E;;;;;GAKG;AACH,SAAS,iBAAiB,CAAC,QAA8B;IACvD,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAClD,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAC1D,+DAA+D;QAC/D,4DAA4D;QAC5D,gEAAgE;QAChE,IAAI,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CACb,iCAAiC,GAAG,oCAAoC,CACzE,CAAC;QACJ,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACf,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED,SAAS,QAAQ,CAAC,CAAqC;IACrD,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IAC5C,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAChD,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAOD,SAAS,UAAU,CAAC,GAA4B,EAAE,QAAkB;IAClE,MAAM,YAAY,GAA2B,EAAE,CAAC;IAChD,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACxB,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC9D,CAAC,CAAC,CAAC;IACH,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACvC,YAAY;KACb,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,gBAAgB,CAAC,QAAkB,EAAE,QAAQ,GAAG,EAAE;IACzD,MAAM,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9C,MAAM,QAAQ,GAAG,SAAS,MAAM,gBAAgB,CAAC;IACjD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IAC3C,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAC5B,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,cAAc,MAAM,qBAAqB,MAAM,cAAc,CAAC,iBAAiB,CAAC,GAAG,CACtF,CAAC;IACF,OAAO,QAAQ,GAAG,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACvC,CAAC;AA6BD;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,OAAgB,EAChB,IAAoB;IAEpB,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAEtD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC3D,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC3B,UAAU,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAEnB,OAAO,OAAO,CACZ;eACW,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;;gBAEvB,MAAM,CAAC,MAAM,EAAE,EAC3B,MAAM,CACP,CAAC;AACJ,CAAC;AAyBD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAgB,EAChB,IAAqB;IAErB,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAEtD,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,UAAU,CAAC,IAAI,CAAC,kBAAkB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,UAAU,CAAC,IAAI,CAAC,iBAAiB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,MAAM,QAAQ,GAAG,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,MAAM,OAAO,CACxB,UAAU,gBAAgB,CAAC,QAAQ,CAAC;;cAE1B,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,EACpC,MAAM,CACP,CAAC;IACF,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;AACvC,CAAC;AAoBD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAgB,EAChB,IAA4B;IAE5B,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IACpE,MAAM,QAAQ,GAAG,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAEtD,MAAM,IAAI,GAAG,MAAM,OAAO,CACxB;;;;;;;;;SASK,gBAAgB,CAAC,QAAQ,EAAE,GAAG,CAAC;;;;;;;qCAOH,EACjC,CAAC,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAC5B,CAAC;IACF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,GAAG,UAAU,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;AAC3E,CAAC;AAeD,SAAS,gBAAgB,CAAC,IAAuB;IAI/C,MAAM,UAAU,GAAa,CAAC,gBAAgB,CAAC,CAAC;IAChD,MAAM,MAAM,GAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAE1C,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,UAAU,CAAC,IAAI,CAAC,WAAW,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QAClC,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CACb,qCAAqC,IAAI,CAAC,UAAU,oCAAoC,CACzF,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,UAAU,GAAG,CAAC,CAAC;QACnC,UAAU,CAAC,IAAI,CAAC,cAAc,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,KAAK,SAAS,EAAE,CAAC;QAClC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC7B,UAAU,CAAC,IAAI,CAAC,kBAAkB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QAChC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC3B,UAAU,CAAC,IAAI,CAAC,gBAAgB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACnD,CAAC;IACD,IAAI,IAAI,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACrC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAChC,UAAU,CAAC,IAAI,CAAC,qBAAqB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACxD,CAAC;IACD,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC5B,UAAU,CAAC,IAAI,CAAC,iBAAiB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzB,UAAU,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;AAChC,CAAC"}

package/dist/record.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `record()` — write one audit event.
+ *
+ * Idempotent when `idempotencyKey` is set: the partial unique index
+ * `audit_events_idempotency_unique` rejects duplicates with Postgres
+ * error code `23505`; we catch that and return the original row
+ * instead of letting the caller see a transactional error.
+ *
+ * Append-only by contract: there is no `update()` / `delete()`
+ * exported from this package. Finalizing a long-running event ("step
+ * succeeded after running for 2 min") writes a NEW row referencing
+ * the same `correlationId`, not an UPDATE on the original.
+ */
+import type { AuditEvent, AuditEventInput, Querier } from './types.js';
+/**
+ * Insert one audit event. Returns the persisted row.
+ *
+ * @example
+ * ```ts
+ * await record(query, {
+ *   tenantId,
+ *   actor: { type: 'user', id: cognitoSub },
+ *   kind: 'blog.save',
+ *   target: { type: 'blog_post', id: post.id, slug: post.slug },
+ *   payload: { locale: 'fr', versionNumber: 4 },
+ * });
+ * ```
+ */
+export declare function record(querier: Querier, input: AuditEventInput): Promise<AuditEvent>;
+//# sourceMappingURL=record.d.ts.map

package/dist/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../src/record.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,OAAO,EACR,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;GAaG;AACH,wBAAsB,MAAM,CAC1B,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,UAAU,CAAC,CAoErB"}

package/dist/record.js

@@ -0,0 +1,136 @@
+/**
+ * `record()` — write one audit event.
+ *
+ * Idempotent when `idempotencyKey` is set: the partial unique index
+ * `audit_events_idempotency_unique` rejects duplicates with Postgres
+ * error code `23505`; we catch that and return the original row
+ * instead of letting the caller see a transactional error.
+ *
+ * Append-only by contract: there is no `update()` / `delete()`
+ * exported from this package. Finalizing a long-running event ("step
+ * succeeded after running for 2 min") writes a NEW row referencing
+ * the same `correlationId`, not an UPDATE on the original.
+ */
+/**
+ * Insert one audit event. Returns the persisted row.
+ *
+ * @example
+ * ```ts
+ * await record(query, {
+ *   tenantId,
+ *   actor: { type: 'user', id: cognitoSub },
+ *   kind: 'blog.save',
+ *   target: { type: 'blog_post', id: post.id, slug: post.slug },
+ *   payload: { locale: 'fr', versionNumber: 4 },
+ * });
+ * ```
+ */
+export async function record(querier, input) {
+    // Payload is rendered as JSON by the driver. We freeze the
+    // top-level shape to a plain object here so a caller-side
+    // `Map`/`Set`/instance leaks as `{}` rather than throwing inside
+    // node-postgres.
+    const payload = sanitizePayload(input.payload);
+    const sql = `
+    INSERT INTO audit_events (
+      tenant_id,
+      actor_type,
+      actor_id,
+      kind,
+      target_type,
+      target_id,
+      target_slug,
+      status,
+      payload,
+      correlation_id,
+      idempotency_key,
+      error_message
+    )
+    VALUES (
+      $1, $2, $3, $4, $5, $6, $7, $8, $9::jsonb, $10, $11, $12
+    )
+    RETURNING *
+  `;
+    const params = [
+        input.tenantId,
+        input.actor.type,
+        input.actor.id ?? null,
+        input.kind,
+        input.target?.type ?? null,
+        input.target?.id ?? null,
+        input.target?.slug ?? null,
+        input.status ?? 'succeeded',
+        JSON.stringify(payload),
+        input.correlationId ?? null,
+        input.idempotencyKey ?? null,
+        input.errorMessage ?? null,
+    ];
+    try {
+        const rows = await querier(sql, params);
+        const row = rows[0];
+        if (!row) {
+            // pg always returns the inserted row from RETURNING; this
+            // branch is defensive against custom queriers that strip it.
+            throw new Error('[audit/record] INSERT ... RETURNING returned no rows');
+        }
+        return row;
+    }
+    catch (err) {
+        if (input.idempotencyKey &&
+            isUniqueViolation(err) &&
+            isIdempotencyConstraint(err)) {
+            // Retried call with the same idempotency key — return the
+            // pre-existing row so the caller sees a stable outcome.
+            const existing = await querier(`SELECT * FROM audit_events WHERE idempotency_key = $1 LIMIT 1`, [input.idempotencyKey]);
+            if (existing[0])
+                return existing[0];
+        }
+        throw err;
+    }
+}
+// ─── Helpers ────────────────────────────────────────────────────────
+function sanitizePayload(payload) {
+    if (payload === undefined || payload === null)
+        return {};
+    if (typeof payload !== 'object') {
+        return { value: payload };
+    }
+    // Best-effort: a plain object passes through; everything else
+    // (Map / Set / class instance) loses its identity but at least
+    // survives JSON.stringify.
+    try {
+        return JSON.parse(JSON.stringify(payload));
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Pg unique-violation SQLSTATE. Driver-agnostic check — both
+ * `node-postgres` and Aurora-DSQL surface this under `err.code`.
+ */
+function isUniqueViolation(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const code = err.code;
+    return code === '23505';
+}
+/**
+ * Distinguish "duplicate idempotency_key" (intentional, return existing
+ * row) from a true 23505 on some other index — would mean a schema
+ * bug we shouldn't swallow. We check the constraint name via pg's
+ * error metadata when available; fall back to the SQL detail string
+ * if not.
+ */
+function isIdempotencyConstraint(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    if (e.constraint === 'audit_events_idempotency_unique')
+        return true;
+    if (typeof e.detail === 'string' && e.detail.includes('(idempotency_key)')) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=record.js.map

package/dist/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../src/record.ts"],"names":[],"mappings":"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"}

package/dist/retention.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Retention pruning — destructive, runs as the privileged migration
+ * role (NOT the application role, which has DELETE revoked).
+ *
+ * Apps typically wire `pruneAuditEvents()` into a daily cron with a
+ * conservative `olderThanDays` (180+) and call `archiveAuditEvents()`
+ * BEFORE pruning so cold history lands in S3 / Glacier / whatever
+ * the compliance team uses.
+ *
+ * **Default retention is open-ended** — this package never auto-prunes.
+ * The caller picks a policy.
+ */
+import type { Querier } from './types.js';
+export interface PruneOptions {
+    /** Delete events older than this many days. */
+    olderThanDays: number;
+    /** Apply only within a specific tenant; null = all tenants. */
+    tenantId?: string | null;
+    /**
+     * Limit each invocation. Defaults to 1000 — high enough to drain
+     * a steady backlog within a few cron ticks without holding a long
+     * transaction.
+     */
+    batchSize?: number;
+}
+/**
+ * DELETE events older than the threshold. Returns the number of rows
+ * pruned.
+ *
+ * The caller's database role MUST have DELETE privileges on
+ * `audit_events`. The application role typically does NOT (that's the
+ * point of the migration's `REVOKE`).
+ */
+export declare function pruneAuditEvents(querier: Querier, options: PruneOptions): Promise<number>;
+/**
+ * Stub for archival — returns the rows that WOULD be pruned, without
+ * deleting. Apps stream this to S3 / Glacier / SIEM before calling
+ * `pruneAuditEvents()`.
+ *
+ * Pure-SQL SELECT; works as the application role (no DELETE needed).
+ */
+export declare function previewPrune(querier: Querier, options: PruneOptions): Promise<Array<{
+    id: string;
+    createdAt: string;
+    tenantId: string | null;
+    kind: string;
+}>>;
+//# sourceMappingURL=retention.d.ts.map

package/dist/retention.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.d.ts","sourceRoot":"","sources":["../src/retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,MAAM,CAAC,CA6BjB;AAED;;;;;;GAMG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,YAAY,GACpB,OAAO,CAAC,KAAK,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAoB1F"}

package/dist/retention.js

@@ -0,0 +1,71 @@
+/**
+ * Retention pruning — destructive, runs as the privileged migration
+ * role (NOT the application role, which has DELETE revoked).
+ *
+ * Apps typically wire `pruneAuditEvents()` into a daily cron with a
+ * conservative `olderThanDays` (180+) and call `archiveAuditEvents()`
+ * BEFORE pruning so cold history lands in S3 / Glacier / whatever
+ * the compliance team uses.
+ *
+ * **Default retention is open-ended** — this package never auto-prunes.
+ * The caller picks a policy.
+ */
+/**
+ * DELETE events older than the threshold. Returns the number of rows
+ * pruned.
+ *
+ * The caller's database role MUST have DELETE privileges on
+ * `audit_events`. The application role typically does NOT (that's the
+ * point of the migration's `REVOKE`).
+ */
+export async function pruneAuditEvents(querier, options) {
+    const days = Math.max(1, Math.floor(options.olderThanDays));
+    const batchSize = Math.max(1, Math.min(options.batchSize ?? 1000, 100_000));
+    const conditions = [`created_at < now() - ($1::int * interval '1 day')`];
+    const params = [days];
+    if (options.tenantId !== undefined && options.tenantId !== null) {
+        params.push(options.tenantId);
+        conditions.push(`tenant_id = $${params.length}`);
+    }
+    params.push(batchSize);
+    // DELETE ... WHERE id IN (SELECT … LIMIT) so a runaway prune
+    // doesn't blow out a single transaction on a giant table.
+    const sql = `
+    WITH victims AS (
+      SELECT id FROM audit_events
+       WHERE ${conditions.join(' AND ')}
+       ORDER BY created_at ASC
+       LIMIT $${params.length}
+    )
+    DELETE FROM audit_events
+     USING victims
+     WHERE audit_events.id = victims.id
+     RETURNING audit_events.id
+  `;
+    const rows = await querier(sql, params);
+    return rows.length;
+}
+/**
+ * Stub for archival — returns the rows that WOULD be pruned, without
+ * deleting. Apps stream this to S3 / Glacier / SIEM before calling
+ * `pruneAuditEvents()`.
+ *
+ * Pure-SQL SELECT; works as the application role (no DELETE needed).
+ */
+export async function previewPrune(querier, options) {
+    const days = Math.max(1, Math.floor(options.olderThanDays));
+    const batchSize = Math.max(1, Math.min(options.batchSize ?? 1000, 100_000));
+    const conditions = [`created_at < now() - ($1::int * interval '1 day')`];
+    const params = [days];
+    if (options.tenantId !== undefined && options.tenantId !== null) {
+        params.push(options.tenantId);
+        conditions.push(`tenant_id = $${params.length}`);
+    }
+    params.push(batchSize);
+    return querier(`SELECT id, created_at AS "createdAt", tenant_id AS "tenantId", kind
+       FROM audit_events
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY created_at ASC
+      LIMIT $${params.length}`, params);
+}
+//# sourceMappingURL=retention.js.map

package/dist/retention.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retention.js","sourceRoot":"","sources":["../src/retention.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAiBH;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAgB,EAChB,OAAqB;IAErB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;IAC5D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IAE5E,MAAM,UAAU,GAAa,CAAC,mDAAmD,CAAC,CAAC;IACnF,MAAM,MAAM,GAAc,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QAChE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC9B,UAAU,CAAC,IAAI,CAAC,gBAAgB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACnD,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAEvB,6DAA6D;IAC7D,0DAA0D;IAC1D,MAAM,GAAG,GAAG;;;eAGC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;;gBAEvB,MAAM,CAAC,MAAM;;;;;;GAM1B,CAAC;IAEF,MAAM,IAAI,GAAG,MAAM,OAAO,CAAwB,GAAG,EAAE,MAAM,CAAC,CAAC;IAC/D,OAAO,IAAI,CAAC,MAAM,CAAC;AACrB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,OAAgB,EAChB,OAAqB;IAErB,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC;IAC5D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IAE5E,MAAM,UAAU,GAAa,CAAC,mDAAmD,CAAC,CAAC;IACnF,MAAM,MAAM,GAAc,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QAChE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC9B,UAAU,CAAC,IAAI,CAAC,gBAAgB,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IACnD,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAEvB,OAAO,OAAO,CACZ;;cAEU,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;;eAEvB,MAAM,CAAC,MAAM,EAAE,EAC1B,MAAM,CACP,CAAC;AACJ,CAAC"}