effortless-aws 0.29.0 → 0.30.0

package/dist/index.d.ts

@@ -253,111 +253,6 @@ type PutInput<T> = {
  */
 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";
 /** Short content-type aliases for common response formats */
@@ -411,13 +306,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 +358,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") */
@@ -495,6 +388,16 @@ type BucketEvent = {
 };
 /** Spread ctx into callback args (empty when no setup) */
 type SpreadCtx$3<C> = [C] extends [undefined] ? {} : C & {};
+/** Setup factory — receives bucket/deps/config/files based on what was declared */
+type SetupArgs$3<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
  */
@@ -507,66 +410,6 @@ type BucketObjectCreatedFn<C = undefined> = (args: {
 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>;
 /**
  * Internal handler object created by defineBucket
  * @internal
@@ -575,7 +418,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 +426,65 @@ type BucketHandler<C = any> = {
     readonly onObjectCreated?: (...args: any[]) => any;
     readonly onObjectRemoved?: (...args: any[]) => any;
 };
+/** Options passed to `defineBucket()` — static config */
+type BucketOptions = {
+    /** Lambda memory in MB (default: 256) */
+    memory?: number;
+    /** Lambda timeout (default: 30s) */
+    timeout?: Duration;
+    /** Additional IAM permissions for the Lambda */
+    permissions?: Permission[];
+    /** Logging verbosity */
+    logLevel?: LogLevel;
+    /** S3 key prefix filter for event notifications (e.g., "uploads/") */
+    prefix?: string;
+    /** S3 key suffix filter for event notifications (e.g., ".jpg") */
+    suffix?: string;
+    /** Static file glob patterns to bundle into the Lambda ZIP */
+    static?: 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>;
+    /** Initialize shared state on cold start. Receives bucket (self-client), deps, config, files. */
+    setup<C2>(fn: (args: SetupArgs$3<D, P, HasFiles>) => C2 | Promise<C2>): BucketBuilder<D, P, C2, HasFiles>;
+    /** Handle errors thrown by callbacks */
+    onError(fn: (args: {
+        error: unknown;
+    } & SpreadCtx$3<C>) => void): BucketBuilder<D, P, C, HasFiles>;
+    /** Cleanup callback — runs after each invocation, before Lambda freezes */
+    onCleanup(fn: (args: SpreadCtx$3<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.
- *
  * @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);
- *   }
- * });
- * ```
+ * export const uploads = defineBucket({ prefix: "images/", suffix: ".jpg" })
+ *   .onObjectCreated(async ({ event, bucket }) => {
+ *     console.log("New upload:", event.key);
+ *   })
  *
- * @example Resource-only bucket (no Lambda)
- * ```typescript
- * export const assets = defineBucket({});
  * ```
  *
- * @example As a dependency
+ * @example Resource-only bucket (no Lambda)
  * ```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 assets = defineBucket().build()
  * ```
  */
-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 & {
+    static: string[];
+}): BucketBuilder<undefined, undefined, undefined, true>;
+declare function defineBucket(options: BucketOptions): BucketBuilder;
 
 /**
  * Configuration options for defining a mailer (SES email identity)
@@ -703,7 +569,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,19 +590,16 @@ 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$2<C> = [C] extends [undefined] ? {} : C & {};
+/** Setup factory — receives deps/config/files based on what was declared */
+type SetupArgs$2<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.
@@ -749,56 +617,6 @@ type FifoQueueBatchFn<T = unknown, C = undefined> = (args: {
 } & SpreadCtx$2<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 +626,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 +634,184 @@ 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> = {
+    /** Lambda memory in MB (default: 256) */
+    memory?: number;
+    /** Lambda timeout (default: 30s) */
+    timeout?: Duration;
+    /** Additional IAM permissions for the Lambda */
+    permissions?: Permission[];
+    /** Logging verbosity */
+    logLevel?: LogLevel;
+    /** 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;
+    /** Static file glob patterns to bundle into the Lambda ZIP */
+    static?: string[];
+};
+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>;
+    /** Initialize shared state on cold start. Receives deps, config, files. */
+    setup<C2>(fn: (args: SetupArgs$2<D, P, HasFiles>) => C2 | Promise<C2>): FifoQueueBuilder<T, D, P, C2, HasFiles>;
+    /** Handle errors thrown by message handlers */
+    onError(fn: (args: {
+        error: unknown;
+    } & SpreadCtx$2<C>) => void): FifoQueueBuilder<T, D, P, C, HasFiles>;
+    /** Cleanup callback — runs after each invocation, before Lambda freezes */
+    onCleanup(fn: (args: SpreadCtx$2<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
- *
- * Creates:
- * - SQS FIFO queue (with `.fifo` suffix)
- * - Lambda function triggered by the queue
- * - Event source mapping with partial batch failure support
+ * Define a FIFO SQS queue with a Lambda message handler.
  *
  * @example Per-message processing
  * ```typescript
- * type OrderEvent = { orderId: string; action: string };
- *
- * export const orderQueue = defineFifoQueue<OrderEvent>({
- *   onMessage: async ({ message }) => {
+ * 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,
- *   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> & {
+    static: string[];
+}): FifoQueueBuilder<T, undefined, undefined, undefined, true>;
+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 +889,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,20 +938,16 @@ 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$1<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 & {};
 /**
@@ -1002,73 +968,10 @@ type TableBatchFn<T = Record<string, unknown>, C = undefined> = (args: {
 } & SpreadCtx$1<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 +979,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,6 +987,55 @@ type TableHandler<T = Record<string, unknown>, C = any> = {
     readonly onRecord?: (...args: any[]) => any;
     readonly onRecordBatch?: (...args: any[]) => any;
 };
+/** Options passed to `defineTable()` — static config, no generics needed for inference */
+type TableOptions<T> = {
+    /** 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 */
+    logLevel?: LogLevel;
+    /** 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;
+    /** Static file glob patterns to bundle into the Lambda ZIP */
+    static?: string[];
+};
+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>;
+    /** Initialize shared state on cold start. Receives table (self-client), deps, config, files. */
+    setup<C2>(fn: (args: SetupArgs$1<T, D, P, HasFiles>) => C2 | Promise<C2>): TableBuilder<T, D, P, C2, HasFiles>;
+    /** Handle errors thrown by onRecord/onRecordBatch */
+    onError(fn: (args: {
+        error: unknown;
+    } & SpreadCtx$1<C>) => void): TableBuilder<T, D, P, C, HasFiles>;
+    /** Cleanup callback — runs after each invocation, before Lambda freezes */
+    onCleanup(fn: (args: SpreadCtx$1<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).
  *
@@ -1092,32 +1044,30 @@ type TableHandler<T = Record<string, unknown>, C = any> = {
  *
  * @example Table with stream handler
  * ```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
+ * @example Table only (no Lambda)
  * ```typescript
- * export const orders = defineTable<OrderData>()({
- *   schema: (input) => OrderSchema.parse(input),
- *   onRecord: async ({ record }) => { ... }
- * });
+ * export const users = defineTable<User>().build()
  * ```
  *
- * @example Table only (no Lambda)
+ * @example Table as dependency (resource-only, no Lambda)
  * ```typescript
- * export const users = defineTable()({});
+ * export const sessions = defineTable<Session>().build()
  * ```
  */
-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> & {
+    static: string[];
+}): TableBuilder<T, undefined, undefined, undefined, true>;
+declare function defineTable<T = Record<string, unknown>>(options: TableOptions<T>): TableBuilder<T>;
 
 /**
  * Configuration for deploying an SSR framework (Nuxt, Astro, etc.)
@@ -1330,7 +1280,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 = {
@@ -1347,29 +1301,33 @@ type SpreadCtx<C> = ([C] extends [undefined] ? {} : Omit<C & {}, 'auth'>) & ([Ex
 type RouteArgs<C, ST> = SpreadCtx<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<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 +1337,104 @@ 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}`;
+    /** 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;
+    /** Enable response streaming. When true, routes receive a `stream` arg for SSE. */
+    stream?: boolean;
+    /** Static file glob patterns to bundle into the Lambda ZIP */
+    static?: string[];
+};
+/**
+ * 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>;
+    /** Initialize shared state on cold start. Receives deps/config/files based on what was declared. */
+    setup<C2>(fn: (args: SetupArgs<D, P, HasFiles>) => ValidateSetupReturn<C2> | Promise<ValidateSetupReturn<C2>>): ApiBuilder<D, P, C2, ST, HasFiles>;
+    /** Handle errors thrown by routes */
+    onError(fn: (args: {
+        error: unknown;
+        req: HttpRequest;
+        ok: OkHelper;
+        fail: FailHelper;
+    } & SpreadCtx<C>) => HttpResponse): ApiBuilder<D, P, C, ST, HasFiles>;
+    /** Cleanup callback — runs after each invocation, before Lambda freezes */
+    onCleanup(fn: (args: SpreadCtx<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.
  *
  * @example
  * ```typescript
- * export default defineApi({
- *   basePath: "/api",
- *   deps: () => ({ users }),
- *   setup: ({ deps }) => ({
+ * // Minimal
+ * export default defineApi({ basePath: "/hello" })
+ *   .get("/", async ({ req, ok }) => ok({ message: "Hello!" }))
+ *
+ * // Full
+ * 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 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 defineApi(options: ApiOptions & {
+    static: string[];
+}): ApiBuilder<undefined, undefined, undefined, false, true>;
+declare function defineApi<const O extends ApiOptions>(options: O): ApiBuilder<undefined, undefined, undefined, O["stream"] extends true ? true : false, O["static"] extends string[] ? true : false>;
 
-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 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, secret, toSeconds, unsafeAs };