@ambasada/sdk 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CENTYSO (https://centyso.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# @ambasada/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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`).
+
+```ts
+import { village } from "@ambasada/sdk"; // AMBASADA_API_KEY, AMBASADA_API_URL (default https://hackaton.ambasada.id)
+```
+
+| | |
+|---|---|
+| `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) |
+
+Errors are `VillageError` with `code` from `@ambasada/protocol` (`isVillageError(e, "PRICE_ABOVE_MAX")`), plus
+`ReceiptInvalidError` (402) and `WebhookInvalidError` (400). Workers: `createAmbasada({ env })`.
+
+`pnpm build` writes `dist/` (one ESM file + `.d.ts`); `publishConfig` points the published package at it.
+
+Built by [CENTYSO](https://centyso.com) for [Ambasada](https://ambasada.id). MIT.

package/dist/client.d.ts

@@ -0,0 +1,166 @@
+import { type IncomingRequest } from "./receipt.js";
+import type { AgentConfigInput, BuyOptions, BuyResult, ChatRequest, ChatResponse, CheckoutInput, CheckoutReceiptClaims, CheckoutSession, FileOptions, 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`. */
+    apiKey?: string;
+    /** Default: `AMBASADA_API_URL`, else https://hackaton.ambasada.id. `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. */
+    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). */
+    timeoutMs?: number;
+    /** Extra env source, e.g. a Worker's `env`. Default: `process.env` where it exists. */
+    env?: Record<string, unknown>;
+}
+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 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`).
+ */
+export declare class Village {
+    private readonly options;
+    private keyLoader?;
+    private companyPromise?;
+    private readonly replays;
+    constructor(options?: VillageOptions);
+    private env;
+    get apiUrl(): string;
+    private get apiKey();
+    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). */
+    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. Returns a public URL other products can fetch.
+         * (`POST /v1/files`: assumed route; the utilities stream serves `GET /files/:id`.)
+         */
+        put: (data: Uint8Array | ArrayBuffer | Blob | string, options?: FileOptions) => Promise<{
+            url: string;
+        }>;
+    };
+    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;

package/dist/define.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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`).
+ */
+import type { FieldSchema } from "./types.js";
+export interface CompanyConfig {
+    /** Your company id in the village (lowercase slug). */
+    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. */
+    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";
+}
+export declare function offering(def: OfferingDef): OfferingDef;

package/dist/errors.d.ts

@@ -0,0 +1,97 @@
+/**
+ * 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`
+ * 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")) … }
+ *
+ * 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`,
+ * `RECEIPT_INVALID`, `WEBHOOK_INVALID`).
+ */
+export declare const ERROR_STATUS: {
+    readonly INSUFFICIENT_FUNDS: 402;
+    readonly OFFLINE: 503;
+    readonly TIMEOUT: 504;
+    readonly SCHEMA_INVALID: 502;
+    readonly CAP_BUYER_HOURLY: 429;
+    readonly CAP_SELLER_RATE: 429;
+    readonly DEAL_EXHAUSTED: 409;
+    readonly DEPTH_EXCEEDED: 422;
+    readonly BUDGET_EXCEEDED: 402;
+    readonly UPSTREAM_ERROR: 502;
+    readonly PRICE_ABOVE_MAX: 409;
+    readonly SELF_PURCHASE: 403;
+    readonly INVALID_REQUEST: 400;
+    readonly UNAUTHORIZED: 401;
+    readonly NOT_FOUND: 404;
+    readonly CONFLICT: 409;
+    readonly IDEMPOTENCY_CONFLICT: 422;
+    readonly IDEMPOTENCY_IN_PROGRESS: 409;
+    readonly HOLD_NOT_ACTIVE: 409;
+    readonly INTERNAL: 500;
+    readonly CAP_PER_PAYMENT: 403;
+    readonly CAP_BUYER_DAILY: 429;
+    readonly CAP_PAYEE_DAILY: 429;
+    readonly CAP_VISITOR_DAILY: 429;
+    readonly APPROVAL_REQUIRED: 403;
+    readonly APPROVAL_INVALID: 403;
+    readonly APPROVALS_PENDING: 429;
+    readonly PROVIDER_BUDGET: 503;
+    readonly PROVIDER_DENIED: 502;
+    readonly FROZEN: 403;
+    readonly CAP_INBOX_RATE: 429;
+    readonly NETWORK: 0;
+    readonly CONFIG: 0;
+    readonly RECEIPT_INVALID: 402;
+    readonly WEBHOOK_INVALID: 400;
+};
+/** A known error code. Servers may add codes before the SDK knows them, so `code` is `ErrorCode | string`. */
+export type ErrorCode = keyof typeof ERROR_STATUS;
+export interface ErrorDetails {
+    /** Present on Pay errors once a call id was assigned. */
+    call_id?: string;
+    /** Always false on Pay errors: a failed call never moves money. */
+    charged?: false;
+    /** True when funds had been held for the call and were released. */
+    refunded?: boolean;
+    /** HTTP status the seller returned, for UPSTREAM_ERROR / SCHEMA_INVALID. */
+    upstream_status?: number;
+    /** APPROVAL_REQUIRED: retry with `{ approval: approvalId }` once the team approved it. */
+    approval_id?: string;
+    [key: string]: unknown;
+}
+export declare class VillageError 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);
+    get callId(): string | undefined;
+    get refunded(): boolean;
+    get approvalId(): string | undefined;
+    /** The wire shape, e.g. to pass an error on from your own endpoint. */
+    toJSON(): {
+        error: {
+            code: string;
+            message: string;
+        } & ErrorDetails;
+    };
+    /** 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 {
+    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;

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @ambasada/sdk: accept and spend TON in the Hack A Ton village.
+ *
+ *   import { village } from "@ambasada/sdk";             // AMBASADA_API_KEY, AMBASADA_API_URL from the env
+ *   const { url } = await village.checkout({ amount: 3, description: "Coffee", success_url });
+ *   export const POST = village.sell("translate", async ({ text, to }) => ({ text: await village.llm(`Translate to ${to}: ${text}`) }));
+ *
+ * Works in Node ≥ 22, Bun, Cloudflare Workers (`createAmbasada({ env })`) and Next.js route handlers.
+ */
+import { Village } from "./client.js";
+export { Village, createAmbasada, DEFAULT_API_URL, DEFAULT_MODEL } from "./client.js";
+export type { VillageOptions, VerifyReceiptOptions, SellHandler } from "./client.js";
+export * from "./errors.js";
+export type * from "./types.js";
+export { verifyWebhookPayload, webhookHeaders, generateWebhookSecret, WEBHOOK_HEADERS } from "./webhook.js";
+export { RECEIPT_HEADER, readIncoming, verifyCallReceipt, verifyCheckoutReceiptToken } from "./receipt.js";
+export type { IncomingRequest } from "./receipt.js";
+export { defineCompany, offering } from "./define.js";
+export type { CompanyConfig, OfferingDef } from "./define.js";
+/** The default client, configured from the environment at call time. */
+export declare const village: Village;
+export default village;