@flipboxlabs/aws-audit-sdk 1.1.0

package/dist/schema/service.d.ts

@@ -0,0 +1,189 @@
+import * as z from "zod/v4";
+/**
+ * Schema for audit upsert operations via the AuditService.
+ *
+ * Extends _BaseLogAuditSchema with additional fields for service-layer operations:
+ * - `id`: Optional identifier (auto-generated if not provided)
+ * - `rerunable`: Flag indicating if the audit's operation can be retried
+ * - `attempts`: History of execution attempts for retry tracking
+ * - `createdAt`: Original creation timestamp (preserved on retries)
+ *
+ * This schema is used by {@link AuditService.upsertItem} for validating
+ * audit entries before storage and event emission.
+ *
+ * @example
+ * ```typescript
+ * const audit = UpsertAuditSchema.parse({
+ *   operation: 'processPayment',
+ *   target: { app: 'Payments', type: 'Payment', id: 'pay-123' },
+ *   status: 'success',
+ *   rerunable: true,
+ *   event: {
+ *     source: 'payments.service',
+ *     'detail-type': 'PaymentRequested',
+ *     detail: { amount: 99.99 },
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With explicit ID for idempotent upserts
+ * const audit = UpsertAuditSchema.parse({
+ *   id: 'idempotent-key-123',
+ *   operation: 'createOrder',
+ *   target: { app: 'Orders', type: 'Order', id: 'order-456' },
+ *   status: 'success',
+ * });
+ * ```
+ */
+export declare const UpsertAuditSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    rerunable: z.ZodOptional<z.ZodBoolean>;
+    attempts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        number: z.ZodNumber;
+        status: z.ZodEnum<{
+            success: "success";
+            warn: "warn";
+            fail: "fail";
+            skip: "skip";
+        }>;
+        error: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<any, string>>, z.ZodPipe<z.ZodCustom<Error, Error>, z.ZodTransform<any, Error>>, z.ZodRecord<z.ZodAny, z.ZodAny>]>>;
+        at: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodISODateTime, z.ZodCustom<Date, Date>]>, z.ZodTransform<string, string | Date>>>;
+    }, z.core.$strip>>>;
+    createdAt: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodISODateTime, z.ZodCustom<Date, Date>]>, z.ZodTransform<string, string | Date>>>;
+    operation: z.ZodString;
+    tenantId: z.ZodOptional<z.ZodString>;
+    tier: z.ZodDefault<z.ZodNumber>;
+    status: z.ZodDefault<z.ZodEnum<{
+        success: "success";
+        warn: "warn";
+        fail: "fail";
+        skip: "skip";
+    }>>;
+    target: z.ZodObject<{
+        app: z.ZodString;
+        id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        type: z.ZodString;
+    }, z.core.$strip>;
+    source: z.ZodOptional<z.ZodObject<{
+        app: z.ZodString;
+        id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        type: z.ZodString;
+    }, z.core.$strip>>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<string | number | boolean | {
+        [key: string]: string | number | boolean | /*elided*/ any;
+    }, unknown, z.core.$ZodTypeInternals<string | number | boolean | {
+        [key: string]: string | number | boolean | /*elided*/ any;
+    }, unknown>>>>;
+    resources: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
+        app: z.ZodString;
+        type: z.ZodString;
+        id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    }, z.core.$strip>>, z.ZodSet<z.ZodObject<{
+        app: z.ZodString;
+        type: z.ZodString;
+        id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    }, z.core.$strip>>]>>, z.ZodTransform<{
+        app: string;
+        type: string;
+        id?: string | number | undefined;
+    }[] | undefined, Set<{
+        app: string;
+        type: string;
+        id?: string | number | undefined;
+    }> | {
+        app: string;
+        type: string;
+        id?: string | number | undefined;
+    }[] | undefined>>;
+    message: z.ZodOptional<z.ZodString>;
+    trace: z.ZodOptional<z.ZodString>;
+    event: z.ZodOptional<z.ZodObject<{
+        source: z.ZodOptional<z.ZodString>;
+        "detail-type": z.ZodOptional<z.ZodString>;
+        detail: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodAny>]>>, z.ZodTransform<string | undefined, string | Record<string, any> | undefined>>;
+    }, z.core.$strip>>;
+    error: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<Error, Error>]>>, z.ZodTransform<string | undefined, string | Error | undefined>>;
+}, z.core.$strip>;
+/**
+ * Input type for UpsertAuditSchema.
+ *
+ * Use this type when building audit objects for upsert operations.
+ */
+export type UpsertAuditInput = z.input<typeof UpsertAuditSchema>;
+/**
+ * Output type from UpsertAuditSchema.
+ *
+ * Validated and transformed audit ready for storage.
+ */
+export type UpsertAudit = z.output<typeof UpsertAuditSchema>;
+/**
+ * Creates a UpsertAuditSchema with typed app and resourceType schemas.
+ *
+ * Use this when you have a config with strict app/resourceType enums
+ * to get runtime validation against those specific values.
+ *
+ * @param resourceReferenceSchema - The typed resource reference schema from config.schemas.resourceReference
+ * @returns A UpsertAuditSchema that validates against the provided resource reference schema
+ *
+ * @example
+ * ```typescript
+ * const config = defineAuditConfig({
+ *   apps: ['Orders', 'Inventory'] as const,
+ *   resourceTypes: ['Order', 'Product'] as const,
+ * });
+ *
+ * const typedSchema = createTypedUpsertAuditSchema(config.schemas.resourceReference);
+ * typedSchema.parse({
+ *   operation: 'createOrder',
+ *   target: { app: 'Orders', type: 'Order', id: '123' },
+ * }); // Validates app/type against config
+ * ```
+ */
+export declare function createTypedUpsertAuditSchema<T extends z.ZodObject<{
+    app: z.ZodTypeAny;
+    type: z.ZodTypeAny;
+    id: z.ZodTypeAny;
+}>>(resourceReferenceSchema: T): z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    rerunable: z.ZodOptional<z.ZodBoolean>;
+    attempts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        number: z.ZodNumber;
+        status: z.ZodEnum<{
+            success: "success";
+            warn: "warn";
+            fail: "fail";
+            skip: "skip";
+        }>;
+        error: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<any, string>>, z.ZodPipe<z.ZodCustom<Error, Error>, z.ZodTransform<any, Error>>, z.ZodRecord<z.ZodAny, z.ZodAny>]>>;
+        at: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodISODateTime, z.ZodCustom<Date, Date>]>, z.ZodTransform<string, string | Date>>>;
+    }, z.core.$strip>>>;
+    createdAt: z.ZodOptional<z.ZodPipe<z.ZodUnion<readonly [z.ZodISODateTime, z.ZodCustom<Date, Date>]>, z.ZodTransform<string, string | Date>>>;
+    operation: z.ZodString;
+    tenantId: z.ZodOptional<z.ZodString>;
+    tier: z.ZodDefault<z.ZodNumber>;
+    status: z.ZodDefault<z.ZodEnum<{
+        success: "success";
+        warn: "warn";
+        fail: "fail";
+        skip: "skip";
+    }>>;
+    target: T;
+    source: z.ZodOptional<T>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<string | number | boolean | {
+        [key: string]: string | number | boolean | /*elided*/ any;
+    }, unknown, z.core.$ZodTypeInternals<string | number | boolean | {
+        [key: string]: string | number | boolean | /*elided*/ any;
+    }, unknown>>>>;
+    resources: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<T>, z.ZodSet<T>]>>, z.ZodTransform<z.core.output<T>[] | undefined, z.core.output<T>[] | Set<z.core.output<T>> | undefined>>;
+    message: z.ZodOptional<z.ZodString>;
+    trace: z.ZodOptional<z.ZodString>;
+    event: z.ZodOptional<z.ZodObject<{
+        source: z.ZodOptional<z.ZodString>;
+        "detail-type": z.ZodOptional<z.ZodString>;
+        detail: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodAny>]>>, z.ZodTransform<string | undefined, string | Record<string, any> | undefined>>;
+    }, z.core.$strip>>;
+    error: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodCustom<Error, Error>]>>, z.ZodTransform<string | undefined, string | Error | undefined>>;
+}, z.core.$strip>;
+//# sourceMappingURL=service.d.ts.map

package/dist/schema/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/schema/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAI5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAU5B,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAEjE;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,4BAA4B,CAC3C,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC;IACrB,GAAG,EAAE,CAAC,CAAC,UAAU,CAAC;IAClB,IAAI,EAAE,CAAC,CAAC,UAAU,CAAC;IACnB,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC;CACjB,CAAC,EACD,uBAAuB,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAc3B"}

package/dist/schema/service.js

@@ -0,0 +1,89 @@
+import * as z from "zod/v4";
+import { AttemptSchema, DateTimeStringSchema } from "./common.js";
+import { _BaseLogAuditSchema, createTypedLogAuditSchema } from "./log.js";
+/**
+ * Schema for audit upsert operations via the AuditService.
+ *
+ * Extends _BaseLogAuditSchema with additional fields for service-layer operations:
+ * - `id`: Optional identifier (auto-generated if not provided)
+ * - `rerunable`: Flag indicating if the audit's operation can be retried
+ * - `attempts`: History of execution attempts for retry tracking
+ * - `createdAt`: Original creation timestamp (preserved on retries)
+ *
+ * This schema is used by {@link AuditService.upsertItem} for validating
+ * audit entries before storage and event emission.
+ *
+ * @example
+ * ```typescript
+ * const audit = UpsertAuditSchema.parse({
+ *   operation: 'processPayment',
+ *   target: { app: 'Payments', type: 'Payment', id: 'pay-123' },
+ *   status: 'success',
+ *   rerunable: true,
+ *   event: {
+ *     source: 'payments.service',
+ *     'detail-type': 'PaymentRequested',
+ *     detail: { amount: 99.99 },
+ *   },
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With explicit ID for idempotent upserts
+ * const audit = UpsertAuditSchema.parse({
+ *   id: 'idempotent-key-123',
+ *   operation: 'createOrder',
+ *   target: { app: 'Orders', type: 'Order', id: 'order-456' },
+ *   status: 'success',
+ * });
+ * ```
+ */
+export const UpsertAuditSchema = z.object({
+    ..._BaseLogAuditSchema.shape,
+    /** Optional audit ID - auto-generated if not provided */
+    id: z.string().optional(),
+    /** Whether the audited operation can be re-run/retried */
+    rerunable: z.boolean().optional(),
+    /** History of execution attempts for retry tracking */
+    attempts: z.array(AttemptSchema).optional(),
+    /** Original creation timestamp (preserved on retries) */
+    createdAt: DateTimeStringSchema.optional(),
+});
+/**
+ * Creates a UpsertAuditSchema with typed app and resourceType schemas.
+ *
+ * Use this when you have a config with strict app/resourceType enums
+ * to get runtime validation against those specific values.
+ *
+ * @param resourceReferenceSchema - The typed resource reference schema from config.schemas.resourceReference
+ * @returns A UpsertAuditSchema that validates against the provided resource reference schema
+ *
+ * @example
+ * ```typescript
+ * const config = defineAuditConfig({
+ *   apps: ['Orders', 'Inventory'] as const,
+ *   resourceTypes: ['Order', 'Product'] as const,
+ * });
+ *
+ * const typedSchema = createTypedUpsertAuditSchema(config.schemas.resourceReference);
+ * typedSchema.parse({
+ *   operation: 'createOrder',
+ *   target: { app: 'Orders', type: 'Order', id: '123' },
+ * }); // Validates app/type against config
+ * ```
+ */
+export function createTypedUpsertAuditSchema(resourceReferenceSchema) {
+    const typedLogSchema = createTypedLogAuditSchema(resourceReferenceSchema);
+    return z.object({
+        ...typedLogSchema.shape,
+        /** Optional audit ID - auto-generated if not provided */
+        id: z.string().optional(),
+        /** Whether the audited operation can be re-run/retried */
+        rerunable: z.boolean().optional(),
+        /** History of execution attempts for retry tracking */
+        attempts: z.array(AttemptSchema).optional(),
+        /** Original creation timestamp (preserved on retries) */
+        createdAt: DateTimeStringSchema.optional(),
+    });
+}

package/dist/schema/storage.d.ts

@@ -0,0 +1,105 @@
+import * as z from "zod/v4";
+/**
+ * Schema for audit records being written to DynamoDB storage.
+ *
+ * Extends BaseSchema with storage-specific fields and transformations:
+ * - `id`: Auto-generated KSUID if not provided
+ * - `updatedAt`: Defaults to current time, normalized to ISO string
+ * - `createdAt`: Defaults to current time, normalized to ISO string
+ *
+ * This schema handles the conversion between application types (Date)
+ * and storage types (ISO string) for DynamoDB compatibility.
+ *
+ * @example
+ * ```typescript
+ * // With auto-generated values
+ * const storage = AuditStorageSchema.parse({
+ *   operation: 'createUser',
+ *   status: 'success',
+ *   target: { app: 'MyApp', type: 'User', id: 'user-123' },
+ *   tier: 2,
+ * });
+ * // storage.id is auto-generated KSUID
+ * // storage.updatedAt is current time as ISO string
+ * // storage.createdAt is current time as ISO string
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With explicit Date objects
+ * const storage = AuditStorageSchema.parse({
+ *   id: 'custom-id',
+ *   operation: 'updateUser',
+ *   status: 'success',
+ *   target: { app: 'MyApp', type: 'User', id: 'user-123' },
+ *   tier: 2,
+ *   updatedAt: new Date(),
+ *   createdAt: new Date('2024-01-01'),
+ * });
+ * // Dates are converted to ISO strings
+ * ```
+ */
+export declare const AuditStorageSchema: z.ZodObject<{
+    id: z.ZodDefault<z.ZodString>;
+    updatedAt: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodISODateTime, z.ZodCustom<Date, Date>]>, z.ZodTransform<string, string | Date>>>;
+    createdAt: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodISODateTime, z.ZodCustom<Date, Date>]>, z.ZodTransform<string, string | Date>>>;
+    tenantId: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        success: "success";
+        warn: "warn";
+        fail: "fail";
+        skip: "skip";
+    }>;
+    tier: z.ZodDefault<z.ZodNumber>;
+    target: z.ZodObject<{
+        app: z.ZodString;
+        id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        type: z.ZodString;
+    }, z.core.$strip>;
+    source: z.ZodOptional<z.ZodObject<{
+        app: z.ZodString;
+        id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        type: z.ZodString;
+    }, z.core.$strip>>;
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<string | number | boolean | {
+        [key: string]: string | number | boolean | /*elided*/ any;
+    }, unknown, z.core.$ZodTypeInternals<string | number | boolean | {
+        [key: string]: string | number | boolean | /*elided*/ any;
+    }, unknown>>>>;
+    operation: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+    rerunable: z.ZodOptional<z.ZodBoolean>;
+    trace: z.ZodOptional<z.ZodString>;
+    event: z.ZodOptional<z.ZodObject<{
+        source: z.ZodOptional<z.ZodString>;
+        "detail-type": z.ZodOptional<z.ZodString>;
+        detail: z.ZodPipe<z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodAny>]>>, z.ZodTransform<string | undefined, string | Record<string, any> | undefined>>;
+    }, z.core.$strip>>;
+    error: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<any, string>>, z.ZodPipe<z.ZodCustom<Error, Error>, z.ZodTransform<any, Error>>, z.ZodRecord<z.ZodAny, z.ZodAny>]>>;
+    attempts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        number: z.ZodNumber;
+        status: z.ZodEnum<{
+            success: "success";
+            warn: "warn";
+            fail: "fail";
+            skip: "skip";
+        }>;
+        error: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<any, string>>, z.ZodPipe<z.ZodCustom<Error, Error>, z.ZodTransform<any, Error>>, z.ZodRecord<z.ZodAny, z.ZodAny>]>>;
+        at: z.ZodDefault<z.ZodPipe<z.ZodUnion<readonly [z.ZodISODateTime, z.ZodCustom<Date, Date>]>, z.ZodTransform<string, string | Date>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * Input type for AuditStorageSchema.
+ *
+ * Accepts Date objects or ISO strings for timestamps.
+ * ID is optional (auto-generated if not provided).
+ */
+export type AuditStorageInput = z.input<typeof AuditStorageSchema>;
+/**
+ * Output type from AuditStorageSchema.
+ *
+ * All timestamps are ISO strings, ID is always present.
+ * Ready for DynamoDB storage.
+ */
+export type AuditStorage = z.output<typeof AuditStorageSchema>;
+//# sourceMappingURL=storage.d.ts.map

package/dist/schema/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/schema/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAI5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmB7B,CAAC;AAEH;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/schema/storage.js

@@ -0,0 +1,63 @@
+import * as z from "zod/v4";
+import { generateAuditId } from "../utils.js";
+import { BaseSchema, DateTimeStringSchema } from "./common.js";
+/**
+ * Schema for audit records being written to DynamoDB storage.
+ *
+ * Extends BaseSchema with storage-specific fields and transformations:
+ * - `id`: Auto-generated KSUID if not provided
+ * - `updatedAt`: Defaults to current time, normalized to ISO string
+ * - `createdAt`: Defaults to current time, normalized to ISO string
+ *
+ * This schema handles the conversion between application types (Date)
+ * and storage types (ISO string) for DynamoDB compatibility.
+ *
+ * @example
+ * ```typescript
+ * // With auto-generated values
+ * const storage = AuditStorageSchema.parse({
+ *   operation: 'createUser',
+ *   status: 'success',
+ *   target: { app: 'MyApp', type: 'User', id: 'user-123' },
+ *   tier: 2,
+ * });
+ * // storage.id is auto-generated KSUID
+ * // storage.updatedAt is current time as ISO string
+ * // storage.createdAt is current time as ISO string
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With explicit Date objects
+ * const storage = AuditStorageSchema.parse({
+ *   id: 'custom-id',
+ *   operation: 'updateUser',
+ *   status: 'success',
+ *   target: { app: 'MyApp', type: 'User', id: 'user-123' },
+ *   tier: 2,
+ *   updatedAt: new Date(),
+ *   createdAt: new Date('2024-01-01'),
+ * });
+ * // Dates are converted to ISO strings
+ * ```
+ */
+export const AuditStorageSchema = z.object({
+    ...BaseSchema.shape,
+    /**
+     * Unique audit identifier.
+     * Auto-generates a KSUID if not provided.
+     */
+    id: z.string().default(generateAuditId()),
+    /**
+     * Last update timestamp.
+     * Accepts ISO string or Date, outputs ISO string.
+     * Defaults to current time.
+     */
+    updatedAt: DateTimeStringSchema.default(() => new Date().toISOString()),
+    /**
+     * Creation timestamp.
+     * Accepts ISO string or Date, outputs ISO string.
+     * Defaults to current time.
+     */
+    createdAt: DateTimeStringSchema.default(() => new Date().toISOString()),
+});