@ambasada/sdk 0.0.0-stage → 0.1.0

package/dist/receipt.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Receipt verification. A paid call reaches a seller with `x-village-receipt`: an Ed25519 JWT signed
+ * by the village, committing to the buyer, seller, offering, amount and the SHA-256 of the exact body.
+ * The seller checks it offline against `<api>/.well-known/jwks.json` (cached), no round-trip.
+ */
+import type { CheckoutReceiptClaims, Jwk, ReceiptClaims } from "./types.js";
+import { type HeaderSource } from "./webhook.js";
+export declare const RECEIPT_HEADER = "x-village-receipt";
+export type KeySource = Jwk[] | (() => Promise<Jwk[]>);
+/** A fetch `Request`, or a Node / Express request (raw body in `body` / `rawBody`, or an unread stream). */
+export type IncomingRequest = Request | {
+    headers: HeaderSource;
+    body?: unknown;
+    rawBody?: unknown;
+    [Symbol.asyncIterator]?: () => AsyncIterator<unknown>;
+};
+export interface Incoming {
+    headers: HeaderSource;
+    body: Uint8Array;
+}
+/** Reads headers and the raw body without consuming a fetch `Request` (it is cloned). */
+export declare function readIncoming(req: IncomingRequest): Promise<Incoming>;
+export interface CallReceiptCheck {
+    keys: KeySource;
+    /** Your company id: required, so a receipt bought from someone else can't be replayed at you. */
+    seller: string;
+    /** `<seller>/<offering>`, when you want to pin the offering. */
+    offering?: string;
+    issuer?: string;
+    now?: number;
+}
+/** Verifies a call receipt token against the raw body. Throws `ReceiptInvalidError`. */
+export declare function verifyCallReceipt(token: string | null, body: Uint8Array, check: CallReceiptCheck): Promise<ReceiptClaims>;
+export interface CheckoutReceiptCheck {
+    keys: KeySource;
+    seller: string;
+    session?: string;
+    issuer?: string;
+    now?: number;
+    clockSkewSeconds?: number;
+}
+/** Verifies a checkout receipt (from pay.js `village:paid` or `session.receipt`) with `@ambasada/protocol`. Throws `ReceiptInvalidError`. */
+export declare function verifyCheckoutReceiptToken(token: string | null | undefined, check: CheckoutReceiptCheck): Promise<CheckoutReceiptClaims>;
+/** Remembers call ids until their receipt expires, so one receipt pays for one call (per process). */
+export declare class ReplayGuard {
+    private seen;
+    /** Returns false if the call id was already used. */
+    claim(callId: string, exp: number): boolean;
+}
+export declare function receiptHeader(headers: HeaderSource): string | null;

package/dist/types.d.ts

@@ -0,0 +1,321 @@
+/** Wire types. TON amounts are decimal numbers (`1`, `0.5`). */
+/** Ed25519 public key as served by `/.well-known/jwks.json`. */
+export interface Jwk {
+    kty: "OKP";
+    crv: "Ed25519";
+    x: string;
+    d?: string;
+    kid?: string;
+    alg?: "EdDSA";
+    use?: "sig";
+}
+/** What a seller learns from a Gateway call receipt (`x-village-receipt`). Same shape as `@ambasada/protocol`. */
+export interface ReceiptClaims {
+    iss: string;
+    jti: string;
+    call_id: string;
+    /** Buyer company id. */
+    buyer: string;
+    /** Your company id. */
+    seller: string;
+    /** `<seller>/<offering name>` */
+    offering: string;
+    /** TON */
+    amount: number;
+    /** 1 for a direct buy; forward it with `buy(…, { parent })`. */
+    depth: number;
+    /** TON you may still spend downstream on behalf of this call. */
+    budget?: number;
+    deal_id?: string;
+    body_sha256: string;
+    iat: number;
+    exp: number;
+}
+/** A verified paid call: the receipt plus the parsed JSON input. */
+export interface PaidCall<Input = any> extends ReceiptClaims {
+    input: Input;
+}
+/** A checkout receipt (pay.js `village:paid`, or `session.receipt`). */
+export interface CheckoutReceiptClaims {
+    iss: string;
+    jti: string;
+    kind: "checkout";
+    session: string;
+    /** The person's pseudonymous wallet id (`p_…`). */
+    buyer: string;
+    seller: string;
+    amount: number;
+    description: string;
+    ref?: string;
+    log_index: number;
+    iat: number;
+    exp: number;
+}
+export interface CheckoutInput {
+    /** TON, 0.1–500. Or give `offering` to charge one of your offerings' price. */
+    amount?: number;
+    offering?: string;
+    /** Shown to the person and written to the public ledger as the memo. No personal data. */
+    description: string;
+    /** `{CHECKOUT_SESSION_ID}` anywhere in the URL is replaced; otherwise `?session=cs_…` is appended. */
+    success_url: string;
+    cancel_url?: string;
+    client_reference_id?: string;
+    metadata?: Record<string, string>;
+    /** Seconds, 300–86400 (default 3600). */
+    expires_in?: number;
+}
+export interface CheckoutSession {
+    id: string;
+    object: "checkout.session";
+    url: string;
+    status: "open" | "paid" | "expired" | (string & {});
+    amount: number;
+    description: string;
+    offering: string | null;
+    /** The payment link it came from (`pl_…`), if any. */
+    link: string | null;
+    client_reference_id: string | null;
+    metadata: Record<string, string>;
+    success_url: string;
+    cancel_url: string | null;
+    buyer: string | null;
+    paid_at: string | null;
+    log_index: number | null;
+    receipt: string | null;
+    created_at: string;
+    expires_at: string;
+    [key: string]: unknown;
+}
+export interface PaymentLinkInput {
+    amount?: number;
+    offering?: string;
+    description: string;
+    success_url: string;
+    cancel_url?: string;
+    metadata?: Record<string, string>;
+}
+export interface PaymentLink {
+    id: string;
+    object: "checkout.link";
+    url: string;
+    active: boolean;
+    amount: number;
+    description: string;
+    offering: string | null;
+    metadata: Record<string, string>;
+    success_url: string;
+    cancel_url: string | null;
+    created_at: string;
+    [key: string]: unknown;
+}
+export interface WebhookDelivery {
+    id: string;
+    type: string;
+    status: "pending" | "delivered" | "failed" | (string & {});
+    attempts: number;
+    [key: string]: unknown;
+}
+export interface WebhookEvent<Data = any> {
+    /** `webhook-id` header: dedupe on it, retries reuse it. */
+    id: string;
+    type: "checkout.paid" | "webhook.test" | (string & {});
+    timestamp: string;
+    data: Data;
+}
+export interface BuyOptions {
+    /** Refuse (PRICE_ABOVE_MAX) if the offering costs more than this, in TON. */
+    maxPrice?: number;
+    /** Retries with the same key never charge twice. Default: a random key per call (reused by the SDK's own retry). */
+    idempotencyKey?: string;
+    /** Inside a paid handler: forward the chain depth and remaining budget of the call you are serving. */
+    parent?: Pick<ReceiptClaims, "depth" | "budget">;
+    /** TON this call may spend downstream (`x-village-budget`). */
+    budget?: number;
+    /** An approved approval id, after APPROVAL_REQUIRED. */
+    approval?: string;
+    /** Why you are buying; shown to your team on approval requests. */
+    reason?: string;
+    signal?: AbortSignal;
+}
+export interface BuyResult<Output = any> {
+    output: Output;
+    callId: string | null;
+    /** TON charged. */
+    amount: number | null;
+    /** The signed receipt for the call (you hold it too). */
+    receipt: string | null;
+    /** Position in the public ledger log. */
+    logIndex: number | null;
+    /** True when the Gateway replayed a previous result for the same idempotency key (no new charge). */
+    replayed: boolean;
+    /** For `need()`: which offering served it (`company/name`), if the Gateway says. */
+    offering: string | null;
+}
+export type ChatModel = "deepseek-v4.1-flash" | "deepseek-v4-pro" | "glm-5.3-flash" | (string & {});
+export interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    [key: string]: unknown;
+}
+/** OpenAI-compatible chat request. */
+export interface ChatRequest {
+    model?: ChatModel;
+    messages: ChatMessage[];
+    temperature?: number;
+    max_tokens?: number;
+    response_format?: {
+        type: "text" | "json_object";
+    } | Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface ChatResponse {
+    id: string;
+    object: "chat.completion";
+    model: string;
+    choices: {
+        index: number;
+        message: ChatMessage;
+        finish_reason: string | null;
+    }[];
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    [key: string]: unknown;
+}
+export interface ImageRequest {
+    model?: "nano_banana" | "gpt-image-2" | (string & {});
+    prompt: string;
+}
+export interface ImageResult {
+    /** Re-hosted in the village files store; safe to pass to other products. */
+    url: string;
+    /** TON charged. */
+    cost: number;
+    call_id: string;
+}
+export interface ToolListing {
+    id: string;
+    name: string;
+    description: string;
+    price_ton?: number;
+    price?: number;
+    unit?: string;
+    input?: unknown;
+    output?: unknown;
+    [key: string]: unknown;
+}
+export interface ToolResult<Output = any> {
+    output: Output;
+    callId: string | null;
+    /** TON charged. */
+    amount: number | null;
+    replayed: boolean;
+}
+export interface FileOptions {
+    contentType?: string;
+    ttlSeconds?: number;
+}
+/** Offering field schema shorthand: `{ text: "string", to: "string", tone: "string?" }`. */
+export type FieldSchema = Record<string, string>;
+export interface ListingInput {
+    description: string;
+    /** TON, 0.1–500. */
+    price: number;
+    /** Absolute URL the Gateway POSTs paid calls to. */
+    endpoint: string;
+    input?: FieldSchema | null;
+    output?: FieldSchema | null;
+    timeout_ms?: number;
+    status?: "open" | "paused";
+    preview?: boolean;
+}
+export interface Listing extends ListingInput {
+    id: string;
+    company: string;
+    name: string;
+    version: number;
+    [key: string]: unknown;
+}
+export interface Wallet {
+    account: string;
+    balance: number;
+    held: number;
+    available: number;
+}
+export interface LedgerEntry {
+    seq: number;
+    id: string;
+    ts: string;
+    kind: string;
+    direction: "in" | "out";
+    counterparty: string;
+    amount: number;
+    balance_after: number;
+    ref: string | null;
+    memo: string | null;
+    hold_id?: string | null;
+    log_index?: number | null;
+    [key: string]: unknown;
+}
+export interface LedgerPage {
+    entries: LedgerEntry[];
+    /** Pass back as `since` for the next page. */
+    next_since: number;
+}
+export interface TransferOptions {
+    reason?: string;
+    ref?: string;
+    idempotencyKey?: string;
+}
+/** `agent/settings.json`, sent with the prompt to `POST /v1/agent/config` (agent stream wire format). */
+export interface AgentSettings {
+    model?: "deepseek-v4.1-flash" | "deepseek-v4-pro";
+    enabled?: boolean;
+    wake?: {
+        interval_minutes?: number;
+        min_event_gap_seconds?: number;
+    };
+    budget?: {
+        tool_calls_per_wake?: number;
+        tokens_per_wake?: number;
+        max_turns?: number;
+        compute_per_day?: number;
+    };
+    /** Agent tools offered to the model (default: all). */
+    tools?: string[];
+    /** Company wallet spend limits, TON. Over `auto_per_payment` an agent payment needs the team's approval. */
+    limits?: {
+        per_payment?: number;
+        per_hour?: number;
+        per_day?: number;
+        per_payee_day?: number;
+        auto_per_payment?: number;
+        auto_per_day?: number;
+    };
+    [key: string]: unknown;
+}
+export interface AgentConfigInput extends AgentSettings {
+    /** The text of agent/agent.md. */
+    prompt?: string;
+    /** Wake the agent once after saving. */
+    wake_now?: boolean;
+}
+export interface TranscriptEntry {
+    seq: number;
+    ts: string;
+    kind: string;
+    data?: unknown;
+    [key: string]: unknown;
+}
+export interface MarketOffering {
+    id: string;
+    company?: string;
+    name: string;
+    description: string;
+    price: number;
+    source?: "company" | "village-tool";
+    [key: string]: unknown;
+}

package/dist/webhook.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Webhook signatures: Standard Webhooks (https://www.standardwebhooks.com), exactly as the village
+ * signs them in `@ambasada/protocol` (packages/protocol/src/webhook.ts):
+ *
+ *   webhook-id: msg_…   webhook-timestamp: <unix s>   webhook-signature: v1,<base64 HMAC-SHA256>
+ *   signed content = "<id>.<timestamp>.<raw body>", key = the base64 bytes after `whsec_`
+ *   body = { "type": "checkout.paid" | "webhook.test", "timestamp": ISO, "data": … }
+ *
+ * This module wraps the protocol functions with the SDK's error type and event shape.
+ */
+import type { WebhookEvent } from "./types.js";
+export { WEBHOOK_HEADERS, generateWebhookSecret, webhookHeaders } from "@ambasada/protocol";
+export type HeaderSource = Headers | Record<string, string | string[] | undefined | null>;
+export declare function getHeader(headers: HeaderSource, name: string): string | null;
+/**
+ * Verifies a raw webhook (headers + body exactly as received) and returns the event, or throws
+ * `WebhookInvalidError`. Prefer `village.verifyWebhook(req)`, which reads a `Request` for you.
+ */
+export declare function verifyWebhookPayload<Data = any>(secret: string, headers: HeaderSource, body: string | Uint8Array, options?: {
+    toleranceSeconds?: number;
+    now?: number;
+}): Promise<WebhookEvent<Data>>;

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@ambasada/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "TypeScript SDK for the Hack A Ton village: Checkout, webhooks, receipts, Pay, needs, LLM, images, tools, files, listings, wallet.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "esbuild": "^0.28.2",
+    "typescript": "~5.9.3",
+    "vitest": "^4.1.12",
+    "@ambasada/protocol": "0.1.0"
+  },
+  "author": "CENTYSO (https://centyso.com)",
+  "homepage": "https://ambasada.id",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ambasada/cli.git",
+    "directory": "packages/sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/ambasada/cli/issues"
+  },
+  "keywords": [
+    "ambasada",
+    "hack-a-ton",
+    "ton",
+    "payments",
+    "cloudflare",
+    "agents"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc -p .",
+    "test": "vitest run"
+  }
 }