@nebutra/audit 0.1.0 → 0.1.2

package/dist/providers/clickhouse.d.ts

@@ -0,0 +1,37 @@
+import type { AuditEvent, AuditQueryFilter } from "../schema";
+import type { AuditProvider } from "./types";
+export interface ClickHouseAuditConfig {
+    url: string;
+    username?: string;
+    password?: string;
+    database?: string;
+    table?: string;
+}
+interface ClickHouseClientLike {
+    insert(args: {
+        table: string;
+        values: unknown[];
+        format: string;
+    }): Promise<unknown>;
+    query(args: {
+        query: string;
+        format: string;
+        query_params?: Record<string, unknown>;
+    }): Promise<{
+        json: <T>() => Promise<{
+            data: T[];
+        }>;
+    }>;
+    close(): Promise<void>;
+}
+export declare class ClickHouseAuditProvider implements AuditProvider {
+    private readonly client;
+    readonly type: "clickhouse";
+    private readonly table;
+    constructor(client: ClickHouseClientLike, config: ClickHouseAuditConfig);
+    log(event: AuditEvent): Promise<void>;
+    query(filter: AuditQueryFilter): Promise<AuditEvent[]>;
+    close(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=clickhouse.d.ts.map

package/dist/providers/clickhouse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clickhouse.d.ts","sourceRoot":"","sources":["../../src/providers/clickhouse.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,UAAU,oBAAoB;IAC5B,MAAM,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrF,KAAK,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,OAAO,CAAC;QAC9F,IAAI,EAAE,CAAC,CAAC,OAAO,OAAO,CAAC;YAAE,IAAI,EAAE,CAAC,EAAE,CAAA;SAAE,CAAC,CAAC;KACvC,CAAC,CAAC;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,qBAAa,uBAAwB,YAAW,aAAa;IAIzD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHzB,QAAQ,CAAC,IAAI,EAAG,YAAY,CAAU;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEZ,MAAM,EAAE,oBAAoB,EAC7C,MAAM,EAAE,qBAAqB;IAKzB,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BrC,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IA+BtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/providers/clickhouse.js

@@ -0,0 +1,114 @@
+// =============================================================================
+// ClickHouseAuditProvider — high-volume analytics-grade audit storage
+// =============================================================================
+// Optional provider for customers running ClickHouse alongside @nebutra/metering.
+// Activates when both `CLICKHOUSE_URL` is set and `AUDIT_USE_CLICKHOUSE=true`.
+//
+// The client is loaded lazily so installations that don't need ClickHouse can
+// skip pulling `@clickhouse/client` into the runtime bundle.
+// =============================================================================
+export class ClickHouseAuditProvider {
+    client;
+    type = "clickhouse";
+    table;
+    constructor(client, config) {
+        this.client = client;
+        this.table = config.table ?? "audit_logs";
+    }
+    async log(event) {
+        await this.client.insert({
+            table: this.table,
+            format: "JSONEachRow",
+            values: [
+                {
+                    id: event.id,
+                    timestamp: event.timestamp,
+                    tenant_id: event.tenantId,
+                    actor_id: event.actor.id,
+                    actor_type: event.actor.type,
+                    actor_email: event.actor.email ?? null,
+                    action: event.action,
+                    resource_type: event.resource.type,
+                    resource_id: event.resource.id,
+                    resource_name: event.resource.name ?? null,
+                    outcome: event.outcome,
+                    severity: event.severity,
+                    ip: event.context?.ip ?? null,
+                    user_agent: event.context?.userAgent ?? null,
+                    request_id: event.context?.requestId ?? null,
+                    session_id: event.context?.sessionId ?? null,
+                    changes_before: event.changes?.before ?? null,
+                    changes_after: event.changes?.after ?? null,
+                    metadata: event.metadata ?? null,
+                },
+            ],
+        });
+    }
+    async query(filter) {
+        // ClickHouse query support is intentionally limited — it's optimized for
+        // ingest, not point lookups. Most query workloads should hit Postgres.
+        const where = [];
+        const params = {};
+        if (filter.tenantId) {
+            where.push("tenant_id = {tenantId:String}");
+            params.tenantId = filter.tenantId;
+        }
+        if (filter.actorId) {
+            where.push("actor_id = {actorId:String}");
+            params.actorId = filter.actorId;
+        }
+        if (filter.action) {
+            where.push("action = {action:String}");
+            params.action = filter.action;
+        }
+        const whereClause = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+        const limit = filter.limit ?? 100;
+        const offset = filter.offset ?? 0;
+        const result = await this.client.query({
+            query: `SELECT * FROM ${this.table} ${whereClause} ORDER BY timestamp DESC LIMIT ${limit} OFFSET ${offset}`,
+            format: "JSONEachRow",
+            query_params: params,
+        });
+        const { data } = await result.json();
+        return data.map(rowToEvent);
+    }
+    async close() {
+        await this.client.close();
+    }
+}
+function rowToEvent(row) {
+    const get = (key) => row[key];
+    return {
+        id: String(row.id),
+        timestamp: String(row.timestamp),
+        actor: {
+            id: String(row.actor_id),
+            type: (row.actor_type ?? "system"),
+            ...(row.actor_email ? { email: String(row.actor_email) } : {}),
+        },
+        tenantId: String(row.tenant_id),
+        action: String(row.action),
+        resource: {
+            type: String(row.resource_type),
+            id: String(row.resource_id),
+            ...(row.resource_name ? { name: String(row.resource_name) } : {}),
+        },
+        outcome: (row.outcome ?? "success"),
+        severity: (row.severity ?? "info"),
+        context: {
+            ...(row.ip ? { ip: String(row.ip) } : {}),
+            ...(row.user_agent ? { userAgent: String(row.user_agent) } : {}),
+            ...(row.request_id ? { requestId: String(row.request_id) } : {}),
+            ...(row.session_id ? { sessionId: String(row.session_id) } : {}),
+        },
+        ...(get("changes_before") && get("changes_after")
+            ? {
+                changes: {
+                    before: get("changes_before"),
+                    after: get("changes_after"),
+                },
+            }
+            : {}),
+        ...(get("metadata") ? { metadata: get("metadata") } : {}),
+    };
+}

package/dist/providers/index.d.ts

@@ -0,0 +1,22 @@
+import { type PrismaAuditDelegate } from "./postgres";
+import type { AuditProvider, AuditProviderType } from "./types";
+export { ClickHouseAuditProvider } from "./clickhouse";
+export { MemoryAuditProvider } from "./memory";
+export type { PrismaAuditDelegate } from "./postgres";
+export { PostgresAuditProvider } from "./postgres";
+export type { AuditProvider, AuditProviderType } from "./types";
+export interface AuditFactoryConfig {
+    /** Force a specific provider type. Useful for tests. */
+    provider?: AuditProviderType;
+    /** Required for the postgres provider. Provide the Prisma client. */
+    prisma?: PrismaAuditDelegate;
+}
+/**
+ * Resolve the configured audit provider. Cached after the first call so the
+ * provider lifecycle matches the process lifecycle.
+ */
+export declare function getAuditProvider(config?: AuditFactoryConfig): Promise<AuditProvider>;
+export declare function createAuditProvider(config?: AuditFactoryConfig): Promise<AuditProvider>;
+/** @internal — exposed for tests so they can reset the singleton. */
+export declare function __resetAuditProviderForTests(): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAyB,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEhE,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/C,YAAY,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACnD,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEhE,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,qEAAqE;IACrE,MAAM,CAAC,EAAE,mBAAmB,CAAC;CAC9B;AAgBD;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,GAAE,kBAAuB,GAAG,OAAO,CAAC,aAAa,CAAC,CAI9F;AAED,wBAAsB,mBAAmB,CAAC,MAAM,GAAE,kBAAuB,GAAG,OAAO,CAAC,aAAa,CAAC,CAkDjG;AAED,qEAAqE;AACrE,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD"}

package/dist/providers/index.js

@@ -0,0 +1,84 @@
+// =============================================================================
+// Audit provider factory — auto-detects the right backend from the environment
+// =============================================================================
+// Detection precedence (matches @nebutra/queue, @nebutra/search):
+//   1. AUDIT_PROVIDER env var               → explicit override
+//   2. CLICKHOUSE_URL + AUDIT_USE_CLICKHOUSE=true → clickhouse
+//   3. DATABASE_URL                          → postgres
+//   4. (fallback)                            → memory (dev/test only)
+// =============================================================================
+import { logger } from "@nebutra/logger";
+import { MemoryAuditProvider } from "./memory";
+import { PostgresAuditProvider } from "./postgres";
+export { ClickHouseAuditProvider } from "./clickhouse";
+export { MemoryAuditProvider } from "./memory";
+export { PostgresAuditProvider } from "./postgres";
+function detectProviderType() {
+    const explicit = process.env.AUDIT_PROVIDER?.trim();
+    if (explicit && ["memory", "postgres", "clickhouse"].includes(explicit)) {
+        return explicit;
+    }
+    if (process.env.CLICKHOUSE_URL && process.env.AUDIT_USE_CLICKHOUSE === "true") {
+        return "clickhouse";
+    }
+    if (process.env.DATABASE_URL)
+        return "postgres";
+    return "memory";
+}
+let cachedProvider = null;
+/**
+ * Resolve the configured audit provider. Cached after the first call so the
+ * provider lifecycle matches the process lifecycle.
+ */
+export async function getAuditProvider(config = {}) {
+    if (cachedProvider)
+        return cachedProvider;
+    cachedProvider = await createAuditProvider(config);
+    return cachedProvider;
+}
+export async function createAuditProvider(config = {}) {
+    const type = config.provider ?? detectProviderType();
+    switch (type) {
+        case "memory":
+            if (process.env.NODE_ENV === "production") {
+                logger.warn("[audit] Falling back to in-memory provider in production — events will be lost. Configure DATABASE_URL or AUDIT_PROVIDER.");
+            }
+            return new MemoryAuditProvider();
+        case "postgres": {
+            let delegate = config.prisma;
+            if (!delegate) {
+                try {
+                    // Lazy import — keeps the package usable in test environments
+                    // that mock @nebutra/db.
+                    const dbModule = (await import("@nebutra/db"));
+                    if (typeof dbModule.getSystemDb === "function") {
+                        delegate = dbModule.getSystemDb();
+                    }
+                }
+                catch (error) {
+                    logger.warn("[audit] Could not load @nebutra/db — falling back to memory provider", {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                    return new MemoryAuditProvider();
+                }
+            }
+            if (!delegate) {
+                logger.warn("[audit] Postgres provider requested but no Prisma client available");
+                return new MemoryAuditProvider();
+            }
+            return new PostgresAuditProvider(delegate);
+        }
+        case "clickhouse":
+            // ClickHouse provider requires explicit construction by the host app
+            // because it owns the @clickhouse/client lifecycle. Fall back to the
+            // postgres provider (or memory) if no client is supplied.
+            logger.warn("[audit] ClickHouse provider must be constructed explicitly via createClickHouseAuditProvider(). Falling back to postgres.");
+            return createAuditProvider({ ...config, provider: "postgres" });
+        default:
+            return new MemoryAuditProvider();
+    }
+}
+/** @internal — exposed for tests so they can reset the singleton. */
+export function __resetAuditProviderForTests() {
+    cachedProvider = null;
+}

package/dist/providers/memory.d.ts

@@ -0,0 +1,12 @@
+import type { AuditEvent, AuditQueryFilter } from "../schema";
+import type { AuditProvider } from "./types";
+export declare class MemoryAuditProvider implements AuditProvider {
+    readonly type: "memory";
+    private readonly events;
+    log(event: AuditEvent): Promise<void>;
+    query(filter: AuditQueryFilter): Promise<AuditEvent[]>;
+    close(): Promise<void>;
+    /** @internal — exposed for tests so they can assert append-only behavior. */
+    __all(): readonly AuditEvent[];
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/providers/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/providers/memory.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,qBAAa,mBAAoB,YAAW,aAAa;IACvD,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAErC,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAKrC,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IA0BtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B,6EAA6E;IAC7E,KAAK,IAAI,SAAS,UAAU,EAAE;CAG/B"}

package/dist/providers/memory.js

@@ -0,0 +1,52 @@
+// =============================================================================
+// MemoryProvider — in-process audit log buffer
+// =============================================================================
+// For local development, unit tests, and last-resort fallback when no
+// production backend is configured. NEVER use in production: events are lost
+// on process exit and there is no retention enforcement.
+// =============================================================================
+export class MemoryAuditProvider {
+    type = "memory";
+    events = [];
+    async log(event) {
+        // Append-only: never replace, never reorder.
+        this.events.push(event);
+    }
+    async query(filter) {
+        const limit = filter.limit ?? 100;
+        const offset = filter.offset ?? 0;
+        const matches = this.events.filter((e) => {
+            if (filter.tenantId && e.tenantId !== filter.tenantId)
+                return false;
+            if (filter.actorId && e.actor.id !== filter.actorId)
+                return false;
+            if (filter.action && e.action !== filter.action)
+                return false;
+            if (filter.resourceType && e.resource.type !== filter.resourceType)
+                return false;
+            if (filter.resourceId && e.resource.id !== filter.resourceId)
+                return false;
+            if (filter.outcome && e.outcome !== filter.outcome)
+                return false;
+            if (filter.startDate && new Date(e.timestamp) < filter.startDate)
+                return false;
+            if (filter.endDate && new Date(e.timestamp) > filter.endDate)
+                return false;
+            return true;
+        });
+        // Sort by timestamp descending (most recent first).
+        const sorted = [...matches].sort((a, b) => {
+            const ta = new Date(a.timestamp).getTime();
+            const tb = new Date(b.timestamp).getTime();
+            return tb - ta;
+        });
+        return sorted.slice(offset, offset + limit);
+    }
+    async close() {
+        // No-op for the memory provider. Buffer is GC'd with the instance.
+    }
+    /** @internal — exposed for tests so they can assert append-only behavior. */
+    __all() {
+        return this.events;
+    }
+}

package/dist/providers/postgres.d.ts

@@ -0,0 +1,19 @@
+import type { AuditEvent, AuditQueryFilter } from "../schema";
+import type { AuditProvider } from "./types";
+export interface PrismaAuditDelegate {
+    auditLog: {
+        create: (args: {
+            data: Record<string, unknown>;
+        }) => Promise<unknown>;
+        findMany: (args: Record<string, unknown>) => Promise<unknown[]>;
+    };
+}
+export declare class PostgresAuditProvider implements AuditProvider {
+    private readonly db;
+    readonly type: "postgres";
+    constructor(db: PrismaAuditDelegate);
+    log(event: AuditEvent): Promise<void>;
+    query(filter: AuditQueryFilter): Promise<AuditEvent[]>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=postgres.d.ts.map

package/dist/providers/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/providers/postgres.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAa,UAAU,EAAE,gBAAgB,EAAW,MAAM,WAAW,CAAC;AAClF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAI7C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE;QACR,MAAM,EAAE,CAAC,IAAI,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;QACtE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;KACjE,CAAC;CACH;AAwBD,qBAAa,qBAAsB,YAAW,aAAa;IAE7C,OAAO,CAAC,QAAQ,CAAC,EAAE;IAD/B,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;gBACP,EAAE,EAAE,mBAAmB;IAE9C,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BrC,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAyBtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/providers/postgres.js

@@ -0,0 +1,138 @@
+// =============================================================================
+// PostgresAuditProvider — production-default Prisma-backed storage
+// =============================================================================
+// Persists audit events into the existing `audit_logs` table defined in
+// `packages/platform/db/prisma/schema.prisma`. Field mapping:
+//
+//   AuditEvent (schema.ts)         → Prisma AuditLog model
+//   ─────────────────────────────────────────────────────────────────────────
+//   id                             → id
+//   timestamp                      → createdAt
+//   actor.id                       → userId
+//   actor.type                     → actorType
+//   tenantId                       → organizationId
+//   action                         → action
+//   resource.type                  → entityType
+//   resource.id                    → entityId
+//   resource.name                  → metadata.resourceName
+//   outcome                        → outcome
+//   severity                       → metadata.severity
+//   context.ip                     → ipAddress
+//   context.userAgent              → userAgent
+//   context.requestId/sessionId/geo → metadata.context
+//   changes.before                 → oldValue
+//   changes.after                  → newValue
+//   metadata                       → metadata.userMetadata
+//
+// The audit_logs table is APPEND-ONLY — see MIGRATION.md for the SQL that
+// revokes UPDATE/DELETE from the application role.
+// =============================================================================
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+export class PostgresAuditProvider {
+    db;
+    type = "postgres";
+    constructor(db) {
+        this.db = db;
+    }
+    async log(event) {
+        const metadataBlob = {
+            severity: event.severity,
+        };
+        if (event.resource.name)
+            metadataBlob.resourceName = event.resource.name;
+        if (event.context && Object.keys(event.context).length > 0) {
+            metadataBlob.context = event.context;
+        }
+        if (event.metadata)
+            metadataBlob.userMetadata = event.metadata;
+        await this.db.auditLog.create({
+            data: {
+                id: event.id,
+                organizationId: event.tenantId,
+                userId: event.actor.id,
+                actorType: event.actor.type,
+                action: event.action,
+                outcome: event.outcome,
+                entityType: event.resource.type,
+                entityId: event.resource.id,
+                oldValue: event.changes?.before ?? null,
+                newValue: event.changes?.after ?? null,
+                ipAddress: event.context?.ip ?? null,
+                userAgent: event.context?.userAgent ?? null,
+                metadata: metadataBlob,
+                createdAt: new Date(event.timestamp),
+            },
+        });
+    }
+    async query(filter) {
+        const where = {};
+        if (filter.tenantId)
+            where.organizationId = filter.tenantId;
+        if (filter.actorId)
+            where.userId = filter.actorId;
+        if (filter.action)
+            where.action = filter.action;
+        if (filter.resourceType)
+            where.entityType = filter.resourceType;
+        if (filter.resourceId)
+            where.entityId = filter.resourceId;
+        if (filter.outcome)
+            where.outcome = filter.outcome;
+        if (filter.startDate || filter.endDate) {
+            const range = {};
+            if (filter.startDate)
+                range.gte = filter.startDate;
+            if (filter.endDate)
+                range.lte = filter.endDate;
+            where.createdAt = range;
+        }
+        const rows = (await this.db.auditLog.findMany({
+            where,
+            orderBy: { createdAt: "desc" },
+            take: filter.limit ?? 100,
+            skip: filter.offset ?? 0,
+        }));
+        return rows.map(rowToEvent);
+    }
+    async close() {
+        // The Prisma client lifecycle is owned by @nebutra/db — do NOT disconnect
+        // here. Closing a shared client would break unrelated callers.
+    }
+}
+function rowToEvent(row) {
+    const meta = isObject(row.metadata) ? row.metadata : {};
+    const severity = (typeof meta.severity === "string" ? meta.severity : "info");
+    const ctx = isObject(meta.context) ? meta.context : {};
+    const userMeta = isObject(meta.userMetadata) ? meta.userMetadata : undefined;
+    const event = {
+        id: row.id,
+        timestamp: row.createdAt.toISOString(),
+        actor: {
+            id: row.userId ?? "unknown",
+            type: (row.actorType ?? "system"),
+        },
+        tenantId: row.organizationId ?? "unknown",
+        action: row.action,
+        resource: {
+            type: row.entityType,
+            id: row.entityId ?? "unknown",
+            ...(typeof meta.resourceName === "string" ? { name: meta.resourceName } : {}),
+        },
+        outcome: (row.outcome ?? "success"),
+        severity,
+        context: {
+            ...(row.ipAddress ? { ip: row.ipAddress } : {}),
+            ...(row.userAgent ? { userAgent: row.userAgent } : {}),
+            ...(typeof ctx.requestId === "string" ? { requestId: ctx.requestId } : {}),
+            ...(typeof ctx.sessionId === "string" ? { sessionId: ctx.sessionId } : {}),
+            ...(isObject(ctx.geo) ? { geo: ctx.geo } : {}),
+        },
+        ...(isObject(row.oldValue) && isObject(row.newValue)
+            ? { changes: { before: row.oldValue, after: row.newValue } }
+            : {}),
+        ...(userMeta ? { metadata: userMeta } : {}),
+    };
+    return event;
+}

package/dist/providers/types.d.ts

@@ -0,0 +1,14 @@
+import type { AuditEvent, AuditQueryFilter } from "../schema";
+export type AuditProviderType = "memory" | "postgres" | "clickhouse";
+export interface AuditProvider {
+    readonly type: AuditProviderType;
+    /** Append an event to the immutable audit log. MUST NOT throw on transient
+     *  failures — log + swallow to keep the caller's path resilient. */
+    log(event: AuditEvent): Promise<void>;
+    /** Query past events. Tenant-scoped queries are STRONGLY RECOMMENDED — the
+     *  caller is responsible for passing `tenantId` to honor multi-tenancy. */
+    query(filter: AuditQueryFilter): Promise<AuditEvent[]>;
+    /** Release any held connections / flush in-flight buffers. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/providers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/providers/types.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE9D,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,UAAU,GAAG,YAAY,CAAC;AAErE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC;wEACoE;IACpE,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC;+EAC2E;IAC3E,KAAK,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;IACvD,8DAA8D;IAC9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/providers/types.js

@@ -0,0 +1,7 @@
+// =============================================================================
+// AuditProvider interface
+// =============================================================================
+// Provider-agnostic abstraction matching the @nebutra/queue and @nebutra/search
+// patterns: customers swap backends via env vars without changing app code.
+// =============================================================================
+export {};