@geekmidas/constructs 0.0.22 → 0.1.0

package/src/endpoints/EndpointFactory.ts

@@ -9,7 +9,11 @@ import { ConsoleLogger } from '@geekmidas/logger/console';
 import type { Service } from '@geekmidas/services';
 import uniqBy from 'lodash.uniqby';
 import type { HttpMethod } from '../types';
-import type { Authorizer } from './Authorizer';
+import type {
+  Authorizer,
+  BuiltInSecuritySchemeId,
+  SecurityScheme,
+} from './Authorizer';
 import type { AuthorizeFn, SessionFn } from './Endpoint';
 import { EndpointBuilder } from './EndpointBuilder';
 import type { ActorExtractor } from './audit';
@@ -32,6 +36,10 @@ export class EndpointFactory<
   > = ExtractStorageAuditAction<NonNullable<TAuditStorage>>,
   TDatabase = undefined,
   TDatabaseServiceName extends string = string,
+  TSecuritySchemes extends Record<string, SecurityScheme> = Record<
+    string,
+    SecurityScheme
+  >,
 > {
   // @ts-ignore
   private defaultServices: TServices;
@@ -56,6 +64,7 @@ export class EndpointFactory<
     | Service<TDatabaseServiceName, TDatabase>
     | undefined;
   private defaultActorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
+  private customSecuritySchemes: TSecuritySchemes = {} as TSecuritySchemes;
 
   constructor({
     basePath,
@@ -70,6 +79,7 @@ export class EndpointFactory<
     defaultAuditorStorage,
     defaultDatabaseService,
     defaultActorExtractor,
+    customSecuritySchemes = {} as TSecuritySchemes,
   }: EndpointFactoryOptions<
     TServices,
     TBasePath,
@@ -81,7 +91,8 @@ export class EndpointFactory<
     TAuditStorage,
     TAuditStorageServiceName,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > = {}) {
     // Initialize default services
     this.defaultServices = uniqBy(
@@ -99,6 +110,7 @@ export class EndpointFactory<
     this.defaultAuditorStorage = defaultAuditorStorage;
     this.defaultDatabaseService = defaultDatabaseService;
     this.defaultActorExtractor = defaultActorExtractor;
+    this.customSecuritySchemes = customSecuritySchemes;
   }
 
   static joinPaths<TBasePath extends string, P extends string>(
@@ -153,7 +165,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     const authorizerConfigs = authorizers.map((name) => ({
       name,
@@ -170,7 +183,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -183,6 +197,73 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
+    });
+  }
+
+  /**
+   * Define custom security schemes for this factory.
+   * These extend the built-in schemes (jwt, bearer, apiKey, oauth2, oidc).
+   *
+   * @example
+   * ```typescript
+   * const router = e.securitySchemes({
+   *   awsIamSigV4: {
+   *     type: 'apiKey',
+   *     in: 'header',
+   *     name: 'Authorization',
+   *     'x-amazon-apigateway-authtype': 'awsSigv4',
+   *   },
+   * });
+   * ```
+   */
+  securitySchemes<T extends Record<string, SecurityScheme>>(
+    schemes: T,
+  ): EndpointFactory<
+    TServices,
+    TBasePath,
+    TLogger,
+    TSession,
+    TEventPublisher,
+    TEventPublisherServiceName,
+    TAuthorizers,
+    TAuditStorage,
+    TAuditStorageServiceName,
+    TAuditAction,
+    TDatabase,
+    TDatabaseServiceName,
+    TSecuritySchemes & T
+  > {
+    return new EndpointFactory<
+      TServices,
+      TBasePath,
+      TLogger,
+      TSession,
+      TEventPublisher,
+      TEventPublisherServiceName,
+      TAuthorizers,
+      TAuditStorage,
+      TAuditStorageServiceName,
+      TAuditAction,
+      TDatabase,
+      TDatabaseServiceName,
+      TSecuritySchemes & T
+    >({
+      defaultServices: this.defaultServices,
+      basePath: this.basePath,
+      defaultAuthorizeFn: this.defaultAuthorizeFn,
+      defaultLogger: this.defaultLogger,
+      defaultSessionExtractor: this.defaultSessionExtractor,
+      defaultEventPublisher: this.defaultEventPublisher,
+      availableAuthorizers: this.availableAuthorizers,
+      defaultAuthorizerName: this.defaultAuthorizerName,
+      defaultAuditorStorage: this.defaultAuditorStorage,
+      defaultDatabaseService: this.defaultDatabaseService,
+      defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: {
+        ...this.customSecuritySchemes,
+        ...schemes,
+      } as TSecuritySchemes & T,
     });
   }
 
@@ -190,9 +271,18 @@ export class EndpointFactory<
    * Set the default authorizer for all endpoints created from this factory.
    * Individual endpoints can override this by calling `.authorizer()` on the builder.
    * Use `'none'` to explicitly disable authorization for all endpoints.
+   *
+   * Accepts:
+   * - Built-in security scheme names: 'jwt', 'bearer', 'apiKey', 'oauth2', 'oidc'
+   * - Custom security scheme names defined via `.securitySchemes()`
+   * - 'none' to disable authorization
    */
   authorizer(
-    name: TAuthorizers[number] | 'none',
+    name:
+      | BuiltInSecuritySchemeId
+      | keyof TSecuritySchemes
+      | TAuthorizers[number]
+      | 'none',
   ): EndpointFactory<
     TServices,
     TBasePath,
@@ -205,9 +295,10 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
-    // Validate that the authorizer exists in available authorizers
+    // Validate that the authorizer exists in available authorizers (if authorizers() was called)
     if (name !== 'none' && this.availableAuthorizers.length > 0) {
       const authorizerExists = this.availableAuthorizers.some(
         (a) => a.name === name,
@@ -234,7 +325,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -243,10 +335,12 @@ export class EndpointFactory<
       defaultSessionExtractor: this.defaultSessionExtractor,
       defaultEventPublisher: this.defaultEventPublisher,
       availableAuthorizers: this.availableAuthorizers,
-      defaultAuthorizerName: name === 'none' ? undefined : name,
+      defaultAuthorizerName:
+        name === 'none' ? undefined : (name as TAuthorizers[number]),
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -265,7 +359,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     const newBasePath = EndpointFactory.joinPaths(path, this.basePath);
     return new EndpointFactory<
@@ -280,7 +375,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: newBasePath,
@@ -293,6 +389,7 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -311,7 +408,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -325,7 +423,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -338,6 +437,7 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -356,7 +456,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       [...S, ...TServices],
@@ -370,7 +471,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: [...services, ...this.defaultServices],
       basePath: this.basePath,
@@ -383,6 +485,7 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -400,7 +503,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -414,7 +518,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -441,6 +546,7 @@ export class EndpointFactory<
         TSession,
         L
       >,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -461,7 +567,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -475,7 +582,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -488,6 +596,7 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: this.defaultActorExtractor,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -505,7 +614,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -519,7 +629,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -541,6 +652,7 @@ export class EndpointFactory<
         T,
         TLogger
       >,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -562,7 +674,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     T,
-    TName
+    TName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -576,7 +689,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       T,
-      TName
+      TName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -592,6 +706,7 @@ export class EndpointFactory<
       defaultAuthorizerName: this.defaultAuthorizerName,
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: service,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -614,7 +729,8 @@ export class EndpointFactory<
     TName,
     ExtractStorageAuditAction<T>,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -628,7 +744,8 @@ export class EndpointFactory<
       TName,
       ExtractStorageAuditAction<T>,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -646,6 +763,7 @@ export class EndpointFactory<
         TSession,
         TLogger
       >,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -667,7 +785,8 @@ export class EndpointFactory<
     TAuditStorageServiceName,
     TAuditAction,
     TDatabase,
-    TDatabaseServiceName
+    TDatabaseServiceName,
+    TSecuritySchemes
   > {
     return new EndpointFactory<
       TServices,
@@ -681,7 +800,8 @@ export class EndpointFactory<
       TAuditStorageServiceName,
       TAuditAction,
       TDatabase,
-      TDatabaseServiceName
+      TDatabaseServiceName,
+      TSecuritySchemes
     >({
       defaultServices: this.defaultServices,
       basePath: this.basePath,
@@ -694,6 +814,7 @@ export class EndpointFactory<
       defaultAuditorStorage: this.defaultAuditorStorage,
       defaultDatabaseService: this.defaultDatabaseService,
       defaultActorExtractor: extractor,
+      customSecuritySchemes: this.customSecuritySchemes,
     });
   }
 
@@ -782,6 +903,9 @@ export class EndpointFactory<
       builder._actorExtractor = this.defaultActorExtractor;
     }
 
+    // Set custom security schemes
+    builder._customSecuritySchemes = this.customSecuritySchemes;
+
     return builder;
   }
 
@@ -849,6 +973,10 @@ export interface EndpointFactoryOptions<
   TAuditStorageServiceName extends string = string,
   TDatabase = undefined,
   TDatabaseServiceName extends string = string,
+  TSecuritySchemes extends Record<string, SecurityScheme> = Record<
+    string,
+    SecurityScheme
+  >,
 > {
   defaultServices?: TServices;
   basePath?: TBasePath;
@@ -862,6 +990,7 @@ export interface EndpointFactoryOptions<
   defaultAuditorStorage?: Service<TAuditStorageServiceName, TAuditStorage>;
   defaultDatabaseService?: Service<TDatabaseServiceName, TDatabase>;
   defaultActorExtractor?: ActorExtractor<TServices, TSession, TLogger>;
+  customSecuritySchemes?: TSecuritySchemes;
 }
 
 export const e = new EndpointFactory();

package/src/endpoints/HonoEndpointAdaptor.ts

@@ -443,6 +443,8 @@ export class HonoEndpoint<
                 });
               }
             },
+            // Pass rawDb so storage can reuse existing transactions
+            { db: rawDb },
           );
 
           const { output, metadata } = result;

package/src/endpoints/TestEndpointAdaptor.ts

@@ -293,6 +293,8 @@ export class TestEndpointAdaptor<
           });
         }
       },
+      // Pass rawDb so storage can reuse existing transactions
+      { db: rawDb },
     );
 
     const { output, metadata } = result;

package/src/endpoints/processAudits.ts

@@ -5,7 +5,6 @@ import type {
   Auditor,
 } 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';
@@ -288,14 +287,34 @@ export async function createAuditContext<
   return { auditor, storage };
 }
 
+/**
+ * Options for executeWithAuditTransaction.
+ */
+export interface ExecuteWithAuditTransactionOptions {
+  /**
+   * Database connection to use for the transaction.
+   * If this is already a transaction, it will be reused instead of creating a nested one.
+   * If not provided, the storage's internal database is used.
+   */
+  db?: unknown;
+}
+
 /**
  * Execute a handler with automatic audit transaction support.
- * If the audit storage has a database (via getDatabase()), wraps execution
+ * If the audit storage provides a withTransaction method, wraps execution
  * in a transaction so audits are atomic with handler's database operations.
  *
+ * This is database-agnostic - each storage implementation provides its own
+ * transaction handling based on the underlying database (Kysely, Drizzle, etc.).
+ *
+ * If the db parameter is provided and is already a transaction, the storage
+ * will reuse it instead of creating a nested transaction (similar to
+ * packages/db/src/kysely.ts#withTransaction).
+ *
  * @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
+ * @param options - Optional configuration including database connection
  * @returns The handler result
  */
 export async function executeWithAuditTransaction<
@@ -308,6 +327,7 @@ export async function executeWithAuditTransaction<
   auditContext: AuditExecutionContext<TAuditAction> | undefined,
   handler: (auditor?: Auditor<TAuditAction>) => Promise<T>,
   onComplete?: (response: T, auditor: Auditor<TAuditAction>) => Promise<void>,
+  options?: ExecuteWithAuditTransactionOptions,
 ): Promise<T> {
   // No audit context - just run handler
   if (!auditContext) {
@@ -316,25 +336,28 @@ export async function executeWithAuditTransaction<
 
   const { auditor, storage } = auditContext;
 
-  // Check if storage has a database for transactional execution
-  const db = storage.getDatabase?.();
-
-  if (db) {
+  // Check if storage provides a transaction wrapper
+  if (storage.withTransaction) {
     // Wrap in transaction - audits are atomic with handler operations
-    return withAuditableTransaction(db as any, auditor as any, async () => {
-      const response = await handler(auditor);
+    // The storage's withTransaction handles setTransaction and flush
+    // Pass db so existing transactions are reused
+    return storage.withTransaction(
+      auditor,
+      async () => {
+        const response = await handler(auditor);
 
-      // Process declarative audits within the transaction
-      if (onComplete) {
-        await onComplete(response, auditor);
-      }
+        // Process declarative audits within the transaction
+        if (onComplete) {
+          await onComplete(response, auditor);
+        }
 
-      // Audits are flushed by withAuditableTransaction before commit
-      return response;
-    });
+        return response;
+      },
+      options?.db,
+    );
   }
 
-  // No database - run handler and flush audits after
+  // No transaction support - run handler and flush audits after
   const response = await handler(auditor);
 
   if (onComplete) {

package/dist/Authorizer-BTmly8ps.d.cts

@@ -1,29 +0,0 @@
-//#region src/endpoints/Authorizer.d.ts
-/**
- * Represents an authorizer configuration for endpoints
- */
-interface Authorizer {
-  /**
-   * Unique identifier for the authorizer
-   */
-  name: string;
-  /**
-   * Type of authorizer (e.g., 'iam', 'jwt', 'custom')
-   */
-  type?: string;
-  /**
-   * Description of what this authorizer does
-   */
-  description?: string;
-  /**
-   * Additional metadata specific to the authorizer type
-   */
-  metadata?: Record<string, any>;
-}
-/**
- * Helper to create an authorizer configuration
- */
-declare function createAuthorizer(name: string, options?: Omit<Authorizer, 'name'>): Authorizer;
-//#endregion
-export { Authorizer, createAuthorizer };
-//# sourceMappingURL=Authorizer-BTmly8ps.d.cts.map

package/dist/Authorizer-pmPvIVgv.d.mts

@@ -1,29 +0,0 @@
-//#region src/endpoints/Authorizer.d.ts
-/**
- * Represents an authorizer configuration for endpoints
- */
-interface Authorizer {
-  /**
-   * Unique identifier for the authorizer
-   */
-  name: string;
-  /**
-   * Type of authorizer (e.g., 'iam', 'jwt', 'custom')
-   */
-  type?: string;
-  /**
-   * Description of what this authorizer does
-   */
-  description?: string;
-  /**
-   * Additional metadata specific to the authorizer type
-   */
-  metadata?: Record<string, any>;
-}
-/**
- * Helper to create an authorizer configuration
- */
-declare function createAuthorizer(name: string, options?: Omit<Authorizer, 'name'>): Authorizer;
-//#endregion
-export { Authorizer, createAuthorizer };
-//# sourceMappingURL=Authorizer-pmPvIVgv.d.mts.map