@ambasada/village 0.0.0-stage → 0.8.0

package/dist/client.d.ts

@@ -0,0 +1,148 @@
+import { Ambasada, type AmbasadaOptions } from "./sdk/platform.js";
+import { type IncomingRequest } from "./receipt.js";
+import type { AgentConfigInput, BuyOptions, BuyResult, ChatRequest, ChatResponse, CheckoutInput, CheckoutReceiptClaims, CheckoutSession, ImageRequest, ImageResult, LedgerPage, Listing, ListingInput, MarketOffering, PaidCall, PaymentLink, PaymentLinkInput, ToolListing, ToolResult, TranscriptEntry, TransferOptions, Wallet, WebhookDelivery, WebhookEvent } from "./types.js";
+/** The Hack A Ton API. The platform API (`@ambasada/sdk`) is https://api.ambasada.dev. */
+export declare const DEFAULT_VILLAGE_API_URL = "https://hackaton.ambasada.id";
+export declare const DEFAULT_MODEL = "deepseek-v4.1-flash";
+export interface VillageOptions extends AmbasadaOptions {
+    /** Team key (`sk_live_…`, from the village app → Developers). Default: `AMBASADA_API_KEY`. */
+    apiKey?: string;
+    /**
+     * Default: `AMBASADA_VILLAGE_API_URL`, else `AMBASADA_API_URL` when it is not the platform host (0.7
+     * projects, `ambasada dev`), else https://hackaton.ambasada.id.
+     */
+    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;
+}
+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: the platform client (`auth`, `apps`, `store`, `files`) plus money, AI, the agent and
+ * the market. `import { village } from "@ambasada/village"` gives one configured from the environment;
+ * `createVillage({ env })` makes another (e.g. from a Worker's `env`).
+ */
+export declare class Village extends Ambasada {
+    private readonly villageOptions;
+    private companyPromise?;
+    private readonly replays;
+    constructor(options?: VillageOptions);
+    get apiUrl(): string;
+    /** Your company id (from options, `AMBASADA_COMPANY`, or the wallet the API key belongs to). */
+    company(): Promise<string>;
+    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 `AmbasadaError` 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 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 createVillage(options?: VillageOptions): Village;

package/dist/define.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The village keys of `ambasada.config.ts` (docs/PLATFORM.md §5). They only add types and checks; the CLI
+ * reads the values (`ambasada deploy`, `ambasada village offerings sync`, `ambasada dev`).
+ *
+ *   export default defineCompany(defineApp({ id, name, product }), { idea, offerings, agent });
+ */
+import type { AppConfig } from "./sdk/platform.js";
+import type { FieldSchema } from "./types.js";
+export interface VillageConfig {
+    /** Locked Fri 20:00. */
+    idea: {
+        title: string;
+        category?: string;
+        pitch?: 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;
+    };
+}
+/** An app (`id` is your company id in the village) with the village keys. */
+export interface CompanyConfig extends AppConfig, VillageConfig {
+}
+/** `defineCompany(defineApp({ … }), { idea, offerings, agent })`, or the 0.7 form `defineCompany({ id, name, idea, … })`. */
+export declare function defineCompany(app: AppConfig, village: VillageConfig): CompanyConfig;
+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,19 @@
+/**
+ * Village errors. Every failure is an `AmbasadaError` (`@ambasada/sdk`) with a code from
+ * `@ambasada/protocol`; `VillageError` is the same class under its 0.7 name (kept through 1.x):
+ *
+ *   try { await village.buy("inkwell/poem", input, { maxPrice: 2 }) }
+ *   catch (e) { if (isVillageError(e, "PRICE_ABOVE_MAX")) … }
+ */
+import { AmbasadaError, isAmbasadaError } from "./sdk/platform.js";
+/** `AmbasadaError` under its 0.7 name. */
+export declare const VillageError: typeof AmbasadaError;
+export type VillageError = AmbasadaError;
+/** `isAmbasadaError` under its 0.7 name. */
+export declare const isVillageError: typeof isAmbasadaError;
+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 AmbasadaError {
+    readonly reason: ReceiptFailure;
+    constructor(reason: ReceiptFailure, message: string);
+}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @ambasada/village: the Hack A Ton add-on. Accept and spend TON in the village, on top of the
+ * Ambasada platform client (`@ambasada/sdk`).
+ *
+ *   import { village } from "@ambasada/village";         // AMBASADA_API_KEY, AMBASADA_VILLAGE_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}`) }));
+ *   const user = await village.auth.user(req);            // the platform client's methods work too
+ *
+ * Works in Node ≥ 22, Bun, Cloudflare Workers (`createVillage({ env })`) and Next.js route handlers.
+ */
+import { Village } from "./client.js";
+export { Village, createVillage, DEFAULT_VILLAGE_API_URL, DEFAULT_MODEL } from "./client.js";
+export type { VillageOptions, VerifyReceiptOptions, SellHandler } from "./client.js";
+export { VillageError, isVillageError, ReceiptInvalidError } from "./errors.js";
+export type { ReceiptFailure } 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, VillageConfig } from "./define.js";
+export { Ambasada, AmbasadaError, isAmbasadaError, defineApp, ERROR_STATUS, WebhookInvalidError } from "./sdk/platform.js";
+export type { AmbasadaUser, AppConfig, ErrorCode, ErrorDetails, Jwk, StoredFile, StoreList, StoreWrite, WebhookFailure } from "./sdk/platform.js";
+/** The default client, configured from the environment at call time. */
+export declare const village: Village;
+export default village;