@karmaniverous/smoz 0.2.3 → 0.2.5

package/dist/index.d.ts

@@ -1,151 +1,117 @@
+import { ZodOpenApiOperationObject, ZodOpenApiPathItemObject, ZodOpenApiPathsObject } from 'zod-openapi';
+import * as aws_lambda from 'aws-lambda';
+import { APIGatewayProxyEvent, Context, APIGatewayProxyEventV2, ALBEvent, SQSEvent, SNSEvent, S3Event, DynamoDBStreamEvent, KinesisStreamEvent, EventBridgeEvent, CloudWatchLogsEvent, SESEvent, CloudFrontRequestEvent, FirehoseTransformationEvent, CognitoUserPoolTriggerEvent } from 'aws-lambda';
 import { AWS } from '@serverless/typescript';
-import { z, ZodObject, ZodRawShape } from 'zod';
-import { ZodOpenApiPathsObject, ZodOpenApiPathItemObject } from 'zod-openapi';
-import { buildStageArtifacts } from '@/src/core/buildStageArtifacts';
-import { EnvSchemaNode as EnvSchemaNode$1 } from '@/src/core/defineAppConfig';
-import { serverlessConfigSchema, AppServerlessConfig } from '@/src/core/serverlessConfig';
-import { ZodObj } from '@/src/core/types';
-import { AppHttpConfig as AppHttpConfig$1 } from '@/src/http/middleware/httpStackCustomization';
-import { MethodKey as MethodKey$1, FunctionConfig } from '@/src/types/FunctionConfig';
-import { HttpContext as HttpContext$1 } from '@/src/types/HttpContext';
-import { APIGatewayProxyEvent, APIGatewayProxyEventV2, ALBEvent, SQSEvent, SNSEvent, S3Event, DynamoDBStreamEvent, KinesisStreamEvent, EventBridgeEvent, CloudWatchLogsEvent, SESEvent, CloudFrontRequestEvent, FirehoseTransformationEvent, CognitoUserPoolTriggerEvent, Context } from 'aws-lambda';
-import { stagesFactory } from '@/src/serverless/stagesFactory';
-import { SecurityContextHttpEventMap as SecurityContextHttpEventMap$1 } from '@/src/types/SecurityContextHttpEventMap';
-import { BaseEventTypeMap } from '@/src/core/baseEventTypeMapSchema';
-import { EnvAttached } from '@/src/core/defineFunctionConfig';
-import { Handler as Handler$1 } from '@/src/types/Handler';
+import { ZodObject, ZodRawShape, z } from 'zod';
 import { MiddlewareObj } from '@middy/core';
 import httpContentNegotiation from '@middy/http-content-negotiation';
 import httpCors from '@middy/http-cors';
 import httpErrorHandler from '@middy/http-error-handler';
 import httpHeaderNormalizer from '@middy/http-header-normalizer';
 import httpJsonBodyParser from '@middy/http-json-body-parser';
-import { HttpTransform, PhasedArrays } from '@/src/http/middleware/transformUtils';
-import { ConsoleLogger as ConsoleLogger$1 } from '@/src/types/Loggable';
-import { DeepOverride } from '@/src/types/DeepOverride';
-import { PropFromUnion } from '@/src/types/PropFromUnion';
 
-interface AppInit<GlobalParamsSchema extends ZodObj, StageParamsSchema extends ZodObj, EventTypeMapSchema extends ZodObj> {
-    appRootAbs: string;
-    globalParamsSchema: GlobalParamsSchema;
-    stageParamsSchema: StageParamsSchema;
-    eventTypeMapSchema?: EventTypeMapSchema;
-    /** Accept raw serverless config; App will parse it internally. */
-    serverless: z.input<typeof serverlessConfigSchema>;
-    global: {
-        params: z.infer<GlobalParamsSchema>;
-        envKeys: readonly (keyof z.infer<GlobalParamsSchema>)[];
-    };
-    stage: {
-        /** Accept raw stage param objects; App will parse with (global.partial + stage) */
-        params: Record<string, Record<string, unknown>>;
-        envKeys: readonly (keyof z.infer<StageParamsSchema>)[];
-    };
-    /**
-     * HTTP tokens to treat as HTTP at runtime (widenable).
-     * Defaults to ['rest', 'http'].
-     */
-    httpEventTypeTokens?: readonly (keyof z.infer<EventTypeMapSchema>)[];
-    /**
-     * Optional app-level HTTP middleware customization (defaults & profiles).
-     */
-    http?: AppHttpConfig$1;
-    /** Optional defaults applied to every function (merged per registration). */
-    functionDefaults?: {
-        fnEnvKeys?: readonly string[];
+/**
+ * Makes specified properties of `T` required.
+ *
+ * @typeParam T - The type to make properties required.
+ * @typeParam U - The properties to make required.
+ *
+ * @example
+ * interface A { x?: number; y?: string; z: boolean }
+ * // => { x: number; y?: string; z: boolean }
+ * type R = MakeRequired<A, 'x'>;
+ */
+type MakeRequired<T extends object, U extends keyof T> = {
+    [P in keyof T as P extends U ? never : P]: T[P];
+} & Required<Pick<T, U>>;
+
+/**
+ * A base OpenAPI operation object, with the `summary` field required.
+ *
+ * @see https://spec.openapis.org/oas/v3.1.0#operation-object * @remarks
+ * Use this when registering per‑function OpenAPI operations via `fn.openapi(baseOperation)`.
+ * The SMOZ registry fills in `operationId`, augments `summary` with the context,
+ * and merges tags for each configured context.
+ */
+type BaseOperation = MakeRequired<Omit<ZodOpenApiOperationObject, 'operationId'>, 'summary'>;
+
+type Dict<T> = Record<string, T>;
+type StagesFactoryInput<GlobalParams extends Record<string, unknown>, StageParams extends Record<string, unknown>> = {
+    globalParamsSchema: ZodObject<ZodRawShape>;
+    stageParamsSchema: ZodObject<ZodRawShape>;
+    globalParams: GlobalParams;
+    globalEnvKeys: readonly (keyof GlobalParams)[];
+    stageEnvKeys: readonly (keyof StageParams)[];
+    stages: Dict<StageParams>;
+};
+type StagesFactoryOutput<GlobalParams extends Record<string, unknown>, StageParams extends Record<string, unknown>> = {
+    /** Serverless 'params' object: { default: { params: GlobalParams }, <stage>: { params: StageParams } } */
+    stages: {
+        default: {
+            params: GlobalParams;
+        };
+    } & {
+        [K in keyof Dict<StageParams>]: {
+            params: StageParams;
+        };
     };
-}
+    /** Provider-level environment mapping for globally exposed keys */
+    environment: Record<string, string>;
+    /** Helper to build per-function environment mapping for additional keys */
+    buildFnEnv: (fnEnvKeys?: readonly (keyof (GlobalParams & StageParams))[]) => Record<string, string>;
+};
 /**
- * Application class. *
- * @typeParam GlobalParamsSchema - Zod object schema for global parameters
- * @typeParam StageParamsSchema  - Zod object schema for per‑stage parameters
- * @typeParam EventTypeMapSchema - Zod object schema mapping event tokens to runtime types
- */ declare class App<GlobalParamsSchema extends ZodObj, StageParamsSchema extends ZodObj, EventTypeMapSchema extends ZodObj> {
-    /** Helper alias for stage artifacts type */
-    private static readonly _stageArtifactsType;
-    readonly appRootAbs: string;
-    readonly globalParamsSchema: GlobalParamsSchema;
-    readonly stageParamsSchema: StageParamsSchema;
-    readonly eventTypeMapSchema: EventTypeMapSchema;
-    readonly serverless: AppServerlessConfig;
-    readonly global: EnvSchemaNode$1<GlobalParamsSchema>;
-    readonly stage: EnvSchemaNode$1<StageParamsSchema>;
-    readonly stages: ReturnType<typeof buildStageArtifacts>['stages'];
-    readonly environment: ReturnType<typeof buildStageArtifacts>['environment'];
-    readonly buildFnEnv: ReturnType<typeof buildStageArtifacts>['buildFnEnv'];
-    readonly http: AppHttpConfig$1;
-    readonly httpEventTypeTokens: readonly string[];
-    private readonly registry;
-    private constructor(); /**
-     * Ergonomic constructor for schema‑first inference.
-     *
-     * @param init - initialization object (schemas, serverless defaults, params/envKeys)
-     * @returns a new App instance
-     */
-    static create<GlobalParamsSchema extends ZodObj, StageParamsSchema extends ZodObj, EventTypeMapSchema extends ZodObj>(init: AppInit<GlobalParamsSchema, StageParamsSchema, EventTypeMapSchema>): App<GlobalParamsSchema, StageParamsSchema, EventTypeMapSchema>;
-    /**
-     * Register a function (HTTP or non‑HTTP).
-     *
-     * @typeParam EventType      - A key from your eventTypeMapSchema (e.g., 'rest' | 'http' | 'sqs' | 'step')
-     * @typeParam EventSchema    - Optional Zod schema validated BEFORE the handler (refines event shape)
-     * @typeParam ResponseSchema - Optional Zod schema validated AFTER the handler (refines response shape)
-     * @param options - per‑function configuration (method/basePath/httpContexts for HTTP; serverless extras for non‑HTTP)
-     * @returns a per‑function API: { handler(business), openapi(baseOperation), serverless(extras) }
-     */
-    defineFunction<EventType extends Extract<keyof z.infer<EventTypeMapSchema>, string>, EventSchema extends z.ZodType | undefined, ResponseSchema extends z.ZodType | undefined>(options: {
-        functionName?: string;
-        eventType: EventType;
-        method?: MethodKey$1;
-        basePath?: string;
-        httpContexts?: readonly HttpContext$1[];
-        contentType?: string;
-        eventSchema?: EventSchema;
-        responseSchema?: ResponseSchema;
-        fnEnvKeys?: readonly (keyof (z.infer<GlobalParamsSchema> & z.infer<StageParamsSchema>))[];
-        callerModuleUrl: string;
-        endpointsRootAbs: string;
-    }): any;
-    /**
-     * Aggregate Serverless function definitions across the registry.
-     *
-     * @returns An AWS['functions'] object suitable for serverless.ts
-     */
-    buildAllServerlessFunctions(): AWS['functions'];
-    /**
-     * Aggregate OpenAPI path items across the registry.
-     *
-     * @returns ZodOpenApiPathsObject to be embedded in a full OpenAPI document
-     */
-    buildAllOpenApiPaths(): ZodOpenApiPathsObject;
-}
+ * Create all stage artifacts from provided configs.  This is generic and can
+ * be used by both production and tests.
+ *
+ * @typeParam GlobalParams - global params record
+ * @typeParam StageParams  - stage params record
+ * @param input - schemas, concrete params, env exposure, and per‑stage values
+ * @returns stage params object, provider environment, and per‑function env builder
+ *
+ * @throws Error if a stage fails validation or a required global key is missing
+ */
+declare const stagesFactory: <GlobalParams extends Record<string, unknown>, StageParams extends Record<string, unknown>>(input: StagesFactoryInput<GlobalParams, StageParams>) => StagesFactoryOutput<GlobalParams, StageParams>;
 
 /**
- * baseEventTypeMapSchema
- * - Schema-first companion to BaseEventTypeMap.
- * - Ensures z.infer<typeof baseEventTypeMapSchema> === BaseEventTypeMap.
+ * Compose stage artifacts (effective schema + parsed stages + env helpers).
+ * Extracted from App.ts to keep the class focused on orchestration.
+ */
+declare function buildStageArtifacts<GlobalParamsSchema extends ZodObject<ZodRawShape>, StageParamsSchema extends ZodObject<ZodRawShape>>(globalParamsSchema: GlobalParamsSchema, stageParamsSchema: StageParamsSchema, global: {
+    params: z.infer<GlobalParamsSchema>;
+    envKeys: readonly (keyof z.infer<GlobalParamsSchema>)[];
+}, stage: {
+    params: Record<string, Record<string, unknown>>;
+    envKeys: readonly (keyof z.infer<StageParamsSchema>)[];
+}): StagesFactoryOutput<z.core.output<GlobalParamsSchema>, z.core.output<StageParamsSchema>>;
+
+/** Security context classification used throughout the handlers. */
+/**
+ * HTTP security context tokens.
+ */
+type HttpContext = 'my' | 'private' | 'public';
+
+/**
+ * Extract the property type `K` from a union of object types `U`.
  *
- * @remarks
- * Consumers typically extend this schema when creating an App to add
- * project‑local event tokens (e.g., 'step').
- * Only tokens listed in the app’s `httpEventTypeTokens` are treated as HTTP at runtime.
+ * @typeParam U - union of object types
+ * @typeParam K - property key to extract
+ *
+ * @example
+ * type U = { a: number } | { a: string; b: boolean };
+ * // => number | string
+ * type A = PropFromUnion<U, 'a'>;
  */
+type PropFromUnion<U, K extends PropertyKey> = Extract<U, Record<K, unknown>>[K];
 
-declare const baseEventTypeMapSchema: z.ZodObject<{
-    rest: z.ZodCustom<APIGatewayProxyEvent, APIGatewayProxyEvent>;
-    http: z.ZodCustom<APIGatewayProxyEventV2, APIGatewayProxyEventV2>;
-    alb: z.ZodCustom<ALBEvent, ALBEvent>;
-    sqs: z.ZodCustom<SQSEvent, SQSEvent>;
-    sns: z.ZodCustom<SNSEvent, SNSEvent>;
-    s3: z.ZodCustom<S3Event, S3Event>;
-    dynamodb: z.ZodCustom<DynamoDBStreamEvent, DynamoDBStreamEvent>;
-    kinesis: z.ZodCustom<KinesisStreamEvent, KinesisStreamEvent>;
-    eventbridge: z.ZodCustom<EventBridgeEvent<string, unknown>, EventBridgeEvent<string, unknown>>;
-    'cloudwatch-logs': z.ZodCustom<CloudWatchLogsEvent, CloudWatchLogsEvent>;
-    ses: z.ZodCustom<SESEvent, SESEvent>;
-    cloudfront: z.ZodCustom<CloudFrontRequestEvent, CloudFrontRequestEvent>;
-    firehose: z.ZodCustom<FirehoseTransformationEvent, FirehoseTransformationEvent>;
-    'cognito-userpool': z.ZodCustom<CognitoUserPoolTriggerEvent, CognitoUserPoolTriggerEvent>;
-}, z.core.$strip>;
+/**
+ * Opaque Serverless event fragments keyed by security context.
+ *
+ * @remarks
+ * Shape is intentionally platform‑specific; used by the App to decorate
+ * generated HTTP events based on 'my' | 'private' | 'public' contexts.
+ */
+type SecurityContextHttpEventMap = Record<HttpContext, Partial<PropFromUnion<PropFromUnion<PropFromUnion<AWS['functions'], string>['events'], number>, 'http'>>>;
 
 /** Base: envKeys tied to a Zod schema’s inferred keys. */
 /**
@@ -204,7 +170,7 @@ interface DefineAppConfigInput<GlobalParamsSchema extends ZodObject<ZodRawShape>
     serverless: {
         defaultHandlerFileName: string;
         defaultHandlerFileExport: string;
-        httpContextEventMap: SecurityContextHttpEventMap$1;
+        httpContextEventMap: SecurityContextHttpEventMap;
     };
     global: GlobalParamsNode<GlobalParamsSchema>;
     stage: StageParamsNode<StageParamsSchema>;
@@ -234,44 +200,75 @@ interface DefineAppConfigOutput<GlobalParamsSchema extends ZodObject<ZodRawShape
  */
 declare function defineAppConfig<GlobalParamsSchema extends ZodObject<ZodRawShape>, StageParamsSchema extends ZodObject<ZodRawShape>>(globalParamsSchema: GlobalParamsSchema, stageParamsSchema: StageParamsSchema, input: DefineAppConfigInput<GlobalParamsSchema, StageParamsSchema>): DefineAppConfigOutput<GlobalParamsSchema, StageParamsSchema>;
 
-/** Classify the security context from either API Gateway event version. */
 /**
- * Detect security context from API Gateway v1/v2 events.
+ * Zod schema for implementation-wide Serverless config.
  *
- * @param evt - unknown event
- * @returns 'my' when authorized (Cognito/JWT/IAM), 'private' when API key present, else 'public'
+ * Extracted to keep App.ts slim and focused on orchestration.
  */
-declare const detectSecurityContext: (evt: unknown) => HttpContext$1;
+declare const serverlessConfigSchema: z.ZodObject<{
+    httpContextEventMap: z.ZodCustom<SecurityContextHttpEventMap, SecurityContextHttpEventMap>;
+    defaultHandlerFileName: z.ZodString;
+    defaultHandlerFileExport: z.ZodString;
+}, z.core.$strip>;
+type AppServerlessConfig = z.infer<typeof serverlessConfigSchema>;
 
 /**
- * Wrap a business handler with SMOZ runtime. *
- * - HTTP event tokens receive the full Middy pipeline (validation, shaping, CORS, etc.)
- * - Non‑HTTP tokens bypass Middy and call the business function directly.
+ * Convenience alias for App generics.
  *
- * @typeParam GlobalParamsSchema - global params schema type
- * @typeParam StageParamsSchema  - stage params schema type
- * @typeParam EventTypeMap       - event token → runtime type map
- * @typeParam EventType          - a key of EventTypeMap
- * @typeParam EventSchema        - optional Zod schema for event (validated before handler)
- * @typeParam ResponseSchema     - optional Zod schema for response (validated after handler)
- * @param functionConfig - per‑function configuration (branded with env nodes)
- * @param business - the business handler implementation
- * @param opts - optional runtime overrides (e.g., widen HTTP tokens)
- * @returns a Lambda‑compatible handler function
+ * @remarks Use this to express “any Zod object schema” in generic parameters.
  */
-declare function wrapHandler<GlobalParamsSchema extends ZodObject<ZodRawShape>, StageParamsSchema extends ZodObject<ZodRawShape>, EventTypeMap extends BaseEventTypeMap, EventType extends keyof EventTypeMap, EventSchema extends z.ZodType | undefined, ResponseSchema extends z.ZodType | undefined>(functionConfig: FunctionConfig<EventSchema, ResponseSchema, z.infer<GlobalParamsSchema>, z.infer<StageParamsSchema>, EventTypeMap, EventType> & EnvAttached<GlobalParamsSchema, StageParamsSchema>, business: Handler$1<EventSchema, ResponseSchema, EventTypeMap[EventType]>, opts?: {
-    httpEventTypeTokens?: readonly string[];
-    httpConfig?: AppHttpConfig$1;
-}): (event: unknown, context: Context) => Promise<any>;
+type ZodObj = ZodObject<ZodRawShape>;
+
+type ConsoleLogger = Pick<Console, 'debug' | 'error' | 'info' | 'log'>;
 
 /**
- * HTTP customization types and aliases.
+ * Transform helpers for HTTP middleware stacks.
+ *
+ * - Steps are identified by a non-enumerable __id property on MiddlewareObj.
+ * - Utilities operate on arrays immutably and return new arrays.
+ * * Requirements addressed:
+ * - insertBefore, insertAfter, replaceStep, removeStep, findIndex, getId
  */
 
 type ApiMiddleware$1 = MiddlewareObj<APIGatewayProxyEvent, Context>;
+type StepId = 'head' | 'header-normalizer' | 'event-normalizer' | 'content-negotiation' | 'json-body-parser' | 'zod-before' | 'head-finalize' | 'zod-after' | 'error-expose' | 'error-handler' | 'cors' | 'preferred-media' | 'shape' | 'serializer';
+/** Attach a non-enumerable __id to a middleware step. */
+declare const tagStep: (mw: ApiMiddleware$1, id: StepId) => ApiMiddleware$1;
+/** Retrieve a step's id, if present. */
+declare const getId: (mw: ApiMiddleware$1) => StepId | undefined;
+/** Find index of a step by id. */
+declare const findIndex: (list: ApiMiddleware$1[], id: StepId) => number;
+/** Insert a step before the step with given id. */
+declare const insertBefore: (list: ApiMiddleware$1[], id: StepId, mw: ApiMiddleware$1) => ApiMiddleware$1[];
+/** Insert a step after the step with given id. */
+declare const insertAfter: (list: ApiMiddleware$1[], id: StepId, mw: ApiMiddleware$1) => ApiMiddleware$1[];
+/** Replace a step with given id. */
+declare const replaceStep: (list: ApiMiddleware$1[], id: StepId, mw: ApiMiddleware$1) => ApiMiddleware$1[];
+/** Remove a step with given id. */
+declare const removeStep: (list: ApiMiddleware$1[], id: StepId) => ApiMiddleware$1[];
+type PhasedArrays = {
+    before?: ApiMiddleware$1[];
+    after?: ApiMiddleware$1[];
+    onError?: ApiMiddleware$1[];
+};
+type HttpTransform = (stack: {
+    before: ApiMiddleware$1[];
+    after: ApiMiddleware$1[];
+    onError: ApiMiddleware$1[];
+}) => Partial<{
+    before: ApiMiddleware$1[];
+    after: ApiMiddleware$1[];
+    onError: ApiMiddleware$1[];
+}>;
+
+/**
+ * HTTP customization types and aliases.
+ */
+
+type ApiMiddleware = MiddlewareObj<APIGatewayProxyEvent, Context>;
 type HttpStackOptions = {
     contentType?: string;
-    logger?: ConsoleLogger$1;
+    logger?: ConsoleLogger;
     contentNegotiation?: Parameters<typeof httpContentNegotiation>[0];
     cors?: Parameters<typeof httpCors>[0];
     errorHandler?: Parameters<typeof httpErrorHandler>[0];
@@ -285,9 +282,9 @@ type HttpStackOptions = {
     headerNormalizer?: Parameters<typeof httpHeaderNormalizer>[0];
 };
 type Extend = {
-    before?: ApiMiddleware$1[];
-    after?: ApiMiddleware$1[];
-    onError?: ApiMiddleware$1[];
+    before?: ApiMiddleware[];
+    after?: ApiMiddleware[];
+    onError?: ApiMiddleware[];
 };
 type HttpProfile = HttpStackOptions & {
     extend?: Extend;
@@ -310,10 +307,10 @@ type FunctionHttpConfig = {
     };
 };
 
-type M = ApiMiddleware$1;
+type M = ApiMiddleware;
 declare const buildDefaultPhases: (args: {
     contentType: string;
-    logger: ConsoleLogger$1;
+    logger: ConsoleLogger;
     opts?: HttpStackOptions;
     eventSchema?: z.ZodType | undefined;
     responseSchema?: z.ZodType | undefined;
@@ -331,33 +328,242 @@ declare const buildSafeDefaults: (args: BuildSafeDefaultsArgs) => {
 };
 
 /**
- * Transform helpers for HTTP middleware stacks.
+ * baseEventTypeMapSchema
+ * - Schema-first companion to BaseEventTypeMap.
+ * - Ensures z.infer<typeof baseEventTypeMapSchema> === BaseEventTypeMap.
  *
- * - Steps are identified by a non-enumerable __id property on MiddlewareObj.
- * - Utilities operate on arrays immutably and return new arrays.
- * * Requirements addressed:
- * - insertBefore, insertAfter, replaceStep, removeStep, findIndex, getId
+ * @remarks
+ * Consumers typically extend this schema when creating an App to add
+ * project‑local event tokens (e.g., 'step').
+ * Only tokens listed in the app’s `httpEventTypeTokens` are treated as HTTP at runtime.
  */
 
-type ApiMiddleware = MiddlewareObj<APIGatewayProxyEvent, Context>;
-type StepId = 'head' | 'header-normalizer' | 'event-normalizer' | 'content-negotiation' | 'json-body-parser' | 'zod-before' | 'head-finalize' | 'zod-after' | 'error-expose' | 'error-handler' | 'cors' | 'preferred-media' | 'shape' | 'serializer';
-/** Attach a non-enumerable __id to a middleware step. */
-declare const tagStep: (mw: ApiMiddleware, id: StepId) => ApiMiddleware;
-/** Retrieve a step's id, if present. */
-declare const getId: (mw: ApiMiddleware) => StepId | undefined;
-/** Find index of a step by id. */
-declare const findIndex: (list: ApiMiddleware[], id: StepId) => number;
-/** Insert a step before the step with given id. */
-declare const insertBefore: (list: ApiMiddleware[], id: StepId, mw: ApiMiddleware) => ApiMiddleware[];
-/** Insert a step after the step with given id. */
-declare const insertAfter: (list: ApiMiddleware[], id: StepId, mw: ApiMiddleware) => ApiMiddleware[];
-/** Replace a step with given id. */
-declare const replaceStep: (list: ApiMiddleware[], id: StepId, mw: ApiMiddleware) => ApiMiddleware[];
-/** Remove a step with given id. */
-declare const removeStep: (list: ApiMiddleware[], id: StepId) => ApiMiddleware[];
+declare const baseEventTypeMapSchema: z.ZodObject<{
+    rest: z.ZodCustom<APIGatewayProxyEvent, APIGatewayProxyEvent>;
+    http: z.ZodCustom<APIGatewayProxyEventV2, APIGatewayProxyEventV2>;
+    alb: z.ZodCustom<ALBEvent, ALBEvent>;
+    sqs: z.ZodCustom<SQSEvent, SQSEvent>;
+    sns: z.ZodCustom<SNSEvent, SNSEvent>;
+    s3: z.ZodCustom<S3Event, S3Event>;
+    dynamodb: z.ZodCustom<DynamoDBStreamEvent, DynamoDBStreamEvent>;
+    kinesis: z.ZodCustom<KinesisStreamEvent, KinesisStreamEvent>;
+    eventbridge: z.ZodCustom<EventBridgeEvent<string, unknown>, EventBridgeEvent<string, unknown>>;
+    'cloudwatch-logs': z.ZodCustom<CloudWatchLogsEvent, CloudWatchLogsEvent>;
+    ses: z.ZodCustom<SESEvent, SESEvent>;
+    cloudfront: z.ZodCustom<CloudFrontRequestEvent, CloudFrontRequestEvent>;
+    firehose: z.ZodCustom<FirehoseTransformationEvent, FirehoseTransformationEvent>;
+    'cognito-userpool': z.ZodCustom<CognitoUserPoolTriggerEvent, CognitoUserPoolTriggerEvent>;
+}, z.core.$strip>;
+/** Canonical base event map type (schema‑first). Extend the schema in your App. */
+type BaseEventTypeMap = z.infer<typeof baseEventTypeMapSchema>;
 
 /** HTTP methods supported from zod-openapi's PathItem shape (excluding helper 'id'). */
 type MethodKey = keyof Omit<ZodOpenApiPathItemObject, 'id'>;
+/**
+ * FunctionConfig
+ * - Per-function schemas, env requirements, routing metadata.
+ * - EventTypeMap binds event tokens (e.g., 'rest'|'http'|'sqs') to runtime shapes.
+ * - HTTP-only options are permitted only when EventType is an HTTP token.
+ *
+ * @typeParam EventSchema   - optional Zod schema for event (validated pre‑handler)
+ * @typeParam ResponseSchema- optional Zod schema for response (validated post‑handler)
+ * @typeParam GlobalParams  - app global params record
+ * @typeParam StageParams   - app stage params record
+ * @typeParam EventTypeMap  - event token → runtime type map
+ * @typeParam EventType     - selected event token
+ *
+ * @remarks
+ * The SMOZ wrapper reads env keys from this config’s brand and builds a typed `options.env`,
+ * then applies HTTP middleware iff the token is in the app’s HTTP tokens set.
+ */
+type FunctionConfig<EventSchema extends z.ZodType | undefined, ResponseSchema extends z.ZodType | undefined, GlobalParams extends Record<string, unknown>, StageParams extends Record<string, unknown>, EventTypeMap extends BaseEventTypeMap, EventType extends keyof EventTypeMap> = {
+    /** Unique function name; used across serverless/OpenAPI outputs. */
+    functionName: string;
+    /** Compile-time token selecting the runtime event type (e.g., 'rest' | 'http' | 'sqs'). */
+    eventType: EventType;
+    /** Optional; defaults to [] wherever consumed. */
+    fnEnvKeys?: readonly (keyof GlobalParams | keyof StageParams)[];
+    /** Optional Zod schemas applied uniformly across all handlers. */
+    eventSchema?: EventSchema;
+    responseSchema?: ResponseSchema;
+    /** Optional extra serverless events (e.g., SQS triggers). */
+    events?: PropFromUnion<AWS['functions'], string>['events'];
+    /** Optional logger; wrapper will default to `console`. */
+    logger?: ConsoleLogger;
+} & (EventType extends keyof Pick<BaseEventTypeMap, 'rest' | 'http'> ? {
+    /** HTTP-only options (permitted for base HTTP tokens). */
+    httpContexts?: readonly HttpContext[];
+    method?: MethodKey;
+    basePath?: string;
+    contentType?: string;
+} : {
+    /** Non-HTTP: deny HTTP-only options via type system. */
+    httpContexts?: never;
+    method?: never;
+    basePath?: never;
+    contentType?: never;
+});
+
+interface AppInit<GlobalParamsSchema extends ZodObj, StageParamsSchema extends ZodObj, EventTypeMapSchema extends ZodObj> {
+    appRootAbs: string;
+    globalParamsSchema: GlobalParamsSchema;
+    stageParamsSchema: StageParamsSchema;
+    eventTypeMapSchema?: EventTypeMapSchema;
+    /** Accept raw serverless config; App will parse it internally. */
+    serverless: z.input<typeof serverlessConfigSchema>;
+    global: {
+        params: z.infer<GlobalParamsSchema>;
+        envKeys: readonly (keyof z.infer<GlobalParamsSchema>)[];
+    };
+    stage: {
+        /** Accept raw stage param objects; App will parse with (global.partial + stage) */
+        params: Record<string, Record<string, unknown>>;
+        envKeys: readonly (keyof z.infer<StageParamsSchema>)[];
+    };
+    /**
+     * HTTP tokens to treat as HTTP at runtime (widenable).
+     * Defaults to ['rest', 'http'].
+     */
+    httpEventTypeTokens?: readonly (keyof z.infer<EventTypeMapSchema>)[];
+    /**
+     * Optional app-level HTTP middleware customization (defaults & profiles).
+     */
+    http?: AppHttpConfig;
+    /** Optional defaults applied to every function (merged per registration). */
+    functionDefaults?: {
+        fnEnvKeys?: readonly string[];
+    };
+}
+/**
+ * Application class. *
+ * @typeParam GlobalParamsSchema - Zod object schema for global parameters
+ * @typeParam StageParamsSchema  - Zod object schema for per‑stage parameters
+ * @typeParam EventTypeMapSchema - Zod object schema mapping event tokens to runtime types
+ */ declare class App<GlobalParamsSchema extends ZodObj, StageParamsSchema extends ZodObj, EventTypeMapSchema extends ZodObj> {
+    /** Helper alias for stage artifacts type */
+    private static readonly _stageArtifactsType;
+    readonly appRootAbs: string;
+    readonly globalParamsSchema: GlobalParamsSchema;
+    readonly stageParamsSchema: StageParamsSchema;
+    readonly eventTypeMapSchema: EventTypeMapSchema;
+    readonly serverless: AppServerlessConfig;
+    readonly global: EnvSchemaNode<GlobalParamsSchema>;
+    readonly stage: EnvSchemaNode<StageParamsSchema>;
+    readonly stages: ReturnType<typeof buildStageArtifacts>['stages'];
+    readonly environment: ReturnType<typeof buildStageArtifacts>['environment'];
+    readonly buildFnEnv: ReturnType<typeof buildStageArtifacts>['buildFnEnv'];
+    readonly http: AppHttpConfig;
+    readonly httpEventTypeTokens: readonly string[];
+    private readonly registry;
+    private constructor(); /**
+     * Ergonomic constructor for schema‑first inference.
+     *
+     * @param init - initialization object (schemas, serverless defaults, params/envKeys)
+     * @returns a new App instance
+     */
+    static create<GlobalParamsSchema extends ZodObj, StageParamsSchema extends ZodObj, EventTypeMapSchema extends ZodObj>(init: AppInit<GlobalParamsSchema, StageParamsSchema, EventTypeMapSchema>): App<GlobalParamsSchema, StageParamsSchema, EventTypeMapSchema>;
+    /**
+     * Register a function (HTTP or non‑HTTP).
+     *
+     * @typeParam EventType      - A key from your eventTypeMapSchema (e.g., 'rest' | 'http' | 'sqs' | 'step')
+     * @typeParam EventSchema    - Optional Zod schema validated BEFORE the handler (refines event shape)
+     * @typeParam ResponseSchema - Optional Zod schema validated AFTER the handler (refines response shape)
+     * @param options - per‑function configuration (method/basePath/httpContexts for HTTP; serverless extras for non‑HTTP)
+     * @returns a per‑function API: { handler(business), openapi(baseOperation), serverless(extras) }
+     */
+    defineFunction<EventType extends Extract<keyof z.infer<EventTypeMapSchema>, string>, EventSchema extends z.ZodType | undefined, ResponseSchema extends z.ZodType | undefined>(options: {
+        functionName?: string;
+        eventType: EventType;
+        method?: MethodKey;
+        basePath?: string;
+        httpContexts?: readonly HttpContext[];
+        contentType?: string;
+        eventSchema?: EventSchema;
+        responseSchema?: ResponseSchema;
+        fnEnvKeys?: readonly (keyof (z.infer<GlobalParamsSchema> & z.infer<StageParamsSchema>))[];
+        callerModuleUrl: string;
+        endpointsRootAbs: string;
+    }): {
+        handler: (business: Handler<EventSchema, ResponseSchema, (z.core.output<EventTypeMapSchema> & {
+            rest: aws_lambda.APIGatewayProxyEvent;
+            http: aws_lambda.APIGatewayProxyEventV2;
+            alb: aws_lambda.ALBEvent;
+            sqs: aws_lambda.SQSEvent;
+            sns: aws_lambda.SNSEvent;
+            s3: aws_lambda.S3Event;
+            dynamodb: aws_lambda.DynamoDBStreamEvent;
+            kinesis: aws_lambda.KinesisStreamEvent;
+            eventbridge: aws_lambda.EventBridgeEvent<string, unknown>;
+            'cloudwatch-logs': aws_lambda.CloudWatchLogsEvent;
+            ses: aws_lambda.SESEvent;
+            cloudfront: aws_lambda.CloudFrontRequestEvent;
+            firehose: aws_lambda.FirehoseTransformationEvent;
+            'cognito-userpool': aws_lambda.CognitoUserPoolTriggerEvent;
+        })[EventType]>) => (event: unknown, context: aws_lambda.Context) => Promise<ResponseSchema extends z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> ? z.core.output<ResponseSchema> : unknown>;
+        openapi: (baseOperation: BaseOperation) => void;
+        serverless: (extras: unknown) => void;
+    };
+    /**
+     * Aggregate Serverless function definitions across the registry.
+     *
+     * @returns An AWS['functions'] object suitable for serverless.ts
+     */
+    buildAllServerlessFunctions(): AWS['functions'];
+    /**
+     * Aggregate OpenAPI path items across the registry.
+     *
+     * @returns ZodOpenApiPathsObject to be embedded in a full OpenAPI document
+     */
+    buildAllOpenApiPaths(): ZodOpenApiPathsObject;
+}
+
+/** Classify the security context from either API Gateway event version. */
+/**
+ * Detect security context from API Gateway v1/v2 events.
+ *
+ * @param evt - unknown event
+ * @returns 'my' when authorized (Cognito/JWT/IAM), 'private' when API key present, else 'public'
+ */
+declare const detectSecurityContext: (evt: unknown) => HttpContext;
+
+/**
+ * Private symbol used to attach env (schemas + envKeys) to FunctionConfig instances.
+ */
+declare const ENV_CONFIG: unique symbol;
+/**
+ * Branding interface that attaches environment metadata to a function config.
+ *
+ * @typeParam GlobalParamsSchema - global params schema
+ * @typeParam StageParamsSchema  - stage params schema
+ * @remarks The brand is read by {@link runtime/wrapHandler.wrapHandler | wrapHandler} to build the typed env object.
+ */
+interface EnvAttached<GlobalParamsSchema extends ZodObject<ZodRawShape>, StageParamsSchema extends ZodObject<ZodRawShape>> {
+    [ENV_CONFIG]: {
+        global: EnvSchemaNode<GlobalParamsSchema>;
+        stage: EnvSchemaNode<StageParamsSchema>;
+    };
+}
+
+/**
+ * DeepOverride
+ * ----------- * For two object types T (base) and U (override), produce a new type where keys present in U
+ * replace those in T; nested objects are recursed. Arrays and primitives are replaced wholesale.
+ *
+ * - If T is `never`, we fall back to U (used when no explicit EventType is provided).
+ * - If U is `never`, we keep T.
+ *
+ * @typeParam T - base type to be overridden
+ * @typeParam U - override type whose keys replace the base
+ *
+ * @example
+ * type A = { x: { a: number }, y: string };
+ * type B = { x: { a: string }, z: boolean };
+ * // => { x: { a: string }, y: string, z: boolean }
+ * type R = DeepOverride<A, B>;
+ */
+type DeepOverride<T, U> = [T] extends [never] ? U : [U] extends [never] ? T : T extends any[] ? U : U extends any[] ? U : T extends object ? U extends object ? {
+    [K in keyof (T & U)]: K extends keyof U ? DeepOverride<K extends keyof T ? T[K] : never, U[K & keyof U]> : K extends keyof T ? T[K] : never;
+} : T : U;
 
 /** Event type after applying deep schema overrides. */
 /**
@@ -370,7 +576,7 @@ type HandlerOptions = {
     /** Present only for HTTP calls; omitted for SQS/Step/etc. */
     securityContext?: unknown;
     /** REQUIRED and must satisfy ConsoleLogger. */
-    logger: ConsoleLogger$1;
+    logger: ConsoleLogger;
 };
 /** Business handler: returns raw payloads; wrapping layers handle HTTP shaping when applicable. */
 /**
@@ -380,11 +586,26 @@ type HandlerOptions = {
  */
 type Handler<EventSchema extends z.ZodType | undefined, ResponseSchema extends z.ZodType | undefined, EventType> = (event: ShapedEvent<EventSchema, EventType>, context: Context, options: HandlerOptions) => Promise<ResponseSchema extends z.ZodType ? z.infer<ResponseSchema> : unknown>;
 
-/** Security context classification used throughout the handlers. */
 /**
- * HTTP security context tokens.
+ * Wrap a business handler with SMOZ runtime. *
+ * - HTTP event tokens receive the full Middy pipeline (validation, shaping, CORS, etc.)
+ * - Non‑HTTP tokens bypass Middy and call the business function directly.
+ *
+ * @typeParam GlobalParamsSchema - global params schema type
+ * @typeParam StageParamsSchema  - stage params schema type
+ * @typeParam EventTypeMap       - event token → runtime type map
+ * @typeParam EventType          - a key of EventTypeMap
+ * @typeParam EventSchema        - optional Zod schema for event (validated before handler)
+ * @typeParam ResponseSchema     - optional Zod schema for response (validated after handler)
+ * @param functionConfig - per‑function configuration (branded with env nodes)
+ * @param business - the business handler implementation
+ * @param opts - optional runtime overrides (e.g., widen HTTP tokens)
+ * @returns a Lambda‑compatible handler function
  */
-type HttpContext = 'my' | 'private' | 'public';
+declare function wrapHandler<GlobalParamsSchema extends ZodObject<ZodRawShape>, StageParamsSchema extends ZodObject<ZodRawShape>, EventTypeMap extends BaseEventTypeMap, EventType extends keyof EventTypeMap, EventSchema extends z.ZodType | undefined, ResponseSchema extends z.ZodType | undefined>(functionConfig: FunctionConfig<EventSchema, ResponseSchema, z.infer<GlobalParamsSchema>, z.infer<StageParamsSchema>, EventTypeMap, EventType> & EnvAttached<GlobalParamsSchema, StageParamsSchema>, business: Handler<EventSchema, ResponseSchema, EventTypeMap[EventType]>, opts?: {
+    httpEventTypeTokens?: readonly string[];
+    httpConfig?: AppHttpConfig;
+}): (event: unknown, context: Context) => Promise<ResponseSchema extends z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>> ? z.core.output<ResponseSchema> : unknown>;
 
 /**
  * REQUIREMENTS ADDRESSED
@@ -396,17 +617,6 @@ type HttpContext = 'my' | 'private' | 'public';
  */
 type LambdaEvent = Record<string, unknown>;
 
-type ConsoleLogger = Pick<Console, 'debug' | 'error' | 'info' | 'log'>;
-
-/**
- * Opaque Serverless event fragments keyed by security context.
- *
- * @remarks
- * Shape is intentionally platform‑specific; used by the App to decorate
- * generated HTTP events based on 'my' | 'private' | 'public' contexts.
- */
-type SecurityContextHttpEventMap = Record<HttpContext$1, Partial<PropFromUnion<PropFromUnion<PropFromUnion<AWS['functions'], string>['events'], number>, 'http'>>>;
-
 /** Normalize a path to POSIX separators. */
 declare const toPosixPath: (p: string) => string;
 /**