@geekmidas/constructs 0.0.10 → 0.0.12

package/dist/types.d.mts

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/constructs",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "private": false,
   "type": "module",
   "exports": {
@@ -59,27 +59,31 @@
     "access": "public"
   },
   "dependencies": {
+    "fast-glob": "~3.3.3",
+    "lodash.compact": "~3.0.1",
+    "lodash.get": "~4.4.2",
     "lodash.pick": "~4.4.0",
     "lodash.set": "~4.3.2",
-    "lodash.get": "~4.4.2",
     "lodash.uniqby": "~4.7.0",
-    "lodash.compact": "~3.0.1",
     "openapi-types": "~12.1.3",
-    "fast-glob": "~3.3.3",
+    "@geekmidas/cache": "0.0.7",
+    "@geekmidas/audit": "0.0.1",
+    "@geekmidas/logger": "0.0.1",
+    "@geekmidas/rate-limit": "0.1.0",
     "@geekmidas/schema": "0.0.2",
     "@geekmidas/services": "0.0.1",
-    "@geekmidas/logger": "0.0.1",
-    "@geekmidas/errors": "0.0.1",
-    "@geekmidas/cache": "0.0.7",
     "@geekmidas/events": "0.0.2",
-    "@geekmidas/rate-limit": "0.1.0"
+    "@geekmidas/errors": "0.0.1"
   },
   "devDependencies": {
+    "@types/lodash.compact": "~3.0.9",
+    "@types/lodash.get": "~4.4.9",
     "@types/lodash.pick": "~4.4.9",
     "@types/lodash.set": "~4.3.9",
-    "@types/lodash.get": "~4.4.9",
     "@types/lodash.uniqby": "~4.7.9",
-    "@types/lodash.compact": "~3.0.9",
+    "@types/pg": "~8.15.6",
+    "kysely": "~0.28.8",
+    "pg": "~8.16.3",
     "zod": "~4.1.12",
     "@geekmidas/testkit": "0.0.17"
   },

package/src/Construct.ts

@@ -1,3 +1,4 @@
+import type { AuditStorage } from '@geekmidas/audit';
 import { SnifferEnvironmentParser } from '@geekmidas/envkit/sniffer';
 import type { EventPublisher, MappedEvent } from '@geekmidas/events';
 import type { Logger } from '@geekmidas/logger';
@@ -5,12 +6,18 @@ import type { Service } from '@geekmidas/services';
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import compact from 'lodash.compact';
 
+// Cache for service environment variables to handle singleton services
+// Key: service class/constructor, Value: array of env var names
+const serviceEnvCache = new Map<Service, string[]>();
+
 export abstract class Construct<
   TLogger extends Logger = Logger,
   TServiceName extends string = string,
   T extends EventPublisher<any> | undefined = undefined,
   OutSchema extends StandardSchemaV1 | undefined = undefined,
   TServices extends Service[] = [],
+  TAuditStorageServiceName extends string = string,
+  TAuditStorage extends AuditStorage | undefined = undefined,
 > {
   constructor(
     public readonly type: ConstructType,
@@ -22,6 +29,10 @@ export abstract class Construct<
     public outputSchema?: OutSchema,
     public readonly timeout?: number,
     public readonly memorySize?: number,
+    public readonly auditorStorageService?: Service<
+      TAuditStorageServiceName,
+      TAuditStorage
+    >,
   ) {}
 
   /**
@@ -29,6 +40,9 @@ export abstract class Construct<
    * This is determined by running a "sniffer" EnvironmentParser through each service's
    * register method to track which environment variables are accessed.
    *
+   * Results are cached per service class to handle singleton patterns where
+   * subsequent register() calls may short-circuit and not access env vars.
+   *
    * @returns Promise that resolves to array of environment variable names, sorted alphabetically
    *
    * @example
@@ -42,15 +56,24 @@ export abstract class Construct<
    * ```
    */
   async getEnvironment(): Promise<string[]> {
-    const sniffer = new SnifferEnvironmentParser();
+    const envVars = new Set<string>();
     const services: Service[] = compact([
       ...this.services,
       this.publisherService,
+      this.auditorStorageService,
     ]);
 
     try {
-      // Run each service's register method with the sniffer to track env var access
       for (const service of services) {
+        // Check cache first - handles singleton services that short-circuit
+        if (serviceEnvCache.has(service)) {
+          const cached = serviceEnvCache.get(service)!;
+          cached.forEach((v) => envVars.add(v));
+          continue;
+        }
+
+        // Sniff the service for env vars
+        const sniffer = new SnifferEnvironmentParser();
         try {
           const result = service.register(sniffer as any);
 
@@ -60,12 +83,15 @@ export abstract class Construct<
           }
         } catch {
           // Service registration may fail but env vars are still tracked
-          continue;
         }
+
+        // Cache and collect the env vars
+        const serviceEnvVars = sniffer.getEnvironmentVariables();
+        serviceEnvCache.set(service, serviceEnvVars);
+        serviceEnvVars.forEach((v) => envVars.add(v));
       }
 
-      // Get tracked env vars directly from the sniffer
-      return sniffer.getEnvironmentVariables();
+      return Array.from(envVars).sort();
     } catch (error) {
       console.error(
         'Error determining environment variables for construct:',

package/src/endpoints/AmazonApiGatewayEndpointAdaptor.ts

@@ -1,3 +1,4 @@
+import type { AuditableAction, Auditor, AuditStorage } 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 AuditExecutionContext,
+  createAuditContext,
+  executeWithAuditTransaction,
+} from './processAudits';
+import type { MappedAudit } from './audit';
 
 // 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,83 @@ 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)
-      : undefined;
+    // Execute handler with automatic audit transaction support
+    const result = await executeWithAuditTransaction(
+      auditContext,
+      async (auditor) => {
+        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,
+            ...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

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 { AuditableAction, Auditor, AuditStorage } 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 { ActorExtractor, MappedAudit } from './audit';
+import type { Authorizer } from './Authorizer';
 
 /**
  * Represents an HTTP endpoint that can handle requests with type-safe input/output validation,
@@ -65,6 +65,12 @@ 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
+  >,
 > extends Function<
   TInput,
   TServices,
@@ -72,7 +78,9 @@ export class Endpoint<
   OutSchema,
   FunctionHandler<TInput, TServices, TLogger, OutSchema>,
   TEventPublisher,
-  TEventPublisherServiceName
+  TEventPublisherServiceName,
+  TAuditStorage,
+  TAuditStorageServiceName
 > {
   operationId?: string;
   /** The route path pattern with parameter placeholders */
@@ -96,6 +104,10 @@ 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>[] = [];
   /** The endpoint handler function */
   private endpointFn!: EndpointHandler<
     TInput,
@@ -335,6 +347,7 @@ export class Endpoint<
         header: ctx.header,
         cookie: ctx.cookie,
         session: ctx.session,
+        auditor: ctx.auditor,
       } as EndpointContext<TInput, TServices, TLogger, TSession>,
       response,
     );
@@ -540,6 +553,9 @@ export class Endpoint<
     publisherService,
     events,
     authorizer,
+    auditorStorageService,
+    actorExtractor,
+    audits,
   }: EndpointOptions<
     TRoute,
     TMethod,
@@ -550,7 +566,10 @@ export class Endpoint<
     TSession,
     OutSchema,
     TEventPublisher,
-    TEventPublisherServiceName
+    TEventPublisherServiceName,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction
   >) {
     super(
       fn as unknown as FunctionHandler<TInput, TServices, TLogger, OutSchema>,
@@ -563,6 +582,7 @@ export class Endpoint<
       publisherService,
       events,
       memorySize,
+      auditorStorageService,
     );
 
     this.route = route;
@@ -587,6 +607,14 @@ export class Endpoint<
     if (authorizer) {
       this.authorizer = authorizer;
     }
+
+    if (actorExtractor) {
+      this.actorExtractor = actorExtractor;
+    }
+
+    if (audits) {
+      this.audits = audits;
+    }
   }
 }
 
@@ -638,6 +666,12 @@ 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
+  >,
 > {
   /** The route path with parameter placeholders */
   route: TRoute;
@@ -677,6 +711,14 @@ 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>[];
 }
 
 /**
@@ -940,6 +982,10 @@ export type EndpointContext<
   TServices extends Service[] = [],
   TLogger extends Logger = Logger,
   TSession = unknown,
+  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
+    string,
+    unknown
+  >,
 > = {
   /** Injected service instances */
   services: ServiceRecord<TServices>;
@@ -951,6 +997,13 @@ export type EndpointContext<
   cookie: CookieFn;
   /** Session data extracted by getSession */
   session: TSession;
+  /**
+   * 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>;
 } & InferComposableStandardSchema<Input>;
 
 /**