effortless-aws 0.6.0 → 0.7.0

package/dist/index.d.ts

@@ -47,21 +47,26 @@ type EffortlessConfig = {
     handlers?: string | string[];
     /**
      * Default settings applied to all handlers unless overridden.
+     *
+     * All Lambdas run on ARM64 (Graviton2) architecture — ~20% cheaper than x86_64
+     * with better price-performance for most workloads.
      */
     defaults?: {
         /**
-         * Lambda memory in MB.
+         * Lambda memory in MB. AWS allocates proportional CPU —
+         * 1769 MB gives one full vCPU.
          * @default 256
          */
         memory?: number;
         /**
          * Lambda timeout as a human-readable string.
+         * AWS maximum is 15 minutes.
          * @example "30 seconds", "5 minutes"
          */
         timeout?: string;
         /**
-         * Lambda runtime.
-         * @default "nodejs22.x"
+         * Node.js Lambda runtime version.
+         * @default "nodejs24.x"
          */
         runtime?: string;
     };
@@ -83,9 +88,6 @@ 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 & {});
-
 /**
  * Query parameters for TableClient.query()
  */
@@ -143,54 +145,6 @@ type TableClient<T = Record<string, unknown>> = {
     tableName: string;
 };
 
-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 AnyTableHandler$2 = TableHandler<any, any, any, any, any, any>;
 /** Maps a deps declaration to resolved runtime client types */
 type ResolveDeps$2<D> = {
@@ -212,9 +166,7 @@ type StreamView = "NEW_AND_OLD_IMAGES" | "NEW_IMAGE" | "OLD_IMAGE" | "KEYS_ONLY"
 /**
  * Configuration options extracted from DefineTableOptions (without onRecord/context)
  */
-type TableConfig = {
-    /** Table/handler name. Defaults to export name if not specified */
-    name?: string;
+type TableConfig = LambdaWithPermissions & {
     /** Partition key definition */
     pk: TableKey;
     /** Sort key definition (optional) */
@@ -231,14 +183,6 @@ type TableConfig = {
     batchWindow?: number;
     /** Where to start reading the stream (default: "LATEST") */
     startingPosition?: "LATEST" | "TRIM_HORIZON";
-    /** Lambda memory in MB (default: 256) */
-    memory?: number;
-    /** Lambda timeout in seconds (default: 30) */
-    timeout?: number;
-    /** Additional IAM permissions for the Lambda */
-    permissions?: Permission[];
-    /** Enable observability logging to platform table (default: true) */
-    observe?: boolean;
 };
 /**
  * DynamoDB stream record passed to onRecord callback
@@ -430,290 +374,73 @@ 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>;
 
-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";
-/**
- * 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
+ * Configuration for a Lambda-served static site (API Gateway + Lambda)
  */
-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>;
+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;
 };
 /**
- * Configuration options extracted from DefineHttpOptions (without onRequest callback)
+ * Internal handler object created by defineApp
+ * @internal
  */
-type HttpConfig = {
-    /** Handler name. Defaults to export name if not specified */
-    name?: string;
-    /** HTTP method for the route */
-    method: HttpMethod;
-    /** Route path (e.g., "/api/users", "/api/users/{id}") */
-    path: string;
-    /** Lambda memory in MB (default: 256) */
-    memory?: number;
-    /** Lambda timeout in seconds (default: 30) */
-    timeout?: number;
-    /** Additional IAM permissions for the Lambda */
-    permissions?: Permission[];
-    /** Enable observability logging to platform table (default: true) */
-    observe?: boolean;
+type AppHandler = {
+    readonly __brand: "effortless-app";
+    readonly config: AppConfig;
 };
 /**
- * Handler function type for HTTP endpoints
+ * Deploy a static site via Lambda + API Gateway.
+ * Files are bundled into the Lambda ZIP and served with auto-detected content types.
  *
- * @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$1<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>`
+ * 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",
+ * });
+ * ```
  */
-type ContextFactory$1<C, P> = [P] extends [undefined] ? () => C | Promise<C> : (args: {
-    params: ResolveParams<P & {}>;
-}) => C | Promise<C>;
+declare const defineApp: (options: AppConfig) => AppHandler;
+
 /**
- * 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)
+ * Configuration for a static site handler (S3 + CloudFront)
  */
-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 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$1<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>;
+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 defineHttp
+ * Internal handler object created by defineStaticSite
  * @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>;
+type StaticSiteHandler = {
+    readonly __brand: "effortless-static-site";
+    readonly config: StaticSiteConfig;
 };
 /**
- * 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$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 = {
-    /** Handler name. Defaults to export name if not specified */
-    name?: string;
-    /** 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;
-    /** Lambda memory in MB (default: 256) */
-    memory?: number;
-    /** Lambda timeout in seconds (default: 5) */
-    timeout?: number;
-    /** Enable observability logging to platform table (default: false) */
-    observe?: boolean;
-};
-/**
- * Internal handler object created by defineApp
- * @internal
- */
-type AppHandler = {
-    readonly __brand: "effortless-app";
-    readonly config: 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 config: StaticSiteConfig;
-};
-/**
- * Deploy a static site via S3 + CloudFront CDN.
+ * 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
@@ -737,9 +464,9 @@ type StaticSiteHandler = {
  */
 declare const defineStaticSite: (options: StaticSiteConfig) => StaticSiteHandler;
 
-type AnyTableHandler = TableHandler<any, any, any, any, any, any>;
+type AnyTableHandler$1 = TableHandler<any, any, any, any, any, any>;
 /** Maps a deps declaration to resolved runtime client types */
-type ResolveDeps<D> = {
+type ResolveDeps$1<D> = {
     [K in keyof D]: D[K] extends TableHandler<infer T, any, any, any, any> ? TableClient<T> : never;
 };
 /**
@@ -775,9 +502,7 @@ type FifoQueueMessage<T = unknown> = {
 /**
  * Configuration options for a FIFO queue handler
  */
-type FifoQueueConfig = {
-    /** Handler name. Defaults to export name if not specified */
-    name?: string;
+type FifoQueueConfig = LambdaWithPermissions & {
     /** Number of messages per Lambda invocation (1-10 for FIFO, default: 10) */
     batchSize?: number;
     /** Maximum time in seconds to gather messages before invoking (0-300, default: 0) */
@@ -788,21 +513,13 @@ type FifoQueueConfig = {
     retentionPeriod?: number;
     /** Enable content-based deduplication (default: true) */
     contentBasedDeduplication?: boolean;
-    /** Lambda memory in MB (default: 256) */
-    memory?: number;
-    /** Lambda timeout in seconds (default: 30) */
-    timeout?: number;
-    /** Additional IAM permissions for the Lambda */
-    permissions?: Permission[];
-    /** Enable observability logging to platform table (default: true) */
-    observe?: boolean;
 };
 /**
  * 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: {
+type ContextFactory$1<C, P> = [P] extends [undefined] ? () => C | Promise<C> : (args: {
     params: ResolveParams<P & {}>;
 }) => C | Promise<C>;
 /**
@@ -814,7 +531,7 @@ type FifoQueueMessageFn<T = unknown, C = undefined, D = undefined, P = undefined
 } & ([C] extends [undefined] ? {} : {
     ctx: C;
 }) & ([D] extends [undefined] ? {} : {
-    deps: ResolveDeps<D>;
+    deps: ResolveDeps$1<D>;
 }) & ([P] extends [undefined] ? {} : {
     params: ResolveParams<P>;
 }) & ([S] extends [undefined] ? {} : {
@@ -829,7 +546,7 @@ type FifoQueueBatchFn<T = unknown, C = undefined, D = undefined, P = undefined,
 } & ([C] extends [undefined] ? {} : {
     ctx: C;
 }) & ([D] extends [undefined] ? {} : {
-    deps: ResolveDeps<D>;
+    deps: ResolveDeps$1<D>;
 }) & ([P] extends [undefined] ? {} : {
     params: ResolveParams<P>;
 }) & ([S] extends [undefined] ? {} : {
@@ -852,7 +569,7 @@ type DefineFifoQueueBase<T = unknown, C = undefined, D = undefined, P = undefine
      * Called once on cold start, result is cached and reused across invocations.
      * When params are declared, receives resolved params as argument.
      */
-    context?: ContextFactory<C, P>;
+    context?: ContextFactory$1<C, P>;
     /**
      * Dependencies on other handlers (tables, queues, etc.).
      * Typed clients are injected into the handler via the `deps` argument.
@@ -879,7 +596,7 @@ 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> | 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$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>;
 /**
  * Internal handler object created by defineFifoQueue
  * @internal
@@ -926,8 +643,80 @@ type FifoQueueHandler<T = unknown, C = undefined, D = undefined, P = undefined,
  * });
  * ```
  */
-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>;
+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.
  *
@@ -967,43 +756,203 @@ declare const defineFifoQueue: <T = unknown, C = undefined, D extends Record<str
  */
 declare function typed<T>(): (input: unknown) => T;
 
-type BasePlatformEntity = {
-    pk: string;
-    sk: string;
-    type: string;
-    ttl?: number;
-};
-type ExecutionEntry = {
-    id: string;
-    ts: string;
-    ms: number;
-    in: unknown;
-    out?: unknown;
-};
-type ErrorEntry = {
-    id: string;
-    ts: string;
-    ms: number;
-    in: unknown;
-    err: string;
-};
-type ExecutionLogEntity = BasePlatformEntity & {
-    type: "execution-log";
-    handlerName: string;
-    handlerType: "http" | "table" | "app" | "fifo-queue";
-    executions: ExecutionEntry[];
-    errors: ErrorEntry[];
-};
-type PlatformEntity = ExecutionLogEntity;
-
-type PlatformClient = {
-    appendExecution(handlerName: string, handlerType: "http" | "table" | "app" | "fifo-queue", entry: ExecutionEntry): Promise<void>;
-    appendError(handlerName: string, handlerType: "http" | "table" | "app" | "fifo-queue", entry: ErrorEntry): Promise<void>;
-    get<T extends PlatformEntity>(pk: string, sk: string): Promise<T | undefined>;
-    query<T extends PlatformEntity>(pk: string, skPrefix?: string): Promise<T[]>;
-    put(entity: PlatformEntity): Promise<void>;
-    tableName: string;
+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>;
 };
-declare const createPlatformClient: () => PlatformClient | undefined;
+/**
+ * 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>;
 
-export { type AppConfig, type AppHandler, type BasePlatformEntity, type ContentType, type DefineFifoQueueOptions, type DefineHttpOptions, type DefineTableOptions, type EffortlessConfig, type ErrorEntry, type ExecutionEntry, type ExecutionLogEntity, 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 ParamRef, type PlatformClient, type PlatformEntity, type QueryParams, type ResolveDeps$1 as 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, createPlatformClient, 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 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 };