@ambasada/sdk 0.7.4 → 0.8.0

package/README.md

@@ -1,30 +1,29 @@
 # @ambasada/sdk
 
-Accept and spend TON in the Hack A Ton village. Node ≥ 22, Bun, Cloudflare Workers, Next.js route handlers.
-No runtime dependencies (the build bundles the receipt code from `@ambasada/protocol`).
+The Ambasada platform client: Sign in with Ambasada, mini-app notifications, the project store, files. Node ≥ 22,
+Bun, Cloudflare Workers, Next.js route handlers. No runtime dependencies.
 
 ```ts
-import { village } from "@ambasada/sdk"; // AMBASADA_API_KEY, AMBASADA_API_URL (default https://hackaton.ambasada.id)
+import { ambasada } from "@ambasada/sdk"; // AMBASADA_API_KEY, AMBASADA_API_URL (default https://api.ambasada.dev)
 ```
 
 | | |
 |---|---|
-| `village.sell(offering, handler)` | fetch handler for a paid endpoint: verifies `x-village-receipt` (402 otherwise), answers JSON |
-| `village.verifyReceipt(req, { offering })` | the same check by hand → receipt claims + parsed `input`; fetch `Request` or Node/Express raw body |
-| `village.checkout(input)` / `getCheckout(id)` / `createPaymentLink(…)` | Checkout for people (`POST /v1/checkout/sessions`) |
-| `village.verifyWebhook(req, secret?)` | Standard Webhooks signature (`AMBASADA_WEBHOOK_SECRET`) → `{ id, type, data }` |
-| `village.verifyCheckoutReceipt(token, { session })` | pay.js `village:paid` receipt |
-| `village.buy("company/offering", input, { maxPrice, idempotencyKey, parent })` | Pay through the Gateway |
-| `village.need(name, input, opts)` | buy whatever your agent routed `name` to |
-| `village.llm(prompt)` / `village.llm.chat(req)` | OpenAI-compatible chat, paid in TON |
-| `village.images.generate(req)`, `village.tools.list()` / `.call(id, input)`, `village.files.put(data)` | LLMOK utilities |
-| `village.listings.put(name, def)` / `.list()` | offerings |
-| `village.wallet()`, `village.ledger(since)`, `village.transfer(to, amount)` | money |
-| `village.agent.config/steer/transcript`, `village.market.search(q)` | agent and market (CLI) |
-| `village.auth.login(req)` / `.callback(req)` / `.user(req)` / `.logout(req)` | Sign in with Ambasada (below) |
-
-Errors are `VillageError` with `code` from `@ambasada/protocol` (`isVillageError(e, "PRICE_ABOVE_MAX")`), plus
-`ReceiptInvalidError` (402) and `WebhookInvalidError` (400). Workers: `createAmbasada({ env })`.
+| `ambasada.auth.login(req)` / `.callback(req)` / `.user(req)` / `.logout(req)` / `.shell(req)` | Sign in with Ambasada (below) |
+| `ambasada.apps.verifyWebhook(req)` / `.notify({ … })` | the Ambasada app's events and push notifications (docs/MINI-APPS.md §7) |
+| `ambasada.store.get(key)` / `.put(key, value)` / `.delete(key)` / `.list(prefix)` | JSON key-value, 1 MB per app |
+| `ambasada.files.put(data)` | a file at a public URL |
+| `ambasada.project()`, `ambasada.keys()` | the app's id; the API's signing keys |
+| `defineApp({ id, name, description, product })` | `ambasada.config.ts` |
+
+Errors are `AmbasadaError` with `code` from `@ambasada/protocol` (`isAmbasadaError(e, "UNAUTHORIZED")`), and
+`WebhookInvalidError` (400). Workers: `createAmbasada({ env })`. An app's own database, KV, files and Durable
+Objects are Worker bindings (`env.DB`, `env.KV`, `env.FILES`; docs/STORAGE.md), not SDK calls.
+
+The Hack A Ton economy (TON, checkout, offerings, the agent) is the add-on
+[`@ambasada/village`](https://www.npmjs.com/package/@ambasada/village). Its 0.7 names (`village`, `createVillage`,
+`VillageError`, `offering`, `defineCompany`, …) are still exported here, `@deprecated`, until 2.0. Note that
+`createAmbasada` returns the platform client from 0.8; selling code uses `createVillage`.
 
 ## Sign in with Ambasada
 
@@ -34,15 +33,15 @@ setup on `https://<slug>.ambasada.dev`: `ambasada deploy` injects `AMBASADA_AUTH
 as "Fake Visitor". Fetch-style handlers for Workers and Next.js route handlers, WebCrypto only.
 
 ```ts
-const village = createAmbasada({ env });
+const ambasada = createAmbasada({ env });
 // GET /api/auth/login?returnTo=/path   → redirect to the Ambasada ID consent screen
-return village.auth.login(req, { returnTo: "/", email: true }); // email: also ask for their email
+return ambasada.auth.login(req, { returnTo: "/", email: true }); // email: also ask for their email
 // GET /api/auth/callback               → checks state, exchanges the code, reads the profile, sets the cookie
-return village.auth.callback(req);
+return ambasada.auth.callback(req);
 // anywhere on the server
-const user = await village.auth.user(req); // AmbasadaUser | null
+const user = await ambasada.auth.user(req); // AmbasadaUser | null
 // GET /api/auth/logout
-return village.auth.logout(req, { returnTo: "/" });
+return ambasada.auth.logout(req, { returnTo: "/" });
 ```
 
 `AmbasadaUser` is `{ id, name, avatar_url, builder, builder_since, member_since, pass, email? }`: `id` is the
@@ -50,7 +49,7 @@ stable Ambasada ID (`user_…`), `pass` is `"builder" | "visitor" | "staff" | nu
 only if you asked and they agreed. The session is an HttpOnly `SameSite=Lax` cookie (`__Host-ambasada_session`
 on https) holding the signed profile (HMAC-SHA256, key derived from the client secret), valid 7 days; no token is
 kept. `returnTo` must be a path on your site. `user()` also takes `{ headers }` (Next server components:
-`village.auth.user({ headers: await headers() })`). `village.auth.configured` says whether credentials are set.
+`ambasada.auth.user({ headers: await headers() })`). `ambasada.auth.configured` says whether credentials are set.
 Override them with `createAmbasada({ auth: { clientId, clientSecret, issuer, publicUrl } })`; `PUBLIC_URL` sets the
 origin of the callback URL when the Worker sees another host. More: docs/AUTH.md.
 

package/dist/apps.d.ts

@@ -10,7 +10,7 @@
  * dashboard shows it for apps hosted elsewhere; `ambasada dev` sets a fake one and plays the hub).
  * WebCrypto only; the wire format is in @ambasada/protocol (packages/protocol/src/apps.ts).
  */
-import type { HeaderSource } from "./webhook.js";
+import type { HeaderSource } from "./headers.js";
 export declare const APP_SIGNATURE_HEADER = "x-ambasada-signature";
 export declare const APP_TIMESTAMP_HEADER = "x-ambasada-timestamp";
 export type AppEventType = "notifications_enabled" | "notifications_disabled" | "app_added" | "app_removed" | "ping";
@@ -104,7 +104,7 @@ export declare class AmbasadaApps {
     /**
      * Sends a push to the people behind `tokens` (or `users`, for Verified apps with `identity`) through the hub.
      * Checks the limits first (title ≤ 40, body ≤ 140, id ≤ 128, ≤ 100 recipients, `url` on your origin) and
-     * throws `VillageError("INVALID_REQUEST")` before sending anything. Tokens in `invalid` are gone: forget them.
+     * throws `AmbasadaError("INVALID_REQUEST")` before sending anything. Tokens in `invalid` are gone: forget them.
      */
     notify(input: AppNotifyInput): Promise<AppNotifyResult>;
 }

package/dist/auth.d.ts

@@ -4,10 +4,10 @@
  * AMBASADA_AUTH_CLIENT_SECRET and AMBASADA_AUTH_ISSUER; `ambasada dev` injects fake ones that point at
  * the mock. Four fetch handlers, WebCrypto only, no dependencies:
  *
- *   GET /api/auth/login     → return village.auth.login(req, { returnTo: "/" })
- *   GET /api/auth/callback  → return village.auth.callback(req)
- *   GET /api/auth/logout    → return village.auth.logout(req)
- *   anywhere                → const user = await village.auth.user(req)   // AmbasadaUser | null
+ *   GET /api/auth/login     → return ambasada.auth.login(req, { returnTo: "/" })
+ *   GET /api/auth/callback  → return ambasada.auth.callback(req)
+ *   GET /api/auth/logout    → return ambasada.auth.logout(req)
+ *   anywhere                → const user = await ambasada.auth.user(req)   // AmbasadaUser | null
  *
  * The session is an HttpOnly cookie holding the signed public profile (HMAC-SHA256 under a key
  * derived from the client secret), host-only (`__Host-` on https), so no other *.ambasada.dev product
@@ -16,8 +16,8 @@
  * Silent sign-in inside the Ambasada app (docs/MINI-APPS.md §5): the page asks the shell for a short-lived
  * token (`auth.getToken()` from @ambasada/miniapp) and POSTs it here; the same session cookie comes back:
  *
- *   POST /api/auth/shell { token } → return village.auth.shell(req)                      // { user } + cookie
- *   anywhere                       → const who = await village.auth.verifyShellToken(token) // { user_id, name, avatar }
+ *   POST /api/auth/shell { token } → return ambasada.auth.shell(req)                      // { user } + cookie
+ *   anywhere                       → const who = await ambasada.auth.verifyShellToken(token) // { user_id, name, avatar }
  */
 /** The person signed in, as `GET /v1/auth/profile` returns them. */
 export interface AmbasadaUser {
@@ -42,7 +42,7 @@ export interface AuthConfig {
     audiences?: string[];
     /** The hub, for the full profile behind a shell token (`/api/apps/profile`). */
     hubUrl?: string;
-    /** Where `/v1/auth/profile` lives (the village API). */
+    /** Where `/v1/auth/profile` lives (the Ambasada API). */
     apiUrl: string;
     /** Your public origin if the Worker sees another host (behind a proxy). Default: the request's origin. */
     publicUrl?: string;
@@ -103,7 +103,7 @@ export declare class AmbasadaAuth {
     login(req: Request, options?: LoginOptions): Promise<Response>;
     /**
      * Ambasada ID sends the person back here: checks the state, exchanges the code (with the PKCE
-     * verifier and the client secret), reads their profile from the village, sets the session cookie
+     * verifier and the client secret), reads their profile from the Ambasada API, sets the session cookie
      * and redirects to `returnTo`. A refused consent goes back to `returnTo` signed out.
      */
     callback(req: Request): Promise<Response>;
@@ -112,7 +112,7 @@ export declare class AmbasadaAuth {
     /**
      * Verifies a shell token (Clerk JWT template `ambasada-miniapp`, RS256, 60 s) against
      * `<AMBASADA_AUTH_ISSUER>/.well-known/jwks.json` (cached 1 h): signature, expiry, issuer, and that its `aud`
-     * is this app (its id or origin). Returns who it is, or throws `VillageError("UNAUTHORIZED")`.
+     * is this app (its id or origin). Returns who it is, or throws `AmbasadaError("UNAUTHORIZED")`.
      */
     verifyShellToken(token: string, options?: {
         audience?: string | string[];

package/dist/client.d.ts

@@ -1,23 +1,19 @@
 import { AmbasadaApps } from "./apps.js";
 import { AmbasadaAuth } from "./auth.js";
-import { type IncomingRequest } from "./receipt.js";
-import type { AgentConfigInput, BuyOptions, BuyResult, ChatRequest, ChatResponse, CheckoutInput, CheckoutReceiptClaims, CheckoutSession, FileOptions, StoredFile, StoreList, StoreWrite, ImageRequest, ImageResult, Jwk, LedgerPage, Listing, ListingInput, MarketOffering, PaidCall, PaymentLink, PaymentLinkInput, ToolListing, ToolResult, TranscriptEntry, TransferOptions, Wallet, WebhookDelivery, WebhookEvent } from "./types.js";
-export declare const DEFAULT_API_URL = "https://hackaton.ambasada.id";
-export declare const DEFAULT_MODEL = "deepseek-v4.1-flash";
-export interface VillageOptions {
-    /** Company API key. Default: `AMBASADA_API_KEY`. */
+import type { FileOptions, Jwk, StoredFile, StoreList, StoreWrite } from "./types.js";
+export declare const DEFAULT_API_URL = "https://api.ambasada.dev";
+export interface AmbasadaOptions {
+    /** Project key (`vk_…` from developer.ambasada.dev, or `ambasada login`). Default: `AMBASADA_API_KEY`. */
     apiKey?: string;
-    /** Default: `AMBASADA_API_URL`, else https://hackaton.ambasada.id. `ambasada dev` serves http://localhost:8788. */
+    /** Default: `AMBASADA_API_URL`, else https://api.ambasada.dev. `ambasada dev` serves http://localhost:8788. */
     apiUrl?: string;
-    /** Your company id, for receipt checks. Default: `AMBASADA_COMPANY`, else looked up once with the API key. */
-    company?: string;
-    /** Webhook signing secret (`whsec_…`). Default: `AMBASADA_WEBHOOK_SECRET`. */
-    webhookSecret?: string;
-    /** Receipt keys; default: `<apiUrl>/.well-known/jwks.json`, cached 10 minutes. */
+    /** Your app's id. Default: `AMBASADA_APP_ID`, else looked up once with the API key. */
+    project?: string;
+    /** Signing keys; default: `<apiUrl>/.well-known/jwks.json`, cached 10 minutes. */
     keys?: Jwk[] | (() => Promise<Jwk[]>);
     /** Custom fetch (tests, proxies). */
     fetch?: typeof fetch;
-    /** Per-request timeout in ms (default 45 s; Pay calls may take 30 s at the seller). */
+    /** Per-request timeout in ms (default 45 s). */
     timeoutMs?: number;
     /** Extra env source, e.g. a Worker's `env`. Default: `process.env` where it exists. */
     env?: Record<string, unknown>;
@@ -36,26 +32,34 @@ export interface VillageOptions {
         id?: string;
     };
 }
-export interface VerifyReceiptOptions {
-    /** Pin the offering name (`translate`), so a receipt for another of your offerings is refused. */
-    offering?: string;
-    /** Refuse a second use of the same receipt in this process (default true). Persist call ids yourself across instances. */
-    replayGuard?: boolean;
+export type Method = "GET" | "POST" | "PUT" | "DELETE";
+export interface RequestOptions {
+    body?: unknown;
+    raw?: NonNullable<RequestInit["body"]>;
+    headers?: Record<string, string | undefined>;
+    query?: Record<string, string | number | undefined>;
+    auth?: boolean;
+    signal?: AbortSignal;
+    /** Retry once on a network error (only safe with an idempotency key). */
+    retry?: boolean;
+}
+export interface RawResponse {
+    status: number;
+    headers: Headers;
+    json: unknown;
 }
-export type SellHandler<Input, Output> = (input: Input, call: PaidCall<Input>, req: Request) => Output | Response | Promise<Output | Response>;
 /**
- * The village client. `import { village } from "@ambasada/sdk"` gives one configured from the
- * environment; `createAmbasada({ apiKey, apiUrl })` makes another (e.g. from a Worker's `env`).
+ * The Ambasada client. `import { ambasada } from "@ambasada/sdk"` gives one configured from the
+ * environment; `createAmbasada({ env })` makes another (e.g. from a Worker's `env`).
  */
-export declare class Village {
-    private readonly options;
+export declare class Ambasada {
+    protected readonly options: AmbasadaOptions;
     private keyLoader?;
-    private companyPromise?;
-    private readonly replays;
-    constructor(options?: VillageOptions);
-    private env;
+    private projectPromise?;
+    constructor(options?: AmbasadaOptions);
+    protected env(name: string): string | undefined;
     get apiUrl(): string;
-    private get apiKey();
+    protected get apiKey(): string;
     /**
      * Sign in with Ambasada (docs/AUTH.md): `login(req)`, `callback(req)`, `user(req)`, `logout(req)`.
      * Credentials come with the deploy to ambasada.dev, and from `ambasada dev` locally.
@@ -68,139 +72,35 @@ export declare class Village {
      * `notify({ … })` to push to people who turned notifications on. Uses `AMBASADA_APP_SECRET`.
      */
     readonly apps: AmbasadaApps;
-    private send;
-    private call;
-    /** Your company id (from options, `AMBASADA_COMPANY`, or the wallet the API key belongs to). */
-    company(): Promise<string>;
-    /** Village receipt keys (cached). */
+    protected send(method: Method, path: string, opts?: RequestOptions): Promise<RawResponse>;
+    protected call<T>(method: Method, path: string, opts?: RequestOptions): Promise<T>;
+    /** Your app's id (from options, `AMBASADA_APP_ID`, or the project the API key belongs to). */
+    project(): Promise<string>;
+    /** The API's signing keys (`/.well-known/jwks.json`, cached). */
     keys(): Promise<Jwk[]>;
-    private keySource;
-    /**
-     * Verifies that a request to your endpoint was paid through the Gateway and returns the receipt
-     * with the parsed JSON `input`. Throws `ReceiptInvalidError` (status 402) otherwise.
-     * Works with a fetch `Request` (not consumed) or a Node/Express request with a raw body.
-     */
-    verifyReceipt<Input = any>(req: IncomingRequest, options?: VerifyReceiptOptions): Promise<PaidCall<Input>>;
-    /**
-     * Wraps a paid offering as a fetch handler: verifies the receipt (402 if missing or bad), runs
-     * `handler(input, call, req)` and answers JSON. A thrown `VillageError` keeps its status (the
-     * Gateway then refunds the buyer).
-     *
-     *   export default village.sell("translate", async ({ text, to }) => ({ text: await village.llm(`…`) }));
-     */
-    sell<Input = any, Output = unknown>(offering: string, handler: SellHandler<Input, Output>): (req: Request) => Promise<Response>;
-    /** Verifies a signed webhook (`checkout.paid`, `webhook.test`) and returns the event. Throws `WebhookInvalidError`. */
-    verifyWebhook<Data = any>(req: IncomingRequest, secret?: string): Promise<WebhookEvent<Data>>;
-    /** Verifies a checkout receipt (pay.js `village:paid` → `e.detail.receipt`, or `session.receipt`). */
-    verifyCheckoutReceipt(token: string | null | undefined, options?: {
-        session?: string;
-    }): Promise<CheckoutReceiptClaims>;
-    /** Creates a Checkout session; redirect the person to `session.url`. Deliver on the webhook or `getCheckout(id).status === "paid"`. */
-    checkout(session: CheckoutInput, options?: {
-        idempotencyKey?: string;
-    }): Promise<CheckoutSession>;
-    getCheckout(id: string): Promise<CheckoutSession>;
-    /** A reusable payment link for static pages (`<button data-village-pay="pl_…">` with pay.js). */
-    createPaymentLink(link: PaymentLinkInput): Promise<PaymentLink>;
-    /** Cancels an open session (`POST /v1/checkout/sessions/:id/expire`). */
-    expireCheckout(id: string): Promise<CheckoutSession>;
-    listPaymentLinks(): Promise<PaymentLink[]>;
-    deactivatePaymentLink(id: string): Promise<PaymentLink>;
-    /** Where checkout webhooks go. Returns the signing secret (the same one until `rotateSecret`). */
-    setWebhook(url: string, options?: {
-        rotateSecret?: boolean;
-    }): Promise<{
-        url: string;
-        secret: string;
-    }>;
-    /** The webhook URL, its secret and the last deliveries. */
-    getWebhook(): Promise<{
-        url: string | null;
-        secret: string | null;
-        deliveries: WebhookDelivery[];
-    }>;
-    deleteWebhook(): Promise<{
-        deleted: true;
-    }>;
-    /** Sends a `webhook.test` event now and returns the delivery. */
-    testWebhook(): Promise<WebhookDelivery>;
-    retryWebhookDelivery(id: string): Promise<WebhookDelivery>;
-    /** Buys one call of `company/offering` through the Gateway. Money moves only if the seller answers 2xx with valid output. */
-    buy<Output = any>(offering: string, input: unknown, options?: BuyOptions): Promise<BuyResult<Output>>;
-    /**
-     * Buys whatever your agent routed the need `name` to (or the best offering within `maxPrice` if it
-     * has not routed it yet), with fallbacks (EXCHANGE.md §4.3). Prefer this over hardcoding a supplier.
-     */
-    need<Output = any>(name: string, input: unknown, options?: BuyOptions): Promise<BuyResult<Output>>;
-    private paid;
-    /**
-     * `village.llm("prompt")` → the answer text; `village.llm.chat(req)` → the full OpenAI-style response.
-     * Default model: deepseek-v4.1-flash.
-     */
-    readonly llm: ((prompt: string, options?: Omit<ChatRequest, "messages"> & {
-        system?: string;
-    }) => Promise<string>) & {
-        chat(req: ChatRequest): Promise<ChatResponse>;
-    };
-    readonly images: {
-        /** Generates an image; the URL is re-hosted in the village files store. Default model: nano_banana. */
-        generate: (req: ImageRequest) => Promise<ImageResult>;
-    };
-    readonly tools: {
-        /** The curated LLMOK tool catalog with TON prices. */
-        list: () => Promise<ToolListing[]>;
-        /** Runs one tool; debits your wallet only on success. Replays with the same idempotency key are free. */
-        call: <Output = any>(id: string, input: unknown, options?: {
-            idempotencyKey?: string;
-        }) => Promise<ToolResult<Output>>;
-    };
     readonly files: {
         /**
-         * Stores bytes, a Blob, or a URL to copy, for the event (`POST /v1/files`, 0.1 TON). Returns a
-         * public URL other products can fetch.
+         * Stores bytes, a Blob, or a URL to copy (`POST /v1/files`). Returns a public URL. For an app's own
+         * uploads prefer its bucket, `env.FILES` (docs/STORAGE.md).
          */
         put: (data: Uint8Array | ArrayBuffer | Blob | string, options?: FileOptions) => Promise<StoredFile>;
     };
     /**
-     * Your company's JSON key-value store (`/v1/store`): 1 MB per company (keys + values), free. State for
-     * a hosted product that needs no database.
+     * Your project's JSON key-value store (`/v1/store`): 1 MB per project (keys + values), free. For more,
+     * use the app's own D1, KV and R2 (docs/STORAGE.md).
      */
     readonly store: {
         /** The value, or null when the key is not set. */
         get: <T = unknown>(key: string) => Promise<T | null>;
         /** Saves any JSON value (fails with INVALID_REQUEST when the store would pass 1 MB). */
         set: (key: string, value: unknown) => Promise<StoreWrite>;
+        /** `set` under its other name. */
+        put: (key: string, value: unknown) => Promise<StoreWrite>;
         /** True when the key existed. */
         delete: (key: string) => Promise<boolean>;
         /** Keys (up to 1000, optionally under a prefix) and how much of the 1 MB is used. */
         list: (prefix?: string) => Promise<StoreList>;
     };
-    readonly listings: {
-        /** Creates or updates an offering (price changes are versioned). */
-        put: (name: string, def: ListingInput) => Promise<Listing>;
-        list: () => Promise<Listing[]>;
-    };
-    wallet(): Promise<Wallet>;
-    ledger(since?: number, limit?: number): Promise<LedgerPage>;
-    transfer(to: string, amount: number, options?: TransferOptions): Promise<{
-        entry: unknown;
-    }>;
-    readonly market: {
-        search: (query: string) => Promise<MarketOffering[]>;
-    };
-    readonly agent: {
-        /** Replaces the agent's prompt (`agent.md`) and settings (`settings.json`). */
-        config: (config: AgentConfigInput) => Promise<{
-            config: unknown;
-            limits?: unknown;
-        }>;
-        /** A message the agent answers on its next wake. */
-        steer: (text: string) => Promise<unknown>;
-        transcript: (since?: number, limit?: number) => Promise<{
-            entries: TranscriptEntry[];
-            next_since: number;
-        }>;
-        state: () => Promise<Record<string, unknown>>;
-    };
 }
-export declare function createAmbasada(options?: VillageOptions): Village;
+export declare function cachedKeys(load: () => Promise<Jwk[]>, ttlMs?: number): () => Promise<Jwk[]>;
+export declare function createAmbasada(options?: AmbasadaOptions): Ambasada;

package/dist/define.d.ts

@@ -1,44 +1,19 @@
 /**
- * Project config helpers (DESIGN.md §2.3). They only add types and checks; the CLI reads the values
- * (`ambasada deploy`, `ambasada offerings sync`, `ambasada dev`).
+ * `ambasada.config.ts` (docs/PLATFORM.md §3). Types and checks only; the CLI reads the values
+ * (`ambasada dev`, `deploy`, `link`, `check`). Add-ons add their own keys (the village: `idea`, `offerings`, `agent`).
  */
-import type { FieldSchema } from "./types.js";
-export interface CompanyConfig {
-    /** Your company id in the village (lowercase slug). */
+export interface AppConfig {
+    /** The app's slug (lowercase): it lives at https://<id>.ambasada.dev. */
     id: string;
     /** Display name. */
     name: string;
-    /** Locked Fri 20:00. */
-    idea: {
-        title: string;
-        category?: string;
-        pitch?: string;
-    };
-    /** Where your product lives; offering endpoints are relative to it. */
+    /** One line about the app: the manifest's subtitle and description (`ambasada init` writes them from it). */
+    description?: string;
+    /** Where the app runs; `ambasada link` sets it when you host elsewhere. */
     product?: {
         url?: string;
     };
-    /** Path to the offerings module (default `./product/offerings.ts`). */
-    offerings?: string;
-    /** Agent folder with agent.md and settings.json (default `./agent`). */
-    agent?: {
-        dir?: string;
-    };
-}
-export declare function defineCompany(config: CompanyConfig): CompanyConfig;
-export interface OfferingDef {
-    /** Slug: a-z, 0-9, _ and -. */
-    name: string;
-    /** TON per call, 0.1–500. */
-    price: number;
-    /** Path on your product (`/api/translate`) or an absolute URL. */
-    endpoint: string;
-    description: string;
-    input?: FieldSchema;
-    output?: FieldSchema;
-    /** Allow a free sample (`market.preview`). */
-    preview?: boolean;
-    timeout_ms?: number;
-    status?: "open" | "paused";
+    /** Add-ons to load besides the ones found in node_modules (package names, e.g. "./village/index.js"). */
+    addons?: string[];
 }
-export declare function offering(def: OfferingDef): OfferingDef;
+export declare function defineApp<T extends AppConfig>(config: T): T;

package/dist/errors.d.ts

@@ -1,10 +1,10 @@
 /**
- * Typed errors. Every village API failure is `{ "error": { "code", "message", ... } }` with a code
- * from `@ambasada/protocol` (packages/protocol/src/errors.ts); the SDK turns it into a `VillageError`
+ * Typed errors. Every Ambasada API failure is `{ "error": { "code", "message", ... } }` with a code
+ * from `@ambasada/protocol` (packages/protocol/src/errors.ts); the SDK turns it into an `AmbasadaError`
  * with the same `code`, so you branch on `error.code` instead of parsing messages:
  *
- *   try { await village.buy("inkwell/poem", input, { maxPrice: 2 }) }
- *   catch (e) { if (isVillageError(e, "PRICE_ABOVE_MAX")) … }
+ *   try { await ambasada.store.set("settings", value) }
+ *   catch (e) { if (isAmbasadaError(e, "INVALID_REQUEST")) … }
  *
  * The list mirrors the protocol (a unit test keeps them in sync), plus codes the in-flight API
  * streams add (checkout, utilities, agent) and a few SDK-side ones (`NETWORK`, `CONFIG`,
@@ -62,12 +62,14 @@ export interface ErrorDetails {
     approval_id?: string;
     [key: string]: unknown;
 }
-export declare class VillageError extends Error {
+export declare class AmbasadaError extends Error {
     readonly code: ErrorCode | (string & {});
     /** HTTP status (0 when the request never got an answer). */
     readonly status: number;
     readonly details: ErrorDetails;
     constructor(code: ErrorCode | (string & {}), message: string, status?: number, details?: ErrorDetails);
+    /** `instanceof AmbasadaError` holds across bundled copies; subclasses keep the usual prototype check. */
+    static [Symbol.hasInstance](value: unknown): boolean;
     get callId(): string | undefined;
     get refunded(): boolean;
     get approvalId(): string | undefined;
@@ -81,17 +83,12 @@ export declare class VillageError extends Error {
     /** A `Response` with the wire shape and status (402 for receipt problems). */
     toResponse(): Response;
 }
-export type ReceiptFailure = "malformed" | "unknown_key" | "bad_signature" | "expired" | "not_yet_valid" | "wrong_issuer" | "wrong_seller" | "wrong_offering" | "wrong_kind" | "wrong_session" | "body_mismatch" | "replayed" | "missing";
-/** The request is not paid: no receipt, a forged or expired one, or one for another seller / offering / body. */
-export declare class ReceiptInvalidError extends VillageError {
-    readonly reason: ReceiptFailure;
-    constructor(reason: ReceiptFailure, message: string);
-}
 export type WebhookFailure = "missing_headers" | "bad_timestamp" | "too_old" | "too_new" | "bad_signature" | "bad_secret" | "bad_body";
-export declare class WebhookInvalidError extends VillageError {
+/** A signed webhook (app events, payments) failed its check. */
+export declare class WebhookInvalidError extends AmbasadaError {
     readonly reason: WebhookFailure;
     constructor(reason: WebhookFailure, message: string);
 }
-export declare function isVillageError(value: unknown, code?: ErrorCode | (string & {})): value is VillageError;
-/** Builds a VillageError from an API response body (or a non-JSON failure). */
-export declare function errorFromResponse(status: number, body: unknown, fallback: string): VillageError;
+export declare function isAmbasadaError(value: unknown, code?: ErrorCode | (string & {})): value is AmbasadaError;
+/** Builds an AmbasadaError from an API response body (or a non-JSON failure). */
+export declare function errorFromResponse(status: number, body: unknown, fallback: string): AmbasadaError;

package/dist/headers.d.ts

@@ -0,0 +1,3 @@
+/** Header lookup that works on a fetch `Headers` and on a Node / Express header record. */
+export type HeaderSource = Headers | Record<string, string | string[] | undefined | null>;
+export declare function getHeader(headers: HeaderSource, name: string): string | null;