effortless-aws 0.32.1 → 0.33.1

package/dist/index.d.ts

@@ -4,13 +4,6 @@
  * @see {@link https://effortless-aws.website/configuration | Configuration guide}
  */
 type EffortlessConfig = {
-    /**
-     * Project root directory. All relative paths (handlers, server, assets, etc.)
-     * are resolved from this directory.
-     * Resolved relative to where the CLI runs (process.cwd()).
-     * @default "." (current working directory)
-     */
-    root?: string;
     /**
      * Project name used for resource naming and tagging.
      * This becomes part of Lambda function names, IAM roles, etc.
@@ -177,8 +170,6 @@ declare const defineSecret: DefineSecretFn;
 declare const secret: DefineSecretFn;
 /** @deprecated Use `SecretRef` instead */
 type ParamRef<T = string> = SecretRef<T>;
-/** @deprecated Use `AnySecretRef` instead */
-type AnyParamRef = AnySecretRef;
 /** @deprecated Use `defineSecret()` instead. */
 declare const param: <T = string>(key: string, transform?: (raw: string) => T) => SecretRef<T>;
 /** @deprecated Use `defineSecret({ generate: "hex:N" })` instead. */
@@ -272,6 +263,12 @@ type HttpResponse = {
     contentType?: ContentType;
     /** Response headers (use for custom content-types not covered by contentType) */
     headers?: Record<string, string>;
+    /**
+     * Multiple Set-Cookie values. Used by Lambda Function URLs to set multiple cookies
+     * in a single response (e.g., session cookie + CloudFront signed cookies).
+     * When present, takes precedence over `set-cookie` in `headers`.
+     */
+    cookies?: string[];
     /**
      * Set to `true` to return binary data.
      * When enabled, `body` must be a base64-encoded string and the response
@@ -326,7 +323,37 @@ type BucketClient = {
     /** The underlying S3 bucket name */
     bucketName: string;
 };
+/**
+ * Typed client for a single entity stored as JSON in a bucket.
+ * Objects are stored at `{entityName}/{id}.json`.
+ */
+type StoreEntityClient<T> = {
+    /** Store a JSON document by id */
+    put(id: string, data: T): Promise<void>;
+    /** Retrieve a JSON document by id. Returns undefined if not found. */
+    get(id: string): Promise<T | undefined>;
+    /** Delete a document by id */
+    delete(id: string): Promise<void>;
+    /** List all documents for this entity */
+    list(): Promise<{
+        id: string;
+        data: T;
+    }[]>;
+};
+/**
+ * BucketClient extended with typed entity clients.
+ */
+type BucketClientWithEntities<Entities extends Record<string, any>> = BucketClient & {
+    [K in keyof Entities]: StoreEntityClient<Entities[K]>;
+};
 
+/**
+ * Per-entity configuration for typed JSON key-value storage within a bucket.
+ */
+type BucketEntityConfig = {
+    /** Cache duration for CloudFront/browser caching (e.g., "10s", "5m", "1h"). No caching if omitted. */
+    cache?: Duration;
+};
 /**
  * Configuration options for defineBucket.
  */
@@ -342,6 +369,8 @@ type BucketConfig = {
     prefix?: string;
     /** S3 key suffix filter for event notifications (e.g., ".jpg") */
     suffix?: string;
+    /** Typed JSON entity definitions for key-value storage */
+    entities?: Record<string, BucketEntityConfig>;
 };
 /**
  * S3 event record passed to onObjectCreated/onObjectRemoved callbacks.
@@ -361,10 +390,10 @@ type BucketEvent = {
     bucketName: string;
 };
 /** Spread ctx into callback args (empty when no setup) */
-type SpreadCtx$5<C> = [C] extends [undefined] ? {} : C & {};
+type SpreadCtx$6<C> = [C] extends [undefined] ? {} : C & {};
 /** Setup factory — receives bucket/deps/config/files based on what was declared */
-type SetupArgs$5<D, P, HasFiles extends boolean> = {
-    bucket: BucketClient;
+type SetupArgs$6<D, P, HasFiles extends boolean, Entities extends Record<string, any> = {}> = {
+    bucket: {} extends Entities ? BucketClient : BucketClientWithEntities<Entities>;
 } & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
@@ -377,18 +406,18 @@ type SetupArgs$5<D, P, HasFiles extends boolean> = {
  */
 type BucketObjectCreatedFn<C = undefined> = (args: {
     event: BucketEvent;
-} & SpreadCtx$5<C>) => Promise<void>;
+} & SpreadCtx$6<C>) => Promise<void>;
 /**
  * Callback function type for S3 ObjectRemoved events
  */
 type BucketObjectRemovedFn<C = undefined> = (args: {
     event: BucketEvent;
-} & SpreadCtx$5<C>) => Promise<void>;
+} & SpreadCtx$6<C>) => Promise<void>;
 /**
  * Internal handler object created by defineBucket
  * @internal
  */
-type BucketHandler<C = any> = {
+type BucketHandler$1<C = any, Entities extends Record<string, any> = {}> = {
     readonly __brand: "effortless-bucket";
     readonly __spec: BucketConfig;
     readonly onError?: (...args: any[]) => any;
@@ -407,31 +436,35 @@ type BucketOptions = {
     /** S3 key suffix filter for event notifications (e.g., ".jpg") */
     suffix?: string;
 };
-interface BucketBuilder<D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false> {
+interface BucketBuilder<D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false, Entities extends Record<string, any> = {}> {
     /** Declare handler dependencies */
-    deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): BucketBuilder<D2, P, C, HasFiles>;
+    deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): BucketBuilder<D2, P, C, HasFiles, Entities>;
     /** Declare SSM secrets */
-    config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): BucketBuilder<D, P2, C, HasFiles>;
+    config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): BucketBuilder<D, P2, C, HasFiles, Entities>;
     /** Include static files in the Lambda ZIP */
-    include(glob: string): BucketBuilder<D, P, C, true>;
+    include(glob: string): BucketBuilder<D, P, C, true, Entities>;
+    /** Register a typed JSON entity stored as `{name}/{id}.json` in the bucket */
+    entity<N extends string, T>(name: N, options?: BucketEntityConfig): BucketBuilder<D, P, C, HasFiles, Entities & {
+        [K in N]: T;
+    }>;
     /** Initialize shared state on cold start with lambda options */
-    setup(lambda: LambdaOptions): BucketBuilder<D, P, C, HasFiles>;
+    setup(lambda: LambdaOptions): BucketBuilder<D, P, C, HasFiles, Entities>;
     /** Initialize shared state on cold start. Receives bucket (self-client), deps, config, files. */
-    setup<C2>(fn: (args: SetupArgs$5<D, P, HasFiles>) => C2 | Promise<C2>): BucketBuilder<D, P, C2, HasFiles>;
+    setup<C2>(fn: (args: SetupArgs$6<D, P, HasFiles, Entities>) => C2 | Promise<C2>): BucketBuilder<D, P, C2, HasFiles, Entities>;
     /** Initialize shared state on cold start with lambda options. Receives bucket (self-client), deps, config, files. */
-    setup<C2>(fn: (args: SetupArgs$5<D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): BucketBuilder<D, P, C2, HasFiles>;
+    setup<C2>(fn: (args: SetupArgs$6<D, P, HasFiles, Entities>) => C2 | Promise<C2>, lambda: LambdaOptions): BucketBuilder<D, P, C2, HasFiles, Entities>;
     /** Handle errors thrown by callbacks */
     onError(fn: (args: {
         error: unknown;
-    } & SpreadCtx$5<C>) => void | Promise<void>): BucketBuilder<D, P, C, HasFiles>;
+    } & SpreadCtx$6<C>) => void | Promise<void>): BucketBuilder<D, P, C, HasFiles, Entities>;
     /** Cleanup callback — runs after each invocation, before Lambda freezes */
-    onCleanup(fn: (args: SpreadCtx$5<C>) => void | Promise<void>): BucketBuilder<D, P, C, HasFiles>;
+    onCleanup(fn: (args: SpreadCtx$6<C>) => void | Promise<void>): BucketBuilder<D, P, C, HasFiles, Entities>;
     /** Handle S3 ObjectCreated events (terminal — returns finalized handler) */
-    onObjectCreated(fn: BucketObjectCreatedFn<C>): BucketHandler<C>;
+    onObjectCreated(fn: BucketObjectCreatedFn<C>): BucketHandler$1<C, Entities>;
     /** Handle S3 ObjectRemoved events (terminal — returns finalized handler) */
-    onObjectRemoved(fn: BucketObjectRemovedFn<C>): BucketHandler<C>;
+    onObjectRemoved(fn: BucketObjectRemovedFn<C>): BucketHandler$1<C, Entities>;
     /** Finalize as resource-only bucket (no Lambda) */
-    build(): BucketHandler<C>;
+    build(): BucketHandler$1<C, Entities>;
 }
 /**
  * Define an S3 bucket with optional event handlers.
@@ -556,9 +589,9 @@ type FifoQueueConfig = {
     maxReceiveCount?: number;
 };
 /** Spread ctx into callback args (empty when no setup) */
-type SpreadCtx$4<C> = [C] extends [undefined] ? {} : C & {};
+type SpreadCtx$5<C> = [C] extends [undefined] ? {} : C & {};
 /** Setup factory — receives deps/config/files based on what was declared */
-type SetupArgs$4<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {} : {
+type SetupArgs$5<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
     config: ResolveConfig<P & {}>;
@@ -571,7 +604,7 @@ type SetupArgs$4<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {}
  */
 type FifoQueueMessageFn<T = unknown, C = undefined> = (args: {
     message: FifoQueueMessage<T>;
-} & SpreadCtx$4<C>) => Promise<void>;
+} & SpreadCtx$5<C>) => Promise<void>;
 /**
  * Batch handler function.
  * Called once with all messages in the batch.
@@ -579,14 +612,14 @@ type FifoQueueMessageFn<T = unknown, C = undefined> = (args: {
  */
 type FifoQueueBatchFn<T = unknown, C = undefined> = (args: {
     messages: FifoQueueMessage<T>[];
-} & SpreadCtx$4<C>) => Promise<void | {
+} & SpreadCtx$5<C>) => Promise<void | {
     failures: string[];
 }>;
 /**
  * Internal handler object created by defineFifoQueue
  * @internal
  */
-type FifoQueueHandler<T = unknown, C = any> = {
+type FifoQueueHandler$1<T = unknown, C = any> = {
     readonly __brand: "effortless-fifo-queue";
     readonly __spec: FifoQueueConfig;
     readonly schema?: (input: unknown) => T;
@@ -628,19 +661,19 @@ interface FifoQueueBuilder<T = unknown, D = undefined, P = undefined, C = undefi
     /** 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$4<D, P, HasFiles>) => C2 | Promise<C2>): FifoQueueBuilder<T, D, P, C2, HasFiles>;
+    setup<C2>(fn: (args: SetupArgs$5<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$4<D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): FifoQueueBuilder<T, D, P, C2, HasFiles>;
+    setup<C2>(fn: (args: SetupArgs$5<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$4<C>) => void | Promise<void>): FifoQueueBuilder<T, D, P, C, HasFiles>;
+    } & SpreadCtx$5<C>) => void | Promise<void>): FifoQueueBuilder<T, D, P, C, HasFiles>;
     /** Cleanup callback — runs after each invocation, before Lambda freezes */
-    onCleanup(fn: (args: SpreadCtx$4<C>) => void | Promise<void>): FifoQueueBuilder<T, D, P, C, HasFiles>;
+    onCleanup(fn: (args: SpreadCtx$5<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>;
+    onMessage(fn: FifoQueueMessageFn<T, C>): FifoQueueHandler$1<T, C>;
     /** Batch handler (terminal — returns finalized handler) */
-    onMessageBatch(fn: FifoQueueBatchFn<T, C>): FifoQueueHandler<T, C>;
+    onMessageBatch(fn: FifoQueueBatchFn<T, C>): FifoQueueHandler$1<T, C>;
 }
 /**
  * Define a FIFO SQS queue with a Lambda message handler.
@@ -672,7 +705,7 @@ type WorkerConfig = {
     concurrency?: number;
 };
 /** Setup factory — receives deps/config/files based on what was declared */
-type SetupArgs$3<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {} : {
+type SetupArgs$4<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
     config: ResolveConfig<P & {}>;
@@ -680,14 +713,14 @@ type SetupArgs$3<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {}
     files: StaticFiles;
 } : {});
 /** 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 & {};
 /** Callback function for the worker's onMessage */
-type WorkerMessageFn<T, C = undefined> = (msg: T, ctx: SpreadCtx$3<C>) => Promise<void> | void;
+type WorkerMessageFn<T, C = undefined> = (msg: T, ctx: SpreadCtx$4<C>) => Promise<void> | void;
 /**
  * Handler object created by defineWorker.
  * @internal
  */
-type WorkerHandler<T = any, C = any> = {
+type WorkerHandler$1<T = any, C = any> = {
     readonly __brand: "effortless-worker";
     readonly __spec: WorkerConfig;
     readonly onError?: (...args: any[]) => any;
@@ -717,19 +750,19 @@ interface WorkerBuilder<T, D = undefined, P = undefined, C = undefined, HasFiles
     /** Configure Lambda settings only (memory, timeout, permissions, logLevel) */
     setup(lambda: LambdaOptions): WorkerBuilder<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>): WorkerBuilder<T, D, P, C2, HasFiles>;
+    setup<C2>(fn: (args: SetupArgs$4<D, P, HasFiles>) => C2 | Promise<C2>): WorkerBuilder<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): WorkerBuilder<T, D, P, C2, HasFiles>;
+    setup<C2>(fn: (args: SetupArgs$4<D, P, HasFiles>) => C2 | Promise<C2>, lambda: LambdaOptions): WorkerBuilder<T, D, P, C2, HasFiles>;
     /** Handle errors thrown by onMessage. Return "delete" to discard, "retry" to reprocess (default). */
     onError(fn: (args: {
         error: unknown;
         msg: T;
         retryCount: number;
-    } & SpreadCtx$3<C>) => "retry" | "delete" | void | Promise<"retry" | "delete" | void>): WorkerBuilder<T, D, P, C, HasFiles>;
+    } & SpreadCtx$4<C>) => "retry" | "delete" | void | Promise<"retry" | "delete" | void>): WorkerBuilder<T, D, P, C, HasFiles>;
     /** Cleanup callback — runs when the worker shuts down */
-    onCleanup(fn: (args: SpreadCtx$3<C>) => void | Promise<void>): WorkerBuilder<T, D, P, C, HasFiles>;
+    onCleanup(fn: (args: SpreadCtx$4<C>) => void | Promise<void>): WorkerBuilder<T, D, P, C, HasFiles>;
     /** Process a single message from the queue (terminal) */
-    onMessage(fn: WorkerMessageFn<T, C>): WorkerHandler<T, C>;
+    onMessage(fn: WorkerMessageFn<T, C>): WorkerHandler$1<T, C>;
 }
 /**
  * Define a worker — a long-running Fargate container with an SQS queue.
@@ -935,10 +968,10 @@ type WorkerClient<T = unknown> = {
 };
 
 /** Dep value types supported by the deps declaration */
-type AnyDepHandler = TableHandler<any, any> | BucketHandler<any> | MailerHandler | FifoQueueHandler<any, any> | WorkerHandler<any, any>;
+type AnyDepHandler = TableHandler$1<any, any> | BucketHandler$1<any, any> | MailerHandler | FifoQueueHandler$1<any, any> | WorkerHandler$1<any, any>;
 /** Maps a deps declaration to resolved runtime client types */
 type ResolveDeps<D> = {
-    [K in keyof D]: D[K] extends TableHandler<infer T> ? TableClient<T> : D[K] extends BucketHandler ? BucketClient : D[K] extends MailerHandler ? EmailClient : D[K] extends FifoQueueHandler<infer T> ? QueueClient<T> : D[K] extends WorkerHandler<infer T> ? WorkerClient<T> : never;
+    [K in keyof D]: D[K] extends TableHandler$1<infer T> ? TableClient<T> : D[K] extends BucketHandler$1<any, infer E> ? ({} extends E ? BucketClient : BucketClientWithEntities<E>) : D[K] extends MailerHandler ? EmailClient : D[K] extends FifoQueueHandler$1<infer T> ? QueueClient<T> : D[K] extends WorkerHandler$1<infer T> ? WorkerClient<T> : never;
 };
 
 /** DynamoDB Streams view type - determines what data is captured in stream records */
@@ -1001,7 +1034,7 @@ type TableRecord<T = Record<string, unknown>> = {
     timestamp?: number;
 };
 /** Setup factory — receives table/deps/config/files based on what was declared */
-type SetupArgs$2<T, D, P, HasFiles extends boolean> = {
+type SetupArgs$3<T, D, P, HasFiles extends boolean> = {
     table: TableClient<T>;
 } & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
@@ -1011,7 +1044,7 @@ type SetupArgs$2<T, D, P, HasFiles extends boolean> = {
     files: StaticFiles;
 } : {});
 /** Spread ctx into callback args (empty when no setup) */
-type SpreadCtx$2<C> = [C] extends [undefined] ? {} : C & {};
+type SpreadCtx$3<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.
@@ -1019,7 +1052,7 @@ type SpreadCtx$2<C> = [C] extends [undefined] ? {} : C & {};
 type TableRecordFn<T = Record<string, unknown>, C = undefined> = (args: {
     record: TableRecord<T>;
     batch: readonly TableRecord<T>[];
-} & SpreadCtx$2<C>) => Promise<void>;
+} & SpreadCtx$3<C>) => Promise<void>;
 /**
  * Batch handler function for DynamoDB stream records.
  * Called once with all records in the batch.
@@ -1027,7 +1060,7 @@ type TableRecordFn<T = Record<string, unknown>, C = undefined> = (args: {
  */
 type TableBatchFn<T = Record<string, unknown>, C = undefined> = (args: {
     records: readonly TableRecord<T>[];
-} & SpreadCtx$2<C>) => Promise<void | {
+} & SpreadCtx$3<C>) => Promise<void | {
     failures: string[];
 }>;
 /** Static config extracted by AST (no runtime callbacks) */
@@ -1036,7 +1069,7 @@ type TableBatchFn<T = Record<string, unknown>, C = undefined> = (args: {
  * Used by runtime wrappers and as type annotation for circular deps.
  * @internal
  */
-type TableHandler<T = Record<string, unknown>, C = any> = {
+type TableHandler$1<T = Record<string, unknown>, C = any> = {
     readonly __brand: "effortless-table";
     readonly __spec: TableConfig;
     readonly schema?: (input: unknown) => T;
@@ -1078,21 +1111,21 @@ interface TableBuilder<T = Record<string, unknown>, D = undefined, P = undefined
     /** 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>;
+    setup<C2>(fn: (args: SetupArgs$3<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>;
+    setup<C2>(fn: (args: SetupArgs$3<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 | Promise<void>): TableBuilder<T, D, P, C, HasFiles>;
+    } & SpreadCtx$3<C>) => void | Promise<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>;
+    onCleanup(fn: (args: SpreadCtx$3<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>;
+    onRecord(fn: TableRecordFn<T, C>): TableHandler$1<T, C>;
     /** Batch stream handler (terminal — returns finalized handler) */
-    onRecordBatch(fn: TableBatchFn<T, C>): TableHandler<T, C>;
+    onRecordBatch(fn: TableBatchFn<T, C>): TableHandler$1<T, C>;
     /** Finalize as resource-only table (no Lambda) */
-    build(): TableHandler<T, C>;
+    build(): TableHandler$1<T, C>;
 }
 /**
  * Define a DynamoDB table with optional stream handler (single-table design).
@@ -1169,6 +1202,18 @@ declare const defineApp: () => (options: AppConfig) => AppHandler;
 type AnyRoutableHandler = {
     readonly __brand: string;
 };
+/** Route configuration for serving bucket content through CloudFront */
+type BucketRouteConfig = {
+    bucket: {
+        readonly __brand: "effortless-bucket";
+    };
+    /** Access control: "private" requires CloudFront signed cookies, "public" serves openly. Default: "public" */
+    access?: "private" | "public";
+};
+/** A route value: either an API handler or a bucket route config */
+type RouteValue = AnyRoutableHandler | BucketRouteConfig;
+/** Type guard for bucket route entries */
+declare const isBucketRoute: (v: unknown) => v is BucketRouteConfig;
 /** Simplified request object passed to middleware */
 type MiddlewareRequest = {
     uri: string;
@@ -1215,10 +1260,10 @@ type StaticSiteConfig = {
     build?: string;
     /** Custom domain name. Accepts a string (same domain for all stages) or a Record mapping stage names to domains (e.g., `{ prod: "example.com", dev: "dev.example.com" }`). Requires an ACM certificate in us-east-1. If the cert also covers www, a 301 redirect from www to non-www is set up automatically. */
     domain?: string | Record<string, string>;
-    /** CloudFront route overrides: path patterns forwarded to API Gateway instead of S3.
-     * Keys are CloudFront path patterns (e.g., "/api/*"), values are HTTP handlers.
-     * Example: `routes: { "/api/*": api }` */
-    routes?: Record<string, AnyRoutableHandler>;
+    /** CloudFront route overrides: path patterns forwarded to API Gateway or S3 bucket origins.
+     * Keys are CloudFront path patterns (e.g., "/api/*"), values are HTTP handlers or bucket route configs.
+     * Example: `routes: { "/api/*": api, "/files/*": { bucket: storage, access: "private" } }` */
+    routes?: Record<string, RouteValue>;
     /** Custom 404 error page path relative to `dir` (e.g. "404.html").
      * For non-SPA sites only. If not set, a default page is generated automatically. */
     errorPage?: string;
@@ -1245,17 +1290,27 @@ type StaticSiteHandler = {
  */
 declare const defineStaticSite: () => (options: StaticSiteConfig) => StaticSiteHandler;
 
+/** Options for CloudFront signed cookie policy */
+type CdnPolicyOptions = {
+    /** Path pattern to grant access to (e.g., "/files/users/123/*"). Supports `*` and `?` wildcards. */
+    path: string;
+    /** How long the CDN access is valid (e.g., "1h", "30m") */
+    ttl: Duration;
+};
 /** Options for creating a session */
 type SessionOptions = {
     expiresIn?: Duration;
+    /** CloudFront signed cookie policy for CDN-level access control */
+    cdnPolicy?: CdnPolicyOptions;
 };
-/** Session response with Set-Cookie header */
+/** Session response with Set-Cookie headers */
 type SessionResponse = {
     status: 200;
     body: {
         ok: true;
     };
     headers: Record<string, string>;
+    cookies?: string[];
 };
 /**
  * Auth helpers injected into API handler callback args when `auth` is configured.
@@ -1309,19 +1364,35 @@ 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";
+/** Cache options for a GET route. Duration shorthand (e.g. "30s", "5m") or object for fine-grained control. */
+type CacheOptions = Duration | {
+    ttl: Duration;
+    swr?: Duration;
+    scope?: "public" | "private";
+};
+/** Resolved cache config with numeric seconds */
+type ResolvedCache = {
+    private?: false;
+    ttl: number;
+    swr: number;
+} | {
+    private: true;
+    ttl: number;
+};
 /** Parsed route definition stored at runtime */
 type RouteEntry = {
     method: HttpMethod;
     path: string;
     onRequest: (...args: any[]) => any;
     public?: boolean;
+    cache?: ResolvedCache;
 };
 /** Spread ctx into route args: Omit auth config, add AuthHelpers if present */
-type SpreadCtx$1<C> = ([C] extends [undefined] ? {} : Omit<C & {}, 'auth'>) & ([ExtractAuth<C>] extends [undefined] ? {} : {
+type SpreadCtx$2<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$1<C> & {
+type RouteArgs<C, ST> = SpreadCtx$2<C> & {
     req: HttpRequest;
     input: unknown;
     ok: OkHelper;
@@ -1331,12 +1402,16 @@ type RouteArgs<C, ST> = SpreadCtx$1<C> & {
 } : {});
 /** Route handler function */
 type RouteHandler<C, ST> = (args: RouteArgs<C, ST>) => Promise<HttpResponse | void> | HttpResponse | void;
-/** Route options (e.g. public) */
+/** Route options for all methods */
 type RouteOptions = {
     public?: boolean;
 };
+/** Route options for GET — supports caching */
+type GetRouteOptions = RouteOptions & {
+    cache?: CacheOptions;
+};
 /** Setup factory — receives deps/config/files/enableAuth based on what was declared */
-type SetupArgs$1<D, P, HasFiles extends boolean> = {
+type SetupArgs$2<D, P, HasFiles extends boolean> = {
     enableAuth: EnableAuth;
     ok: OkHelper;
     fail: FailHelper;
@@ -1384,7 +1459,7 @@ type ApiOptions = {
  * 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>;
+    get(path: `/${string}`, handler: RouteHandler<C, ST>, options?: GetRouteOptions): 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>;
@@ -1406,20 +1481,20 @@ interface ApiBuilder<D = undefined, P = undefined, C = undefined, ST extends boo
     /** 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>;
+    setup<C2>(fn: (args: SetupArgs$2<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>;
+    setup<C2>(fn: (args: SetupArgs$2<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 | Promise<HttpResponse>): ApiBuilder<D, P, C, ST, HasFiles>;
+    } & SpreadCtx$2<C>) => HttpResponse | Promise<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>;
+    onCleanup(fn: (args: SpreadCtx$2<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>;
+    get(path: `/${string}`, handler: RouteHandler<C, ST>, options?: GetRouteOptions): 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) */
@@ -1494,7 +1569,7 @@ type CronConfig = {
     timezone?: Timezone;
 };
 /** Setup factory — receives deps/config/files based on what was declared */
-type SetupArgs<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {} : {
+type SetupArgs$1<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
     config: ResolveConfig<P & {}>;
@@ -1502,14 +1577,14 @@ type SetupArgs<D, P, HasFiles extends boolean> = ([D] extends [undefined] ? {} :
     files: StaticFiles;
 } : {});
 /** Spread ctx into callback args (empty when no setup) */
-type SpreadCtx<C> = [C] extends [undefined] ? {} : C & {};
+type SpreadCtx$1<C> = [C] extends [undefined] ? {} : C & {};
 /** Callback function for cron tick */
-type CronTickFn<C = undefined> = (args: SpreadCtx<C>) => Promise<void> | void;
+type CronTickFn<C = undefined> = (args: SpreadCtx$1<C>) => Promise<void> | void;
 /**
  * Handler object created by defineCron.
  * @internal
  */
-type CronHandler<C = any> = {
+type CronHandler$1<C = any> = {
     readonly __brand: "effortless-cron";
     readonly __spec: CronConfig;
     readonly onError?: (...args: any[]) => any;
@@ -1537,17 +1612,17 @@ interface CronBuilder<D = undefined, P = undefined, C = undefined, HasFiles exte
     /** 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>;
+    setup<C2>(fn: (args: SetupArgs$1<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>;
+    setup<C2>(fn: (args: SetupArgs$1<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 | Promise<void>): CronBuilder<D, P, C, HasFiles>;
+    } & SpreadCtx$1<C>) => void | Promise<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>;
+    onCleanup(fn: (args: SpreadCtx$1<C>) => void | Promise<void>): CronBuilder<D, P, C, HasFiles>;
     /** Tick handler — called on each scheduled invocation (terminal) */
-    onTick(fn: CronTickFn<C>): CronHandler<C>;
+    onTick(fn: CronTickFn<C>): CronHandler$1<C>;
 }
 /**
  * Define a cron job — scheduled Lambda invocation via EventBridge Scheduler.
@@ -1568,4 +1643,135 @@ interface CronBuilder<D = undefined, P = undefined, C = undefined, HasFiles exte
  */
 declare function defineCron(options: CronOptions): CronBuilder;
 
-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, type WorkerClient, type WorkerConfig, type WorkerHandler, type WorkerSendOptions, defineApi, defineApp, defineBucket, defineConfig, defineCron, defineFifoQueue, defineMailer, defineSecret, defineStaticSite, defineTable, defineWorker, generateBase64, generateHex, generateUuid, param, secret, toSeconds };
+/** Static config extracted at deploy time */
+type McpConfig = {
+    /** MCP server name (used in server info) */
+    name: string;
+    /** MCP server version (default: "1.0.0") */
+    version?: string;
+    /** Lambda function settings (memory, timeout, permissions, etc.) */
+    lambda?: LambdaWithPermissions;
+};
+/** JSON Schema for a tool's input parameters */
+type McpInputSchema = {
+    type: "object";
+    properties: Record<string, unknown>;
+    required?: string[];
+};
+/** Content block returned by a tool handler */
+type McpToolContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+} | {
+    type: "resource";
+    resource: {
+        uri: string;
+        text: string;
+        mimeType?: string;
+    };
+};
+/** Result returned by a tool handler */
+type McpToolResult = {
+    content: McpToolContent[];
+    isError?: boolean;
+};
+/** A single MCP tool definition */
+type McpToolDef<C = undefined> = {
+    /** Human-readable description of the tool */
+    description: string;
+    /** JSON Schema describing the tool's input parameters */
+    input: McpInputSchema;
+    /** Handler function called when the tool is invoked */
+    handler: (input: any, ctx: SpreadCtx<C>) => McpToolResult | Promise<McpToolResult>;
+};
+/** 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 & {};
+/**
+ * Handler object created by defineMcp.
+ * @internal
+ */
+type McpHandler$1<C = any> = {
+    readonly __brand: "effortless-mcp";
+    readonly __spec: McpConfig;
+    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 tools?: (...args: any[]) => any;
+};
+/** Options passed to `defineMcp()` */
+type McpOptions = {
+    /** MCP server name (used in server info) */
+    name: string;
+    /** MCP server version (default: "1.0.0") */
+    version?: string;
+};
+interface McpBuilder<D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false> {
+    /** Declare handler dependencies (tables, queues, buckets, mailers, workers) */
+    deps<D2 extends Record<string, AnyDepHandler>>(fn: () => D2): McpBuilder<D2, P, C, HasFiles>;
+    /** Declare SSM secrets */
+    config<P2 extends Record<string, AnySecretRef>>(fn: ConfigFactory<P2>): McpBuilder<D, P2, C, HasFiles>;
+    /** Include static files in the bundle. Chainable — call multiple times. */
+    include(glob: string): McpBuilder<D, P, C, true>;
+    /** Configure Lambda settings only (memory, timeout, permissions, logLevel) */
+    setup(lambda: LambdaOptions): McpBuilder<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>): McpBuilder<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): McpBuilder<D, P, C2, HasFiles>;
+    /** Handle errors thrown by tool handlers */
+    onError(fn: (args: {
+        error: unknown;
+        toolName: string;
+    } & SpreadCtx<C>) => void | Promise<void>): McpBuilder<D, P, C, HasFiles>;
+    /** Cleanup callback — runs on shutdown */
+    onCleanup(fn: (args: SpreadCtx<C>) => void | Promise<void>): McpBuilder<D, P, C, HasFiles>;
+    /** Define MCP tools (terminal) */
+    tools(fn: (ctx: SpreadCtx<C>) => Record<string, McpToolDef<C>>): McpHandler$1<C>;
+}
+/**
+ * Define an MCP (Model Context Protocol) server endpoint.
+ *
+ * Creates a Lambda-backed MCP server that exposes tools for AI models
+ * and MCP-compatible clients to discover and invoke.
+ *
+ * @example
+ * ```typescript
+ * export const mcp = defineMcp({ name: "my-tools" })
+ *   .deps(() => ({ users: usersTable }))
+ *   .setup(({ deps }) => ({ db: deps.users }))
+ *   .tools(({ db }) => ({
+ *     get_user: {
+ *       description: "Get a user by ID",
+ *       input: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+ *       handler: async (input) => ({
+ *         content: [{ type: "text", text: JSON.stringify(await db.get({ pk: input.id, sk: "profile" })) }]
+ *       })
+ *     }
+ *   }))
+ * ```
+ */
+declare function defineMcp(options: McpOptions): McpBuilder;
+
+type TableHandler<T = Record<string, unknown>> = TableHandler$1<T, any>;
+type FifoQueueHandler<T = unknown> = FifoQueueHandler$1<T, any>;
+type BucketHandler<Entities extends Record<string, any> = {}> = BucketHandler$1<any, Entities>;
+type CronHandler = CronHandler$1<any>;
+type WorkerHandler<T = any> = WorkerHandler$1<T, any>;
+type McpHandler = McpHandler$1<any>;
+
+export { type ApiAuthConfig, type ApiConfig, type ApiHandler, type ApiRoutes, type AppConfig, type AppHandler, type AuthHelpers, type BucketClient, type BucketClientWithEntities, type BucketConfig, type BucketEntityConfig, type BucketEvent, type BucketHandler, type BucketRouteConfig, type CacheOptions, type CdnPolicyOptions, type ConfigHelpers, type ContentType, type CronConfig, type CronHandler, type DefineSecretFn, type Duration, type EffortlessConfig, type EmailClient, type FifoQueueConfig, type FifoQueueHandler, type FifoQueueMessage, type HttpMethod$1 as HttpMethod, type HttpRequest, type HttpResponse, type LogLevel, type MailerConfig, type MailerHandler, type McpConfig, type McpHandler, type McpInputSchema, type McpToolContent, type McpToolDef, type McpToolResult, 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 StoreEntityClient, type StreamView, type TableClient, type TableConfig, type TableHandler, type TableItem, type TableKey, type TableRecord, type Timezone, type UpdateActions, type WorkerClient, type WorkerConfig, type WorkerHandler, type WorkerSendOptions, defineApi, defineApp, defineBucket, defineConfig, defineCron, defineFifoQueue, defineMailer, defineMcp, defineSecret, defineStaticSite, defineTable, defineWorker, generateBase64, generateHex, generateUuid, isBucketRoute, param, secret, toSeconds };