@usebetterdev/audit-core 0.6.1 → 0.8.0

package/dist/index.d.cts

@@ -53,6 +53,8 @@ interface AuditQueryResult {
     entries: AuditLog[];
     /** If present, more results are available. Pass to `.after()` for the next page. */
     nextCursor?: string;
+    /** If present, more results are available in the reverse direction. */
+    prevCursor?: string;
 }
 
 /** Callback that executes a query spec against the adapter. */
@@ -170,12 +172,6 @@ interface AuditContext {
     /** Arbitrary key-value metadata. Redaction rules do not apply to metadata. */
     metadata?: Record<string, unknown>;
 }
-/**
- * Database adapter provided by ORM packages (e.g. drizzle, prisma).
- * Passed as the `database` field in `BetterAuditConfig`.
- *
- * `writeLog` is required. `queryLogs` is optional — only needed when `query()` is used.
- */
 /** Aggregated statistics returned by `AuditApi.getStats()`. */
 interface AuditStats {
     totalLogs: number;
@@ -195,12 +191,19 @@ interface AuditStats {
     operationBreakdown: Record<string, number>;
     severityBreakdown: Record<string, number>;
 }
+/**
+ * Database adapter provided by ORM packages (e.g. drizzle, prisma).
+ * Passed as the `database` field in `BetterAuditConfig`.
+ *
+ * `writeLog` is required. `queryLogs` is optional — only needed when `query()` is used.
+ */
 interface AuditDatabaseAdapter {
     writeLog(log: AuditLog): Promise<void>;
     queryLogs?(spec: AuditQuerySpec): Promise<AuditQueryResult>;
     getLogById?(id: string): Promise<AuditLog | null>;
     getStats?(options?: {
         since?: Date;
+        until?: Date;
     }): Promise<AuditStats>;
     purgeLogs?(options: {
         before: Date;
@@ -414,7 +417,7 @@ declare function normalizeInput(operation: AuditOperation, before: Record<string
  * ORM adapters translate this into their own migration format.
  * Core never runs SQL — this is a declarative data structure only.
  */
-type ColumnType = "uuid" | "timestamptz" | "text" | "jsonb" | "boolean";
+type ColumnType = "uuid" | "timestamptz" | "text" | "jsonb" | "boolean" | "integer";
 interface ColumnDefinition {
     type: ColumnType;
     nullable: boolean;
@@ -452,6 +455,120 @@ declare const AUDIT_LOG_SCHEMA: AuditLogSchema;
  */
 declare function parseDuration(input: string, referenceDate?: Date): Date;
 
+/**
+ * Encodes a cursor from a timestamp and id.
+ * Format: base64(JSON.stringify({ t: iso_string, i: id }))
+ */
+declare function encodeCursor(timestamp: Date, id: string): string;
+/**
+ * Decodes an opaque cursor string back to timestamp + id.
+ * Throws on invalid input.
+ */
+declare function decodeCursor(cursor: string): {
+    timestamp: Date;
+    id: string;
+};
+
+/**
+ * Escapes LIKE/ILIKE wildcard characters so they match literally.
+ * Backslash is the default escape character in PostgreSQL and SQLite LIKE patterns.
+ */
+declare function escapeLikePattern(input: string): string;
+
+/**
+ * Resolves a `TimeFilter` to an absolute `Date`.
+ * Absolute dates are returned as-is; duration strings are parsed relative to now.
+ */
+declare function resolveTimeFilter(filter: TimeFilter): Date;
+
+/** Column names that support simple equality / IN filtering. */
+type AuditFilterField = "tableName" | "recordId" | "actorId" | "severity" | "operation";
+/**
+ * Intermediate representation for a single filter condition.
+ *
+ * Adapters map each variant to their native expression type
+ * (Drizzle `SQL`, Prisma `QueryState` fragments, etc.).
+ */
+type FilterCondition = {
+    readonly kind: "eq";
+    readonly field: AuditFilterField;
+    readonly value: string;
+} | {
+    readonly kind: "in";
+    readonly field: AuditFilterField;
+    readonly values: string[];
+} | {
+    readonly kind: "timestampGte";
+    readonly value: Date;
+} | {
+    readonly kind: "timestampLte";
+    readonly value: Date;
+} | {
+    readonly kind: "search";
+    readonly pattern: string;
+} | {
+    readonly kind: "compliance";
+    readonly tags: string[];
+} | {
+    readonly kind: "cursor";
+    readonly timestamp: Date;
+    readonly id: string;
+    readonly sortOrder: "asc" | "desc";
+};
+interface InterpretFiltersOptions {
+    cursor?: {
+        timestamp: Date;
+        id: string;
+    } | undefined;
+    sortOrder?: "asc" | "desc" | undefined;
+}
+/**
+ * Converts `AuditQueryFilters` + optional cursor into a flat array of
+ * `FilterCondition` values. Pure, zero-dep, independently testable.
+ *
+ * Decision logic (shared across all adapters):
+ * - Array filters with 1 element → `eq`, >1 → `in`, 0/undefined → skip
+ * - Time filters → resolved to absolute `Date` via `resolveTimeFilter()`
+ * - Search text → escaped + wrapped with `%` for LIKE/ILIKE
+ * - Compliance tags → passed through (adapter handles JSONB vs json_each)
+ * - Cursor → emitted with sort order for adapter-specific comparison
+ */
+declare function interpretFilters(filters: AuditQueryFilters, options?: InterpretFiltersOptions): readonly FilterCondition[];
+
+/**
+ * Safely converts a count value (number, string, or bigint) to a JavaScript number.
+ * Handles PostgreSQL bigint-as-string, Prisma BigInt, and SQLite numeric returns.
+ */
+declare function toCount(value: unknown): number;
+/**
+ * Assembles raw query result arrays into an `AuditStats` object.
+ * Works for both Date objects (PostgreSQL) and strings (SQLite, Prisma raw).
+ */
+declare function assembleStats(summaryRows: Array<{
+    totalLogs: unknown;
+    tablesAudited: unknown;
+}>, eventsPerDayRows: Array<{
+    date: unknown;
+    count: unknown;
+}>, topActorsRows: Array<{
+    actorId: unknown;
+    count: unknown;
+}>, topTablesRows: Array<{
+    tableName: unknown;
+    count: unknown;
+}>, operationRows: Array<{
+    operation: unknown;
+    count: unknown;
+}>, severityRows: Array<{
+    severity: unknown;
+    count: unknown;
+}>): AuditStats;
+
+declare const VALID_OPERATIONS: ReadonlySet<string>;
+declare const VALID_SEVERITIES: ReadonlySet<string>;
+declare function isAuditOperation(value: string): value is AuditOperation;
+declare function isAuditSeverity(value: string): value is AuditSeverity;
+
 /**
  * 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.
@@ -482,6 +599,7 @@ declare class EnrichmentRegistry {
 /** Flat console-friendly query filters. Single-value fields translated to multi-value internal filters. */
 interface ConsoleQueryFilters {
     tableName?: string;
+    recordId?: string;
     operation?: string;
     actorId?: string;
     severity?: string;
@@ -491,6 +609,10 @@ interface ConsoleQueryFilters {
     search?: string;
     limit?: number;
     cursor?: string;
+    /** Pagination direction: "after" fetches older entries (default), "before" fetches newer entries. */
+    direction?: "after" | "before";
+    /** Sort order: "asc" (oldest first) or "desc" (newest first). Overrides direction-based sort when both present. */
+    order?: "asc" | "desc";
 }
 /** Serializable summary of an enrichment config (function fields stripped). */
 interface EnrichmentSummary {
@@ -503,9 +625,10 @@ interface EnrichmentSummary {
     redact?: string[];
     include?: string[];
 }
-/** Query result extended with a convenience `hasNextPage` flag. */
+/** Query result extended with convenience pagination flags. */
 interface ConsoleQueryResult extends AuditQueryResult {
     hasNextPage: boolean;
+    hasPrevPage: boolean;
 }
 /**
  * High-level API consumed by console endpoints.
@@ -516,11 +639,14 @@ interface ConsoleQueryResult extends AuditQueryResult {
 interface AuditApi {
     /** Query audit log entries with optional flat filters and cursor-based pagination. */
     queryLogs(filters?: ConsoleQueryFilters): Promise<ConsoleQueryResult>;
+    /** Query audit log entries centered around a specific log ID. */
+    queryLogsAround(anchorId: string, filters?: ConsoleQueryFilters): Promise<ConsoleQueryResult>;
     /** Retrieve a single audit log entry by its ID. Returns `null` when not found. */
     getLog(id: string): Promise<AuditLog | null>;
     /** Get aggregated audit statistics. Requires adapter.getStats. */
     getStats(options?: {
         since?: Date;
+        until?: Date;
     }): Promise<AuditStats>;
     /** Get serializable summaries of all registered enrichments. */
     getEnrichments(): EnrichmentSummary[];
@@ -585,6 +711,12 @@ declare function fromCookie(cookieName: string): ValueExtractor;
  * @param headerName - Header name (case-insensitive per the Web API)
  */
 declare function fromHeader(headerName: string): ValueExtractor;
+/** Default extractor: reads `sub` from `Authorization: Bearer <jwt>` as actor. */
+declare const defaultExtractor: ContextExtractor;
+/**
+ * Runs an extractor safely, catching errors and returning undefined on failure.
+ */
+declare function safeExtract(extractor: ValueExtractor | undefined, request: Request, onError: ((error: unknown) => void) | undefined): Promise<string | undefined>;
 /**
  * Shared middleware handler used by all framework adapters.
  *
@@ -597,4 +729,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 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 };
+export { AUDIT_LOG_SCHEMA, type AfterLogHook, type AuditApi, type AuditContext, type AuditDatabaseAdapter, type AuditFilterField, 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 FilterCondition, type InterpretFiltersOptions, type MiddlewareHandlerOptions, type QueryExecutor, type ResourceFilter, type TimeFilter, VALID_OPERATIONS, VALID_SEVERITIES, type ValueExtractor, assembleStats, betterAudit, createAuditApi, createAuditConsoleEndpoints, createExportResponse, decodeCursor, defaultExtractor, encodeCursor, escapeLikePattern, fromBearerToken, fromCookie, fromHeader, getAuditContext, handleMiddleware, interpretFilters, isAuditOperation, isAuditSeverity, mergeAuditContext, normalizeInput, parseDuration, resolveTimeFilter, runExport, runWithAuditContext, safeExtract, toCount };

package/dist/index.d.ts

@@ -53,6 +53,8 @@ interface AuditQueryResult {
     entries: AuditLog[];
     /** If present, more results are available. Pass to `.after()` for the next page. */
     nextCursor?: string;
+    /** If present, more results are available in the reverse direction. */
+    prevCursor?: string;
 }
 
 /** Callback that executes a query spec against the adapter. */
@@ -170,12 +172,6 @@ interface AuditContext {
     /** Arbitrary key-value metadata. Redaction rules do not apply to metadata. */
     metadata?: Record<string, unknown>;
 }
-/**
- * Database adapter provided by ORM packages (e.g. drizzle, prisma).
- * Passed as the `database` field in `BetterAuditConfig`.
- *
- * `writeLog` is required. `queryLogs` is optional — only needed when `query()` is used.
- */
 /** Aggregated statistics returned by `AuditApi.getStats()`. */
 interface AuditStats {
     totalLogs: number;
@@ -195,12 +191,19 @@ interface AuditStats {
     operationBreakdown: Record<string, number>;
     severityBreakdown: Record<string, number>;
 }
+/**
+ * Database adapter provided by ORM packages (e.g. drizzle, prisma).
+ * Passed as the `database` field in `BetterAuditConfig`.
+ *
+ * `writeLog` is required. `queryLogs` is optional — only needed when `query()` is used.
+ */
 interface AuditDatabaseAdapter {
     writeLog(log: AuditLog): Promise<void>;
     queryLogs?(spec: AuditQuerySpec): Promise<AuditQueryResult>;
     getLogById?(id: string): Promise<AuditLog | null>;
     getStats?(options?: {
         since?: Date;
+        until?: Date;
     }): Promise<AuditStats>;
     purgeLogs?(options: {
         before: Date;
@@ -414,7 +417,7 @@ declare function normalizeInput(operation: AuditOperation, before: Record<string
  * ORM adapters translate this into their own migration format.
  * Core never runs SQL — this is a declarative data structure only.
  */
-type ColumnType = "uuid" | "timestamptz" | "text" | "jsonb" | "boolean";
+type ColumnType = "uuid" | "timestamptz" | "text" | "jsonb" | "boolean" | "integer";
 interface ColumnDefinition {
     type: ColumnType;
     nullable: boolean;
@@ -452,6 +455,120 @@ declare const AUDIT_LOG_SCHEMA: AuditLogSchema;
  */
 declare function parseDuration(input: string, referenceDate?: Date): Date;
 
+/**
+ * Encodes a cursor from a timestamp and id.
+ * Format: base64(JSON.stringify({ t: iso_string, i: id }))
+ */
+declare function encodeCursor(timestamp: Date, id: string): string;
+/**
+ * Decodes an opaque cursor string back to timestamp + id.
+ * Throws on invalid input.
+ */
+declare function decodeCursor(cursor: string): {
+    timestamp: Date;
+    id: string;
+};
+
+/**
+ * Escapes LIKE/ILIKE wildcard characters so they match literally.
+ * Backslash is the default escape character in PostgreSQL and SQLite LIKE patterns.
+ */
+declare function escapeLikePattern(input: string): string;
+
+/**
+ * Resolves a `TimeFilter` to an absolute `Date`.
+ * Absolute dates are returned as-is; duration strings are parsed relative to now.
+ */
+declare function resolveTimeFilter(filter: TimeFilter): Date;
+
+/** Column names that support simple equality / IN filtering. */
+type AuditFilterField = "tableName" | "recordId" | "actorId" | "severity" | "operation";
+/**
+ * Intermediate representation for a single filter condition.
+ *
+ * Adapters map each variant to their native expression type
+ * (Drizzle `SQL`, Prisma `QueryState` fragments, etc.).
+ */
+type FilterCondition = {
+    readonly kind: "eq";
+    readonly field: AuditFilterField;
+    readonly value: string;
+} | {
+    readonly kind: "in";
+    readonly field: AuditFilterField;
+    readonly values: string[];
+} | {
+    readonly kind: "timestampGte";
+    readonly value: Date;
+} | {
+    readonly kind: "timestampLte";
+    readonly value: Date;
+} | {
+    readonly kind: "search";
+    readonly pattern: string;
+} | {
+    readonly kind: "compliance";
+    readonly tags: string[];
+} | {
+    readonly kind: "cursor";
+    readonly timestamp: Date;
+    readonly id: string;
+    readonly sortOrder: "asc" | "desc";
+};
+interface InterpretFiltersOptions {
+    cursor?: {
+        timestamp: Date;
+        id: string;
+    } | undefined;
+    sortOrder?: "asc" | "desc" | undefined;
+}
+/**
+ * Converts `AuditQueryFilters` + optional cursor into a flat array of
+ * `FilterCondition` values. Pure, zero-dep, independently testable.
+ *
+ * Decision logic (shared across all adapters):
+ * - Array filters with 1 element → `eq`, >1 → `in`, 0/undefined → skip
+ * - Time filters → resolved to absolute `Date` via `resolveTimeFilter()`
+ * - Search text → escaped + wrapped with `%` for LIKE/ILIKE
+ * - Compliance tags → passed through (adapter handles JSONB vs json_each)
+ * - Cursor → emitted with sort order for adapter-specific comparison
+ */
+declare function interpretFilters(filters: AuditQueryFilters, options?: InterpretFiltersOptions): readonly FilterCondition[];
+
+/**
+ * Safely converts a count value (number, string, or bigint) to a JavaScript number.
+ * Handles PostgreSQL bigint-as-string, Prisma BigInt, and SQLite numeric returns.
+ */
+declare function toCount(value: unknown): number;
+/**
+ * Assembles raw query result arrays into an `AuditStats` object.
+ * Works for both Date objects (PostgreSQL) and strings (SQLite, Prisma raw).
+ */
+declare function assembleStats(summaryRows: Array<{
+    totalLogs: unknown;
+    tablesAudited: unknown;
+}>, eventsPerDayRows: Array<{
+    date: unknown;
+    count: unknown;
+}>, topActorsRows: Array<{
+    actorId: unknown;
+    count: unknown;
+}>, topTablesRows: Array<{
+    tableName: unknown;
+    count: unknown;
+}>, operationRows: Array<{
+    operation: unknown;
+    count: unknown;
+}>, severityRows: Array<{
+    severity: unknown;
+    count: unknown;
+}>): AuditStats;
+
+declare const VALID_OPERATIONS: ReadonlySet<string>;
+declare const VALID_SEVERITIES: ReadonlySet<string>;
+declare function isAuditOperation(value: string): value is AuditOperation;
+declare function isAuditSeverity(value: string): value is AuditSeverity;
+
 /**
  * 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.
@@ -482,6 +599,7 @@ declare class EnrichmentRegistry {
 /** Flat console-friendly query filters. Single-value fields translated to multi-value internal filters. */
 interface ConsoleQueryFilters {
     tableName?: string;
+    recordId?: string;
     operation?: string;
     actorId?: string;
     severity?: string;
@@ -491,6 +609,10 @@ interface ConsoleQueryFilters {
     search?: string;
     limit?: number;
     cursor?: string;
+    /** Pagination direction: "after" fetches older entries (default), "before" fetches newer entries. */
+    direction?: "after" | "before";
+    /** Sort order: "asc" (oldest first) or "desc" (newest first). Overrides direction-based sort when both present. */
+    order?: "asc" | "desc";
 }
 /** Serializable summary of an enrichment config (function fields stripped). */
 interface EnrichmentSummary {
@@ -503,9 +625,10 @@ interface EnrichmentSummary {
     redact?: string[];
     include?: string[];
 }
-/** Query result extended with a convenience `hasNextPage` flag. */
+/** Query result extended with convenience pagination flags. */
 interface ConsoleQueryResult extends AuditQueryResult {
     hasNextPage: boolean;
+    hasPrevPage: boolean;
 }
 /**
  * High-level API consumed by console endpoints.
@@ -516,11 +639,14 @@ interface ConsoleQueryResult extends AuditQueryResult {
 interface AuditApi {
     /** Query audit log entries with optional flat filters and cursor-based pagination. */
     queryLogs(filters?: ConsoleQueryFilters): Promise<ConsoleQueryResult>;
+    /** Query audit log entries centered around a specific log ID. */
+    queryLogsAround(anchorId: string, filters?: ConsoleQueryFilters): Promise<ConsoleQueryResult>;
     /** Retrieve a single audit log entry by its ID. Returns `null` when not found. */
     getLog(id: string): Promise<AuditLog | null>;
     /** Get aggregated audit statistics. Requires adapter.getStats. */
     getStats(options?: {
         since?: Date;
+        until?: Date;
     }): Promise<AuditStats>;
     /** Get serializable summaries of all registered enrichments. */
     getEnrichments(): EnrichmentSummary[];
@@ -585,6 +711,12 @@ declare function fromCookie(cookieName: string): ValueExtractor;
  * @param headerName - Header name (case-insensitive per the Web API)
  */
 declare function fromHeader(headerName: string): ValueExtractor;
+/** Default extractor: reads `sub` from `Authorization: Bearer <jwt>` as actor. */
+declare const defaultExtractor: ContextExtractor;
+/**
+ * Runs an extractor safely, catching errors and returning undefined on failure.
+ */
+declare function safeExtract(extractor: ValueExtractor | undefined, request: Request, onError: ((error: unknown) => void) | undefined): Promise<string | undefined>;
 /**
  * Shared middleware handler used by all framework adapters.
  *
@@ -597,4 +729,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 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 };
+export { AUDIT_LOG_SCHEMA, type AfterLogHook, type AuditApi, type AuditContext, type AuditDatabaseAdapter, type AuditFilterField, 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 FilterCondition, type InterpretFiltersOptions, type MiddlewareHandlerOptions, type QueryExecutor, type ResourceFilter, type TimeFilter, VALID_OPERATIONS, VALID_SEVERITIES, type ValueExtractor, assembleStats, betterAudit, createAuditApi, createAuditConsoleEndpoints, createExportResponse, decodeCursor, defaultExtractor, encodeCursor, escapeLikePattern, fromBearerToken, fromCookie, fromHeader, getAuditContext, handleMiddleware, interpretFilters, isAuditOperation, isAuditSeverity, mergeAuditContext, normalizeInput, parseDuration, resolveTimeFilter, runExport, runWithAuditContext, safeExtract, toCount };