@flipboxlabs/aws-audit-sdk 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Flipbox Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,30 @@
+# @flipboxlabs/aws-audit-sdk
+
+AWS Audit SDK - Core SDK for audit logging and event management.
+
+## Installation
+
+```bash
+npm install @flipboxlabs/aws-audit-sdk
+# or
+pnpm add @flipboxlabs/aws-audit-sdk
+```
+
+## Usage
+
+```typescript
+import { Audits, defineAuditConfig } from '@flipboxlabs/aws-audit-sdk';
+import { logAudits } from '@flipboxlabs/aws-audit-sdk/middleware';
+```
+
+## Features
+
+- Audit logging with structured data
+- EventBridge integration
+- DynamoDB storage
+- Middy middleware support
+- Batch processing utilities
+
+## License
+
+MIT

package/dist/audits.d.ts

@@ -0,0 +1,188 @@
+import type { GenericLogger } from "@aws-lambda-powertools/commons/types";
+import type { AuditConfig } from "./config.js";
+import { type LogAuditInput } from "./schema/log.js";
+/**
+ * Configuration options for the Audits class.
+ */
+export type AuditsOptions<C extends AuditConfig> = {
+    /**
+     * Custom logger for debug, warning, and error messages.
+     * If not provided, a Console instance is used.
+     * Note: Audit logs are always written to stdout regardless of this setting.
+     */
+    logger?: GenericLogger;
+    /**
+     * Audit configuration for strict typing of app and resourceType fields.
+     * TypeScript will enforce correct app/type values at compile time and
+     * runtime validation occurs against the config schemas.
+     */
+    config: C;
+};
+/**
+ * Strictly typed audit input based on the provided config.
+ * Replaces generic string types with the specific app and resourceType unions.
+ */
+export type StrictLogAuditInput<C extends AuditConfig> = Omit<LogAuditInput, "target" | "source" | "resources"> & {
+    target: {
+        app: C["_types"]["App"];
+        type: C["_types"]["ResourceType"];
+        id?: string | number;
+    };
+    source?: {
+        app: C["_types"]["App"];
+        type: C["_types"]["ResourceType"];
+        id?: string | number;
+    };
+    resources?: Array<{
+        app: C["_types"]["App"];
+        type: C["_types"]["ResourceType"];
+        id?: string | number;
+    }> | Set<{
+        app: C["_types"]["App"];
+        type: C["_types"]["ResourceType"];
+        id?: string | number;
+    }>;
+};
+/**
+ * Manages audit log collection and emission for AWS Lambda functions.
+ *
+ * Buffers audit entries and emits them as structured JSON logs to stdout,
+ * which can be captured by CloudWatch Logs and processed by subscription filters.
+ *
+ * Features:
+ * - Automatic buffering with configurable flush threshold
+ * - X-Ray trace ID injection for distributed tracing
+ * - Environment-based enable/disable control
+ * - Schema validation via Zod before emission
+ * - Strict typing for app and resourceType via config
+ *
+ * @example
+ * ```typescript
+ * const config = defineAuditConfig({
+ *   apps: ['Orders', 'Inventory'] as const,
+ *   resourceTypes: ['Order', 'Product'] as const,
+ * });
+ *
+ * const audits = new Audits({ config });
+ *
+ * audits.addAudit({
+ *   operation: 'createOrder',
+ *   target: { app: 'Orders', type: 'Order', id: '123' }, // Strictly typed!
+ *   status: Status.SUCCESS,
+ * });
+ *
+ * // Flush at end of Lambda execution
+ * audits.publishStoredAudits();
+ * ```
+ */
+export declare class Audits<C extends AuditConfig> {
+    #private;
+    /**
+     * Console instance for emitting audit logs to stdout.
+     * Uses a dedicated Console instance in Lambda for isolation from custom loggers.
+     * @internal
+     */
+    private console;
+    /**
+     * Logger for debug, warning, and error messages (not audit logs).
+     */
+    readonly logger: GenericLogger;
+    /**
+     * Whether audit emission is disabled.
+     * @internal
+     */
+    private disabled;
+    /**
+     * X-Ray trace ID from the Lambda environment, if available.
+     * Automatically injected into audit entries that don't have a trace ID.
+     */
+    readonly traceId: string | undefined;
+    /**
+     * Buffer of audit entries waiting to be published.
+     * @internal
+     */
+    private storedAudits;
+    /**
+     * Audit configuration for strict typing validation.
+     * @internal
+     */
+    private readonly config;
+    /**
+     * Creates a new Audits instance.
+     *
+     * Initializes the console, reads environment configuration, and captures
+     * the X-Ray trace ID from the Lambda environment.
+     *
+     * @param options - Configuration options including the required audit config
+     */
+    constructor(options: AuditsOptions<C>);
+    /**
+     * Checks whether audit emission is currently disabled.
+     *
+     * @returns True if audits are disabled, false otherwise
+     */
+    protected isDisabled(): boolean;
+    /**
+     * Clears all buffered audit entries without publishing them.
+     */
+    protected clearAudits(): void;
+    /**
+     * Adds an audit entry to the buffer.
+     *
+     * If the buffer reaches MAX_AUDITS_SIZE, automatically triggers
+     * a flush to prevent unbounded memory growth.
+     *
+     * The input is validated against the config's schemas at runtime
+     * and TypeScript enforces strict typing at compile time.
+     *
+     * @param item - The audit entry to buffer
+     */
+    addAudit(item: StrictLogAuditInput<C>): void;
+    /**
+     * Publishes all buffered audit entries to stdout and clears the buffer.
+     *
+     * Each audit entry is:
+     * 1. Injected with the X-Ray trace ID if not already set
+     * 2. Validated and transformed through LogAuditSchema (or typed schema if config provided)
+     * 3. Emitted as JSON with the AUDIT_LOG_IDENTIFIER wrapper
+     *
+     * If audits are disabled, the buffer is cleared without emission.
+     *
+     * @example
+     * ```typescript
+     * // Manual flush at end of handler
+     * audits.publishStoredAudits();
+     * ```
+     */
+    publishStoredAudits(): void;
+    /**
+     * Initializes the console instance based on environment mode.
+     *
+     * In production (non-dev mode), creates a dedicated Console instance
+     * writing to process.stdout/stderr. In dev mode, uses the global console
+     * for better local debugging experience.
+     *
+     * @internal
+     */
+    private setConsole;
+    /**
+     * Reads and caches environment configuration values.
+     *
+     * Checks POWERTOOLS_AUDITS_DISABLED and POWERTOOLS_DEV environment
+     * variables using AWS Lambda Powertools utilities.
+     *
+     * @internal
+     */
+    private setEnvConfig;
+    /**
+     * Determines whether audits should be disabled based on environment.
+     *
+     * Priority:
+     * 1. POWERTOOLS_AUDITS_DISABLED takes precedence if explicitly set
+     * 2. Otherwise, audits are disabled in dev mode (POWERTOOLS_DEV=true)
+     *
+     * @internal
+     */
+    private setDisabled;
+}
+//# sourceMappingURL=audits.d.ts.map

package/dist/audits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audits.d.ts","sourceRoot":"","sources":["../src/audits.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAC;AAM1E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAA6B,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAQhF;;GAEG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,WAAW,IAAI;IAClD;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB;;;;OAIG;IACH,MAAM,EAAE,CAAC,CAAC;CACV,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,WAAW,IAAI,IAAI,CAC5D,aAAa,EACb,QAAQ,GAAG,QAAQ,GAAG,WAAW,CACjC,GAAG;IACH,MAAM,EAAE;QACP,GAAG,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,cAAc,CAAC,CAAC;QAClC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KACrB,CAAC;IACF,MAAM,CAAC,EAAE;QACR,GAAG,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,cAAc,CAAC,CAAC;QAClC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KACrB,CAAC;IACF,SAAS,CAAC,EACP,KAAK,CAAC;QACN,GAAG,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,cAAc,CAAC,CAAC;QAClC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KACpB,CAAC,GACF,GAAG,CAAC;QACJ,GAAG,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,KAAK,CAAC,CAAC;QACxB,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,cAAc,CAAC,CAAC;QAClC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KACpB,CAAC,CAAC;CACN,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,MAAM,CAAC,CAAC,SAAS,WAAW;;IACxC;;;;OAIG;IACH,OAAO,CAAC,OAAO,CAAW;IAE1B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAE/B;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAS;IAWzB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAErC;;;OAGG;IACH,OAAO,CAAC,YAAY,CAA4B;IAEhD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAI;IAE3B;;;;;;;OAOG;gBACgB,OAAO,EAAE,aAAa,CAAC,CAAC,CAAC;IAU5C;;;;OAIG;IACH,SAAS,CAAC,UAAU,IAAI,OAAO;IAI/B;;OAEG;IACH,SAAS,CAAC,WAAW,IAAI,IAAI;IAI7B;;;;;;;;;;OAUG;IACI,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC,CAAC,GAAG,IAAI;IAsBnD;;;;;;;;;;;;;;;OAeG;IACI,mBAAmB,IAAI,IAAI;IAwBlC;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;IAWlB;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IASpB;;;;;;;;OAQG;IACH,OAAO,CAAC,WAAW;CAUnB"}

package/dist/audits.js

@@ -0,0 +1,225 @@
+import { Console } from "node:console";
+import { getBooleanFromEnv, getXRayTraceIdFromEnv, isDevMode, } from "@aws-lambda-powertools/commons/utils/env";
+import { AUDIT_LOG_IDENTIFIER } from "./constants.js";
+import { createTypedLogAuditSchema } from "./schema/log.js";
+/**
+ * Maximum number of audit entries that can be buffered before automatic flush.
+ * When this limit is reached, audits are automatically published to prevent memory issues.
+ */
+const MAX_AUDITS_SIZE = 20;
+/**
+ * Manages audit log collection and emission for AWS Lambda functions.
+ *
+ * Buffers audit entries and emits them as structured JSON logs to stdout,
+ * which can be captured by CloudWatch Logs and processed by subscription filters.
+ *
+ * Features:
+ * - Automatic buffering with configurable flush threshold
+ * - X-Ray trace ID injection for distributed tracing
+ * - Environment-based enable/disable control
+ * - Schema validation via Zod before emission
+ * - Strict typing for app and resourceType via config
+ *
+ * @example
+ * ```typescript
+ * const config = defineAuditConfig({
+ *   apps: ['Orders', 'Inventory'] as const,
+ *   resourceTypes: ['Order', 'Product'] as const,
+ * });
+ *
+ * const audits = new Audits({ config });
+ *
+ * audits.addAudit({
+ *   operation: 'createOrder',
+ *   target: { app: 'Orders', type: 'Order', id: '123' }, // Strictly typed!
+ *   status: Status.SUCCESS,
+ * });
+ *
+ * // Flush at end of Lambda execution
+ * audits.publishStoredAudits();
+ * ```
+ */
+export class Audits {
+    /**
+     * Console instance for emitting audit logs to stdout.
+     * Uses a dedicated Console instance in Lambda for isolation from custom loggers.
+     * @internal
+     */
+    console;
+    /**
+     * Logger for debug, warning, and error messages (not audit logs).
+     */
+    logger;
+    /**
+     * Whether audit emission is disabled.
+     * @internal
+     */
+    disabled = false;
+    /**
+     * Cached environment configuration values.
+     * @internal
+     */
+    #envConfig = {
+        disabled: false,
+        devMode: false,
+    };
+    /**
+     * X-Ray trace ID from the Lambda environment, if available.
+     * Automatically injected into audit entries that don't have a trace ID.
+     */
+    traceId;
+    /**
+     * Buffer of audit entries waiting to be published.
+     * @internal
+     */
+    storedAudits = [];
+    /**
+     * Audit configuration for strict typing validation.
+     * @internal
+     */
+    config;
+    /**
+     * Creates a new Audits instance.
+     *
+     * Initializes the console, reads environment configuration, and captures
+     * the X-Ray trace ID from the Lambda environment.
+     *
+     * @param options - Configuration options including the required audit config
+     */
+    constructor(options) {
+        this.setEnvConfig();
+        this.setConsole();
+        this.setDisabled();
+        this.logger = options.logger || this.console;
+        this.config = options.config;
+        this.traceId = getXRayTraceIdFromEnv();
+    }
+    /**
+     * Checks whether audit emission is currently disabled.
+     *
+     * @returns True if audits are disabled, false otherwise
+     */
+    isDisabled() {
+        return this.disabled;
+    }
+    /**
+     * Clears all buffered audit entries without publishing them.
+     */
+    clearAudits() {
+        this.storedAudits = [];
+    }
+    /**
+     * Adds an audit entry to the buffer.
+     *
+     * If the buffer reaches MAX_AUDITS_SIZE, automatically triggers
+     * a flush to prevent unbounded memory growth.
+     *
+     * The input is validated against the config's schemas at runtime
+     * and TypeScript enforces strict typing at compile time.
+     *
+     * @param item - The audit entry to buffer
+     */
+    addAudit(item) {
+        if (Object.keys(this.storedAudits).length >= MAX_AUDITS_SIZE) {
+            this.publishStoredAudits();
+        }
+        this.config.schemas.resourceReference.parse(item.target);
+        if (item.source) {
+            this.config.schemas.resourceReference.parse(item.source);
+        }
+        if (item.resources) {
+            const resources = item.resources instanceof Set
+                ? Array.from(item.resources)
+                : item.resources;
+            for (const resource of resources) {
+                this.config.schemas.resourceReference.parse(resource);
+            }
+        }
+        this.storedAudits.push(item);
+    }
+    /**
+     * Publishes all buffered audit entries to stdout and clears the buffer.
+     *
+     * Each audit entry is:
+     * 1. Injected with the X-Ray trace ID if not already set
+     * 2. Validated and transformed through LogAuditSchema (or typed schema if config provided)
+     * 3. Emitted as JSON with the AUDIT_LOG_IDENTIFIER wrapper
+     *
+     * If audits are disabled, the buffer is cleared without emission.
+     *
+     * @example
+     * ```typescript
+     * // Manual flush at end of handler
+     * audits.publishStoredAudits();
+     * ```
+     */
+    publishStoredAudits() {
+        if (!this.disabled) {
+            const schema = createTypedLogAuditSchema(this.config.schemas.resourceReference);
+            this.storedAudits.forEach((item) => {
+                if (!item.trace) {
+                    item.trace = this.traceId;
+                }
+                this.console.log(JSON.stringify({
+                    [AUDIT_LOG_IDENTIFIER]: {
+                        ...schema.parse(item),
+                    },
+                }));
+            });
+        }
+        this.clearAudits();
+    }
+    /**
+     * Initializes the console instance based on environment mode.
+     *
+     * In production (non-dev mode), creates a dedicated Console instance
+     * writing to process.stdout/stderr. In dev mode, uses the global console
+     * for better local debugging experience.
+     *
+     * @internal
+     */
+    setConsole() {
+        if (!this.#envConfig.devMode) {
+            this.console = new Console({
+                stdout: process.stdout,
+                stderr: process.stderr,
+            });
+        }
+        else {
+            this.console = console;
+        }
+    }
+    /**
+     * Reads and caches environment configuration values.
+     *
+     * Checks POWERTOOLS_AUDITS_DISABLED and POWERTOOLS_DEV environment
+     * variables using AWS Lambda Powertools utilities.
+     *
+     * @internal
+     */
+    setEnvConfig() {
+        this.#envConfig.disabled = getBooleanFromEnv({
+            key: "POWERTOOLS_AUDITS_DISABLED",
+            defaultValue: false,
+            extendedParsing: true,
+        });
+        this.#envConfig.devMode = isDevMode();
+    }
+    /**
+     * Determines whether audits should be disabled based on environment.
+     *
+     * Priority:
+     * 1. POWERTOOLS_AUDITS_DISABLED takes precedence if explicitly set
+     * 2. Otherwise, audits are disabled in dev mode (POWERTOOLS_DEV=true)
+     *
+     * @internal
+     */
+    setDisabled() {
+        if ("POWERTOOLS_AUDITS_DISABLED" in process.env &&
+            process.env.POWERTOOLS_AUDITS_DISABLED !== undefined) {
+            this.disabled = this.#envConfig.disabled;
+            return;
+        }
+        this.disabled = this.#envConfig.devMode;
+    }
+}

package/dist/batch/batch-processor.d.ts

@@ -0,0 +1,81 @@
+import { BatchProcessor, type EventType } from "@aws-lambda-powertools/batch";
+import type { EventSourceDataClassTypes, FailureResponse, SuccessResponse } from "@aws-lambda-powertools/batch/types";
+import type { Audits } from "../audits.js";
+import type { AuditConfig } from "../config.js";
+import { type LogAuditInput } from "../schema/log.js";
+/**
+ * Result type that can include optional audit overrides.
+ * When a batch processor handler returns this type, the _audit field
+ * can be used to customize the audit log entry.
+ */
+export type MessageWithAuditOverride = {
+    /** Human-readable message describing the result */
+    message: string;
+    /** Optional overrides to apply to the audit log entry */
+    _audit?: Partial<LogAuditInput>;
+};
+/**
+ * Extended batch processor that automatically creates audit log entries
+ * for each record processed in a batch operation.
+ *
+ * Integrates with AWS Lambda Powertools BatchProcessor to provide
+ * automatic audit logging for SQS, Kinesis, and DynamoDB Streams events.
+ *
+ * @template Record - The type of event source record being processed
+ *
+ * @example
+ * ```typescript
+ * const processor = new AuditBatchProcessor(
+ *   EventType.SQS,
+ *   audits,
+ *   (record, overrides) => ({
+ *     operation: 'processMessage',
+ *     target: { app: 'MyApp', type: 'Message' },
+ *     ...overrides,
+ *   })
+ * );
+ * ```
+ */
+export declare class AuditBatchProcessor<Record extends EventSourceDataClassTypes> extends BatchProcessor {
+    readonly audit: Audits<AuditConfig>;
+    readonly createAuditItem: (record: Record, overrides?: Partial<LogAuditInput>) => LogAuditInput;
+    /**
+     * Creates a new AuditBatchProcessor instance.
+     *
+     * @param eventType - The type of event source (SQS, Kinesis, or DynamoDB)
+     * @param audit - The Audits instance used to collect and publish audit logs
+     * @param createAuditItem - Factory function that creates an audit log entry from a record
+     */
+    constructor(eventType: keyof typeof EventType, audit: Audits<AuditConfig>, createAuditItem: (record: Record, overrides?: Partial<LogAuditInput>) => LogAuditInput);
+    /**
+     * Handles successful record processing by creating a success audit entry.
+     *
+     * Called automatically by the batch processor when a record is processed
+     * without throwing an error. Creates an audit entry with SUCCESS status
+     * and excludes the original event data to reduce storage costs.
+     *
+     * The audit ID is automatically set from the record's unique identifier
+     * (messageId for SQS, eventID for Kinesis/DynamoDB) to enable retry correlation.
+     *
+     * @param record - The successfully processed record
+     * @param result - The result returned by the record handler, may include audit overrides
+     * @returns The success response from the parent BatchProcessor
+     */
+    successHandler(record: Record, result: unknown | MessageWithAuditOverride): SuccessResponse;
+    /**
+     * Handles failed record processing by creating a failure audit entry.
+     *
+     * Called automatically by the batch processor when a record handler
+     * throws an error. Creates an audit entry with FAIL status, includes
+     * the original event data for debugging, and captures the error details.
+     *
+     * The audit ID is automatically set from the record's unique identifier
+     * (messageId for SQS, eventID for Kinesis/DynamoDB) to enable retry correlation.
+     *
+     * @param record - The record that failed processing
+     * @param error - The error thrown during processing
+     * @returns The failure response from the parent BatchProcessor
+     */
+    failureHandler(record: Record, error: Error): FailureResponse;
+}
+//# sourceMappingURL=batch-processor.d.ts.map

package/dist/batch/batch-processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-processor.d.ts","sourceRoot":"","sources":["../../src/batch/batch-processor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,KAAK,EACX,yBAAyB,EACzB,eAAe,EACf,eAAe,EACf,MAAM,oCAAoC,CAAC;AAM5C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,KAAK,aAAa,EAAU,MAAM,kBAAkB,CAAC;AAO9D;;;;GAIG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACtC,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;CAChC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,mBAAmB,CAC/B,MAAM,SAAS,yBAAyB,CACvC,SAAQ,cAAc;IAUtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC;IACnC,QAAQ,CAAC,eAAe,EAAE,CACzB,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,KAC9B,aAAa;IAbnB;;;;;;OAMG;gBAEF,SAAS,EAAE,MAAM,OAAO,SAAS,EACxB,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,EAC1B,eAAe,EAAE,CACzB,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,KAC9B,aAAa;IAKnB;;;;;;;;;;;;;OAaG;IACI,cAAc,CACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,GAAG,wBAAwB,GACxC,eAAe;IAuBlB;;;;;;;;;;;;;OAaG;IACI,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,eAAe;CAuBpE"}

package/dist/batch/batch-processor.js

@@ -0,0 +1,102 @@
+import { BatchProcessor } from "@aws-lambda-powertools/batch";
+import { Status } from "../schema/log.js";
+import { extractOverridesFromBatchProcessor, getRecordId, normalizeEventBridgetEventBody, } from "../utils.js";
+/**
+ * Extended batch processor that automatically creates audit log entries
+ * for each record processed in a batch operation.
+ *
+ * Integrates with AWS Lambda Powertools BatchProcessor to provide
+ * automatic audit logging for SQS, Kinesis, and DynamoDB Streams events.
+ *
+ * @template Record - The type of event source record being processed
+ *
+ * @example
+ * ```typescript
+ * const processor = new AuditBatchProcessor(
+ *   EventType.SQS,
+ *   audits,
+ *   (record, overrides) => ({
+ *     operation: 'processMessage',
+ *     target: { app: 'MyApp', type: 'Message' },
+ *     ...overrides,
+ *   })
+ * );
+ * ```
+ */
+export class AuditBatchProcessor extends BatchProcessor {
+    audit;
+    createAuditItem;
+    /**
+     * Creates a new AuditBatchProcessor instance.
+     *
+     * @param eventType - The type of event source (SQS, Kinesis, or DynamoDB)
+     * @param audit - The Audits instance used to collect and publish audit logs
+     * @param createAuditItem - Factory function that creates an audit log entry from a record
+     */
+    constructor(eventType, audit, createAuditItem) {
+        super(eventType);
+        this.audit = audit;
+        this.createAuditItem = createAuditItem;
+    }
+    /**
+     * Handles successful record processing by creating a success audit entry.
+     *
+     * Called automatically by the batch processor when a record is processed
+     * without throwing an error. Creates an audit entry with SUCCESS status
+     * and excludes the original event data to reduce storage costs.
+     *
+     * The audit ID is automatically set from the record's unique identifier
+     * (messageId for SQS, eventID for Kinesis/DynamoDB) to enable retry correlation.
+     *
+     * @param record - The successfully processed record
+     * @param result - The result returned by the record handler, may include audit overrides
+     * @returns The success response from the parent BatchProcessor
+     */
+    successHandler(record, result) {
+        const auditItem = this.createAuditItem(record, {
+            status: Status.SUCCESS,
+            ...extractOverridesFromBatchProcessor(result),
+        });
+        // Auto-set ID for retry correlation using event record ID
+        const recordId = getRecordId(this.eventType, record);
+        if (recordId && !auditItem.id) {
+            auditItem.id = recordId;
+        }
+        this.audit.addAudit({
+            ...auditItem,
+            event: undefined, // Don't store event when successful
+        });
+        return super.successHandler(record, result);
+    }
+    /**
+     * Handles failed record processing by creating a failure audit entry.
+     *
+     * Called automatically by the batch processor when a record handler
+     * throws an error. Creates an audit entry with FAIL status, includes
+     * the original event data for debugging, and captures the error details.
+     *
+     * The audit ID is automatically set from the record's unique identifier
+     * (messageId for SQS, eventID for Kinesis/DynamoDB) to enable retry correlation.
+     *
+     * @param record - The record that failed processing
+     * @param error - The error thrown during processing
+     * @returns The failure response from the parent BatchProcessor
+     */
+    failureHandler(record, error) {
+        const auditItem = this.createAuditItem(record, {
+            status: Status.FAIL,
+            event: normalizeEventBridgetEventBody(this.eventType, record),
+            message: error.message,
+        });
+        // Auto-set ID for retry correlation using event record ID
+        const recordId = getRecordId(this.eventType, record);
+        if (recordId && !auditItem.id) {
+            auditItem.id = recordId;
+        }
+        this.audit.addAudit({
+            ...auditItem,
+            error,
+        });
+        return super.failureHandler(record, error);
+    }
+}

package/dist/batch/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./batch-processor.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/batch/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC"}

package/dist/batch/index.js

@@ -0,0 +1 @@
+export * from "./batch-processor.js";