effortless-aws 0.33.0 → 0.34.0

package/dist/index.d.ts

@@ -263,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
@@ -317,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.
  */
@@ -333,6 +369,12 @@ 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>;
+    /** Local directory to seed into bucket on deploy (only uploads files that don't already exist) */
+    seed?: string;
+    /** Local directory to sync into bucket on every deploy (uploads new/changed, deletes removed) */
+    sync?: string;
 };
 /**
  * S3 event record passed to onObjectCreated/onObjectRemoved callbacks.
@@ -354,8 +396,8 @@ type BucketEvent = {
 /** Spread ctx into callback args (empty when no setup) */
 type SpreadCtx$6<C> = [C] extends [undefined] ? {} : C & {};
 /** Setup factory — receives bucket/deps/config/files based on what was declared */
-type SetupArgs$6<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] ? {} : {
@@ -379,7 +421,7 @@ type BucketObjectRemovedFn<C = undefined> = (args: {
  * Internal handler object created by defineBucket
  * @internal
  */
-type BucketHandler$1<C = any> = {
+type BucketHandler$1<C = any, Entities extends Record<string, any> = {}> = {
     readonly __brand: "effortless-bucket";
     readonly __spec: BucketConfig;
     readonly onError?: (...args: any[]) => any;
@@ -397,32 +439,40 @@ type BucketOptions = {
     prefix?: string;
     /** S3 key suffix filter for event notifications (e.g., ".jpg") */
     suffix?: string;
+    /** Local directory to seed into bucket on deploy (only uploads files that don't already exist) */
+    seed?: string;
+    /** Local directory to sync into bucket on every deploy (uploads new/changed, deletes removed) */
+    sync?: 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$6<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$6<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$6<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$6<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$1<C>;
+    onObjectCreated(fn: BucketObjectCreatedFn<C>): BucketHandler$1<C, Entities>;
     /** Handle S3 ObjectRemoved events (terminal — returns finalized handler) */
-    onObjectRemoved(fn: BucketObjectRemovedFn<C>): BucketHandler$1<C>;
+    onObjectRemoved(fn: BucketObjectRemovedFn<C>): BucketHandler$1<C, Entities>;
     /** Finalize as resource-only bucket (no Lambda) */
-    build(): BucketHandler$1<C>;
+    build(): BucketHandler$1<C, Entities>;
 }
 /**
  * Define an S3 bucket with optional event handlers.
@@ -926,10 +976,10 @@ type WorkerClient<T = unknown> = {
 };
 
 /** Dep value types supported by the deps declaration */
-type AnyDepHandler = TableHandler$1<any, any> | BucketHandler$1<any> | MailerHandler | FifoQueueHandler$1<any, any> | WorkerHandler$1<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$1<infer T> ? TableClient<T> : D[K] extends BucketHandler$1 ? BucketClient : D[K] extends MailerHandler ? EmailClient : D[K] extends FifoQueueHandler$1<infer T> ? QueueClient<T> : D[K] extends WorkerHandler$1<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 */
@@ -1160,6 +1210,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;
@@ -1206,10 +1268,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;
@@ -1236,17 +1298,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.
@@ -1300,12 +1372,28 @@ 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$2<C> = ([C] extends [undefined] ? {} : Omit<C & {}, 'auth'>) & ([ExtractAuth<C>] extends [undefined] ? {} : {
@@ -1322,10 +1410,14 @@ type RouteArgs<C, ST> = SpreadCtx$2<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$2<D, P, HasFiles extends boolean> = {
     enableAuth: EnableAuth;
@@ -1375,7 +1467,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>;
@@ -1410,7 +1502,7 @@ interface ApiBuilder<D = undefined, P = undefined, C = undefined, ST extends boo
     /** Cleanup callback — runs after each invocation, before Lambda freezes */
     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) */
@@ -1565,6 +1657,8 @@ type McpConfig = {
     name: string;
     /** MCP server version (default: "1.0.0") */
     version?: string;
+    /** Human-readable description — sent to clients in initialize response as system prompt context */
+    instructions?: string;
     /** Lambda function settings (memory, timeout, permissions, etc.) */
     lambda?: LambdaWithPermissions;
 };
@@ -1595,8 +1689,93 @@ type McpToolResult = {
     content: McpToolContent[];
     isError?: boolean;
 };
+/** Content returned when reading a resource */
+type McpResourceContent = {
+    uri: string;
+    mimeType?: string;
+    text: string;
+} | {
+    uri: string;
+    mimeType?: string;
+    blob: string;
+};
+/** A static resource definition */
+type McpResourceDef$1<C = undefined> = {
+    /** Human-readable name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Optional MIME type */
+    mimeType?: string;
+    /** Handler called on resources/read */
+    handler: (ctx: SpreadCtx<C>) => McpResourceContent | McpResourceContent[] | Promise<McpResourceContent | McpResourceContent[]>;
+};
+/** A parameterized resource template (URI template RFC 6570) */
+type McpResourceTemplateDef$1<C = undefined> = {
+    /** Human-readable name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Optional MIME type */
+    mimeType?: string;
+    /** Handler called on resources/read — receives matched URI params */
+    handler: (params: Record<string, string>, ctx: SpreadCtx<C>) => McpResourceContent | McpResourceContent[] | Promise<McpResourceContent | McpResourceContent[]>;
+};
+/** Map of uri → resource definition, or uriTemplate → template definition */
+type McpResourceMap$1<C = undefined> = {
+    [uriOrTemplate: string]: McpResourceDef$1<C> | McpResourceTemplateDef$1<C>;
+};
+/** An argument accepted by a prompt */
+type McpPromptArgument = {
+    /** Argument name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Whether the argument is required (default: false) */
+    required?: boolean;
+};
+/** Content block inside a prompt message */
+type McpPromptContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+} | {
+    type: "audio";
+    data: string;
+    mimeType: string;
+} | {
+    type: "resource";
+    resource: {
+        uri: string;
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    };
+};
+/** A single message returned by a prompt */
+type McpPromptMessage = {
+    role: "user" | "assistant";
+    content: McpPromptContent;
+};
+/** Result returned by a prompt handler */
+type McpPromptResult = {
+    description?: string;
+    messages: McpPromptMessage[];
+};
+/** A single prompt definition */
+type McpPromptDef$1<C = undefined> = {
+    /** Human-readable description */
+    description?: string;
+    /** Arguments this prompt accepts */
+    arguments?: McpPromptArgument[];
+    /** Handler called on prompts/get — receives argument values */
+    handler: (args: Record<string, string>, ctx: SpreadCtx<C>) => McpPromptResult | Promise<McpPromptResult>;
+};
 /** A single MCP tool definition */
-type McpToolDef<C = undefined> = {
+type McpToolDef$1<C = undefined> = {
     /** Human-readable description of the tool */
     description: string;
     /** JSON Schema describing the tool's input parameters */
@@ -1604,8 +1783,10 @@ type McpToolDef<C = undefined> = {
     /** 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] ? {} : {
+/** Setup factory — receives deps/config/files/enableAuth based on what was declared */
+type SetupArgs<D, P, HasFiles extends boolean> = {
+    enableAuth: EnableAuth;
+} & ([D] extends [undefined] ? {} : {
     deps: ResolveDeps<D>;
 }) & ([P] extends [undefined] ? {} : {
     config: ResolveConfig<P & {}>;
@@ -1627,6 +1808,8 @@ type McpHandler$1<C = any> = {
     readonly deps?: Record<string, unknown> | (() => Record<string, unknown>);
     readonly config?: Record<string, unknown>;
     readonly static?: string[];
+    readonly resources?: (...args: any[]) => any;
+    readonly prompts?: (...args: any[]) => any;
     readonly tools?: (...args: any[]) => any;
 };
 /** Options passed to `defineMcp()` */
@@ -1635,6 +1818,8 @@ type McpOptions = {
     name: string;
     /** MCP server version (default: "1.0.0") */
     version?: string;
+    /** Human-readable description — sent to clients in initialize response as system prompt context */
+    instructions?: string;
 };
 interface McpBuilder<D = undefined, P = undefined, C = undefined, HasFiles extends boolean = false> {
     /** Declare handler dependencies (tables, queues, buckets, mailers, workers) */
@@ -1656,38 +1841,35 @@ interface McpBuilder<D = undefined, P = undefined, C = undefined, HasFiles exten
     } & 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 resources (chainable) */
+    resources(fn: (ctx: SpreadCtx<C>) => McpResourceMap$1<C>): McpBuilder<D, P, C, HasFiles>;
+    /** Define MCP prompts (chainable) */
+    prompts(fn: (ctx: SpreadCtx<C>) => Record<string, McpPromptDef$1<C>>): McpBuilder<D, P, C, HasFiles>;
     /** Define MCP tools (terminal) */
-    tools(fn: (ctx: SpreadCtx<C>) => Record<string, McpToolDef<C>>): McpHandler$1<C>;
+    tools(fn: (ctx: SpreadCtx<C>) => Record<string, McpToolDef$1<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.
+ * Creates a Lambda-backed MCP server that exposes tools, resources, and prompts
+ * for AI models and MCP-compatible clients via Streamable HTTP (JSON-RPC over POST).
  *
- * @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" })) }]
- *       })
- *     }
- *   }))
- * ```
+ * @see https://modelcontextprotocol.io/specification/2025-03-26 — MCP specification
+ * @see https://effortless-aws.com/use-cases/mcp-server/ — full documentation with examples
  */
 declare function defineMcp(options: McpOptions): McpBuilder;
 
+type McpToolDef = McpToolDef$1;
+type McpResourceDef = McpResourceDef$1;
+type McpResourceTemplateDef = McpResourceTemplateDef$1;
+type McpResourceMap = McpResourceMap$1;
+type McpPromptDef = McpPromptDef$1;
+
 type TableHandler<T = Record<string, unknown>> = TableHandler$1<T, any>;
 type FifoQueueHandler<T = unknown> = FifoQueueHandler$1<T, any>;
-type BucketHandler = BucketHandler$1<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 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 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 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, param, secret, toSeconds };
+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 McpPromptArgument, type McpPromptContent, type McpPromptDef, type McpPromptMessage, type McpPromptResult, type McpResourceContent, type McpResourceDef, type McpResourceMap, type McpResourceTemplateDef, 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 };

package/dist/index.js

@@ -116,6 +116,7 @@ var defineApp = () => (options) => ({
 });
 
 // src/handlers/define-static-site.ts
+var isBucketRoute = (v) => v != null && typeof v === "object" && "bucket" in v && v.bucket != null && typeof v.bucket === "object" && v.bucket.__brand === "effortless-bucket";
 var defineStaticSite = () => (options) => ({
   __brand: "effortless-static-site",
   __spec: options
@@ -231,6 +232,13 @@ function defineBucket(options) {
       state.static = [...state.static ?? [], glob];
       return builder;
     },
+    entity(name, options2) {
+      state.spec = {
+        ...state.spec,
+        entities: { ...state.spec.entities, [name]: options2 ?? {} }
+      };
+      return builder;
+    },
     setup(fnOrLambda, maybeLambda) {
       if (typeof fnOrLambda === "function") {
         state.setup = fnOrLambda;
@@ -270,6 +278,20 @@ var defineMailer = () => (options) => ({
 });
 
 // src/handlers/define-api.ts
+var resolveCache = (cache) => {
+  if (typeof cache === "number" || typeof cache === "string") {
+    const ttl2 = toSeconds(cache);
+    return { ttl: ttl2, swr: ttl2 * 2 };
+  }
+  const ttl = toSeconds(cache.ttl);
+  if (cache.scope === "private") {
+    return { private: true, ttl };
+  }
+  return {
+    ttl,
+    swr: cache.swr != null ? toSeconds(cache.swr) : ttl * 2
+  };
+};
 function defineApi(options) {
   const { basePath, stream } = options;
   const state = {
@@ -280,11 +302,13 @@ function defineApi(options) {
     routes: []
   };
   const addRoute = (method, path, handler, opts) => {
+    const routeCache = opts?.cache != null ? resolveCache(opts.cache) : void 0;
     state.routes.push({
       method,
       path,
       onRequest: handler,
-      ...opts?.public ? { public: true } : {}
+      ...opts?.public ? { public: true } : {},
+      ...routeCache ? { cache: routeCache } : {}
     });
   };
   const applyLambdaOptions = (lambda) => {
@@ -495,7 +519,8 @@ function defineWorker(options) {
 function defineMcp(options) {
   const spec = {
     name: options.name,
-    ...options.version ? { version: options.version } : {}
+    ...options.version ? { version: options.version } : {},
+    ...options.instructions ? { instructions: options.instructions } : {}
   };
   const state = { spec };
   const applyLambdaOptions = (lambda) => {
@@ -512,6 +537,8 @@ function defineMcp(options) {
     ...state.deps ? { deps: state.deps } : {},
     ...state.config ? { config: state.config } : {},
     ...state.static ? { static: state.static } : {},
+    ...state.resources ? { resources: state.resources } : {},
+    ...state.prompts ? { prompts: state.prompts } : {},
     ...state.tools ? { tools: state.tools } : {}
   });
   const builder = {
@@ -544,6 +571,14 @@ function defineMcp(options) {
       state.onCleanup = fn;
       return builder;
     },
+    resources(fn) {
+      state.resources = fn;
+      return builder;
+    },
+    prompts(fn) {
+      state.prompts = fn;
+      return builder;
+    },
     tools(fn) {
       state.tools = fn;
       return finalize();
@@ -567,6 +602,7 @@ export {
   generateBase64,
   generateHex,
   generateUuid,
+  isBucketRoute,
   param,
   secret,
   toSeconds