effortless-aws 0.7.1 → 0.8.0

package/dist/index.d.ts

@@ -88,6 +88,118 @@ type EffortlessConfig = {
  */
 declare const defineConfig: (config: EffortlessConfig) => EffortlessConfig;
 
+type AwsService = "dynamodb" | "s3" | "sqs" | "sns" | "ses" | "ssm" | "lambda" | "events" | "secretsmanager" | "cognito-idp" | "logs";
+type Permission = `${AwsService}:${string}` | (string & {});
+/** Logging verbosity level for Lambda handlers */
+type LogLevel = "error" | "info" | "debug";
+/**
+ * Common Lambda configuration shared by all handler types.
+ */
+type LambdaConfig = {
+    /** Handler name. Defaults to export name if not specified */
+    name?: string;
+    /** Lambda memory in MB (default: 256) */
+    memory?: number;
+    /** Lambda timeout in seconds (default: 30) */
+    timeout?: number;
+    /** Logging verbosity: "error" (errors only), "info" (+ execution summary), "debug" (+ input/output). Default: "info" */
+    logLevel?: LogLevel;
+};
+/**
+ * Lambda configuration with additional IAM permissions.
+ * Used by handler types that support custom permissions (http, table, fifo-queue).
+ */
+type LambdaWithPermissions = LambdaConfig & {
+    /** Additional IAM permissions for the Lambda */
+    permissions?: Permission[];
+};
+type AnyParamRef = ParamRef<any> | string;
+/**
+ * Reference to an SSM Parameter Store parameter.
+ *
+ * @typeParam T - The resolved type after optional transform (default: string)
+ */
+type ParamRef<T = string> = {
+    readonly __brand: "effortless-param";
+    readonly key: string;
+    readonly transform?: (raw: string) => T;
+};
+/**
+ * Maps a config declaration to resolved value types.
+ * Plain strings resolve to `string`, `ParamRef<T>` resolves to `T`.
+ *
+ * @typeParam P - Record of config keys to string or ParamRef instances
+ */
+type ResolveConfig<P> = {
+    [K in keyof P]: P[K] extends ParamRef<infer T> ? T : string;
+};
+/**
+ * Declare an SSM Parameter Store parameter.
+ *
+ * The key is combined with project and stage at deploy time to form the full
+ * SSM path: `/${project}/${stage}/${key}`.
+ *
+ * @param key - Parameter key (e.g., "database-url")
+ * @param transform - Optional function to transform the raw string value
+ * @returns A ParamRef used by the deployment and runtime systems
+ *
+ * @example Simple string parameter
+ * ```typescript
+ * config: {
+ *   dbUrl: param("database-url"),
+ * }
+ * ```
+ *
+ * @example With transform (e.g., TOML parsing)
+ * ```typescript
+ * import TOML from "smol-toml";
+ *
+ * config: {
+ *   appConfig: param("app-config", TOML.parse),
+ * }
+ * ```
+ */
+declare function param(key: string): ParamRef<string>;
+declare function param<T>(key: string, transform: (raw: string) => T): ParamRef<T>;
+/**
+ * Type-only schema helper for handlers.
+ *
+ * Use this instead of explicit generic parameters like `defineTable<Order>(...)`.
+ * It enables TypeScript to infer all generic types from the options object,
+ * avoiding the partial-inference problem where specifying one generic
+ * forces all others to their defaults.
+ *
+ * At runtime this is a no-op identity function — it simply returns the input unchanged.
+ * The type narrowing happens entirely at the TypeScript level.
+ *
+ * @example Resource-only table
+ * ```typescript
+ * type User = { id: string; email: string };
+ *
+ * // Before (breaks inference for setup, deps, config):
+ * export const users = defineTable<User>({ pk: { name: "id", type: "string" } });
+ *
+ * // After (all generics inferred correctly):
+ * export const users = defineTable({
+ *   pk: { name: "id", type: "string" },
+ *   schema: typed<User>(),
+ * });
+ * ```
+ *
+ * @example Table with stream handler
+ * ```typescript
+ * export const orders = defineTable({
+ *   pk: { name: "id", type: "string" },
+ *   schema: typed<Order>(),
+ *   setup: async () => ({ db: createClient() }),
+ *   onRecord: async ({ record, ctx }) => {
+ *     // record.new is Order, ctx is { db: Client } — all inferred
+ *   },
+ * });
+ * ```
+ */
+declare function typed<T>(): (input: unknown) => T;
+
 /**
  * Query parameters for TableClient.query()
  */
@@ -164,7 +276,7 @@ type TableKey = {
 /** DynamoDB Streams view type - determines what data is captured in stream records */
 type StreamView = "NEW_AND_OLD_IMAGES" | "NEW_IMAGE" | "OLD_IMAGE" | "KEYS_ONLY";
 /**
- * Configuration options extracted from DefineTableOptions (without onRecord/context)
+ * Configuration options extracted from DefineTableOptions (without onRecord/setup)
  */
 type TableConfig = LambdaWithPermissions & {
     /** Partition key definition */
@@ -215,13 +327,15 @@ type FailedRecord<T = Record<string, unknown>> = {
     error: unknown;
 };
 /**
- * Context factory type — conditional on whether params are declared.
- * Without params: `() => C | Promise<C>`
- * With params: `(args: { params: ResolveParams<P> }) => C | Promise<C>`
+ * Setup factory type — conditional on whether deps/config are declared.
+ * No deps/config: `() => C | Promise<C>`
+ * With deps/config: `(args: { deps?, config? }) => C | Promise<C>`
  */
-type ContextFactory$2<C, P> = [P] extends [undefined] ? () => C | Promise<C> : (args: {
-    params: ResolveParams<P & {}>;
-}) => C | Promise<C>;
+type SetupFactory$2<C, D, P> = [D | P] extends [undefined] ? () => C | Promise<C> : (args: ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps$2<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P & {}>;
+})) => C | Promise<C>;
 /**
  * Callback function type for processing a single DynamoDB stream record
  */
@@ -233,7 +347,7 @@ type TableRecordFn<T = Record<string, unknown>, C = undefined, R = void, D = und
 }) & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps$2<D>;
 }) & ([P] extends [undefined] ? {} : {
-    params: ResolveParams<P>;
+    config: ResolveConfig<P>;
 }) & ([S] extends [undefined] ? {} : {
     readStatic: (path: string) => string;
 })) => Promise<R>;
@@ -249,7 +363,7 @@ type TableBatchCompleteFn<T = Record<string, unknown>, C = undefined, R = void,
 }) & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps$2<D>;
 }) & ([P] extends [undefined] ? {} : {
-    params: ResolveParams<P>;
+    config: ResolveConfig<P>;
 }) & ([S] extends [undefined] ? {} : {
     readStatic: (path: string) => string;
 })) => Promise<void>;
@@ -264,7 +378,7 @@ type TableBatchFn<T = Record<string, unknown>, C = undefined, D = undefined, P =
 }) & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps$2<D>;
 }) & ([P] extends [undefined] ? {} : {
-    params: ResolveParams<P>;
+    config: ResolveConfig<P>;
 }) & ([S] extends [undefined] ? {} : {
     readStatic: (path: string) => string;
 })) => Promise<void>;
@@ -282,12 +396,12 @@ type DefineTableBase<T = Record<string, unknown>, C = undefined, D = undefined,
      */
     onError?: (error: unknown) => void;
     /**
-     * Factory function to create context/dependencies for callbacks.
+     * Factory function to initialize shared state for callbacks.
      * Called once on cold start, result is cached and reused across invocations.
-     * When params are declared, receives resolved params as argument.
+     * When deps/params are declared, receives them as argument.
      * Supports both sync and async return values.
      */
-    context?: ContextFactory$2<C, P>;
+    setup?: SetupFactory$2<C, D, P>;
     /**
      * Dependencies on other handlers (tables, queues, etc.).
      * Typed clients are injected into the handler via the `deps` argument.
@@ -296,9 +410,9 @@ type DefineTableBase<T = Record<string, unknown>, C = undefined, D = undefined,
     /**
      * SSM Parameter Store parameters.
      * Declare with `param()` helper. Values are fetched and cached at cold start.
-     * Typed values are injected into the handler via the `params` argument.
+     * Typed values are injected into the handler via the `config` argument.
      */
-    params?: P;
+    config?: P;
     /**
      * Static file glob patterns to bundle into the Lambda ZIP.
      * Files are accessible at runtime via the `readStatic` callback argument.
@@ -330,12 +444,12 @@ type DefineTableOptions<T = Record<string, unknown>, C = undefined, R = void, D
  */
 type TableHandler<T = Record<string, unknown>, C = undefined, R = void, D = undefined, P = undefined, S extends string[] | undefined = undefined> = {
     readonly __brand: "effortless-table";
-    readonly config: TableConfig;
+    readonly __spec: TableConfig;
     readonly schema?: (input: unknown) => T;
     readonly onError?: (error: unknown) => void;
-    readonly context?: (...args: any[]) => C | Promise<C>;
+    readonly setup?: (...args: any[]) => C | Promise<C>;
     readonly deps?: D;
-    readonly params?: P;
+    readonly config?: P;
     readonly static?: string[];
     readonly onRecord?: TableRecordFn<T, C, R, D, P, S>;
     readonly onBatchComplete?: TableBatchCompleteFn<T, C, R, D, P, S>;
@@ -374,110 +488,311 @@ type TableHandler<T = Record<string, unknown>, C = undefined, R = void, D = unde
  */
 declare const defineTable: <T = Record<string, unknown>, C = undefined, R = void, D extends Record<string, AnyTableHandler$2> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined>(options: DefineTableOptions<T, C, R, D, P, S>) => TableHandler<T, C, R, D, P, S>;
 
-/**
- * Configuration for a Lambda-served static site (API Gateway + Lambda)
- */
-type AppConfig = LambdaConfig & {
-    /** Base URL path the site is served under (e.g., "/app") */
-    path?: string;
-    /** Directory containing the static site files, relative to project root */
-    dir: string;
-    /** Default file for directory requests (default: "index.html") */
-    index?: string;
-    /** SPA mode: serve index.html for all paths that don't match a file (default: false) */
-    spa?: boolean;
-    /** Shell command to run before deploy to generate site content (e.g., "npx astro build") */
-    build?: string;
+type AnyTableHandler$1 = TableHandler<any, any, any, any, any, any>;
+/** Maps a deps declaration to resolved runtime client types */
+type ResolveDeps$1<D> = {
+    [K in keyof D]: D[K] extends TableHandler<infer T, any, any, any, any> ? TableClient<T> : never;
 };
+/** HTTP methods supported by API Gateway */
+type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+/** Short content-type aliases for common response formats */
+type ContentType = "json" | "html" | "text" | "css" | "js" | "xml" | "csv" | "svg";
 /**
- * Internal handler object created by defineApp
- * @internal
+ * Incoming HTTP request object passed to the handler
  */
-type AppHandler = {
-    readonly __brand: "effortless-app";
-    readonly config: AppConfig;
+type HttpRequest = {
+    /** HTTP method (GET, POST, etc.) */
+    method: string;
+    /** Request path (e.g., "/users/123") */
+    path: string;
+    /** Request headers */
+    headers: Record<string, string | undefined>;
+    /** Query string parameters */
+    query: Record<string, string | undefined>;
+    /** Path parameters extracted from route (e.g., {id} -> params.id) */
+    params: Record<string, string | undefined>;
+    /** Parsed request body (JSON parsed if Content-Type is application/json) */
+    body: unknown;
+    /** Raw unparsed request body */
+    rawBody?: string;
 };
 /**
- * Deploy a static site via Lambda + API Gateway.
- * Files are bundled into the Lambda ZIP and served with auto-detected content types.
- *
- * For CDN-backed sites (S3 + CloudFront), use {@link defineStaticSite} instead.
- *
- * @param options - Site configuration: path, directory, optional SPA mode
- * @returns Handler object used by the deployment system
- *
- * @example Basic static site
- * ```typescript
- * export const app = defineApp({
- *   path: "/app",
- *   dir: "src/webapp",
- * });
- * ```
- */
-declare const defineApp: (options: AppConfig) => AppHandler;
-
-/**
- * Configuration for a static site handler (S3 + CloudFront)
+ * HTTP response returned from the handler
  */
-type StaticSiteConfig = {
-    /** Handler name. Defaults to export name if not specified */
-    name?: string;
-    /** Directory containing the static site files, relative to project root */
-    dir: string;
-    /** Default file for directory requests (default: "index.html") */
-    index?: string;
-    /** SPA mode: serve index.html for all paths that don't match a file (default: false) */
-    spa?: boolean;
-    /** Shell command to run before deploy to generate site content (e.g., "npx astro build") */
-    build?: string;
+type HttpResponse = {
+    /** HTTP status code (e.g., 200, 404, 500) */
+    status: number;
+    /** Response body — JSON-serialized by default, or sent as string when contentType is set */
+    body?: unknown;
+    /**
+     * Short content-type alias. Resolves to full MIME type automatically:
+     * - `"json"` → `application/json` (default if omitted)
+     * - `"html"` → `text/html; charset=utf-8`
+     * - `"text"` → `text/plain; charset=utf-8`
+     * - `"css"` → `text/css; charset=utf-8`
+     * - `"js"` → `application/javascript; charset=utf-8`
+     * - `"xml"` → `application/xml; charset=utf-8`
+     * - `"csv"` → `text/csv; charset=utf-8`
+     * - `"svg"` → `image/svg+xml; charset=utf-8`
+     */
+    contentType?: ContentType;
+    /** Response headers (use for custom content-types not covered by contentType) */
+    headers?: Record<string, string>;
 };
 /**
- * Internal handler object created by defineStaticSite
- * @internal
+ * Configuration options extracted from DefineHttpOptions (without onRequest callback)
  */
-type StaticSiteHandler = {
-    readonly __brand: "effortless-static-site";
-    readonly config: StaticSiteConfig;
+type HttpConfig = LambdaWithPermissions & {
+    /** HTTP method for the route */
+    method: HttpMethod;
+    /** Route path (e.g., "/api/users", "/api/users/{id}") */
+    path: string;
 };
 /**
- * Deploy a static site via S3 + CloudFront CDN.
- *
- * @param options - Static site configuration: directory, optional SPA mode, build command
- * @returns Handler object used by the deployment system
- *
- * @example Documentation site
- * ```typescript
- * export const docs = defineStaticSite({
- *   dir: "dist",
- *   build: "npx astro build",
- * });
- * ```
+ * Handler function type for HTTP endpoints
  *
- * @example SPA with client-side routing
- * ```typescript
- * export const app = defineStaticSite({
- *   dir: "dist",
- *   spa: true,
- *   build: "npm run build",
- * });
- * ```
+ * @typeParam T - Type of the validated request body (from schema function)
+ * @typeParam C - Type of the setup result (from setup function)
+ * @typeParam D - Type of the deps (from deps declaration)
+ * @typeParam P - Type of the params (from params declaration)
  */
-declare const defineStaticSite: (options: StaticSiteConfig) => StaticSiteHandler;
-
-type AnyTableHandler$1 = TableHandler<any, any, any, any, any, any>;
-/** Maps a deps declaration to resolved runtime client types */
-type ResolveDeps$1<D> = {
-    [K in keyof D]: D[K] extends TableHandler<infer T, any, any, any, any> ? TableClient<T> : never;
-};
+type HttpHandlerFn<T = undefined, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = (args: {
+    req: HttpRequest;
+} & ([T] extends [undefined] ? {} : {
+    data: T;
+}) & ([C] extends [undefined] ? {} : {
+    ctx: C;
+}) & ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps$1<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P>;
+}) & ([S] extends [undefined] ? {} : {
+    readStatic: (path: string) => string;
+})) => Promise<HttpResponse>;
 /**
- * Parsed SQS FIFO message passed to the handler callbacks.
- *
- * @typeParam T - Type of the decoded message body (from schema function)
+ * Setup factory type — conditional on whether deps/config are declared.
+ * No deps/config: `() => C | Promise<C>`
+ * With deps/config: `(args: { deps?, config? }) => C | Promise<C>`
  */
-type FifoQueueMessage<T = unknown> = {
-    /** Unique message identifier */
-    messageId: string;
-    /** Receipt handle for acknowledgement */
+type SetupFactory$1<C, D, P> = [D | P] extends [undefined] ? () => C | Promise<C> : (args: ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps$1<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P & {}>;
+})) => C | Promise<C>;
+/**
+ * Options for defining an HTTP endpoint
+ *
+ * @typeParam T - Type of the validated request body (inferred from schema function)
+ * @typeParam C - Type of the setup result returned by setup function
+ * @typeParam D - Type of the deps (from deps declaration)
+ * @typeParam P - Type of the params (from params declaration)
+ */
+type DefineHttpOptions<T = undefined, C = undefined, D extends Record<string, AnyTableHandler$1> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined> = HttpConfig & {
+    /**
+     * Decode/validate function for the request body.
+     * Called with the parsed body; should return typed data or throw on validation failure.
+     * When provided, the handler receives validated `data` and invalid requests get a 400 response.
+     *
+     * Works with any validation library:
+     * - Effect: `S.decodeUnknownSync(MySchema)`
+     * - Zod: `(body) => myZodSchema.parse(body)`
+     */
+    schema?: (input: unknown) => T;
+    /**
+     * Error handler called when schema validation or onRequest throws.
+     * Receives the error and request, returns an HttpResponse.
+     * If not provided, defaults to 400 for validation errors and 500 for handler errors.
+     */
+    onError?: (error: unknown, req: HttpRequest) => HttpResponse;
+    /**
+     * Factory function to initialize shared state for the request handler.
+     * Called once on cold start, result is cached and reused across invocations.
+     * When deps/params are declared, receives them as argument.
+     * Supports both sync and async return values.
+     */
+    setup?: SetupFactory$1<C, D, P>;
+    /**
+     * Dependencies on other handlers (tables, queues, etc.).
+     * Typed clients are injected into the handler via the `deps` argument.
+     */
+    deps?: D;
+    /**
+     * SSM Parameter Store parameters.
+     * Declare with `param()` helper. Values are fetched and cached at cold start.
+     * Typed values are injected into the handler via the `config` argument.
+     */
+    config?: P;
+    /**
+     * Static file glob patterns to bundle into the Lambda ZIP.
+     * Files are accessible at runtime via the `readStatic` callback argument.
+     */
+    static?: S;
+    /** HTTP request handler function */
+    onRequest: HttpHandlerFn<T, C, D, P, S>;
+};
+/**
+ * Internal handler object created by defineHttp
+ * @internal
+ */
+type HttpHandler<T = undefined, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = {
+    readonly __brand: "effortless-http";
+    readonly __spec: HttpConfig;
+    readonly schema?: (input: unknown) => T;
+    readonly onError?: (error: unknown, req: HttpRequest) => HttpResponse;
+    readonly setup?: (...args: any[]) => C | Promise<C>;
+    readonly deps?: D;
+    readonly config?: P;
+    readonly static?: string[];
+    readonly onRequest: HttpHandlerFn<T, C, D, P, S>;
+};
+/**
+ * Define an HTTP endpoint that creates an API Gateway route + Lambda function
+ *
+ * @typeParam T - Type of the validated request body (inferred from schema function)
+ * @typeParam C - Type of the setup result (inferred from setup function)
+ * @typeParam D - Type of the deps (from deps declaration)
+ * @typeParam P - Type of the params (from params declaration)
+ * @param options - Configuration, optional schema, optional setup factory, and request handler
+ * @returns Handler object used by the deployment system
+ *
+ * @example Basic GET endpoint
+ * ```typescript
+ * export const hello = defineHttp({
+ *   method: "GET",
+ *   path: "/hello",
+ *   onRequest: async ({ req }) => ({
+ *     status: 200,
+ *     body: { message: "Hello World!" }
+ *   })
+ * });
+ * ```
+ *
+ * @example With SSM parameters
+ * ```typescript
+ * import { param } from "effortless-aws";
+ *
+ * export const api = defineHttp({
+ *   method: "GET",
+ *   path: "/orders",
+ *   config: {
+ *     dbUrl: param("database-url"),
+ *   },
+ *   setup: async ({ config }) => ({
+ *     pool: createPool(config.dbUrl),
+ *   }),
+ *   onRequest: async ({ req, ctx, config }) => ({
+ *     status: 200,
+ *     body: { dbUrl: config.dbUrl }
+ *   })
+ * });
+ * ```
+ */
+declare const defineHttp: <T = undefined, C = undefined, D extends Record<string, AnyTableHandler$1> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined>(options: DefineHttpOptions<T, C, D, P, S>) => HttpHandler<T, C, D, P, S>;
+
+/**
+ * Configuration for a Lambda-served static site (API Gateway + Lambda)
+ */
+type AppConfig = LambdaConfig & {
+    /** Base URL path the site is served under (e.g., "/app") */
+    path?: string;
+    /** Directory containing the static site files, relative to project root */
+    dir: string;
+    /** Default file for directory requests (default: "index.html") */
+    index?: string;
+    /** SPA mode: serve index.html for all paths that don't match a file (default: false) */
+    spa?: boolean;
+    /** Shell command to run before deploy to generate site content (e.g., "npx astro build") */
+    build?: string;
+};
+/**
+ * Internal handler object created by defineApp
+ * @internal
+ */
+type AppHandler = {
+    readonly __brand: "effortless-app";
+    readonly __spec: AppConfig;
+};
+/**
+ * Deploy a static site via Lambda + API Gateway.
+ * Files are bundled into the Lambda ZIP and served with auto-detected content types.
+ *
+ * For CDN-backed sites (S3 + CloudFront), use {@link defineStaticSite} instead.
+ *
+ * @param options - Site configuration: path, directory, optional SPA mode
+ * @returns Handler object used by the deployment system
+ *
+ * @example Basic static site
+ * ```typescript
+ * export const app = defineApp({
+ *   path: "/app",
+ *   dir: "src/webapp",
+ * });
+ * ```
+ */
+declare const defineApp: (options: AppConfig) => AppHandler;
+
+/**
+ * Configuration for a static site handler (S3 + CloudFront)
+ */
+type StaticSiteConfig = {
+    /** Handler name. Defaults to export name if not specified */
+    name?: string;
+    /** Directory containing the static site files, relative to project root */
+    dir: string;
+    /** Default file for directory requests (default: "index.html") */
+    index?: string;
+    /** SPA mode: serve index.html for all paths that don't match a file (default: false) */
+    spa?: boolean;
+    /** Shell command to run before deploy to generate site content (e.g., "npx astro build") */
+    build?: string;
+};
+/**
+ * Internal handler object created by defineStaticSite
+ * @internal
+ */
+type StaticSiteHandler = {
+    readonly __brand: "effortless-static-site";
+    readonly __spec: StaticSiteConfig;
+};
+/**
+ * Deploy a static site via S3 + CloudFront CDN.
+ *
+ * @param options - Static site configuration: directory, optional SPA mode, build command
+ * @returns Handler object used by the deployment system
+ *
+ * @example Documentation site
+ * ```typescript
+ * export const docs = defineStaticSite({
+ *   dir: "dist",
+ *   build: "npx astro build",
+ * });
+ * ```
+ *
+ * @example SPA with client-side routing
+ * ```typescript
+ * export const app = defineStaticSite({
+ *   dir: "dist",
+ *   spa: true,
+ *   build: "npm run build",
+ * });
+ * ```
+ */
+declare const defineStaticSite: (options: StaticSiteConfig) => StaticSiteHandler;
+
+type AnyTableHandler = TableHandler<any, any, any, any, any, any>;
+/** Maps a deps declaration to resolved runtime client types */
+type ResolveDeps<D> = {
+    [K in keyof D]: D[K] extends TableHandler<infer T, any, any, any, any> ? TableClient<T> : never;
+};
+/**
+ * Parsed SQS FIFO message passed to the handler callbacks.
+ *
+ * @typeParam T - Type of the decoded message body (from schema function)
+ */
+type FifoQueueMessage<T = unknown> = {
+    /** Unique message identifier */
+    messageId: string;
+    /** Receipt handle for acknowledgement */
     receiptHandle: string;
     /** Parsed message body (JSON-decoded, then optionally schema-validated) */
     body: T;
@@ -515,13 +830,15 @@ type FifoQueueConfig = LambdaWithPermissions & {
     contentBasedDeduplication?: boolean;
 };
 /**
- * Context factory type — conditional on whether params are declared.
- * Without params: `() => C | Promise<C>`
- * With params: `(args: { params: ResolveParams<P> }) => C | Promise<C>`
+ * Setup factory type — conditional on whether deps/config are declared.
+ * No deps/config: `() => C | Promise<C>`
+ * With deps/config: `(args: { deps?, config? }) => C | Promise<C>`
  */
-type ContextFactory$1<C, P> = [P] extends [undefined] ? () => C | Promise<C> : (args: {
-    params: ResolveParams<P & {}>;
-}) => C | Promise<C>;
+type SetupFactory<C, D, P> = [D | P] extends [undefined] ? () => C | Promise<C> : (args: ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P & {}>;
+})) => C | Promise<C>;
 /**
  * Per-message handler function.
  * Called once per message in the batch. Failures are reported individually.
@@ -531,9 +848,9 @@ type FifoQueueMessageFn<T = unknown, C = undefined, D = undefined, P = undefined
 } & ([C] extends [undefined] ? {} : {
     ctx: C;
 }) & ([D] extends [undefined] ? {} : {
-    deps: ResolveDeps$1<D>;
+    deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
-    params: ResolveParams<P>;
+    config: ResolveConfig<P>;
 }) & ([S] extends [undefined] ? {} : {
     readStatic: (path: string) => string;
 })) => Promise<void>;
@@ -546,9 +863,9 @@ type FifoQueueBatchFn<T = unknown, C = undefined, D = undefined, P = undefined,
 } & ([C] extends [undefined] ? {} : {
     ctx: C;
 }) & ([D] extends [undefined] ? {} : {
-    deps: ResolveDeps$1<D>;
+    deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
-    params: ResolveParams<P>;
+    config: ResolveConfig<P>;
 }) & ([S] extends [undefined] ? {} : {
     readStatic: (path: string) => string;
 })) => Promise<void>;
@@ -565,11 +882,11 @@ type DefineFifoQueueBase<T = unknown, C = undefined, D = undefined, P = undefine
      */
     onError?: (error: unknown) => void;
     /**
-     * Factory function to create context/dependencies for the handler.
+     * Factory function to initialize shared state for the handler.
      * Called once on cold start, result is cached and reused across invocations.
-     * When params are declared, receives resolved params as argument.
+     * When deps/params are declared, receives them as argument.
      */
-    context?: ContextFactory$1<C, P>;
+    setup?: SetupFactory<C, D, P>;
     /**
      * Dependencies on other handlers (tables, queues, etc.).
      * Typed clients are injected into the handler via the `deps` argument.
@@ -579,7 +896,7 @@ type DefineFifoQueueBase<T = unknown, C = undefined, D = undefined, P = undefine
      * SSM Parameter Store parameters.
      * Declare with `param()` helper. Values are fetched and cached at cold start.
      */
-    params?: P;
+    config?: P;
     /**
      * Static file glob patterns to bundle into the Lambda ZIP.
      * Files are accessible at runtime via the `readStatic` callback argument.
@@ -596,19 +913,19 @@ type DefineFifoQueueWithOnBatch<T = unknown, C = undefined, D = undefined, P = u
     onBatch: FifoQueueBatchFn<T, C, D, P, S>;
     onMessage?: never;
 };
-type DefineFifoQueueOptions<T = unknown, C = undefined, D extends Record<string, AnyTableHandler$1> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined> = DefineFifoQueueWithOnMessage<T, C, D, P, S> | DefineFifoQueueWithOnBatch<T, C, D, P, S>;
+type DefineFifoQueueOptions<T = unknown, C = undefined, D extends Record<string, AnyTableHandler> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined> = DefineFifoQueueWithOnMessage<T, C, D, P, S> | DefineFifoQueueWithOnBatch<T, C, D, P, S>;
 /**
  * Internal handler object created by defineFifoQueue
  * @internal
  */
 type FifoQueueHandler<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = {
     readonly __brand: "effortless-fifo-queue";
-    readonly config: FifoQueueConfig;
+    readonly __spec: FifoQueueConfig;
     readonly schema?: (input: unknown) => T;
     readonly onError?: (error: unknown) => void;
-    readonly context?: (...args: any[]) => C | Promise<C>;
+    readonly setup?: (...args: any[]) => C | Promise<C>;
     readonly deps?: D;
-    readonly params?: P;
+    readonly config?: P;
     readonly static?: string[];
     readonly onMessage?: FifoQueueMessageFn<T, C, D, P, S>;
     readonly onBatch?: FifoQueueBatchFn<T, C, D, P, S>;
@@ -643,316 +960,6 @@ type FifoQueueHandler<T = unknown, C = undefined, D = undefined, P = undefined,
  * });
  * ```
  */
-declare const defineFifoQueue: <T = unknown, C = undefined, D extends Record<string, AnyTableHandler$1> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined>(options: DefineFifoQueueOptions<T, C, D, P, S>) => FifoQueueHandler<T, C, D, P, S>;
-
-type AwsService = "dynamodb" | "s3" | "sqs" | "sns" | "ses" | "ssm" | "lambda" | "events" | "secretsmanager" | "cognito-idp" | "logs";
-type Permission = `${AwsService}:${string}` | (string & {});
-/** Logging verbosity level for Lambda handlers */
-type LogLevel = "error" | "info" | "debug";
-/**
- * Common Lambda configuration shared by all handler types.
- */
-type LambdaConfig = {
-    /** Handler name. Defaults to export name if not specified */
-    name?: string;
-    /** Lambda memory in MB (default: 256) */
-    memory?: number;
-    /** Lambda timeout in seconds (default: 30) */
-    timeout?: number;
-    /** Logging verbosity: "error" (errors only), "info" (+ execution summary), "debug" (+ input/output). Default: "info" */
-    logLevel?: LogLevel;
-};
-/**
- * Lambda configuration with additional IAM permissions.
- * Used by handler types that support custom permissions (http, table, fifo-queue).
- */
-type LambdaWithPermissions = LambdaConfig & {
-    /** Additional IAM permissions for the Lambda */
-    permissions?: Permission[];
-};
-type AnyParamRef = ParamRef<any>;
-/**
- * Reference to an SSM Parameter Store parameter.
- *
- * @typeParam T - The resolved type after optional transform (default: string)
- */
-type ParamRef<T = string> = {
-    readonly __brand: "effortless-param";
-    readonly key: string;
-    readonly transform?: (raw: string) => T;
-};
-/**
- * Maps a params declaration to resolved value types.
- *
- * @typeParam P - Record of param names to ParamRef instances
- */
-type ResolveParams<P> = {
-    [K in keyof P]: P[K] extends ParamRef<infer T> ? T : never;
-};
-/**
- * Declare an SSM Parameter Store parameter.
- *
- * The key is combined with project and stage at deploy time to form the full
- * SSM path: `/${project}/${stage}/${key}`.
- *
- * @param key - Parameter key (e.g., "database-url")
- * @param transform - Optional function to transform the raw string value
- * @returns A ParamRef used by the deployment and runtime systems
- *
- * @example Simple string parameter
- * ```typescript
- * params: {
- *   dbUrl: param("database-url"),
- * }
- * ```
- *
- * @example With transform (e.g., TOML parsing)
- * ```typescript
- * import TOML from "smol-toml";
- *
- * params: {
- *   config: param("app-config", TOML.parse),
- * }
- * ```
- */
-declare function param(key: string): ParamRef<string>;
-declare function param<T>(key: string, transform: (raw: string) => T): ParamRef<T>;
-/**
- * Type-only schema helper for handlers.
- *
- * Use this instead of explicit generic parameters like `defineTable<Order>(...)`.
- * It enables TypeScript to infer all generic types from the options object,
- * avoiding the partial-inference problem where specifying one generic
- * forces all others to their defaults.
- *
- * At runtime this is a no-op identity function — it simply returns the input unchanged.
- * The type narrowing happens entirely at the TypeScript level.
- *
- * @example Resource-only table
- * ```typescript
- * type User = { id: string; email: string };
- *
- * // Before (breaks inference for context, deps, params):
- * export const users = defineTable<User>({ pk: { name: "id", type: "string" } });
- *
- * // After (all generics inferred correctly):
- * export const users = defineTable({
- *   pk: { name: "id", type: "string" },
- *   schema: typed<User>(),
- * });
- * ```
- *
- * @example Table with stream handler
- * ```typescript
- * export const orders = defineTable({
- *   pk: { name: "id", type: "string" },
- *   schema: typed<Order>(),
- *   context: async () => ({ db: createClient() }),
- *   onRecord: async ({ record, ctx }) => {
- *     // record.new is Order, ctx is { db: Client } — all inferred
- *   },
- * });
- * ```
- */
-declare function typed<T>(): (input: unknown) => T;
-
-type AnyTableHandler = TableHandler<any, any, any, any, any, any>;
-/** Maps a deps declaration to resolved runtime client types */
-type ResolveDeps<D> = {
-    [K in keyof D]: D[K] extends TableHandler<infer T, any, any, any, any> ? TableClient<T> : never;
-};
-/** HTTP methods supported by API Gateway */
-type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
-/** Short content-type aliases for common response formats */
-type ContentType = "json" | "html" | "text" | "css" | "js" | "xml" | "csv" | "svg";
-/**
- * Incoming HTTP request object passed to the handler
- */
-type HttpRequest = {
-    /** HTTP method (GET, POST, etc.) */
-    method: string;
-    /** Request path (e.g., "/users/123") */
-    path: string;
-    /** Request headers */
-    headers: Record<string, string | undefined>;
-    /** Query string parameters */
-    query: Record<string, string | undefined>;
-    /** Path parameters extracted from route (e.g., {id} -> params.id) */
-    params: Record<string, string | undefined>;
-    /** Parsed request body (JSON parsed if Content-Type is application/json) */
-    body: unknown;
-    /** Raw unparsed request body */
-    rawBody?: string;
-};
-/**
- * HTTP response returned from the handler
- */
-type HttpResponse = {
-    /** HTTP status code (e.g., 200, 404, 500) */
-    status: number;
-    /** Response body — JSON-serialized by default, or sent as string when contentType is set */
-    body?: unknown;
-    /**
-     * Short content-type alias. Resolves to full MIME type automatically:
-     * - `"json"` → `application/json` (default if omitted)
-     * - `"html"` → `text/html; charset=utf-8`
-     * - `"text"` → `text/plain; charset=utf-8`
-     * - `"css"` → `text/css; charset=utf-8`
-     * - `"js"` → `application/javascript; charset=utf-8`
-     * - `"xml"` → `application/xml; charset=utf-8`
-     * - `"csv"` → `text/csv; charset=utf-8`
-     * - `"svg"` → `image/svg+xml; charset=utf-8`
-     */
-    contentType?: ContentType;
-    /** Response headers (use for custom content-types not covered by contentType) */
-    headers?: Record<string, string>;
-};
-/**
- * Configuration options extracted from DefineHttpOptions (without onRequest callback)
- */
-type HttpConfig = LambdaWithPermissions & {
-    /** HTTP method for the route */
-    method: HttpMethod;
-    /** Route path (e.g., "/api/users", "/api/users/{id}") */
-    path: string;
-};
-/**
- * Handler function type for HTTP endpoints
- *
- * @typeParam T - Type of the validated request body (from schema function)
- * @typeParam C - Type of the context/dependencies (from context function)
- * @typeParam D - Type of the deps (from deps declaration)
- * @typeParam P - Type of the params (from params declaration)
- */
-type HttpHandlerFn<T = undefined, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = (args: {
-    req: HttpRequest;
-} & ([T] extends [undefined] ? {} : {
-    data: T;
-}) & ([C] extends [undefined] ? {} : {
-    ctx: C;
-}) & ([D] extends [undefined] ? {} : {
-    deps: ResolveDeps<D>;
-}) & ([P] extends [undefined] ? {} : {
-    params: ResolveParams<P>;
-}) & ([S] extends [undefined] ? {} : {
-    readStatic: (path: string) => string;
-})) => Promise<HttpResponse>;
-/**
- * Context factory type — conditional on whether params are declared.
- * Without params: `() => C | Promise<C>`
- * With params: `(args: { params: ResolveParams<P> }) => C | Promise<C>`
- */
-type ContextFactory<C, P> = [P] extends [undefined] ? () => C | Promise<C> : (args: {
-    params: ResolveParams<P & {}>;
-}) => C | Promise<C>;
-/**
- * Options for defining an HTTP endpoint
- *
- * @typeParam T - Type of the validated request body (inferred from schema function)
- * @typeParam C - Type of the context/dependencies returned by context function
- * @typeParam D - Type of the deps (from deps declaration)
- * @typeParam P - Type of the params (from params declaration)
- */
-type DefineHttpOptions<T = undefined, C = undefined, D extends Record<string, AnyTableHandler> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined> = HttpConfig & {
-    /**
-     * Decode/validate function for the request body.
-     * Called with the parsed body; should return typed data or throw on validation failure.
-     * When provided, the handler receives validated `data` and invalid requests get a 400 response.
-     *
-     * Works with any validation library:
-     * - Effect: `S.decodeUnknownSync(MySchema)`
-     * - Zod: `(body) => myZodSchema.parse(body)`
-     */
-    schema?: (input: unknown) => T;
-    /**
-     * Error handler called when schema validation or onRequest throws.
-     * Receives the error and request, returns an HttpResponse.
-     * If not provided, defaults to 400 for validation errors and 500 for handler errors.
-     */
-    onError?: (error: unknown, req: HttpRequest) => HttpResponse;
-    /**
-     * Factory function to create context/dependencies for the request handler.
-     * Called once on cold start, result is cached and reused across invocations.
-     * When params are declared, receives resolved params as argument.
-     * Supports both sync and async return values.
-     */
-    context?: ContextFactory<C, P>;
-    /**
-     * Dependencies on other handlers (tables, queues, etc.).
-     * Typed clients are injected into the handler via the `deps` argument.
-     */
-    deps?: D;
-    /**
-     * SSM Parameter Store parameters.
-     * Declare with `param()` helper. Values are fetched and cached at cold start.
-     * Typed values are injected into the handler via the `params` argument.
-     */
-    params?: P;
-    /**
-     * Static file glob patterns to bundle into the Lambda ZIP.
-     * Files are accessible at runtime via the `readStatic` callback argument.
-     */
-    static?: S;
-    /** HTTP request handler function */
-    onRequest: HttpHandlerFn<T, C, D, P, S>;
-};
-/**
- * Internal handler object created by defineHttp
- * @internal
- */
-type HttpHandler<T = undefined, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = {
-    readonly __brand: "effortless-http";
-    readonly config: HttpConfig;
-    readonly schema?: (input: unknown) => T;
-    readonly onError?: (error: unknown, req: HttpRequest) => HttpResponse;
-    readonly context?: (...args: any[]) => C | Promise<C>;
-    readonly deps?: D;
-    readonly params?: P;
-    readonly static?: string[];
-    readonly onRequest: HttpHandlerFn<T, C, D, P, S>;
-};
-/**
- * Define an HTTP endpoint that creates an API Gateway route + Lambda function
- *
- * @typeParam T - Type of the validated request body (inferred from schema function)
- * @typeParam C - Type of the context/dependencies (inferred from context function)
- * @typeParam D - Type of the deps (from deps declaration)
- * @typeParam P - Type of the params (from params declaration)
- * @param options - Configuration, optional schema, optional context factory, and request handler
- * @returns Handler object used by the deployment system
- *
- * @example Basic GET endpoint
- * ```typescript
- * export const hello = defineHttp({
- *   method: "GET",
- *   path: "/hello",
- *   onRequest: async ({ req }) => ({
- *     status: 200,
- *     body: { message: "Hello World!" }
- *   })
- * });
- * ```
- *
- * @example With SSM parameters
- * ```typescript
- * import { param } from "effortless-aws";
- *
- * export const api = defineHttp({
- *   method: "GET",
- *   path: "/orders",
- *   params: {
- *     dbUrl: param("database-url"),
- *   },
- *   context: async ({ params }) => ({
- *     pool: createPool(params.dbUrl),
- *   }),
- *   onRequest: async ({ req, ctx, params }) => ({
- *     status: 200,
- *     body: { dbUrl: params.dbUrl }
- *   })
- * });
- * ```
- */
-declare const defineHttp: <T = undefined, C = undefined, D extends Record<string, AnyTableHandler> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined>(options: DefineHttpOptions<T, C, D, P, S>) => HttpHandler<T, C, D, P, S>;
+declare const defineFifoQueue: <T = unknown, C = undefined, D extends Record<string, AnyTableHandler> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined>(options: DefineFifoQueueOptions<T, C, D, P, S>) => FifoQueueHandler<T, C, D, P, S>;
 
-export { type AppConfig, type AppHandler, type ContentType, type DefineFifoQueueOptions, type DefineHttpOptions, type DefineTableOptions, type EffortlessConfig, type FailedRecord, type FifoQueueBatchFn, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type FifoQueueMessageFn, type HttpConfig, type HttpHandler, type HttpHandlerFn, type HttpMethod, type HttpRequest, type HttpResponse, type KeyType, type LambdaConfig, type LambdaWithPermissions, type LogLevel, type ParamRef, type QueryParams, type ResolveDeps, type ResolveParams, type StaticSiteConfig, type StaticSiteHandler, type StreamView, type TableBatchCompleteFn, type TableBatchFn, type TableClient, type TableConfig, type TableHandler, type TableKey, type TableRecord, type TableRecordFn, defineApp, defineConfig, defineFifoQueue, defineHttp, defineStaticSite, defineTable, param, typed };
+export { type AppConfig, type AppHandler, type ContentType, type DefineFifoQueueOptions, type DefineHttpOptions, type DefineTableOptions, type EffortlessConfig, type FailedRecord, type FifoQueueBatchFn, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type FifoQueueMessageFn, type HttpConfig, type HttpHandler, type HttpHandlerFn, type HttpMethod, type HttpRequest, type HttpResponse, type KeyType, type LambdaConfig, type LambdaWithPermissions, type LogLevel, type ParamRef, type QueryParams, type ResolveConfig, type ResolveDeps$1 as ResolveDeps, type StaticSiteConfig, type StaticSiteHandler, type StreamView, type TableBatchCompleteFn, type TableBatchFn, type TableClient, type TableConfig, type TableHandler, type TableKey, type TableRecord, type TableRecordFn, defineApp, defineConfig, defineFifoQueue, defineHttp, defineStaticSite, defineTable, param, typed };