@mettlecast/domain-runtime 0.2.60 → 0.2.62

package/dist/primitives/action.d.ts

@@ -16,8 +16,7 @@ export type BackendAccess = 'private' | 'domain' | 'platform';
  */
 export type ApiAuthMode = 'required' | 'none' | 'service';
 /**
- * Tenancy posture for an API-exposed action. Mirrors `defineApi`'s contract
- * so the same registry row can describe an action or a standalone API.
+ * Tenancy posture for an API-exposed action.
  */
 export type ApiTenancyMode = 'required' | 'none' | 'system';
 /**
@@ -37,8 +36,8 @@ export interface InternalExposure {
     type: 'internal';
 }
 /**
- * Action exposed as an HTTP endpoint. The shape mirrors `defineApi` so the
- * downstream CDK/registry pipeline can treat both primitives uniformly.
+ * Action exposed as an HTTP endpoint. The downstream CDK/registry
+ * pipeline generates API Gateway routes from this shape.
  */
 export interface ApiExposure {
     type: 'api';

package/dist/primitives/action.js

@@ -62,12 +62,13 @@ const ActionExposureSchema = z.discriminatedUnion('type', [
     InternalExposureSchema,
     ApiExposureSchema,
 ]);
+const ZodSchemaRefinement = z.custom((v) => typeof v === 'object' && v !== null && typeof v.parse === 'function', { message: 'input/output must be Zod schema objects' });
 const ActionConfigSchema = z.object({
     id: z.string().min(1),
     backendAccess: z.nativeEnum(BackendAccessLiteral),
     exposure: ActionExposureSchema,
-    input: z.unknown(),
-    output: z.unknown(),
+    input: ZodSchemaRefinement,
+    output: ZodSchemaRefinement,
     idempotent: z.boolean().optional(),
     allowedCallers: z.array(z.string().min(1)).optional(),
     outboundAccess: z.enum(['internal', 'internet']).default('internal'),

package/dist/primitives/index.d.ts

@@ -1,5 +1,4 @@
 export * from './domain.js';
-export * from './api.js';
 export * from './webhook.js';
 export * from './define-outbound-webhook.js';
 export * from './events.js';

package/dist/primitives/index.js

@@ -1,5 +1,4 @@
 export * from './domain.js';
-export * from './api.js';
 export * from './webhook.js';
 export * from './define-outbound-webhook.js';
 export * from './events.js';

package/dist/runtime/exposed-action-api-handler.d.ts

@@ -8,14 +8,13 @@
  * (validation, auth/tenancy, idempotency, output validation, audit) to
  * `executeAction`.
  *
- * Mirrors the structure of `createApiLambdaHandler` (api-handler.ts) so the
- * two adapters stay visually parallel — but trades versioning/sunset/rate
- * limiting for action-specific concerns (exposure precondition, actor role
- * claims, output-as-action semantics).
+ * This is the canonical HTTP adapter now that public endpoints are declared
+ * as API-exposed actions. It keeps HTTP concerns local while action-specific
+ * validation, auth/tenancy, idempotency, and output checks stay in
+ * `executeAction`.
  *
- * DB lifecycle: the adapter owns `ctx.db.release()` in a `finally` block, just
- * like `createApiLambdaHandler`. `executeAction` does not auto-release by
- * default, so there is no double-release.
+ * DB lifecycle: the adapter owns `ctx.db.release()` in a `finally` block.
+ * `executeAction` does not auto-release by default, so there is no double-release.
  */
 import type { APIGatewayProxyEventV2WithJWTAuthorizer, APIGatewayProxyStructuredResultV2 } from 'aws-lambda';
 import type { ActionDefinition } from '../primitives/action.js';

package/dist/runtime/exposed-action-api-handler.js

@@ -8,14 +8,13 @@
  * (validation, auth/tenancy, idempotency, output validation, audit) to
  * `executeAction`.
  *
- * Mirrors the structure of `createApiLambdaHandler` (api-handler.ts) so the
- * two adapters stay visually parallel — but trades versioning/sunset/rate
- * limiting for action-specific concerns (exposure precondition, actor role
- * claims, output-as-action semantics).
+ * This is the canonical HTTP adapter now that public endpoints are declared
+ * as API-exposed actions. It keeps HTTP concerns local while action-specific
+ * validation, auth/tenancy, idempotency, and output checks stay in
+ * `executeAction`.
  *
- * DB lifecycle: the adapter owns `ctx.db.release()` in a `finally` block, just
- * like `createApiLambdaHandler`. `executeAction` does not auto-release by
- * default, so there is no double-release.
+ * DB lifecycle: the adapter owns `ctx.db.release()` in a `finally` block.
+ * `executeAction` does not auto-release by default, so there is no double-release.
  */
 import { hydrateCtx } from './hydrate.js';
 import { extractActorFromApiGatewayEvent, extractTenantFromApiGatewayEvent, } from './extractors.js';
@@ -192,8 +191,8 @@ export function createExposedActionApiHandler(action, options = {}) {
         // always reach it (it may be unset if hydration itself throws).
         let ctx;
         try {
-            // 2. Actor / tenant extraction — uses the same helpers as
-            //    createApiLambdaHandler so JWT/path behaviour stays uniform.
+            // 2. Actor / tenant extraction — use shared helpers so JWT/path
+            //    behaviour stays uniform across HTTP adapters.
             const actor = extractActorFromApiGatewayEvent(event);
             const tenant = extractTenantFromApiGatewayEvent(event);
             // 3. Input parsing.

package/dist/runtime/index.d.ts

@@ -47,8 +47,6 @@ export { eventVersionMatches } from './event-version-matcher.js';
 export { extractActorFromApiGatewayEvent, extractTenantFromApiGatewayEvent } from './extractors.js';
 export { parseQuery, encodeCursor, decodeCursor, DEFAULT_LIMIT, MAX_LIMIT } from './query-parser.js';
 export type { ParsedQuery } from './query-parser.js';
-export { createApiLambdaHandler } from './api-handler.js';
-export type { CreateApiHandlerOptions } from './api-handler.js';
 export { createExposedActionApiHandler } from './exposed-action-api-handler.js';
 export type { CreateExposedActionHandlerOptions } from './exposed-action-api-handler.js';
 export { createActionLambdaHandler } from './action-handler.js';

package/dist/runtime/index.js

@@ -53,7 +53,6 @@ export { extractActorFromApiGatewayEvent, extractTenantFromApiGatewayEvent } fro
 // Query parsing
 export { parseQuery, encodeCursor, decodeCursor, DEFAULT_LIMIT, MAX_LIMIT } from './query-parser.js';
 // Lambda handler wrappers
-export { createApiLambdaHandler } from './api-handler.js';
 export { createExposedActionApiHandler } from './exposed-action-api-handler.js';
 export { createActionLambdaHandler } from './action-handler.js';
 export { createSubscriberLambdaHandler } from './subscriber-handler.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mettlecast/domain-runtime",
-  "version": "0.2.60",
+  "version": "0.2.62",
   "type": "module",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/dist/primitives/api.d.ts

@@ -1,44 +0,0 @@
-import type { AuthConfig, RateLimitConfig, TenancyMode, DeploymentConfig, ObservabilityConfig, ApiVersion, OutboundAccess } from '../types/index.js';
-/** Configuration for an API primitive. */
-export interface ApiConfig {
-    /** Machine-readable API identifier (kebab-case). */
-    id: string;
-    /** HTTP route path relative to domain base, e.g. '/users/:id'. */
-    path: string;
-    /** HTTP method. Defaults to ANY. */
-    method?: string;
-    /** Tenancy requirement for this API. */
-    tenancy: TenancyMode;
-    /**
-     * Version map. Keys are version strings (e.g. 'v1', 'v2').
-     * At least one version is required.
-     */
-    versions: Record<string, ApiVersion<any, any>>;
-    /** Authentication configuration. Defaults to jwt. */
-    auth?: AuthConfig;
-    /** Rate limiting configuration. */
-    rateLimit?: RateLimitConfig;
-    /** Deployment overrides. */
-    deployment?: DeploymentConfig;
-    /** Whether this handler may use NAT-backed public internet egress. Defaults to internal. */
-    outboundAccess?: OutboundAccess;
-    /** Observability thresholds. */
-    observability?: ObservabilityConfig;
-    /** Example request/response payloads for documentation (no runtime impact). */
-    examples?: {
-        request?: Record<string, unknown>;
-        response?: Record<string, unknown>;
-    };
-}
-/** Return type of defineApi. */
-export interface ApiDefinition extends ApiConfig {
-    /** Discriminant. */
-    _kind: 'api';
-}
-/**
- * Register an API primitive with versioned handlers.
- * Validates that deprecated versions have a sunset date and that input/output
- * schemas are wrapped with `.default(...)` (the Zod v4 example-data pattern).
- * @throws {ZodError} if config is invalid
- */
-export declare function defineApi(config: ApiConfig): ApiDefinition;

package/dist/primitives/api.js

@@ -1,70 +0,0 @@
-import { z } from 'zod';
-// Native enum objects — Zod v4's recommended pattern over `z.enum([...])`.
-// Each `as const` object becomes the source of truth; `z.nativeEnum(...)`
-// derives the inferred string-literal union from the keys.
-const TenancyModeLiteral = { required: 'required', none: 'none', system: 'system' };
-const VersionStatusLiteral = { preview: 'preview', stable: 'stable', deprecated: 'deprecated', sunset: 'sunset' };
-const AuthTypeLiteral = { jwt: 'jwt', 'api-key': 'api-key', none: 'none' };
-const DeploymentTargetLiteral = { single: 'single', split: 'split' };
-const OutboundAccessLiteral = { internal: 'internal', internet: 'internet' };
-/**
- * Returns true when a Zod schema has been wrapped with `.default(...)` (Zod v4
- * pattern). The wrapped schema exposes a `_def.typeName` of `ZodDefault`.
- * `defineApi` requires every version's `input` and `output` to be wrapped this
- * way so that the runtime has a concrete example payload for documentation and
- * schema-publish tooling.
- */
-const hasDefault = (schema) => {
-    if (typeof schema !== 'object' || schema === null)
-        return false;
-    const def = schema._def;
-    if (!def)
-        return false;
-    if (def.typeName === 'ZodDefault' || def.type === 'default')
-        return true;
-    // Unwrap ZodOptional / ZodNullable — e.g. z.object({}).default({}).optional()
-    if (def.type === 'optional' || def.type === 'nullable') {
-        return hasDefault(schema._def.innerType);
-    }
-    return false;
-};
-const ApiConfigSchema = z.object({
-    id: z.string().min(1),
-    path: z.string().startsWith('/'),
-    method: z.string().optional(),
-    tenancy: z.nativeEnum(TenancyModeLiteral),
-    versions: z.record(z.string(), z.object({
-        status: z.nativeEnum(VersionStatusLiteral),
-        sunset: z.string().optional(),
-        input: z.unknown().refine(hasDefault, { message: 'input schema must have .default()' }),
-        output: z.unknown().refine(hasDefault, { message: 'output schema must have .default()' }),
-        handler: z.function(),
-    }).refine(v => v.status !== VersionStatusLiteral.deprecated || v.sunset !== undefined, {
-        message: 'sunset date is required when status is deprecated',
-    })),
-    auth: z.object({
-        type: z.nativeEnum(AuthTypeLiteral),
-        roles: z.array(z.string()).optional(),
-    }).optional(),
-    rateLimit: z.object({
-        perTenant: z.string().optional(),
-        perApiKey: z.string().optional(),
-        perIp: z.string().optional(),
-    }).optional(),
-    deployment: z.object({ target: z.nativeEnum(DeploymentTargetLiteral) }).passthrough().optional(),
-    outboundAccess: z.nativeEnum(OutboundAccessLiteral).default(OutboundAccessLiteral.internal),
-    observability: z.object({
-        sloP99Ms: z.number().positive().optional(),
-        alertOnErrorRate: z.number().min(0).max(1).optional(),
-    }).optional(),
-}).refine(c => Object.keys(c.versions).length > 0, { message: 'at least one version required' });
-/**
- * Register an API primitive with versioned handlers.
- * Validates that deprecated versions have a sunset date and that input/output
- * schemas are wrapped with `.default(...)` (the Zod v4 example-data pattern).
- * @throws {ZodError} if config is invalid
- */
-export function defineApi(config) {
-    ApiConfigSchema.parse(config);
-    return { ...config, outboundAccess: config.outboundAccess ?? 'internal', _kind: 'api' };
-}

package/dist/runtime/api-handler.d.ts

@@ -1,29 +0,0 @@
-import type { APIGatewayProxyEventV2WithJWTAuthorizer, APIGatewayProxyStructuredResultV2 } from 'aws-lambda';
-import type { ApiDefinition } from '../primitives/api.js';
-/**
- * Options for createApiLambdaHandler.
- */
-export interface CreateApiHandlerOptions {
-    /** Default version when no Accept-Version header. Defaults to highest stable. */
-    defaultVersion?: number;
-}
-/**
- * Wrap an ApiDefinition into an AWS Lambda HTTP API v2 handler with full
- * version negotiation, sunset enforcement, validation, ctx hydration, tenancy
- * guard, and error formatting.
- *
- * The handler performs the following steps in order:
- * 1. Version negotiation from Accept-Version or Accept headers
- * 2. Sunset check and response header decoration
- * 3. Tenancy validation (if required)
- * 4. Input validation via Zod schema
- * 5. Context hydration with actor, tenant, DB, secrets, etc.
- * 6. Handler invocation with typed input and ctx
- * 7. Output validation via Zod schema
- * 8. DB connection release
- *
- * @param api - ApiDefinition with versioned handlers.
- * @param options - Options for version negotiation and defaults.
- * @returns AWS Lambda HTTP API v2 handler function.
- */
-export declare function createApiLambdaHandler(api: ApiDefinition, options?: CreateApiHandlerOptions): (event: APIGatewayProxyEventV2WithJWTAuthorizer) => Promise<APIGatewayProxyStructuredResultV2>;

package/dist/runtime/api-handler.js

@@ -1,212 +0,0 @@
-import { negotiateVersion } from './version-negotiator.js';
-import { checkSunset, applySunsetHeaders } from './sunset-guard.js';
-import { hydrateCtx } from './hydrate.js';
-import { extractActorFromApiGatewayEvent, extractTenantFromApiGatewayEvent } from './extractors.js';
-import { formatError, extractTraceId, TibError } from './error-formatter.js';
-import { createMetrics } from './metrics.js';
-import { checkRateLimit } from './rate-limiter.js';
-/**
- * Wrap an ApiDefinition into an AWS Lambda HTTP API v2 handler with full
- * version negotiation, sunset enforcement, validation, ctx hydration, tenancy
- * guard, and error formatting.
- *
- * The handler performs the following steps in order:
- * 1. Version negotiation from Accept-Version or Accept headers
- * 2. Sunset check and response header decoration
- * 3. Tenancy validation (if required)
- * 4. Input validation via Zod schema
- * 5. Context hydration with actor, tenant, DB, secrets, etc.
- * 6. Handler invocation with typed input and ctx
- * 7. Output validation via Zod schema
- * 8. DB connection release
- *
- * @param api - ApiDefinition with versioned handlers.
- * @param options - Options for version negotiation and defaults.
- * @returns AWS Lambda HTTP API v2 handler function.
- */
-export function createApiLambdaHandler(api, options) {
-    return async (event) => {
-        const responseHeaders = { 'Content-Type': 'application/json' };
-        // G7: Extract W3C traceparent header and propagate as traceId
-        const traceparent = event.headers?.['traceparent'];
-        const traceId = traceparent ?? extractTraceId(event.headers ?? {});
-        // G6: Initialize EMF metrics (TODO: extract domainId from api definition or context)
-        const metrics = createMetrics({
-            domainId: api.id, // TODO: domainId should come from api definition or deployment context
-            endpointId: api.id,
-            primitiveClass: 'api',
-            // tenantId will be added after tenant is extracted
-        });
-        const requestStart = Date.now();
-        metrics.recordColdStart();
-        try {
-            // 1. Version negotiation
-            const versionKeys = Object.keys(api.versions).sort();
-            const stableVersions = versionKeys.filter(k => api.versions[k].status === 'stable');
-            const defaultVersionKey = options?.defaultVersion !== undefined
-                ? `v${options.defaultVersion}`
-                : (stableVersions[stableVersions.length - 1] ?? versionKeys[versionKeys.length - 1] ?? 'v1');
-            const defaultVersionNum = parseInt(defaultVersionKey.replace(/^v/, ''), 10);
-            const negotiation = negotiateVersion(event.headers ?? {}, isNaN(defaultVersionNum) ? 1 : defaultVersionNum);
-            const versionKey = `v${negotiation.requestedVersion}`;
-            const apiVersion = api.versions[versionKey];
-            if (!apiVersion) {
-                // G1: Use standard error envelope for unsupported version
-                return {
-                    statusCode: 406,
-                    headers: responseHeaders,
-                    body: JSON.stringify(formatError(new TibError('Unsupported version', 'UNSUPPORTED_VERSION'), traceId)),
-                };
-            }
-            // 2. Sunset check
-            const lifecycle = {
-                version: negotiation.requestedVersion,
-                status: apiVersion.status,
-                ...(apiVersion.sunset && { sunsetAt: apiVersion.sunset }),
-            };
-            const sunsetResult = checkSunset(lifecycle, new Date());
-            applySunsetHeaders(responseHeaders, sunsetResult);
-            if (sunsetResult.blocked) {
-                // G1: Use standard error envelope
-                return {
-                    statusCode: 410,
-                    headers: responseHeaders,
-                    body: JSON.stringify(formatError(new TibError('Version sunset', 'VERSION_SUNSET'), traceId)),
-                };
-            }
-            // 3. Tenancy guard (before validation, before hydrate — fail fast)
-            const actor = extractActorFromApiGatewayEvent(event);
-            const tenant = extractTenantFromApiGatewayEvent(event);
-            if (api.tenancy === 'required') {
-                if (tenant.id === 'unknown') {
-                    // G1: Use standard error envelope for auth errors
-                    return {
-                        statusCode: 401,
-                        headers: responseHeaders,
-                        body: JSON.stringify(formatError(new TibError('Tenant context required', 'TENANT_REQUIRED'), traceId)),
-                    };
-                }
-                const pathTenantId = event.pathParameters?.tenantId;
-                if (pathTenantId && pathTenantId !== tenant.id) {
-                    // G1: Use standard error envelope for auth errors
-                    return {
-                        statusCode: 403,
-                        headers: responseHeaders,
-                        body: JSON.stringify(formatError(new TibError('Tenant mismatch', 'TENANT_MISMATCH'), traceId)),
-                    };
-                }
-            }
-            // Rate limiting — per-tenant token bucket (in-memory, resets on cold start)
-            if (api.rateLimit?.perTenant) {
-                const tenantId = extractTenantFromApiGatewayEvent(event)?.id ?? 'anonymous';
-                const rateLimitKey = `${api.id}:tenant:${tenantId}`;
-                const allowed = checkRateLimit(rateLimitKey, api.rateLimit.perTenant);
-                if (!allowed) {
-                    return {
-                        statusCode: 429,
-                        headers: { ...responseHeaders, 'Retry-After': '60' },
-                        body: JSON.stringify(formatError(new TibError('Rate limit exceeded', 'RATE_LIMIT_EXCEEDED'), traceId)),
-                    };
-                }
-            }
-            if (api.rateLimit?.perIp) {
-                const sourceIp = event.requestContext?.http?.sourceIp ?? 'unknown';
-                const rateLimitKey = `${api.id}:ip:${sourceIp}`;
-                const allowed = checkRateLimit(rateLimitKey, api.rateLimit.perIp);
-                if (!allowed) {
-                    return {
-                        statusCode: 429,
-                        headers: { ...responseHeaders, 'Retry-After': '60' },
-                        body: JSON.stringify(formatError(new TibError('Rate limit exceeded', 'RATE_LIMIT_EXCEEDED'), traceId)),
-                    };
-                }
-            }
-            // 4. Validate input
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            let parsedInput;
-            try {
-                const rawBody = event.body ? (event.isBase64Encoded ? Buffer.from(event.body, 'base64').toString('utf8') : event.body) : undefined;
-                const inputJson = rawBody ? JSON.parse(rawBody) : undefined;
-                parsedInput = apiVersion.input.parse(inputJson);
-            }
-            catch (err) {
-                // G1: Use standard error envelope for validation errors
-                return {
-                    statusCode: 400,
-                    headers: responseHeaders,
-                    body: JSON.stringify(formatError(err, traceId)),
-                };
-            }
-            // G5: Auto-trigger idempotency check for POST/PUT/PATCH
-            const idempotencyKey = event.headers?.['idempotency-key'] ?? event.headers?.['Idempotency-Key'];
-            const httpMethod = event.requestContext?.http?.method ?? '';
-            // 5. Hydrate context
-            const { tenantId: _tenantId, ...remainingPathParams } = event.pathParameters ?? {};
-            const ctx = await hydrateCtx(event, {
-                actor,
-                tenant,
-                databaseUrl: process.env['DATABASE_URL'],
-                eventBusName: process.env['EVENT_BUS_NAME'],
-                traceId,
-                pathParams: remainingPathParams,
-            });
-            // G5: After hydration, check idempotency cache for POST/PUT/PATCH
-            if (idempotencyKey && ['POST', 'PUT', 'PATCH'].includes(httpMethod)) {
-                const cached = await ctx.idempotency.isProcessed();
-                if (cached) {
-                    // Return cached response — for now return 200 with a replay indicator
-                    return {
-                        statusCode: 200,
-                        headers: { ...responseHeaders, 'Idempotency-Replayed': 'true' },
-                        body: JSON.stringify({ replayed: true, idempotencyKey }),
-                    };
-                }
-            }
-            try {
-                // 6. Call handler
-                const result = await apiVersion.handler(parsedInput, ctx);
-                // 7. Validate output
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                let parsedOutput;
-                try {
-                    parsedOutput = apiVersion.output.parse(result);
-                }
-                catch (err) {
-                    ctx.logger.error('Output validation failed');
-                    // G1: Use standard error envelope for output validation errors
-                    return {
-                        statusCode: 500,
-                        headers: responseHeaders,
-                        body: JSON.stringify(formatError(err, traceId, ctx.logger)),
-                    };
-                }
-                // G5: Mark as processed after successful handler completion
-                if (idempotencyKey && ['POST', 'PUT', 'PATCH'].includes(httpMethod)) {
-                    await ctx.idempotency.markProcessed();
-                }
-                return { statusCode: 200, headers: responseHeaders, body: JSON.stringify(parsedOutput) };
-            }
-            finally {
-                // 8. Always release DB
-                try {
-                    await ctx.db.release();
-                }
-                catch { /* swallow */ }
-                // G6: Record latency and flush metrics
-                metrics.recordLatency(Date.now() - requestStart);
-                metrics.flush();
-            }
-        }
-        catch (err) {
-            // Last-resort error handler
-            // G1: Use standard error envelope for unhandled errors
-            // eslint-disable-next-line no-console
-            console.error('Unhandled handler error', err);
-            return {
-                statusCode: 500,
-                headers: responseHeaders,
-                body: JSON.stringify(formatError(err, traceId)),
-            };
-        }
-    };
-}