@ambasada/village 0.8.10 → 0.8.11

package/dist/client.d.ts

@@ -53,11 +53,23 @@ export declare class Village extends Ambasada {
     /**
      * Wraps a paid offering as a fetch handler: verifies the receipt (402 if missing or bad), runs
      * `handler(input, call, req)` and answers JSON. A thrown `AmbasadaError` keeps its status (the
-     * Gateway then refunds the buyer).
+     * Gateway then refunds the buyer). The buyer pays only for what you deliver, so a handler that returns an error
+     * object (`{ error: { code, message } }`) or nothing (`undefined`, `null`, `""`) is answered as an error too, never
+     * 200 (dry run 7 #8: "busy, try again" answers were charged). If you can't deliver the paid thing (a tool you
+     * need is rate-limited, CAP_TOOLS_RATE, or down, TOOL_UNAVAILABLE), throw, or rethrow what you caught: the buyer
+     * is refunded and told when to try again.
      *
      *   export default village.sell("translate", async ({ text, to }) => ({ text: await village.llm(`…`) }));
      */
     sell<Input = any, Output = unknown>(offering: string, handler: SellHandler<Input, Output>): (req: Request) => Promise<Response>;
+    /**
+     * A warning worth seeing in `ambasada logs` even though the request succeeded, e.g. an answer degraded because a
+     * tool was rate-limited: `console.warn("[village]", …)`. The templates send a request's `[village]` lines along with
+     * any answer, and ambasada.dev keeps them as warnings (at most 50 an hour; never counted as errors).
+     *
+     *   village.warn("wikipedia.search: CAP_TOOLS_RATE, answering from the model alone");
+     */
+    warn(...message: unknown[]): void;
     /**
      * An async offering's answer to a paid call (`async: true` in offerings.ts): the work goes on as job `id` (in the
      * template, a Jobs Durable Object named after it), and the Gateway asks `GET <endpoint>/jobs/<id>` until it is done.

package/dist/index.js

@@ -1749,7 +1749,11 @@ var Village = class extends Ambasada {
   /**
    * Wraps a paid offering as a fetch handler: verifies the receipt (402 if missing or bad), runs
    * `handler(input, call, req)` and answers JSON. A thrown `AmbasadaError` keeps its status (the
-   * Gateway then refunds the buyer).
+   * Gateway then refunds the buyer). The buyer pays only for what you deliver, so a handler that returns an error
+   * object (`{ error: { code, message } }`) or nothing (`undefined`, `null`, `""`) is answered as an error too, never
+   * 200 (dry run 7 #8: "busy, try again" answers were charged). If you can't deliver the paid thing (a tool you
+   * need is rate-limited, CAP_TOOLS_RATE, or down, TOOL_UNAVAILABLE), throw, or rethrow what you caught: the buyer
+   * is refunded and told when to try again.
    *
    *   export default village.sell("translate", async ({ text, to }) => ({ text: await village.llm(`…`) }));
    */
@@ -1765,7 +1769,16 @@ var Village = class extends Ambasada {
       }
       try {
         const out = await handler(call.input, call, req);
-        return out instanceof Response ? out : Response.json(out);
+        if (out instanceof Response) return out;
+        if (out === void 0 || out === null || out === "") {
+          return new AmbasadaError3("UPSTREAM_ERROR", `the ${offering2} handler returned nothing; the buyer is refunded (return what was paid for, or throw)`, 502).toResponse();
+        }
+        const error = out.error;
+        if (typeof error === "object" && error !== null && typeof error.code === "string") {
+          const { code, message, ...details } = error;
+          return new AmbasadaError3(code, typeof message === "string" ? message : code, void 0, details).toResponse();
+        }
+        return Response.json(out);
       } catch (error) {
         if (error instanceof AmbasadaError3) return error.toResponse();
         console.error(error);
@@ -1773,6 +1786,16 @@ var Village = class extends Ambasada {
       }
     };
   }
+  /**
+   * A warning worth seeing in `ambasada logs` even though the request succeeded, e.g. an answer degraded because a
+   * tool was rate-limited: `console.warn("[village]", …)`. The templates send a request's `[village]` lines along with
+   * any answer, and ambasada.dev keeps them as warnings (at most 50 an hour; never counted as errors).
+   *
+   *   village.warn("wikipedia.search: CAP_TOOLS_RATE, answering from the model alone");
+   */
+  warn(...message) {
+    console.warn("[village]", ...message);
+  }
   /**
    * An async offering's answer to a paid call (`async: true` in offerings.ts): the work goes on as job `id` (in the
    * template, a Jobs Durable Object named after it), and the Gateway asks `GET <endpoint>/jobs/<id>` until it is done.

package/dist/types.d.ts

@@ -17,7 +17,7 @@ export interface ReceiptClaims {
     /** TON you may still spend downstream on behalf of this call. */
     budget?: number;
     deal_id?: string;
-    /** An async offering's call: when the buyer's max_wait_s runs out (unix seconds); `startJob(…, { deadline: call.deadline * 1000 })`. */
+    /** An async offering's call: when the buyer's max_wait_s runs out (unix seconds); pass it as it is: `startJob(…, { deadline: call.deadline })` (the templates' jobs take seconds or ms). */
     deadline?: number;
     body_sha256: string;
     iat: number;
@@ -159,7 +159,7 @@ export interface BuyOptions {
 }
 /** What an async offering's `GET <endpoint>/jobs/<id>` says (village.jobStatus): the Gateway settles on done or failed. */
 export type JobAnswer = 
-/** `attempts`: the failed ones so far (the template's `jobAnswer(job)`); the buyer sees "working (attempt 2, last error: …)". */
+/** `attempts`: the failed ones so far (the template's `jobAnswer(job)`); the buyer sees "working (attempt 1 failed: …; retrying)". */
 {
     status: "working";
     attempts?: {
@@ -344,6 +344,8 @@ export interface AgentSettings {
     };
     /** Agent tools offered to the model (default: all). */
     tools?: string[];
+    /** A wake changes one offering's price at most this often, in minutes (default 120; 0: any time). */
+    price_cooldown_minutes?: number;
     /**
      * 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ambasada/village",
-  "version": "0.8.10",
+  "version": "0.8.11",
   "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,15 +27,15 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@ambasada/sdk": "^0.8.10"
+    "@ambasada/sdk": "^0.8.11"
   },
   "devDependencies": {
     "@types/node": "^22.20.5",
     "esbuild": "^0.28.2",
     "typescript": "~5.9.3",
     "vitest": "^4.1.12",
-    "@ambasada/protocol": "0.1.0",
-    "@ambasada/cli": "0.8.10"
+    "@ambasada/cli": "0.8.11",
+    "@ambasada/protocol": "0.1.0"
   },
   "author": "CENTYSO (https://centyso.com)",
   "homepage": "https://ambasada.id",