@ambasada/village 0.8.5 → 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, {
@@ -53,18 +37,23 @@ __export(src_exports, {
   OFFERING_TIMEOUT_MS: () => OFFERING_TIMEOUT_MS,
   RECEIPT_HEADER: () => RECEIPT_HEADER,
   ReceiptError: () => ReceiptError,
+  SDK_SCRIPT_LIMIT: () => SDK_SCRIPT_LIMIT,
   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,
   appNotifyResult: () => appNotifyResult,
   appWebhookHeaders: () => appWebhookHeaders,
   base64url: () => base64url,
+  bundlesMiniappSdk: () => bundlesMiniappSdk,
   checkHtml: () => checkHtml,
   checkIcon: () => checkIcon,
+  checkPending: () => checkPending,
   checkRemote: () => checkRemote,
   createReceiptSigner: () => createReceiptSigner,
   decodeLeaf: () => decodeLeaf,
@@ -186,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;
@@ -1274,7 +1263,7 @@ function checkHtml(html) {
   const darkStyle = [...html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)].concat([...html.matchAll(/\bstyle\s*=\s*"([^"]*)"/gi)]).some(([, css]) => [...css.matchAll(/color-scheme\s*:\s*([^;}"]+)/gi)].some(([, v]) => /\bdark\b/i.test(v) && !/\blight\b/i.test(v)));
   if (darkMeta || darkStyle) f.problems.push({ code: "dark_only", message: "the entry page declares a dark-only color-scheme; the Ambasada app is light (use light, or light dark)" });
   if (!SDK_MARKERS.some((m) => html.includes(m))) {
-    f.warnings.push({ code: "no_miniapp_sdk", message: "no @ambasada/miniapp, miniapp.js or ambasadaShell in the entry HTML: a bundled import is fine too, the registry crawler confirms ready() is called at runtime" });
+    f.warnings.push({ code: "no_miniapp_sdk", message: "no @ambasada/miniapp, miniapp.js or ambasadaShell in the entry HTML or its scripts: the Ambasada app waits for ready() to drop the splash" });
   }
   return f;
 }
@@ -1296,6 +1285,23 @@ async function probeManifest(origin, fetchImpl = fetch) {
     return { on: false, entry: null };
   }
 }
+var SDK_SCRIPT_LIMIT = 16;
+var BUNDLED_SDK = /ambasadaShell|@ambasada\/miniapp/;
+async function bundlesMiniappSdk(fetchImpl, pageUrl, html) {
+  const origin = new URL(pageUrl).origin;
+  const srcs = [...html.matchAll(/<script\b[^>]*\bsrc\s*=\s*["']([^"']+)["']/gi)].map(([, src]) => URL.canParse(src, pageUrl) ? new URL(src, pageUrl) : null).filter((u) => !!u && u.origin === origin).slice(0, SDK_SCRIPT_LIMIT);
+  const found = await Promise.all(
+    srcs.map(async (u) => {
+      try {
+        const res = await get(fetchImpl, u.toString());
+        return res.status === 200 && BUNDLED_SDK.test(await res.text());
+      } catch {
+        return false;
+      }
+    })
+  );
+  return found.includes(true);
+}
 async function checkPage(fetchImpl, url, report, html) {
   try {
     const started = Date.now();
@@ -1304,7 +1310,11 @@ async function checkPage(fetchImpl, url, report, html) {
     if (!html) await res.body?.cancel();
     const ms = Date.now() - started;
     if (res.status !== 200) report.problems.push({ code: "entry_status", message: `${url} answered ${res.status}${res.headers.get("location") ? ` \u2192 ${res.headers.get("location")}` : ""}; ${html ? "the entry" : "the app"} must answer 200 without redirects` });
-    else if (html) merge(report, checkHtml(text));
+    else if (html) {
+      const found = checkHtml(text);
+      if (found.warnings.some((w) => w.code === "no_miniapp_sdk") && await bundlesMiniappSdk(fetchImpl, url, text)) found.warnings = found.warnings.filter((w) => w.code !== "no_miniapp_sdk");
+      merge(report, found);
+    }
     if (ms > SLOW_ENTRY_MS) report.warnings.push({ code: "slow_entry", message: `${url} took ${ms} ms; aim for under ${SLOW_ENTRY_MS} ms${html ? " (the splash stays until ready())" : ""}` });
   } catch (error) {
     report.problems.push({ code: "entry_fetch", message: `could not fetch ${url}: ${error.message}` });
@@ -1424,6 +1434,7 @@ var LABELS = [
 function findingLabel(code) {
   return LABELS.find(([re]) => re.test(code))?.[1] ?? code.replace(/_/g, " ");
 }
+var checkPending = (check) => check?.status === "pending";
 function summarizeCheck(report, now = /* @__PURE__ */ new Date()) {
   const issues = [
     ...report.problems.map((p) => ({ ...p, level: "problem", label: findingLabel(p.code) })),
@@ -1433,10 +1444,12 @@ function summarizeCheck(report, now = /* @__PURE__ */ new Date()) {
   const miniapp = report.miniapp ? { miniapp: report.miniapp.on ? "on" : "off", entry: report.miniapp.entry } : {};
   return { ok: report.ok, issues, needs, checked_at: now.toISOString(), ...miniapp };
 }
-function listingLine(tier, check) {
+function listingLine(tier, check, kind = "company") {
   if (check?.miniapp === "off") return "Mini app: off";
+  const listed = kind === "project" ? "Listed" : "Listed for the event";
+  if (checkPending(check)) return `${tier === "verified" ? "Verified" : tier === "listed" ? listed : tier === "unlisted" ? "Unlisted" : "Not registered yet"} \xB7 checking\u2026`;
   if (tier === "verified") return "Verified";
-  if (tier === "listed") return "Listed for the event";
+  if (tier === "listed") return listed;
   if (tier === "unlisted") return check?.needs.length ? `Unlisted \xB7 needs: ${check.needs.join(", ")}` : "Unlisted";
   return check?.needs.length ? `Not registered yet \xB7 needs: ${check.needs.join(", ")}` : "Not registered yet";
 }
@@ -1478,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";
@@ -1600,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() {
@@ -1728,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 });
@@ -1762,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`);
   }
@@ -1818,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. */
@@ -1836,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;
@@ -1924,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,8 +177,18 @@ 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";
+    } | {
+        type: "json_schema";
+        json_schema: {
+            name: string;
+            schema: Record<string, unknown>;
+            strict?: boolean;
+        };
     } | Record<string, unknown>;
     [key: string]: unknown;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ambasada/village",
-  "version": "0.8.5",
+  "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.5"
+    "@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.5"
+    "@ambasada/cli": "0.8.7"
   },
   "author": "CENTYSO (https://centyso.com)",
   "homepage": "https://ambasada.id",