@flytedesk/app-kit 0.0.1 → 0.1.1

package/dist/trace/client.js

@@ -0,0 +1,21 @@
+/**
+ * createTraceClient(prisma) — bundles the query helpers and captureError into one
+ * object bound to the consumer's PrismaClient (or any TracePrismaClient-shaped
+ * object), so call sites don't have to thread `prisma` through every call.
+ */
+import { captureError } from "./errors.js";
+import { getAuditHistoryForModel, getRecentApiCallsForRoute, getTraceChainForRoot, insertApiCallLog, insertModelAudit, insertTraceLink, insertTraceNode, setTraceNodeRoot, } from "./queries.js";
+export function createTraceClient(prisma) {
+    return {
+        insertTraceNode: (input) => insertTraceNode(prisma, input),
+        setTraceNodeRoot: (id, rootId) => setTraceNodeRoot(prisma, id, rootId),
+        getTraceChainForRoot: (rootId) => getTraceChainForRoot(prisma, rootId),
+        insertModelAudit: (input) => insertModelAudit(prisma, input),
+        getAuditHistoryForModel: (modelType, modelId, limit) => getAuditHistoryForModel(prisma, modelType, modelId, limit),
+        insertApiCallLog: (input) => insertApiCallLog(prisma, input),
+        getRecentApiCallsForRoute: (route, sinceMinutes) => getRecentApiCallsForRoute(prisma, route, sinceMinutes),
+        insertTraceLink: (input) => insertTraceLink(prisma, input),
+        captureError: (options) => captureError(prisma, options),
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/trace/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/trace/client.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAA4B,MAAM,aAAa,CAAC;AACrE,OAAO,EACL,uBAAuB,EACvB,yBAAyB,EACzB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,gBAAgB,GAKjB,MAAM,cAAc,CAAC;AA4BtB,MAAM,UAAU,iBAAiB,CAAC,MAAyB;IACzD,OAAO;QACL,eAAe,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC;QAC1D,gBAAgB,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,gBAAgB,CAAC,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC;QACtE,oBAAoB,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC;QACtE,gBAAgB,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC;QAC5D,uBAAuB,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,CACrD,uBAAuB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,KAAK,CAAC;QAC5D,gBAAgB,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,gBAAgB,CAAC,MAAM,EAAE,KAAK,CAAC;QAC5D,yBAAyB,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,CACjD,yBAAyB,CAAC,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC;QACxD,eAAe,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC;QAC1D,YAAY,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC;KACzD,CAAC;AACJ,CAAC"}

package/dist/trace/errors.d.ts

@@ -0,0 +1,31 @@
+import type { TraceNodeRow, TracePrismaClient } from "./types.js";
+export interface CapturedErrorPayload {
+    message: string;
+    stack: string | null;
+    context: unknown;
+}
+export interface TraceErrorAlertPayload {
+    traceNode: TraceNodeRow;
+    error: Error;
+    actorId?: string | undefined;
+    route?: string | undefined;
+}
+export type TraceErrorAlertHook = (payload: TraceErrorAlertPayload) => Promise<void>;
+export declare const defaultTraceErrorAlertHook: TraceErrorAlertHook;
+export interface CaptureErrorOptions {
+    error: Error;
+    actorId?: string;
+    route?: string;
+    /** Existing trace root to hang this error node off of. Omit to make the error
+     *  node self-rooted (`root_id = id`) — e.g. an uncaught exception with no
+     *  in-flight trace context. */
+    rootId?: bigint;
+    /** Arbitrary structured context to store alongside the error (request body,
+     *  job payload, ids, ...). Stored as-is in `request_data.context`. */
+    context?: unknown;
+    /** Defaults to logging to console.error. The real Slack-webhook (or other
+     *  alerting) wiring is consumer-specific and lives outside this module —
+     *  this is just the injectable, typed seam for it. */
+    alertHook?: TraceErrorAlertHook;
+}
+export declare function captureError(prisma: TracePrismaClient, options: CaptureErrorOptions): Promise<TraceNodeRow>;

package/dist/trace/errors.js

@@ -0,0 +1,37 @@
+/**
+ * Error capture (DEC-49): folded into trace rather than shipped as a separate
+ * module. An `ERROR`-kind TraceNode is the record; the alert hook is the seam for
+ * wiring in wherever the consumer wants notifications (Slack, PagerDuty, email,
+ * ...) — that wiring is consumer-specific and out of scope for this module, so the
+ * default hook just logs, and consumers pass their own `alertHook`.
+ */
+import { insertTraceNode, setTraceNodeRoot } from "./queries.js";
+export const defaultTraceErrorAlertHook = async (payload) => {
+    console.error(`[app-kit/trace] captured error${payload.route ? ` on ${payload.route}` : ""}:`, payload.error);
+};
+export async function captureError(prisma, options) {
+    const { error, actorId, route, context, alertHook = defaultTraceErrorAlertHook, } = options;
+    const requestData = {
+        message: error.message,
+        stack: error.stack ?? null,
+        context: context ?? null,
+    };
+    let node = await insertTraceNode(prisma, {
+        // rootId is NOT NULL on TraceNode; when the caller has no root to attach to,
+        // insert self-referentially rooted below once the id is known.
+        rootId: options.rootId ?? 0n,
+        parentId: null,
+        kind: "ERROR",
+        actorId: actorId ?? null,
+        route: route ?? null,
+        requestData,
+        responseData: null,
+        statusCode: null,
+    });
+    if (options.rootId === undefined) {
+        node = await setTraceNodeRoot(prisma, node.id, node.id);
+    }
+    await alertHook({ traceNode: node, error, actorId, route });
+    return node;
+}
+//# sourceMappingURL=errors.js.map

package/dist/trace/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/trace/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAoBjE,MAAM,CAAC,MAAM,0BAA0B,GAAwB,KAAK,EAClE,OAAO,EACP,EAAE;IACF,OAAO,CAAC,KAAK,CACX,iCAAiC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAC/E,OAAO,CAAC,KAAK,CACd,CAAC;AACJ,CAAC,CAAC;AAmBF,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,MAAyB,EACzB,OAA4B;IAE5B,MAAM,EACJ,KAAK,EACL,OAAO,EACP,KAAK,EACL,OAAO,EACP,SAAS,GAAG,0BAA0B,GACvC,GAAG,OAAO,CAAC;IAEZ,MAAM,WAAW,GAAyB;QACxC,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,IAAI;QAC1B,OAAO,EAAE,OAAO,IAAI,IAAI;KACzB,CAAC;IAEF,IAAI,IAAI,GAAG,MAAM,eAAe,CAAC,MAAM,EAAE;QACvC,6EAA6E;QAC7E,+DAA+D;QAC/D,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,EAAE;QAC5B,QAAQ,EAAE,IAAI;QACd,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,OAAO,IAAI,IAAI;QACxB,KAAK,EAAE,KAAK,IAAI,IAAI;QACpB,WAAW;QACX,YAAY,EAAE,IAAI;QAClB,UAAU,EAAE,IAAI;KACjB,CAAC,CAAC;IAEH,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QACjC,IAAI,GAAG,MAAM,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,MAAM,SAAS,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IAE5D,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/trace/index.d.ts

@@ -1,6 +1,17 @@
 /**
- * Postgres-native trace/audit layer — placeholder for the real module (DEC-16, DEC-22,
- * DEC-26, DEC-31). Ships Prisma schema fragments + SQL migrations + a `trace:sync` CLI,
- * not a generated Prisma Client — see DEC-31 for why.
+ * Postgres-native trace/audit layer (DEC-16, DEC-22, DEC-26, DEC-31, DEC-39,
+ * DEC-49). Ships Prisma schema fragments + raw SQL migrations + a `trace-sync`
+ * CLI, not a generated Prisma Client — see prisma/fragments/trace.prisma and
+ * src/cli/trace-sync.ts for why and how.
+ *
+ * Consumers bring their own generated PrismaClient (after running
+ * `trace-sync init`) and get a bound query surface from createTraceClient, or use
+ * the individual query helpers directly.
  */
-export declare const APP_KIT_TRACE_PLACEHOLDER = true;
+export type { TracePrismaClient, TraceNodeKind, TraceNodeRow, ModelAuditRow, ApiCallLogRow, TraceLinkRow, } from "./types.js";
+export { insertTraceNode, setTraceNodeRoot, getTraceChainForRoot, insertModelAudit, getAuditHistoryForModel, insertApiCallLog, getRecentApiCallsForRoute, insertTraceLink, } from "./queries.js";
+export type { NewTraceNodeInput, NewModelAuditInput, NewApiCallLogInput, NewTraceLinkInput, } from "./queries.js";
+export { captureError, defaultTraceErrorAlertHook } from "./errors.js";
+export type { CaptureErrorOptions, CapturedErrorPayload, TraceErrorAlertHook, TraceErrorAlertPayload, } from "./errors.js";
+export { createTraceClient } from "./client.js";
+export type { TraceClient } from "./client.js";

package/dist/trace/index.js

@@ -1,7 +1,4 @@
-/**
- * Postgres-native trace/audit layer — placeholder for the real module (DEC-16, DEC-22,
- * DEC-26, DEC-31). Ships Prisma schema fragments + SQL migrations + a `trace:sync` CLI,
- * not a generated Prisma Client — see DEC-31 for why.
- */
-export const APP_KIT_TRACE_PLACEHOLDER = true;
+export { insertTraceNode, setTraceNodeRoot, getTraceChainForRoot, insertModelAudit, getAuditHistoryForModel, insertApiCallLog, getRecentApiCallsForRoute, insertTraceLink, } from "./queries.js";
+export { captureError, defaultTraceErrorAlertHook } from "./errors.js";
+export { createTraceClient } from "./client.js";
 //# sourceMappingURL=index.js.map

package/dist/trace/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/trace/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,IAAI,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/trace/index.ts"],"names":[],"mappings":"AAmBA,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,yBAAyB,EACzB,eAAe,GAChB,MAAM,cAAc,CAAC;AAQtB,OAAO,EAAE,YAAY,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAC;AAQvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC"}

package/dist/trace/queries.d.ts

@@ -0,0 +1,59 @@
+import type { ApiCallLogRow, ModelAuditRow, TraceLinkRow, TraceNodeRow, TracePrismaClient } from "./types.js";
+export interface NewTraceNodeInput {
+    externalId?: string;
+    parentId?: bigint | null;
+    rootId: bigint;
+    kind: string;
+    actorId?: string | null;
+    route?: string | null;
+    requestData?: unknown;
+    responseData?: unknown;
+    statusCode?: number | null;
+    startedAt?: Date;
+    endedAt?: Date | null;
+    durationMs?: number | null;
+}
+export declare function insertTraceNode(prisma: TracePrismaClient, input: NewTraceNodeInput): Promise<TraceNodeRow>;
+/**
+ * Point an already-inserted TraceNode's `root_id` at a (possibly different) id.
+ * Used by src/trace/errors.ts to make a standalone captured error self-rooted
+ * (`root_id = id`) when the caller has no existing trace root to hang it off of —
+ * `TraceNode.rootId` is `NOT NULL`, so an orphan error always needs *some* root.
+ */
+export declare function setTraceNodeRoot(prisma: TracePrismaClient, id: bigint, rootId: bigint): Promise<TraceNodeRow>;
+export declare function getTraceChainForRoot(prisma: TracePrismaClient, rootId: bigint): Promise<TraceNodeRow[]>;
+export interface NewModelAuditInput {
+    traceNodeId?: bigint | null;
+    modelType: string;
+    modelId: string;
+    event: string;
+    actorId?: string | null;
+    oldValues?: unknown;
+    newValues?: unknown;
+    createdAt?: Date;
+}
+export declare function insertModelAudit(prisma: TracePrismaClient, input: NewModelAuditInput): Promise<ModelAuditRow>;
+export declare function getAuditHistoryForModel(prisma: TracePrismaClient, modelType: string, modelId: string, limit?: number): Promise<ModelAuditRow[]>;
+export interface NewApiCallLogInput {
+    traceNodeId?: bigint | null;
+    route: string;
+    method: string;
+    statusCode?: number | null;
+    actorId?: string | null;
+    durationMs?: number | null;
+    createdAt?: Date;
+}
+export declare function insertApiCallLog(prisma: TracePrismaClient, input: NewApiCallLogInput): Promise<ApiCallLogRow>;
+export declare function getRecentApiCallsForRoute(prisma: TracePrismaClient, route: string, sinceMinutes?: number): Promise<ApiCallLogRow[]>;
+export interface NewTraceLinkInput {
+    fromId: bigint;
+    toId: bigint;
+    kind: string;
+    createdAt?: Date;
+}
+/**
+ * Upsert on the (fromId, toId, kind) unique constraint: calling this twice for
+ * the same triple updates the one row in place (a no-op `SET kind = EXCLUDED.kind`)
+ * instead of raising a unique-violation or silently inserting a duplicate.
+ */
+export declare function insertTraceLink(prisma: TracePrismaClient, input: NewTraceLinkInput): Promise<TraceLinkRow>;

package/dist/trace/queries.js

@@ -0,0 +1,147 @@
+/**
+ * Typed $queryRaw/$executeRaw helpers for @flytedesk/app-kit/trace.
+ *
+ * Every helper writes/reads the tables created by
+ * prisma/migrations/0001_app_kit_trace_init/migration.sql directly. Column lists
+ * are written out literally in each query's tagged template (rather than shared
+ * via a string constant interpolated into the template) because a `${...}`
+ * interpolation inside a $queryRaw tagged template becomes a bound *parameter*,
+ * not raw SQL text — the TracePrismaClient structural interface has no
+ * `Prisma.raw`/`$queryRawUnsafe` escape hatch, deliberately, so there is no way to
+ * splice SQL fragments in from a variable. That's fine: the column lists are
+ * static.
+ */
+import { randomUUID } from "node:crypto";
+function toJsonParam(value) {
+    return value === undefined || value === null ? null : JSON.stringify(value);
+}
+function requireOne(rows, what) {
+    const row = rows[0];
+    if (!row) {
+        throw new Error(`${what}: expected a returned row but got none`);
+    }
+    return row;
+}
+export async function insertTraceNode(prisma, input) {
+    const externalId = input.externalId ?? randomUUID();
+    const startedAt = input.startedAt ?? new Date();
+    const rows = await prisma.$queryRaw `
+    INSERT INTO app_kit_trace_nodes (
+      external_id, parent_id, root_id, kind, actor_id, route,
+      request_data, response_data, status_code, started_at, ended_at, duration_ms
+    ) VALUES (
+      ${externalId}::uuid, ${input.parentId ?? null}, ${input.rootId}, ${input.kind},
+      ${input.actorId ?? null}, ${input.route ?? null},
+      ${toJsonParam(input.requestData)}::jsonb, ${toJsonParam(input.responseData)}::jsonb,
+      ${input.statusCode ?? null}, ${startedAt}, ${input.endedAt ?? null}, ${input.durationMs ?? null}
+    )
+    RETURNING
+      id, external_id AS "externalId", parent_id AS "parentId", root_id AS "rootId", kind,
+      actor_id AS "actorId", route, request_data AS "requestData", response_data AS "responseData",
+      status_code AS "statusCode", started_at AS "startedAt", ended_at AS "endedAt",
+      duration_ms AS "durationMs"
+  `;
+    return requireOne(rows, "insertTraceNode");
+}
+/**
+ * Point an already-inserted TraceNode's `root_id` at a (possibly different) id.
+ * Used by src/trace/errors.ts to make a standalone captured error self-rooted
+ * (`root_id = id`) when the caller has no existing trace root to hang it off of —
+ * `TraceNode.rootId` is `NOT NULL`, so an orphan error always needs *some* root.
+ */
+export async function setTraceNodeRoot(prisma, id, rootId) {
+    const rows = await prisma.$queryRaw `
+    UPDATE app_kit_trace_nodes
+    SET root_id = ${rootId}
+    WHERE id = ${id}
+    RETURNING
+      id, external_id AS "externalId", parent_id AS "parentId", root_id AS "rootId", kind,
+      actor_id AS "actorId", route, request_data AS "requestData", response_data AS "responseData",
+      status_code AS "statusCode", started_at AS "startedAt", ended_at AS "endedAt",
+      duration_ms AS "durationMs"
+  `;
+    return requireOne(rows, "setTraceNodeRoot");
+}
+export async function getTraceChainForRoot(prisma, rootId) {
+    return prisma.$queryRaw `
+    SELECT
+      id, external_id AS "externalId", parent_id AS "parentId", root_id AS "rootId", kind,
+      actor_id AS "actorId", route, request_data AS "requestData", response_data AS "responseData",
+      status_code AS "statusCode", started_at AS "startedAt", ended_at AS "endedAt",
+      duration_ms AS "durationMs"
+    FROM app_kit_trace_nodes
+    WHERE root_id = ${rootId}
+    ORDER BY started_at ASC
+  `;
+}
+export async function insertModelAudit(prisma, input) {
+    const createdAt = input.createdAt ?? new Date();
+    const rows = await prisma.$queryRaw `
+    INSERT INTO app_kit_trace_model_audits (
+      trace_node_id, model_type, model_id, event, actor_id, old_values, new_values, created_at
+    ) VALUES (
+      ${input.traceNodeId ?? null}, ${input.modelType}, ${input.modelId}, ${input.event},
+      ${input.actorId ?? null}, ${toJsonParam(input.oldValues)}::jsonb,
+      ${toJsonParam(input.newValues)}::jsonb, ${createdAt}
+    )
+    RETURNING
+      id, trace_node_id AS "traceNodeId", model_type AS "modelType", model_id AS "modelId",
+      event, actor_id AS "actorId", old_values AS "oldValues", new_values AS "newValues",
+      created_at AS "createdAt"
+  `;
+    return requireOne(rows, "insertModelAudit");
+}
+export async function getAuditHistoryForModel(prisma, modelType, modelId, limit = 50) {
+    return prisma.$queryRaw `
+    SELECT
+      id, trace_node_id AS "traceNodeId", model_type AS "modelType", model_id AS "modelId",
+      event, actor_id AS "actorId", old_values AS "oldValues", new_values AS "newValues",
+      created_at AS "createdAt"
+    FROM app_kit_trace_model_audits
+    WHERE model_type = ${modelType} AND model_id = ${modelId}
+    ORDER BY created_at DESC
+    LIMIT ${limit}
+  `;
+}
+export async function insertApiCallLog(prisma, input) {
+    const createdAt = input.createdAt ?? new Date();
+    const rows = await prisma.$queryRaw `
+    INSERT INTO app_kit_trace_api_call_logs (
+      trace_node_id, route, method, status_code, actor_id, duration_ms, created_at
+    ) VALUES (
+      ${input.traceNodeId ?? null}, ${input.route}, ${input.method}, ${input.statusCode ?? null},
+      ${input.actorId ?? null}, ${input.durationMs ?? null}, ${createdAt}
+    )
+    RETURNING
+      id, trace_node_id AS "traceNodeId", route, method, status_code AS "statusCode",
+      actor_id AS "actorId", duration_ms AS "durationMs", created_at AS "createdAt"
+  `;
+    return requireOne(rows, "insertApiCallLog");
+}
+export async function getRecentApiCallsForRoute(prisma, route, sinceMinutes = 30) {
+    const since = new Date(Date.now() - sinceMinutes * 60_000);
+    return prisma.$queryRaw `
+    SELECT
+      id, trace_node_id AS "traceNodeId", route, method, status_code AS "statusCode",
+      actor_id AS "actorId", duration_ms AS "durationMs", created_at AS "createdAt"
+    FROM app_kit_trace_api_call_logs
+    WHERE route = ${route} AND created_at >= ${since}
+    ORDER BY created_at DESC
+  `;
+}
+/**
+ * Upsert on the (fromId, toId, kind) unique constraint: calling this twice for
+ * the same triple updates the one row in place (a no-op `SET kind = EXCLUDED.kind`)
+ * instead of raising a unique-violation or silently inserting a duplicate.
+ */
+export async function insertTraceLink(prisma, input) {
+    const createdAt = input.createdAt ?? new Date();
+    const rows = await prisma.$queryRaw `
+    INSERT INTO app_kit_trace_links (from_id, to_id, kind, created_at)
+    VALUES (${input.fromId}, ${input.toId}, ${input.kind}, ${createdAt})
+    ON CONFLICT (from_id, to_id, kind) DO UPDATE SET kind = EXCLUDED.kind
+    RETURNING id, from_id AS "fromId", to_id AS "toId", kind, created_at AS "createdAt"
+  `;
+    return requireOne(rows, "insertTraceLink");
+}
+//# sourceMappingURL=queries.js.map

package/dist/trace/queries.js.map

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

package/dist/trace/types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Hand-written row/client types for @flytedesk/app-kit/trace.
+ *
+ * These are written by hand, not generated by Prisma, because this package never
+ * builds its own PrismaClient (DEC-39): the consumer generates their own client
+ * from their own schema plus the fragment copied in by `trace-sync init`, and this
+ * package only ever talks to that client through the minimal structural interface
+ * below, via raw SQL. Field names here mirror the field names in
+ * prisma/fragments/trace.prisma; query helpers (src/trace/queries.ts) are
+ * responsible for aliasing the snake_case SQL columns back onto these camelCase
+ * shapes with `AS "camelCaseName"`.
+ */
+/**
+ * The structural subset of a generated PrismaClient this package actually needs.
+ * Deliberately minimal and decoupled from `@prisma/client`'s own types: any object
+ * exposing tagged-template `$queryRaw`/`$executeRaw` methods satisfies this,
+ * including a real PrismaClient instance, a lightly-wrapped one (e.g. request
+ * logging middleware), or a hand-rolled test double.
+ */
+export interface TracePrismaClient {
+    $queryRaw<T = unknown>(query: TemplateStringsArray, ...values: unknown[]): Promise<T>;
+    $executeRaw(query: TemplateStringsArray, ...values: unknown[]): Promise<number>;
+}
+/**
+ * Valid `TraceNode.kind` values this package knows how to write.
+ * The column itself is a plain `String` (see trace.prisma for why), so consumers
+ * remain free to write their own kinds; this union is what src/trace helpers use.
+ */
+export type TraceNodeKind = "HTTP_REQUEST" | "JOB" | "EVENT" | "SYSTEM" | "ERROR";
+export interface TraceNodeRow {
+    id: bigint;
+    externalId: string;
+    parentId: bigint | null;
+    rootId: bigint;
+    kind: string;
+    actorId: string | null;
+    route: string | null;
+    requestData: unknown;
+    responseData: unknown;
+    statusCode: number | null;
+    startedAt: Date;
+    endedAt: Date | null;
+    durationMs: number | null;
+}
+export interface ModelAuditRow {
+    id: bigint;
+    traceNodeId: bigint | null;
+    modelType: string;
+    modelId: string;
+    event: string;
+    actorId: string | null;
+    oldValues: unknown;
+    newValues: unknown;
+    createdAt: Date;
+}
+export interface ApiCallLogRow {
+    id: bigint;
+    traceNodeId: bigint | null;
+    route: string;
+    method: string;
+    statusCode: number | null;
+    actorId: string | null;
+    durationMs: number | null;
+    createdAt: Date;
+}
+export interface TraceLinkRow {
+    id: bigint;
+    fromId: bigint;
+    toId: bigint;
+    kind: string;
+    createdAt: Date;
+}

package/dist/trace/types.js

@@ -0,0 +1,14 @@
+/**
+ * Hand-written row/client types for @flytedesk/app-kit/trace.
+ *
+ * These are written by hand, not generated by Prisma, because this package never
+ * builds its own PrismaClient (DEC-39): the consumer generates their own client
+ * from their own schema plus the fragment copied in by `trace-sync init`, and this
+ * package only ever talks to that client through the minimal structural interface
+ * below, via raw SQL. Field names here mirror the field names in
+ * prisma/fragments/trace.prisma; query helpers (src/trace/queries.ts) are
+ * responsible for aliasing the snake_case SQL columns back onto these camelCase
+ * shapes with `AS "camelCaseName"`.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/trace/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/trace/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flytedesk/app-kit",
-  "version": "0.0.1",
+  "version": "0.1.1",
   "description": "Shared platform kit for flytedesk apps: flytedesk-id auth (BFF/OIDC client) and a Postgres-native trace/audit layer.",
   "type": "module",
   "license": "UNLICENSED",
@@ -19,12 +19,16 @@
     "pnpm": ">=12.0.0"
   },
   "publishConfig": {
-    "access": "restricted",
+    "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "files": [
-    "dist"
+    "dist",
+    "prisma"
   ],
+  "bin": {
+    "trace-sync": "./dist/cli/trace-sync.js"
+  },
   "exports": {
     "./auth": {
       "types": "./dist/auth/index.d.ts",
@@ -33,26 +37,68 @@
     "./trace": {
       "types": "./dist/trace/index.d.ts",
       "import": "./dist/trace/index.js"
+    },
+    "./rate-limit": {
+      "types": "./dist/rate-limit/index.d.ts",
+      "import": "./dist/rate-limit/index.js"
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "prepare": "node scripts/postinstall-eslint-ts6-shim.cjs",
+    "test": "vitest run",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "lint": "eslint .",
+    "format": "prettier --check .",
+    "check:exports": "publint && attw --pack . --profile esm-only",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "npm run build && npm run check:exports && changeset publish"
   },
   "peerDependencies": {
-    "fastify": "^4 || ^5",
-    "@prisma/client": "^7"
+    "@prisma/client": "^7",
+    "fastify": "^4 || ^5"
   },
   "peerDependenciesMeta": {
     "@prisma/client": {
       "optional": true
     }
   },
+  "overrides": {
+    "typescript-eslint": {
+      "typescript": "$typescript"
+    }
+  },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@changesets/changelog-github": "^1.0.0",
+    "@changesets/cli": "^3.0.1",
     "@prisma/client": "^7.10.0",
+    "@testcontainers/postgresql": "^12.1.0",
+    "@types/cross-spawn": "^6.0.6",
     "@types/node": "^24.0.0",
+    "@types/pg": "^8.23.1",
+    "@typescript/typescript6": "^6.0.2",
+    "@vitest/coverage-v8": "^4.1.11",
+    "eslint": "^10.9.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-n": "^18.3.0",
     "fastify": "^5.12.0",
-    "typescript": "^5.7.0"
+    "globals": "^17.12.0",
+    "pg": "^8.23.0",
+    "prettier": "^3.9.6",
+    "publint": "^0.3.24",
+    "testcontainers": "^12.1.0",
+    "typescript": "^7.0.2",
+    "typescript-eslint": "^8.69.0",
+    "vitest": "^4.1.11"
+  },
+  "dependencies": {
+    "@fastify/cookie": "^11.0.1",
+    "cross-spawn": "^7.0.6",
+    "fastify-plugin": "^6.0.0",
+    "jose": "^6.2.10"
   }
 }

package/prisma/fragments/trace.meta.json

@@ -0,0 +1,4 @@
+{
+  "fragmentVersion": "1.0.0",
+  "minCliVersion": "1.0.0"
+}

package/prisma/fragments/trace.prisma

@@ -0,0 +1,87 @@
+// @flytedesk/app-kit/trace — canonical Prisma model fragment (DEC-39).
+//
+// This fragment is NOT built into a Prisma Client by this package. It is copied
+// verbatim into the consumer's own multi-file Prisma schema folder by `trace-sync
+// init` (see src/cli/trace-sync.ts), and the consumer generates their own client
+// against their own schema + this fragment merged in.
+//
+// Design constraints (deliberate, see DEC-39):
+//   - No `@relation`/FK attributes anywhere. These are plain scalar columns. A
+//     package that ships models into a consumer's schema cannot see the consumer's
+//     other models, and dropping relation attributes avoids lock contention on the
+//     hottest insert path (trace nodes are written on every request/job).
+//   - No Prisma `enum`. Enums are schema-global in Prisma and would collide across
+//     packages that both want to declare, say, an `EventKind`. `kind`/`event` are
+//     plain `String` columns; the TypeScript layer (src/trace/types.ts) provides a
+//     union type for the values this package writes.
+//   - `BigInt @id @default(autoincrement())` primary keys, not UUID, for insert
+//     locality on a high-write append log.
+//
+// Table names are prefixed `app_kit_trace_` via `@@map` so they can't collide with
+// consumer tables. Column names are snake_case via `@map`, matching the raw SQL in
+// prisma/migrations/0001_app_kit_trace_init/migration.sql exactly.
+
+model TraceNode {
+  id           BigInt    @id @default(autoincrement())
+  externalId   String    @default(uuid()) @db.Uuid @map("external_id")
+  parentId     BigInt?   @map("parent_id")
+  rootId       BigInt    @map("root_id")
+  kind         String
+  actorId      String?   @map("actor_id")
+  route        String?
+  requestData  Json?     @map("request_data")
+  responseData Json?     @map("response_data")
+  statusCode   Int?      @map("status_code")
+  startedAt    DateTime  @default(now()) @map("started_at")
+  endedAt      DateTime? @map("ended_at")
+  durationMs   Int?      @map("duration_ms")
+
+  @@index([rootId])
+  @@index([parentId])
+  @@index([route, startedAt(sort: Desc)])
+  @@index([actorId, startedAt(sort: Desc)])
+  @@map("app_kit_trace_nodes")
+}
+
+model ModelAudit {
+  id          BigInt   @id @default(autoincrement())
+  traceNodeId BigInt?  @map("trace_node_id")
+  modelType   String   @map("model_type")
+  modelId     String   @map("model_id")
+  event       String
+  actorId     String?  @map("actor_id")
+  oldValues   Json?    @map("old_values")
+  newValues   Json?    @map("new_values")
+  createdAt   DateTime @default(now()) @map("created_at")
+
+  @@index([modelType, modelId, createdAt(sort: Desc)])
+  @@index([traceNodeId])
+  @@map("app_kit_trace_model_audits")
+}
+
+model ApiCallLog {
+  id          BigInt   @id @default(autoincrement())
+  traceNodeId BigInt?  @map("trace_node_id")
+  route       String
+  method      String
+  statusCode  Int?     @map("status_code")
+  actorId     String?  @map("actor_id")
+  durationMs  Int?     @map("duration_ms")
+  createdAt   DateTime @default(now()) @map("created_at")
+
+  @@index([route, createdAt(sort: Desc)])
+  @@index([actorId, createdAt(sort: Desc)])
+  @@map("app_kit_trace_api_call_logs")
+}
+
+model TraceLink {
+  id        BigInt   @id @default(autoincrement())
+  fromId    BigInt   @map("from_id")
+  toId      BigInt   @map("to_id")
+  kind      String
+  createdAt DateTime @default(now()) @map("created_at")
+
+  @@unique([fromId, toId, kind])
+  @@index([toId])
+  @@map("app_kit_trace_links")
+}