@ambasada/sdk 0.7.5 → 0.8.0

package/dist/village/types.d.ts

@@ -0,0 +1,307 @@
+/** Village wire types. TON amounts are decimal numbers (`1`, `0.5`). */
+/** 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;
+}
+/** 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 → village/webhook.d.ts}

@@ -8,10 +8,18 @@
  *
  * This module wraps the protocol functions with the SDK's error type and event shape.
  */
+import { type HeaderSource } from "../platform.js";
 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;
+/** The three Standard Webhooks headers. */
+export declare const WEBHOOK_HEADERS: {
+    readonly id: "webhook-id";
+    readonly timestamp: "webhook-timestamp";
+    readonly signature: "webhook-signature";
+};
+/** A fresh `whsec_…` signing secret. */
+export declare const generateWebhookSecret: () => string;
+/** The headers that sign `body` (tests, your own senders). */
+export declare const webhookHeaders: (secret: string, id: string, timestamp: number, body: string) => Promise<Record<string, string>>;
 /**
  * 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.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ambasada/sdk",
-  "version": "0.7.5",
-  "description": "TypeScript SDK for the Hack A Ton village: Checkout, webhooks, receipts, Pay, needs, LLM, images, tools, files, listings, wallet.",
+  "version": "0.8.0",
+  "description": "The Ambasada platform SDK: Sign in with Ambasada, mini-app notifications, the project store, files.",
   "type": "module",
   "license": "MIT",
   "sideEffects": false,
@@ -27,7 +27,8 @@
     "esbuild": "^0.28.2",
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",
-    "@ambasada/protocol": "0.1.0"
+    "@ambasada/protocol": "0.1.0",
+    "@ambasada/village": "0.8.0"
   },
   "author": "CENTYSO (https://centyso.com)",
   "homepage": "https://ambasada.id",
@@ -41,11 +42,10 @@
   },
   "keywords": [
     "ambasada",
-    "hack-a-ton",
-    "ton",
-    "payments",
     "cloudflare",
-    "agents"
+    "workers",
+    "auth",
+    "mini-apps"
   ],
   "scripts": {
     "build": "node scripts/build.mjs",