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

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(index_exports, {
   betterAudit: () => betterAudit,
   createAuditApi: () => createAuditApi,
   createAuditConsoleEndpoints: () => createAuditConsoleEndpoints,
+  createExportResponse: () => createExportResponse,
   fromBearerToken: () => fromBearerToken,
   fromCookie: () => fromCookie,
   fromHeader: () => fromHeader,
@@ -33,6 +34,7 @@ __export(index_exports, {
   mergeAuditContext: () => mergeAuditContext,
   normalizeInput: () => normalizeInput,
   parseDuration: () => parseDuration,
+  runExport: () => runExport,
   runWithAuditContext: () => runWithAuditContext
 });
 module.exports = __toCommonJS(index_exports);
@@ -559,38 +561,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 };
 }
@@ -607,13 +785,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);
@@ -714,17 +903,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();
@@ -960,14 +1160,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) {
@@ -1075,6 +1374,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);
@@ -1084,7 +1401,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
@@ -1293,6 +1610,7 @@ async function handleMiddleware(extractor, request, next, options = {}) {
   betterAudit,
   createAuditApi,
   createAuditConsoleEndpoints,
+  createExportResponse,
   fromBearerToken,
   fromCookie,
   fromHeader,
@@ -1301,6 +1619,7 @@ async function handleMiddleware(extractor, request, next, options = {}) {
   mergeAuditContext,
   normalizeInput,
   parseDuration,
+  runExport,
   runWithAuditContext
 });
 //# sourceMappingURL=index.cjs.map