@ambasada/village 0.8.3 → 0.8.5

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, 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`). */
@@ -136,8 +150,25 @@ export declare class Village extends Ambasada {
             config: unknown;
             limits?: unknown;
         }>;
-        /** A message the agent answers on its next wake. */
+        /** A message from the team: the agent answers in the chat now, and reads it on its next wake. */
         steer: (text: string) => Promise<unknown>;
+        /**
+         * Talk to your agent (docs/AGENT-CHAT.md). With `wait` (the default) it resolves with the reply, up to a
+         * minute; the same `idempotencyKey` is the same turn, so a retry never asks twice.
+         */
+        chat: (text: string, options?: {
+            idempotencyKey?: string;
+            wait?: boolean;
+        }) => Promise<ChatTurn>;
+        /** The chat, oldest first: your words, the agent's replies and proposals, and cards for what happened. */
+        messages: (options?: {
+            since?: number;
+            limit?: number;
+        }) => Promise<ChatLine[]>;
+        /** Proposals waiting for your team. */
+        proposals: () => Promise<ChatProposal[]>;
+        /** Approve (it runs now) or decline a proposal. */
+        decide: (id: string, decision: "approve" | "decline", reason?: string) => Promise<unknown>;
         transcript: (since?: number, limit?: number) => Promise<{
             entries: TranscriptEntry[];
             next_since: number;

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,6 +50,7 @@ __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,
   SHELL_TOKEN_TTL_S: () => SHELL_TOKEN_TTL_S,
@@ -82,6 +84,7 @@ __export(src_exports, {
   leafHash: () => leafHash,
   listingLine: () => listingLine,
   nodeHash: () => nodeHash,
+  offeringTimeoutProblem: () => offeringTimeoutProblem,
   parseCheckpoint: () => parseCheckpoint,
   parseVerifierKey: () => parseVerifierKey,
   pngInfo: () => pngInfo,
@@ -152,6 +155,8 @@ var ERROR_STATUS = {
   BUDGET_EXCEEDED: 402,
   CAP_INBOX_RATE: 429,
   // inbox texts: 20 an hour, 1 unsolicited per counterparty an hour (EXCHANGE.md §8)
+  CAP_CHAT_RATE: 429,
+  // turns of the CEO chat per company (docs/AGENT-CHAT.md)
   // Additions needed by the gateway and bank
   UPSTREAM_ERROR: 502,
   PRICE_ABOVE_MAX: 409,
@@ -1141,6 +1146,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$/;
@@ -1201,6 +1207,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");
@@ -1462,6 +1477,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";
@@ -1698,6 +1719,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 });
@@ -1841,8 +1876,19 @@ var Village = class extends Ambasada {
   agent = {
     /** Replaces the agent's prompt (`agent.md`) and settings (`settings.json`). */
     config: (config) => this.call("POST", "/v1/agent/config", { body: config }),
-    /** A message the agent answers on its next wake. */
+    /** A message from the team: the agent answers in the chat now, and reads it on its next wake. */
     steer: (text) => this.call("POST", "/v1/agent/steer", { body: { text } }),
+    /**
+     * Talk to your agent (docs/AGENT-CHAT.md). With `wait` (the default) it resolves with the reply, up to a
+     * minute; the same `idempotencyKey` is the same turn, so a retry never asks twice.
+     */
+    chat: (text, options = {}) => this.call("POST", "/v1/agent/chat/turn", { body: { text, wait: options.wait ?? true, idempotency_key: options.idempotencyKey ?? randomKey() } }),
+    /** The chat, oldest first: your words, the agent's replies and proposals, and cards for what happened. */
+    messages: async (options = {}) => (await this.call("GET", "/v1/agent/chat/messages", { query: { limit: options.limit ?? 50, ...options.since ? { since: options.since } : {} } })).messages,
+    /** Proposals waiting for your team. */
+    proposals: async () => (await this.call("GET", "/v1/agent/chat/proposals")).proposals,
+    /** Approve (it runs now) or decline a proposal. */
+    decide: (id, decision, reason) => this.call("POST", `/v1/agent/chat/proposals/${encodeURIComponent(id)}`, { body: { decision, ...reason ? { reason } : {} } }),
     transcript: (since = 0, limit = 200) => this.call("GET", "/v1/agent/transcript", { query: { since, limit } }),
     state: () => this.call("GET", "/v1/agent/state")
   };
@@ -1860,6 +1906,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;
@@ -258,7 +270,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 +284,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;
@@ -296,6 +313,45 @@ export interface TranscriptEntry {
     data?: unknown;
     [key: string]: unknown;
 }
+/** Something the agent wants to do, waiting for the team in the chat (docs/AGENT-CHAT.md). */
+export interface ChatProposal {
+    /** What `agent.decide(id, …)` takes. */
+    id: string;
+    tool: string;
+    /** One plain sentence: "Change the price of translate to 1.2 TON". */
+    text: string;
+    input: unknown;
+    risk?: "low" | "medium" | "high";
+    state: "pending" | "approved" | "declined" | "done" | "failed";
+}
+/** One line of the chat with your agent: your words, its reply (with proposals), or a card for what happened. */
+export interface ChatLine {
+    id: string;
+    role: "user" | "agent" | "card" | "village";
+    at: number | null;
+    text: string;
+    card?: {
+        id: string;
+        kind: string;
+        title: string;
+        body?: string | null;
+        delta_ton?: number | null;
+        from?: string | null;
+        at: number;
+    };
+    proposals?: ChatProposal[];
+    cost_ton?: number;
+}
+export interface ChatTurn {
+    submission_id: string;
+    message_id: string;
+    /** false when this idempotency key was already sent: the same turn, not a new one. */
+    accepted: boolean;
+    /** With `wait`: how the turn ended and the agent's reply. */
+    status?: "completed" | "error" | "aborted" | "skipped" | "pending" | "running";
+    error?: string;
+    reply?: ChatLine | null;
+}
 export interface MarketOffering {
     id: string;
     company?: string;

package/package.json

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