@ambasada/skills 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CENTYSO (https://centyso.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# @ambasada/skills
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Skills for AI coding tools (Claude Code, Cursor, Codex) building products for the Hack A Ton Village.
+
+| Skill | Use it to |
+|---|---|
+| [`ambasada-product`](skills/ambasada-product/SKILL.md) | build a product that sells in the Village: the Next.js-on-Cloudflare layout, allowed features, data and secrets, `ambasada dev` / `deploy` / `link`, design, a sellable checklist, prompts for ChatGPT and Lovable |
+| [`ambasada-payments`](skills/ambasada-payments/SKILL.md) | take and spend TON: Checkout, pay.js, webhooks, receipts, `buy` / `need`, LLM, images, tools, files; recipes for Next.js, static pages, Lovable/Bolt and self-hosted stacks |
+
+Each skill is a folder with `SKILL.md` (frontmatter `name`, `description`) plus `reference/`, `recipes/` or
+`checklists/`.
+
+Install:
+
+- New project: `npm create ambasada@latest my-shop` vendors both into `.claude/skills/`.
+- Existing project: `npx skills add centyso-dev/ambasada-skills` (public mirror), or copy `skills/*` into
+  `.claude/skills/`. Cursor and Codex: point the agent at the `SKILL.md` files.
+
+After editing, run `pnpm --filter @ambasada/skills sync`: it copies every skill into each
+`templates/*/.claude/skills/` (and the legacy `template/.claude/skills/` while it exists).
+`pnpm test` (`node scripts/sync.mjs --check`) fails on bad frontmatter, a broken relative link, or a stale copy.
+
+Built by [CENTYSO](https://centyso.com) for [Ambasada](https://ambasada.id). MIT.

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@ambasada/skills",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Skills for Claude Code, Cursor and Codex: ambasada-product (build a product that sells in the Hack A Ton Village) and ambasada-payments (TON Checkout, receipts, webhooks).",
+  "type": "module",
+  "files": [
+    "skills",
+    "LICENSE",
+    "README.md"
+  ],
+  "license": "MIT",
+  "author": "CENTYSO (https://centyso.com)",
+  "homepage": "https://ambasada.id",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ambasada/cli.git",
+    "directory": "packages/skills"
+  },
+  "bugs": {
+    "url": "https://github.com/ambasada/cli/issues"
+  },
+  "keywords": [
+    "ambasada",
+    "hack-a-ton",
+    "ton",
+    "payments",
+    "cloudflare",
+    "agents"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "sync": "node scripts/sync.mjs",
+    "test": "node scripts/sync.mjs --check"
+  }
 }

package/skills/ambasada-payments/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: ambasada-payments
+description: Add TON payments to any app for the Hack A Ton village. Use when the user wants to accept TON from people (Checkout, pay.js button, webhooks), sell an HTTP endpoint that agents pay per call (verify the x-village-receipt), buy from other companies (village.buy / village.need), use the village LLM, images, tools or files, list offerings, or test all of it offline with `ambasada dev`. Covers Next.js on Cloudflare (the default template), static pages with pay.js, Lovable/Bolt, and self-hosted stacks (Express, FastAPI, Workers, Astro).
+---
+
+# Village payments
+
+The Hack A Ton village has its own currency, **TON** (not the TON blockchain: a play currency held by
+the village bank). Every product in the village gets paid in TON two ways:
+
+| Who pays | Primitive | You write |
+|---|---|---|
+| **People** (visitors, builders) | **Checkout**: redirect to the village approve page, or a pay.js button | create a session on your server; deliver on the signed webhook |
+| **Agents and other products** | **Pay**: the Gateway calls your endpoint with a signed receipt | an HTTP POST endpoint that verifies `x-village-receipt` |
+
+API base: `https://hackaton.ambasada.id` (`AMBASADA_API_URL`). Auth: `Authorization: Bearer <server key>`
+(`AMBASADA_API_KEY`, from the village app → your team → Developers). **Never put the key in browser code.**
+Amounts are TON as decimal numbers. Errors are always `{ "error": { "code", "message", ... } }`.
+
+## Decide what the user needs
+
+1. *"Let people pay on my site"* → [reference/checkout.md](reference/checkout.md). Static page without a backend → [recipes/static-payjs.md](recipes/static-payjs.md).
+2. *"Let agents buy my service"* → [reference/receipts.md](reference/receipts.md), then list it as an offering ([reference/primitives.md](reference/primitives.md#listings)).
+3. *"My product needs something another team sells"* → [reference/need-vs-buy.md](reference/need-vs-buy.md).
+4. *"Use an LLM / generate images / search the web"* → [reference/primitives.md](reference/primitives.md#utilities) (paid in TON from the company wallet).
+5. Always set up **test mode** first → [reference/test-mode.md](reference/test-mode.md) (`ambasada dev`, no login, fake money).
+
+Stack recipes:
+
+- [Next.js on Cloudflare](recipes/nextjs.md): the default (`npm create ambasada@latest`), hosted by `ambasada deploy`.
+- [Static page + pay.js](recipes/static-payjs.md): no backend, a payment link and a button.
+- [Lovable / Bolt / v0](recipes/lovable-bolt.md): prompts to paste into the builder.
+- [Other stacks](recipes/other-stacks.md): Express, FastAPI, a bare Worker, Astro; power users who host
+  it themselves, then `ambasada link`.
+
+Building the whole product (layout, allowed Next.js features, data, deploy, design)? Use the
+**ambasada-product** skill as well.
+
+## Rules that prevent real bugs
+
+- **Verify on the server.** A paid endpoint must verify the receipt before doing paid work; a checkout
+  must be confirmed by the webhook or `GET /v1/checkout/sessions/:id` (`status: "paid"`), never by the
+  `?session=` in the redirect URL alone. Anything unlocked purely in the browser can be unlocked by anyone.
+- **Raw body.** Receipts and webhooks are signed over the exact bytes. Read the raw body before any JSON
+  parser (Express: `express.raw({ type: "*/*" })` on those routes).
+- **Answer 2xx only when you delivered.** Any non-2xx (or output not matching the declared `output`
+  schema) makes the Gateway refund the buyer. Throwing is the refund path.
+- **Idempotency.** Send `Idempotency-Key` on purchases and transfers; retries with the same key never charge twice.
+- **One receipt, one call.** Dedupe on `call_id` (the SDK does it per process; persist it if you run several instances).
+- TypeScript: use `@ambasada/sdk` (`npm i @ambasada/sdk`). Other languages: plain HTTP ([recipes/other-stacks.md](recipes/other-stacks.md#fastapi-or-any-language-over-plain-http)).
+
+## The SDK in 20 lines
+
+The examples call the client `village`. `import { village } from "@ambasada/sdk"` reads `process.env`
+(`AMBASADA_API_KEY`, `AMBASADA_API_URL`, `AMBASADA_COMPANY`, `AMBASADA_WEBHOOK_SECRET`); on Cloudflare make
+one with `createAmbasada({ env })`. In the Next template it is `ambasada()` from `lib/ambasada.ts`.
+The SDK still reads the old `VILLAGE_*` names as a fallback.
+
+```ts
+import { village } from "@ambasada/sdk";
+
+// sell to agents: a fetch handler that verifies the receipt and answers JSON (402 if unpaid)
+export const POST = village.sell("translate", async ({ text, to }, call) => {
+  return { text: await village.llm(`Translate to ${to}. Reply with the translation only.\n\n${text}`) };
+});
+
+// sell to people
+const session = await village.checkout({ amount: 3, description: "Coffee for the team", success_url: "https://my.app/thanks" });
+// → redirect to session.url; then in the webhook handler:
+const event = await village.verifyWebhook(req); // checkout.paid
+
+// buy
+const { output } = await village.need("image.square", { prompt: "a lighthouse" }, { maxPrice: 3 });
+```

package/skills/ambasada-payments/recipes/lovable-bolt.md

@@ -0,0 +1,37 @@
+# Lovable, Bolt, v0 and other no-code builders
+
+These tools build from a prompt, so give them the docs instead of code. Two options: keep hosting there
+(below), or export the code into the `spa` template and use `ambasada deploy` (the ambasada-product skill,
+`reference/build-elsewhere.md`). Either way, finish with `ambasada link https://your.app` or `ambasada deploy`.
+
+**1. Static "Pay with TON" button (works everywhere, no backend):** create a payment link with
+`ambasada links create --amount 3 --description "…" --success-url https://your.app/thanks`, then paste this
+into the builder's chat:
+
+> Add a "Pay 3 TON" button. Include `<script src="https://hackaton.ambasada.id/pay.js" defer></script>` in the
+> page head and render `<button data-village-pay="pl_XXXX">Pay 3 TON</button>` (add `data-mode="popup"` to
+> stay on the page). Listen for the `village:paid` DOM event on `document`; `event.detail` has `session` and
+> `receipt`. When it fires, show a thank-you message; on `village:cancelled` do nothing. The page that the
+> payment returns to must also load pay.js. Do not add any other payment provider.
+
+**2. Paid features that matter (credits, downloads, a paid API) need a server.** Lovable/Bolt apps usually have
+Supabase Edge Functions or similar; paste this:
+
+> Create an edge function `village-webhook` that verifies Standard Webhooks signatures (library
+> `standardwebhooks`, secret from env `AMBASADA_WEBHOOK_SECRET`) over the raw request body, and when
+> `type == "checkout.paid"` marks the order `data.session.client_reference_id` as paid (dedupe on the
+> `webhook-id` header). Create an edge function `buy` that POSTs to
+> `https://hackaton.ambasada.id/v1/checkout/sessions` with header `Authorization: Bearer ${AMBASADA_API_KEY}`
+> and JSON `{ amount, description, success_url, client_reference_id }`, then returns the `url` from the
+> response for the browser to redirect to. Never expose AMBASADA_API_KEY to the browser.
+
+Then register the webhook URL: `ambasada webhook set https://…/functions/v1/village-webhook`.
+
+**3. Selling to agents** needs an endpoint that verifies `x-village-receipt` ([reference/receipts.md](../reference/receipts.md)). In an
+edge function with npm support: `import { village } from "npm:@ambasada/sdk"` and
+`Deno.serve(village.sell("translate", async (input) => ({ … })))`.
+
+**4. MCP:** the village MCP server (`https://hackaton.ambasada.id/mcp`) works as a Lovable custom chat
+connector while building; a published app calls the HTTP API with its key or uses pay.js.
+
+If the builder supports custom knowledge files, upload this skill's `SKILL.md` and `reference/*.md`.

package/skills/ambasada-payments/recipes/nextjs.md

@@ -0,0 +1,150 @@
+# Next.js on Cloudflare (the default template)
+
+`npm create ambasada@latest my-shop` gives you all of this already: Next.js 16.4 App Router, built into one
+Cloudflare Worker by `@opennextjs/cloudflare` 1.20 with `nodejs_compat`. Local secrets in `.env`
+(`AMBASADA_API_KEY`, `AMBASADA_API_URL`, `AMBASADA_COMPANY`, `AMBASADA_WEBHOOK_SECRET`); `.dev.vars` works too. What runs on
+Workers and what doesn't: the ambasada-product skill, `reference/stack.md`.
+
+## The client: `lib/ambasada.ts`
+
+Server code only. One client per Worker instance: it caches the receipt keys and remembers used receipts.
+
+```ts
+// lib/ambasada.ts (the template ships it; this is the core)
+import { createAmbasada, type Village } from "@ambasada/sdk";
+import { getCloudflareContext } from "@opennextjs/cloudflare";
+
+function cloudflareEnv(): Record<string, unknown> | undefined {
+  try {
+    return getCloudflareContext().env as unknown as Record<string, unknown>;
+  } catch {
+    return undefined; // `next dev`: the SDK reads process.env
+  }
+}
+
+let client: Village | undefined;
+
+export function ambasada(): Village {
+  return (client ??= createAmbasada({ env: cloudflareEnv() }));
+}
+```
+
+It also exports `env(name)` (a variable from the Worker env, else `process.env`) and `villageUrl()`
+(the Village, or the mock under `ambasada dev`).
+
+## An offering agents pay for
+
+```ts
+// app/api/translate/route.ts   (offering endpoint "/api/translate")
+import { ambasada } from "../../../lib/ambasada.ts";
+
+export const POST = (req: Request) =>
+  ambasada().sell<{ text: string; to: string }>("translate", async ({ text, to }) => ({
+    text: await ambasada().llm(`Translate to ${to}. Reply with the translation only.\n\n${text}`),
+  }))(req);
+```
+
+`sell` answers `402` without a valid receipt, runs your handler, returns its JSON. Throw a `VillageError`
+(or let it fail) and the buyer is refunded.
+
+## People pay: Checkout
+
+```ts
+// app/api/checkout/route.ts   (the landing page: <form action="/api/checkout" method="post">)
+import { ambasada } from "../../../lib/ambasada.ts";
+
+export async function POST(req: Request) {
+  const origin = new URL(req.url).origin;
+  const id = crypto.randomUUID();
+  const a = ambasada();
+  await a.store.set(`order:${id}`, { paid: false });
+  const session = await a.checkout(
+    {
+      amount: 2,
+      description: "Your name as a folk poem",            // public in the ledger: no personal data
+      success_url: `${origin}/thanks?session={CHECKOUT_SESSION_ID}`,
+      cancel_url: `${origin}/`,
+      client_reference_id: id,
+    },
+    { idempotencyKey: id },
+  );
+  return Response.redirect(session.url, 303);
+}
+```
+
+Or as a server action:
+
+```ts
+"use server";
+import { redirect } from "next/navigation";
+import { ambasada } from "../../../lib/ambasada.ts";
+
+export async function buy() {
+  const session = await ambasada().checkout({ amount: 2, description: "Your name as a folk poem", success_url: "…" });
+  redirect(session.url);
+}
+```
+
+## Deliver: the webhook
+
+```ts
+// app/api/webhook/route.ts   (`ambasada webhook set https://<slug>.hackaton.ambasada.id/api/webhook`)
+import { ambasada } from "../../../lib/ambasada.ts";
+
+export async function POST(req: Request) {
+  const a = ambasada();
+  let event;
+  try {
+    event = await a.verifyWebhook(req);                    // reads the raw body itself
+  } catch {
+    return new Response("bad signature", { status: 400 });
+  }
+  if (event.type === "checkout.paid") {
+    const key = `order:${event.data.session.client_reference_id}`;
+    const order = (await a.store.get(key)) as { paid: boolean } | null;
+    if (order && !order.paid) await a.store.set(key, { ...order, paid: true });   // retries reuse event.id
+  }
+  return new Response("ok");                               // 2xx within 10 s, or it is retried
+}
+```
+
+## The thanks page: check on the server
+
+```tsx
+// app/thanks/page.tsx
+import { ambasada } from "../../lib/ambasada.ts";
+
+export default async function Thanks({ searchParams }: { searchParams: Promise<{ session?: string }> }) {
+  const { session } = await searchParams;
+  const s = session ? await ambasada().getCheckout(session) : null;
+  if (s?.status !== "paid") return <h1>Payment pending… refresh in a moment.</h1>;
+  return <h1>Thank you! Paid {s.amount} TON.</h1>;
+}
+```
+
+## pay.js receipts from the browser
+
+```ts
+// app/api/receipt/route.ts   (POST { receipt } from a `village:paid` event)
+import { ambasada } from "../../../lib/ambasada.ts";
+import { isVillageError } from "@ambasada/sdk";
+
+export async function POST(req: Request) {
+  try {
+    const { receipt } = (await req.json()) as { receipt?: string };
+    const claims = await ambasada().verifyCheckoutReceipt(receipt);
+    return Response.json({ ok: true, amount: claims.amount, session: claims.session });
+  } catch (error) {
+    if (isVillageError(error)) return error.toResponse();
+    return Response.json({ error: { code: "INVALID_REQUEST", message: "body must be { receipt }" } }, { status: 400 });
+  }
+}
+```
+
+The button side is in [static-payjs.md](static-payjs.md). In Next, the template's `app/page.tsx` loads it
+with `<Script src={`${villageUrl()}/pay.js`} />` (`next/script`), so the same page works against the mock.
+
+## Not on Cloudflare
+
+Next on Vercel or a Node server works with the same route handlers: replace `ambasada()` with the
+default client, `import { village } from "@ambasada/sdk"`, which reads `process.env`. Then `ambasada link <url>`.

package/skills/ambasada-payments/recipes/other-stacks.md

@@ -0,0 +1,159 @@
+# Other stacks: host it yourself, then `ambasada link`
+
+For power users who already have a server. The Village does not host these: run them anywhere with a
+public HTTPS URL, then `ambasada link https://your.server` (it rewrites `product.url` in
+`ambasada.config.ts` and lists your offerings there). Agents and people pay the same way; only the code differs.
+
+Every stack needs the same four things: a paid endpoint that verifies `x-village-receipt` on the **raw
+body**, a Checkout route, a webhook route that verifies the signature on the **raw body**, and the env
+`AMBASADA_API_KEY`, `AMBASADA_COMPANY`, `AMBASADA_WEBHOOK_SECRET` (plus
+`AMBASADA_API_URL=http://127.0.0.1:8788` against `ambasada dev --mock-only`).
+
+## Express (Node)
+
+`npm i @ambasada/sdk express`. The default `village` client reads `process.env`.
+
+```ts
+import express from "express";
+import { isVillageError, village } from "@ambasada/sdk";
+
+const app = express();
+const raw = express.raw({ type: "*/*", limit: "1mb" }); // receipts and webhooks are signed over the raw bytes
+
+// An offering agents pay for.
+app.post("/api/translate", raw, async (req, res) => {
+  try {
+    const { input, buyer, amount } = await village.verifyReceipt(req, { offering: "translate" });
+    const text = await village.llm(`Translate to ${input.to}. Reply with the translation only.\n\n${input.text}`);
+    res.json({ text }); // 2xx = you get paid; any error status = buyer refunded
+  } catch (e) {
+    if (isVillageError(e)) return res.status(e.status || 500).json(e.toJSON()); // 402 when unpaid
+    throw e;
+  }
+});
+
+// People pay.
+app.post("/buy", express.json(), async (req, res) => {
+  const session = await village.checkout({
+    amount: 3,
+    description: "Coffee for the team",
+    success_url: "https://my.app/thanks?session={CHECKOUT_SESSION_ID}",
+  });
+  res.redirect(303, session.url);
+});
+
+app.post("/village-webhook", raw, async (req, res) => {
+  try {
+    const event = await village.verifyWebhook(req);
+    if (event.type === "checkout.paid") await fulfil(event.data.session, event.id);
+    res.sendStatus(200);
+  } catch {
+    res.sendStatus(400);
+  }
+});
+
+app.listen(3000);
+```
+
+Don't put `app.use(express.json())` in front of the paid routes: once the body is parsed the bytes are gone
+and `verifyReceipt` refuses with a `CONFIG` error. Full example: `examples/express-seller` in the village repo.
+
+## Cloudflare Worker without a framework
+
+The `worker` template (`npm create ambasada@latest my-shop -- --template worker`) is this, with Village
+hosting by `ambasada deploy`. By hand, in your own account (`wrangler secret put AMBASADA_API_KEY`, …):
+
+```ts
+import { createAmbasada, type Village } from "@ambasada/sdk";
+
+let village: Village | undefined; // one per isolate: it caches receipt keys and remembers used receipts
+
+export default {
+  async fetch(req: Request, env: Record<string, string>): Promise<Response> {
+    village ??= createAmbasada({ env }); // AMBASADA_API_KEY, AMBASADA_API_URL, AMBASADA_COMPANY, AMBASADA_WEBHOOK_SECRET
+    const { pathname } = new URL(req.url);
+    if (pathname === "/api/translate") {
+      return village.sell("translate", async ({ text, to }) => ({ text: await village.llm(`Translate to ${to}: ${text}`) }))(req);
+    }
+    if (pathname === "/village-webhook") {
+      const event = await village.verifyWebhook(req);
+      if (event.type === "checkout.paid") { /* fulfil event.data.session */ }
+      return new Response("ok");
+    }
+    return new Response("not found", { status: 404 });
+  },
+};
+```
+
+Workers have no `process.env` by default, hence `createAmbasada({ env })`. Bun, Deno, Hono, Astro endpoints
+(`output: "server"`) and SvelteKit use the same fetch-style handlers: `village.sell(name, handler)` is a
+`(req: Request) => Promise<Response>`.
+
+## FastAPI (or any language over plain HTTP)
+
+`pip install fastapi uvicorn httpx pyjwt[crypto] standardwebhooks`
+
+```python
+import hashlib, json, os, httpx, jwt
+from fastapi import FastAPI, Request, HTTPException
+from standardwebhooks.webhooks import Webhook
+
+API = os.environ.get("AMBASADA_API_URL", "https://hackaton.ambasada.id")
+KEY = os.environ["AMBASADA_API_KEY"]
+COMPANY = os.environ["AMBASADA_COMPANY"]          # your company id
+HEADERS = {"Authorization": f"Bearer {KEY}"}
+app = FastAPI()
+_keys = {k["kid"]: jwt.PyJWK(k) for k in httpx.get(f"{API}/.well-known/jwks.json").json()["keys"]}
+_seen: set[str] = set()
+
+def verify_receipt(token: str | None, body: bytes, offering: str) -> dict:
+    if not token:
+        raise HTTPException(402, "payment required")
+    key = _keys.get(jwt.get_unverified_header(token).get("kid"))
+    if not key:
+        raise HTTPException(402, "unknown village key")
+    try:
+        c = jwt.decode(token, key, algorithms=["EdDSA"], issuer="village")  # checks signature + exp
+    except jwt.PyJWTError as e:
+        raise HTTPException(402, f"bad receipt: {e}")
+    if c.get("kind") or c["seller"] != COMPANY or c["offering"] != f"{COMPANY}/{offering}":
+        raise HTTPException(402, "receipt is for another offering")
+    if hashlib.sha256(body).hexdigest() != c["body_sha256"] or c["call_id"] in _seen:
+        raise HTTPException(402, "receipt does not match this request")
+    _seen.add(c["call_id"])
+    return c
+
+def llm(prompt: str) -> str:
+    r = httpx.post(f"{API}/v1/llm/chat", headers=HEADERS, timeout=60,
+                   json={"model": "deepseek-v4.1-flash", "messages": [{"role": "user", "content": prompt}]})
+    r.raise_for_status()
+    return r.json()["choices"][0]["message"]["content"]
+
+@app.post("/api/translate")                       # offering endpoint agents pay for
+async def translate(request: Request):
+    body = await request.body()                   # raw bytes first
+    verify_receipt(request.headers.get("x-village-receipt"), body, "translate")
+    data = json.loads(body)
+    return {"text": llm(f"Translate to {data['to']}. Reply with the translation only.\n\n{data['text']}")}
+
+@app.post("/buy")                                 # people pay
+def buy():
+    s = httpx.post(f"{API}/v1/checkout/sessions", headers=HEADERS, json={
+        "amount": 3, "description": "Coffee for the team",
+        "success_url": "https://my.app/thanks?session={CHECKOUT_SESSION_ID}"}).json()
+    return {"url": s["url"]}
+
+@app.post("/village-webhook")
+async def webhook(request: Request):
+    body = await request.body()
+    try:
+        event = Webhook(os.environ["AMBASADA_WEBHOOK_SECRET"]).verify(body, dict(request.headers))
+    except Exception:
+        raise HTTPException(400, "bad signature")
+    if event["type"] == "checkout.paid":
+        fulfil(event["data"]["session"], request.headers["webhook-id"])
+    return "ok"
+```
+
+Buy from another company: `httpx.post(f"{API}/v1/pay/inkwell/poem", headers={**HEADERS, "Idempotency-Key": str(uuid4()), "x-village-max-price": "2"}, json=input)`.
+Errors come back as `{"error": {"code": …}}` with the HTTP status. Go, PHP, Ruby: same calls.

package/skills/ambasada-payments/recipes/static-payjs.md

@@ -0,0 +1,58 @@
+# A static page: pay.js (no backend)
+
+For plain HTML, Astro, a page built in Lovable, Bolt or v0, Carrd, anything that can include a script.
+pay.js is served by the village (`https://hackaton.ambasada.id/pay.js`; `ambasada dev` serves the same script at
+`http://127.0.0.1:8788/pay.js`, and it talks to whichever origin it was loaded from). It turns a button into
+"Pay with TON" using a **payment link**, so the page never needs your key.
+
+1. Create a link once, from your terminal:
+
+```sh
+ambasada links create --amount 3 --description "A coffee for the team" --success-url https://my.site/thanks
+# → pl_… (or POST /v1/checkout/links with curl)
+```
+
+2. On the page (plain HTML, `index.html`, or `src/pages/index.astro`):
+
+```html
+<script src="https://hackaton.ambasada.id/pay.js" defer></script>
+
+<button data-village-pay="pl_…" data-ref="table-4">Pay 3 TON</button>
+<!-- data-mode="popup" keeps the person on the page (desktop); redirect works best on phones -->
+
+<script>
+  // Fired on the button (bubbles) in popup mode, and on document when the person comes back from a redirect.
+  document.addEventListener("village:paid", (e) => {
+    // e.detail.session = "cs_…", e.detail.receipt = signed checkout receipt (JWT)
+    document.querySelector("#thanks").hidden = false;
+  });
+  document.addEventListener("village:cancelled", (e) => console.log("not paid:", e.detail.reason)); // "cancelled" | "closed"
+</script>
+<p id="thanks" hidden>Mulțumim!</p>
+```
+
+How it flows: the button goes to `https://hackaton.ambasada.id/pay/pl_…` (`?ref=` from `data-ref`). After approving,
+the person returns to the link's `success_url` with `?session=cs_…`; pay.js on that page reads
+`GET /v1/web/checkout/cs_…` (public) and fires `village:paid`. In popup mode the approve page posts the result
+to your page's origin and closes. Each click is a new payment; a double tap is not.
+
+From code: `const { session, receipt } = await Village.pay("pl_…", { ref: "order-42", mode: "popup" })` (rejects
+with `cancelled` or `closed`), and `await Village.session("cs_…")` → `{ status, amount, description, receipt, … }`.
+`ambasada links create` makes a link; `POST /v1/checkout/links/<id>/deactivate` turns one off.
+
+**Anything unlocked purely in the browser can be unlocked by anyone who reads your JavaScript.** If the
+purchase matters (a download, credits), send `e.detail.receipt` to a server or edge function and verify it:
+
+```ts
+// any fetch-style server route: the templates' /api/receipt, an Astro endpoint, a Worker
+import { village } from "@ambasada/sdk"; // reads process.env; on a Worker: createAmbasada({ env })
+export async function POST(request: Request) {
+  const { receipt } = await request.json();
+  const claims = await village.verifyCheckoutReceipt(receipt); // throws if forged / for another company
+  return Response.json({ ok: true, amount: claims.amount });
+}
+```
+
+Or set up the `checkout.paid` webhook ([reference/checkout.md](../reference/checkout.md)).
+
+Then tell the village where the page lives: `ambasada link https://your.page`.

package/skills/ambasada-payments/reference/checkout.md

@@ -0,0 +1,75 @@
+# Checkout: people pay with a redirect, you deliver on the webhook
+
+Same shape as Stripe Checkout.
+
+1. **Your server** creates a session (never the browser: it needs your key).
+2. Redirect the person to `session.url`. They approve with their Ambasada ID wallet on hackaton.ambasada.id.
+3. They come back to `success_url` with `?session=cs_…` (or wherever you put `{CHECKOUT_SESSION_ID}`).
+4. The village POSTs a signed `checkout.paid` webhook to your webhook URL. **Deliver there**, or after
+   `GET /v1/checkout/sessions/:id` says `"status": "paid"`. Never on the redirect alone.
+
+```ts
+import { village } from "@ambasada/sdk";
+
+// 1–2: POST /buy
+export async function buy(req: Request) {
+  const order = await db.orders.create({ item: "post-kit" });
+  const session = await village.checkout(
+    {
+      amount: 12,                                   // or { offering: "post_kit" } to charge an offering's price
+      description: "Launch post kit: 3 posts + images", // shown to the person AND public in the ledger: no personal data
+      success_url: "https://my.app/thanks?session={CHECKOUT_SESSION_ID}",
+      cancel_url: "https://my.app/cart",
+      client_reference_id: order.id,                // comes back to you, never shown
+    },
+    { idempotencyKey: order.id },                   // a double click returns the same session
+  );
+  return Response.redirect(session.url, 303);
+}
+
+// 4: POST /village-webhook  (register once: `ambasada webhook set https://my.app/village-webhook`)
+export async function webhook(req: Request) {
+  const event = await village.verifyWebhook(req); // AMBASADA_WEBHOOK_SECRET; throws if forged or older than 5 min
+  if (event.type === "checkout.paid") {
+    const s = event.data.session;                  // same shape as GET /v1/checkout/sessions/:id
+    await db.orders.markPaidOnce(s.client_reference_id, event.id); // dedupe on event.id: retries reuse it
+  }
+  return new Response("ok");                       // 2xx within 10 s, or it is retried (1 min … 6 h)
+}
+
+// 3: GET /thanks
+export async function thanks(req: Request) {
+  const s = await village.getCheckout(new URL(req.url).searchParams.get("session")!);
+  return s.status === "paid" ? deliver(s.client_reference_id) : pending();
+}
+```
+
+## Webhook signature (any language)
+
+[Standard Webhooks](https://www.standardwebhooks.com): headers `webhook-id`, `webhook-timestamp`,
+`webhook-signature: v1,<base64>`, where the signature is HMAC-SHA256 with the bytes of the secret after
+`whsec_` (base64-decoded) over `"<webhook-id>.<webhook-timestamp>.<raw body>"`. Off-the-shelf
+libraries verify it: `npm i standardwebhooks`, `pip install standardwebhooks`, Go, PHP, Ruby.
+Reject timestamps more than 5 minutes off.
+
+## Managing it
+
+| | HTTP | SDK |
+|---|---|---|
+| cancel an open session | `POST /v1/checkout/sessions/:id/expire` | `village.expireCheckout(id)` |
+| payment links | `POST /v1/checkout/links`, `GET /v1/checkout/links`, `POST /v1/checkout/links/:id/deactivate` | `createPaymentLink`, `listPaymentLinks`, `deactivatePaymentLink` |
+| webhook URL + secret | `PUT /v1/webhook { url, rotate_secret? }` → `{ url, secret }`, `GET /v1/webhook` (+ last deliveries), `DELETE /v1/webhook` | `setWebhook`, `getWebhook`, `deleteWebhook` |
+| send a test event | `POST /v1/webhook/test` (event `webhook.test`) | `village.testWebhook()` |
+| resend a delivery | `POST /v1/webhook/deliveries/:id/retry` (same `webhook-id`) | `village.retryWebhookDelivery(id)` |
+
+Events: `{ "type": "checkout.paid", "timestamp": ISO, "data": { "session": <the session> } }` and
+`{ "type": "webhook.test", "data": { "company", "message" } }`.
+
+## Rules
+
+- `amount` 0.1–500 TON. A person can spend at most 30 TON a day at one team.
+- `metadata`: at most 20 string values. `expires_in`: 300–86400 seconds.
+- No automatic refunds: refund with `village.transfer("p_…", amount, { reason })` (the buyer id is `session.buyer`).
+- Sessions expire after `expires_in` seconds (default 3600).
+- Full API guide: `docs/PAYMENTS.md` in the village repo. Without the SDK, `@ambasada/protocol` exports the same
+  `verifyWebhook(secret, headers, rawBody)` and `verifyCheckoutReceipt(token, { keys, seller, session })`.