@geekmidas/constructs 0.0.11 → 0.0.13

package/src/endpoints/AmazonApiGatewayEndpointAdaptor.ts

@@ -1,3 +1,4 @@
+import type { AuditStorage, AuditableAction } from '@geekmidas/audit';
 import type { Logger } from '@geekmidas/logger';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { HttpMethod } from '../types';
@@ -29,6 +30,12 @@ import type {
   InferStandardSchema,
 } from '@geekmidas/schema';
 import { publishConstructEvents } from '../publisher';
+import type { CookieFn, HeaderFn } from './Endpoint';
+import type { MappedAudit } from './audit';
+import {
+  createAuditContext,
+  executeWithAuditTransaction,
+} from './processAudits';
 
 // Helper function to publish events
 
@@ -46,6 +53,12 @@ export abstract class AmazonApiGatewayEndpoint<
   TSession = unknown,
   TEventPublisher extends EventPublisher<any> | undefined = undefined,
   TEventPublisherServiceName extends string = string,
+  TAuditStorage extends AuditStorage | undefined = undefined,
+  TAuditStorageServiceName extends string = string,
+  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
+    string,
+    unknown
+  >,
 > {
   constructor(
     protected envParser: EnvironmentParser<{}>,
@@ -58,7 +71,10 @@ export abstract class AmazonApiGatewayEndpoint<
       TLogger,
       TSession,
       TEventPublisher,
-      TEventPublisherServiceName
+      TEventPublisherServiceName,
+      TAuditStorage,
+      TAuditStorageServiceName,
+      TAuditAction
     >,
   ) {}
 
@@ -199,12 +215,15 @@ export abstract class AmazonApiGatewayEndpoint<
         const statusCode = req.response?.statusCode ?? this.endpoint.status;
 
         // Only publish events on successful responses (2xx status codes)
+        // Note: Audits are processed inside the handler's transaction
         if (Endpoint.isSuccessStatus(statusCode)) {
           const logger = event.logger as TLogger;
           const serviceDiscovery = ServiceDiscovery.getInstance<
             ServiceRecord<TServices>,
             TLogger
           >(logger, this.envParser);
+
+          // Publish events
           await publishConstructEvents(
             this.endpoint,
             response,
@@ -220,33 +239,106 @@ export abstract class AmazonApiGatewayEndpoint<
     event: Event<TEvent, TInput, TServices, TLogger, TSession>,
   ) {
     const input = this.endpoint.refineInput(event);
-
-    const responseBuilder = new ResponseBuilder();
-    const response = await this.endpoint.handler(
+    const logger = event.logger as TLogger;
+    const serviceDiscovery = ServiceDiscovery.getInstance<
+      ServiceRecord<TServices>,
+      TLogger
+    >(logger, this.envParser);
+
+    // Create audit context if audit storage is configured
+    const auditContext = await createAuditContext(
+      this.endpoint,
+      serviceDiscovery,
+      logger,
       {
+        session: event.session,
         header: event.header,
         cookie: event.cookie,
-        logger: event.logger,
-        services: event.services,
-        session: event.session,
-        ...input,
+        services: event.services as Record<string, unknown>,
       },
-      responseBuilder,
     );
 
-    // Check if response has metadata
-    let data = response;
-    let metadata = responseBuilder.getMetadata();
-
-    if (Endpoint.hasMetadata(response)) {
-      data = response.data;
-      metadata = response.metadata;
+    // Warn if declarative audits are configured but no audit storage
+    const audits = this.endpoint.audits as MappedAudit<
+      TAuditAction,
+      TOutSchema
+    >[];
+    if (!auditContext && audits?.length) {
+      logger.warn('No auditor storage service available');
     }
 
-    const output = this.endpoint.outputSchema
-      ? await this.endpoint.parseOutput(data)
+    // Resolve database service if configured
+    const rawDb = this.endpoint.databaseService
+      ? await serviceDiscovery
+          .register([this.endpoint.databaseService])
+          .then(
+            (s) =>
+              s[this.endpoint.databaseService!.serviceName as keyof typeof s],
+          )
       : undefined;
 
+    // Execute handler with automatic audit transaction support
+    const result = await executeWithAuditTransaction(
+      auditContext,
+      async (auditor) => {
+        // Use audit transaction as db only if the storage uses the same database service
+        const sameDatabase =
+          auditContext?.storage?.databaseServiceName &&
+          auditContext.storage.databaseServiceName ===
+            this.endpoint.databaseService?.serviceName;
+        const db = sameDatabase
+          ? (auditor?.getTransaction?.() ?? rawDb)
+          : rawDb;
+
+        const responseBuilder = new ResponseBuilder();
+        const response = await this.endpoint.handler(
+          {
+            header: event.header,
+            cookie: event.cookie,
+            logger: event.logger,
+            services: event.services,
+            session: event.session,
+            auditor,
+            db,
+            ...input,
+          } as any,
+          responseBuilder,
+        );
+
+        // Check if response has metadata
+        let data = response;
+        let metadata = responseBuilder.getMetadata();
+
+        if (Endpoint.hasMetadata(response)) {
+          data = response.data;
+          metadata = response.metadata;
+        }
+
+        const output = this.endpoint.outputSchema
+          ? await this.endpoint.parseOutput(data)
+          : undefined;
+
+        return { output, metadata, responseBuilder };
+      },
+      // Process declarative audits after handler (inside transaction)
+      async (result, auditor) => {
+        if (!audits?.length) return;
+
+        for (const audit of audits) {
+          if (audit.when && !audit.when(result.output as any)) {
+            continue;
+          }
+          const payload = audit.payload(result.output as any);
+          const entityId = audit.entityId?.(result.output as any);
+          auditor.audit(audit.type as any, payload as any, {
+            table: audit.table,
+            entityId,
+          });
+        }
+      },
+    );
+
+    const { output, metadata } = result;
     const body = output !== undefined ? JSON.stringify(output) : undefined;
 
     // Store response for middleware access
@@ -305,8 +397,8 @@ export type Event<
 > = {
   services: ServiceRecord<TServices>;
   logger: TLogger;
-  header(key: string): string | undefined;
-  cookie(name: string): string | undefined;
+  header: HeaderFn;
+  cookie: CookieFn;
   session: TSession;
 } & TEvent &
   InferComposableStandardSchema<TInput>;

package/src/endpoints/Endpoint.ts

@@ -1,19 +1,10 @@
-import type { Logger } from '@geekmidas/logger';
-import type { StandardSchemaV1 } from '@standard-schema/spec';
-import pick from 'lodash.pick';
-import set from 'lodash.set';
-import type { OpenAPIV3_1 } from 'openapi-types';
-
-import type { Service, ServiceRecord } from '@geekmidas/services';
-import type { Authorizer } from './Authorizer';
-import { ConstructType } from '../Construct';
-import { Function, type FunctionHandler } from '../functions';
-
+import type { AuditStorage, AuditableAction, Auditor } from '@geekmidas/audit';
 import type {
   EventPublisher,
   ExtractPublisherMessage,
   MappedEvent,
 } from '@geekmidas/events';
+import type { Logger } from '@geekmidas/logger';
 import type { RateLimitConfig } from '@geekmidas/rate-limit';
 import type {
   InferComposableStandardSchema,
@@ -28,7 +19,16 @@ import {
   type OpenApiSchemaOptions,
   buildOpenApiSchema,
 } from '@geekmidas/schema/openapi';
+import type { Service, ServiceRecord } from '@geekmidas/services';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import pick from 'lodash.pick';
+import set from 'lodash.set';
+import type { OpenAPIV3_1 } from 'openapi-types';
+import { ConstructType } from '../Construct';
+import { Function, type FunctionHandler } from '../functions';
 import type { HttpMethod, LowerHttpMethod, RemoveUndefined } from '../types';
+import type { Authorizer } from './Authorizer';
+import type { ActorExtractor, MappedAudit } from './audit';
 
 /**
  * Represents an HTTP endpoint that can handle requests with type-safe input/output validation,
@@ -65,14 +65,35 @@ export class Endpoint<
   TSession = unknown,
   TEventPublisher extends EventPublisher<any> | undefined = undefined,
   TEventPublisherServiceName extends string = string,
+  TAuditStorage extends AuditStorage | undefined = undefined,
+  TAuditStorageServiceName extends string = string,
+  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
+    string,
+    unknown
+  >,
+  TDatabase = undefined,
+  TDatabaseServiceName extends string = string,
 > extends Function<
   TInput,
   TServices,
   TLogger,
   OutSchema,
-  FunctionHandler<TInput, TServices, TLogger, OutSchema>,
   TEventPublisher,
-  TEventPublisherServiceName
+  TEventPublisherServiceName,
+  TAuditStorage,
+  TAuditStorageServiceName,
+  TDatabase,
+  TDatabaseServiceName,
+  TAuditAction,
+  FunctionHandler<
+    TInput,
+    TServices,
+    TLogger,
+    OutSchema,
+    TDatabase,
+    TAuditStorage,
+    TAuditAction
+  >
 > {
   operationId?: string;
   /** The route path pattern with parameter placeholders */
@@ -96,13 +117,22 @@ export class Endpoint<
   public rateLimit?: RateLimitConfig;
   /** Optional authorizer for this endpoint */
   public authorizer?: Authorizer;
+  /** Optional actor extractor for audit records */
+  public actorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
+  /** Declarative audit definitions */
+  public audits: MappedAudit<TAuditAction, OutSchema>[] = [];
+  /** Database service for this endpoint */
+  public databaseService?: Service<TDatabaseServiceName, TDatabase>;
   /** The endpoint handler function */
   private endpointFn!: EndpointHandler<
     TInput,
     TServices,
     TLogger,
     OutSchema,
-    TSession
+    TSession,
+    TDatabase,
+    TAuditStorage,
+    TAuditAction
   >;
 
   /**
@@ -309,7 +339,15 @@ export class Endpoint<
   }
 
   handler = (
-    ctx: EndpointContext<TInput, TServices, TLogger, TSession>,
+    ctx: EndpointContext<
+      TInput,
+      TServices,
+      TLogger,
+      TSession,
+      TAuditAction,
+      TDatabase,
+      TAuditStorage
+    >,
     response: ResponseBuilder,
   ): OutSchema extends StandardSchemaV1
     ?
@@ -327,17 +365,28 @@ export class Endpoint<
       response.header(key, value);
     }
 
-    return this.endpointFn(
-      {
-        ...this.refineInput(ctx),
-        services: ctx.services,
-        logger: ctx.logger,
-        header: ctx.header,
-        cookie: ctx.cookie,
-        session: ctx.session,
-      } as EndpointContext<TInput, TServices, TLogger, TSession>,
-      response,
-    );
+    // Build context object, conditionally including auditor and db
+    const handlerCtx = {
+      ...this.refineInput(ctx),
+      services: ctx.services,
+      logger: ctx.logger,
+      header: ctx.header,
+      cookie: ctx.cookie,
+      session: ctx.session,
+      // These are conditionally present based on configuration
+      ...('auditor' in ctx && { auditor: ctx.auditor }),
+      ...('db' in ctx && { db: ctx.db }),
+    } as EndpointContext<
+      TInput,
+      TServices,
+      TLogger,
+      TSession,
+      TAuditAction,
+      TDatabase,
+      TAuditStorage
+    >;
+
+    return this.endpointFn(handlerCtx, response);
   };
 
   /**
@@ -540,6 +589,10 @@ export class Endpoint<
     publisherService,
     events,
     authorizer,
+    auditorStorageService,
+    actorExtractor,
+    audits,
+    databaseService,
   }: EndpointOptions<
     TRoute,
     TMethod,
@@ -550,7 +603,12 @@ export class Endpoint<
     TSession,
     OutSchema,
     TEventPublisher,
-    TEventPublisherServiceName
+    TEventPublisherServiceName,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName
   >) {
     super(
       fn as unknown as FunctionHandler<TInput, TServices, TLogger, OutSchema>,
@@ -563,6 +621,7 @@ export class Endpoint<
       publisherService,
       events,
       memorySize,
+      auditorStorageService,
     );
 
     this.route = route;
@@ -587,6 +646,18 @@ export class Endpoint<
     if (authorizer) {
       this.authorizer = authorizer;
     }
+
+    if (actorExtractor) {
+      this.actorExtractor = actorExtractor;
+    }
+
+    if (audits) {
+      this.audits = audits;
+    }
+
+    if (databaseService) {
+      this.databaseService = databaseService;
+    }
   }
 }
 
@@ -638,13 +709,30 @@ export interface EndpointOptions<
   OutSchema extends StandardSchemaV1 | undefined = undefined,
   TEventPublisher extends EventPublisher<any> | undefined = undefined,
   TEventPublisherServiceName extends string = string,
+  TAuditStorage extends AuditStorage | undefined = undefined,
+  TAuditStorageServiceName extends string = string,
+  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
+    string,
+    unknown
+  >,
+  TDatabase = undefined,
+  TDatabaseServiceName extends string = string,
 > {
   /** The route path with parameter placeholders */
   route: TRoute;
   /** The HTTP method for this endpoint */
   method: TMethod;
   /** The handler function that implements the endpoint logic */
-  fn: EndpointHandler<TInput, TServices, TLogger, TOutput, TSession>;
+  fn: EndpointHandler<
+    TInput,
+    TServices,
+    TLogger,
+    TOutput,
+    TSession,
+    TDatabase,
+    TAuditStorage,
+    TAuditAction
+  >;
   /** Optional authorization check function */
   authorize: AuthorizeFn<TServices, TLogger, TSession> | undefined;
   /** Optional description for documentation */
@@ -677,6 +765,16 @@ export interface EndpointOptions<
   events?: MappedEvent<TEventPublisher, OutSchema>[];
   /** Optional authorizer configuration */
   authorizer?: Authorizer;
+  /**
+   * Auditor storage service for persisting audit records from this endpoint
+   */
+  auditorStorageService?: Service<TAuditStorageServiceName, TAuditStorage>;
+  /** Optional actor extractor function for audit records */
+  actorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
+  /** Declarative audit definitions */
+  audits?: MappedAudit<TAuditAction, OutSchema>[];
+  /** Database service for this endpoint */
+  databaseService?: Service<TDatabaseServiceName, TDatabase>;
 }
 
 /**
@@ -927,16 +1025,9 @@ export class ResponseBuilder {
 }
 
 /**
- * The execution context provided to endpoint handlers.
- * Contains all parsed input data, services, logger, headers, cookies, and session.
- *
- * @template Input - The input schemas (body, query, params)
- * @template TServices - Available service dependencies
- * @template TLogger - Logger type
- * @template TSession - Session data type
+ * Base context properties that are always available
  */
-export type EndpointContext<
-  Input extends EndpointSchemas | undefined = undefined,
+type BaseEndpointContext<
   TServices extends Service[] = [],
   TLogger extends Logger = Logger,
   TSession = unknown,
@@ -951,7 +1042,71 @@ export type EndpointContext<
   cookie: CookieFn;
   /** Session data extracted by getSession */
   session: TSession;
-} & InferComposableStandardSchema<Input>;
+};
+
+/**
+ * Conditional auditor context - only present when audit storage is configured
+ */
+type AuditorContext<
+  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
+    string,
+    unknown
+  >,
+  TAuditStorage = undefined,
+> = TAuditStorage extends undefined
+  ? {}
+  : {
+      /**
+       * Auditor instance for recording audit events.
+       * Only present when audit storage is configured on the endpoint.
+       * When a transactional database is used for audit storage,
+       * the auditor is pre-configured with the transaction context.
+       */
+      auditor: Auditor<TAuditAction>;
+    };
+
+/**
+ * Conditional database context - only present when database service is configured
+ */
+type DatabaseContext<TDatabase = undefined> = TDatabase extends undefined
+  ? {}
+  : {
+      /**
+       * Database instance for this request.
+       * When audit storage is configured and uses the same database,
+       * this will be the transaction for ACID compliance.
+       * Otherwise, it's the raw database connection.
+       */
+      db: TDatabase;
+    };
+
+/**
+ * The execution context provided to endpoint handlers.
+ * Contains all parsed input data, services, logger, headers, cookies, and session.
+ *
+ * @template Input - The input schemas (body, query, params)
+ * @template TServices - Available service dependencies
+ * @template TLogger - Logger type
+ * @template TSession - Session data type
+ * @template TAuditAction - Audit action types (when auditor is configured)
+ * @template TDatabase - Database type (when database service is configured)
+ * @template TAuditStorage - Audit storage type (determines if auditor is present)
+ */
+export type EndpointContext<
+  Input extends EndpointSchemas | undefined = undefined,
+  TServices extends Service[] = [],
+  TLogger extends Logger = Logger,
+  TSession = unknown,
+  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
+    string,
+    unknown
+  >,
+  TDatabase = undefined,
+  TAuditStorage = undefined,
+> = BaseEndpointContext<TServices, TLogger, TSession> &
+  InferComposableStandardSchema<Input> &
+  AuditorContext<TAuditAction, TAuditStorage> &
+  DatabaseContext<TDatabase>;
 
 /**
  * Handler function type for endpoint implementations.
@@ -988,8 +1143,22 @@ export type EndpointHandler<
   TLogger extends Logger = Logger,
   OutSchema extends StandardSchemaV1 | undefined = undefined,
   TSession = unknown,
+  TDatabase = undefined,
+  TAuditStorage = undefined,
+  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
+    string,
+    unknown
+  >,
 > = (
-  ctx: EndpointContext<TInput, TServices, TLogger, TSession>,
+  ctx: EndpointContext<
+    TInput,
+    TServices,
+    TLogger,
+    TSession,
+    TAuditAction,
+    TDatabase,
+    TAuditStorage
+  >,
   response: ResponseBuilder,
 ) => OutSchema extends StandardSchemaV1
   ?