@geekmidas/constructs 0.0.11 → 0.0.12

package/src/endpoints/EndpointBuilder.ts

@@ -1,11 +1,15 @@
+import type { AuditableAction, AuditStorage } 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 { ActorExtractor, MappedAudit } from './audit';
+import type { Authorizer } from './Authorizer';
 import { Endpoint, type EndpointSchemas } from './Endpoint';
 import type {
   AuthorizeFn,
@@ -14,9 +18,6 @@ import type {
   SuccessStatus,
 } from './Endpoint';
 
-import type { EventPublisher, MappedEvent } from '@geekmidas/events';
-import type { HttpMethod } from '../types';
-
 export class EndpointBuilder<
   TRoute extends string,
   TMethod extends HttpMethod,
@@ -28,13 +29,21 @@ 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
+  >,
 > extends BaseFunctionBuilder<
   TInput,
   OutSchema,
   TServices,
   TLogger,
   TEventPublisher,
-  TEventPublisherServiceName
+  TEventPublisherServiceName,
+  TAuditStorage,
+  TAuditStorageServiceName
 > {
   protected schemas: TInput = {} as TInput;
   protected _description?: string;
@@ -46,6 +55,8 @@ export class EndpointBuilder<
   _rateLimit?: RateLimitConfig;
   _availableAuthorizers: Authorizer[] = [];
   _authorizerName?: TAuthorizers[number];
+  _actorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
+  _audits: MappedAudit<TAuditAction, OutSchema>[] = [];
 
   constructor(
     readonly route: TRoute,
@@ -100,7 +111,9 @@ export class EndpointBuilder<
     TSession,
     T,
     TName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName
   > {
     this._publisher = publisher as unknown as Service<
       TEventPublisherServiceName,
@@ -117,7 +130,9 @@ export class EndpointBuilder<
       TSession,
       T,
       TName,
-      TAuthorizers
+      TAuthorizers,
+      TAuditStorage,
+      TAuditStorageServiceName
     >;
   }
 
@@ -133,7 +148,9 @@ export class EndpointBuilder<
     TSession,
     TEventPublisher,
     TEventPublisherServiceName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName
   > {
     this.schemas.body = schema as unknown as T;
     // @ts-ignore
@@ -152,7 +169,9 @@ export class EndpointBuilder<
     TSession,
     TEventPublisher,
     TEventPublisherServiceName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName
   > {
     this.schemas.query = schema as unknown as T;
     // @ts-ignore
@@ -171,7 +190,9 @@ export class EndpointBuilder<
     TSession,
     TEventPublisher,
     TEventPublisherServiceName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName
   > {
     return this.search(schema);
   }
@@ -188,7 +209,9 @@ export class EndpointBuilder<
     TSession,
     TEventPublisher,
     TEventPublisherServiceName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName
   > {
     this.schemas.params = schema as unknown as T;
     // @ts-ignore
@@ -212,7 +235,9 @@ export class EndpointBuilder<
     TSession,
     TEventPublisher,
     TEventPublisherServiceName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName
   > {
     // Special case: 'none' explicitly marks endpoint as having no authorizer
     if (name === 'none') {
@@ -246,7 +271,9 @@ export class EndpointBuilder<
     TSession,
     TEventPublisher,
     TEventPublisherServiceName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName
   > {
     this._services = uniqBy(
       [...this._services, ...services],
@@ -263,7 +290,9 @@ export class EndpointBuilder<
       TSession,
       TEventPublisher,
       TEventPublisherServiceName,
-      TAuthorizers
+      TAuthorizers,
+      TAuditStorage,
+      TAuditStorageServiceName
     >;
   }
 
@@ -279,7 +308,9 @@ export class EndpointBuilder<
     TSession,
     TEventPublisher,
     TEventPublisherServiceName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName
   > {
     this._logger = logger as unknown as TLogger;
 
@@ -293,7 +324,9 @@ export class EndpointBuilder<
       TSession,
       TEventPublisher,
       TEventPublisherServiceName,
-      TAuthorizers
+      TAuthorizers,
+      TAuditStorage,
+      TAuditStorageServiceName
     >;
   }
 
@@ -309,7 +342,9 @@ export class EndpointBuilder<
     TSession,
     TEventPublisher,
     TEventPublisherServiceName,
-    TAuthorizers
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName
   > {
     this.outputSchema = schema as unknown as OutSchema;
 
@@ -323,7 +358,129 @@ export class EndpointBuilder<
       TSession,
       TEventPublisher,
       TEventPublisherServiceName,
-      TAuthorizers
+      TAuthorizers,
+      TAuditStorage,
+      TAuditStorageServiceName
+    >;
+  }
+
+  /**
+   * 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
+  > {
+    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
+    >;
+  }
+
+  /**
+   * 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
+  > {
+    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
+  > {
+    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
     >;
   }
 
@@ -344,7 +501,11 @@ export class EndpointBuilder<
     TServices,
     TLogger,
     TSession,
-    TEventPublisher
+    TEventPublisher,
+    TEventPublisherServiceName,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction
   > {
     // Find authorizer metadata if name is set
     const authorizer = this._authorizerName
@@ -370,6 +531,9 @@ export class EndpointBuilder<
       publisherService: this._publisher,
       events: this._events,
       authorizer,
+      auditorStorageService: this._auditorStorage,
+      actorExtractor: this._actorExtractor,
+      audits: this._audits,
     });
   }
 }

package/src/endpoints/HonoEndpointAdaptor.ts

@@ -1,3 +1,4 @@
+import type { AuditableAction, AuditStorage } from '@geekmidas/audit';
 import type { EnvironmentParser } from '@geekmidas/envkit';
 import type { EventPublisher } from '@geekmidas/events';
 import type { Logger } from '@geekmidas/logger';
@@ -19,6 +20,7 @@ import { getEndpointsFromRoutes } from './helpers';
 import { parseHonoQuery } from './parseHonoQuery';
 
 import { wrapError } from '@geekmidas/errors';
+import type { InferStandardSchema } from '@geekmidas/schema';
 import {
   type Service,
   ServiceDiscovery,
@@ -26,6 +28,11 @@ import {
 } from '@geekmidas/services';
 import type { ContentfulStatusCode } from 'hono/utils/http-status';
 import { publishConstructEvents } from '../publisher';
+import type { MappedAudit } from './audit';
+import {
+  createAuditContext,
+  executeWithAuditTransaction,
+} from './processAudits';
 
 export interface HonoEndpointOptions {
   /**
@@ -53,6 +60,13 @@ export class HonoEndpoint<
   TLogger extends Logger = Logger,
   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(
     private readonly endpoint: Endpoint<
@@ -63,7 +77,11 @@ export class HonoEndpoint<
       TServices,
       TLogger,
       TSession,
-      TEventPublisher
+      TEventPublisher,
+      TEventPublisherServiceName,
+      TAuditStorage,
+      TAuditStorageServiceName,
+      TAuditAction
     >,
   ) {}
 
@@ -111,11 +129,12 @@ export class HonoEndpoint<
         any
       >;
       // @ts-ignore
-      const response = c.get('__response') as InferStandardSchema<TOutSchema>;
+      const response = c.get('__response');
       // @ts-ignore
       const logger = c.get('__logger') as Logger;
 
       if (Endpoint.isSuccessStatus(c.res.status) && endpoint) {
+        // Process events (audits are handled in the handler with transaction support)
         await publishConstructEvents<any, any>(
           endpoint,
           response,
@@ -215,6 +234,13 @@ export class HonoEndpoint<
     TLogger extends Logger = Logger,
     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
+    >,
   >(
     endpoint: Endpoint<
       TRoute,
@@ -224,7 +250,11 @@ export class HonoEndpoint<
       TServices,
       TLogger,
       TSession,
-      TEventPublisher
+      TEventPublisher,
+      TEventPublisherServiceName,
+      TAuditStorage,
+      TAuditStorageServiceName,
+      TAuditAction
     >,
     serviceDiscovery: ServiceDiscovery<ServiceRecord<TServices>, TLogger>,
     app: Hono,
@@ -304,41 +334,91 @@ export class HonoEndpoint<
             }
           }
 
-          const responseBuilder = new ResponseBuilder();
-          const response = await endpoint.handler(
+          // Create audit context if audit storage is configured
+          const auditContext = await createAuditContext(
+            endpoint,
+            serviceDiscovery,
+            logger,
             {
-              services,
-              logger,
-              body: c.req.valid('json'),
-              query: c.req.valid('query'),
-              params: c.req.valid('param'),
               session,
-              header: Endpoint.createHeaders(headerValues),
-              cookie: Endpoint.createCookies(headerValues.cookie),
-            } as unknown as EndpointContext<
-              TInput,
-              TServices,
-              TLogger,
-              TSession
-            >,
-            responseBuilder,
+              header,
+              cookie,
+              services: services as Record<string, unknown>,
+            },
           );
 
-          // Publish events if configured
+          // Warn if declarative audits are configured but no audit storage
+          const audits = endpoint.audits as MappedAudit<
+            TAuditAction,
+            TOutSchema
+          >[];
+          if (!auditContext && audits?.length) {
+            logger.warn('No auditor storage service available');
+          }
 
-          // Validate output if schema is defined
+          // Execute handler with automatic audit transaction support
+          const result = await executeWithAuditTransaction(
+            auditContext,
+            async (auditor) => {
+              const responseBuilder = new ResponseBuilder();
+              const response = await endpoint.handler(
+                {
+                  services,
+                  logger,
+                  body: c.req.valid('json'),
+                  query: c.req.valid('query'),
+                  params: c.req.valid('param'),
+                  session,
+                  header,
+                  cookie,
+                  auditor,
+                } as unknown as EndpointContext<
+                  TInput,
+                  TServices,
+                  TLogger,
+                  TSession
+                >,
+                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 = endpoint.outputSchema
+                ? await 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;
 
           try {
-            // Check if response has metadata
-            let data = response;
-            let metadata = responseBuilder.getMetadata();
             let status = endpoint.status as ContentfulStatusCode;
 
-            if (Endpoint.hasMetadata(response)) {
-              data = response.data;
-              metadata = response.metadata;
-            }
-
             // Apply response metadata
             if (metadata.status) {
               status = metadata.status as ContentfulStatusCode;
@@ -356,21 +436,22 @@ export class HonoEndpoint<
               }
             }
 
-            const output = endpoint.outputSchema
-              ? await endpoint.parseOutput(data)
-              : ({} as any);
             // @ts-ignore
             c.set('__response', output);
             // @ts-ignore
             c.set('__endpoint', endpoint);
             // @ts-ignore
             c.set('__logger', logger);
+            // @ts-ignore
+            c.set('__session', session);
+            // @ts-ignore
+            c.set('__services', services);
 
             if (HonoEndpoint.isDev) {
               logger.info({ status, body: output }, 'Outgoing response');
             }
 
-            return c.json(output, status);
+            return c.json(output ?? {}, status);
           } catch (validationError: any) {
             logger.error(validationError, 'Output validation failed');
             const error = wrapError(