@ambasada/sdk 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,795 @@
+// src/errors.ts
+var ERROR_STATUS = {
+  // EXCHANGE.md §5 vocabulary
+  INSUFFICIENT_FUNDS: 402,
+  OFFLINE: 503,
+  TIMEOUT: 504,
+  SCHEMA_INVALID: 502,
+  CAP_BUYER_HOURLY: 429,
+  CAP_SELLER_RATE: 429,
+  DEAL_EXHAUSTED: 409,
+  DEPTH_EXCEEDED: 422,
+  BUDGET_EXCEEDED: 402,
+  // Gateway and bank
+  UPSTREAM_ERROR: 502,
+  PRICE_ABOVE_MAX: 409,
+  SELF_PURCHASE: 403,
+  INVALID_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  NOT_FOUND: 404,
+  CONFLICT: 409,
+  IDEMPOTENCY_CONFLICT: 422,
+  IDEMPOTENCY_IN_PROGRESS: 409,
+  HOLD_NOT_ACTIVE: 409,
+  INTERNAL: 500,
+  // Spending limits and approvals (checkout stream)
+  CAP_PER_PAYMENT: 403,
+  CAP_BUYER_DAILY: 429,
+  CAP_PAYEE_DAILY: 429,
+  CAP_VISITOR_DAILY: 429,
+  APPROVAL_REQUIRED: 403,
+  APPROVAL_INVALID: 403,
+  APPROVALS_PENDING: 429,
+  // LLMOK mapping (utilities stream, docs/LLMOK.md)
+  PROVIDER_BUDGET: 503,
+  PROVIDER_DENIED: 502,
+  // Clock windows (agent stream): deploys / steering refused while frozen
+  FROZEN: 403,
+  // Exchange stream: an agent sent too many inbox messages
+  CAP_INBOX_RATE: 429,
+  // SDK-side
+  NETWORK: 0,
+  CONFIG: 0,
+  RECEIPT_INVALID: 402,
+  WEBHOOK_INVALID: 400
+};
+var VillageError = class extends Error {
+  code;
+  /** HTTP status (0 when the request never got an answer). */
+  status;
+  details;
+  constructor(code, message, status, details = {}) {
+    super(message);
+    this.name = "VillageError";
+    this.code = code;
+    this.status = status ?? ERROR_STATUS[code] ?? 500;
+    this.details = details;
+  }
+  get callId() {
+    return this.details.call_id;
+  }
+  get refunded() {
+    return this.details.refunded === true;
+  }
+  get approvalId() {
+    return this.details.approval_id;
+  }
+  /** The wire shape, e.g. to pass an error on from your own endpoint. */
+  toJSON() {
+    return { error: { code: this.code, message: this.message, ...this.details } };
+  }
+  /** A `Response` with the wire shape and status (402 for receipt problems). */
+  toResponse() {
+    return Response.json(this.toJSON(), { status: this.status || 500 });
+  }
+};
+var ReceiptInvalidError = class extends VillageError {
+  reason;
+  constructor(reason, message) {
+    super("RECEIPT_INVALID", `payment required: ${message}`, 402, { reason });
+    this.name = "ReceiptInvalidError";
+    this.reason = reason;
+  }
+};
+var WebhookInvalidError = class extends VillageError {
+  reason;
+  constructor(reason, message) {
+    super("WEBHOOK_INVALID", message, 400, { reason });
+    this.name = "WebhookInvalidError";
+    this.reason = reason;
+  }
+};
+function isVillageError(value, code) {
+  return value instanceof VillageError && (code === void 0 || value.code === code);
+}
+function errorFromResponse(status, body, fallback) {
+  const error = typeof body === "object" && body !== null ? body.error : void 0;
+  if (typeof error === "object" && error !== null && typeof error.code === "string") {
+    const { code: code2, message, ...details } = error;
+    return new VillageError(code2, typeof message === "string" ? message : code2, status, details);
+  }
+  const code = status === 401 ? "UNAUTHORIZED" : status === 404 ? "NOT_FOUND" : status >= 500 ? "INTERNAL" : "INVALID_REQUEST";
+  return new VillageError(code, fallback, status);
+}
+
+// ../protocol/src/encoding.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function utf8(text) {
+  return encoder.encode(text);
+}
+function fromUtf8(bytes) {
+  return decoder.decode(bytes);
+}
+function fromBase64url(text) {
+  const padded = text.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((text.length + 3) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+function toBytes(data) {
+  if (typeof data === "string") return utf8(data);
+  if (data instanceof Uint8Array) return new Uint8Array(data);
+  return new Uint8Array(data);
+}
+async function sha256Hex(data) {
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", toBytes(data)));
+  let hex = "";
+  for (const byte of digest) hex += byte.toString(16).padStart(2, "0");
+  return hex;
+}
+
+// ../protocol/src/receipt.ts
+var RECEIPT_HEADER = "x-village-receipt";
+var DEFAULT_ISSUER = "village";
+var ReceiptError = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+    this.name = "ReceiptError";
+  }
+  reason;
+};
+var ED25519 = { name: "Ed25519" };
+async function verifyReceipt(token, options) {
+  const claims = await verifySigned(token, options);
+  if (claims.kind !== void 0 || typeof claims.call_id !== "string" || typeof claims.body_sha256 !== "string") {
+    throw new ReceiptError("wrong_kind", "not a call receipt");
+  }
+  if (options.seller !== void 0 && claims.seller !== options.seller) {
+    throw new ReceiptError("wrong_seller", `receipt is for seller ${claims.seller}`);
+  }
+  if (options.offering !== void 0 && claims.offering !== options.offering) {
+    throw new ReceiptError("wrong_offering", `receipt is for offering ${claims.offering}`);
+  }
+  if (options.body !== void 0 && await sha256Hex(options.body) !== claims.body_sha256) {
+    throw new ReceiptError("body_mismatch", "request body does not match the receipt");
+  }
+  return claims;
+}
+async function verifyCheckoutReceipt(token, options) {
+  const claims = await verifySigned(token, options);
+  if (claims.kind !== "checkout" || typeof claims.session !== "string") throw new ReceiptError("wrong_kind", "not a checkout receipt");
+  if (options.seller !== void 0 && claims.seller !== options.seller) {
+    throw new ReceiptError("wrong_seller", `receipt is for seller ${claims.seller}`);
+  }
+  if (options.session !== void 0 && claims.session !== options.session) {
+    throw new ReceiptError("wrong_session", `receipt is for checkout ${claims.session}`);
+  }
+  return claims;
+}
+async function verifySigned(token, options) {
+  if (!token) throw new ReceiptError("missing", `missing ${RECEIPT_HEADER}`);
+  const parts = token.split(".");
+  if (parts.length !== 3) throw new ReceiptError("malformed", "receipt is not a JWT");
+  const [headerPart, payloadPart, signaturePart] = parts;
+  let header2;
+  let claims;
+  try {
+    header2 = JSON.parse(fromUtf8(fromBase64url(headerPart)));
+    claims = JSON.parse(fromUtf8(fromBase64url(payloadPart)));
+  } catch {
+    throw new ReceiptError("malformed", "receipt is not valid base64url JSON");
+  }
+  if (header2.alg !== "EdDSA") throw new ReceiptError("malformed", `unsupported alg ${header2.alg}`);
+  if (typeof claims !== "object" || claims === null) throw new ReceiptError("malformed", "receipt claims are not an object");
+  const keys = typeof options.keys === "function" ? await options.keys() : options.keys;
+  const jwk = keys.find((k) => (k.kid ?? k.x.slice(0, 16)) === header2.kid) ?? (keys.length === 1 && !header2.kid ? keys[0] : void 0);
+  if (!jwk) throw new ReceiptError("unknown_key", `no village key with kid ${header2.kid}`);
+  const key = await crypto.subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x }, ED25519, false, ["verify"]);
+  const ok = await crypto.subtle.verify(ED25519, key, fromBase64url(signaturePart), utf8(`${headerPart}.${payloadPart}`));
+  if (!ok) throw new ReceiptError("bad_signature", "receipt signature is invalid");
+  const now = options.now ?? Math.floor(Date.now() / 1e3);
+  const skew = options.clockSkewSeconds ?? 30;
+  if (typeof claims.exp !== "number" || claims.exp + skew < now) throw new ReceiptError("expired", "receipt expired");
+  if (typeof claims.iat === "number" && claims.iat - skew > now) throw new ReceiptError("not_yet_valid", "receipt issued in the future");
+  if (claims.iss !== (options.issuer ?? DEFAULT_ISSUER)) throw new ReceiptError("wrong_issuer", `unexpected issuer ${String(claims.iss)}`);
+  return claims;
+}
+
+// ../protocol/src/webhook.ts
+var WEBHOOK_HEADERS = {
+  id: "webhook-id",
+  timestamp: "webhook-timestamp",
+  signature: "webhook-signature"
+};
+var SECRET_PREFIX = "whsec_";
+var encoder2 = new TextEncoder();
+var WebhookError = class extends Error {
+  constructor(reason, message) {
+    super(message);
+    this.reason = reason;
+    this.name = "WebhookError";
+  }
+  reason;
+};
+function generateWebhookSecret() {
+  const bytes = new Uint8Array(24);
+  crypto.getRandomValues(bytes);
+  return SECRET_PREFIX + toStdBase64(bytes);
+}
+async function hmacKey(secret) {
+  const raw = secret.startsWith(SECRET_PREFIX) ? secret.slice(SECRET_PREFIX.length) : secret;
+  let bytes;
+  try {
+    bytes = fromStdBase64(raw);
+  } catch {
+    throw new WebhookError("bad_secret", "webhook secret is not whsec_<base64>");
+  }
+  return crypto.subtle.importKey("raw", bytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+}
+async function signWebhook(secret, id, timestamp, body) {
+  const mac = await crypto.subtle.sign("HMAC", await hmacKey(secret), encoder2.encode(`${id}.${timestamp}.${body}`));
+  return `v1,${toStdBase64(new Uint8Array(mac))}`;
+}
+async function webhookHeaders(secret, id, timestamp, body) {
+  return {
+    [WEBHOOK_HEADERS.id]: id,
+    [WEBHOOK_HEADERS.timestamp]: String(timestamp),
+    [WEBHOOK_HEADERS.signature]: await signWebhook(secret, id, timestamp, body)
+  };
+}
+function header(headers, name) {
+  if (headers instanceof Headers) return headers.get(name);
+  const value = headers[name] ?? headers[name.toLowerCase()];
+  return Array.isArray(value) ? value[0] ?? null : value ?? null;
+}
+async function verifyWebhook(secret, headers, body, { toleranceSeconds = 300, now = Math.floor(Date.now() / 1e3) } = {}) {
+  const id = header(headers, WEBHOOK_HEADERS.id);
+  const ts = header(headers, WEBHOOK_HEADERS.timestamp);
+  const signatures = header(headers, WEBHOOK_HEADERS.signature);
+  if (!id || !ts || !signatures) throw new WebhookError("missing_headers", "missing webhook-id, webhook-timestamp or webhook-signature");
+  const timestamp = Number(ts);
+  if (!/^\d+$/.test(ts) || !Number.isSafeInteger(timestamp)) throw new WebhookError("bad_timestamp", "webhook-timestamp is not unix seconds");
+  if (timestamp < now - toleranceSeconds) throw new WebhookError("too_old", "webhook timestamp is too old");
+  if (timestamp > now + toleranceSeconds) throw new WebhookError("too_new", "webhook timestamp is in the future");
+  const text = typeof body === "string" ? body : fromUtf8(body);
+  const expected = (await signWebhook(secret, id, timestamp, text)).slice(3);
+  const match = signatures.split(" ").filter((s) => s.startsWith("v1,")).some((s) => constantTimeEqual(s.slice(3), expected));
+  if (!match) throw new WebhookError("bad_signature", "no matching webhook signature");
+  return JSON.parse(text);
+}
+function constantTimeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+function toStdBase64(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+function fromStdBase64(text) {
+  const binary = atob(text);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+// src/webhook.ts
+function getHeader(headers, name) {
+  if (typeof headers.get === "function") return headers.get(name);
+  const record = headers;
+  const key = Object.keys(record).find((k) => k.toLowerCase() === name);
+  const value = key === void 0 ? void 0 : record[key];
+  return Array.isArray(value) ? value[0] ?? null : value ?? null;
+}
+function plainHeaders(headers) {
+  const out = {};
+  for (const name of ["webhook-id", "webhook-timestamp", "webhook-signature"]) {
+    const v = getHeader(headers, name);
+    if (v !== null) out[name] = v;
+  }
+  return out;
+}
+async function verifyWebhookPayload(secret, headers, body, options = {}) {
+  if (!secret) throw new WebhookInvalidError("bad_secret", "no webhook secret: set AMBASADA_WEBHOOK_SECRET or pass it");
+  const plain = plainHeaders(headers);
+  let parsed;
+  try {
+    parsed = await verifyWebhook(secret, plain, body, options);
+  } catch (error) {
+    if (error instanceof WebhookError) throw new WebhookInvalidError(error.reason, error.message);
+    if (error instanceof SyntaxError) throw new WebhookInvalidError("bad_body", "webhook body is not JSON");
+    if (error instanceof DOMException || error instanceof TypeError) throw new WebhookInvalidError("bad_secret", "webhook secret is not whsec_<base64>");
+    throw error;
+  }
+  return { id: plain["webhook-id"], type: String(parsed.type), timestamp: String(parsed.timestamp ?? ""), data: parsed.data };
+}
+
+// src/receipt.ts
+var RECEIPT_HEADER2 = "x-village-receipt";
+async function readIncoming(req) {
+  if (typeof req.clone === "function" && typeof req.arrayBuffer === "function") {
+    const r = req;
+    return { headers: r.headers, body: new Uint8Array(await r.clone().arrayBuffer()) };
+  }
+  const node = req;
+  const raw = toBytes2(node.rawBody) ?? toBytes2(node.body);
+  if (raw) return { headers: node.headers, body: raw };
+  if (node.body !== void 0 && node.body !== null && !(typeof node.body === "object" && Object.keys(node.body).length === 0)) {
+    throw new VillageError(
+      "CONFIG",
+      "the request body was already parsed as JSON; receipts commit to the raw bytes. Use express.raw({ type: '*/*' }) on paid routes (or keep req.rawBody)."
+    );
+  }
+  if (typeof node[Symbol.asyncIterator] === "function") {
+    const chunks = [];
+    for await (const chunk of node) chunks.push(toBytes2(chunk) ?? new Uint8Array());
+    const body = concat(chunks);
+    node.rawBody = body;
+    return { headers: node.headers, body };
+  }
+  return { headers: node.headers, body: new Uint8Array() };
+}
+async function verifyCallReceipt(token, body, check) {
+  let claims;
+  try {
+    claims = await verifyReceipt(token, {
+      keys: check.keys,
+      seller: check.seller,
+      offering: check.offering,
+      body,
+      issuer: check.issuer,
+      now: check.now
+    });
+  } catch (error) {
+    if (error instanceof ReceiptError) throw new ReceiptInvalidError(error.reason, error.message);
+    throw error;
+  }
+  if (claims.kind !== void 0 || typeof claims.call_id !== "string" || typeof claims.body_sha256 !== "string") {
+    throw new ReceiptInvalidError("wrong_kind", "not a call receipt");
+  }
+  return claims;
+}
+async function verifyCheckoutReceiptToken(token, check) {
+  try {
+    return await verifyCheckoutReceipt(token, check);
+  } catch (error) {
+    if (error instanceof ReceiptError) throw new ReceiptInvalidError(error.reason, error.message);
+    throw error;
+  }
+}
+var ReplayGuard = class {
+  seen = /* @__PURE__ */ new Map();
+  /** Returns false if the call id was already used. */
+  claim(callId, exp) {
+    const now = Math.floor(Date.now() / 1e3);
+    if (this.seen.size > 1e3) {
+      for (const [id, e] of this.seen) if (e < now) this.seen.delete(id);
+    }
+    if (this.seen.has(callId)) return false;
+    this.seen.set(callId, exp);
+    return true;
+  }
+};
+function receiptHeader(headers) {
+  return getHeader(headers, RECEIPT_HEADER2);
+}
+function toBytes2(value) {
+  if (value instanceof Uint8Array) return value;
+  if (value instanceof ArrayBuffer) return new Uint8Array(value);
+  if (typeof value === "string") return new TextEncoder().encode(value);
+  return null;
+}
+function concat(chunks) {
+  const out = new Uint8Array(chunks.reduce((n, c) => n + c.byteLength, 0));
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
+
+// src/client.ts
+var DEFAULT_API_URL = "https://hackaton.ambasada.id";
+var DEFAULT_MODEL = "deepseek-v4.1-flash";
+function processEnv() {
+  const p = globalThis.process;
+  return p?.env ?? {};
+}
+function randomKey() {
+  return `sdk_${crypto.randomUUID()}`;
+}
+function num(value) {
+  if (value === null || value === "") return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+function splitOffering(offering2) {
+  const [company, name, ...rest] = offering2.split("/");
+  if (!company || !name || rest.length) throw new VillageError("INVALID_REQUEST", `offering must be "company/name", got "${offering2}"`);
+  return [company, name];
+}
+var Village = class {
+  options;
+  keyLoader;
+  companyPromise;
+  replays = new ReplayGuard();
+  constructor(options = {}) {
+    this.options = options;
+  }
+  env(name) {
+    const v = this.options.env?.[name];
+    return typeof v === "string" ? v : processEnv()[name];
+  }
+  get apiUrl() {
+    return (this.options.apiUrl ?? (this.env("AMBASADA_API_URL") ?? this.env("VILLAGE_API_URL")) ?? DEFAULT_API_URL).replace(/\/+$/, "");
+  }
+  get apiKey() {
+    const key = this.options.apiKey ?? (this.env("AMBASADA_API_KEY") ?? this.env("VILLAGE_API_KEY"));
+    if (!key) throw new VillageError("CONFIG", "no API key: set AMBASADA_API_KEY (from the village app, or `ambasada login`) or pass { apiKey }");
+    return key;
+  }
+  // ── HTTP ──────────────────────────────────────────────────────────────────
+  async send(method, path, opts = {}) {
+    const url = new URL(this.apiUrl + path);
+    for (const [k, v] of Object.entries(opts.query ?? {})) if (v !== void 0) url.searchParams.set(k, String(v));
+    const headers = { accept: "application/json" };
+    if (opts.auth !== false) headers.authorization = `Bearer ${this.apiKey}`;
+    let body = opts.raw;
+    if (opts.body !== void 0) {
+      body = JSON.stringify(opts.body);
+      headers["content-type"] = "application/json";
+    }
+    for (const [k, v] of Object.entries(opts.headers ?? {})) if (v !== void 0) headers[k.toLowerCase()] = v;
+    const doFetch = this.options.fetch ?? fetch;
+    const attempt = () => {
+      const timeout = AbortSignal.timeout(this.options.timeoutMs ?? 45e3);
+      const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
+      return doFetch(url, { method, headers, body, signal });
+    };
+    let res;
+    try {
+      res = await attempt();
+    } catch (error) {
+      if (opts.signal?.aborted) throw error;
+      if (!opts.retry) throw new VillageError("NETWORK", `${method} ${url.pathname}: ${error.message}`, 0);
+      try {
+        res = await attempt();
+      } catch (again) {
+        throw new VillageError("NETWORK", `${method} ${url.pathname}: ${again.message}`, 0);
+      }
+    }
+    const text = await res.text();
+    let json = text;
+    if (text && (res.headers.get("content-type") ?? "").includes("json")) {
+      try {
+        json = JSON.parse(text);
+      } catch {
+      }
+    }
+    if (!res.ok) throw errorFromResponse(res.status, json, `${method} ${url.pathname} \u2192 ${res.status}${text ? `: ${text.slice(0, 200)}` : ""}`);
+    return { status: res.status, headers: res.headers, json };
+  }
+  async call(method, path, opts) {
+    return (await this.send(method, path, opts)).json;
+  }
+  // ── identity, keys ────────────────────────────────────────────────────────
+  /** Your company id (from options, `AMBASADA_COMPANY`, or the wallet the API key belongs to). */
+  company() {
+    const known = this.options.company ?? (this.env("AMBASADA_COMPANY") ?? this.env("VILLAGE_COMPANY"));
+    if (known) return Promise.resolve(known);
+    this.companyPromise ??= this.wallet().then(
+      (w) => w.account,
+      (error) => {
+        this.companyPromise = void 0;
+        throw error;
+      }
+    );
+    return this.companyPromise;
+  }
+  /** Village receipt keys (cached). */
+  keys() {
+    const given = this.options.keys;
+    if (Array.isArray(given)) return Promise.resolve(given);
+    if (typeof given === "function") return given();
+    this.keyLoader ??= cachedKeys(() => this.call("GET", "/.well-known/jwks.json", { auth: false }).then((r) => r.keys));
+    return this.keyLoader();
+  }
+  keySource() {
+    return () => this.keys();
+  }
+  // ── selling: receipts, webhooks ───────────────────────────────────────────
+  /**
+   * Verifies that a request to your endpoint was paid through the Gateway and returns the receipt
+   * with the parsed JSON `input`. Throws `ReceiptInvalidError` (status 402) otherwise.
+   * Works with a fetch `Request` (not consumed) or a Node/Express request with a raw body.
+   */
+  async verifyReceipt(req, options = {}) {
+    const { headers, body } = await readIncoming(req);
+    const token = receiptHeader(headers);
+    if (!token) throw new ReceiptInvalidError("missing", "missing x-village-receipt (call this endpoint through the village Gateway)");
+    const seller = await this.company();
+    const claims = await verifyCallReceipt(token, body, {
+      keys: this.keySource(),
+      seller,
+      offering: options.offering === void 0 ? void 0 : `${seller}/${options.offering}`
+    });
+    if (options.replayGuard !== false && !this.replays.claim(claims.call_id, claims.exp)) {
+      throw new ReceiptInvalidError("replayed", "receipt already used");
+    }
+    let input = {};
+    if (body.byteLength) {
+      const text = new TextDecoder().decode(body);
+      try {
+        input = JSON.parse(text);
+      } catch {
+        input = text;
+      }
+    }
+    return { ...claims, input };
+  }
+  /**
+   * 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 `VillageError` keeps its status (the
+   * Gateway then refunds the buyer).
+   *
+   *   export default village.sell("translate", async ({ text, to }) => ({ text: await village.llm(`…`) }));
+   */
+  sell(offering2, handler) {
+    return async (req) => {
+      if (req.method !== "POST") return Response.json({ error: { code: "INVALID_REQUEST", message: "POST only" } }, { status: 405 });
+      let call;
+      try {
+        call = await this.verifyReceipt(req, { offering: offering2 });
+      } catch (error) {
+        if (error instanceof VillageError) return error.toResponse();
+        throw error;
+      }
+      try {
+        const out = await handler(call.input, call, req);
+        return out instanceof Response ? out : Response.json(out);
+      } catch (error) {
+        if (error instanceof VillageError) return error.toResponse();
+        console.error(error);
+        return Response.json({ error: { code: "INTERNAL", message: "handler failed" } }, { status: 500 });
+      }
+    };
+  }
+  /** Verifies a signed webhook (`checkout.paid`, `webhook.test`) and returns the event. Throws `WebhookInvalidError`. */
+  async verifyWebhook(req, secret) {
+    const { headers, body } = await readIncoming(req);
+    return verifyWebhookPayload(secret ?? this.options.webhookSecret ?? (this.env("AMBASADA_WEBHOOK_SECRET") ?? this.env("VILLAGE_WEBHOOK_SECRET")) ?? "", headers, body);
+  }
+  /** Verifies a checkout receipt (pay.js `village:paid` → `e.detail.receipt`, or `session.receipt`). */
+  async verifyCheckoutReceipt(token, options = {}) {
+    return verifyCheckoutReceiptToken(token, { keys: this.keySource(), seller: await this.company(), session: options.session });
+  }
+  // ── checkout (humans) ─────────────────────────────────────────────────────
+  /** Creates a Checkout session; redirect the person to `session.url`. Deliver on the webhook or `getCheckout(id).status === "paid"`. */
+  checkout(session, options = {}) {
+    return this.call("POST", "/v1/checkout/sessions", { body: session, headers: { "idempotency-key": options.idempotencyKey } });
+  }
+  getCheckout(id) {
+    return this.call("GET", `/v1/checkout/sessions/${encodeURIComponent(id)}`);
+  }
+  /** 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 });
+  }
+  /** Cancels an open session (`POST /v1/checkout/sessions/:id/expire`). */
+  expireCheckout(id) {
+    return this.call("POST", `/v1/checkout/sessions/${encodeURIComponent(id)}/expire`);
+  }
+  async listPaymentLinks() {
+    return (await this.call("GET", "/v1/checkout/links")).links;
+  }
+  deactivatePaymentLink(id) {
+    return this.call("POST", `/v1/checkout/links/${encodeURIComponent(id)}/deactivate`);
+  }
+  /** Where checkout webhooks go. Returns the signing secret (the same one until `rotateSecret`). */
+  setWebhook(url, options = {}) {
+    return this.call("PUT", "/v1/webhook", { body: { url, rotate_secret: options.rotateSecret || void 0 } });
+  }
+  /** The webhook URL, its secret and the last deliveries. */
+  getWebhook() {
+    return this.call("GET", "/v1/webhook");
+  }
+  deleteWebhook() {
+    return this.call("DELETE", "/v1/webhook");
+  }
+  /** Sends a `webhook.test` event now and returns the delivery. */
+  testWebhook() {
+    return this.call("POST", "/v1/webhook/test");
+  }
+  retryWebhookDelivery(id) {
+    return this.call("POST", `/v1/webhook/deliveries/${encodeURIComponent(id)}/retry`);
+  }
+  // ── buying (machines) ─────────────────────────────────────────────────────
+  /** Buys one call of `company/offering` through the Gateway. Money moves only if the seller answers 2xx with valid output. */
+  async buy(offering2, input, options = {}) {
+    const [company, name] = splitOffering(offering2);
+    return this.paid(`/v1/pay/${encodeURIComponent(company)}/${encodeURIComponent(name)}`, input, options);
+  }
+  /**
+   * Buys whatever your agent routed the need `name` to (or the best offering within `maxPrice` if it
+   * has not routed it yet), with fallbacks (EXCHANGE.md §4.3). Prefer this over hardcoding a supplier.
+   */
+  need(name, input, options = {}) {
+    return this.paid(`/v1/need/${encodeURIComponent(name)}`, input, options);
+  }
+  async paid(path, input, options) {
+    const depth = options.parent?.depth;
+    const budget = options.budget ?? options.parent?.budget;
+    const res = await this.send("POST", path, {
+      body: input ?? {},
+      retry: true,
+      signal: options.signal,
+      headers: {
+        "idempotency-key": options.idempotencyKey ?? randomKey(),
+        "x-village-max-price": options.maxPrice === void 0 ? void 0 : String(options.maxPrice),
+        "x-village-depth": depth === void 0 ? void 0 : String(depth),
+        "x-village-budget": budget === void 0 ? void 0 : String(budget),
+        "x-village-approval": options.approval,
+        "x-village-reason": options.reason?.slice(0, 280)
+      }
+    });
+    const h = res.headers;
+    return {
+      output: res.json,
+      callId: h.get("x-village-call-id"),
+      amount: num(h.get("x-village-amount")),
+      receipt: h.get("x-village-receipt"),
+      logIndex: num(h.get("x-village-log-index")),
+      replayed: h.get("idempotent-replayed") === "true",
+      offering: h.get("x-village-offering")
+    };
+  }
+  // ── utilities (LLMOK, paid in TON from your wallet) ───────────────────────
+  /**
+   * `village.llm("prompt")` → the answer text; `village.llm.chat(req)` → the full OpenAI-style response.
+   * Default model: deepseek-v4.1-flash.
+   */
+  llm = Object.assign(
+    async (prompt, options = {}) => {
+      const { system, ...rest } = options;
+      const messages = system ? [{ role: "system", content: system }] : [];
+      const res = await this.llm.chat({ ...rest, messages: [...messages, { role: "user", content: prompt }] });
+      return res.choices[0]?.message.content ?? "";
+    },
+    {
+      chat: (req) => this.call("POST", "/v1/llm/chat", { body: { ...req, model: req.model ?? DEFAULT_MODEL } })
+    }
+  );
+  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" } })
+  };
+  tools = {
+    /** The curated LLMOK tool catalog with TON prices. */
+    list: async () => {
+      const res = await this.call("GET", "/v1/tools");
+      return Array.isArray(res) ? res : res.tools;
+    },
+    /** Runs one tool; debits your wallet only on success. Replays with the same idempotency key are free. */
+    call: async (id, input, options = {}) => {
+      const res = await this.send("POST", `/v1/tools/${encodeURIComponent(id)}`, {
+        body: input ?? {},
+        retry: true,
+        headers: { "idempotency-key": options.idempotencyKey ?? randomKey() }
+      });
+      const json = res.json;
+      return {
+        output: json.output,
+        callId: json.call_id ?? res.headers.get("x-village-call-id"),
+        amount: json.cost ?? num(res.headers.get("x-village-amount")),
+        replayed: res.headers.get("idempotent-replayed") === "true"
+      };
+    }
+  };
+  files = {
+    /**
+     * Stores bytes, a Blob, or a URL to copy, for the event. Returns a public URL other products can fetch.
+     * (`POST /v1/files`: assumed route; the utilities stream serves `GET /files/:id`.)
+     */
+    put: (data, options = {}) => {
+      const query = { ttl_seconds: options.ttlSeconds };
+      if (typeof data === "string") return this.call("POST", "/v1/files", { body: { url: data, content_type: options.contentType }, query });
+      const contentType = options.contentType ?? (data instanceof Blob && data.type ? data.type : "application/octet-stream");
+      return this.call("POST", "/v1/files", { raw: data, headers: { "content-type": contentType }, query });
+    }
+  };
+  // ── listings, wallet, ledger ──────────────────────────────────────────────
+  listings = {
+    /** Creates or updates an offering (price changes are versioned). */
+    put: (name, def) => this.call("PUT", `/v1/offerings/${encodeURIComponent(name)}`, { body: def }),
+    list: async () => (await this.call("GET", "/v1/offerings")).offerings
+  };
+  wallet() {
+    return this.call("GET", "/v1/wallet");
+  }
+  ledger(since = 0, limit = 100) {
+    return this.call("GET", "/v1/ledger", { query: { since, limit } });
+  }
+  transfer(to, amount, options = {}) {
+    return this.call("POST", "/v1/transfer", {
+      body: { to, amount, reason: options.reason, ref: options.ref },
+      retry: true,
+      headers: { "idempotency-key": options.idempotencyKey ?? randomKey() }
+    });
+  }
+  // ── market, agent (CLI, scripts) ──────────────────────────────────────────
+  market = {
+    search: async (query) => {
+      const res = await this.call("GET", "/v1/market/search", { query: { q: query } });
+      return res.offerings ?? res.results ?? [];
+    }
+  };
+  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. */
+    steer: (text) => this.call("POST", "/v1/agent/steer", { body: { text } }),
+    transcript: (since = 0, limit = 200) => this.call("GET", "/v1/agent/transcript", { query: { since, limit } }),
+    state: () => this.call("GET", "/v1/agent/state")
+  };
+};
+function cachedKeys(load, ttlMs = 10 * 6e4) {
+  let cached;
+  return () => {
+    if (!cached || Date.now() - cached.at > ttlMs) {
+      const keys = load();
+      const entry = { at: Date.now(), keys };
+      cached = entry;
+      keys.catch(() => {
+        if (cached === entry) cached = void 0;
+      });
+    }
+    return cached.keys;
+  };
+}
+function createAmbasada(options = {}) {
+  return new Village(options);
+}
+
+// src/define.ts
+function defineCompany(config) {
+  return config;
+}
+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`);
+  return def;
+}
+
+// src/index.ts
+var village = new Village();
+var index_default = village;
+export {
+  DEFAULT_API_URL,
+  DEFAULT_MODEL,
+  ERROR_STATUS,
+  RECEIPT_HEADER2 as RECEIPT_HEADER,
+  ReceiptInvalidError,
+  Village,
+  VillageError,
+  WEBHOOK_HEADERS,
+  WebhookInvalidError,
+  createAmbasada,
+  index_default as default,
+  defineCompany,
+  errorFromResponse,
+  generateWebhookSecret,
+  isVillageError,
+  offering,
+  readIncoming,
+  verifyCallReceipt,
+  verifyCheckoutReceiptToken,
+  verifyWebhookPayload,
+  village,
+  webhookHeaders
+};