@fonderie/audit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fonderie, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# @fonderie/audit
+
+The paper trail: query the platform's event log as a human-readable,
+workspace-scoped activity feed. If a brick emitted it, this brick can
+show it.
+
+## Install
+
+```sh
+npm install @fonderie/audit
+```
+
+## Use
+
+```ts
+import { FonderieApp, defineConfig } from '@fonderie/core';
+import { AuditModule } from '@fonderie/audit';
+
+const app = await new FonderieApp(defineConfig({}))
+  .register(new AuditModule())
+  .boot();
+```
+
+```ts
+import type { IAuditQuery, IAuditPageDTO } from '@fonderie/audit';
+```
+
+## Why this exists
+
+You've shipped this plumbing before — auth, teams, billing, messaging —
+and the next project will ask for it again. Fonderie packages it once:
+plain TypeScript modules for
+[`@fonderie/core`](https://github.com/fonderie-js/sdk/tree/main/packages/core),
+PostgreSQL-backed, self-hosted, MIT. No external control plane, no
+per-seat anything. Register the modules you need; skip the ones you don't.
+
+**This package owns** what happened. It reads the platform's event log back as a
+human-readable, workspace-scoped activity trail.
+
+Browse the whole set at
+[fonderie-js/sdk](https://github.com/fonderie-js/sdk) · follow
+[@fonderiejs](https://x.com/fonderiejs)
+
+## License
+
+MIT © Fonderie, Inc.

package/dist/index.cjs

@@ -0,0 +1,170 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuditModule: () => AuditModule
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/routes.ts
+var import_core = require("@fonderie/core");
+var import_middlewares = require("@fonderie/core/middlewares");
+
+// src/dtos/audit.ts
+function toAuditEventDTO(e) {
+  return {
+    id: e.id,
+    type: e.type,
+    actorId: e.payload["userId"] ?? null,
+    requestId: e.meta["requestId"] ?? null,
+    payload: e.payload,
+    createdAt: e.createdAt.toISOString()
+  };
+}
+function encodeCursor(createdAt, id) {
+  return Buffer.from(`${createdAt.toISOString()},${id}`).toString("base64");
+}
+function decodeCursor(cursor) {
+  try {
+    const raw = Buffer.from(cursor, "base64").toString();
+    const commaIdx = raw.indexOf(",");
+    if (commaIdx === -1) return null;
+    const createdAt = raw.slice(0, commaIdx);
+    const id = raw.slice(commaIdx + 1);
+    if (!id || isNaN(Date.parse(createdAt))) return null;
+    return { createdAt, id };
+  } catch {
+    return null;
+  }
+}
+
+// src/models/event.model.ts
+var MAX_LIMIT = 200;
+var AuditEventModel = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  async list(query) {
+    const limit = Math.min(query.limit ?? 50, MAX_LIMIT);
+    const params = [query.workspaceId];
+    const where = [`payload->>'workspaceId' = $1`];
+    if (query.type) {
+      params.push(query.type);
+      where.push(`type = $${params.length}`);
+    }
+    if (query.actorId) {
+      params.push(query.actorId);
+      where.push(`payload->>'userId' = $${params.length}`);
+    }
+    if (query.from) {
+      params.push(query.from);
+      where.push(`created_at >= $${params.length}`);
+    }
+    if (query.to) {
+      params.push(query.to);
+      where.push(`created_at <= $${params.length}`);
+    }
+    if (query.cursor) {
+      const decoded = decodeCursor(query.cursor);
+      if (decoded) {
+        params.push(decoded.createdAt, decoded.id);
+        where.push(
+          `(created_at, id) < ($${params.length - 1}::timestamptz, $${params.length}::uuid)`
+        );
+      }
+    }
+    params.push(limit);
+    return this.store.query(
+      `SELECT id, type, payload, meta, created_at as "createdAt"
+			 FROM   fonderie_events
+			 WHERE  ${where.join(" AND ")}
+			 ORDER  BY created_at DESC, id DESC
+			 LIMIT  $${params.length}`,
+      params
+    );
+  }
+};
+
+// src/routes.ts
+function buildAuditRoutes(store) {
+  return [
+    [
+      "GET",
+      "/audit",
+      import_middlewares.requireAuth,
+      async (ctx) => {
+        if (!ctx.workspace)
+          return (0, import_core.setApiResponse)(
+            import_core.HTTP.UNPROCESSABLE,
+            "MISSING_WORKSPACE",
+            "Workspace context required"
+          );
+        const url = new URL(ctx.request.url);
+        const params = url.searchParams;
+        const limit = Math.min(Number(params.get("limit") ?? 50), 200);
+        const type = params.get("type") ?? void 0;
+        const actor = params.get("actorId") ?? void 0;
+        const from = params.get("from") ? new Date(params.get("from")) : void 0;
+        const to = params.get("to") ? new Date(params.get("to")) : void 0;
+        const cursor = params.get("cursor") ?? void 0;
+        const query = {
+          workspaceId: ctx.workspace.id,
+          limit: limit + 1
+        };
+        if (type) query.type = type;
+        if (actor) query.actorId = actor;
+        if (from) query.from = from;
+        if (to) query.to = to;
+        if (cursor) query.cursor = cursor;
+        const events = await new AuditEventModel(store).list(query);
+        const hasMore = events.length > limit;
+        const page = hasMore ? events.slice(0, limit) : events;
+        const lastEvent = page[page.length - 1];
+        const nextCursor = hasMore && lastEvent ? encodeCursor(lastEvent.createdAt, lastEvent.id) : null;
+        return (0, import_core.setApiResponse)(import_core.HTTP.OK, "AUDIT_FETCHED", "Audit events retrieved.", {
+          events: page.map(toAuditEventDTO),
+          nextCursor
+        });
+      }
+    ]
+  ];
+}
+
+// src/module.ts
+var AuditModule = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  name = "@fonderie/audit";
+  deps = ["@fonderie/auth", "@fonderie/workspaces"];
+  install(app) {
+    for (const [method, path, ...handlers] of buildAuditRoutes(this.store)) {
+      app.addRoute(method, path, ...handlers);
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuditModule
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/routes.ts","../src/dtos/audit.ts","../src/models/event.model.ts","../src/module.ts"],"sourcesContent":["export { AuditModule } from './module';\nexport type { IAuditEvent, IAuditQuery } from './types';\nexport type { IAuditEventDTO, IAuditPageDTO } from './dtos/audit';\n","import type { Middleware } from '@fonderie/core';\nimport { setApiResponse, HTTP } from '@fonderie/core';\nimport { requireAuth } from '@fonderie/core/middlewares';\nimport type { IStoreAdapter } from '@fonderie/store';\n\nimport { AuditEventModel } from './models/event.model';\nimport { toAuditEventDTO, encodeCursor } from './dtos/audit';\n\ntype Route = [string, string, ...Middleware[]];\n\nexport function buildAuditRoutes(store: IStoreAdapter): Route[] {\n\treturn [\n\t\t[\n\t\t\t'GET',\n\t\t\t'/audit',\n\t\t\trequireAuth,\n\t\t\tasync (ctx) => {\n\t\t\t\tif (!ctx.workspace)\n\t\t\t\t\treturn setApiResponse(\n\t\t\t\t\t\tHTTP.UNPROCESSABLE,\n\t\t\t\t\t\t'MISSING_WORKSPACE',\n\t\t\t\t\t\t'Workspace context required',\n\t\t\t\t\t);\n\n\t\t\t\tconst url = new URL(ctx.request.url);\n\t\t\t\tconst params = url.searchParams;\n\n\t\t\t\tconst limit = Math.min(Number(params.get('limit') ?? 50), 200);\n\t\t\t\tconst type = params.get('type') ?? undefined;\n\t\t\t\tconst actor = params.get('actorId') ?? undefined;\n\t\t\t\tconst from = params.get('from') ? new Date(params.get('from')!) : undefined;\n\t\t\t\tconst to = params.get('to') ? new Date(params.get('to')!) : undefined;\n\t\t\t\tconst cursor = params.get('cursor') ?? undefined;\n\n\t\t\t\tconst query: Parameters<AuditEventModel['list']>[0] = {\n\t\t\t\t\tworkspaceId: ctx.workspace.id,\n\t\t\t\t\tlimit: limit + 1,\n\t\t\t\t};\n\t\t\t\tif (type) query.type = type;\n\t\t\t\tif (actor) query.actorId = actor;\n\t\t\t\tif (from) query.from = from;\n\t\t\t\tif (to) query.to = to;\n\t\t\t\tif (cursor) query.cursor = cursor;\n\n\t\t\t\tconst events = await new AuditEventModel(store).list(query);\n\n\t\t\t\t// fetch one extra to determine if there's a next page\n\t\t\t\tconst hasMore = events.length > limit;\n\t\t\t\tconst page = hasMore ? events.slice(0, limit) : events;\n\t\t\t\tconst lastEvent = page[page.length - 1];\n\t\t\t\tconst nextCursor =\n\t\t\t\t\thasMore && lastEvent ? encodeCursor(lastEvent.createdAt, lastEvent.id) : null;\n\n\t\t\t\treturn setApiResponse(HTTP.OK, 'AUDIT_FETCHED', 'Audit events retrieved.', {\n\t\t\t\t\tevents: page.map(toAuditEventDTO),\n\t\t\t\t\tnextCursor,\n\t\t\t\t});\n\t\t\t},\n\t\t],\n\t];\n}\n","import type { IAuditEvent } from '../types';\n\nexport interface IAuditEventDTO {\n\tid: string;\n\ttype: string;\n\tactorId: string | null;\n\trequestId: string | null;\n\tpayload: Record<string, unknown>;\n\tcreatedAt: string;\n}\n\nexport interface IAuditPageDTO {\n\tevents: IAuditEventDTO[];\n\tnextCursor: string | null;\n}\n\nexport function toAuditEventDTO(e: IAuditEvent): IAuditEventDTO {\n\treturn {\n\t\tid: e.id,\n\t\ttype: e.type,\n\t\tactorId: (e.payload['userId'] as string | undefined) ?? null,\n\t\trequestId: (e.meta['requestId'] as string | undefined) ?? null,\n\t\tpayload: e.payload,\n\t\tcreatedAt: e.createdAt.toISOString(),\n\t};\n}\n\nexport function encodeCursor(createdAt: Date, id: string): string {\n\treturn Buffer.from(`${createdAt.toISOString()},${id}`).toString('base64');\n}\n\nexport function decodeCursor(cursor: string): { createdAt: string; id: string } | null {\n\ttry {\n\t\tconst raw = Buffer.from(cursor, 'base64').toString();\n\t\tconst commaIdx = raw.indexOf(',');\n\t\tif (commaIdx === -1) return null;\n\t\tconst createdAt = raw.slice(0, commaIdx);\n\t\tconst id = raw.slice(commaIdx + 1);\n\t\tif (!id || isNaN(Date.parse(createdAt))) return null;\n\t\treturn { createdAt, id };\n\t} catch {\n\t\treturn null;\n\t}\n}\n","import type { IStoreAdapter } from '@fonderie/store';\n\nimport type { IAuditEvent, IAuditQuery } from '../types';\nimport { decodeCursor } from '../dtos/audit';\n\nconst MAX_LIMIT = 200;\n\nexport class AuditEventModel {\n\tconstructor(private readonly store: IStoreAdapter) {}\n\n\tasync list(query: IAuditQuery): Promise<IAuditEvent[]> {\n\t\tconst limit = Math.min(query.limit ?? 50, MAX_LIMIT);\n\t\tconst params: unknown[] = [query.workspaceId];\n\t\tconst where: string[] = [`payload->>'workspaceId' = $1`];\n\n\t\tif (query.type) {\n\t\t\tparams.push(query.type);\n\t\t\twhere.push(`type = $${params.length}`);\n\t\t}\n\n\t\tif (query.actorId) {\n\t\t\tparams.push(query.actorId);\n\t\t\twhere.push(`payload->>'userId' = $${params.length}`);\n\t\t}\n\n\t\tif (query.from) {\n\t\t\tparams.push(query.from);\n\t\t\twhere.push(`created_at >= $${params.length}`);\n\t\t}\n\n\t\tif (query.to) {\n\t\t\tparams.push(query.to);\n\t\t\twhere.push(`created_at <= $${params.length}`);\n\t\t}\n\n\t\tif (query.cursor) {\n\t\t\tconst decoded = decodeCursor(query.cursor);\n\t\t\tif (decoded) {\n\t\t\t\tparams.push(decoded.createdAt, decoded.id);\n\t\t\t\twhere.push(\n\t\t\t\t\t`(created_at, id) < ($${params.length - 1}::timestamptz, $${params.length}::uuid)`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\tparams.push(limit);\n\n\t\treturn this.store.query<IAuditEvent>(\n\t\t\t`SELECT id, type, payload, meta, created_at as \"createdAt\"\n\t\t\t FROM   fonderie_events\n\t\t\t WHERE  ${where.join(' AND ')}\n\t\t\t ORDER  BY created_at DESC, id DESC\n\t\t\t LIMIT  $${params.length}`,\n\t\t\tparams,\n\t\t);\n\t}\n}\n","import type { IFonderieModule, IFonderieApp } from '@fonderie/core';\nimport type { IStoreAdapter } from '@fonderie/store';\n\nimport { buildAuditRoutes } from './routes';\n\nexport class AuditModule implements IFonderieModule {\n\treadonly name = '@fonderie/audit';\n\treadonly deps = ['@fonderie/auth', '@fonderie/workspaces'];\n\n\tconstructor(private readonly store: IStoreAdapter) {}\n\n\tinstall(app: IFonderieApp): void {\n\t\tfor (const [method, path, ...handlers] of buildAuditRoutes(this.store)) {\n\t\t\tapp.addRoute(method, path, ...handlers);\n\t\t}\n\t}\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,42 @@
+import { IFonderieModule, IFonderieApp } from '@fonderie/core';
+import { IStoreAdapter } from '@fonderie/store';
+
+declare class AuditModule implements IFonderieModule {
+    private readonly store;
+    readonly name = "@fonderie/audit";
+    readonly deps: string[];
+    constructor(store: IStoreAdapter);
+    install(app: IFonderieApp): void;
+}
+
+interface IAuditEvent {
+    id: string;
+    type: string;
+    payload: Record<string, unknown>;
+    meta: Record<string, unknown>;
+    createdAt: Date;
+}
+interface IAuditQuery {
+    workspaceId: string;
+    type?: string;
+    actorId?: string;
+    from?: Date;
+    to?: Date;
+    limit?: number;
+    cursor?: string;
+}
+
+interface IAuditEventDTO {
+    id: string;
+    type: string;
+    actorId: string | null;
+    requestId: string | null;
+    payload: Record<string, unknown>;
+    createdAt: string;
+}
+interface IAuditPageDTO {
+    events: IAuditEventDTO[];
+    nextCursor: string | null;
+}
+
+export { AuditModule, type IAuditEvent, type IAuditEventDTO, type IAuditPageDTO, type IAuditQuery };

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+import { IFonderieModule, IFonderieApp } from '@fonderie/core';
+import { IStoreAdapter } from '@fonderie/store';
+
+declare class AuditModule implements IFonderieModule {
+    private readonly store;
+    readonly name = "@fonderie/audit";
+    readonly deps: string[];
+    constructor(store: IStoreAdapter);
+    install(app: IFonderieApp): void;
+}
+
+interface IAuditEvent {
+    id: string;
+    type: string;
+    payload: Record<string, unknown>;
+    meta: Record<string, unknown>;
+    createdAt: Date;
+}
+interface IAuditQuery {
+    workspaceId: string;
+    type?: string;
+    actorId?: string;
+    from?: Date;
+    to?: Date;
+    limit?: number;
+    cursor?: string;
+}
+
+interface IAuditEventDTO {
+    id: string;
+    type: string;
+    actorId: string | null;
+    requestId: string | null;
+    payload: Record<string, unknown>;
+    createdAt: string;
+}
+interface IAuditPageDTO {
+    events: IAuditEventDTO[];
+    nextCursor: string | null;
+}
+
+export { AuditModule, type IAuditEvent, type IAuditEventDTO, type IAuditPageDTO, type IAuditQuery };

package/dist/index.js

@@ -0,0 +1,143 @@
+// src/routes.ts
+import { setApiResponse, HTTP } from "@fonderie/core";
+import { requireAuth } from "@fonderie/core/middlewares";
+
+// src/dtos/audit.ts
+function toAuditEventDTO(e) {
+  return {
+    id: e.id,
+    type: e.type,
+    actorId: e.payload["userId"] ?? null,
+    requestId: e.meta["requestId"] ?? null,
+    payload: e.payload,
+    createdAt: e.createdAt.toISOString()
+  };
+}
+function encodeCursor(createdAt, id) {
+  return Buffer.from(`${createdAt.toISOString()},${id}`).toString("base64");
+}
+function decodeCursor(cursor) {
+  try {
+    const raw = Buffer.from(cursor, "base64").toString();
+    const commaIdx = raw.indexOf(",");
+    if (commaIdx === -1) return null;
+    const createdAt = raw.slice(0, commaIdx);
+    const id = raw.slice(commaIdx + 1);
+    if (!id || isNaN(Date.parse(createdAt))) return null;
+    return { createdAt, id };
+  } catch {
+    return null;
+  }
+}
+
+// src/models/event.model.ts
+var MAX_LIMIT = 200;
+var AuditEventModel = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  async list(query) {
+    const limit = Math.min(query.limit ?? 50, MAX_LIMIT);
+    const params = [query.workspaceId];
+    const where = [`payload->>'workspaceId' = $1`];
+    if (query.type) {
+      params.push(query.type);
+      where.push(`type = $${params.length}`);
+    }
+    if (query.actorId) {
+      params.push(query.actorId);
+      where.push(`payload->>'userId' = $${params.length}`);
+    }
+    if (query.from) {
+      params.push(query.from);
+      where.push(`created_at >= $${params.length}`);
+    }
+    if (query.to) {
+      params.push(query.to);
+      where.push(`created_at <= $${params.length}`);
+    }
+    if (query.cursor) {
+      const decoded = decodeCursor(query.cursor);
+      if (decoded) {
+        params.push(decoded.createdAt, decoded.id);
+        where.push(
+          `(created_at, id) < ($${params.length - 1}::timestamptz, $${params.length}::uuid)`
+        );
+      }
+    }
+    params.push(limit);
+    return this.store.query(
+      `SELECT id, type, payload, meta, created_at as "createdAt"
+			 FROM   fonderie_events
+			 WHERE  ${where.join(" AND ")}
+			 ORDER  BY created_at DESC, id DESC
+			 LIMIT  $${params.length}`,
+      params
+    );
+  }
+};
+
+// src/routes.ts
+function buildAuditRoutes(store) {
+  return [
+    [
+      "GET",
+      "/audit",
+      requireAuth,
+      async (ctx) => {
+        if (!ctx.workspace)
+          return setApiResponse(
+            HTTP.UNPROCESSABLE,
+            "MISSING_WORKSPACE",
+            "Workspace context required"
+          );
+        const url = new URL(ctx.request.url);
+        const params = url.searchParams;
+        const limit = Math.min(Number(params.get("limit") ?? 50), 200);
+        const type = params.get("type") ?? void 0;
+        const actor = params.get("actorId") ?? void 0;
+        const from = params.get("from") ? new Date(params.get("from")) : void 0;
+        const to = params.get("to") ? new Date(params.get("to")) : void 0;
+        const cursor = params.get("cursor") ?? void 0;
+        const query = {
+          workspaceId: ctx.workspace.id,
+          limit: limit + 1
+        };
+        if (type) query.type = type;
+        if (actor) query.actorId = actor;
+        if (from) query.from = from;
+        if (to) query.to = to;
+        if (cursor) query.cursor = cursor;
+        const events = await new AuditEventModel(store).list(query);
+        const hasMore = events.length > limit;
+        const page = hasMore ? events.slice(0, limit) : events;
+        const lastEvent = page[page.length - 1];
+        const nextCursor = hasMore && lastEvent ? encodeCursor(lastEvent.createdAt, lastEvent.id) : null;
+        return setApiResponse(HTTP.OK, "AUDIT_FETCHED", "Audit events retrieved.", {
+          events: page.map(toAuditEventDTO),
+          nextCursor
+        });
+      }
+    ]
+  ];
+}
+
+// src/module.ts
+var AuditModule = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  name = "@fonderie/audit";
+  deps = ["@fonderie/auth", "@fonderie/workspaces"];
+  install(app) {
+    for (const [method, path, ...handlers] of buildAuditRoutes(this.store)) {
+      app.addRoute(method, path, ...handlers);
+    }
+  }
+};
+export {
+  AuditModule
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/routes.ts","../src/dtos/audit.ts","../src/models/event.model.ts","../src/module.ts"],"sourcesContent":["import type { Middleware } from '@fonderie/core';\nimport { setApiResponse, HTTP } from '@fonderie/core';\nimport { requireAuth } from '@fonderie/core/middlewares';\nimport type { IStoreAdapter } from '@fonderie/store';\n\nimport { AuditEventModel } from './models/event.model';\nimport { toAuditEventDTO, encodeCursor } from './dtos/audit';\n\ntype Route = [string, string, ...Middleware[]];\n\nexport function buildAuditRoutes(store: IStoreAdapter): Route[] {\n\treturn [\n\t\t[\n\t\t\t'GET',\n\t\t\t'/audit',\n\t\t\trequireAuth,\n\t\t\tasync (ctx) => {\n\t\t\t\tif (!ctx.workspace)\n\t\t\t\t\treturn setApiResponse(\n\t\t\t\t\t\tHTTP.UNPROCESSABLE,\n\t\t\t\t\t\t'MISSING_WORKSPACE',\n\t\t\t\t\t\t'Workspace context required',\n\t\t\t\t\t);\n\n\t\t\t\tconst url = new URL(ctx.request.url);\n\t\t\t\tconst params = url.searchParams;\n\n\t\t\t\tconst limit = Math.min(Number(params.get('limit') ?? 50), 200);\n\t\t\t\tconst type = params.get('type') ?? undefined;\n\t\t\t\tconst actor = params.get('actorId') ?? undefined;\n\t\t\t\tconst from = params.get('from') ? new Date(params.get('from')!) : undefined;\n\t\t\t\tconst to = params.get('to') ? new Date(params.get('to')!) : undefined;\n\t\t\t\tconst cursor = params.get('cursor') ?? undefined;\n\n\t\t\t\tconst query: Parameters<AuditEventModel['list']>[0] = {\n\t\t\t\t\tworkspaceId: ctx.workspace.id,\n\t\t\t\t\tlimit: limit + 1,\n\t\t\t\t};\n\t\t\t\tif (type) query.type = type;\n\t\t\t\tif (actor) query.actorId = actor;\n\t\t\t\tif (from) query.from = from;\n\t\t\t\tif (to) query.to = to;\n\t\t\t\tif (cursor) query.cursor = cursor;\n\n\t\t\t\tconst events = await new AuditEventModel(store).list(query);\n\n\t\t\t\t// fetch one extra to determine if there's a next page\n\t\t\t\tconst hasMore = events.length > limit;\n\t\t\t\tconst page = hasMore ? events.slice(0, limit) : events;\n\t\t\t\tconst lastEvent = page[page.length - 1];\n\t\t\t\tconst nextCursor =\n\t\t\t\t\thasMore && lastEvent ? encodeCursor(lastEvent.createdAt, lastEvent.id) : null;\n\n\t\t\t\treturn setApiResponse(HTTP.OK, 'AUDIT_FETCHED', 'Audit events retrieved.', {\n\t\t\t\t\tevents: page.map(toAuditEventDTO),\n\t\t\t\t\tnextCursor,\n\t\t\t\t});\n\t\t\t},\n\t\t],\n\t];\n}\n","import type { IAuditEvent } from '../types';\n\nexport interface IAuditEventDTO {\n\tid: string;\n\ttype: string;\n\tactorId: string | null;\n\trequestId: string | null;\n\tpayload: Record<string, unknown>;\n\tcreatedAt: string;\n}\n\nexport interface IAuditPageDTO {\n\tevents: IAuditEventDTO[];\n\tnextCursor: string | null;\n}\n\nexport function toAuditEventDTO(e: IAuditEvent): IAuditEventDTO {\n\treturn {\n\t\tid: e.id,\n\t\ttype: e.type,\n\t\tactorId: (e.payload['userId'] as string | undefined) ?? null,\n\t\trequestId: (e.meta['requestId'] as string | undefined) ?? null,\n\t\tpayload: e.payload,\n\t\tcreatedAt: e.createdAt.toISOString(),\n\t};\n}\n\nexport function encodeCursor(createdAt: Date, id: string): string {\n\treturn Buffer.from(`${createdAt.toISOString()},${id}`).toString('base64');\n}\n\nexport function decodeCursor(cursor: string): { createdAt: string; id: string } | null {\n\ttry {\n\t\tconst raw = Buffer.from(cursor, 'base64').toString();\n\t\tconst commaIdx = raw.indexOf(',');\n\t\tif (commaIdx === -1) return null;\n\t\tconst createdAt = raw.slice(0, commaIdx);\n\t\tconst id = raw.slice(commaIdx + 1);\n\t\tif (!id || isNaN(Date.parse(createdAt))) return null;\n\t\treturn { createdAt, id };\n\t} catch {\n\t\treturn null;\n\t}\n}\n","import type { IStoreAdapter } from '@fonderie/store';\n\nimport type { IAuditEvent, IAuditQuery } from '../types';\nimport { decodeCursor } from '../dtos/audit';\n\nconst MAX_LIMIT = 200;\n\nexport class AuditEventModel {\n\tconstructor(private readonly store: IStoreAdapter) {}\n\n\tasync list(query: IAuditQuery): Promise<IAuditEvent[]> {\n\t\tconst limit = Math.min(query.limit ?? 50, MAX_LIMIT);\n\t\tconst params: unknown[] = [query.workspaceId];\n\t\tconst where: string[] = [`payload->>'workspaceId' = $1`];\n\n\t\tif (query.type) {\n\t\t\tparams.push(query.type);\n\t\t\twhere.push(`type = $${params.length}`);\n\t\t}\n\n\t\tif (query.actorId) {\n\t\t\tparams.push(query.actorId);\n\t\t\twhere.push(`payload->>'userId' = $${params.length}`);\n\t\t}\n\n\t\tif (query.from) {\n\t\t\tparams.push(query.from);\n\t\t\twhere.push(`created_at >= $${params.length}`);\n\t\t}\n\n\t\tif (query.to) {\n\t\t\tparams.push(query.to);\n\t\t\twhere.push(`created_at <= $${params.length}`);\n\t\t}\n\n\t\tif (query.cursor) {\n\t\t\tconst decoded = decodeCursor(query.cursor);\n\t\t\tif (decoded) {\n\t\t\t\tparams.push(decoded.createdAt, decoded.id);\n\t\t\t\twhere.push(\n\t\t\t\t\t`(created_at, id) < ($${params.length - 1}::timestamptz, $${params.length}::uuid)`,\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\tparams.push(limit);\n\n\t\treturn this.store.query<IAuditEvent>(\n\t\t\t`SELECT id, type, payload, meta, created_at as \"createdAt\"\n\t\t\t FROM   fonderie_events\n\t\t\t WHERE  ${where.join(' AND ')}\n\t\t\t ORDER  BY created_at DESC, id DESC\n\t\t\t LIMIT  $${params.length}`,\n\t\t\tparams,\n\t\t);\n\t}\n}\n","import type { IFonderieModule, IFonderieApp } from '@fonderie/core';\nimport type { IStoreAdapter } from '@fonderie/store';\n\nimport { buildAuditRoutes } from './routes';\n\nexport class AuditModule implements IFonderieModule {\n\treadonly name = '@fonderie/audit';\n\treadonly deps = ['@fonderie/auth', '@fonderie/workspaces'];\n\n\tconstructor(private readonly store: IStoreAdapter) {}\n\n\tinstall(app: IFonderieApp): void {\n\t\tfor (const [method, path, ...handlers] of buildAuditRoutes(this.store)) {\n\t\t\tapp.addRoute(method, path, ...handlers);\n\t\t}\n\t}\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,65 @@
+{
+	"name": "@fonderie/audit",
+	"version": "1.0.0",
+	"description": "Workspace-scoped audit log — query fonderie_events for a human-readable activity trail.",
+	"keywords": [
+		"fonderie-js",
+		"audit",
+		"events",
+		"saas",
+		"typescript"
+	],
+	"license": "MIT",
+	"type": "module",
+	"engines": {
+		"node": ">=20"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsup",
+		"dev": "tsup --watch",
+		"typecheck": "tsc --noEmit",
+		"test": "tsx --test src/__tests__/*.test.ts",
+		"lint": "biome lint src",
+		"format": "biome format --write src",
+		"check": "biome check --write src"
+	},
+	"peerDependencies": {
+		"@fonderie/core": "^0.1.0",
+		"@fonderie/store": "^0.1.0"
+	},
+	"devDependencies": {
+		"@fonderie/core": "../core",
+		"@fonderie/store": "../store",
+		"@types/node": "^25.6.0",
+		"tsup": "^8.5.1",
+		"tsx": "^4.21.0",
+		"typescript": "^6.0.3"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"dist",
+		"LICENSE",
+		"README.md"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/fonderie-js/sdk.git",
+		"directory": "packages/audit"
+	},
+	"homepage": "https://github.com/fonderie-js/sdk/tree/main/packages/audit#readme",
+	"bugs": {
+		"url": "https://github.com/fonderie-js/sdk/issues"
+	}
+}