@usebetterdev/audit-core 0.5.0-beta.1 → 0.6.0

package/dist/index.d.ts

@@ -1,5 +1,7 @@
-import { ConsoleRegistration, ConsoleProductEndpoint } from '@usebetterdev/console-contract';
-export { ConsoleRegistration } from '@usebetterdev/console-contract';
+import { RetentionPolicy } from '@usebetterdev/contract/config-types';
+export { RetentionPolicy } from '@usebetterdev/contract/config-types';
+import { ConsoleRegistration, ConsoleProductEndpoint } from '@usebetterdev/contract';
+export { ConsoleRegistration } from '@usebetterdev/contract';
 
 /** Identifies a specific resource (table + optional record). */
 interface ResourceFilter {
@@ -104,14 +106,33 @@ declare class AuditQueryBuilder {
     list(): Promise<AuditQueryResult>;
 }
 
-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[];
+/** 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";
+
 type AuditSeverity = "low" | "medium" | "high" | "critical";
 /** A single audit log entry as stored in the database. */
 interface AuditLog {
@@ -333,6 +354,14 @@ interface BetterAuditInstance {
      * 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.
@@ -568,4 +597,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 ExportOptions, type ExportResult, type MiddlewareHandlerOptions, type QueryExecutor, type ResourceFilter, type RetentionPolicy, type TimeFilter, type ValueExtractor, betterAudit, createAuditApi, createAuditConsoleEndpoints, fromBearerToken, fromCookie, fromHeader, getAuditContext, handleMiddleware, mergeAuditContext, normalizeInput, parseDuration, runExport, 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 TimeFilter, type ValueExtractor, betterAudit, createAuditApi, createAuditConsoleEndpoints, createExportResponse, fromBearerToken, fromCookie, fromHeader, getAuditContext, handleMiddleware, mergeAuditContext, normalizeInput, parseDuration, runExport, runWithAuditContext };

package/dist/index.js

@@ -1119,6 +1119,65 @@ 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) {
@@ -1143,6 +1202,11 @@ function betterAudit(config) {
   if (config.retention !== void 0) {
     validateRetentionPolicy(config.retention);
   }
+  if (config.asyncWrite === true && config.onError === void 0) {
+    console.warn(
+      "audit: asyncWrite is enabled without onError \u2014 write failures will only log to console.error. Set onError to route failures to your error tracking system."
+    );
+  }
   const { database } = config;
   const auditTables = new Set(config.auditTables);
   if (config.retention?.tables !== void 0) {
@@ -1283,6 +1347,15 @@ function betterAudit(config) {
     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);
@@ -1292,7 +1365,7 @@ function betterAudit(config) {
       endpoints
     });
   }
-  return { captureLog, query, export: exportLogs, withContext, enrich, onBeforeLog, onAfterLog, retentionPolicy };
+  return { captureLog, query, export: exportLogs, exportResponse, withContext, enrich, onBeforeLog, onAfterLog, retentionPolicy };
 }
 
 // src/audit-log-schema.ts
@@ -1500,6 +1573,7 @@ export {
   betterAudit,
   createAuditApi,
   createAuditConsoleEndpoints,
+  createExportResponse,
   fromBearerToken,
   fromCookie,
   fromHeader,