@ambasada/village 0.8.6 → 0.8.7

package/dist/client.d.ts

@@ -1,11 +1,17 @@
 import { Ambasada, type AmbasadaOptions } from "@ambasada/sdk/platform";
 import { type IncomingRequest } from "./receipt.js";
 import type { AgentConfigInput, BuyOptions, BuyResult, ChatRequest, ChatResponse, CheckoutInput, CheckoutReceiptClaims, CheckoutDelivery, CheckoutDeliveryInput, CheckoutSession, ImageRequest, ImageResult, LedgerPage, Listing, ListingInput, MarketOffering, PaidCall, PaymentLink, PaymentLinkInput, ToolListing, ToolResult, TranscriptEntry, ChatLine, ChatProposal, ChatTurn, TransferOptions, Wallet, WebhookDelivery, WebhookEvent } from "./types.js";
+/** How long a utility call may take here: the API's own limit plus a margin, so the SDK never gives up on a call the API finishes and charges. */
+export declare const CLIENT_TIMEOUT_MS: {
+    readonly llm: number;
+    readonly image: number;
+    readonly tool: number;
+};
 /** 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`. */
+    /** Team key (`sk_live_…`, from the village app → Team → Settings). Default: `AMBASADA_API_KEY`. */
     apiKey?: string;
     /**
      * Default: `AMBASADA_VILLAGE_API_URL`, else `AMBASADA_API_URL` when it is not the platform host (0.7
@@ -74,7 +80,9 @@ export declare class Village extends Ambasada {
     }>;
     /**
      * Tells the village what a paid checkout delivered (`text` ≤ 4000 chars, an https `url`, or both): the person sees it
-     * with the purchase in their app and can rate it. Again for the same session replaces it. CONFLICT before it is paid.
+     * with the purchase in their app (one push, the first time) and can rate it. The same delivery again changes nothing;
+     * a new text replaces it. `{ status: "working" }` / `{ status: "failed", error }` while the work runs or when it gave
+     * up (never over a delivery). CONFLICT before it is paid.
      */
     deliverCheckout(id: string, delivery: CheckoutDeliveryInput): Promise<CheckoutDelivery>;
     /** A reusable payment link for static pages (`<button data-village-pay="pl_…">` with pay.js). */
@@ -101,6 +109,7 @@ export declare class Village extends Ambasada {
     }>;
     /** Sends a `webhook.test` event now and returns the delivery. */
     testWebhook(): Promise<WebhookDelivery>;
+    /** Sends a failed or pending delivery again now (same `webhook-id`). CONFLICT for one already delivered: it never goes out twice. */
     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>>;

package/dist/index.js

@@ -4,22 +4,6 @@ var __export = (target, all) => {
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
-// src/client.ts
-import { Ambasada, AmbasadaError as AmbasadaError3 } from "@ambasada/sdk/platform";
-
-// src/errors.ts
-import { AmbasadaError, isAmbasadaError } from "@ambasada/sdk/platform";
-var VillageError = AmbasadaError;
-var isVillageError = isAmbasadaError;
-var ReceiptInvalidError = class extends AmbasadaError {
-  reason;
-  constructor(reason, message) {
-    super("RECEIPT_INVALID", `payment required: ${message}`, 402, { reason });
-    this.name = "ReceiptInvalidError";
-    this.reason = reason;
-  }
-};
-
 // ../protocol/src/index.ts
 var src_exports = {};
 __export(src_exports, {
@@ -57,7 +41,9 @@ __export(src_exports, {
   SHELL_TOKEN_TTL_S: () => SHELL_TOKEN_TTL_S,
   SLOW_ENTRY_MS: () => SLOW_ENTRY_MS,
   SYSTEM_ACCOUNT: () => SYSTEM_ACCOUNT,
-  VillageError: () => VillageError2,
+  UTILITY_CLIENT_MARGIN_MS: () => UTILITY_CLIENT_MARGIN_MS,
+  UTILITY_TIMEOUT_MS: () => UTILITY_TIMEOUT_MS,
+  VillageError: () => VillageError,
   WEBHOOK_HEADERS: () => WEBHOOK_HEADERS,
   WebhookError: () => WebhookError,
   appNotifyBody: () => appNotifyBody,
@@ -189,7 +175,7 @@ var ERROR_STATUS = {
   // Deploy-freeze and unattended windows: agents keep running, but config and steer are closed (DESIGN.md §5)
   FROZEN: 403
 };
-var VillageError2 = class extends Error {
+var VillageError = class extends Error {
   code;
   status;
   details;
@@ -1505,12 +1491,30 @@ var HEADERS = {
 };
 var MAX_DEPTH = 4;
 var OFFERING_TIMEOUT_MS = { min: 100, max: 3e4 };
+var UTILITY_TIMEOUT_MS = { llm: 12e4, image: 18e4, tool: 6e4 };
+var UTILITY_CLIENT_MARGIN_MS = 1e4;
 function offeringTimeoutProblem(value) {
   if (value === void 0) return null;
   const n = Number(value);
   return Number.isInteger(n) && n >= OFFERING_TIMEOUT_MS.min && n <= OFFERING_TIMEOUT_MS.max ? null : `timeout_ms must be between ${OFFERING_TIMEOUT_MS.min} and ${OFFERING_TIMEOUT_MS.max} (got ${JSON.stringify(value)})`;
 }
 
+// src/client.ts
+import { Ambasada, AmbasadaError as AmbasadaError3 } from "@ambasada/sdk/platform";
+
+// src/errors.ts
+import { AmbasadaError, isAmbasadaError } from "@ambasada/sdk/platform";
+var VillageError2 = AmbasadaError;
+var isVillageError = isAmbasadaError;
+var ReceiptInvalidError = class extends AmbasadaError {
+  reason;
+  constructor(reason, message) {
+    super("RECEIPT_INVALID", `payment required: ${message}`, 402, { reason });
+    this.name = "ReceiptInvalidError";
+    this.reason = reason;
+  }
+};
+
 // src/receipt.ts
 import { AmbasadaError as AmbasadaError2, getHeader } from "@ambasada/sdk/platform";
 var RECEIPT_HEADER2 = "x-village-receipt";
@@ -1627,6 +1631,11 @@ async function verifyWebhookPayload(secret, headers, body, options = {}) {
 }
 
 // src/client.ts
+var CLIENT_TIMEOUT_MS = {
+  llm: UTILITY_TIMEOUT_MS.llm + UTILITY_CLIENT_MARGIN_MS,
+  image: UTILITY_TIMEOUT_MS.image + UTILITY_CLIENT_MARGIN_MS,
+  tool: UTILITY_TIMEOUT_MS.tool + UTILITY_CLIENT_MARGIN_MS
+};
 var DEFAULT_VILLAGE_API_URL = "https://hackaton.ambasada.id";
 var DEFAULT_MODEL = "deepseek-v4.1-flash";
 function randomKey() {
@@ -1755,7 +1764,9 @@ var Village = class extends Ambasada {
   }
   /**
    * Tells the village what a paid checkout delivered (`text` ≤ 4000 chars, an https `url`, or both): the person sees it
-   * with the purchase in their app and can rate it. Again for the same session replaces it. CONFLICT before it is paid.
+   * with the purchase in their app (one push, the first time) and can rate it. The same delivery again changes nothing;
+   * a new text replaces it. `{ status: "working" }` / `{ status: "failed", error }` while the work runs or when it gave
+   * up (never over a delivery). CONFLICT before it is paid.
    */
   deliverCheckout(id, delivery) {
     return this.call("POST", `/v1/checkout/sessions/${encodeURIComponent(id)}/delivery`, { body: delivery });
@@ -1789,6 +1800,7 @@ var Village = class extends Ambasada {
   testWebhook() {
     return this.call("POST", "/v1/webhook/test");
   }
+  /** Sends a failed or pending delivery again now (same `webhook-id`). CONFLICT for one already delivered: it never goes out twice. */
   retryWebhookDelivery(id) {
     return this.call("POST", `/v1/webhook/deliveries/${encodeURIComponent(id)}/retry`);
   }
@@ -1845,12 +1857,13 @@ var Village = class extends Ambasada {
       return res.choices[0]?.message.content ?? "";
     },
     {
-      chat: (req) => this.call("POST", "/v1/llm/chat", { body: { ...req, model: req.model ?? DEFAULT_MODEL } })
+      // The API waits up to 120 s for the model (one that reasons first can take a minute): not the client's 45 s.
+      chat: (req) => this.call("POST", "/v1/llm/chat", { body: { ...req, model: req.model ?? DEFAULT_MODEL }, timeoutMs: CLIENT_TIMEOUT_MS.llm })
     }
   );
   images = {
     /** Generates an image; the URL is re-hosted in the village files store. Default model: nano_banana. */
-    generate: (req) => this.call("POST", "/v1/images", { body: { ...req, model: req.model ?? "nano_banana" } })
+    generate: (req) => this.call("POST", "/v1/images", { body: { ...req, model: req.model ?? "nano_banana" }, timeoutMs: CLIENT_TIMEOUT_MS.image })
   };
   tools = {
     /** The curated LLMOK tool catalog with TON prices. */
@@ -1863,6 +1876,8 @@ var Village = class extends Ambasada {
       const res = await this.send("POST", `/v1/tools/${encodeURIComponent(id)}`, {
         body: input ?? {},
         retry: true,
+        // Image tools take as long as images; a routed search may try several providers within the API's 60 s.
+        timeoutMs: id.startsWith("image.") ? CLIENT_TIMEOUT_MS.image : CLIENT_TIMEOUT_MS.tool,
         headers: { "idempotency-key": options.idempotencyKey ?? randomKey() }
       });
       const json = res.json;
@@ -1951,7 +1966,7 @@ export {
   RECEIPT_HEADER2 as RECEIPT_HEADER,
   ReceiptInvalidError,
   Village,
-  VillageError,
+  VillageError2 as VillageError,
   WEBHOOK_HEADERS2 as WEBHOOK_HEADERS,
   WebhookInvalidError2 as WebhookInvalidError,
   createVillage,

package/dist/types.d.ts

@@ -55,15 +55,26 @@ export interface CheckoutInput {
     /** Seconds, 300–86400 (default 3600). */
     expires_in?: number;
 }
-/** What a paid checkout delivered (`POST /v1/checkout/sessions/:id/delivery`): text, an https URL, or both. */
+/**
+ * What a paid checkout delivered (`POST /v1/checkout/sessions/:id/delivery`): text, an https URL, or both. While the
+ * work runs (the templates' Jobs Durable Object), `status: "working"` (with `error`: why the last attempt failed, while
+ * it retries); `status: "failed"` with `error` when it gives up. `ambasada village deliveries` shows all three.
+ */
 export interface CheckoutDeliveryInput {
     text?: string;
     url?: string;
+    /** Default `delivered` (with text and/or url). */
+    status?: "working" | "delivered" | "failed";
+    /** Why an attempt failed (working: retrying) or why it gave up (failed); at most 300 characters are kept. */
+    error?: string;
 }
 export interface CheckoutDelivery {
     session: string;
+    /** `delivered` when the API predates delivery statuses. */
+    status?: "working" | "delivered" | "failed";
     text: string | null;
     url: string | null;
+    error?: string | null;
     at: string;
 }
 export interface CheckoutSession {
@@ -166,6 +177,8 @@ export interface ChatRequest {
     messages: ChatMessage[];
     temperature?: number;
     max_tokens?: number;
+    /** How much the model thinks before it answers; the village sends "low" when you leave it out. More thinking takes longer and more of `max_tokens`. */
+    reasoning_effort?: "low" | "medium" | "high" | (string & {});
     /** `json_schema`: JSON in the schema's shape (live, and the mock's sample of it under `ambasada dev`); `json_object`: any JSON. */
     response_format?: {
         type: "text" | "json_object";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ambasada/village",
-  "version": "0.8.6",
+  "version": "0.8.7",
   "description": "The Hack A Ton add-on for Ambasada apps: TON checkout, receipts, offerings, LLM, the agent, the market; CLI commands and the local bank.",
   "type": "module",
   "license": "MIT",
@@ -27,7 +27,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@ambasada/sdk": "^0.8.6"
+    "@ambasada/sdk": "^0.8.7"
   },
   "devDependencies": {
     "@types/node": "^22.20.5",
@@ -35,7 +35,7 @@
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",
     "@ambasada/protocol": "0.1.0",
-    "@ambasada/cli": "0.8.6"
+    "@ambasada/cli": "0.8.7"
   },
   "author": "CENTYSO (https://centyso.com)",
   "homepage": "https://ambasada.id",