effortless-aws 0.29.0 → 0.31.0

package/dist/index.d.ts

@@ -1,17 +1,7 @@
 /**
  * Configuration for an Effortless project.
  *
- * @example
- * ```typescript
- * // effortless.config.ts
- * import { defineConfig } from "effortless-aws";
- *
- * export default defineConfig({
- *   name: "my-service",
- *   region: "eu-central-1",
- *   handlers: "src",
- * });
- * ```
+ * @see {@link https://effortless-aws.website/configuration | Configuration guide}
  */
 type EffortlessConfig = {
     /**
@@ -78,21 +68,7 @@ type EffortlessConfig = {
         runtime?: string;
     };
 };
-/**
- * Helper function for type-safe configuration.
- * Returns the config object as-is, but provides TypeScript autocompletion.
- *
- * @example
- * ```typescript
- * import { defineConfig } from "effortless-aws";
- *
- * export default defineConfig({
- *   name: "my-service",
- *   region: "eu-central-1",
- *   handlers: "src",
- * });
- * ```
- */
+/** Helper function for type-safe configuration with TypeScript autocompletion. */
 declare const defineConfig: (config: EffortlessConfig) => EffortlessConfig;
 
 /** Generator spec for auto-creating secrets at deploy time. */
@@ -136,6 +112,20 @@ type LambdaWithPermissions = LambdaConfig & {
     /** Additional IAM permissions for the Lambda */
     permissions?: Permission[];
 };
+/**
+ * Lambda configuration passed as argument to `.setup()`.
+ * Common across all handler types that create a Lambda function.
+ */
+type LambdaOptions = {
+    /** Lambda memory in MB (default: 256) */
+    memory?: number;
+    /** Lambda timeout (default: 30s). Accepts seconds or duration string: `"30s"`, `"5m"` */
+    timeout?: Duration;
+    /** Additional IAM permissions for the Lambda */
+    permissions?: Permission[];
+    /** Logging verbosity: "error" (errors only), "info" (+ execution summary), "debug" (+ input/output). Default: "info" */
+    logLevel?: LogLevel;
+};
 type AnySecretRef = SecretRef<any>;
 /**
  * Reference to an SSM Parameter Store secret.
@@ -236,127 +226,6 @@ type PutInput<T> = {
     data: T;
     ttl?: number;
 };
-/**
- * Create a schema function that casts input to T without runtime validation.
- * Use when you need T inference alongside other generics (deps, config).
- * For handlers without deps/config, prefer `defineTable<Order>({...})`.
- * For untrusted input, prefer a real parser (Zod, Effect Schema).
- *
- * @example
- * ```typescript
- * export const orders = defineTable({
- *   schema: unsafeAs<Order>(),
- *   deps: () => ({ notifications }),
- *   onRecord: async ({ record, deps }) => { ... }
- * });
- * ```
- */
-declare function unsafeAs<T>(): (input: unknown) => T;
-
-/**
- * Sort key condition for TableClient.query()
- */
-type SkCondition = string | {
-    begins_with: string;
-} | {
-    gt: string;
-} | {
-    gte: string;
-} | {
-    lt: string;
-} | {
-    lte: string;
-} | {
-    between: [string, string];
-};
-/**
- * Query parameters for TableClient.query()
- */
-type QueryParams = {
-    /** Partition key value */
-    pk: string;
-    /** Optional sort key condition */
-    sk?: SkCondition;
-    /** Maximum number of items to return */
-    limit?: number;
-    /** Sort order (true = ascending, false = descending) */
-    scanIndexForward?: boolean;
-};
-/**
- * Query parameters for TableClient.queryByTag() — cross-partition query via GSI.
- * Uses the built-in `tag-pk-index` GSI (tag as partition key, pk as sort key).
- */
-type QueryByTagParams = {
-    /** Tag value (GSI partition key) — the entity type discriminant */
-    tag: string;
-    /** Optional pk condition (GSI sort key) */
-    pk?: SkCondition;
-    /** Maximum number of items to return */
-    limit?: number;
-    /** Sort order (true = ascending, false = descending) */
-    scanIndexForward?: boolean;
-};
-/** Extract keys of T whose values are arrays */
-type ArrayKeys<T> = {
-    [K in keyof T]: T[K] extends unknown[] ? K : never;
-}[keyof T];
-/** Extract keys of T whose values are numbers */
-type NumberKeys<T> = {
-    [K in keyof T]: T[K] extends number ? K : never;
-}[keyof T];
-/**
- * Update actions for TableClient.update()
- *
- * `set`, `append`, and `remove` target fields inside the `data` attribute.
- * Effortless auto-prefixes `data.` in the DynamoDB expression.
- *
- * @typeParam T - Type of the domain data (the `data` attribute)
- */
-type UpdateActions<T> = {
-    /** Set domain data fields (inside `data` attribute) */
-    set?: Partial<T>;
-    /** Atomically increment/decrement numeric fields inside `data` (use negative values to decrement) */
-    increment?: Pick<Partial<T>, NumberKeys<T>>;
-    /** Append elements to list fields inside `data` (creates the list if it doesn't exist) */
-    append?: Pick<Partial<T>, ArrayKeys<T>>;
-    /** Remove fields from `data` */
-    remove?: (keyof T)[];
-    /** Update the top-level `tag` attribute */
-    tag?: string;
-    /** Update TTL (set number or null to remove) */
-    ttl?: number | null;
-};
-/**
- * Typed DynamoDB table client for single-table design.
- *
- * All items follow the `{ pk, sk, tag, data, ttl? }` structure.
- * `T` is the domain data type stored in the `data` attribute.
- *
- * @typeParam T - Type of the domain data
- */
-/**
- * Options for `put()` operation.
- */
-type PutOptions = {
-    /** When true, the put fails if an item with the same pk+sk already exists. */
-    ifNotExists?: boolean;
-};
-type TableClient<T = Record<string, unknown>> = {
-    /** Put an item. Tag is auto-extracted from `data[tagField]`. Use `ifNotExists` to prevent overwrites. */
-    put(item: PutInput<T>, options?: PutOptions): Promise<void>;
-    /** Get an item by pk + sk */
-    get(key: TableKey): Promise<TableItem<T> | undefined>;
-    /** Delete an item by pk + sk */
-    delete(key: TableKey): Promise<void>;
-    /** Update domain data fields without reading the full item */
-    update(key: TableKey, actions: UpdateActions<T>): Promise<void>;
-    /** Query by partition key with optional sort key condition */
-    query(params: QueryParams): Promise<TableItem<T>[]>;
-    /** Query by tag across all partitions via GSI (tag-pk-index). */
-    queryByTag(params: QueryByTagParams): Promise<TableItem<T>[]>;
-    /** The underlying DynamoDB table name */
-    tableName: string;
-};
 
 /** HTTP methods supported by Lambda Function URLs */
 type HttpMethod$1 = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "ANY";
@@ -411,13 +280,6 @@ type HttpResponse = {
      */
     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 */
@@ -470,7 +332,12 @@ type BucketClient = {
  */
 type BucketConfig = {
     /** Lambda function settings (memory, timeout, permissions, etc.) */
-    lambda?: LambdaWithPermissions;
+    lambda?: {
+        memory?: number;
+        timeout?: Duration;
+        logLevel?: LogLevel;
+        permissions?: Permission[];
+    };
     /** S3 key prefix filter for event notifications (e.g., "uploads/") */
     prefix?: string;
     /** S3 key suffix filter for event notifications (e.g., ".jpg") */
@@ -494,79 +361,29 @@ type BucketEvent = {
     bucketName: string;
 };
 /** Spread ctx into callback args (empty when no setup) */
-type SpreadCtx$3<C> = [C] extends [undefined] ? {} : C & {};
+type SpreadCtx$4<C> = [C] extends [undefined] ? {} : C & {};
+/** Setup factory — receives bucket/deps/config/files based on what was declared */
+type SetupArgs$4<D, P, HasFiles extends boolean> = {
+    bucket: BucketClient;
+} & ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P & {}>;
+}) & (HasFiles extends true ? {
+    files: StaticFiles;
+} : {});
 /**
  * Callback function type for S3 ObjectCreated events
  */
 type BucketObjectCreatedFn<C = undefined> = (args: {
     event: BucketEvent;
-} & SpreadCtx$3<C>) => Promise<void>;
+} & SpreadCtx$4<C>) => Promise<void>;
 /**
  * Callback function type for S3 ObjectRemoved events
  */
 type BucketObjectRemovedFn<C = undefined> = (args: {
     event: BucketEvent;
-} & SpreadCtx$3<C>) => Promise<void>;
-/**
- * Setup factory type for bucket handlers.
- * Always receives `bucket: BucketClient` (self-client for the handler's own bucket).
- * Also receives `deps` and/or `config` when declared.
- */
-type SetupFactory$3<C, D, P, S extends string[] | undefined = undefined> = (args: {
-    bucket: BucketClient;
-} & ([D] extends [undefined] ? {} : {
-    deps: ResolveDeps<D>;
-}) & ([P] extends [undefined] ? {} : {
-    config: ResolveConfig<P & {}>;
-}) & ([S] extends [undefined] ? {} : {
-    files: StaticFiles;
-})) => C | Promise<C>;
-/** Base options shared by all defineBucket variants */
-type DefineBucketBase<C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = BucketConfig & {
-    /**
-     * Error handler called when onObjectCreated or onObjectRemoved throws.
-     * If not provided, defaults to `console.error`.
-     */
-    onError?: (args: {
-        error: unknown;
-    } & SpreadCtx$3<C>) => void;
-    /** Called after each invocation completes, right before Lambda freezes the process */
-    onAfterInvoke?: (args: SpreadCtx$3<C>) => void | Promise<void>;
-    /**
-     * Factory function to initialize shared state for callbacks.
-     * Called once on cold start, result is cached and reused across invocations.
-     * Always receives `bucket: BucketClient` (self-client). When deps/config
-     * are declared, receives them as well.
-     */
-    setup?: SetupFactory$3<C, NoInfer<D>, NoInfer<P>, NoInfer<S>>;
-    /**
-     * Dependencies on other handlers (tables, buckets, etc.).
-     * Typed clients are injected into the handler via the `deps` argument.
-     * Pass a function returning the deps object: `deps: () => ({ uploads })`.
-     */
-    deps?: () => D & {};
-    /**
-     * SSM Parameter Store parameters.
-     * Declare with `defineSecret()` helper. Values are fetched and cached at cold start.
-     */
-    config?: ConfigFactory<P>;
-    /**
-     * Static file glob patterns to bundle into the Lambda ZIP.
-     * Files are accessible at runtime via the `files` callback argument.
-     */
-    static?: S;
-};
-/** With event handlers (at least one callback) */
-type DefineBucketWithHandlers<C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = DefineBucketBase<C, D, P, S> & {
-    onObjectCreated?: BucketObjectCreatedFn<C>;
-    onObjectRemoved?: BucketObjectRemovedFn<C>;
-};
-/** Resource-only: no Lambda, just creates the bucket */
-type DefineBucketResourceOnly<C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = DefineBucketBase<C, D, P, S> & {
-    onObjectCreated?: never;
-    onObjectRemoved?: never;
-};
-type DefineBucketOptions<C = undefined, D extends Record<string, AnyDepHandler> | undefined = undefined, P extends Record<string, AnySecretRef> | undefined = undefined, S extends string[] | undefined = undefined> = DefineBucketWithHandlers<C, D, P, S> | DefineBucketResourceOnly<C, D, P, S>;
+} & SpreadCtx$4<C>) => Promise<void>;
 /**
  * Internal handler object created by defineBucket
  * @internal
@@ -575,7 +392,7 @@ type BucketHandler<C = any> = {
     readonly __brand: "effortless-bucket";
     readonly __spec: BucketConfig;
     readonly onError?: (...args: any[]) => any;
-    readonly onAfterInvoke?: (...args: any[]) => any;
+    readonly onCleanup?: (...args: any[]) => any;
     readonly setup?: (...args: any[]) => C | Promise<C>;
     readonly deps?: Record<string, unknown> | (() => Record<string, unknown>);
     readonly config?: Record<string, unknown>;
@@ -583,42 +400,54 @@ type BucketHandler<C = any> = {
     readonly onObjectCreated?: (...args: any[]) => any;
     readonly onObjectRemoved?: (...args: any[]) => any;
 };
+/** Options passed to `defineBucket()` — static config */
+type BucketOptions = {
+    /** S3 key prefix filter for event notifications (e.g., "uploads/") */
+    prefix?: string;
+    /** S3 key suffix filter for event notifications (e.g., ".jpg") */
+    suffix?: string;
+};
+interface BucketBuilder<D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false> {
+    /** Declare handler dependencies */
+    deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): BucketBuilder<D2, P, C, HasFiles>;
+    /** Declare SSM secrets */
+    config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): BucketBuilder<D, P2, C, HasFiles>;
+    /** Include static files in the Lambda ZIP */
+    include(glob: string): BucketBuilder<D, P, C, true>;
+    /** Initialize shared state on cold start with lambda options */
+    setup(lambda: LambdaOptions): BucketBuilder<D, P, C, HasFiles>;
+    /** Initialize shared state on cold start. Receives bucket (self-client), deps, config, files. */
+    setup<C2>(fn: (args: SetupArgs$4<D, P, HasFiles>) => C2 | Promise<C2>): BucketBuilder<D, P, C2, HasFiles>;
+    /** Initialize shared state on cold start with lambda options. Receives bucket (self-client), deps, config, files. */
+    setup<C2>(fn: (args: SetupArgs$4<D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): BucketBuilder<D, P, C2, HasFiles>;
+    /** Handle errors thrown by callbacks */
+    onError(fn: (args: {
+        error: unknown;
+    } & SpreadCtx$4<C>) => void): BucketBuilder<D, P, C, HasFiles>;
+    /** Cleanup callback — runs after each invocation, before Lambda freezes */
+    onCleanup(fn: (args: SpreadCtx$4<C>) => void | Promise<void>): BucketBuilder<D, P, C, HasFiles>;
+    /** Handle S3 ObjectCreated events (terminal — returns finalized handler) */
+    onObjectCreated(fn: BucketObjectCreatedFn<C>): BucketHandler<C>;
+    /** Handle S3 ObjectRemoved events (terminal — returns finalized handler) */
+    onObjectRemoved(fn: BucketObjectRemovedFn<C>): BucketHandler<C>;
+    /** Finalize as resource-only bucket (no Lambda) */
+    build(): BucketHandler<C>;
+}
 /**
  * Define an S3 bucket with optional event handlers.
  *
- * Creates an S3 bucket. When event handlers are provided, also creates a Lambda
- * function triggered by S3 event notifications.
+ * @see {@link https://effortless-aws.website/use-cases/storage | Storage guide}
  *
- * @example Bucket with event handler
- * ```typescript
- * export const uploads = defineBucket({
- *   prefix: "images/",
- *   suffix: ".jpg",
- *   onObjectCreated: async ({ event, bucket }) => {
- *     const file = await bucket.get(event.key);
- *     console.log("New upload:", event.key, file?.body.length);
- *   }
- * });
- * ```
- *
- * @example Resource-only bucket (no Lambda)
- * ```typescript
- * export const assets = defineBucket({});
- * ```
- *
- * @example As a dependency
+ * @example
  * ```typescript
- * export const api = defineApi({
- *   basePath: "/process",
- *   deps: { uploads },
- *   post: async ({ req, deps }) => {
- *     await deps.uploads.put("output.jpg", buffer);
- *     return { status: 200, body: "OK" };
- *   },
- * });
+ * export const uploads = defineBucket({ prefix: "images/", suffix: ".jpg" })
+ *   .onObjectCreated(async ({ event, bucket }) => {
+ *     console.log("New upload:", event.key);
+ *   })
  * ```
  */
-declare const defineBucket: () => <C = undefined, D extends Record<string, AnyDepHandler> | undefined = undefined, P extends Record<string, AnySecretRef> | undefined = undefined, S extends string[] | undefined = undefined>(options: DefineBucketOptions<C, D, P, S>) => BucketHandler<C>;
+declare function defineBucket(): BucketBuilder;
+declare function defineBucket(options: BucketOptions): BucketBuilder;
 
 /**
  * Configuration options for defining a mailer (SES email identity)
@@ -644,6 +473,8 @@ type MailerHandler = {
  * On first deploy, DKIM DNS records are printed to the console.
  * Add them to your DNS provider to verify the domain.
  *
+ * @see {@link https://effortless-aws.website/use-cases/email | Email guide}
+ *
  * @param options - Mailer configuration with the domain to send from
  * @returns Handler object used by the deployment system and as a `deps` value
  *
@@ -703,7 +534,12 @@ type FifoQueueMessage<T = unknown> = {
  */
 type FifoQueueConfig = {
     /** Lambda function settings (memory, timeout, permissions, etc.) */
-    lambda?: LambdaWithPermissions;
+    lambda?: {
+        memory?: number;
+        timeout?: Duration;
+        logLevel?: LogLevel;
+        permissions?: Permission[];
+    };
     /** 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. */
@@ -719,26 +555,23 @@ type FifoQueueConfig = {
     /** Max number of receives before a message is sent to the dead-letter queue (default: 3) */
     maxReceiveCount?: number;
 };
-/**
- * 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] ? {} : {
+/** Spread ctx into callback args (empty when no setup) */
+type SpreadCtx$3<C> = [C] extends [undefined] ? {} : C & {};
+/** Setup factory — receives deps/config/files based on what was declared */
+type SetupArgs$3<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
     config: ResolveConfig<P & {}>;
-}) & ([S] extends [undefined] ? {} : {
+}) & (HasFiles extends true ? {
     files: StaticFiles;
-})) => C | Promise<C>;
-/** Spread ctx into callback args (empty when no setup) */
-type SpreadCtx$2<C> = [C] extends [undefined] ? {} : C & {};
+} : {});
 /**
  * Per-message handler function.
  * Called once per message in the batch. Failures are reported individually.
  */
 type FifoQueueMessageFn<T = unknown, C = undefined> = (args: {
     message: FifoQueueMessage<T>;
-} & SpreadCtx$2<C>) => Promise<void>;
+} & SpreadCtx$3<C>) => Promise<void>;
 /**
  * Batch handler function.
  * Called once with all messages in the batch.
@@ -746,59 +579,9 @@ type FifoQueueMessageFn<T = unknown, C = undefined> = (args: {
  */
 type FifoQueueBatchFn<T = unknown, C = undefined> = (args: {
     messages: FifoQueueMessage<T>[];
-} & SpreadCtx$2<C>) => Promise<void | {
+} & SpreadCtx$3<C>) => Promise<void | {
     failures: string[];
 }>;
-/** 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 onMessageBatch throws.
-     * If not provided, defaults to `console.error`.
-     */
-    onError?: (args: {
-        error: unknown;
-    } & SpreadCtx$2<C>) => void;
-    /** Called after each invocation completes, right before Lambda freezes the process */
-    onAfterInvoke?: (args: SpreadCtx$2<C>) => void | Promise<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, NoInfer<D>, NoInfer<P>, NoInfer<S>>;
-    /**
-     * Dependencies on other handlers (tables, queues, etc.).
-     * Typed clients are injected into the handler via the `deps` argument.
-     * Pass a function returning the deps object: `deps: () => ({ orders })`.
-     */
-    deps?: () => D & {};
-    /**
-     * SSM Parameter Store parameters.
-     * Declare with `defineSecret()` helper. Values are fetched and cached at cold start.
-     */
-    config?: ConfigFactory<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>;
-    onMessageBatch?: 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> & {
-    onMessageBatch: FifoQueueBatchFn<T, C>;
-    onMessage?: never;
-};
-type DefineFifoQueueOptions<T = unknown, C = undefined, D extends Record<string, AnyDepHandler> | undefined = undefined, P extends Record<string, AnySecretRef> | 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
@@ -808,7 +591,7 @@ type FifoQueueHandler<T = unknown, C = any> = {
     readonly __spec: FifoQueueConfig;
     readonly schema?: (input: unknown) => T;
     readonly onError?: (...args: any[]) => any;
-    readonly onAfterInvoke?: (...args: any[]) => any;
+    readonly onCleanup?: (...args: any[]) => any;
     readonly setup?: (...args: any[]) => C | Promise<C>;
     readonly deps?: Record<string, unknown> | (() => Record<string, unknown>);
     readonly config?: Record<string, unknown>;
@@ -816,37 +599,169 @@ type FifoQueueHandler<T = unknown, C = any> = {
     readonly onMessage?: (...args: any[]) => any;
     readonly onMessageBatch?: (...args: any[]) => any;
 };
+/** Options passed to `defineFifoQueue()` — static config */
+type FifoQueueOptions<T> = {
+    /** Number of messages per Lambda invocation (1-10 for FIFO, default: 10) */
+    batchSize?: number;
+    /** Maximum time to gather messages before invoking (default: 0) */
+    batchWindow?: Duration;
+    /** Visibility timeout (default: max of timeout or 30s) */
+    visibilityTimeout?: Duration;
+    /** Message retention period (default: "4d") */
+    retentionPeriod?: Duration;
+    /** Delivery delay for all messages in the queue (default: 0) */
+    delay?: Duration;
+    /** Enable content-based deduplication (default: true) */
+    contentBasedDeduplication?: boolean;
+    /** Max number of receives before DLQ (default: 3) */
+    maxReceiveCount?: number;
+    /** Decode/validate function for the message body */
+    schema?: (input: unknown) => T;
+};
+interface FifoQueueBuilder<T = unknown, D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false> {
+    /** Declare handler dependencies */
+    deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): FifoQueueBuilder<T, D2, P, C, HasFiles>;
+    /** Declare SSM secrets */
+    config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): FifoQueueBuilder<T, D, P2, C, HasFiles>;
+    /** Include static files in the Lambda bundle. Chainable — call multiple times. */
+    include(glob: string): FifoQueueBuilder<T, D, P, C, true>;
+    /** Configure Lambda settings only (memory, timeout, permissions, etc.) */
+    setup(lambda: LambdaOptions): FifoQueueBuilder<T, D, P, C, HasFiles>;
+    /** Initialize shared state on cold start. Receives deps, config, files. */
+    setup<C2>(fn: (args: SetupArgs$3<D, P, HasFiles>) => C2 | Promise<C2>): FifoQueueBuilder<T, D, P, C2, HasFiles>;
+    /** Initialize shared state on cold start + configure Lambda settings. */
+    setup<C2>(fn: (args: SetupArgs$3<D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): FifoQueueBuilder<T, D, P, C2, HasFiles>;
+    /** Handle errors thrown by message handlers */
+    onError(fn: (args: {
+        error: unknown;
+    } & SpreadCtx$3<C>) => void): FifoQueueBuilder<T, D, P, C, HasFiles>;
+    /** Cleanup callback — runs after each invocation, before Lambda freezes */
+    onCleanup(fn: (args: SpreadCtx$3<C>) => void | Promise<void>): FifoQueueBuilder<T, D, P, C, HasFiles>;
+    /** Per-message handler (terminal — returns finalized handler) */
+    onMessage(fn: FifoQueueMessageFn<T, C>): FifoQueueHandler<T, C>;
+    /** Batch handler (terminal — returns finalized handler) */
+    onMessageBatch(fn: FifoQueueBatchFn<T, C>): FifoQueueHandler<T, C>;
+}
 /**
- * Define a FIFO SQS queue with a Lambda message handler
+ * 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
+ * @see {@link https://effortless-aws.website/use-cases/queue | Queue guide}
  *
- * @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
+ * @example
  * ```typescript
- * export const notifications = defineFifoQueue({
- *   schema: (input) => NotificationSchema.parse(input),
- *   batchSize: 5,
- *   onMessageBatch: async ({ messages }) => {
+ * export const notifications = defineFifoQueue({ batchSize: 5, schema: (i) => NotifSchema.parse(i) })
+ *   .onMessageBatch(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, AnySecretRef> | undefined = undefined, S extends string[] | undefined = undefined>(options: DefineFifoQueueOptions<T, C, D, P, S>) => FifoQueueHandler<T, C>;
+declare function defineFifoQueue<T = unknown>(): FifoQueueBuilder<T>;
+declare function defineFifoQueue<T = unknown>(options: FifoQueueOptions<T>): FifoQueueBuilder<T>;
+
+/**
+ * Sort key condition for TableClient.query()
+ */
+type SkCondition = string | {
+    begins_with: string;
+} | {
+    gt: string;
+} | {
+    gte: string;
+} | {
+    lt: string;
+} | {
+    lte: string;
+} | {
+    between: [string, string];
+};
+/**
+ * Query parameters for TableClient.query()
+ */
+type QueryParams = {
+    /** Partition key value */
+    pk: string;
+    /** Optional sort key condition */
+    sk?: SkCondition;
+    /** Maximum number of items to return */
+    limit?: number;
+    /** Sort order (true = ascending, false = descending) */
+    scanIndexForward?: boolean;
+};
+/**
+ * Query parameters for TableClient.queryByTag() — cross-partition query via GSI.
+ * Uses the built-in `tag-pk-index` GSI (tag as partition key, pk as sort key).
+ */
+type QueryByTagParams = {
+    /** Tag value (GSI partition key) — the entity type discriminant */
+    tag: string;
+    /** Optional pk condition (GSI sort key) */
+    pk?: SkCondition;
+    /** Maximum number of items to return */
+    limit?: number;
+    /** Sort order (true = ascending, false = descending) */
+    scanIndexForward?: boolean;
+};
+/** Extract keys of T whose values are arrays */
+type ArrayKeys<T> = {
+    [K in keyof T]: T[K] extends unknown[] ? K : never;
+}[keyof T];
+/** Extract keys of T whose values are numbers */
+type NumberKeys<T> = {
+    [K in keyof T]: T[K] extends number ? K : never;
+}[keyof T];
+/**
+ * Update actions for TableClient.update()
+ *
+ * `set`, `append`, and `remove` target fields inside the `data` attribute.
+ * Effortless auto-prefixes `data.` in the DynamoDB expression.
+ *
+ * @typeParam T - Type of the domain data (the `data` attribute)
+ */
+type UpdateActions<T> = {
+    /** Set domain data fields (inside `data` attribute) */
+    set?: Partial<T>;
+    /** Atomically increment/decrement numeric fields inside `data` (use negative values to decrement) */
+    increment?: Pick<Partial<T>, NumberKeys<T>>;
+    /** Append elements to list fields inside `data` (creates the list if it doesn't exist) */
+    append?: Pick<Partial<T>, ArrayKeys<T>>;
+    /** Remove fields from `data` */
+    remove?: (keyof T)[];
+    /** Update the top-level `tag` attribute */
+    tag?: string;
+    /** Update TTL (set number or null to remove) */
+    ttl?: number | null;
+};
+/**
+ * Typed DynamoDB table client for single-table design.
+ *
+ * All items follow the `{ pk, sk, tag, data, ttl? }` structure.
+ * `T` is the domain data type stored in the `data` attribute.
+ *
+ * @typeParam T - Type of the domain data
+ */
+/**
+ * Options for `put()` operation.
+ */
+type PutOptions = {
+    /** When true, the put fails if an item with the same pk+sk already exists. */
+    ifNotExists?: boolean;
+};
+type TableClient<T = Record<string, unknown>> = {
+    /** Put an item. Tag is auto-extracted from `data[tagField]`. Use `ifNotExists` to prevent overwrites. */
+    put(item: PutInput<T>, options?: PutOptions): Promise<void>;
+    /** Get an item by pk + sk */
+    get(key: TableKey): Promise<TableItem<T> | undefined>;
+    /** Delete an item by pk + sk */
+    delete(key: TableKey): Promise<void>;
+    /** Update domain data fields without reading the full item */
+    update(key: TableKey, actions: UpdateActions<T>): Promise<void>;
+    /** Query by partition key with optional sort key condition */
+    query(params: QueryParams): Promise<TableItem<T>[]>;
+    /** Query by tag across all partitions via GSI (tag-pk-index). */
+    queryByTag(params: QueryByTagParams): Promise<TableItem<T>[]>;
+    /** The underlying DynamoDB table name */
+    tableName: string;
+};
 
 /**
  * Options for sending an email via EmailClient.send()
@@ -924,7 +839,12 @@ type StreamView = "NEW_AND_OLD_IMAGES" | "NEW_IMAGE" | "OLD_IMAGE" | "KEYS_ONLY"
  */
 type TableConfig = {
     /** Lambda function settings (memory, timeout, permissions, etc.) */
-    lambda?: LambdaWithPermissions;
+    lambda?: {
+        memory?: number;
+        timeout?: Duration;
+        logLevel?: LogLevel;
+        permissions?: Permission[];
+    };
     /** 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") */
@@ -968,22 +888,18 @@ type TableRecord<T = Record<string, unknown>> = {
     /** Approximate timestamp when the modification occurred */
     timestamp?: number;
 };
-/**
- * Setup factory type for table handlers.
- * Receives `table: TableClient<T>` (self-client for the handler's own table).
- * Also receives `deps` and/or `config` when declared.
- */
-type SetupFactory$1<C, T, D, P, S extends string[] | undefined = undefined> = (args: {
+/** Setup factory — receives table/deps/config/files based on what was declared */
+type SetupArgs$2<T, D, P, HasFiles extends boolean> = {
     table: TableClient<T>;
 } & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
     config: ResolveConfig<P & {}>;
-}) & ([S] extends [undefined] ? {} : {
+}) & (HasFiles extends true ? {
     files: StaticFiles;
-})) => C | Promise<C>;
+} : {});
 /** Spread ctx into callback args (empty when no setup) */
-type SpreadCtx$1<C> = [C] extends [undefined] ? {} : C & {};
+type SpreadCtx$2<C> = [C] extends [undefined] ? {} : C & {};
 /**
  * Callback function type for processing a single DynamoDB stream record.
  * Receives the current record and the full batch for context.
@@ -991,7 +907,7 @@ type SpreadCtx$1<C> = [C] extends [undefined] ? {} : C & {};
 type TableRecordFn<T = Record<string, unknown>, C = undefined> = (args: {
     record: TableRecord<T>;
     batch: readonly TableRecord<T>[];
-} & SpreadCtx$1<C>) => Promise<void>;
+} & SpreadCtx$2<C>) => Promise<void>;
 /**
  * Batch handler function for DynamoDB stream records.
  * Called once with all records in the batch.
@@ -999,76 +915,13 @@ type TableRecordFn<T = Record<string, unknown>, C = undefined> = (args: {
  */
 type TableBatchFn<T = Record<string, unknown>, C = undefined> = (args: {
     records: readonly TableRecord<T>[];
-} & SpreadCtx$1<C>) => Promise<void | {
+} & SpreadCtx$2<C>) => Promise<void | {
     failures: string[];
 }>;
-/** Base options shared by all defineTable variants */
-type DefineTableBase<T = Record<string, unknown>, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = Omit<TableConfig, "tagField"> & {
-    /** Name of the field in `data` that serves as the entity type discriminant (default: `"tag"`). */
-    tagField?: Extract<keyof T, string>;
-    /**
-     * Decode/validate function for the `data` portion of stream record items.
-     * Called with the unmarshalled `data` attribute; should return typed data or throw on validation failure.
-     * When provided, T is inferred from the return type — no need to specify generic parameters.
-     */
-    schema?: (input: unknown) => T;
-    /**
-     * Error handler called when onRecord/onRecordBatch throws.
-     * If not provided, defaults to `console.error`.
-     */
-    onError?: (args: {
-        error: unknown;
-    } & SpreadCtx$1<C>) => void;
-    /** Called after each invocation completes, right before Lambda freezes the process */
-    onAfterInvoke?: (args: SpreadCtx$1<C>) => void | Promise<void>;
-    /**
-     * Factory function to initialize shared state for callbacks.
-     * Called once on cold start, result is cached and reused across invocations.
-     * Receives `table` (self-client), plus `deps`/`config`/`files` when declared.
-     */
-    setup?: SetupFactory$1<C, T, NoInfer<D>, NoInfer<P>, NoInfer<S>>;
-    /**
-     * Dependencies on other handlers (tables, queues, etc.).
-     * Typed clients are injected into setup via the `deps` argument.
-     * Pass a function returning the deps object: `deps: () => ({ orders })`.
-     */
-    deps?: () => D & {};
-    /**
-     * SSM Parameter Store parameters.
-     * Declare with `defineSecret()` helper. Values are fetched and cached at cold start.
-     */
-    config?: ConfigFactory<P>;
-    /**
-     * Static file glob patterns to bundle into the Lambda ZIP.
-     * Files are accessible at runtime via the `files` argument in setup.
-     */
-    static?: S;
-};
-/**
- * Options for defineTable.
- * `onRecord` and `onRecordBatch` are mutually exclusive. Both are optional (table-only mode).
- */
-type DefineTableOptions<T = Record<string, unknown>, C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined> = DefineTableBase<T, C, D, P, S> & ({
-    /**
-     * Per-record stream handler. Called once per record in the batch.
-     * Runtime handles partial batch failure reporting automatically.
-     * Records are processed with configurable `concurrency` (default: 1 — sequential).
-     */
-    onRecord?: TableRecordFn<T, C>;
-    onRecordBatch?: never;
-} | {
-    /**
-     * Batch stream handler. Called once with all records in the batch.
-     * Return `{ failures: string[] }` with sequence numbers for partial batch failure.
-     */
-    onRecordBatch?: TableBatchFn<T, C>;
-    onRecord?: never;
-} | {
-    onRecord?: never;
-    onRecordBatch?: never;
-});
+/** Static config extracted by AST (no runtime callbacks) */
 /**
- * Internal handler object created by defineTable
+ * Handler object created by defineTable.
+ * Used by runtime wrappers and as type annotation for circular deps.
  * @internal
  */
 type TableHandler<T = Record<string, unknown>, C = any> = {
@@ -1076,7 +929,7 @@ type TableHandler<T = Record<string, unknown>, C = any> = {
     readonly __spec: TableConfig;
     readonly schema?: (input: unknown) => T;
     readonly onError?: (...args: any[]) => any;
-    readonly onAfterInvoke?: (...args: any[]) => any;
+    readonly onCleanup?: (...args: any[]) => any;
     readonly setup?: (...args: any[]) => C | Promise<C>;
     readonly deps?: Record<string, unknown> | (() => Record<string, unknown>);
     readonly config?: Record<string, unknown>;
@@ -1084,40 +937,72 @@ type TableHandler<T = Record<string, unknown>, C = any> = {
     readonly onRecord?: (...args: any[]) => any;
     readonly onRecordBatch?: (...args: any[]) => any;
 };
+/** Options passed to `defineTable()` — resource config only, no Lambda settings */
+type TableOptions<T> = {
+    /** DynamoDB billing mode (default: "PAY_PER_REQUEST") */
+    billingMode?: "PAY_PER_REQUEST" | "PROVISIONED";
+    /** Stream view type (default: "NEW_AND_OLD_IMAGES") */
+    streamView?: StreamView;
+    /** Number of records to process in each Lambda invocation (1-10000, default: 100) */
+    batchSize?: number;
+    /** Maximum time to gather records before invoking (default: "2s") */
+    batchWindow?: Duration;
+    /** Where to start reading the stream (default: "LATEST") */
+    startingPosition?: "LATEST" | "TRIM_HORIZON";
+    /** Number of records to process concurrently within a batch (default: 1) */
+    concurrency?: number;
+    /** Name of the field in `data` that serves as the entity type discriminant (default: "tag") */
+    tagField?: Extract<keyof T, string>;
+    /** Decode/validate function for the `data` portion of stream records */
+    schema?: (input: unknown) => T;
+};
+interface TableBuilder<T = Record<string, unknown>, D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false> {
+    /** Declare handler dependencies (tables, queues, buckets, mailers) */
+    deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): TableBuilder<T, D2, P, C, HasFiles>;
+    /** Declare SSM secrets */
+    config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): TableBuilder<T, D, P2, C, HasFiles>;
+    /** Include static files in the Lambda bundle. Chainable — call multiple times. */
+    include(glob: string): TableBuilder<T, D, P, C, true>;
+    /** Configure Lambda settings only (memory, timeout, permissions, etc.) */
+    setup(lambda: LambdaOptions): TableBuilder<T, D, P, C, HasFiles>;
+    /** Initialize shared state on cold start. Receives table (self-client), deps, config, files. */
+    setup<C2>(fn: (args: SetupArgs$2<T, D, P, HasFiles>) => C2 | Promise<C2>): TableBuilder<T, D, P, C2, HasFiles>;
+    /** Initialize shared state on cold start + configure Lambda settings. */
+    setup<C2>(fn: (args: SetupArgs$2<T, D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): TableBuilder<T, D, P, C2, HasFiles>;
+    /** Handle errors thrown by onRecord/onRecordBatch */
+    onError(fn: (args: {
+        error: unknown;
+    } & SpreadCtx$2<C>) => void): TableBuilder<T, D, P, C, HasFiles>;
+    /** Cleanup callback — runs after each invocation, before Lambda freezes */
+    onCleanup(fn: (args: SpreadCtx$2<C>) => void | Promise<void>): TableBuilder<T, D, P, C, HasFiles>;
+    /** Per-record stream handler (terminal — returns finalized handler) */
+    onRecord(fn: TableRecordFn<T, C>): TableHandler<T, C>;
+    /** Batch stream handler (terminal — returns finalized handler) */
+    onRecordBatch(fn: TableBatchFn<T, C>): TableHandler<T, C>;
+    /** Finalize as resource-only table (no Lambda) */
+    build(): TableHandler<T, C>;
+}
 /**
  * Define a DynamoDB table with optional stream handler (single-table design).
  *
  * Creates a table with fixed key schema: `pk (S)` + `sk (S)`, plus `tag (S)`,
  * `data (M)`, and `ttl (N)` attributes. TTL is always enabled.
  *
- * @example Table with stream handler
+ * @see {@link https://effortless-aws.website/use-cases/database | Database guide}
+ *
+ * @example
  * ```typescript
- * export const orders = defineTable<OrderData>()({
- *   batchSize: 10,
- *   concurrency: 5,
- *   setup: ({ table }) => ({ table }),
- *   onRecord: async ({ record, batch, table }) => {
+ * export const orders = defineTable<OrderData>({ batchSize: 10, concurrency: 5 })
+ *   .setup(({ table }) => ({ table }))
+ *   .onRecord(async ({ record, table }) => {
  *     if (record.eventName === "INSERT") {
  *       console.log("New order:", record.new?.data);
  *     }
- *   }
- * });
- * ```
- *
- * @example Table with runtime validation
- * ```typescript
- * export const orders = defineTable<OrderData>()({
- *   schema: (input) => OrderSchema.parse(input),
- *   onRecord: async ({ record }) => { ... }
- * });
- * ```
- *
- * @example Table only (no Lambda)
- * ```typescript
- * export const users = defineTable()({});
+ *   })
  * ```
  */
-declare const defineTable: <T = Record<string, unknown>>() => <C = undefined, D = undefined, P = undefined, S extends string[] | undefined = undefined>(options: DefineTableOptions<T, C, D, P, S>) => TableHandler<T, C>;
+declare function defineTable<T = Record<string, unknown>>(): TableBuilder<T>;
+declare function defineTable<T = Record<string, unknown>>(options: TableOptions<T>): TableBuilder<T>;
 
 /**
  * Configuration for deploying an SSR framework (Nuxt, Astro, etc.)
@@ -1161,18 +1046,10 @@ type AppHandler = {
  *
  * For static-only sites (no SSR), use {@link defineStaticSite} instead.
  *
+ * @see {@link https://effortless-aws.website/use-cases/web-app | Web app guide}
+ *
  * @param options - App configuration: server directory, assets directory, optional build command
  * @returns Handler object used by the deployment system
- *
- * @example Nuxt SSR
- * ```typescript
- * export const app = defineApp({
- *   build: "nuxt build",
- *   server: ".output/server",
- *   assets: ".output/public",
- *   lambda: { memory: 1024 },
- * });
- * ```
  */
 declare const defineApp: () => (options: AppConfig) => AppHandler;
 
@@ -1249,26 +1126,10 @@ type StaticSiteHandler = {
 /**
  * Deploy a static site via S3 + CloudFront CDN.
  *
+ * @see {@link https://effortless-aws.website/use-cases/web-app | Web app guide}
+ *
  * @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;
 
@@ -1330,7 +1191,11 @@ type ExtractAuth<C> = C extends {
     auth: ApiAuthConfig<infer A>;
 } ? A : undefined;
 /** Property names reserved by the framework — cannot be used in setup return */
-type ReservedKeys = 'req' | 'input' | 'stream';
+type ReservedKeys = 'req' | 'input' | 'stream' | 'ok' | 'fail';
+/** Success response helper: `ok({ data })` → `{ status: 200, body: { data } }` */
+type OkHelper = (body?: unknown, status?: number) => HttpResponse;
+/** Error response helper: `fail("message")` → `{ status: 400, body: { error: "message" } }` */
+type FailHelper = (message: string, status?: number) => HttpResponse;
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 /** Parsed route definition stored at runtime */
 type RouteEntry = {
@@ -1340,36 +1205,40 @@ type RouteEntry = {
     public?: boolean;
 };
 /** Spread ctx into route args: Omit auth config, add AuthHelpers if present */
-type SpreadCtx<C> = ([C] extends [undefined] ? {} : Omit<C & {}, 'auth'>) & ([ExtractAuth<C>] extends [undefined] ? {} : {
+type SpreadCtx$1<C> = ([C] extends [undefined] ? {} : Omit<C & {}, 'auth'>) & ([ExtractAuth<C>] extends [undefined] ? {} : {
     auth: AuthHelpers<ExtractAuth<C>>;
 });
 /** Callback args available inside each route — ctx is spread into args */
-type RouteArgs<C, ST> = SpreadCtx<C> & {
+type RouteArgs<C, ST> = SpreadCtx$1<C> & {
     req: HttpRequest;
     input: unknown;
+    ok: OkHelper;
+    fail: FailHelper;
 } & ([ST] extends [true] ? {
     stream: ResponseStream;
 } : {});
-/** Route definition with typed args */
-type RouteDefinition<C, ST> = {
-    path: `${HttpMethod} /${string}`;
-    onRequest: (args: RouteArgs<C, ST>) => Promise<HttpResponse | void> | HttpResponse | void;
+/** Route handler function */
+type RouteHandler<C, ST> = (args: RouteArgs<C, ST>) => Promise<HttpResponse | void> | HttpResponse | void;
+/** Route options (e.g. public) */
+type RouteOptions = {
     public?: boolean;
 };
-/** Validate that setup return type does not use reserved property names */
-type ValidateSetupReturn<C> = C & {
-    [K in ReservedKeys]?: never;
-};
-/** Setup factory — receives deps/config/files/enableAuth when declared */
-type SetupFactory<C, D, P, S extends string[] | undefined = undefined> = (args: {
+/** Setup factory — receives deps/config/files/enableAuth based on what was declared */
+type SetupArgs$1<D, P, HasFiles extends boolean> = {
     enableAuth: EnableAuth;
+    ok: OkHelper;
+    fail: FailHelper;
 } & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
     config: ResolveConfig<P & {}>;
-}) & ([S] extends [undefined] ? {} : {
+}) & (HasFiles extends true ? {
     files: StaticFiles;
-})) => ValidateSetupReturn<C> | Promise<ValidateSetupReturn<C>>;
+} : {});
+/** Validate that setup return type does not use reserved property names */
+type ValidateSetupReturn<C> = C & {
+    [K in ReservedKeys]?: never;
+};
 /** Static config extracted by AST (no runtime callbacks) */
 type ApiConfig = {
     /** Lambda function settings (memory, timeout, permissions, etc.) */
@@ -1379,79 +1248,212 @@ type ApiConfig = {
     /** Enable response streaming. When true, the Lambda Function URL uses RESPONSE_STREAM invoke mode. */
     stream?: boolean;
 };
-type DefineApiOptions<C = undefined, D extends Record<string, AnyDepHandler> | undefined = undefined, P extends Record<string, AnySecretRef> | 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. */
-    stream?: ST;
-    /** Factory function to initialize shared state. Called once on cold start. */
-    setup?: SetupFactory<C, NoInfer<D>, NoInfer<P>, NoInfer<S>>;
-    /** Dependencies on other handlers (tables, queues, etc.): `deps: () => ({ users })` */
-    deps?: () => D & {};
-    /** SSM Parameter Store parameters. Receives `{ defineSecret }` helper. */
-    config?: ConfigFactory<P>;
-    /** Static file glob patterns to bundle into the Lambda ZIP */
-    static?: S;
-    /** Error handler called when a route throws */
-    onError?: (args: {
-        error: unknown;
-        req: HttpRequest;
-    } & SpreadCtx<C>) => HttpResponse;
-    /** Called after each invocation completes */
-    onAfterInvoke?: (args: SpreadCtx<C>) => void | Promise<void>;
-    /** Route definitions — plain array of route objects */
-    routes?: RouteDefinition<C, ST>[];
-};
 /** Internal handler object created by defineApi */
 type ApiHandler<C = undefined> = {
     readonly __brand: "effortless-api";
     readonly __spec: ApiConfig;
     readonly onError?: (...args: any[]) => any;
-    readonly onAfterInvoke?: (...args: any[]) => any;
+    readonly onCleanup?: (...args: any[]) => any;
     readonly setup?: (...args: any[]) => C | Promise<C>;
     readonly deps?: Record<string, unknown> | (() => Record<string, unknown>);
     readonly config?: Record<string, unknown>;
     readonly static?: string[];
     readonly routes?: RouteEntry[];
 };
+/** Options passed to `defineApi()` */
+type ApiOptions = {
+    /** Base path prefix for all routes (e.g., "/api") */
+    basePath: `/${string}`;
+    /** Enable response streaming. When true, routes receive a `stream` arg for SSE. */
+    stream?: boolean;
+};
+/**
+ * Finalized API handler with route-adding methods.
+ * Has `__brand` so CLI discovers it. Each `.get()/.post()` adds a route and returns self.
+ */
+interface ApiRoutes<C = undefined, ST extends boolean = false> extends ApiHandler<C> {
+    get(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
+    post(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
+    put(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
+    patch(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
+    delete(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
+}
 /**
- * Define an API with typed routes.
+ * Builder interface for defining API handlers.
  *
- * Setup return is spread into route args — all properties are directly accessible.
- * Reserved names (`req`, `input`, `stream`) cannot be used in setup return.
- * Auth is configured via an `auth` property in setup return — runtime replaces it with `AuthHelpers`.
+ * Each method sets exactly one generic, so inference happens one step at a time.
+ * This prevents cascading type errors when one property has a mistake.
+ */
+interface ApiBuilder<D = undefined, P = undefined, C = undefined, ST extends boolean = false, HasFiles extends boolean = false> {
+    /** Declare handler dependencies (tables, queues, buckets, mailers) */
+    deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): ApiBuilder<D2, P, C, ST, HasFiles>;
+    /** Declare SSM secrets */
+    config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): ApiBuilder<D, P2, C, ST, HasFiles>;
+    /** Include static files by glob pattern */
+    include(glob: string): ApiBuilder<D, P, C, ST, true>;
+    /** Configure Lambda settings only (no init function) */
+    setup(lambda: LambdaOptions): ApiBuilder<D, P, C, ST, HasFiles>;
+    /** Initialize shared state on cold start. Receives deps/config/files based on what was declared. */
+    setup<C2>(fn: (args: SetupArgs$1<D, P, HasFiles>) => ValidateSetupReturn<C2> | Promise<ValidateSetupReturn<C2>>): ApiBuilder<D, P, C2, ST, HasFiles>;
+    /** Initialize shared state on cold start with Lambda config. */
+    setup<C2>(fn: (args: SetupArgs$1<D, P, HasFiles>) => ValidateSetupReturn<C2> | Promise<ValidateSetupReturn<C2>>, lambda: LambdaOptions): ApiBuilder<D, P, C2, ST, HasFiles>;
+    /** Handle errors thrown by routes */
+    onError(fn: (args: {
+        error: unknown;
+        req: HttpRequest;
+        ok: OkHelper;
+        fail: FailHelper;
+    } & SpreadCtx$1<C>) => HttpResponse): ApiBuilder<D, P, C, ST, HasFiles>;
+    /** Cleanup callback — runs after each invocation, before Lambda freezes */
+    onCleanup(fn: (args: SpreadCtx$1<C>) => void | Promise<void>): ApiBuilder<D, P, C, ST, HasFiles>;
+    /** Add a GET route (terminal — returns finalized handler with route methods) */
+    get(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
+    /** Add a POST route (terminal) */
+    post(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
+    /** Add a PUT route (terminal) */
+    put(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
+    /** Add a PATCH route (terminal) */
+    patch(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
+    /** Add a DELETE route (terminal) */
+    delete(path: `/${string}`, handler: RouteHandler<C, ST>, options?: RouteOptions): ApiRoutes<C, ST>;
+}
+/**
+ * Define an API with typed routes using a builder pattern.
+ *
+ * @see {@link https://effortless-aws.website/use-cases/http-api | HTTP API guide}
  *
  * @example
  * ```typescript
- * export default defineApi({
- *   basePath: "/api",
- *   deps: () => ({ users }),
- *   setup: ({ deps }) => ({
+ * export const api = defineApi({ basePath: "/api", timeout: "30s" })
+ *   .deps(() => ({ users }))
+ *   .config(({ defineSecret }) => ({ dbUrl: defineSecret() }))
+ *   .setup(async ({ deps, config, enableAuth }) => ({
  *     users: deps.users,
- *     auth: {
- *       schema: unsafeAs<Session>(),
- *       apiToken: {
- *         verify: async (value) => {
- *           const user = await deps.users.query({ pk: value });
- *           return user[0] ? { userId: user[0].sk } : null;
- *         },
- *       },
- *     },
- *   }),
- *   routes: [
- *     {
- *       path: "GET /me",
- *       onRequest: async ({ users, auth }) => ({
- *         status: 200,
- *         body: { user: await users.get(auth.session.userId) },
- *       }),
- *     },
- *   ],
- * })
+ *     auth: enableAuth<Session>({ secret: config.dbUrl }),
+ *   }))
+ *   .onError(({ error, fail }) => fail(String(error), 500))
+ *   .get("/me", async ({ users, auth, ok }) => ok(auth.session))
+ *   .post("/login", async ({ auth, ok }) => ok(await auth.createSession()), { public: true })
+ * ```
+ */
+declare function defineApi<const O extends ApiOptions>(options: O): ApiBuilder<undefined, undefined, undefined, O["stream"] extends true ? true : false, false>;
+
+/**
+ * All IANA time zones.
+ * Generated from Intl.supportedValuesOf("timeZone") on Node.js 22.
+ */
+type Timezone = "UTC" | "Africa/Abidjan" | "Africa/Accra" | "Africa/Addis_Ababa" | "Africa/Algiers" | "Africa/Asmera" | "Africa/Bamako" | "Africa/Bangui" | "Africa/Banjul" | "Africa/Bissau" | "Africa/Blantyre" | "Africa/Brazzaville" | "Africa/Bujumbura" | "Africa/Cairo" | "Africa/Casablanca" | "Africa/Ceuta" | "Africa/Conakry" | "Africa/Dakar" | "Africa/Dar_es_Salaam" | "Africa/Djibouti" | "Africa/Douala" | "Africa/El_Aaiun" | "Africa/Freetown" | "Africa/Gaborone" | "Africa/Harare" | "Africa/Johannesburg" | "Africa/Juba" | "Africa/Kampala" | "Africa/Khartoum" | "Africa/Kigali" | "Africa/Kinshasa" | "Africa/Lagos" | "Africa/Libreville" | "Africa/Lome" | "Africa/Luanda" | "Africa/Lubumbashi" | "Africa/Lusaka" | "Africa/Malabo" | "Africa/Maputo" | "Africa/Maseru" | "Africa/Mbabane" | "Africa/Mogadishu" | "Africa/Monrovia" | "Africa/Nairobi" | "Africa/Ndjamena" | "Africa/Niamey" | "Africa/Nouakchott" | "Africa/Ouagadougou" | "Africa/Porto-Novo" | "Africa/Sao_Tome" | "Africa/Tripoli" | "Africa/Tunis" | "Africa/Windhoek" | "America/Adak" | "America/Anchorage" | "America/Anguilla" | "America/Antigua" | "America/Araguaina" | "America/Argentina/La_Rioja" | "America/Argentina/Rio_Gallegos" | "America/Argentina/Salta" | "America/Argentina/San_Juan" | "America/Argentina/San_Luis" | "America/Argentina/Tucuman" | "America/Argentina/Ushuaia" | "America/Aruba" | "America/Asuncion" | "America/Bahia" | "America/Bahia_Banderas" | "America/Barbados" | "America/Belem" | "America/Belize" | "America/Blanc-Sablon" | "America/Boa_Vista" | "America/Bogota" | "America/Boise" | "America/Buenos_Aires" | "America/Cambridge_Bay" | "America/Campo_Grande" | "America/Cancun" | "America/Caracas" | "America/Catamarca" | "America/Cayenne" | "America/Cayman" | "America/Chicago" | "America/Chihuahua" | "America/Ciudad_Juarez" | "America/Coral_Harbour" | "America/Cordoba" | "America/Costa_Rica" | "America/Coyhaique" | "America/Creston" | "America/Cuiaba" | "America/Curacao" | "America/Danmarkshavn" | "America/Dawson" | "America/Dawson_Creek" | "America/Denver" | "America/Detroit" | "America/Dominica" | "America/Edmonton" | "America/Eirunepe" | "America/El_Salvador" | "America/Fort_Nelson" | "America/Fortaleza" | "America/Glace_Bay" | "America/Godthab" | "America/Goose_Bay" | "America/Grand_Turk" | "America/Grenada" | "America/Guadeloupe" | "America/Guatemala" | "America/Guayaquil" | "America/Guyana" | "America/Halifax" | "America/Havana" | "America/Hermosillo" | "America/Indiana/Knox" | "America/Indiana/Marengo" | "America/Indiana/Petersburg" | "America/Indiana/Tell_City" | "America/Indiana/Vevay" | "America/Indiana/Vincennes" | "America/Indiana/Winamac" | "America/Indianapolis" | "America/Inuvik" | "America/Iqaluit" | "America/Jamaica" | "America/Jujuy" | "America/Juneau" | "America/Kentucky/Monticello" | "America/Kralendijk" | "America/La_Paz" | "America/Lima" | "America/Los_Angeles" | "America/Louisville" | "America/Lower_Princes" | "America/Maceio" | "America/Managua" | "America/Manaus" | "America/Marigot" | "America/Martinique" | "America/Matamoros" | "America/Mazatlan" | "America/Mendoza" | "America/Menominee" | "America/Merida" | "America/Metlakatla" | "America/Mexico_City" | "America/Miquelon" | "America/Moncton" | "America/Monterrey" | "America/Montevideo" | "America/Montserrat" | "America/Nassau" | "America/New_York" | "America/Nome" | "America/Noronha" | "America/North_Dakota/Beulah" | "America/North_Dakota/Center" | "America/North_Dakota/New_Salem" | "America/Ojinaga" | "America/Panama" | "America/Paramaribo" | "America/Phoenix" | "America/Port-au-Prince" | "America/Port_of_Spain" | "America/Porto_Velho" | "America/Puerto_Rico" | "America/Punta_Arenas" | "America/Rankin_Inlet" | "America/Recife" | "America/Regina" | "America/Resolute" | "America/Rio_Branco" | "America/Santarem" | "America/Santiago" | "America/Santo_Domingo" | "America/Sao_Paulo" | "America/Scoresbysund" | "America/Sitka" | "America/St_Barthelemy" | "America/St_Johns" | "America/St_Kitts" | "America/St_Lucia" | "America/St_Thomas" | "America/St_Vincent" | "America/Swift_Current" | "America/Tegucigalpa" | "America/Thule" | "America/Tijuana" | "America/Toronto" | "America/Tortola" | "America/Vancouver" | "America/Whitehorse" | "America/Winnipeg" | "America/Yakutat" | "Antarctica/Casey" | "Antarctica/Davis" | "Antarctica/DumontDUrville" | "Antarctica/Macquarie" | "Antarctica/Mawson" | "Antarctica/McMurdo" | "Antarctica/Palmer" | "Antarctica/Rothera" | "Antarctica/Syowa" | "Antarctica/Troll" | "Antarctica/Vostok" | "Arctic/Longyearbyen" | "Asia/Aden" | "Asia/Almaty" | "Asia/Amman" | "Asia/Anadyr" | "Asia/Aqtau" | "Asia/Aqtobe" | "Asia/Ashgabat" | "Asia/Atyrau" | "Asia/Baghdad" | "Asia/Bahrain" | "Asia/Baku" | "Asia/Bangkok" | "Asia/Barnaul" | "Asia/Beirut" | "Asia/Bishkek" | "Asia/Brunei" | "Asia/Calcutta" | "Asia/Chita" | "Asia/Colombo" | "Asia/Damascus" | "Asia/Dhaka" | "Asia/Dili" | "Asia/Dubai" | "Asia/Dushanbe" | "Asia/Famagusta" | "Asia/Gaza" | "Asia/Hebron" | "Asia/Hong_Kong" | "Asia/Hovd" | "Asia/Irkutsk" | "Asia/Jakarta" | "Asia/Jayapura" | "Asia/Jerusalem" | "Asia/Kabul" | "Asia/Kamchatka" | "Asia/Karachi" | "Asia/Katmandu" | "Asia/Khandyga" | "Asia/Krasnoyarsk" | "Asia/Kuala_Lumpur" | "Asia/Kuching" | "Asia/Kuwait" | "Asia/Macau" | "Asia/Magadan" | "Asia/Makassar" | "Asia/Manila" | "Asia/Muscat" | "Asia/Nicosia" | "Asia/Novokuznetsk" | "Asia/Novosibirsk" | "Asia/Omsk" | "Asia/Oral" | "Asia/Phnom_Penh" | "Asia/Pontianak" | "Asia/Pyongyang" | "Asia/Qatar" | "Asia/Qostanay" | "Asia/Qyzylorda" | "Asia/Rangoon" | "Asia/Riyadh" | "Asia/Saigon" | "Asia/Sakhalin" | "Asia/Samarkand" | "Asia/Seoul" | "Asia/Shanghai" | "Asia/Singapore" | "Asia/Srednekolymsk" | "Asia/Taipei" | "Asia/Tashkent" | "Asia/Tbilisi" | "Asia/Tehran" | "Asia/Thimphu" | "Asia/Tokyo" | "Asia/Tomsk" | "Asia/Ulaanbaatar" | "Asia/Urumqi" | "Asia/Ust-Nera" | "Asia/Vientiane" | "Asia/Vladivostok" | "Asia/Yakutsk" | "Asia/Yekaterinburg" | "Asia/Yerevan" | "Atlantic/Azores" | "Atlantic/Bermuda" | "Atlantic/Canary" | "Atlantic/Cape_Verde" | "Atlantic/Faeroe" | "Atlantic/Madeira" | "Atlantic/Reykjavik" | "Atlantic/South_Georgia" | "Atlantic/St_Helena" | "Atlantic/Stanley" | "Australia/Adelaide" | "Australia/Brisbane" | "Australia/Broken_Hill" | "Australia/Darwin" | "Australia/Eucla" | "Australia/Hobart" | "Australia/Lindeman" | "Australia/Lord_Howe" | "Australia/Melbourne" | "Australia/Perth" | "Australia/Sydney" | "Europe/Amsterdam" | "Europe/Andorra" | "Europe/Astrakhan" | "Europe/Athens" | "Europe/Belgrade" | "Europe/Berlin" | "Europe/Bratislava" | "Europe/Brussels" | "Europe/Bucharest" | "Europe/Budapest" | "Europe/Busingen" | "Europe/Chisinau" | "Europe/Copenhagen" | "Europe/Dublin" | "Europe/Gibraltar" | "Europe/Guernsey" | "Europe/Helsinki" | "Europe/Isle_of_Man" | "Europe/Istanbul" | "Europe/Jersey" | "Europe/Kaliningrad" | "Europe/Kiev" | "Europe/Kirov" | "Europe/Lisbon" | "Europe/Ljubljana" | "Europe/London" | "Europe/Luxembourg" | "Europe/Madrid" | "Europe/Malta" | "Europe/Mariehamn" | "Europe/Minsk" | "Europe/Monaco" | "Europe/Moscow" | "Europe/Oslo" | "Europe/Paris" | "Europe/Podgorica" | "Europe/Prague" | "Europe/Riga" | "Europe/Rome" | "Europe/Samara" | "Europe/San_Marino" | "Europe/Sarajevo" | "Europe/Saratov" | "Europe/Simferopol" | "Europe/Skopje" | "Europe/Sofia" | "Europe/Stockholm" | "Europe/Tallinn" | "Europe/Tirane" | "Europe/Ulyanovsk" | "Europe/Vaduz" | "Europe/Vatican" | "Europe/Vienna" | "Europe/Vilnius" | "Europe/Volgograd" | "Europe/Warsaw" | "Europe/Zagreb" | "Europe/Zurich" | "Indian/Antananarivo" | "Indian/Chagos" | "Indian/Christmas" | "Indian/Cocos" | "Indian/Comoro" | "Indian/Kerguelen" | "Indian/Mahe" | "Indian/Maldives" | "Indian/Mauritius" | "Indian/Mayotte" | "Indian/Reunion" | "Pacific/Apia" | "Pacific/Auckland" | "Pacific/Bougainville" | "Pacific/Chatham" | "Pacific/Easter" | "Pacific/Efate" | "Pacific/Enderbury" | "Pacific/Fakaofo" | "Pacific/Fiji" | "Pacific/Funafuti" | "Pacific/Galapagos" | "Pacific/Gambier" | "Pacific/Guadalcanal" | "Pacific/Guam" | "Pacific/Honolulu" | "Pacific/Kiritimati" | "Pacific/Kosrae" | "Pacific/Kwajalein" | "Pacific/Majuro" | "Pacific/Marquesas" | "Pacific/Midway" | "Pacific/Nauru" | "Pacific/Niue" | "Pacific/Norfolk" | "Pacific/Noumea" | "Pacific/Pago_Pago" | "Pacific/Palau" | "Pacific/Pitcairn" | "Pacific/Ponape" | "Pacific/Port_Moresby" | "Pacific/Rarotonga" | "Pacific/Saipan" | "Pacific/Tahiti" | "Pacific/Tarawa" | "Pacific/Tongatapu" | "Pacific/Truk" | "Pacific/Wake" | "Pacific/Wallis";
+
+/** Singular/plural unit for rate expressions */
+type RateUnit = "minute" | "minutes" | "hour" | "hours" | "day" | "days";
+/**
+ * Rate expression: `rate(1 hour)`, `rate(5 minutes)`, `rate(2 days)`
+ *
+ * Strictly typed — autocomplete and compile-time validation for unit.
+ */
+type RateExpression = `rate(${number} ${RateUnit})`;
+/**
+ * Cron expression: `cron(min hour dom month dow year)`
+ *
+ * Not deeply typed (too combinatorial for TS), but the `cron(...)` wrapper is enforced.
+ *
+ * @example
+ * ```
+ * "cron(0 9 * * ? *)"          // daily at 9:00 UTC
+ * "cron(0 9 ? * MON-FRI *)"    // weekdays at 9:00
+ * "cron(0/15 * * * ? *)"       // every 15 minutes
+ * ```
+ */
+type CronExpression = `cron(${string})`;
+/**
+ * EventBridge Scheduler schedule expression.
+ *
+ * - **Rate**: `"rate(5 minutes)"`, `"rate(1 hour)"`, `"rate(1 day)"` — strictly typed units
+ * - **Cron**: `"cron(0 9 * * ? *)"` — 6 fields: min hour dom month dow year
+ */
+type ScheduleExpression = RateExpression | CronExpression;
+/** Static config extracted at deploy time */
+type CronConfig = {
+    /** Lambda function settings (memory, timeout, permissions, etc.) */
+    lambda?: LambdaWithPermissions;
+    /** EventBridge Scheduler schedule expression */
+    schedule: ScheduleExpression;
+    /** IANA timezone for the schedule (default: UTC) */
+    timezone?: Timezone;
+};
+/** Setup factory — receives deps/config/files based on what was declared */
+type SetupArgs<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {} : {
+    deps: ResolveDeps<D>;
+}) & ([P] extends [undefined] ? {} : {
+    config: ResolveConfig<P & {}>;
+}) & (HasFiles extends true ? {
+    files: StaticFiles;
+} : {});
+/** Spread ctx into callback args (empty when no setup) */
+type SpreadCtx<C> = [C] extends [undefined] ? {} : C & {};
+/** Callback function for cron tick */
+type CronTickFn<C = undefined> = (args: SpreadCtx<C>) => Promise<void> | void;
+/**
+ * Handler object created by defineCron.
+ * @internal
+ */
+type CronHandler<C = any> = {
+    readonly __brand: "effortless-cron";
+    readonly __spec: CronConfig;
+    readonly onError?: (...args: any[]) => any;
+    readonly onCleanup?: (...args: any[]) => any;
+    readonly setup?: (...args: any[]) => C | Promise<C>;
+    readonly deps?: Record<string, unknown> | (() => Record<string, unknown>);
+    readonly config?: Record<string, unknown>;
+    readonly static?: string[];
+    readonly onTick?: (...args: any[]) => any;
+};
+/** Options passed to `defineCron()` — resource config only */
+type CronOptions = {
+    /** EventBridge Scheduler schedule expression: `"rate(5 minutes)"` or `"cron(0 9 * * ? *)"` */
+    schedule: ScheduleExpression;
+    /** IANA timezone for the schedule (default: UTC). Full autocomplete for all timezones. */
+    timezone?: Timezone;
+};
+interface CronBuilder<D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false> {
+    /** Declare handler dependencies (tables, queues, buckets, mailers) */
+    deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): CronBuilder<D2, P, C, HasFiles>;
+    /** Declare SSM secrets */
+    config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): CronBuilder<D, P2, C, HasFiles>;
+    /** Include static files in the Lambda bundle. Chainable — call multiple times. */
+    include(glob: string): CronBuilder<D, P, C, true>;
+    /** Configure Lambda settings only (memory, timeout, permissions, logLevel) */
+    setup(lambda: LambdaOptions): CronBuilder<D, P, C, HasFiles>;
+    /** Initialize shared state on cold start. Receives deps, config, files. */
+    setup<C2>(fn: (args: SetupArgs<D, P, HasFiles>) => C2 | Promise<C2>): CronBuilder<D, P, C2, HasFiles>;
+    /** Initialize shared state on cold start + configure Lambda settings. */
+    setup<C2>(fn: (args: SetupArgs<D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): CronBuilder<D, P, C2, HasFiles>;
+    /** Handle errors thrown by onTick */
+    onError(fn: (args: {
+        error: unknown;
+    } & SpreadCtx<C>) => void): CronBuilder<D, P, C, HasFiles>;
+    /** Cleanup callback — runs after each invocation, before Lambda freezes */
+    onCleanup(fn: (args: SpreadCtx<C>) => void | Promise<void>): CronBuilder<D, P, C, HasFiles>;
+    /** Tick handler — called on each scheduled invocation (terminal) */
+    onTick(fn: CronTickFn<C>): CronHandler<C>;
+}
+/**
+ * Define a cron job — scheduled Lambda invocation via EventBridge Scheduler.
+ *
+ * @example
+ * ```typescript
+ * export const sync = defineCron({ schedule: "cron(0 9 * * ? *)" })
+ *   .deps(() => ({ orders }))
+ *   .config(({ defineSecret }) => ({ apiKey: defineSecret() }))
+ *   .include("templates/*.html")
+ *   .setup(async ({ deps, config, files }) => ({
+ *     db: deps.orders, key: config.apiKey, tpl: files,
+ *   }), { memory: 512 })
+ *   .onTick(async ({ db, key, tpl }) => {
+ *     const html = tpl.read("templates/report.html")
+ *   })
  * ```
  */
-declare const defineApi: () => <C = undefined, D extends Record<string, AnyDepHandler> | undefined = undefined, P extends Record<string, AnySecretRef> | undefined = undefined, S extends string[] | undefined = undefined, ST extends boolean | undefined = undefined>(options: DefineApiOptions<C, D, P, S, ST>) => ApiHandler<C>;
+declare function defineCron(options: CronOptions): CronBuilder;
 
-export { type AnyParamRef, type AnySecretRef, type ApiAuthConfig, type ApiConfig, type ApiHandler, type AppConfig, type AppHandler, type AuthHelpers, type BucketClient, type BucketConfig, type BucketEvent, type BucketHandler, type ConfigHelpers, type ContentType, type DefineSecretFn, type Duration, type EffortlessConfig, type EmailClient, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type GenerateSpec, type HttpMethod$1 as 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 ResponseStream, type SecretRef, type SendEmailOptions, type SendMessageInput, type SkCondition, type StaticFiles, type StaticSiteConfig, type StaticSiteHandler, type StaticSiteSeo, type StreamView, type TableClient, type TableConfig, type TableHandler, type TableItem, type TableKey, type TableRecord, type UpdateActions, defineApi, defineApp, defineBucket, defineConfig, defineFifoQueue, defineMailer, defineSecret, defineStaticSite, defineTable, generateBase64, generateHex, generateUuid, param, result, secret, toSeconds, unsafeAs };
+export { type AnyParamRef, type AnySecretRef, type ApiAuthConfig, type ApiConfig, type ApiHandler, type ApiRoutes, type AppConfig, type AppHandler, type AuthHelpers, type BucketClient, type BucketConfig, type BucketEvent, type BucketHandler, type ConfigHelpers, type ContentType, type CronConfig, type CronHandler, type DefineSecretFn, type Duration, type EffortlessConfig, type EmailClient, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type GenerateSpec, type HttpMethod$1 as 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 ResponseStream, type SecretRef, type SendEmailOptions, type SendMessageInput, type SkCondition, type StaticFiles, type StaticSiteConfig, type StaticSiteHandler, type StaticSiteSeo, type StreamView, type TableClient, type TableConfig, type TableHandler, type TableItem, type TableKey, type TableRecord, type Timezone, type UpdateActions, defineApi, defineApp, defineBucket, defineConfig, defineCron, defineFifoQueue, defineMailer, defineSecret, defineStaticSite, defineTable, generateBase64, generateHex, generateUuid, param, secret, toSeconds };