effortless-aws 0.20.0 → 0.22.0

package/dist/index.d.ts

@@ -53,12 +53,12 @@ type EffortlessConfig = {
      */
     handlers?: string | string[];
     /**
-     * Default settings applied to all handlers unless overridden.
+     * Default Lambda 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?: {
         /**
          * Lambda memory in MB. AWS allocates proportional CPU —
          * 1769 MB gives one full vCPU.
@@ -97,6 +97,22 @@ 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 & {});
+/**
+ * Human-readable duration. Accepts a plain number (seconds) or a string
+ * with a unit suffix: `"30s"`, `"5m"`, `"1h"`, `"2d"`.
+ *
+ * @example
+ * ```typescript
+ * timeout: 30        // 30 seconds
+ * timeout: "30s"     // 30 seconds
+ * timeout: "5m"      // 300 seconds
+ * timeout: "1h"      // 3600 seconds
+ * retentionPeriod: "4d"  // 345600 seconds
+ * ```
+ */
+type Duration = number | `${number}s` | `${number}m` | `${number}h` | `${number}d`;
+/** Convert a Duration to seconds. */
+declare const toSeconds: (d: Duration) => number;
 /** Logging verbosity level for Lambda handlers */
 type LogLevel = "error" | "info" | "debug";
 /**
@@ -105,8 +121,8 @@ type LogLevel = "error" | "info" | "debug";
 type LambdaConfig = {
     /** Lambda memory in MB (default: 256) */
     memory?: number;
-    /** Lambda timeout in seconds (default: 30) */
-    timeout?: number;
+    /** Lambda timeout (default: 30s). Accepts seconds or duration string: `"30s"`, `"5m"` */
+    timeout?: Duration;
     /** Logging verbosity: "error" (errors only), "info" (+ execution summary), "debug" (+ input/output). Default: "info" */
     logLevel?: LogLevel;
 };
@@ -382,6 +398,31 @@ type HttpResponse = {
     contentType?: ContentType;
     /** Response headers (use for custom content-types not covered by contentType) */
     headers?: Record<string, string>;
+    /**
+     * Set to `true` to return binary data.
+     * When enabled, `body` must be a base64-encoded string and the response
+     * will include `isBase64Encoded: true` so Lambda Function URLs / API Gateway
+     * decode it back to binary for the client.
+     */
+    binary?: boolean;
+};
+/** Response helpers for defineApi handlers */
+declare const result: {
+    /** Return a JSON response */
+    json: (body: unknown, status?: number) => HttpResponse;
+    /** Return a binary response. Accepts a Buffer and converts to base64 automatically. */
+    binary: (body: Buffer, contentType: string, headers?: Record<string, string>) => HttpResponse;
+};
+/** Stream helper injected into route args when `stream: true` is set on defineApi */
+type ResponseStream = {
+    /** Write a raw string chunk to the response stream */
+    write(chunk: string): void;
+    /** End the response stream */
+    end(): void;
+    /** Switch to SSE mode: sets Content-Type to text/event-stream */
+    sse(): void;
+    /** Write an SSE event: `data: JSON.stringify(data)\n\n` */
+    event(data: unknown): void;
 };
 /** Service for reading static files bundled into the Lambda ZIP */
 type StaticFiles = {
@@ -422,7 +463,9 @@ type BucketClient = {
 /**
  * Configuration options for defineBucket.
  */
-type BucketConfig = LambdaWithPermissions & {
+type BucketConfig = {
+    /** Lambda function settings (memory, timeout, permissions, etc.) */
+    lambda?: LambdaWithPermissions;
     /** S3 key prefix filter for event notifications (e.g., "uploads/") */
     prefix?: string;
     /** S3 key suffix filter for event notifications (e.g., ".jpg") */
@@ -630,6 +673,189 @@ type MailerHandler = {
  */
 declare const defineMailer: (options: MailerConfig) => MailerHandler;
 
+/**
+ * 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;
+    /** Raw unparsed message body string */
+    rawBody: string;
+    /** Message group ID (FIFO ordering key) */
+    messageGroupId: string;
+    /** Message deduplication ID */
+    messageDeduplicationId?: string;
+    /** SQS message attributes */
+    messageAttributes: Record<string, {
+        dataType?: string;
+        stringValue?: string;
+    }>;
+    /** Approximate first receive timestamp */
+    approximateFirstReceiveTimestamp?: string;
+    /** Approximate receive count */
+    approximateReceiveCount?: string;
+    /** Sent timestamp */
+    sentTimestamp?: string;
+};
+/**
+ * Configuration options for a FIFO queue handler
+ */
+type FifoQueueConfig = {
+    /** Lambda function settings (memory, timeout, permissions, etc.) */
+    lambda?: LambdaWithPermissions;
+    /** Number of messages per Lambda invocation (1-10 for FIFO, default: 10) */
+    batchSize?: number;
+    /** Maximum time to gather messages before invoking (default: 0). Accepts `"5s"`, `"1m"`, etc. */
+    batchWindow?: Duration;
+    /** Visibility timeout (default: max of timeout or 30s). Accepts `"30s"`, `"5m"`, etc. */
+    visibilityTimeout?: Duration;
+    /** Message retention period (default: `"4d"`). Accepts `"1h"`, `"7d"`, etc. */
+    retentionPeriod?: Duration;
+    /** Delivery delay for all messages in the queue (default: 0). Accepts `"30s"`, `"5m"`, etc. */
+    delay?: Duration;
+    /** Enable content-based deduplication (default: true) */
+    contentBasedDeduplication?: boolean;
+};
+/**
+ * Setup factory type — always receives an args object.
+ * Args include `deps` and/or `config` when declared (empty `{}` otherwise).
+ */
+type SetupFactory$2<C, D, P, S extends string[] | undefined = undefined> = (args: ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P & {}>;
+}) & ([S] extends [undefined] ? {} : {
+    files: StaticFiles;
+})) => C | Promise<C>;
+/**
+ * Per-message handler function.
+ * Called once per message in the batch. Failures are reported individually.
+ */
+type FifoQueueMessageFn<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = (args: {
+    message: FifoQueueMessage<T>;
+} & ([C] extends [undefined] ? {} : {
+    ctx: C;
+}) & ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P>;
+}) & ([S] extends [undefined] ? {} : {
+    files: StaticFiles;
+})) => Promise<void>;
+/**
+ * Batch handler function.
+ * Called once with all messages in the batch.
+ */
+type FifoQueueBatchFn<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = (args: {
+    messages: FifoQueueMessage<T>[];
+} & ([C] extends [undefined] ? {} : {
+    ctx: C;
+}) & ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P>;
+}) & ([S] extends [undefined] ? {} : {
+    files: StaticFiles;
+})) => Promise<void>;
+/** Base options shared by all defineFifoQueue variants */
+type DefineFifoQueueBase<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = FifoQueueConfig & {
+    /**
+     * Decode/validate function for the message body.
+     * Called with the JSON-parsed body; should return typed data or throw on validation failure.
+     */
+    schema?: (input: unknown) => T;
+    /**
+     * Error handler called when onMessage or onBatch throws.
+     * If not provided, defaults to `console.error`.
+     */
+    onError?: (error: unknown) => void;
+    /**
+     * Factory function to initialize shared state for the handler.
+     * Called once on cold start, result is cached and reused across invocations.
+     * When deps/params are declared, receives them as argument.
+     */
+    setup?: SetupFactory$2<C, D, P, S>;
+    /**
+     * 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.
+     */
+    config?: P;
+    /**
+     * Static file glob patterns to bundle into the Lambda ZIP.
+     * Files are accessible at runtime via the `files` callback argument.
+     */
+    static?: S;
+};
+/** Per-message processing */
+type DefineFifoQueueWithOnMessage<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = DefineFifoQueueBase<T, C, D, P, S> & {
+    onMessage: FifoQueueMessageFn<T, C, D, P, S>;
+    onBatch?: never;
+};
+/** Batch processing: all messages at once */
+type DefineFifoQueueWithOnBatch<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = DefineFifoQueueBase<T, C, D, P, S> & {
+    onBatch: FifoQueueBatchFn<T, C, D, P, S>;
+    onMessage?: never;
+};
+type DefineFifoQueueOptions<T = unknown, C = undefined, D extends Record<string, AnyDepHandler> | 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 __spec: FifoQueueConfig;
+    readonly schema?: (input: unknown) => T;
+    readonly onError?: (error: unknown) => void;
+    readonly setup?: (...args: any[]) => C | Promise<C>;
+    readonly deps?: D;
+    readonly config?: P;
+    readonly static?: string[];
+    readonly onMessage?: FifoQueueMessageFn<T, C, D, P, S>;
+    readonly onBatch?: FifoQueueBatchFn<T, C, D, P, S>;
+};
+/**
+ * Define a FIFO SQS queue with a Lambda message handler
+ *
+ * Creates:
+ * - SQS FIFO queue (with `.fifo` suffix)
+ * - Lambda function triggered by the queue
+ * - Event source mapping with partial batch failure support
+ *
+ * @example Per-message processing
+ * ```typescript
+ * type OrderEvent = { orderId: string; action: string };
+ *
+ * export const orderQueue = defineFifoQueue<OrderEvent>({
+ *   onMessage: async ({ message }) => {
+ *     console.log("Processing order:", message.body.orderId);
+ *   }
+ * });
+ * ```
+ *
+ * @example Batch processing with schema
+ * ```typescript
+ * export const notifications = defineFifoQueue({
+ *   schema: (input) => NotificationSchema.parse(input),
+ *   batchSize: 5,
+ *   onBatch: async ({ messages }) => {
+ *     await sendAll(messages.map(m => m.body));
+ *   }
+ * });
+ * ```
+ */
+declare const defineFifoQueue: <T = unknown, C = undefined, D extends Record<string, AnyDepHandler> | 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>;
+
 /**
  * Options for sending an email via EmailClient.send()
  */
@@ -659,14 +885,45 @@ type EmailClient = {
     send(opts: SendEmailOptions): Promise<void>;
 };
 
+/**
+ * Input for QueueClient.send()
+ */
+type SendMessageInput<T> = {
+    /** Message body (serialized as JSON) */
+    body: T;
+    /** Message group ID (FIFO ordering key) */
+    groupId: string;
+    /** Message deduplication ID. Required if content-based deduplication is disabled. */
+    deduplicationId?: string;
+    /** Optional message attributes */
+    messageAttributes?: Record<string, {
+        dataType: string;
+        stringValue: string;
+    }>;
+};
+/**
+ * Typed SQS FIFO queue client for sending messages.
+ *
+ * @typeParam T - Type of the message body (serialized as JSON)
+ */
+type QueueClient<T = unknown> = {
+    /** Send a single message to the FIFO queue */
+    send(input: SendMessageInput<T>): Promise<void>;
+    /** Send a batch of messages (up to 10) to the FIFO queue */
+    sendBatch(messages: SendMessageInput<T>[]): Promise<void>;
+    /** The SQS queue name (without .fifo suffix) */
+    queueName: string;
+};
+
 type AnyTableHandler = TableHandler<any, any, any, any, any, any>;
 type AnyBucketHandler = BucketHandler<any, any, any, any>;
 type AnyMailerHandler = MailerHandler;
+type AnyFifoQueueHandler = FifoQueueHandler<any, any, any, any, any>;
 /** Dep value types supported by the deps declaration */
-type AnyDepHandler = AnyTableHandler | AnyBucketHandler | AnyMailerHandler;
+type AnyDepHandler = AnyTableHandler | AnyBucketHandler | AnyMailerHandler | AnyFifoQueueHandler;
 /** 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> : D[K] extends BucketHandler<any, any, any, any> ? BucketClient : D[K] extends MailerHandler ? EmailClient : never;
+    [K in keyof D]: D[K] extends TableHandler<infer T, any, any, any, any> ? TableClient<T> : D[K] extends BucketHandler<any, any, any, any> ? BucketClient : D[K] extends MailerHandler ? EmailClient : D[K] extends FifoQueueHandler<infer T, any, any, any, any> ? QueueClient<T> : never;
 };
 
 /** DynamoDB Streams view type - determines what data is captured in stream records */
@@ -677,15 +934,17 @@ type StreamView = "NEW_AND_OLD_IMAGES" | "NEW_IMAGE" | "OLD_IMAGE" | "KEYS_ONLY"
  * Tables always use `pk (S)` + `sk (S)` keys, `tag (S)` discriminator,
  * `data (M)` for domain fields, and `ttl (N)` for optional expiration.
  */
-type TableConfig = LambdaWithPermissions & {
+type TableConfig = {
+    /** Lambda function settings (memory, timeout, permissions, etc.) */
+    lambda?: LambdaWithPermissions;
     /** DynamoDB billing mode (default: "PAY_PER_REQUEST") */
     billingMode?: "PAY_PER_REQUEST" | "PROVISIONED";
     /** Stream view type - what data to include in stream records (default: "NEW_AND_OLD_IMAGES") */
     streamView?: StreamView;
     /** Number of records to process in each Lambda invocation (1-10000, default: 100) */
     batchSize?: number;
-    /** Maximum time in seconds to gather records before invoking (0-300, default: 2) */
-    batchWindow?: number;
+    /** Maximum time to gather records before invoking (default: `"2s"`). Accepts `"5s"`, `"1m"`, etc. */
+    batchWindow?: Duration;
     /** Where to start reading the stream (default: "LATEST") */
     startingPosition?: "LATEST" | "TRIM_HORIZON";
     /**
@@ -744,7 +1003,7 @@ type FailedRecord<T = Record<string, unknown>> = {
  * Always receives `table: TableClient<T>` (self-client for the handler's own table).
  * Also receives `deps` and/or `config` when declared.
  */
-type SetupFactory$2<C, T, D, P, S extends string[] | undefined = undefined> = (args: {
+type SetupFactory$1<C, T, D, P, S extends string[] | undefined = undefined> = (args: {
     table: TableClient<T>;
 } & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
@@ -820,7 +1079,7 @@ type DefineTableBase<T = Record<string, unknown>, C = undefined, D = undefined,
      * When deps/params are declared, receives them as argument.
      * Supports both sync and async return values.
      */
-    setup?: SetupFactory$2<C, T, D, P, S>;
+    setup?: SetupFactory$1<C, T, D, P, S>;
     /**
      * Dependencies on other handlers (tables, queues, etc.).
      * Typed clients are injected into the handler via the `deps` argument.
@@ -907,7 +1166,9 @@ declare const defineTable: <T = Record<string, unknown>, C = undefined, R = void
  * Configuration for deploying an SSR framework (Nuxt, Astro, etc.)
  * via CloudFront + S3 (static assets) + Lambda Function URL (server-side rendering).
  */
-type AppConfig = LambdaWithPermissions & {
+type AppConfig = {
+    /** Lambda function settings (memory, timeout, permissions, etc.) */
+    lambda?: LambdaWithPermissions;
     /** Directory containing the Lambda server handler (e.g., ".output/server").
      *  Must contain an `index.mjs` (or `index.js`) that exports a `handler` function. */
     server: string;
@@ -952,7 +1213,7 @@ type AppHandler = {
  *   build: "nuxt build",
  *   server: ".output/server",
  *   assets: ".output/public",
- *   memory: 1024,
+ *   lambda: { memory: 1024 },
  * });
  * ```
  */
@@ -1065,187 +1326,8 @@ type StaticSiteHandler = {
  */
 declare const defineStaticSite: (options: StaticSiteConfig) => StaticSiteHandler;
 
-/**
- * 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;
-    /** Raw unparsed message body string */
-    rawBody: string;
-    /** Message group ID (FIFO ordering key) */
-    messageGroupId: string;
-    /** Message deduplication ID */
-    messageDeduplicationId?: string;
-    /** SQS message attributes */
-    messageAttributes: Record<string, {
-        dataType?: string;
-        stringValue?: string;
-    }>;
-    /** Approximate first receive timestamp */
-    approximateFirstReceiveTimestamp?: string;
-    /** Approximate receive count */
-    approximateReceiveCount?: string;
-    /** Sent timestamp */
-    sentTimestamp?: string;
-};
-/**
- * Configuration options for a FIFO queue handler
- */
-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) */
-    batchWindow?: number;
-    /** Visibility timeout in seconds (default: max of timeout or 30) */
-    visibilityTimeout?: number;
-    /** Message retention period in seconds (60-1209600, default: 345600 = 4 days) */
-    retentionPeriod?: number;
-    /** Enable content-based deduplication (default: true) */
-    contentBasedDeduplication?: boolean;
-};
-/**
- * Setup factory type — always receives an args object.
- * Args include `deps` and/or `config` when declared (empty `{}` otherwise).
- */
-type SetupFactory$1<C, D, P, S extends string[] | undefined = undefined> = (args: ([D] extends [undefined] ? {} : {
-    deps: ResolveDeps<D>;
-}) & ([P] extends [undefined] ? {} : {
-    config: ResolveConfig<P & {}>;
-}) & ([S] extends [undefined] ? {} : {
-    files: StaticFiles;
-})) => C | Promise<C>;
-/**
- * Per-message handler function.
- * Called once per message in the batch. Failures are reported individually.
- */
-type FifoQueueMessageFn<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = (args: {
-    message: FifoQueueMessage<T>;
-} & ([C] extends [undefined] ? {} : {
-    ctx: C;
-}) & ([D] extends [undefined] ? {} : {
-    deps: ResolveDeps<D>;
-}) & ([P] extends [undefined] ? {} : {
-    config: ResolveConfig<P>;
-}) & ([S] extends [undefined] ? {} : {
-    files: StaticFiles;
-})) => Promise<void>;
-/**
- * Batch handler function.
- * Called once with all messages in the batch.
- */
-type FifoQueueBatchFn<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = (args: {
-    messages: FifoQueueMessage<T>[];
-} & ([C] extends [undefined] ? {} : {
-    ctx: C;
-}) & ([D] extends [undefined] ? {} : {
-    deps: ResolveDeps<D>;
-}) & ([P] extends [undefined] ? {} : {
-    config: ResolveConfig<P>;
-}) & ([S] extends [undefined] ? {} : {
-    files: StaticFiles;
-})) => Promise<void>;
-/** Base options shared by all defineFifoQueue variants */
-type DefineFifoQueueBase<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = FifoQueueConfig & {
-    /**
-     * Decode/validate function for the message body.
-     * Called with the JSON-parsed body; should return typed data or throw on validation failure.
-     */
-    schema?: (input: unknown) => T;
-    /**
-     * Error handler called when onMessage or onBatch throws.
-     * If not provided, defaults to `console.error`.
-     */
-    onError?: (error: unknown) => void;
-    /**
-     * Factory function to initialize shared state for the handler.
-     * Called once on cold start, result is cached and reused across invocations.
-     * When deps/params are declared, receives them as argument.
-     */
-    setup?: SetupFactory$1<C, D, P, S>;
-    /**
-     * 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.
-     */
-    config?: P;
-    /**
-     * Static file glob patterns to bundle into the Lambda ZIP.
-     * Files are accessible at runtime via the `files` callback argument.
-     */
-    static?: S;
-};
-/** Per-message processing */
-type DefineFifoQueueWithOnMessage<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = DefineFifoQueueBase<T, C, D, P, S> & {
-    onMessage: FifoQueueMessageFn<T, C, D, P, S>;
-    onBatch?: never;
-};
-/** Batch processing: all messages at once */
-type DefineFifoQueueWithOnBatch<T = unknown, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = DefineFifoQueueBase<T, C, D, P, S> & {
-    onBatch: FifoQueueBatchFn<T, C, D, P, S>;
-    onMessage?: never;
-};
-type DefineFifoQueueOptions<T = unknown, C = undefined, D extends Record<string, AnyDepHandler> | 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 __spec: FifoQueueConfig;
-    readonly schema?: (input: unknown) => T;
-    readonly onError?: (error: unknown) => void;
-    readonly setup?: (...args: any[]) => C | Promise<C>;
-    readonly deps?: D;
-    readonly config?: P;
-    readonly static?: string[];
-    readonly onMessage?: FifoQueueMessageFn<T, C, D, P, S>;
-    readonly onBatch?: FifoQueueBatchFn<T, C, D, P, S>;
-};
-/**
- * Define a FIFO SQS queue with a Lambda message handler
- *
- * Creates:
- * - SQS FIFO queue (with `.fifo` suffix)
- * - Lambda function triggered by the queue
- * - Event source mapping with partial batch failure support
- *
- * @example Per-message processing
- * ```typescript
- * type OrderEvent = { orderId: string; action: string };
- *
- * export const orderQueue = defineFifoQueue<OrderEvent>({
- *   onMessage: async ({ message }) => {
- *     console.log("Processing order:", message.body.orderId);
- *   }
- * });
- * ```
- *
- * @example Batch processing with schema
- * ```typescript
- * export const notifications = defineFifoQueue({
- *   schema: (input) => NotificationSchema.parse(input),
- *   batchSize: 5,
- *   onBatch: async ({ messages }) => {
- *     await sendAll(messages.map(m => m.body));
- *   }
- * });
- * ```
- */
-declare const defineFifoQueue: <T = unknown, C = undefined, D extends Record<string, AnyDepHandler> | 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>;
-
 /** GET route handler — no schema, no data */
-type ApiGetHandlerFn<C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = (args: {
+type ApiGetHandlerFn<C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined, ST extends boolean | undefined = undefined> = (args: {
     req: HttpRequest;
 } & ([C] extends [undefined] ? {} : {
     ctx: C;
@@ -1255,9 +1337,11 @@ type ApiGetHandlerFn<C = undefined, D = undefined, P = undefined, S extends stri
     config: ResolveConfig<P>;
 }) & ([S] extends [undefined] ? {} : {
     files: StaticFiles;
-})) => Promise<HttpResponse> | HttpResponse;
+}) & ([ST] extends [true] ? {
+    stream: ResponseStream;
+} : {})) => Promise<HttpResponse | void> | HttpResponse | void;
 /** POST handler — with typed data from schema */
-type ApiPostHandlerFn<T = undefined, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = (args: {
+type ApiPostHandlerFn<T = undefined, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined, ST extends boolean | undefined = undefined> = (args: {
     req: HttpRequest;
 } & ([T] extends [undefined] ? {} : {
     data: T;
@@ -1269,7 +1353,9 @@ type ApiPostHandlerFn<T = undefined, C = undefined, D = undefined, P = undefined
     config: ResolveConfig<P>;
 }) & ([S] extends [undefined] ? {} : {
     files: StaticFiles;
-})) => Promise<HttpResponse> | HttpResponse;
+}) & ([ST] extends [true] ? {
+    stream: ResponseStream;
+} : {})) => Promise<HttpResponse | void> | HttpResponse | void;
 /** Setup factory — receives deps/config/files when declared */
 type SetupFactory<C, D, P, S extends string[] | undefined = undefined> = (args: ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
@@ -1279,9 +1365,13 @@ type SetupFactory<C, D, P, S extends string[] | undefined = undefined> = (args:
     files: StaticFiles;
 })) => C | Promise<C>;
 /** Static config extracted by AST (no runtime callbacks) */
-type ApiConfig = LambdaWithPermissions & {
+type ApiConfig = {
+    /** Lambda function settings (memory, timeout, permissions, etc.) */
+    lambda?: LambdaWithPermissions;
     /** Base path prefix for all routes (e.g., "/api") */
     basePath: string;
+    /** Enable response streaming. When true, the Lambda Function URL uses RESPONSE_STREAM invoke mode. */
+    stream?: boolean;
 };
 /**
  * Options for defining a CQRS-style API endpoint.
@@ -1289,9 +1379,13 @@ type ApiConfig = LambdaWithPermissions & {
  * - `get` routes handle queries (path-based routing, no body)
  * - `post` handles commands (single entry point, discriminated union via `schema`)
  */
-type DefineApiOptions<T = undefined, C = undefined, D extends Record<string, AnyDepHandler> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined> = LambdaWithPermissions & {
+type DefineApiOptions<T = undefined, C = undefined, D extends Record<string, AnyDepHandler> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined, ST extends boolean | undefined = undefined> = {
+    /** Lambda function settings (memory, timeout, permissions, etc.) */
+    lambda?: LambdaWithPermissions;
     /** Base path prefix for all routes (e.g., "/api") */
     basePath: string;
+    /** Enable response streaming. When true, routes receive a `stream` arg for SSE. Routes can still return HttpResponse normally. */
+    stream?: ST;
     /**
      * Factory function to initialize shared state.
      * Called once on cold start, result is cached and reused across invocations.
@@ -1306,7 +1400,7 @@ type DefineApiOptions<T = undefined, C = undefined, D extends Record<string, Any
     /** Error handler called when schema validation or handler throws */
     onError?: (error: unknown, req: HttpRequest) => HttpResponse;
     /** GET routes — query handlers keyed by relative path (e.g., "/users/{id}") */
-    get?: Record<string, ApiGetHandlerFn<C, D, P, S>>;
+    get?: Record<string, ApiGetHandlerFn<C, D, P, S, ST>>;
     /**
      * Schema for POST body validation. Use with discriminated unions:
      * ```typescript
@@ -1316,10 +1410,10 @@ type DefineApiOptions<T = undefined, C = undefined, D extends Record<string, Any
      */
     schema?: (input: unknown) => T;
     /** POST handler — single entry point for commands */
-    post?: ApiPostHandlerFn<T, C, D, P, S>;
+    post?: ApiPostHandlerFn<T, C, D, P, S, ST>;
 };
 /** Internal handler object created by defineApi */
-type ApiHandler<T = undefined, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = {
+type ApiHandler<T = undefined, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined, ST extends boolean | undefined = undefined> = {
     readonly __brand: "effortless-api";
     readonly __spec: ApiConfig;
     readonly schema?: (input: unknown) => T;
@@ -1328,8 +1422,8 @@ type ApiHandler<T = undefined, C = undefined, D = undefined, P = undefined, S ex
     readonly deps?: D;
     readonly config?: P;
     readonly static?: string[];
-    readonly get?: Record<string, ApiGetHandlerFn<C, D, P, S>>;
-    readonly post?: ApiPostHandlerFn<T, C, D, P, S>;
+    readonly get?: Record<string, ApiGetHandlerFn<C, D, P, S, ST>>;
+    readonly post?: ApiPostHandlerFn<T, C, D, P, S, ST>;
 };
 /**
  * Define a CQRS-style API with typed GET routes and POST commands.
@@ -1365,6 +1459,6 @@ type ApiHandler<T = undefined, C = undefined, D = undefined, P = undefined, S ex
  * })
  * ```
  */
-declare const defineApi: <T = undefined, C = undefined, D extends Record<string, AnyDepHandler> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined>(options: DefineApiOptions<T, C, D, P, S>) => ApiHandler<T, C, D, P, S>;
+declare const defineApi: <T = undefined, C = undefined, D extends Record<string, AnyDepHandler> | undefined = undefined, P extends Record<string, AnyParamRef> | undefined = undefined, S extends string[] | undefined = undefined, ST extends boolean | undefined = undefined>(options: DefineApiOptions<T, C, D, P, S, ST>) => ApiHandler<T, C, D, P, S, ST>;
 
-export { type AnyParamRef, type ApiConfig, type ApiGetHandlerFn, type ApiHandler, type ApiPostHandlerFn, type AppConfig, type AppHandler, type BucketClient, type BucketConfig, type BucketEvent, type BucketHandler, type BucketObjectCreatedFn, type BucketObjectRemovedFn, type ContentType, type DefineApiOptions, type DefineBucketOptions, type DefineFifoQueueOptions, type DefineTableOptions, type EffortlessConfig, type EmailClient, type FailedRecord, type FifoQueueBatchFn, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type FifoQueueMessageFn, type HttpMethod, type HttpRequest, type HttpResponse, type LambdaConfig, type LambdaWithPermissions, type LogLevel, type MailerConfig, type MailerHandler, type MiddlewareDeny, type MiddlewareHandler, type MiddlewareRedirect, type MiddlewareRequest, type MiddlewareResult, type ParamRef, type Permission, type PutInput, type PutOptions, type QueryByTagParams, type QueryParams, type ResolveConfig, type ResolveDeps, type SendEmailOptions, type SkCondition, type StaticFiles, type StaticSiteConfig, type StaticSiteHandler, type StaticSiteSeo, type StreamView, type TableBatchCompleteFn, type TableBatchFn, type TableClient, type TableConfig, type TableHandler, type TableItem, type TableKey, type TableRecord, type TableRecordFn, type UpdateActions, defineApi, defineApp, defineBucket, defineConfig, defineFifoQueue, defineMailer, defineStaticSite, defineTable, param, typed };
+export { type AnyParamRef, type ApiConfig, type ApiGetHandlerFn, type ApiHandler, type ApiPostHandlerFn, type AppConfig, type AppHandler, type BucketClient, type BucketConfig, type BucketEvent, type BucketHandler, type BucketObjectCreatedFn, type BucketObjectRemovedFn, type ContentType, type DefineApiOptions, type DefineBucketOptions, type DefineFifoQueueOptions, type DefineTableOptions, type Duration, type EffortlessConfig, type EmailClient, type FailedRecord, type FifoQueueBatchFn, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type FifoQueueMessageFn, type HttpMethod, type HttpRequest, type HttpResponse, type LambdaConfig, type LambdaWithPermissions, type LogLevel, type MailerConfig, type MailerHandler, type MiddlewareDeny, type MiddlewareHandler, type MiddlewareRedirect, type MiddlewareRequest, type MiddlewareResult, type ParamRef, type Permission, type PutInput, type PutOptions, type QueryByTagParams, type QueryParams, type QueueClient, type ResolveConfig, type ResolveDeps, type ResponseStream, type SendEmailOptions, type SendMessageInput, type SkCondition, type StaticFiles, type StaticSiteConfig, type StaticSiteHandler, type StaticSiteSeo, type StreamView, type TableBatchCompleteFn, type TableBatchFn, type TableClient, type TableConfig, type TableHandler, type TableItem, type TableKey, type TableRecord, type TableRecordFn, type UpdateActions, defineApi, defineApp, defineBucket, defineConfig, defineFifoQueue, defineMailer, defineStaticSite, defineTable, param, result, toSeconds, typed };