@usebetterdev/audit-core 0.4.0-beta.4 → 0.5.0

package/dist/index.d.ts

@@ -104,7 +104,39 @@ declare class AuditQueryBuilder {
     list(): Promise<AuditQueryResult>;
 }
 
+/** Options for `createExportResponse()`. */
+interface ExportResponseOptions {
+    /** Output format. Default: `"csv"`. */
+    format?: "csv" | "json";
+    /** JSON output style. Default: `"ndjson"`. */
+    jsonStyle?: "ndjson" | "array";
+    /** Rows per database round-trip. */
+    batchSize?: number;
+    /** CSV delimiter character. */
+    csvDelimiter?: string;
+    /** Optional query builder to filter exported entries. */
+    query?: AuditQueryBuilder;
+    /** Custom filename stem (without extension). Default: `"audit-export-YYYY-MM-DD"`. */
+    filename?: string;
+}
+/**
+ * Create a streaming `Response` from the audit export engine.
+ *
+ * Uses `TransformStream` + `TextEncoderStream` to bridge the string-based
+ * `runExport()` output to a binary `ReadableStream` suitable for `new Response()`.
+ * The export runs asynchronously — the Response is returned immediately so the
+ * first byte can arrive before all rows are read.
+ */
+declare function createExportResponse(executor: QueryExecutor, options?: ExportResponseOptions): Response;
+
 type AuditOperation = "INSERT" | "UPDATE" | "DELETE";
+/** Retention policy controlling automatic and CLI-driven purge of old audit logs. */
+interface RetentionPolicy {
+    /** Purge entries older than this many days. Must be a positive integer. */
+    days: number;
+    /** When set, only purge logs for these specific tables. */
+    tables?: string[];
+}
 type AuditSeverity = "low" | "medium" | "high" | "critical";
 /** A single audit log entry as stored in the database. */
 interface AuditLog {
@@ -225,6 +257,8 @@ interface BetterAuditConfig {
     onError?: (error: unknown) => void;
     /** Console integration. Pass a BetterConsoleInstance to register audit dashboard endpoints. */
     console?: ConsoleRegistration;
+    /** Optional retention policy. When set, enables purge CLI and auto-purge scheduler. */
+    retention?: RetentionPolicy;
 }
 /** Input to a manual captureLog call. Context fields override the current AsyncLocalStorage scope. */
 interface CaptureLogInput {
@@ -288,10 +322,50 @@ interface EnrichmentConfig {
      */
     include?: string[];
 }
+/** Options for `audit.export()`. */
+interface ExportOptions {
+    /** Output format. */
+    format: "csv" | "json";
+    /** Optional query builder to filter exported entries. */
+    query?: AuditQueryBuilder;
+    /**
+     * Output target.
+     * - `WritableStream<string>`: WHATWG Web Streams API (Node 18+, Bun, Deno)
+     * - `'string'`: buffer in memory and return the full output via `ExportResult`
+     */
+    output: WritableStream<string> | "string";
+    /** Rows per database round-trip. Default 500. */
+    batchSize?: number;
+    /** CSV delimiter character (must be exactly one character). Default `','`. */
+    csvDelimiter?: string;
+    /** JSON output style. `'ndjson'` (default) for streaming, `'array'` for pretty-printed. */
+    jsonStyle?: "ndjson" | "array";
+}
+/** Result returned when `audit.export()` completes. */
+interface ExportResult {
+    rowCount: number;
+    /** Present only when `output` is `'string'`. */
+    data?: string;
+}
 interface BetterAuditInstance {
     captureLog(input: CaptureLogInput): Promise<void>;
     /** Returns a fluent query builder. Requires `queryAdapter` in config. */
     query(): AuditQueryBuilder;
+    /**
+     * Export audit log entries as CSV or JSON.
+     *
+     * Streams rows in batches via cursor pagination so memory stays flat
+     * regardless of export size. Requires `queryLogs` on the database adapter.
+     */
+    export(options: ExportOptions): Promise<ExportResult>;
+    /**
+     * Create a streaming HTTP `Response` for downloading audit logs.
+     *
+     * Returns a standard `Response` with correct Content-Type, Content-Disposition,
+     * and Cache-Control headers. The body is a streaming `ReadableStream` backed
+     * by the export engine. Requires `queryLogs` on the database adapter.
+     */
+    exportResponse(options?: ExportResponseOptions): Response;
     withContext<T>(context: AuditContext, fn: () => Promise<T>): Promise<T>;
     /**
      * Register an enrichment config for a table/operation pair.
@@ -304,6 +378,8 @@ interface BetterAuditInstance {
     onBeforeLog(hook: BeforeLogHook): () => void;
     /** Register a hook that runs after each log is written. Returns a dispose function to unregister the hook. */
     onAfterLog(hook: AfterLogHook): () => void;
+    /** Returns the resolved retention policy, or undefined if none was configured. */
+    retentionPolicy(): RetentionPolicy | undefined;
 }
 
 declare function betterAudit(config: BetterAuditConfig): BetterAuditInstance;
@@ -380,6 +456,12 @@ declare const AUDIT_LOG_SCHEMA: AuditLogSchema;
  */
 declare function parseDuration(input: string, referenceDate?: Date): Date;
 
+/**
+ * Core export engine. Fetches rows in cursor-paginated batches and writes
+ * them to the sink as CSV or JSON. Memory stays flat regardless of total rows.
+ */
+declare function runExport(executor: QueryExecutor, options: ExportOptions): Promise<ExportResult>;
+
 /** Resolved enrichment config after merging all matching tiers. */
 interface ResolvedEnrichment {
     label?: string;
@@ -519,4 +601,4 @@ declare function fromHeader(headerName: string): ValueExtractor;
  */
 declare function handleMiddleware(extractor: ContextExtractor, request: Request, next: () => Promise<void>, options?: MiddlewareHandlerOptions): Promise<void>;
 
-export { AUDIT_LOG_SCHEMA, type AfterLogHook, type AuditApi, type AuditContext, type AuditDatabaseAdapter, type AuditLog, type AuditLogColumnName, type AuditLogSchema, type AuditOperation, AuditQueryBuilder, type AuditQueryFilters, type AuditQueryResult, type AuditQuerySpec, type AuditSeverity, type AuditStats, type BeforeLogHook, type BetterAuditConfig, type BetterAuditInstance, type CaptureLogInput, type ColumnDefinition, type ColumnType, type ConsoleQueryFilters, type ConsoleQueryResult, type ContextExtractor, type EnrichmentConfig, type EnrichmentDescriptionContext, type EnrichmentSummary, type MiddlewareHandlerOptions, type QueryExecutor, type ResourceFilter, type TimeFilter, type ValueExtractor, betterAudit, createAuditApi, createAuditConsoleEndpoints, fromBearerToken, fromCookie, fromHeader, getAuditContext, handleMiddleware, mergeAuditContext, normalizeInput, parseDuration, runWithAuditContext };
+export { AUDIT_LOG_SCHEMA, type AfterLogHook, type AuditApi, type AuditContext, type AuditDatabaseAdapter, type AuditLog, type AuditLogColumnName, type AuditLogSchema, type AuditOperation, AuditQueryBuilder, type AuditQueryFilters, type AuditQueryResult, type AuditQuerySpec, type AuditSeverity, type AuditStats, type BeforeLogHook, type BetterAuditConfig, type BetterAuditInstance, type CaptureLogInput, type ColumnDefinition, type ColumnType, type ConsoleQueryFilters, type ConsoleQueryResult, type ContextExtractor, type EnrichmentConfig, type EnrichmentDescriptionContext, type EnrichmentSummary, type ExportOptions, type ExportResponseOptions, type ExportResult, type MiddlewareHandlerOptions, type QueryExecutor, type ResourceFilter, type RetentionPolicy, type TimeFilter, type ValueExtractor, betterAudit, createAuditApi, createAuditConsoleEndpoints, createExportResponse, fromBearerToken, fromCookie, fromHeader, getAuditContext, handleMiddleware, mergeAuditContext, normalizeInput, parseDuration, runExport, runWithAuditContext };

package/dist/index.js

@@ -520,38 +520,214 @@ var AuditQueryBuilder = class _AuditQueryBuilder {
   }
 };
 
-// src/audit-api.ts
-var CSV_HEADERS = [
+// src/export.ts
+var DEFAULT_BATCH_SIZE = 500;
+var DEFAULT_CSV_DELIMITER = ",";
+var CSV_COLUMNS = [
   "id",
   "timestamp",
   "tableName",
   "operation",
   "recordId",
   "actorId",
-  "severity",
+  "beforeData",
+  "afterData",
+  "diff",
   "label",
-  "description"
+  "description",
+  "severity",
+  "compliance",
+  "notify",
+  "reason",
+  "metadata",
+  "redactedFields"
 ];
-function escapeCsvField(value) {
-  if (value.includes('"') || value.includes(",") || value.includes("\n") || value.includes("\r")) {
+var JSON_FIELDS = /* @__PURE__ */ new Set([
+  "beforeData",
+  "afterData",
+  "diff",
+  "compliance",
+  "metadata",
+  "redactedFields"
+]);
+function escapeCsvField(value, delimiter) {
+  if (value.includes('"') || value.includes(delimiter) || value.includes("\n") || value.includes("\r")) {
     return `"${value.replace(/"/g, '""')}"`;
   }
   return value;
 }
-function logToCsvRow(log) {
-  const fields = [
-    log.id,
-    log.timestamp instanceof Date ? log.timestamp.toISOString() : String(log.timestamp),
-    log.tableName,
-    log.operation,
-    log.recordId,
-    log.actorId ?? "",
-    log.severity ?? "",
-    log.label ?? "",
-    log.description ?? ""
-  ];
-  return fields.map(escapeCsvField).join(",");
+function formatCsvValue(log, field, delimiter) {
+  const value = log[field];
+  if (value === void 0 || value === null) {
+    return "";
+  }
+  if (JSON_FIELDS.has(field)) {
+    return escapeCsvField(JSON.stringify(value), delimiter);
+  }
+  if (value instanceof Date) {
+    return escapeCsvField(value.toISOString(), delimiter);
+  }
+  if (typeof value === "boolean") {
+    return value ? "true" : "false";
+  }
+  return escapeCsvField(String(value), delimiter);
+}
+function createStringSink() {
+  const chunks = [];
+  return {
+    async write(chunk) {
+      chunks.push(chunk);
+    },
+    async finish() {
+      return chunks.join("");
+    },
+    async abort() {
+    }
+  };
 }
+function createStreamSink(stream) {
+  const writer = stream.getWriter();
+  return {
+    async write(chunk) {
+      await writer.write(chunk);
+    },
+    async finish() {
+      await writer.close();
+      return void 0;
+    },
+    async abort(error) {
+      await writer.abort(error);
+    }
+  };
+}
+async function runExport(executor, options) {
+  const batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+  if (batchSize <= 0) {
+    throw new Error(`batchSize must be greater than 0, got ${batchSize}`);
+  }
+  const delimiter = options.csvDelimiter ?? DEFAULT_CSV_DELIMITER;
+  if (delimiter.length !== 1) {
+    throw new Error("csvDelimiter must be exactly one character");
+  }
+  const jsonStyle = options.jsonStyle ?? "ndjson";
+  const sink = options.output === "string" ? createStringSink() : createStreamSink(options.output);
+  const isStringSink = options.output === "string";
+  const baseSpec = options.query !== void 0 ? options.query.toSpec() : { filters: {} };
+  const totalLimit = baseSpec.limit;
+  const spec = { ...baseSpec, limit: batchSize };
+  let rowCount = 0;
+  try {
+    if (options.format === "csv") {
+      const header = CSV_COLUMNS.map((col) => escapeCsvField(col, delimiter)).join(delimiter);
+      await sink.write(header + "\n");
+      let cursor;
+      for (; ; ) {
+        const currentSpec = cursor !== void 0 ? { ...spec, cursor } : spec;
+        const result = await executor(currentSpec);
+        if (isStringSink) {
+          const lines = [];
+          for (const entry of result.entries) {
+            if (totalLimit !== void 0 && rowCount >= totalLimit) {
+              break;
+            }
+            const row = CSV_COLUMNS.map((col) => formatCsvValue(entry, col, delimiter)).join(delimiter);
+            lines.push(row + "\n");
+            rowCount++;
+          }
+          if (lines.length > 0) {
+            await sink.write(lines.join(""));
+          }
+        } else {
+          for (const entry of result.entries) {
+            if (totalLimit !== void 0 && rowCount >= totalLimit) {
+              break;
+            }
+            const row = CSV_COLUMNS.map((col) => formatCsvValue(entry, col, delimiter)).join(delimiter);
+            await sink.write(row + "\n");
+            rowCount++;
+          }
+        }
+        if (totalLimit !== void 0 && rowCount >= totalLimit) {
+          break;
+        }
+        if (result.nextCursor === void 0) {
+          break;
+        }
+        cursor = result.nextCursor;
+      }
+    } else {
+      if (jsonStyle === "array") {
+        let cursor;
+        const entries = [];
+        for (; ; ) {
+          const currentSpec = cursor !== void 0 ? { ...spec, cursor } : spec;
+          const result = await executor(currentSpec);
+          for (const entry of result.entries) {
+            if (totalLimit !== void 0 && rowCount >= totalLimit) {
+              break;
+            }
+            entries.push(entry);
+            rowCount++;
+          }
+          if (totalLimit !== void 0 && rowCount >= totalLimit) {
+            break;
+          }
+          if (result.nextCursor === void 0) {
+            break;
+          }
+          cursor = result.nextCursor;
+        }
+        await sink.write(JSON.stringify(entries, null, 2) + "\n");
+      } else {
+        let cursor;
+        for (; ; ) {
+          const currentSpec = cursor !== void 0 ? { ...spec, cursor } : spec;
+          const result = await executor(currentSpec);
+          if (isStringSink) {
+            const lines = [];
+            for (const entry of result.entries) {
+              if (totalLimit !== void 0 && rowCount >= totalLimit) {
+                break;
+              }
+              lines.push(JSON.stringify(entry) + "\n");
+              rowCount++;
+            }
+            if (lines.length > 0) {
+              await sink.write(lines.join(""));
+            }
+          } else {
+            for (const entry of result.entries) {
+              if (totalLimit !== void 0 && rowCount >= totalLimit) {
+                break;
+              }
+              await sink.write(JSON.stringify(entry) + "\n");
+              rowCount++;
+            }
+          }
+          if (totalLimit !== void 0 && rowCount >= totalLimit) {
+            break;
+          }
+          if (result.nextCursor === void 0) {
+            break;
+          }
+          cursor = result.nextCursor;
+        }
+      }
+    }
+  } catch (error) {
+    await sink.abort(error);
+    throw error;
+  }
+  const data = await sink.finish();
+  if (data !== void 0) {
+    return { rowCount, data };
+  }
+  return { rowCount };
+}
+
+// src/audit-api.ts
+var VALID_SEVERITIES = /* @__PURE__ */ new Set(["low", "medium", "high", "critical"]);
+var VALID_OPERATIONS = /* @__PURE__ */ new Set(["INSERT", "UPDATE", "DELETE"]);
 function toTimeFilter(date) {
   return { date };
 }
@@ -568,13 +744,24 @@ function buildQuerySpec(filters, effectiveLimit) {
     spec.filters.actorIds = [filters.actorId];
   }
   if (filters.severity !== void 0) {
+    if (!VALID_SEVERITIES.has(filters.severity)) {
+      throw new Error(
+        `Invalid severity "${filters.severity}". Must be one of: low, medium, high, critical`
+      );
+    }
     spec.filters.severities = [filters.severity];
   }
   if (filters.compliance !== void 0) {
     spec.filters.compliance = [filters.compliance];
   }
   if (filters.operation !== void 0) {
-    spec.filters.operations = [filters.operation.toUpperCase()];
+    const normalized = filters.operation.toUpperCase();
+    if (!VALID_OPERATIONS.has(normalized)) {
+      throw new Error(
+        `Invalid operation "${filters.operation}". Must be one of: INSERT, UPDATE, DELETE`
+      );
+    }
+    spec.filters.operations = [normalized];
   }
   if (filters.since !== void 0) {
     spec.filters.since = toTimeFilter(filters.since);
@@ -675,17 +862,28 @@ function createAuditApi(adapter, registry, maxQueryLimit) {
     return summaries;
   }
   async function exportLogs(filters, format) {
+    const queryFn = requireQueryLogs();
     const exportFormat = format ?? "json";
-    const exportFilters = { ...filters, limit: effectiveLimit };
-    const result = await queryLogs(exportFilters);
-    if (exportFormat === "json") {
-      return JSON.stringify(result.entries);
-    }
-    const rows = [CSV_HEADERS.join(",")];
-    for (const log of result.entries) {
-      rows.push(logToCsvRow(log));
-    }
-    return rows.join("\n");
+    const spec = buildQuerySpec(filters ?? {}, effectiveLimit);
+    const queryBuilder = new AuditQueryBuilder(
+      (s) => queryFn(s),
+      spec.filters,
+      spec.limit,
+      void 0,
+      effectiveLimit,
+      spec.sortOrder
+    );
+    const exportOptions = {
+      format: exportFormat,
+      query: queryBuilder,
+      output: "string",
+      ...exportFormat === "json" && { jsonStyle: "array" }
+    };
+    const result = await runExport(
+      (s) => queryFn(s),
+      exportOptions
+    );
+    return result.data ?? "";
   }
   async function purgeLogs(options) {
     const purgeFn = requirePurgeLogs();
@@ -921,14 +1119,113 @@ function createAuditConsoleEndpoints(api) {
   ];
 }
 
+// src/export-response.ts
+function contentTypeForFormat(format, jsonStyle) {
+  if (format === "csv") {
+    return "text/csv; charset=utf-8";
+  }
+  if (jsonStyle === "ndjson") {
+    return "application/x-ndjson; charset=utf-8";
+  }
+  return "application/json; charset=utf-8";
+}
+function fileExtensionForFormat(format, jsonStyle) {
+  if (format === "csv") {
+    return ".csv";
+  }
+  if (jsonStyle === "ndjson") {
+    return ".ndjson";
+  }
+  return ".json";
+}
+function formatDate(date) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+function sanitiseFilename(name) {
+  return name.replace(/["\\\r\n\x00-\x1f]/g, "");
+}
+function createExportResponse(executor, options = {}) {
+  const format = options.format ?? "csv";
+  const jsonStyle = options.jsonStyle ?? "ndjson";
+  const stem = options.filename ?? `audit-export-${formatDate(/* @__PURE__ */ new Date())}`;
+  const extension = fileExtensionForFormat(format, jsonStyle);
+  const fullFilename = sanitiseFilename(`${stem}${extension}`);
+  const contentType = contentTypeForFormat(format, jsonStyle);
+  const transform = new TransformStream();
+  const encoder = new TextEncoderStream();
+  const readable = transform.readable.pipeThrough(encoder);
+  runExport(executor, {
+    format,
+    jsonStyle,
+    output: transform.writable,
+    ...options.batchSize !== void 0 && { batchSize: options.batchSize },
+    ...options.csvDelimiter !== void 0 && {
+      csvDelimiter: options.csvDelimiter
+    },
+    ...options.query !== void 0 && { query: options.query }
+  }).catch(() => {
+  });
+  return new Response(readable, {
+    status: 200,
+    headers: {
+      "Content-Type": contentType,
+      "Content-Disposition": `attachment; filename="${fullFilename}"`,
+      "Cache-Control": "no-cache"
+    }
+  });
+}
+
+// src/retention.ts
+function validateRetentionPolicy(policy) {
+  if (!Number.isInteger(policy.days) || !Number.isFinite(policy.days) || policy.days <= 0) {
+    throw new Error(
+      `retention: 'days' must be a positive integer, got ${String(policy.days)}`
+    );
+  }
+  if (policy.tables !== void 0) {
+    if (!Array.isArray(policy.tables) || policy.tables.length === 0 || policy.tables.some((t) => typeof t !== "string" || t === "")) {
+      throw new Error(
+        "retention: 'tables' must be a non-empty array of non-empty strings"
+      );
+    }
+  }
+}
+
 // src/better-audit.ts
 function withContext(context, fn) {
   return runWithAuditContext(context, fn);
 }
 function betterAudit(config) {
+  if (config.retention !== void 0) {
+    validateRetentionPolicy(config.retention);
+  }
   const { database } = config;
   const auditTables = new Set(config.auditTables);
+  if (config.retention?.tables !== void 0) {
+    const unknown = config.retention.tables.filter((t) => !auditTables.has(t));
+    if (unknown.length > 0) {
+      throw new Error(
+        `retention: 'tables' contains table(s) not in auditTables: ${unknown.join(", ")}. Registered tables: ${[...auditTables].join(", ")}`
+      );
+    }
+  }
   const registry = new EnrichmentRegistry();
+  const resolvedRetention = config.retention !== void 0 ? {
+    ...config.retention,
+    ...config.retention.tables !== void 0 && { tables: [...config.retention.tables] }
+  } : void 0;
+  function retentionPolicy() {
+    if (resolvedRetention === void 0) {
+      return void 0;
+    }
+    return {
+      ...resolvedRetention,
+      ...resolvedRetention.tables !== void 0 && { tables: [...resolvedRetention.tables] }
+    };
+  }
   const beforeLogHooks = config.beforeLog !== void 0 ? [...config.beforeLog] : [];
   const afterLogHooks = config.afterLog !== void 0 ? [...config.afterLog] : [];
   function enrich(table, operation, enrichmentConfig) {
@@ -1036,6 +1333,24 @@ function betterAudit(config) {
       config.maxQueryLimit
     );
   }
+  async function exportLogs(options) {
+    if (database.queryLogs === void 0) {
+      throw new Error(
+        "audit.export() requires a database adapter that implements queryLogs(). Check that your ORM adapter supports querying."
+      );
+    }
+    const queryLogs = database.queryLogs;
+    return runExport((spec) => queryLogs(spec), options);
+  }
+  function exportResponse(options) {
+    if (database.queryLogs === void 0) {
+      throw new Error(
+        "audit.exportResponse() requires a database adapter that implements queryLogs(). Check that your ORM adapter supports querying."
+      );
+    }
+    const queryLogs = database.queryLogs;
+    return createExportResponse((spec) => queryLogs(spec), options);
+  }
   if (config.console) {
     const api = createAuditApi(database, registry, config.maxQueryLimit);
     const endpoints = createAuditConsoleEndpoints(api);
@@ -1045,7 +1360,7 @@ function betterAudit(config) {
       endpoints
     });
   }
-  return { captureLog, query, withContext, enrich, onBeforeLog, onAfterLog };
+  return { captureLog, query, export: exportLogs, exportResponse, withContext, enrich, onBeforeLog, onAfterLog, retentionPolicy };
 }
 
 // src/audit-log-schema.ts
@@ -1253,6 +1568,7 @@ export {
   betterAudit,
   createAuditApi,
   createAuditConsoleEndpoints,
+  createExportResponse,
   fromBearerToken,
   fromCookie,
   fromHeader,
@@ -1261,6 +1577,7 @@ export {
   mergeAuditContext,
   normalizeInput,
   parseDuration,
+  runExport,
   runWithAuditContext
 };
 //# sourceMappingURL=index.js.map