@ambasada/village 0.8.4 → 0.8.6

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import { Ambasada, type AmbasadaOptions } from "@ambasada/sdk/platform";
 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, ChatLine, ChatProposal, ChatTurn, TransferOptions, Wallet, WebhookDelivery, WebhookEvent } from "./types.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";
 /** 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";
@@ -63,6 +63,20 @@ export declare class Village extends Ambasada {
         idempotencyKey?: string;
     }): Promise<CheckoutSession>;
     getCheckout(id: string): Promise<CheckoutSession>;
+    /** Your latest Checkout sessions (newest first, default 20, at most 100), each with what you said you delivered. */
+    listCheckouts(options?: {
+        limit?: number;
+        status?: "open" | "paid" | "expired";
+    }): Promise<{
+        sessions: (CheckoutSession & {
+            delivery: Omit<CheckoutDelivery, "session"> | null;
+        })[];
+    }>;
+    /**
+     * 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.
+     */
+    deliverCheckout(id: string, delivery: CheckoutDeliveryInput): Promise<CheckoutDelivery>;
     /** 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`). */

package/dist/define.d.ts

@@ -38,6 +38,7 @@ export interface OfferingDef {
     output?: FieldSchema;
     /** Allow a free sample (`market.preview`). */
     preview?: boolean;
+    /** How long the Gateway waits for your answer, ms: 100–30000 (default 30000, the most). Longer work: answer fast, finish later. */
     timeout_ms?: number;
     status?: "open" | "paused";
 }

package/dist/index.js

@@ -37,6 +37,7 @@ __export(src_exports, {
   HEADERS: () => HEADERS,
   HOSTED_MANIFEST: () => HOSTED_MANIFEST,
   ICON_SIZE: () => ICON_SIZE,
+  MANIFEST_AGE_RATINGS: () => MANIFEST_AGE_RATINGS,
   MANIFEST_CATEGORIES: () => MANIFEST_CATEGORIES,
   MANIFEST_ID: () => MANIFEST_ID,
   MANIFEST_KINDS: () => MANIFEST_KINDS,
@@ -49,8 +50,10 @@ __export(src_exports, {
   MIN_PRICE_NANO: () => MIN_PRICE_NANO,
   NANO_PER_TON: () => NANO_PER_TON,
   NOTIFY_LIMITS: () => NOTIFY_LIMITS,
+  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,
@@ -61,8 +64,10 @@ __export(src_exports, {
   appNotifyResult: () => appNotifyResult,
   appWebhookHeaders: () => appWebhookHeaders,
   base64url: () => base64url,
+  bundlesMiniappSdk: () => bundlesMiniappSdk,
   checkHtml: () => checkHtml,
   checkIcon: () => checkIcon,
+  checkPending: () => checkPending,
   checkRemote: () => checkRemote,
   createReceiptSigner: () => createReceiptSigner,
   decodeLeaf: () => decodeLeaf,
@@ -82,6 +87,7 @@ __export(src_exports, {
   leafHash: () => leafHash,
   listingLine: () => listingLine,
   nodeHash: () => nodeHash,
+  offeringTimeoutProblem: () => offeringTimeoutProblem,
   parseCheckpoint: () => parseCheckpoint,
   parseVerifierKey: () => parseVerifierKey,
   pngInfo: () => pngInfo,
@@ -1143,6 +1149,7 @@ var MANIFEST_SCHEMA = 2;
 var MANIFEST_KINDS = ["product", "event", "tool", "assistant"];
 var MANIFEST_CATEGORIES = ["shopping", "food", "events", "tools", "learning", "community", "games", "finance", "other"];
 var MANIFEST_VISIBILITY = ["public", "builders", "unlisted"];
+var MANIFEST_AGE_RATINGS = ["4+", "9+", "12+", "17+"];
 var MANIFEST_LIMITS = { id: 32, name: 32, subtitle: 40, description: 170, tags: 5, screenshots: 3 };
 var MANIFEST_ID = /^[a-z0-9-]{3,32}$/;
 var HOSTED_MANIFEST = /^https:\/\/hub\.ambasada\.id\/api\/apps\/([a-z0-9-]+)\/manifest$/;
@@ -1203,6 +1210,15 @@ function validateManifest(json) {
     const color = splash?.color;
     if (!splash || color !== void 0 && (typeof color !== "string" || !HEX_COLOR.test(color))) problem("splash_color", `"splash.color" must be a #RRGGBB colour (got ${JSON.stringify(color ?? m.splash)})`);
   }
+  const age = str("age_rating");
+  if (m.age_rating === void 0) {
+    if (m.schema === MANIFEST_SCHEMA) problem("age_rating", `"age_rating" is required: one of ${MANIFEST_AGE_RATINGS.join(", ")} (the hub refuses to register an app without it)`);
+  } else if (!age || !MANIFEST_AGE_RATINGS.includes(age)) {
+    problem("age_rating", `"age_rating" must be one of ${MANIFEST_AGE_RATINGS.join(", ")} (got ${JSON.stringify(m.age_rating)})`);
+  }
+  if (m.support !== void 0 && (typeof m.support !== "string" || !/^(mailto:[^@\s]+@[^@\s]+|https:\/\/\S+)$/.test(m.support))) {
+    problem("support", `"support" must be a mailto: address or an https URL (got ${JSON.stringify(m.support)})`);
+  }
   const kind = str("kind");
   if (m.kind !== void 0 && (!kind || !MANIFEST_KINDS.includes(kind))) warn("kind", `unknown "kind" ${JSON.stringify(m.kind)}: the app knows ${MANIFEST_KINDS.join(", ")} and shows this one as a product`);
   const category = str("category");
@@ -1261,7 +1277,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;
 }
@@ -1283,6 +1299,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();
@@ -1291,7 +1324,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}` });
@@ -1411,6 +1448,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) })),
@@ -1420,10 +1458,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";
 }
@@ -1464,6 +1504,12 @@ var HEADERS = {
   idempotentReplay: "idempotent-replayed"
 };
 var MAX_DEPTH = 4;
+var OFFERING_TIMEOUT_MS = { min: 100, max: 3e4 };
+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/receipt.ts
 import { AmbasadaError as AmbasadaError2, getHeader } from "@ambasada/sdk/platform";
@@ -1700,6 +1746,20 @@ var Village = class extends Ambasada {
   getCheckout(id) {
     return this.call("GET", `/v1/checkout/sessions/${encodeURIComponent(id)}`);
   }
+  /** Your latest Checkout sessions (newest first, default 20, at most 100), each with what you said you delivered. */
+  listCheckouts(options = {}) {
+    const q = new URLSearchParams();
+    if (options.limit !== void 0) q.set("limit", String(options.limit));
+    if (options.status) q.set("status", options.status);
+    return this.call("GET", `/v1/checkout/sessions${q.size ? `?${q}` : ""}`);
+  }
+  /**
+   * 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.
+   */
+  deliverCheckout(id, delivery) {
+    return this.call("POST", `/v1/checkout/sessions/${encodeURIComponent(id)}/delivery`, { body: delivery });
+  }
   /** A reusable payment link for static pages (`<button data-village-pay="pl_…">` with pay.js). */
   createPaymentLink(link) {
     return this.call("POST", "/v1/checkout/links", { body: link });
@@ -1873,6 +1933,8 @@ function defineCompany(app, village2) {
 function offering(def) {
   if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(def.name)) throw new Error(`offering name "${def.name}" must be a slug (a-z, 0-9, _, -)`);
   if (!(def.price >= 0.1 && def.price <= 500)) throw new Error(`offering ${def.name}: price must be between 0.1 and 500 TON`);
+  const timeout = offeringTimeoutProblem(def.timeout_ms);
+  if (timeout) throw new Error(`offering ${def.name}: ${timeout}`);
   return def;
 }
 

package/dist/types.d.ts

@@ -55,6 +55,17 @@ 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. */
+export interface CheckoutDeliveryInput {
+    text?: string;
+    url?: string;
+}
+export interface CheckoutDelivery {
+    session: string;
+    text: string | null;
+    url: string | null;
+    at: string;
+}
 export interface CheckoutSession {
     id: string;
     object: "checkout.session";
@@ -142,7 +153,8 @@ export interface BuyResult<Output = any> {
     /** 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 & {});
+/** What the village sells (apps/api/config/pricing.json); any other model is refused. */
+export type ChatModel = "deepseek-v4.1-flash" | (string & {});
 export interface ChatMessage {
     role: "system" | "user" | "assistant" | "tool";
     content: string;
@@ -154,8 +166,16 @@ export interface ChatRequest {
     messages: ChatMessage[];
     temperature?: number;
     max_tokens?: number;
+    /** `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;
 }
@@ -258,7 +278,7 @@ export interface TransferOptions {
 }
 /** `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";
+    model?: "deepseek-v4.1-flash";
     enabled?: boolean;
     wake?: {
         interval_minutes?: number;
@@ -272,7 +292,12 @@ export interface AgentSettings {
     };
     /** 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. */
+    /**
+     * The whole company's spend limits, TON: the product's own LLM and image calls count too, not only the agent's
+     * purchases. Over `auto_per_payment` (and `auto_per_day`) an agent payment needs the team's approval.
+     */
+    company_limits?: AgentSettings["limits"];
+    /** @deprecated The 0.8 name of `company_limits` (they were always the company's, not only the agent's). */
     limits?: {
         per_payment?: number;
         per_hour?: number;

package/package.json

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