@flipboxlabs/aws-audit-sdk 1.1.0

package/dist/repository.d.ts

@@ -0,0 +1,421 @@
+import type { Logger } from "@aws-lambda-powertools/logger";
+import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import type { NativeAttributeValue } from "@aws-sdk/util-dynamodb";
+import type { AuditConfig } from "./config.js";
+import { type Audit } from "./schema/audit.js";
+import { type Pagination } from "./schema/model.js";
+import type { UpsertAuditInput } from "./schema/service.js";
+import type { AnyApp, AnyResourceType, InferApp, InferResourceType } from "./types.js";
+/**
+ * DynamoDB TTL attribute structure.
+ */
+export interface TTLAttribute {
+    /** Unix timestamp in seconds when the item should expire */
+    ttl: number;
+}
+/**
+ * Generic type for unmarshalled DynamoDB attributes.
+ */
+export type UnmarshalledAttributes = {
+    [key: string]: NativeAttributeValue;
+};
+/**
+ * Identifiers used to locate audit records in DynamoDB.
+ * Used for constructing primary and secondary keys.
+ */
+export type Identifiers = {
+    /** Tenant/organization identifier for multi-tenancy support (optional) */
+    tenantId?: string;
+    /** Unique audit record identifier */
+    id: string | number;
+    /** Application that owns this audit record */
+    app: AnyApp;
+    /** Optional resource identifier within the application */
+    resourceId?: string | number;
+    /** Type of resource being audited */
+    resourceType: AnyResourceType;
+};
+/**
+ * Generic identifiers with typed App and ResourceType from config.
+ * @typeParam C - The audit config type for type inference
+ */
+export type TypedIdentifiers<C extends AuditConfig> = {
+    /** Tenant/organization identifier for multi-tenancy support (optional) */
+    tenantId?: string;
+    /** Unique audit record identifier */
+    id: string | number;
+    /** Application that owns this audit record */
+    app: InferApp<C>;
+    /** Optional resource identifier within the application */
+    resourceId?: string | number;
+    /** Type of resource being audited */
+    resourceType: InferResourceType<C>;
+};
+/**
+ * Options for listing audit items by resource with typed App and ResourceType.
+ * @typeParam C - The audit config type for type inference
+ */
+export type TypedListItemsOptions<C extends AuditConfig> = {
+    /** Tenant/organization identifier for multi-tenancy support (optional) */
+    tenantId?: string;
+    /** Resource identification */
+    resource: {
+        /** Type of the resource */
+        type: InferResourceType<C>;
+        /** Unique identifier of the resource */
+        id: string;
+    };
+    /** Application owning the resource */
+    app: InferApp<C>;
+};
+/**
+ * Options for listing audit items by trace ID with typed App and ResourceType.
+ * @typeParam C - The audit config type for type inference
+ */
+export type TypedListTraceItems<C extends AuditConfig> = {
+    /** Tenant/organization identifier for multi-tenancy support (optional) */
+    tenantId?: string;
+    /** Trace ID to query for related audit records */
+    trace: string;
+    /** Optional application filter */
+    app?: InferApp<C>;
+    /** Optional resource filter */
+    resource?: {
+        /** Filter by resource type */
+        type?: InferResourceType<C>;
+        /** Filter by resource ID */
+        id?: string;
+    };
+};
+/**
+ * Repository for managing audit records in DynamoDB.
+ *
+ * Provides CRUD operations for audit records with support for:
+ * - Single item retrieval by identifiers
+ * - Batch upsert operations with automatic batching
+ * - Paginated listing by resource
+ * - Paginated listing by trace ID for distributed tracing
+ *
+ * The repository uses a single-table design with composite keys and
+ * multiple GSI/LSI indexes for efficient query patterns.
+ *
+ * @typeParam C - The audit config type for type inference
+ *
+ * @example
+ * ```typescript
+ * const config = defineAuditConfig({
+ *   apps: ['Orders', 'Inventory'] as const,
+ *   resourceTypes: ['Order', 'Product'] as const,
+ * });
+ * const repository = new AuditRepository(logger, config);
+ *
+ * // Get a single audit record - typed!
+ * const audit = await repository.getItem({
+ *   id: 'audit-123',
+ *   app: 'Orders',           // TypeScript knows valid values
+ *   resourceType: 'Order',   // Autocomplete works
+ * });
+ *
+ * // Upsert multiple audit records
+ * await repository.upsertBatch([
+ *   { operation: 'createUser', status: 'success', ... },
+ *   { operation: 'updateUser', status: 'success', ... },
+ * ]);
+ *
+ * // List audits for a specific resource
+ * const { items, pagination } = await repository.listItems({
+ *   app: 'Orders',
+ *   resource: { type: 'Order', id: 'user-123' },
+ * });
+ * ```
+ */
+export declare class AuditRepository<C extends AuditConfig> {
+    private readonly logger;
+    private readonly config;
+    private readonly client;
+    /**
+     * Creates a new AuditRepository instance.
+     *
+     * @param logger - Logger instance for error reporting and debugging
+     * @param config - Audit configuration for type inference
+     * @param client - DynamoDB client (defaults to new instance with AWS_REGION from environment)
+     */
+    constructor(logger: Logger, config: C, client?: DynamoDBClient);
+    /**
+     * Retrieves a single audit record by its identifiers.
+     *
+     * Performs a DynamoDB GetItem operation using the constructed primary key.
+     * Returns undefined if the item is not found or if an error occurs.
+     *
+     * @param identifiers - Object containing id, app, and resourceType to locate the record
+     * @returns The audit record if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const audit = await repository.getItem({
+     *   id: 'audit-123',
+     *   app: 'Orders',
+     *   resourceType: 'Order',
+     * });
+     *
+     * if (audit) {
+     *   console.log('Found audit:', audit.operation);
+     * }
+     * ```
+     */
+    getItem(identifiers: Omit<TypedIdentifiers<C>, "resourceId">): Promise<Audit | undefined>;
+    /**
+     * Upserts multiple audit records in batch.
+     *
+     * Performs a DynamoDB BatchWriteItem operation, automatically chunking
+     * items into batches of 25 (DynamoDB's maximum batch size).
+     * Each item is enriched with:
+     * - Primary keys (PK, SK)
+     * - Secondary index keys (GSI1_SS, GSI1_SN, LSI1_N)
+     * - TTL attribute (90 days from creation)
+     * - Timestamps (createdAt, updatedAt)
+     *
+     * @param items - Array of audit records to upsert
+     * @returns True when the operation completes (does not check for unprocessed items)
+     *
+     * @example
+     * ```typescript
+     * await repository.upsertBatch([
+     *   {
+     *     operation: 'createUser',
+     *     status: 'success',
+     *     tier: 2,
+     *     target: { app: App.App1, type: ResourceType.USER, id: 'user-123' },
+     *   },
+     *   {
+     *     operation: 'updateUser',
+     *     status: 'success',
+     *     tier: 2,
+     *     target: { app: App.App1, type: ResourceType.USER, id: 'user-456' },
+     *   },
+     * ]);
+     * ```
+     */
+    upsertBatch(items: Array<UpsertAuditInput>): Promise<boolean>;
+    /**
+     * Lists audit records for a specific resource with pagination.
+     *
+     * Queries the GSI1_SS index to efficiently retrieve all audits
+     * associated with a specific app/resource combination.
+     * Results are returned in reverse chronological order.
+     *
+     * @param params - Query parameters including app and resource identifiers
+     * @param pagination - Optional pagination settings (pageSize, nextToken)
+     * @returns Paginated collection of audit records
+     *
+     * @example
+     * ```typescript
+     * // Get first page
+     * const page1 = await repository.listItems({
+     *   app: 'Orders',
+     *   resource: { type: 'Order', id: 'user-123' },
+     * });
+     *
+     * // Get next page using the pagination token
+     * const page2 = await repository.listItems(
+     *   { app: 'Orders', resource: { type: 'Order', id: 'user-123' } },
+     *   { nextToken: page1.pagination?.nextToken },
+     * );
+     * ```
+     */
+    listItems(params: TypedListItemsOptions<C>, pagination?: Pagination): Promise<{
+        items: {
+            id: string;
+            status: "success" | "warn" | "fail" | "skip";
+            tier: number;
+            target: {
+                app: string;
+                type: string;
+                id?: string | number | undefined;
+            };
+            operation: string;
+            tenantId?: string | undefined;
+            source?: {
+                app: string;
+                type: string;
+                id?: string | number | undefined;
+            } | undefined;
+            context?: Record<string, string | number | boolean | {
+                [key: string]: string | number | boolean | /*elided*/ any;
+            }> | undefined;
+            message?: string | undefined;
+            rerunable?: boolean | undefined;
+            trace?: string | undefined;
+            event?: {
+                detail: string | undefined;
+                source?: string | undefined;
+                "detail-type"?: string | undefined;
+            } | undefined;
+            error?: any;
+            attempts?: {
+                number: number;
+                status: "success" | "warn" | "fail" | "skip";
+                at: string;
+                error?: any;
+            }[] | undefined;
+        }[];
+        pagination?: {
+            pageSize?: string | number | null | undefined;
+            nextToken?: string | null | undefined;
+        } | undefined;
+    }>;
+    /**
+     * Lists audit records by trace ID for distributed tracing.
+     *
+     * Queries the GSI1_SN index to retrieve all audits sharing
+     * the same trace ID, ordered by trace stage/depth.
+     * Supports optional filtering by app, resource type, and resource ID.
+     *
+     * This is useful for viewing the complete audit trail of a
+     * distributed operation across multiple services or resources.
+     *
+     * @param params - Query parameters including trace ID and optional filters
+     * @param pagination - Optional pagination settings (pageSize, nextToken)
+     * @returns Paginated collection of audit records in trace order
+     *
+     * @example
+     * ```typescript
+     * // Get all audits for a trace
+     * const trace = await repository.listTraceItems({
+     *   trace: 'trace-abc-123',
+     * });
+     *
+     * // Filter by app and resource type
+     * const filtered = await repository.listTraceItems({
+     *   trace: 'trace-abc-123',
+     *   app: 'Orders',
+     *   resource: { type: 'Order' },
+     * });
+     * ```
+     */
+    listTraceItems(params: TypedListTraceItems<C>, pagination?: Pagination): Promise<{
+        items: {
+            id: string;
+            status: "success" | "warn" | "fail" | "skip";
+            tier: number;
+            target: {
+                app: string;
+                type: string;
+                id?: string | number | undefined;
+            };
+            operation: string;
+            tenantId?: string | undefined;
+            source?: {
+                app: string;
+                type: string;
+                id?: string | number | undefined;
+            } | undefined;
+            context?: Record<string, string | number | boolean | {
+                [key: string]: string | number | boolean | /*elided*/ any;
+            }> | undefined;
+            message?: string | undefined;
+            rerunable?: boolean | undefined;
+            trace?: string | undefined;
+            event?: {
+                detail: string | undefined;
+                source?: string | undefined;
+                "detail-type"?: string | undefined;
+            } | undefined;
+            error?: any;
+            attempts?: {
+                number: number;
+                status: "success" | "warn" | "fail" | "skip";
+                at: string;
+                error?: any;
+            }[] | undefined;
+        }[];
+        pagination?: {
+            pageSize?: string | number | null | undefined;
+            nextToken?: string | null | undefined;
+        } | undefined;
+    }>;
+    /**
+     * Constructs the DynamoDB primary key from identifiers.
+     *
+     * When tenantId is provided, it prefixes the partition key for multi-tenant isolation.
+     *
+     * @param identifiers - Object containing tenantId (optional), app, id, and resourceType
+     * @returns Primary key object with PK and SK attributes
+     * @internal
+     */
+    private constructPrimaryKey;
+    /**
+     * Constructs all secondary index keys for an audit item.
+     *
+     * Includes:
+     * - LSI1_N: Tier-based sort key for priority ordering
+     * - GSI1_SS: Resource-based index keys
+     * - GSI1_SN: Trace-based index keys (if trace exists)
+     *
+     * @param item - The audit storage item
+     * @returns Object containing all secondary key attributes
+     * @internal
+     */
+    private constructSecondaryKeys;
+    /**
+     * Constructs GSI1_SS (String-String) index keys for resource-based queries.
+     *
+     * The partition key combines app, resourceType, and resourceId for
+     * efficient querying of all audits for a specific resource.
+     * When tenantId is provided, it prefixes the partition key for multi-tenant isolation.
+     *
+     * @param identifiers - Full identifiers including resourceId and optional tenantId
+     * @returns GSI1_SS key attributes
+     * @internal
+     */
+    private constructGSI1_SS;
+    /**
+     * Constructs GSI1_SN (String-Number) index keys for trace-based queries.
+     *
+     * Parses the trace string to extract the trace ID and stage number,
+     * enabling efficient querying of all audits in a distributed trace.
+     * When tenantId is provided, it prefixes the partition key for multi-tenant isolation.
+     *
+     * @param item - The audit storage item
+     * @returns GSI1_SN key attributes, or empty object if no trace
+     * @internal
+     */
+    private constructGSI1_SN;
+    /**
+     * Constructs the TTL attribute for automatic item expiration.
+     *
+     * @param ttlSeconds - Seconds until expiration (defaults to 90 days)
+     * @param date - Base date for TTL calculation (defaults to now)
+     * @returns TTL attribute with Unix timestamp in seconds
+     * @internal
+     */
+    private constructTTLAttribute;
+    /**
+     * Transforms a raw DynamoDB item into an Audit object.
+     *
+     * Reconstructs the trace string and extracts the clean ID
+     * from compound keys.
+     *
+     * @param item - Raw DynamoDB item with all keys
+     * @returns Parsed and validated Audit object
+     * @internal
+     */
+    private transformItem;
+    /**
+     * Transforms a trace listing item into an audit list item payload.
+     *
+     * @param item - Raw trace listing item from GSI1_SN query
+     * @returns Parsed audit list item payload
+     * @internal
+     */
+    private transformTraceListItem;
+    /**
+     * Transforms a resource listing item into an audit list item payload.
+     *
+     * @param item - Raw listing item from GSI1_SS query
+     * @returns Parsed audit list item payload
+     * @internal
+     */
+    private transformListItem;
+}
+//# sourceMappingURL=repository.d.ts.map

package/dist/repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../src/repository.ts"],"names":[],"mappings":"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"}