@geekmidas/constructs 0.0.22 → 0.1.0

package/dist/processAudits-CzHkPokQ.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"processAudits-CzHkPokQ.cjs","names":["endpoint: Endpoint<\n    any,\n    any,\n    any,\n    OutSchema,\n    TServices,\n    TLogger,\n    TSession,\n    any,\n    any,\n    TAuditStorage,\n    TAuditStorageServiceName,\n    TAuditAction\n  >","response: InferStandardSchema<OutSchema>","serviceDiscovery: ServiceDiscovery<any, any>","logger: TLogger","ctx: {\n    session: TSession;\n    header: HeaderFn;\n    cookie: CookieFn;\n    services: Record<string, unknown>;\n  }","existingAuditor?: Auditor<TAuditAction>","auditor: Auditor<TAuditAction>","actor: AuditActor","DefaultAuditor","endpoint: Endpoint<\n    any,\n    any,\n    any,\n    any,\n    TServices,\n    TLogger,\n    TSession,\n    any,\n    any,\n    TAuditStorage,\n    TAuditStorageServiceName,\n    TAuditAction,\n    TDatabase,\n    TDatabaseServiceName\n  >","auditContext: AuditExecutionContext<TAuditAction> | undefined","handler: (auditor?: Auditor<TAuditAction>) => Promise<T>","onComplete?: (response: T, auditor: Auditor<TAuditAction>) => Promise<void>","options?: ExecuteWithAuditTransactionOptions","response"],"sources":["../src/endpoints/processAudits.ts"],"sourcesContent":["import type {\n  AuditActor,\n  AuditStorage,\n  AuditableAction,\n  Auditor,\n} from '@geekmidas/audit';\nimport { DefaultAuditor } from '@geekmidas/audit';\nimport type { Logger } from '@geekmidas/logger';\nimport type { InferStandardSchema } from '@geekmidas/schema';\nimport type { Service, ServiceDiscovery } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { CookieFn, Endpoint, HeaderFn } from './Endpoint';\nimport type { ActorExtractor, MappedAudit } from './audit';\n\n/**\n * Process declarative audit definitions after successful endpoint execution.\n * Similar to publishConstructEvents for events.\n *\n * @param endpoint - The endpoint with audit configuration\n * @param response - The handler response to generate audit payloads from\n * @param serviceDiscovery - Service discovery for registering audit storage\n * @param logger - Logger for debug/error messages\n * @param ctx - Request context (session, headers, cookies, services)\n * @param existingAuditor - Optional existing auditor instance (e.g., from handler context).\n *                          If provided, uses this auditor (with its stored transaction).\n *                          If not provided, creates a new auditor.\n */\nexport async function processEndpointAudits<\n  TServices extends Service[] = [],\n  TSession = unknown,\n  TLogger extends Logger = Logger,\n  OutSchema extends StandardSchemaV1 | undefined = undefined,\n  TAuditStorage extends AuditStorage | undefined = undefined,\n  TAuditStorageServiceName extends string = string,\n  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n    string,\n    unknown\n  >,\n>(\n  endpoint: Endpoint<\n    any,\n    any,\n    any,\n    OutSchema,\n    TServices,\n    TLogger,\n    TSession,\n    any,\n    any,\n    TAuditStorage,\n    TAuditStorageServiceName,\n    TAuditAction\n  >,\n  response: InferStandardSchema<OutSchema>,\n  serviceDiscovery: ServiceDiscovery<any, any>,\n  logger: TLogger,\n  ctx: {\n    session: TSession;\n    header: HeaderFn;\n    cookie: CookieFn;\n    services: Record<string, unknown>;\n  },\n  existingAuditor?: Auditor<TAuditAction>,\n): Promise<void> {\n  try {\n    const audits = endpoint.audits as MappedAudit<TAuditAction, OutSchema>[];\n\n    // If we have an existing auditor (from handler context), we need to flush\n    // any manual audits it collected, even if there are no declarative audits\n    const hasExistingRecords =\n      existingAuditor && existingAuditor.getRecords().length > 0;\n\n    // Skip if no declarative audits and no existing records to flush\n    if (!audits?.length && !hasExistingRecords) {\n      logger.debug('No audits to process');\n      return;\n    }\n\n    // If no auditor storage service and we have things to process, warn\n    if (!endpoint.auditorStorageService) {\n      if (hasExistingRecords || audits?.length) {\n        logger.warn('No auditor storage service available');\n      }\n      return;\n    }\n\n    // Get or create auditor\n    let auditor: Auditor<TAuditAction>;\n\n    if (existingAuditor) {\n      // Use existing auditor (preserves stored transaction and manual audits)\n      auditor = existingAuditor;\n      logger.debug('Using existing auditor from handler context');\n    } else {\n      // Create new auditor (backward compatibility)\n      const services = await serviceDiscovery.register([\n        endpoint.auditorStorageService,\n      ]);\n      const storage = services[\n        endpoint.auditorStorageService.serviceName\n      ] as AuditStorage;\n\n      // Extract actor if configured\n      let actor: AuditActor = { id: 'system', type: 'system' };\n      if (endpoint.actorExtractor) {\n        try {\n          actor = await (\n            endpoint.actorExtractor as ActorExtractor<\n              TServices,\n              TSession,\n              TLogger\n            >\n          )({\n            services: ctx.services as any,\n            session: ctx.session,\n            header: ctx.header,\n            cookie: ctx.cookie,\n            logger,\n          });\n        } catch (error) {\n          logger.error(error as Error, 'Failed to extract actor for audits');\n          // Continue with system actor\n        }\n      }\n\n      auditor = new DefaultAuditor<TAuditAction>({\n        actor,\n        storage,\n        metadata: {\n          endpoint: endpoint.route,\n          method: endpoint.method,\n        },\n      });\n    }\n\n    // Process each declarative audit\n    if (audits?.length) {\n      for (const audit of audits) {\n        logger.debug({ audit: audit.type }, 'Processing declarative audit');\n\n        // Check when condition\n        if (audit.when && !audit.when(response as any)) {\n          logger.debug(\n            { audit: audit.type },\n            'Audit skipped due to when condition',\n          );\n          continue;\n        }\n\n        // Extract payload\n        const payload = audit.payload(response as any);\n\n        // Extract entityId if configured\n        const entityId = audit.entityId?.(response as any);\n\n        // Record the audit\n        auditor.audit(audit.type as any, payload as any, {\n          table: audit.table,\n          entityId,\n        });\n      }\n    }\n\n    // Flush audits to storage\n    // Note: If existingAuditor has a stored transaction (via setTransaction),\n    // flush() will use it automatically\n    const recordCount = auditor.getRecords().length;\n    if (recordCount > 0) {\n      // Check if auditor has a stored transaction (for logging purposes)\n      const trx =\n        'getTransaction' in auditor\n          ? (auditor as { getTransaction(): unknown }).getTransaction()\n          : undefined;\n      logger.debug(\n        { auditCount: recordCount, hasTransaction: !!trx },\n        'Flushing audits',\n      );\n      await auditor.flush();\n    }\n  } catch (error) {\n    logger.error(error as Error, 'Failed to process audits');\n    // Don't rethrow - audit failures shouldn't fail the request\n  }\n}\n\n/**\n * Context for audit-aware handler execution.\n */\nexport interface AuditExecutionContext<\n  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n    string,\n    unknown\n  >,\n> {\n  /** The auditor instance for recording audits */\n  auditor: Auditor<TAuditAction>;\n  /** The audit storage instance */\n  storage: AuditStorage;\n}\n\n/**\n * Create audit context for handler execution.\n * Returns the auditor and storage for use in the handler.\n *\n * @param endpoint - The endpoint with audit configuration\n * @param serviceDiscovery - Service discovery for getting audit storage\n * @param logger - Logger for debug/error messages\n * @param ctx - Request context for actor extraction\n * @returns Audit context with auditor and storage, or undefined if not configured\n */\nexport async function createAuditContext<\n  TServices extends Service[] = [],\n  TSession = unknown,\n  TLogger extends Logger = Logger,\n  TAuditStorage extends AuditStorage | undefined = undefined,\n  TAuditStorageServiceName extends string = string,\n  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n    string,\n    unknown\n  >,\n  TDatabase = undefined,\n  TDatabaseServiceName extends string = string,\n>(\n  endpoint: Endpoint<\n    any,\n    any,\n    any,\n    any,\n    TServices,\n    TLogger,\n    TSession,\n    any,\n    any,\n    TAuditStorage,\n    TAuditStorageServiceName,\n    TAuditAction,\n    TDatabase,\n    TDatabaseServiceName\n  >,\n  serviceDiscovery: ServiceDiscovery<any, any>,\n  logger: TLogger,\n  ctx: {\n    session: TSession;\n    header: HeaderFn;\n    cookie: CookieFn;\n    services: Record<string, unknown>;\n  },\n): Promise<AuditExecutionContext<TAuditAction> | undefined> {\n  if (!endpoint.auditorStorageService) {\n    return undefined;\n  }\n\n  const services = await serviceDiscovery.register([\n    endpoint.auditorStorageService,\n  ]);\n  const storage = services[\n    endpoint.auditorStorageService.serviceName\n  ] as AuditStorage;\n\n  // Extract actor if configured\n  let actor: AuditActor = { id: 'system', type: 'system' };\n  if (endpoint.actorExtractor) {\n    try {\n      actor = await (\n        endpoint.actorExtractor as ActorExtractor<TServices, TSession, TLogger>\n      )({\n        services: ctx.services as any,\n        session: ctx.session,\n        header: ctx.header,\n        cookie: ctx.cookie,\n        logger,\n      });\n    } catch (error) {\n      logger.error(error as Error, 'Failed to extract actor for audits');\n    }\n  }\n\n  const auditor = new DefaultAuditor<TAuditAction>({\n    actor,\n    storage,\n    metadata: {\n      endpoint: endpoint.route,\n      method: endpoint.method,\n    },\n  });\n\n  return { auditor, storage };\n}\n\n/**\n * Options for executeWithAuditTransaction.\n */\nexport interface ExecuteWithAuditTransactionOptions {\n  /**\n   * Database connection to use for the transaction.\n   * If this is already a transaction, it will be reused instead of creating a nested one.\n   * If not provided, the storage's internal database is used.\n   */\n  db?: unknown;\n}\n\n/**\n * Execute a handler with automatic audit transaction support.\n * If the audit storage provides a withTransaction method, wraps execution\n * in a transaction so audits are atomic with handler's database operations.\n *\n * This is database-agnostic - each storage implementation provides its own\n * transaction handling based on the underlying database (Kysely, Drizzle, etc.).\n *\n * If the db parameter is provided and is already a transaction, the storage\n * will reuse it instead of creating a nested transaction (similar to\n * packages/db/src/kysely.ts#withTransaction).\n *\n * @param auditContext - The audit context from createAuditContext\n * @param handler - The handler function to execute (receives auditor)\n * @param onComplete - Called after handler with response, to process declarative audits\n * @param options - Optional configuration including database connection\n * @returns The handler result\n */\nexport async function executeWithAuditTransaction<\n  T,\n  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n    string,\n    unknown\n  >,\n>(\n  auditContext: AuditExecutionContext<TAuditAction> | undefined,\n  handler: (auditor?: Auditor<TAuditAction>) => Promise<T>,\n  onComplete?: (response: T, auditor: Auditor<TAuditAction>) => Promise<void>,\n  options?: ExecuteWithAuditTransactionOptions,\n): Promise<T> {\n  // No audit context - just run handler\n  if (!auditContext) {\n    return handler(undefined);\n  }\n\n  const { auditor, storage } = auditContext;\n\n  // Check if storage provides a transaction wrapper\n  if (storage.withTransaction) {\n    // Wrap in transaction - audits are atomic with handler operations\n    // The storage's withTransaction handles setTransaction and flush\n    // Pass db so existing transactions are reused\n    return storage.withTransaction(\n      auditor,\n      async () => {\n        const response = await handler(auditor);\n\n        // Process declarative audits within the transaction\n        if (onComplete) {\n          await onComplete(response, auditor);\n        }\n\n        return response;\n      },\n      options?.db,\n    );\n  }\n\n  // No transaction support - run handler and flush audits after\n  const response = await handler(auditor);\n\n  if (onComplete) {\n    await onComplete(response, auditor);\n  }\n\n  // Flush audits (no transaction)\n  await auditor.flush();\n\n  return response;\n}\n"],"mappings":"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"}

package/dist/{processAudits-DfcB-X-4.mjs → processAudits-Dj8UGqcW.mjs}

@@ -1,5 +1,4 @@
 import { DefaultAuditor } from "@geekmidas/audit";
-import { withAuditableTransaction } from "@geekmidas/audit/kysely";
 
 //#region src/endpoints/processAudits.ts
 /**
@@ -128,23 +127,30 @@ async function createAuditContext(endpoint, serviceDiscovery, logger, ctx) {
 }
 /**
 * Execute a handler with automatic audit transaction support.
-* If the audit storage has a database (via getDatabase()), wraps execution
+* If the audit storage provides a withTransaction method, wraps execution
 * in a transaction so audits are atomic with handler's database operations.
 *
+* This is database-agnostic - each storage implementation provides its own
+* transaction handling based on the underlying database (Kysely, Drizzle, etc.).
+*
+* If the db parameter is provided and is already a transaction, the storage
+* will reuse it instead of creating a nested transaction (similar to
+* packages/db/src/kysely.ts#withTransaction).
+*
 * @param auditContext - The audit context from createAuditContext
 * @param handler - The handler function to execute (receives auditor)
 * @param onComplete - Called after handler with response, to process declarative audits
+* @param options - Optional configuration including database connection
 * @returns The handler result
 */
-async function executeWithAuditTransaction(auditContext, handler, onComplete) {
+async function executeWithAuditTransaction(auditContext, handler, onComplete, options) {
 	if (!auditContext) return handler(void 0);
 	const { auditor, storage } = auditContext;
-	const db = storage.getDatabase?.();
-	if (db) return withAuditableTransaction(db, auditor, async () => {
+	if (storage.withTransaction) return storage.withTransaction(auditor, async () => {
 		const response$1 = await handler(auditor);
 		if (onComplete) await onComplete(response$1, auditor);
 		return response$1;
-	});
+	}, options?.db);
 	const response = await handler(auditor);
 	if (onComplete) await onComplete(response, auditor);
 	await auditor.flush();
@@ -153,4 +159,4 @@ async function executeWithAuditTransaction(auditContext, handler, onComplete) {
 
 //#endregion
 export { createAuditContext, executeWithAuditTransaction, processEndpointAudits };
-//# sourceMappingURL=processAudits-DfcB-X-4.mjs.map
+//# sourceMappingURL=processAudits-Dj8UGqcW.mjs.map

package/dist/processAudits-Dj8UGqcW.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"processAudits-Dj8UGqcW.mjs","names":["endpoint: Endpoint<\n    any,\n    any,\n    any,\n    OutSchema,\n    TServices,\n    TLogger,\n    TSession,\n    any,\n    any,\n    TAuditStorage,\n    TAuditStorageServiceName,\n    TAuditAction\n  >","response: InferStandardSchema<OutSchema>","serviceDiscovery: ServiceDiscovery<any, any>","logger: TLogger","ctx: {\n    session: TSession;\n    header: HeaderFn;\n    cookie: CookieFn;\n    services: Record<string, unknown>;\n  }","existingAuditor?: Auditor<TAuditAction>","auditor: Auditor<TAuditAction>","actor: AuditActor","endpoint: Endpoint<\n    any,\n    any,\n    any,\n    any,\n    TServices,\n    TLogger,\n    TSession,\n    any,\n    any,\n    TAuditStorage,\n    TAuditStorageServiceName,\n    TAuditAction,\n    TDatabase,\n    TDatabaseServiceName\n  >","auditContext: AuditExecutionContext<TAuditAction> | undefined","handler: (auditor?: Auditor<TAuditAction>) => Promise<T>","onComplete?: (response: T, auditor: Auditor<TAuditAction>) => Promise<void>","options?: ExecuteWithAuditTransactionOptions","response"],"sources":["../src/endpoints/processAudits.ts"],"sourcesContent":["import type {\n  AuditActor,\n  AuditStorage,\n  AuditableAction,\n  Auditor,\n} from '@geekmidas/audit';\nimport { DefaultAuditor } from '@geekmidas/audit';\nimport type { Logger } from '@geekmidas/logger';\nimport type { InferStandardSchema } from '@geekmidas/schema';\nimport type { Service, ServiceDiscovery } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { CookieFn, Endpoint, HeaderFn } from './Endpoint';\nimport type { ActorExtractor, MappedAudit } from './audit';\n\n/**\n * Process declarative audit definitions after successful endpoint execution.\n * Similar to publishConstructEvents for events.\n *\n * @param endpoint - The endpoint with audit configuration\n * @param response - The handler response to generate audit payloads from\n * @param serviceDiscovery - Service discovery for registering audit storage\n * @param logger - Logger for debug/error messages\n * @param ctx - Request context (session, headers, cookies, services)\n * @param existingAuditor - Optional existing auditor instance (e.g., from handler context).\n *                          If provided, uses this auditor (with its stored transaction).\n *                          If not provided, creates a new auditor.\n */\nexport async function processEndpointAudits<\n  TServices extends Service[] = [],\n  TSession = unknown,\n  TLogger extends Logger = Logger,\n  OutSchema extends StandardSchemaV1 | undefined = undefined,\n  TAuditStorage extends AuditStorage | undefined = undefined,\n  TAuditStorageServiceName extends string = string,\n  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n    string,\n    unknown\n  >,\n>(\n  endpoint: Endpoint<\n    any,\n    any,\n    any,\n    OutSchema,\n    TServices,\n    TLogger,\n    TSession,\n    any,\n    any,\n    TAuditStorage,\n    TAuditStorageServiceName,\n    TAuditAction\n  >,\n  response: InferStandardSchema<OutSchema>,\n  serviceDiscovery: ServiceDiscovery<any, any>,\n  logger: TLogger,\n  ctx: {\n    session: TSession;\n    header: HeaderFn;\n    cookie: CookieFn;\n    services: Record<string, unknown>;\n  },\n  existingAuditor?: Auditor<TAuditAction>,\n): Promise<void> {\n  try {\n    const audits = endpoint.audits as MappedAudit<TAuditAction, OutSchema>[];\n\n    // If we have an existing auditor (from handler context), we need to flush\n    // any manual audits it collected, even if there are no declarative audits\n    const hasExistingRecords =\n      existingAuditor && existingAuditor.getRecords().length > 0;\n\n    // Skip if no declarative audits and no existing records to flush\n    if (!audits?.length && !hasExistingRecords) {\n      logger.debug('No audits to process');\n      return;\n    }\n\n    // If no auditor storage service and we have things to process, warn\n    if (!endpoint.auditorStorageService) {\n      if (hasExistingRecords || audits?.length) {\n        logger.warn('No auditor storage service available');\n      }\n      return;\n    }\n\n    // Get or create auditor\n    let auditor: Auditor<TAuditAction>;\n\n    if (existingAuditor) {\n      // Use existing auditor (preserves stored transaction and manual audits)\n      auditor = existingAuditor;\n      logger.debug('Using existing auditor from handler context');\n    } else {\n      // Create new auditor (backward compatibility)\n      const services = await serviceDiscovery.register([\n        endpoint.auditorStorageService,\n      ]);\n      const storage = services[\n        endpoint.auditorStorageService.serviceName\n      ] as AuditStorage;\n\n      // Extract actor if configured\n      let actor: AuditActor = { id: 'system', type: 'system' };\n      if (endpoint.actorExtractor) {\n        try {\n          actor = await (\n            endpoint.actorExtractor as ActorExtractor<\n              TServices,\n              TSession,\n              TLogger\n            >\n          )({\n            services: ctx.services as any,\n            session: ctx.session,\n            header: ctx.header,\n            cookie: ctx.cookie,\n            logger,\n          });\n        } catch (error) {\n          logger.error(error as Error, 'Failed to extract actor for audits');\n          // Continue with system actor\n        }\n      }\n\n      auditor = new DefaultAuditor<TAuditAction>({\n        actor,\n        storage,\n        metadata: {\n          endpoint: endpoint.route,\n          method: endpoint.method,\n        },\n      });\n    }\n\n    // Process each declarative audit\n    if (audits?.length) {\n      for (const audit of audits) {\n        logger.debug({ audit: audit.type }, 'Processing declarative audit');\n\n        // Check when condition\n        if (audit.when && !audit.when(response as any)) {\n          logger.debug(\n            { audit: audit.type },\n            'Audit skipped due to when condition',\n          );\n          continue;\n        }\n\n        // Extract payload\n        const payload = audit.payload(response as any);\n\n        // Extract entityId if configured\n        const entityId = audit.entityId?.(response as any);\n\n        // Record the audit\n        auditor.audit(audit.type as any, payload as any, {\n          table: audit.table,\n          entityId,\n        });\n      }\n    }\n\n    // Flush audits to storage\n    // Note: If existingAuditor has a stored transaction (via setTransaction),\n    // flush() will use it automatically\n    const recordCount = auditor.getRecords().length;\n    if (recordCount > 0) {\n      // Check if auditor has a stored transaction (for logging purposes)\n      const trx =\n        'getTransaction' in auditor\n          ? (auditor as { getTransaction(): unknown }).getTransaction()\n          : undefined;\n      logger.debug(\n        { auditCount: recordCount, hasTransaction: !!trx },\n        'Flushing audits',\n      );\n      await auditor.flush();\n    }\n  } catch (error) {\n    logger.error(error as Error, 'Failed to process audits');\n    // Don't rethrow - audit failures shouldn't fail the request\n  }\n}\n\n/**\n * Context for audit-aware handler execution.\n */\nexport interface AuditExecutionContext<\n  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n    string,\n    unknown\n  >,\n> {\n  /** The auditor instance for recording audits */\n  auditor: Auditor<TAuditAction>;\n  /** The audit storage instance */\n  storage: AuditStorage;\n}\n\n/**\n * Create audit context for handler execution.\n * Returns the auditor and storage for use in the handler.\n *\n * @param endpoint - The endpoint with audit configuration\n * @param serviceDiscovery - Service discovery for getting audit storage\n * @param logger - Logger for debug/error messages\n * @param ctx - Request context for actor extraction\n * @returns Audit context with auditor and storage, or undefined if not configured\n */\nexport async function createAuditContext<\n  TServices extends Service[] = [],\n  TSession = unknown,\n  TLogger extends Logger = Logger,\n  TAuditStorage extends AuditStorage | undefined = undefined,\n  TAuditStorageServiceName extends string = string,\n  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n    string,\n    unknown\n  >,\n  TDatabase = undefined,\n  TDatabaseServiceName extends string = string,\n>(\n  endpoint: Endpoint<\n    any,\n    any,\n    any,\n    any,\n    TServices,\n    TLogger,\n    TSession,\n    any,\n    any,\n    TAuditStorage,\n    TAuditStorageServiceName,\n    TAuditAction,\n    TDatabase,\n    TDatabaseServiceName\n  >,\n  serviceDiscovery: ServiceDiscovery<any, any>,\n  logger: TLogger,\n  ctx: {\n    session: TSession;\n    header: HeaderFn;\n    cookie: CookieFn;\n    services: Record<string, unknown>;\n  },\n): Promise<AuditExecutionContext<TAuditAction> | undefined> {\n  if (!endpoint.auditorStorageService) {\n    return undefined;\n  }\n\n  const services = await serviceDiscovery.register([\n    endpoint.auditorStorageService,\n  ]);\n  const storage = services[\n    endpoint.auditorStorageService.serviceName\n  ] as AuditStorage;\n\n  // Extract actor if configured\n  let actor: AuditActor = { id: 'system', type: 'system' };\n  if (endpoint.actorExtractor) {\n    try {\n      actor = await (\n        endpoint.actorExtractor as ActorExtractor<TServices, TSession, TLogger>\n      )({\n        services: ctx.services as any,\n        session: ctx.session,\n        header: ctx.header,\n        cookie: ctx.cookie,\n        logger,\n      });\n    } catch (error) {\n      logger.error(error as Error, 'Failed to extract actor for audits');\n    }\n  }\n\n  const auditor = new DefaultAuditor<TAuditAction>({\n    actor,\n    storage,\n    metadata: {\n      endpoint: endpoint.route,\n      method: endpoint.method,\n    },\n  });\n\n  return { auditor, storage };\n}\n\n/**\n * Options for executeWithAuditTransaction.\n */\nexport interface ExecuteWithAuditTransactionOptions {\n  /**\n   * Database connection to use for the transaction.\n   * If this is already a transaction, it will be reused instead of creating a nested one.\n   * If not provided, the storage's internal database is used.\n   */\n  db?: unknown;\n}\n\n/**\n * Execute a handler with automatic audit transaction support.\n * If the audit storage provides a withTransaction method, wraps execution\n * in a transaction so audits are atomic with handler's database operations.\n *\n * This is database-agnostic - each storage implementation provides its own\n * transaction handling based on the underlying database (Kysely, Drizzle, etc.).\n *\n * If the db parameter is provided and is already a transaction, the storage\n * will reuse it instead of creating a nested transaction (similar to\n * packages/db/src/kysely.ts#withTransaction).\n *\n * @param auditContext - The audit context from createAuditContext\n * @param handler - The handler function to execute (receives auditor)\n * @param onComplete - Called after handler with response, to process declarative audits\n * @param options - Optional configuration including database connection\n * @returns The handler result\n */\nexport async function executeWithAuditTransaction<\n  T,\n  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<\n    string,\n    unknown\n  >,\n>(\n  auditContext: AuditExecutionContext<TAuditAction> | undefined,\n  handler: (auditor?: Auditor<TAuditAction>) => Promise<T>,\n  onComplete?: (response: T, auditor: Auditor<TAuditAction>) => Promise<void>,\n  options?: ExecuteWithAuditTransactionOptions,\n): Promise<T> {\n  // No audit context - just run handler\n  if (!auditContext) {\n    return handler(undefined);\n  }\n\n  const { auditor, storage } = auditContext;\n\n  // Check if storage provides a transaction wrapper\n  if (storage.withTransaction) {\n    // Wrap in transaction - audits are atomic with handler operations\n    // The storage's withTransaction handles setTransaction and flush\n    // Pass db so existing transactions are reused\n    return storage.withTransaction(\n      auditor,\n      async () => {\n        const response = await handler(auditor);\n\n        // Process declarative audits within the transaction\n        if (onComplete) {\n          await onComplete(response, auditor);\n        }\n\n        return response;\n      },\n      options?.db,\n    );\n  }\n\n  // No transaction support - run handler and flush audits after\n  const response = await handler(auditor);\n\n  if (onComplete) {\n    await onComplete(response, auditor);\n  }\n\n  // Flush audits (no transaction)\n  await auditor.flush();\n\n  return response;\n}\n"],"mappings":"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"}

package/dist/publisher.d.mts

@@ -1,4 +1,4 @@
-import { Construct } from "./Construct-DDR0295I.mjs";
+import { Construct } from "./Construct-DCPATqec.mjs";
 import { Service, ServiceDiscovery } from "@geekmidas/services";
 import { AuditStorage } from "@geekmidas/audit";
 import { EventPublisher, MappedEvent } from "@geekmidas/events";

package/dist/subscribers/AWSLambdaSubscriberAdaptor.d.mts

@@ -1,4 +1,4 @@
-import "../Construct-DDR0295I.mjs";
-import "../Subscriber-itwm7ugy.mjs";
-import { AWSLambdaHandler, AWSLambdaSubscriber } from "../AWSLambdaSubscriberAdaptor-CWbBNRz3.mjs";
+import "../Construct-DCPATqec.mjs";
+import "../Subscriber-BfxLwZpX.mjs";
+import { AWSLambdaHandler, AWSLambdaSubscriber } from "../AWSLambdaSubscriberAdaptor-DtNZPMoV.mjs";
 export { AWSLambdaHandler, AWSLambdaSubscriber };

package/dist/subscribers/Subscriber.cjs

@@ -1,4 +1,4 @@
 require('../Construct-BYSPikVm.cjs');
-const require_Subscriber = require('../Subscriber-D-FPWts6.cjs');
+const require_Subscriber = require('../Subscriber-DvOtIyWq.cjs');
 
 exports.Subscriber = require_Subscriber.Subscriber;

package/dist/subscribers/Subscriber.d.mts

@@ -1,3 +1,3 @@
-import "../Construct-DDR0295I.mjs";
-import { Subscriber, SubscriberContext, SubscriberHandler } from "../Subscriber-itwm7ugy.mjs";
+import "../Construct-DCPATqec.mjs";
+import { Subscriber, SubscriberContext, SubscriberHandler } from "../Subscriber-BfxLwZpX.mjs";
 export { Subscriber, SubscriberContext, SubscriberHandler };

package/dist/subscribers/Subscriber.mjs

@@ -1,4 +1,4 @@
 import "../Construct-LWeB1rSQ.mjs";
-import { Subscriber } from "../Subscriber-CGb8LjZa.mjs";
+import { Subscriber } from "../Subscriber-JzcFFi4p.mjs";
 
 export { Subscriber };

package/dist/subscribers/SubscriberBuilder.cjs

@@ -1,5 +1,5 @@
 require('../Construct-BYSPikVm.cjs');
-require('../Subscriber-D-FPWts6.cjs');
-const require_SubscriberBuilder = require('../SubscriberBuilder-BfE2cL1q.cjs');
+require('../Subscriber-DvOtIyWq.cjs');
+const require_SubscriberBuilder = require('../SubscriberBuilder-DUuV207i.cjs');
 
 exports.SubscriberBuilder = require_SubscriberBuilder.SubscriberBuilder;

package/dist/subscribers/SubscriberBuilder.d.mts

@@ -1,4 +1,4 @@
-import "../Construct-DDR0295I.mjs";
-import "../Subscriber-itwm7ugy.mjs";
-import { SubscriberBuilder } from "../SubscriberBuilder-9j3JCu8-.mjs";
+import "../Construct-DCPATqec.mjs";
+import "../Subscriber-BfxLwZpX.mjs";
+import { SubscriberBuilder } from "../SubscriberBuilder-lTiTUS1o.mjs";
 export { SubscriberBuilder };

package/dist/subscribers/SubscriberBuilder.mjs

@@ -1,5 +1,5 @@
 import "../Construct-LWeB1rSQ.mjs";
-import "../Subscriber-CGb8LjZa.mjs";
-import { SubscriberBuilder } from "../SubscriberBuilder-BcAspHv9.mjs";
+import "../Subscriber-JzcFFi4p.mjs";
+import { SubscriberBuilder } from "../SubscriberBuilder-tm4oVOt3.mjs";
 
 export { SubscriberBuilder };

package/dist/subscribers/index.cjs

@@ -1,6 +1,6 @@
 require('../Construct-BYSPikVm.cjs');
-const require_Subscriber = require('../Subscriber-D-FPWts6.cjs');
-const require_SubscriberBuilder = require('../SubscriberBuilder-BfE2cL1q.cjs');
+const require_Subscriber = require('../Subscriber-DvOtIyWq.cjs');
+const require_SubscriberBuilder = require('../SubscriberBuilder-DUuV207i.cjs');
 
 //#region src/subscribers/index.ts
 const s = new require_SubscriberBuilder.SubscriberBuilder();

package/dist/subscribers/index.d.cts

@@ -1,10 +1,10 @@
 import "../Construct-Dkd8Kvc9.cjs";
 import { Subscriber } from "../Subscriber-DMSzvO_J.cjs";
 import { SubscriberBuilder } from "../SubscriberBuilder-BxJM3Hz_.cjs";
-import * as _geekmidas_logger4 from "@geekmidas/logger";
+import * as _geekmidas_logger10 from "@geekmidas/logger";
 
 //#region src/subscribers/index.d.ts
-declare const s: SubscriberBuilder<[], _geekmidas_logger4.Logger, undefined, undefined, string, []>;
+declare const s: SubscriberBuilder<[], _geekmidas_logger10.Logger, undefined, undefined, string, []>;
 //#endregion
 export { Subscriber, SubscriberBuilder, s };
 //# sourceMappingURL=index.d.cts.map

package/dist/subscribers/index.d.mts

@@ -1,10 +1,10 @@
-import "../Construct-DDR0295I.mjs";
-import { Subscriber } from "../Subscriber-itwm7ugy.mjs";
-import { SubscriberBuilder } from "../SubscriberBuilder-9j3JCu8-.mjs";
-import * as _geekmidas_logger9 from "@geekmidas/logger";
+import "../Construct-DCPATqec.mjs";
+import { Subscriber } from "../Subscriber-BfxLwZpX.mjs";
+import { SubscriberBuilder } from "../SubscriberBuilder-lTiTUS1o.mjs";
+import * as _geekmidas_logger10 from "@geekmidas/logger";
 
 //#region src/subscribers/index.d.ts
-declare const s: SubscriberBuilder<[], _geekmidas_logger9.Logger, undefined, undefined, string, []>;
+declare const s: SubscriberBuilder<[], _geekmidas_logger10.Logger, undefined, undefined, string, []>;
 //#endregion
 export { Subscriber, SubscriberBuilder, s };
 //# sourceMappingURL=index.d.mts.map

package/dist/subscribers/index.mjs

@@ -1,6 +1,6 @@
 import "../Construct-LWeB1rSQ.mjs";
-import { Subscriber } from "../Subscriber-CGb8LjZa.mjs";
-import { SubscriberBuilder } from "../SubscriberBuilder-BcAspHv9.mjs";
+import { Subscriber } from "../Subscriber-JzcFFi4p.mjs";
+import { SubscriberBuilder } from "../SubscriberBuilder-tm4oVOt3.mjs";
 
 //#region src/subscribers/index.ts
 const s = new SubscriberBuilder();

package/dist/{types-DKf0juBf.d.mts → types-Cy1IhmUB.d.mts}

@@ -4,4 +4,4 @@ type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
 type LowerHttpMethod<T extends HttpMethod> = Lowercase<T>;
 //#endregion
 export { HttpMethod, LowerHttpMethod, RemoveUndefined };
-//# sourceMappingURL=types-DKf0juBf.d.mts.map
+//# sourceMappingURL=types-Cy1IhmUB.d.mts.map

package/dist/types.d.mts

@@ -1,2 +1,2 @@
-import { HttpMethod, LowerHttpMethod, RemoveUndefined } from "./types-DKf0juBf.mjs";
+import { HttpMethod, LowerHttpMethod, RemoveUndefined } from "./types-Cy1IhmUB.mjs";
 export { HttpMethod, LowerHttpMethod, RemoveUndefined };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/constructs",
-  "version": "0.0.22",
+  "version": "0.1.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -67,13 +67,13 @@
     "lodash.uniqby": "~4.7.0",
     "openapi-types": "~12.1.3",
     "@geekmidas/audit": "0.0.8",
+    "@geekmidas/errors": "0.0.1",
     "@geekmidas/cache": "0.0.7",
     "@geekmidas/events": "0.0.2",
-    "@geekmidas/errors": "0.0.1",
     "@geekmidas/logger": "0.0.1",
-    "@geekmidas/rate-limit": "0.1.0",
+    "@geekmidas/services": "0.0.1",
     "@geekmidas/schema": "0.0.2",
-    "@geekmidas/services": "0.0.1"
+    "@geekmidas/rate-limit": "0.1.0"
   },
   "devDependencies": {
     "@types/lodash.compact": "~3.0.9",
@@ -91,7 +91,7 @@
     "@middy/core": ">=6.3.1",
     "@types/aws-lambda": ">=8.10.92",
     "hono": ">=4.8.2",
-    "@geekmidas/envkit": "~0.0.8"
+    "@geekmidas/envkit": "~0.1.0"
   },
   "scripts": {
     "ts": "tsc --noEmit --skipLibCheck src/**/*.ts"

package/src/endpoints/AmazonApiGatewayEndpointAdaptor.ts

@@ -356,6 +356,8 @@ export abstract class AmazonApiGatewayEndpoint<
           });
         }
       },
+      // Pass rawDb so storage can reuse existing transactions
+      { db: rawDb },
     );
 
     const { output, metadata } = result;

package/src/endpoints/Authorizer.ts

@@ -1,3 +1,89 @@
+/**
+ * OpenAPI 3.1 compliant security scheme definition.
+ * @see https://spec.openapis.org/oas/v3.1.0#security-scheme-object
+ */
+export interface SecurityScheme {
+  /** The type of the security scheme */
+  type: 'apiKey' | 'http' | 'mutualTLS' | 'oauth2' | 'openIdConnect';
+  /** A description for security scheme */
+  description?: string;
+  /** Required for apiKey. The name of the header, query or cookie parameter */
+  name?: string;
+  /** Required for apiKey. The location of the API key */
+  in?: 'query' | 'header' | 'cookie';
+  /** Required for http. The name of the HTTP Authorization scheme (e.g., 'bearer') */
+  scheme?: string;
+  /** Optional for http bearer. A hint to the format of the bearer token */
+  bearerFormat?: string;
+  /** Required for oauth2. An object containing configuration for the flow types */
+  flows?: OAuthFlows;
+  /** Required for openIdConnect. The URL to discover OAuth2 configuration */
+  openIdConnectUrl?: string;
+  /** Vendor extensions (e.g., x-amazon-apigateway-authtype) */
+  [key: `x-${string}`]: unknown;
+}
+
+/**
+ * OAuth2 flow configuration
+ */
+export interface OAuthFlows {
+  implicit?: OAuthFlow;
+  password?: OAuthFlow;
+  clientCredentials?: OAuthFlow;
+  authorizationCode?: OAuthFlow;
+}
+
+export interface OAuthFlow {
+  authorizationUrl?: string;
+  tokenUrl?: string;
+  refreshUrl?: string;
+  scopes: Record<string, string>;
+}
+
+/**
+ * Built-in security schemes available by default.
+ * Users can use these without defining them via .securitySchemes().
+ */
+export const BUILT_IN_SECURITY_SCHEMES = {
+  jwt: {
+    type: 'http',
+    scheme: 'bearer',
+    bearerFormat: 'JWT',
+    description: 'JWT Bearer token authentication',
+  },
+  bearer: {
+    type: 'http',
+    scheme: 'bearer',
+    description: 'Bearer token authentication',
+  },
+  apiKey: {
+    type: 'apiKey',
+    in: 'header',
+    name: 'X-API-Key',
+    description: 'API key authentication via header',
+  },
+  oauth2: {
+    type: 'oauth2',
+    flows: {},
+    description: 'OAuth 2.0 authentication',
+  },
+  oidc: {
+    type: 'openIdConnect',
+    openIdConnectUrl: '',
+    description: 'OpenID Connect authentication',
+  },
+  iam: {
+    type: 'apiKey',
+    in: 'header',
+    name: 'Authorization',
+    description: 'AWS IAM Signature Version 4 authentication',
+    'x-amazon-apigateway-authtype': 'awsSigv4',
+  },
+} as const satisfies Record<string, SecurityScheme>;
+
+/** Names of built-in security schemes */
+export type BuiltInSecuritySchemeId = keyof typeof BUILT_IN_SECURITY_SCHEMES;
+
 /**
  * Represents an authorizer configuration for endpoints
  */
@@ -6,18 +92,25 @@ export interface Authorizer {
    * Unique identifier for the authorizer
    */
   name: string;
+  /**
+   * The OpenAPI security scheme definition for this authorizer
+   */
+  securityScheme?: SecurityScheme;
   /**
    * Type of authorizer (e.g., 'iam', 'jwt', 'custom')
+   * @deprecated Use securityScheme.type instead
    */
   type?: string;
   /**
    * Description of what this authorizer does
+   * @deprecated Use securityScheme.description instead
    */
   description?: string;
   /**
    * Additional metadata specific to the authorizer type
+   * @deprecated Use securityScheme with x-* extensions instead
    */
-  metadata?: Record<string, any>;
+  metadata?: Record<string, unknown>;
 }
 
 /**
@@ -32,3 +125,28 @@ export function createAuthorizer(
     ...options,
   };
 }
+
+/**
+ * Check if a name is a built-in security scheme
+ */
+export function isBuiltInSecurityScheme(
+  name: string,
+): name is BuiltInSecuritySchemeId {
+  return name in BUILT_IN_SECURITY_SCHEMES;
+}
+
+/**
+ * Get a security scheme by name (built-in or custom)
+ */
+export function getSecurityScheme(
+  name: string,
+  customSchemes?: Record<string, SecurityScheme>,
+): SecurityScheme | undefined {
+  if (customSchemes && name in customSchemes) {
+    return customSchemes[name];
+  }
+  if (isBuiltInSecurityScheme(name)) {
+    return BUILT_IN_SECURITY_SCHEMES[name];
+  }
+  return undefined;
+}

package/src/endpoints/EndpointBuilder.ts

@@ -12,7 +12,8 @@ import uniqBy from 'lodash.uniqby';
 import { ConstructType } from '../Construct';
 import { BaseFunctionBuilder } from '../functions';
 import type { HttpMethod } from '../types';
-import type { Authorizer } from './Authorizer';
+import type { Authorizer, SecurityScheme } from './Authorizer';
+import { getSecurityScheme } from './Authorizer';
 import { Endpoint, type EndpointSchemas } from './Endpoint';
 import type {
   AuthorizeFn,
@@ -66,6 +67,7 @@ export class EndpointBuilder<
   _authorizerName?: TAuthorizers[number];
   _actorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
   _audits: MappedAudit<TAuditAction, OutSchema>[] = [];
+  _customSecuritySchemes: Record<string, SecurityScheme> = {};
 
   constructor(
     readonly route: TRoute,
@@ -617,11 +619,26 @@ export class EndpointBuilder<
   > {
     // Find authorizer metadata if name is set
     // If the authorizer name is set but not in availableAuthorizers, create a simple authorizer object
-    const authorizer = this._authorizerName
-      ? (this._availableAuthorizers.find(
-          (a) => a.name === this._authorizerName,
-        ) ?? { name: this._authorizerName })
-      : undefined;
+    let authorizer: Authorizer | undefined;
+    if (this._authorizerName) {
+      const existingAuthorizer = this._availableAuthorizers.find(
+        (a) => a.name === this._authorizerName,
+      );
+
+      if (existingAuthorizer) {
+        authorizer = existingAuthorizer;
+      } else {
+        // Create authorizer with security scheme if available (built-in or custom)
+        const securityScheme = getSecurityScheme(
+          this._authorizerName as string,
+          this._customSecuritySchemes,
+        );
+        authorizer = {
+          name: this._authorizerName as string,
+          securityScheme,
+        };
+      }
+    }
 
     return new Endpoint({
       fn,