@geekmidas/constructs 0.0.10 → 0.0.12

package/src/endpoints/__tests__/HonoEndpointAdaptor.spec.ts

@@ -31,6 +31,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -68,6 +69,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -118,6 +120,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -157,6 +160,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -195,6 +199,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -233,6 +238,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -266,6 +272,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -305,6 +312,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -345,6 +353,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -397,6 +406,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -434,6 +444,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -482,6 +493,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [TestService],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -523,6 +535,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: customLogger as Logger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -579,6 +592,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -636,6 +650,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         authorize: undefined,
         status: 200,
         getSession: undefined,
@@ -690,6 +705,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         authorize: undefined,
         status: 200,
         getSession: undefined,
@@ -765,6 +781,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -794,6 +811,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -826,6 +844,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: undefined,
@@ -883,6 +902,7 @@ describe('HonoEndpointAdaptor', () => {
           return services.authService.isValidToken(token);
         },
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         description: undefined,
@@ -917,6 +937,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: async ({ header }) => {
           const token = header('authorization');
@@ -958,6 +979,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: undefined,
         getSession: undefined,
         authorize: async () => {
@@ -993,6 +1015,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: 200,
         getSession: undefined,
         authorize: undefined,
@@ -1030,6 +1053,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: 200,
         getSession: undefined,
         authorize: undefined,
@@ -1059,6 +1083,7 @@ describe('HonoEndpointAdaptor', () => {
         services: [],
         logger: mockLogger,
         timeout: undefined,
+        memorySize: undefined,
         status: 200,
         getSession: undefined,
         authorize: undefined,

package/src/endpoints/audit.ts

@@ -0,0 +1,87 @@
+import type {
+  AuditableAction,
+  AuditActor,
+  AuditStorage,
+  ExtractAuditPayload,
+  ExtractAuditType,
+} from '@geekmidas/audit';
+import type { Logger } from '@geekmidas/logger';
+import type { InferStandardSchema } from '@geekmidas/schema';
+import type { Service, ServiceRecord } from '@geekmidas/services';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { CookieFn, HeaderFn } from './Endpoint';
+
+/**
+ * Defines how to map an endpoint response to an audit record.
+ * Similar to MappedEvent for events.
+ *
+ * @template TAuditAction - Union of all allowed audit action types
+ * @template TOutput - The output schema of the endpoint
+ */
+export interface MappedAudit<
+  TAuditAction extends AuditableAction<string, unknown>,
+  TOutput extends StandardSchemaV1 | undefined,
+  TType extends ExtractAuditType<TAuditAction> = ExtractAuditType<TAuditAction>,
+> {
+  /** The audit type (must be a valid type from TAuditAction) */
+  type: TType;
+  /** Function to extract payload from the endpoint response */
+  payload: (
+    response: TOutput extends StandardSchemaV1
+      ? InferStandardSchema<TOutput>
+      : unknown,
+  ) => ExtractAuditPayload<TAuditAction, TType>;
+  /** Optional condition to determine if audit should be recorded */
+  when?: (
+    response: TOutput extends StandardSchemaV1
+      ? InferStandardSchema<TOutput>
+      : unknown,
+  ) => boolean;
+  /** Optional function to extract entity ID for easier querying */
+  entityId?: (
+    response: TOutput extends StandardSchemaV1
+      ? InferStandardSchema<TOutput>
+      : unknown,
+  ) => string | Record<string, unknown>;
+  /** Optional table name for the audit record */
+  table?: string;
+}
+
+/**
+ * Function type for extracting actor information from request context.
+ *
+ * @template TServices - Available service dependencies
+ * @template TSession - Session data type
+ * @template TLogger - Logger type
+ */
+export type ActorExtractor<
+  TServices extends Service[] = [],
+  TSession = unknown,
+  TLogger extends Logger = Logger,
+> = (ctx: {
+  services: ServiceRecord<TServices>;
+  session: TSession;
+  header: HeaderFn;
+  cookie: CookieFn;
+  logger: TLogger;
+}) => AuditActor | Promise<AuditActor>;
+
+/**
+ * Configuration for the auditor on an endpoint.
+ */
+export interface EndpointAuditorConfig<
+  TAuditStorage extends AuditStorage,
+  TAuditStorageServiceName extends string,
+  TServices extends Service[],
+  TSession,
+  TLogger extends Logger,
+  TAuditAction extends AuditableAction<string, unknown>,
+  TOutput extends StandardSchemaV1 | undefined,
+> {
+  /** The audit storage service */
+  storageService: Service<TAuditStorageServiceName, TAuditStorage>;
+  /** Optional actor extractor function */
+  actorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
+  /** Declarative audit definitions */
+  audits: MappedAudit<TAuditAction, TOutput>[];
+}

package/src/endpoints/index.ts

@@ -9,5 +9,6 @@ export {
   type EndpointContext,
 } from './Endpoint';
 export { EndpointBuilder } from './EndpointBuilder';
+export { type MappedAudit, type ActorExtractor } from './audit';
 
 export const e = new EndpointFactory();

package/src/endpoints/processAudits.ts

@@ -0,0 +1,339 @@
+import type {
+  AuditableAction,
+  AuditActor,
+  Auditor,
+  AuditStorage,
+} from '@geekmidas/audit';
+import { DefaultAuditor } from '@geekmidas/audit';
+import { withAuditableTransaction } from '@geekmidas/audit/kysely';
+import type { Logger } from '@geekmidas/logger';
+import type { InferStandardSchema } from '@geekmidas/schema';
+import type { Service, ServiceDiscovery } from '@geekmidas/services';
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { Endpoint, CookieFn, HeaderFn } from './Endpoint';
+import type { ActorExtractor, MappedAudit } from './audit';
+
+/**
+ * Process declarative audit definitions after successful endpoint execution.
+ * Similar to publishConstructEvents for events.
+ *
+ * @param endpoint - The endpoint with audit configuration
+ * @param response - The handler response to generate audit payloads from
+ * @param serviceDiscovery - Service discovery for registering audit storage
+ * @param logger - Logger for debug/error messages
+ * @param ctx - Request context (session, headers, cookies, services)
+ * @param existingAuditor - Optional existing auditor instance (e.g., from handler context).
+ *                          If provided, uses this auditor (with its stored transaction).
+ *                          If not provided, creates a new auditor.
+ */
+export async function processEndpointAudits<
+  TServices extends Service[] = [],
+  TSession = unknown,
+  TLogger extends Logger = Logger,
+  OutSchema extends StandardSchemaV1 | undefined = undefined,
+  TAuditStorage extends AuditStorage | undefined = undefined,
+  TAuditStorageServiceName extends string = string,
+  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
+    string,
+    unknown
+  >,
+>(
+  endpoint: Endpoint<
+    any,
+    any,
+    any,
+    OutSchema,
+    TServices,
+    TLogger,
+    TSession,
+    any,
+    any,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction
+  >,
+  response: InferStandardSchema<OutSchema>,
+  serviceDiscovery: ServiceDiscovery<any, any>,
+  logger: TLogger,
+  ctx: {
+    session: TSession;
+    header: HeaderFn;
+    cookie: CookieFn;
+    services: Record<string, unknown>;
+  },
+  existingAuditor?: Auditor<TAuditAction>,
+): Promise<void> {
+  try {
+    const audits = endpoint.audits as MappedAudit<TAuditAction, OutSchema>[];
+
+    // If we have an existing auditor (from handler context), we need to flush
+    // any manual audits it collected, even if there are no declarative audits
+    const hasExistingRecords = existingAuditor && existingAuditor.getRecords().length > 0;
+
+    // Skip if no declarative audits and no existing records to flush
+    if (!audits?.length && !hasExistingRecords) {
+      logger.debug('No audits to process');
+      return;
+    }
+
+    // If no auditor storage service and we have things to process, warn
+    if (!endpoint.auditorStorageService) {
+      if (hasExistingRecords || audits?.length) {
+        logger.warn('No auditor storage service available');
+      }
+      return;
+    }
+
+    // Get or create auditor
+    let auditor: Auditor<TAuditAction>;
+
+    if (existingAuditor) {
+      // Use existing auditor (preserves stored transaction and manual audits)
+      auditor = existingAuditor;
+      logger.debug('Using existing auditor from handler context');
+    } else {
+      // Create new auditor (backward compatibility)
+      const services = await serviceDiscovery.register([
+        endpoint.auditorStorageService,
+      ]);
+      const storage = services[
+        endpoint.auditorStorageService.serviceName
+      ] as AuditStorage;
+
+      // Extract actor if configured
+      let actor: AuditActor = { id: 'system', type: 'system' };
+      if (endpoint.actorExtractor) {
+        try {
+          actor = await (
+            endpoint.actorExtractor as ActorExtractor<TServices, TSession, TLogger>
+          )({
+            services: ctx.services as any,
+            session: ctx.session,
+            header: ctx.header,
+            cookie: ctx.cookie,
+            logger,
+          });
+        } catch (error) {
+          logger.error(error as Error, 'Failed to extract actor for audits');
+          // Continue with system actor
+        }
+      }
+
+      auditor = new DefaultAuditor<TAuditAction>({
+        actor,
+        storage,
+        metadata: {
+          endpoint: endpoint.route,
+          method: endpoint.method,
+        },
+      });
+    }
+
+    // Process each declarative audit
+    if (audits?.length) {
+      for (const audit of audits) {
+        logger.debug({ audit: audit.type }, 'Processing declarative audit');
+
+        // Check when condition
+        if (audit.when && !audit.when(response as any)) {
+          logger.debug({ audit: audit.type }, 'Audit skipped due to when condition');
+          continue;
+        }
+
+        // Extract payload
+        const payload = audit.payload(response as any);
+
+        // Extract entityId if configured
+        const entityId = audit.entityId?.(response as any);
+
+        // Record the audit
+        auditor.audit(audit.type as any, payload as any, {
+          table: audit.table,
+          entityId,
+        });
+      }
+    }
+
+    // Flush audits to storage
+    // Note: If existingAuditor has a stored transaction (via setTransaction),
+    // flush() will use it automatically
+    const recordCount = auditor.getRecords().length;
+    if (recordCount > 0) {
+      // Check if auditor has a stored transaction (for logging purposes)
+      const trx = 'getTransaction' in auditor
+        ? (auditor as { getTransaction(): unknown }).getTransaction()
+        : undefined;
+      logger.debug(
+        { auditCount: recordCount, hasTransaction: !!trx },
+        'Flushing audits',
+      );
+      await auditor.flush();
+    }
+  } catch (error) {
+    logger.error(error as Error, 'Failed to process audits');
+    // Don't rethrow - audit failures shouldn't fail the request
+  }
+}
+
+/**
+ * Context for audit-aware handler execution.
+ */
+export interface AuditExecutionContext<
+  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
+    string,
+    unknown
+  >,
+> {
+  /** The auditor instance for recording audits */
+  auditor: Auditor<TAuditAction>;
+  /** The audit storage instance */
+  storage: AuditStorage;
+}
+
+/**
+ * Create audit context for handler execution.
+ * Returns the auditor and storage for use in the handler.
+ *
+ * @param endpoint - The endpoint with audit configuration
+ * @param serviceDiscovery - Service discovery for getting audit storage
+ * @param logger - Logger for debug/error messages
+ * @param ctx - Request context for actor extraction
+ * @returns Audit context with auditor and storage, or undefined if not configured
+ */
+export async function createAuditContext<
+  TServices extends Service[] = [],
+  TSession = unknown,
+  TLogger extends Logger = Logger,
+  TAuditStorage extends AuditStorage | undefined = undefined,
+  TAuditStorageServiceName extends string = string,
+  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
+    string,
+    unknown
+  >,
+>(
+  endpoint: Endpoint<
+    any,
+    any,
+    any,
+    any,
+    TServices,
+    TLogger,
+    TSession,
+    any,
+    any,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction
+  >,
+  serviceDiscovery: ServiceDiscovery<any, any>,
+  logger: TLogger,
+  ctx: {
+    session: TSession;
+    header: HeaderFn;
+    cookie: CookieFn;
+    services: Record<string, unknown>;
+  },
+): Promise<AuditExecutionContext<TAuditAction> | undefined> {
+  if (!endpoint.auditorStorageService) {
+    return undefined;
+  }
+
+  const services = await serviceDiscovery.register([
+    endpoint.auditorStorageService,
+  ]);
+  const storage = services[
+    endpoint.auditorStorageService.serviceName
+  ] as AuditStorage;
+
+  // Extract actor if configured
+  let actor: AuditActor = { id: 'system', type: 'system' };
+  if (endpoint.actorExtractor) {
+    try {
+      actor = await (
+        endpoint.actorExtractor as ActorExtractor<TServices, TSession, TLogger>
+      )({
+        services: ctx.services as any,
+        session: ctx.session,
+        header: ctx.header,
+        cookie: ctx.cookie,
+        logger,
+      });
+    } catch (error) {
+      logger.error(error as Error, 'Failed to extract actor for audits');
+    }
+  }
+
+  const auditor = new DefaultAuditor<TAuditAction>({
+    actor,
+    storage,
+    metadata: {
+      endpoint: endpoint.route,
+      method: endpoint.method,
+    },
+  });
+
+  return { auditor, storage };
+}
+
+/**
+ * Execute a handler with automatic audit transaction support.
+ * If the audit storage has a database (via getDatabase()), wraps execution
+ * in a transaction so audits are atomic with handler's database operations.
+ *
+ * @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
+ * @returns The handler result
+ */
+export async function executeWithAuditTransaction<
+  T,
+  TAuditAction extends AuditableAction<string, unknown> = AuditableAction<
+    string,
+    unknown
+  >,
+>(
+  auditContext: AuditExecutionContext<TAuditAction> | undefined,
+  handler: (auditor?: Auditor<TAuditAction>) => Promise<T>,
+  onComplete?: (response: T, auditor: Auditor<TAuditAction>) => Promise<void>,
+): Promise<T> {
+  // No audit context - just run handler
+  if (!auditContext) {
+    return handler(undefined);
+  }
+
+  const { auditor, storage } = auditContext;
+
+  // Check if storage has a database for transactional execution
+  const db = storage.getDatabase?.();
+
+  if (db) {
+    // Wrap in transaction - audits are atomic with handler operations
+    return withAuditableTransaction(
+      db as any,
+      auditor as any,
+      async () => {
+        const response = await handler(auditor);
+
+        // Process declarative audits within the transaction
+        if (onComplete) {
+          await onComplete(response, auditor);
+        }
+
+        // Audits are flushed by withAuditableTransaction before commit
+        return response;
+      },
+    );
+  }
+
+  // No database - run handler and flush audits after
+  const response = await handler(auditor);
+
+  if (onComplete) {
+    await onComplete(response, auditor);
+  }
+
+  // Flush audits (no transaction)
+  await auditor.flush();
+
+  return response;
+}