serverless-event-orchestrator 2.0.1 → 2.3.0

package/src/tenant/TenantContext.ts

@@ -1,115 +1,115 @@
-import { AsyncLocalStorage } from 'node:async_hooks';
-import type { TenantInfo } from './types.js';
-
-/**
- * TenantContext provides thread-safe (async-safe) access to the current tenant context.
- *
- * Uses Node.js AsyncLocalStorage to maintain TenantInfo throughout the
- * execution of a request without needing to pass it as a parameter.
- *
- * Initialization:
- *   - In HTTP requests: the `initTenantContext` middleware extracts the tenant
- *     from JWT claims or headers and calls `TenantContext.set()`.
- *   - In EventBridge/SQS: the handler extracts tenantId from event.detail and calls `TenantContext.run()`.
- *
- * Consumption:
- *   - TenantAwareDynamoRepository: `TenantContext.current().tenantId`
- *   - ApiInvoker: `TenantContext.currentOptional()` to propagate headers
- *   - Use cases: `TenantContext.current()` when they need the tenant explicitly
- *
- * IMPORTANT:
- *   - `current()` is FAIL-CLOSED: throws error if no context (prevents data leaks).
- *   - `currentOptional()` returns undefined without error (for code that works with/without tenant).
- *   - `run()` is for scenarios where an explicit scope is needed (EventBridge handlers).
- *   - `set()` is for the orchestrator middleware that operates in the same async scope.
- */
-export class TenantContext {
-  private static storage = new AsyncLocalStorage<TenantInfo>();
-
-  /**
-   * Executes a callback within a tenant context.
-   * Useful for EventBridge/SQS handlers where there's no orchestrator middleware.
-   *
-   * @example
-   * ```typescript
-   * await TenantContext.run(tenantInfo, async () => {
-   *   const props = await propertiesRepo.findByStatus('PUBLISHED');
-   *   // propertiesRepo automatically filters by tenantInfo.tenantId
-   * });
-   * ```
-   */
-  static run<T>(tenant: TenantInfo, callback: () => T): T {
-    return this.storage.run(tenant, callback);
-  }
-
-  /**
-   * Sets the tenant context in the current AsyncLocalStorage store.
-   * ONLY should be called by the initTenantContext middleware.
-   *
-   * NOTE: Requires an active store (created by AsyncLocalStorage.run()
-   * or by the Lambda runtime). If called outside an async context,
-   * the value is lost. For those cases, use `run()`.
-   *
-   * Internally uses enterWith() which replaces the current store.
-   */
-  static set(tenant: TenantInfo): void {
-    this.storage.enterWith(tenant);
-  }
-
-  /**
-   * Gets the current TenantInfo. FAIL-CLOSED: throws error if not initialized.
-   * Use in code that REQUIRES a tenant (repositories, guards).
-   *
-   * @throws Error if TenantContext is not initialized
-   *
-   * @example
-   * ```typescript
-   * const { tenantId } = TenantContext.current();
-   * // Safe: if we get here, tenantId exists
-   * ```
-   */
-  static current(): TenantInfo {
-    const tenant = this.storage.getStore();
-    if (!tenant) {
-      throw new Error(
-        'TenantContext not initialized. Ensure initTenantContext middleware is configured ' +
-        'in globalMiddleware, or use TenantContext.run() for non-HTTP triggers.'
-      );
-    }
-    return tenant;
-  }
-
-  /**
-   * Gets the current TenantInfo or undefined if not initialized.
-   * Use in code that works with or without tenant (ApiInvoker, loggers, public routes).
-   *
-   * @example
-   * ```typescript
-   * const tenant = TenantContext.currentOptional();
-   * if (tenant) {
-   *   headers['x-tenant-id'] = tenant.tenantId;
-   * }
-   * ```
-   */
-  static currentOptional(): TenantInfo | undefined {
-    return this.storage.getStore();
-  }
-
-  /**
-   * Checks if there's an active tenant context.
-   * Useful for conditionals without getting the full object.
-   */
-  static isActive(): boolean {
-    return this.storage.getStore() !== undefined;
-  }
-
-  /**
-   * Clears the current context. Only for testing.
-   * DO NOT use in production — the context is automatically cleaned when exiting the scope.
-   * @internal
-   */
-  static _reset(): void {
-    this.storage.disable();
-    (this as any).storage = new AsyncLocalStorage<TenantInfo>();
-  }
-}
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { TenantInfo } from './types.js';
+
+/**
+ * TenantContext provides thread-safe (async-safe) access to the current tenant context.
+ *
+ * Uses Node.js AsyncLocalStorage to maintain TenantInfo throughout the
+ * execution of a request without needing to pass it as a parameter.
+ *
+ * Initialization:
+ *   - In HTTP requests: the `initTenantContext` middleware extracts the tenant
+ *     from JWT claims or headers and calls `TenantContext.set()`.
+ *   - In EventBridge/SQS: the handler extracts tenantId from event.detail and calls `TenantContext.run()`.
+ *
+ * Consumption:
+ *   - TenantAwareDynamoRepository: `TenantContext.current().tenantId`
+ *   - ApiInvoker: `TenantContext.currentOptional()` to propagate headers
+ *   - Use cases: `TenantContext.current()` when they need the tenant explicitly
+ *
+ * IMPORTANT:
+ *   - `current()` is FAIL-CLOSED: throws error if no context (prevents data leaks).
+ *   - `currentOptional()` returns undefined without error (for code that works with/without tenant).
+ *   - `run()` is for scenarios where an explicit scope is needed (EventBridge handlers).
+ *   - `set()` is for the orchestrator middleware that operates in the same async scope.
+ */
+export class TenantContext {
+  private static storage = new AsyncLocalStorage<TenantInfo>();
+
+  /**
+   * Executes a callback within a tenant context.
+   * Useful for EventBridge/SQS handlers where there's no orchestrator middleware.
+   *
+   * @example
+   * ```typescript
+   * await TenantContext.run(tenantInfo, async () => {
+   *   const props = await propertiesRepo.findByStatus('PUBLISHED');
+   *   // propertiesRepo automatically filters by tenantInfo.tenantId
+   * });
+   * ```
+   */
+  static run<T>(tenant: TenantInfo, callback: () => T): T {
+    return this.storage.run(tenant, callback);
+  }
+
+  /**
+   * Sets the tenant context in the current AsyncLocalStorage store.
+   * ONLY should be called by the initTenantContext middleware.
+   *
+   * NOTE: Requires an active store (created by AsyncLocalStorage.run()
+   * or by the Lambda runtime). If called outside an async context,
+   * the value is lost. For those cases, use `run()`.
+   *
+   * Internally uses enterWith() which replaces the current store.
+   */
+  static set(tenant: TenantInfo): void {
+    this.storage.enterWith(tenant);
+  }
+
+  /**
+   * Gets the current TenantInfo. FAIL-CLOSED: throws error if not initialized.
+   * Use in code that REQUIRES a tenant (repositories, guards).
+   *
+   * @throws Error if TenantContext is not initialized
+   *
+   * @example
+   * ```typescript
+   * const { tenantId } = TenantContext.current();
+   * // Safe: if we get here, tenantId exists
+   * ```
+   */
+  static current(): TenantInfo {
+    const tenant = this.storage.getStore();
+    if (!tenant) {
+      throw new Error(
+        'TenantContext not initialized. Ensure initTenantContext middleware is configured ' +
+        'in globalMiddleware, or use TenantContext.run() for non-HTTP triggers.'
+      );
+    }
+    return tenant;
+  }
+
+  /**
+   * Gets the current TenantInfo or undefined if not initialized.
+   * Use in code that works with or without tenant (ApiInvoker, loggers, public routes).
+   *
+   * @example
+   * ```typescript
+   * const tenant = TenantContext.currentOptional();
+   * if (tenant) {
+   *   headers['x-tenant-id'] = tenant.tenantId;
+   * }
+   * ```
+   */
+  static currentOptional(): TenantInfo | undefined {
+    return this.storage.getStore();
+  }
+
+  /**
+   * Checks if there's an active tenant context.
+   * Useful for conditionals without getting the full object.
+   */
+  static isActive(): boolean {
+    return this.storage.getStore() !== undefined;
+  }
+
+  /**
+   * Clears the current context. Only for testing.
+   * DO NOT use in production — the context is automatically cleaned when exiting the scope.
+   * @internal
+   */
+  static _reset(): void {
+    this.storage.disable();
+    (this as any).storage = new AsyncLocalStorage<TenantInfo>();
+  }
+}

package/src/tenant/helpers.ts

@@ -1,112 +1,112 @@
-import type { TenantInfo } from './types.js';
-import { isTenantType, isPlan, TENANT_HEADERS } from './types.js';
-
-/**
- * Resolves a claim value by checking both `custom:{key}` and `{key}` formats.
- * Cognito Pre Token Generation V2 adds claims WITHOUT the `custom:` prefix,
- * while Cognito user pool custom attributes use the `custom:` prefix.
- * This helper supports both conventions transparently.
- */
-function getClaim(claims: Record<string, any>, key: string): any {
-  return claims[`custom:${key}`] ?? claims[key];
-}
-
-/**
- * Builds a TenantInfo from TenantClaims in the JWT.
- * Used by initTenantContext middleware in serverless-event-orchestrator.
- *
- * Supports claims with or without the `custom:` prefix:
- * - `custom:tenantId` (Cognito user pool custom attributes)
- * - `tenantId` (Cognito Pre Token Generation V2 added claims)
- *
- * @param claims - Partial claims object from JWT (event.context.identity.claims)
- * @returns TenantInfo if all required fields are present, undefined otherwise
- */
-export function tenantInfoFromClaims(claims: Record<string, any>): TenantInfo | undefined {
-  const tenantId = getClaim(claims, 'tenantId');
-  const tenantType = getClaim(claims, 'tenantType');
-  const userId = getClaim(claims, 'userId') || claims['sub'];
-  const countryCode = getClaim(claims, 'countryCode');
-  const personProfileId = getClaim(claims, 'personProfileId');
-  const orgProfileId = getClaim(claims, 'orgProfileId');
-  const hasCRM = getClaim(claims, 'hasCRM');
-
-  if (!tenantId || !tenantType || !userId || !countryCode) {
-    return undefined;
-  }
-
-  if (!isTenantType(tenantType)) {
-    return undefined;
-  }
-
-  return {
-    tenantId,
-    tenantType,
-    userId,
-    personProfileId,
-    orgProfileId,
-    countryCode,
-    plan: isPlan(getClaim(claims, 'plan')) ? getClaim(claims, 'plan') : undefined,
-    hasCRM,
-  };
-}
-
-/**
- * Builds a TenantInfo from headers (Lambda-to-Lambda).
- * Used by initTenantContext middleware for internal routes.
- *
- * @param headers - Headers object (may have original or lowercase keys)
- * @returns TenantInfo if all required fields are present, undefined otherwise
- */
-export function tenantInfoFromHeaders(
-  headers: Record<string, string | undefined>
-): TenantInfo | undefined {
-  const get = (key: string) => headers[key] || headers[key.toLowerCase()];
-
-  const tenantId = get(TENANT_HEADERS.TENANT_ID);
-  const tenantType = get(TENANT_HEADERS.TENANT_TYPE);
-  const userId = get(TENANT_HEADERS.USER_ID);
-  const countryCode = get(TENANT_HEADERS.COUNTRY_CODE);
-
-  if (!tenantId || !tenantType || !userId || !countryCode) {
-    return undefined;
-  }
-
-  if (!isTenantType(tenantType)) {
-    return undefined;
-  }
-
-  return {
-    tenantId,
-    tenantType: tenantType as 'ORG' | 'PERSON',
-    userId,
-    personProfileId: get(TENANT_HEADERS.PERSON_PROFILE_ID),
-    orgProfileId: get(TENANT_HEADERS.ORG_PROFILE_ID),
-    countryCode,
-  };
-}
-
-/**
- * Converts TenantInfo to headers for Lambda-to-Lambda propagation.
- * Used by ApiInvoker to propagate the context.
- *
- * @param tenant - TenantInfo to serialize
- * @returns Headers object with X-Tenant-* headers
- */
-export function tenantInfoToHeaders(tenant: TenantInfo): Record<string, string> {
-  const headers: Record<string, string> = {
-    [TENANT_HEADERS.TENANT_ID]: tenant.tenantId,
-    [TENANT_HEADERS.TENANT_TYPE]: tenant.tenantType,
-    [TENANT_HEADERS.USER_ID]: tenant.userId,
-    [TENANT_HEADERS.COUNTRY_CODE]: tenant.countryCode,
-  };
-
-  if (tenant.personProfileId) {
-    headers[TENANT_HEADERS.PERSON_PROFILE_ID] = tenant.personProfileId;
-  }
-  if (tenant.orgProfileId) {
-    headers[TENANT_HEADERS.ORG_PROFILE_ID] = tenant.orgProfileId;
-  }
-
-  return headers;
-}
+import type { TenantInfo } from './types.js';
+import { isTenantType, isPlan, TENANT_HEADERS } from './types.js';
+
+/**
+ * Resolves a claim value by checking both `custom:{key}` and `{key}` formats.
+ * Cognito Pre Token Generation V2 adds claims WITHOUT the `custom:` prefix,
+ * while Cognito user pool custom attributes use the `custom:` prefix.
+ * This helper supports both conventions transparently.
+ */
+function getClaim(claims: Record<string, any>, key: string): any {
+  return claims[`custom:${key}`] ?? claims[key];
+}
+
+/**
+ * Builds a TenantInfo from TenantClaims in the JWT.
+ * Used by initTenantContext middleware in serverless-event-orchestrator.
+ *
+ * Supports claims with or without the `custom:` prefix:
+ * - `custom:tenantId` (Cognito user pool custom attributes)
+ * - `tenantId` (Cognito Pre Token Generation V2 added claims)
+ *
+ * @param claims - Partial claims object from JWT (event.context.identity.claims)
+ * @returns TenantInfo if all required fields are present, undefined otherwise
+ */
+export function tenantInfoFromClaims(claims: Record<string, any>): TenantInfo | undefined {
+  const tenantId = getClaim(claims, 'tenantId');
+  const tenantType = getClaim(claims, 'tenantType');
+  const userId = getClaim(claims, 'userId') || claims['sub'];
+  const countryCode = getClaim(claims, 'countryCode');
+  const personProfileId = getClaim(claims, 'personProfileId');
+  const orgProfileId = getClaim(claims, 'orgProfileId');
+  const hasCRM = getClaim(claims, 'hasCRM');
+
+  if (!tenantId || !tenantType || !userId || !countryCode) {
+    return undefined;
+  }
+
+  if (!isTenantType(tenantType)) {
+    return undefined;
+  }
+
+  return {
+    tenantId,
+    tenantType,
+    userId,
+    personProfileId,
+    orgProfileId,
+    countryCode,
+    plan: isPlan(getClaim(claims, 'plan')) ? getClaim(claims, 'plan') : undefined,
+    hasCRM,
+  };
+}
+
+/**
+ * Builds a TenantInfo from headers (Lambda-to-Lambda).
+ * Used by initTenantContext middleware for internal routes.
+ *
+ * @param headers - Headers object (may have original or lowercase keys)
+ * @returns TenantInfo if all required fields are present, undefined otherwise
+ */
+export function tenantInfoFromHeaders(
+  headers: Record<string, string | undefined>
+): TenantInfo | undefined {
+  const get = (key: string) => headers[key] || headers[key.toLowerCase()];
+
+  const tenantId = get(TENANT_HEADERS.TENANT_ID);
+  const tenantType = get(TENANT_HEADERS.TENANT_TYPE);
+  const userId = get(TENANT_HEADERS.USER_ID);
+  const countryCode = get(TENANT_HEADERS.COUNTRY_CODE);
+
+  if (!tenantId || !tenantType || !userId || !countryCode) {
+    return undefined;
+  }
+
+  if (!isTenantType(tenantType)) {
+    return undefined;
+  }
+
+  return {
+    tenantId,
+    tenantType: tenantType as 'ORG' | 'PERSON',
+    userId,
+    personProfileId: get(TENANT_HEADERS.PERSON_PROFILE_ID),
+    orgProfileId: get(TENANT_HEADERS.ORG_PROFILE_ID),
+    countryCode,
+  };
+}
+
+/**
+ * Converts TenantInfo to headers for Lambda-to-Lambda propagation.
+ * Used by ApiInvoker to propagate the context.
+ *
+ * @param tenant - TenantInfo to serialize
+ * @returns Headers object with X-Tenant-* headers
+ */
+export function tenantInfoToHeaders(tenant: TenantInfo): Record<string, string> {
+  const headers: Record<string, string> = {
+    [TENANT_HEADERS.TENANT_ID]: tenant.tenantId,
+    [TENANT_HEADERS.TENANT_TYPE]: tenant.tenantType,
+    [TENANT_HEADERS.USER_ID]: tenant.userId,
+    [TENANT_HEADERS.COUNTRY_CODE]: tenant.countryCode,
+  };
+
+  if (tenant.personProfileId) {
+    headers[TENANT_HEADERS.PERSON_PROFILE_ID] = tenant.personProfileId;
+  }
+  if (tenant.orgProfileId) {
+    headers[TENANT_HEADERS.ORG_PROFILE_ID] = tenant.orgProfileId;
+  }
+
+  return headers;
+}

package/src/tenant/index.ts

@@ -1,21 +1,21 @@
-export { TenantContext } from './TenantContext.js';
-
-export type {
-  TenantInfo,
-  TenantType,
-  Plan,
-  TenantFeatures,
-  TenantClaims,
-} from './types.js';
-
-export {
-  isTenantType,
-  isPlan,
-  TENANT_HEADERS,
-} from './types.js';
-
-export {
-  tenantInfoFromClaims,
-  tenantInfoFromHeaders,
-  tenantInfoToHeaders,
-} from './helpers.js';
+export { TenantContext } from './TenantContext.js';
+
+export type {
+  TenantInfo,
+  TenantType,
+  Plan,
+  TenantFeatures,
+  TenantClaims,
+} from './types.js';
+
+export {
+  isTenantType,
+  isPlan,
+  TENANT_HEADERS,
+} from './types.js';
+
+export {
+  tenantInfoFromClaims,
+  tenantInfoFromHeaders,
+  tenantInfoToHeaders,
+} from './helpers.js';