@geekmidas/constructs 0.0.11 → 0.0.13

package/src/endpoints/EndpointBuilder.ts

@@ -1,11 +1,14 @@
+import type { AuditStorage, AuditableAction } from '@geekmidas/audit';
+import type { EventPublisher, MappedEvent } from '@geekmidas/events';
 import type { Logger } from '@geekmidas/logger';
 import type { RateLimitConfig } from '@geekmidas/rate-limit';
 import type { Service } from '@geekmidas/services';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import uniqBy from 'lodash.uniqby';
-import type { Authorizer } from './Authorizer';
 import { ConstructType } from '../Construct';
 import { BaseFunctionBuilder } from '../functions';
+import type { HttpMethod } from '../types';
+import type { Authorizer } from './Authorizer';
 import { Endpoint, type EndpointSchemas } from './Endpoint';
 import type {
   AuthorizeFn,
@@ -13,9 +16,7 @@ import type {
   SessionFn,
   SuccessStatus,
 } from './Endpoint';
-
-import type { EventPublisher, MappedEvent } from '@geekmidas/events';
-import type { HttpMethod } from '../types';
+import type { ActorExtractor, MappedAudit } from './audit';
 
 export class EndpointBuilder<
   TRoute extends string,
@@ -28,13 +29,23 @@ export class EndpointBuilder<
   TEventPublisher extends EventPublisher<any> | undefined = undefined,
   TEventPublisherServiceName extends string = string,
   TAuthorizers extends readonly string[] = readonly 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 BaseFunctionBuilder<
   TInput,
   OutSchema,
   TServices,
   TLogger,
   TEventPublisher,
-  TEventPublisherServiceName
+  TEventPublisherServiceName,
+  TAuditStorage,
+  TAuditStorageServiceName
 > {
   protected schemas: TInput = {} as TInput;
   protected _description?: string;
@@ -46,6 +57,9 @@ export class EndpointBuilder<
   _rateLimit?: RateLimitConfig;
   _availableAuthorizers: Authorizer[] = [];
   _authorizerName?: TAuthorizers[number];
+  _actorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
+  _audits: MappedAudit<TAuditAction, OutSchema>[] = [];
+  _databaseService?: Service<TDatabaseServiceName, TDatabase>;
 
   constructor(
     readonly route: TRoute,
@@ -100,7 +114,9 @@ export class EndpointBuilder<
     TSession,
     T,
     TName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName
   > {
     this._publisher = publisher as unknown as Service<
       TEventPublisherServiceName,
@@ -117,7 +133,9 @@ export class EndpointBuilder<
       TSession,
       T,
       TName,
-      TAuthorizers
+      TAuthorizers,
+      TAuditStorage,
+      TAuditStorageServiceName
     >;
   }
 
@@ -133,7 +151,9 @@ export class EndpointBuilder<
     TSession,
     TEventPublisher,
     TEventPublisherServiceName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName
   > {
     this.schemas.body = schema as unknown as T;
     // @ts-ignore
@@ -152,7 +172,9 @@ export class EndpointBuilder<
     TSession,
     TEventPublisher,
     TEventPublisherServiceName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName
   > {
     this.schemas.query = schema as unknown as T;
     // @ts-ignore
@@ -171,7 +193,9 @@ export class EndpointBuilder<
     TSession,
     TEventPublisher,
     TEventPublisherServiceName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName
   > {
     return this.search(schema);
   }
@@ -188,7 +212,9 @@ export class EndpointBuilder<
     TSession,
     TEventPublisher,
     TEventPublisherServiceName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName
   > {
     this.schemas.params = schema as unknown as T;
     // @ts-ignore
@@ -212,7 +238,12 @@ export class EndpointBuilder<
     TSession,
     TEventPublisher,
     TEventPublisherServiceName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName
   > {
     // Special case: 'none' explicitly marks endpoint as having no authorizer
     if (name === 'none') {
@@ -225,7 +256,9 @@ export class EndpointBuilder<
       (a) => a.name === name,
     );
     if (!authorizerExists && this._availableAuthorizers.length > 0) {
-      const available = this._availableAuthorizers.map((a) => a.name).join(', ');
+      const available = this._availableAuthorizers
+        .map((a) => a.name)
+        .join(', ');
       throw new Error(
         `Authorizer "${name as string}" not found in available authorizers: ${available}`,
       );
@@ -246,7 +279,12 @@ export class EndpointBuilder<
     TSession,
     TEventPublisher,
     TEventPublisherServiceName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName
   > {
     this._services = uniqBy(
       [...this._services, ...services],
@@ -263,7 +301,12 @@ export class EndpointBuilder<
       TSession,
       TEventPublisher,
       TEventPublisherServiceName,
-      TAuthorizers
+      TAuthorizers,
+      TAuditStorage,
+      TAuditStorageServiceName,
+      TAuditAction,
+      TDatabase,
+      TDatabaseServiceName
     >;
   }
 
@@ -279,7 +322,12 @@ export class EndpointBuilder<
     TSession,
     TEventPublisher,
     TEventPublisherServiceName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName
   > {
     this._logger = logger as unknown as TLogger;
 
@@ -293,7 +341,12 @@ export class EndpointBuilder<
       TSession,
       TEventPublisher,
       TEventPublisherServiceName,
-      TAuthorizers
+      TAuthorizers,
+      TAuditStorage,
+      TAuditStorageServiceName,
+      TAuditAction,
+      TDatabase,
+      TDatabaseServiceName
     >;
   }
 
@@ -309,7 +362,12 @@ export class EndpointBuilder<
     TSession,
     TEventPublisher,
     TEventPublisherServiceName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName
   > {
     this.outputSchema = schema as unknown as OutSchema;
 
@@ -323,7 +381,200 @@ export class EndpointBuilder<
       TSession,
       TEventPublisher,
       TEventPublisherServiceName,
-      TAuthorizers
+      TAuthorizers,
+      TAuditStorage,
+      TAuditStorageServiceName,
+      TAuditAction,
+      TDatabase,
+      TDatabaseServiceName
+    >;
+  }
+
+  /**
+   * Set the auditor storage service for this endpoint.
+   * This enables audit functionality and makes `auditor` available in the handler context.
+   */
+  auditor<T extends AuditStorage, TName extends string>(
+    storage: Service<TName, T>,
+  ): EndpointBuilder<
+    TRoute,
+    TMethod,
+    TInput,
+    TServices,
+    TLogger,
+    OutSchema,
+    TSession,
+    TEventPublisher,
+    TEventPublisherServiceName,
+    TAuthorizers,
+    T,
+    TName,
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName
+  > {
+    this._auditorStorage = storage as unknown as Service<
+      TAuditStorageServiceName,
+      TAuditStorage
+    >;
+
+    return this as unknown as EndpointBuilder<
+      TRoute,
+      TMethod,
+      TInput,
+      TServices,
+      TLogger,
+      OutSchema,
+      TSession,
+      TEventPublisher,
+      TEventPublisherServiceName,
+      TAuthorizers,
+      T,
+      TName,
+      TAuditAction,
+      TDatabase,
+      TDatabaseServiceName
+    >;
+  }
+
+  /**
+   * Set the actor extractor function for audit records.
+   * The actor is extracted from the request context and attached to all audits.
+   */
+  actor(
+    extractor: ActorExtractor<TServices, TSession, TLogger>,
+  ): EndpointBuilder<
+    TRoute,
+    TMethod,
+    TInput,
+    TServices,
+    TLogger,
+    OutSchema,
+    TSession,
+    TEventPublisher,
+    TEventPublisherServiceName,
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName
+  > {
+    this._actorExtractor = extractor;
+    return this;
+  }
+
+  /**
+   * Add declarative audit definitions that are processed after the handler executes.
+   * Similar to `.event()` for events, but for audits.
+   *
+   * @example
+   * ```typescript
+   * .audit<AppAuditAction>([
+   *   {
+   *     type: 'user.created',
+   *     payload: (response) => ({ userId: response.id, email: response.email }),
+   *     when: (response) => response.active,
+   *     entityId: (response) => response.id,
+   *     table: 'users',
+   *   },
+   * ])
+   * ```
+   */
+  audit<T extends AuditableAction<string, unknown>>(
+    audits: MappedAudit<T, OutSchema>[],
+  ): EndpointBuilder<
+    TRoute,
+    TMethod,
+    TInput,
+    TServices,
+    TLogger,
+    OutSchema,
+    TSession,
+    TEventPublisher,
+    TEventPublisherServiceName,
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    T,
+    TDatabase,
+    TDatabaseServiceName
+  > {
+    this._audits = audits as unknown as MappedAudit<TAuditAction, OutSchema>[];
+    return this as unknown as EndpointBuilder<
+      TRoute,
+      TMethod,
+      TInput,
+      TServices,
+      TLogger,
+      OutSchema,
+      TSession,
+      TEventPublisher,
+      TEventPublisherServiceName,
+      TAuthorizers,
+      TAuditStorage,
+      TAuditStorageServiceName,
+      T,
+      TDatabase,
+      TDatabaseServiceName
+    >;
+  }
+
+  /**
+   * Set the database service for this endpoint.
+   * The database will be available in the handler context as `db`.
+   * When audit storage is configured and uses the same database,
+   * `db` will automatically be the transaction for ACID compliance.
+   *
+   * @example
+   * ```typescript
+   * .database(databaseService)
+   * .handle(async ({ db }) => {
+   *   // db is the raw database or transaction (when auditor uses same db)
+   *   return await db.selectFrom('users').selectAll().execute();
+   * })
+   * ```
+   */
+  database<T, TName extends string>(
+    service: Service<TName, T>,
+  ): EndpointBuilder<
+    TRoute,
+    TMethod,
+    TInput,
+    TServices,
+    TLogger,
+    OutSchema,
+    TSession,
+    TEventPublisher,
+    TEventPublisherServiceName,
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction,
+    T,
+    TName
+  > {
+    this._databaseService = service as unknown as Service<
+      TDatabaseServiceName,
+      TDatabase
+    >;
+
+    return this as unknown as EndpointBuilder<
+      TRoute,
+      TMethod,
+      TInput,
+      TServices,
+      TLogger,
+      OutSchema,
+      TSession,
+      TEventPublisher,
+      TEventPublisherServiceName,
+      TAuthorizers,
+      TAuditStorage,
+      TAuditStorageServiceName,
+      TAuditAction,
+      T,
+      TName
     >;
   }
 
@@ -335,7 +586,16 @@ export class EndpointBuilder<
   }
 
   handle(
-    fn: EndpointHandler<TInput, TServices, TLogger, OutSchema, TSession>,
+    fn: EndpointHandler<
+      TInput,
+      TServices,
+      TLogger,
+      OutSchema,
+      TSession,
+      TDatabase,
+      TAuditStorage,
+      TAuditAction
+    >,
   ): Endpoint<
     TRoute,
     TMethod,
@@ -344,7 +604,13 @@ export class EndpointBuilder<
     TServices,
     TLogger,
     TSession,
-    TEventPublisher
+    TEventPublisher,
+    TEventPublisherServiceName,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName
   > {
     // Find authorizer metadata if name is set
     const authorizer = this._authorizerName
@@ -370,6 +636,10 @@ export class EndpointBuilder<
       publisherService: this._publisher,
       events: this._events,
       authorizer,
+      auditorStorageService: this._auditorStorage,
+      actorExtractor: this._actorExtractor,
+      audits: this._audits,
+      databaseService: this._databaseService,
     });
   }
 }

package/src/endpoints/EndpointFactory.ts

@@ -264,7 +264,11 @@ export class EndpointFactory<
       >,
       defaultLogger: logger,
       defaultSessionExtractor: this
-        .defaultSessionExtractor as unknown as SessionFn<TServices, L, TSession>,
+        .defaultSessionExtractor as unknown as SessionFn<
+        TServices,
+        L,
+        TSession
+      >,
       defaultEventPublisher: this.defaultEventPublisher,
       availableAuthorizers: this.availableAuthorizers,
       defaultAuthorizerName: this.defaultAuthorizerName,