@ambasada/skills 0.2.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ambasada/skills",
-  "version": "0.2.0",
+  "version": "0.4.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": [

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

@@ -43,14 +43,50 @@ const res = await village.llm.chat({ model: "deepseek-v4-pro", messages });   //
 const { url } = await village.images.generate({ prompt: "a lighthouse", model: "nano_banana" });
 const tools = await village.tools.list();                                     // curated catalog, TON prices
 const { output } = await village.tools.call("web.search", { query: "Mamaia weather" });
-const file = await village.files.put(bytes, { contentType: "image/png" });     // public URL for other products
+const file = await village.files.put(bytes, { contentType: "image/png" });     // { id, url }: public URL, 0.1 TON
 ```
 
 HTTP: `POST /v1/llm/chat` (OpenAI body), `POST /v1/images { model, prompt }` → `{ url, cost }`,
-`GET /v1/tools`, `POST /v1/tools/:id` → `{ output, cost, call_id }`, `POST /v1/files`.
+`GET /v1/tools`, `POST /v1/tools/:id` → `{ output, cost, call_id }`, `POST /v1/files` (raw body +
+content-type, or `{ url }`) → `{ id, url, cost }`.
 LLM models: `deepseek-v4.1-flash` (default, cheap), `deepseek-v4-pro`, `glm-5.3-flash`.
 Images: `nano_banana` (2 TON), `gpt-image-2` (8 TON).
 
+## Store and hosting
+
+`village.store` is your company's JSON key-value store: free, 1 MB per company (keys + values), so a
+hosted product needs no database. `ambasada deploy` hosts the product at `https://<slug>.ambasada.dev`
+with `AMBASADA_API_KEY`, `AMBASADA_API_URL`, `AMBASADA_COMPANY` and `AMBASADA_WEBHOOK_SECRET` already set.
+
+```ts
+await village.store.set("cart:ana", { items: ["translate"] });   // any JSON value
+const cart = await village.store.get<{ items: string[] }>("cart:ana"); // null when not set
+await village.store.delete("cart:ana");
+const { keys, used_bytes } = await village.store.list("cart:");
+```
+
+HTTP: `GET|PUT|DELETE /v1/store/:key` (PUT body = the JSON value), `GET /v1/store?prefix=`;
+`POST /v1/product/deploy` (what `ambasada deploy` calls), `GET /v1/product`, `DELETE /v1/product`.
+
+## Sign in with Ambasada
+
+People sign in to your hosted product with their Ambasada ID. There is nothing to set up: `ambasada deploy`
+injects `AMBASADA_AUTH_CLIENT_ID`, `AMBASADA_AUTH_CLIENT_SECRET` and `AMBASADA_AUTH_ISSUER`, and `ambasada dev`
+injects fake ones (the mock signs you in as "Fake Visitor"). The templates already have the routes and a
+header button.
+
+```ts
+// GET /api/auth/login?returnTo=/   GET /api/auth/callback   GET /api/auth/logout
+return village.auth.login(req, { returnTo: "/", email: false }); // email: true asks for it on the consent screen
+return village.auth.callback(req);                                // sets an HttpOnly session cookie
+return village.auth.logout(req);
+const user = await village.auth.user(req); // null, or { id, name, avatar_url, builder, builder_since, member_since, pass, email? }
+```
+
+`user.id` (`user_…`) is stable: key your data by it (``village.store.set(`user:${user.id}`, …)``).
+`pass` is `"builder" | "visitor" | "staff" | null` for the current event. Server code only; the browser asks
+`/api/auth/me`. It works on `https://<slug>.ambasada.dev` and under `ambasada dev`, not with `--own` hosting.
+
 ## Errors
 
 `{ "error": { "code", "message", call_id?, charged?: false, refunded?, approval_id? } }`. The SDK throws

package/skills/ambasada-product/reference/stack.md

@@ -14,6 +14,8 @@ my-shop/
   app/api/webhook/route.ts     checkout.paid arrives here, signed: deliver here
   app/api/receipt/route.ts     verifies a pay.js receipt from the browser
   app/api/translate/route.ts   the paid offering: agents call it with a receipt
+  app/api/auth/*/route.ts      Sign in with Ambasada: login, callback, logout, me
+  app/account.tsx              the header: "Sign in with Ambasada", or the person's name and avatar
   lib/ambasada.ts              the Village client for server code (reads the Worker env)
   offerings.ts                 what agents can buy: name, price, endpoint, input and output
   agent/agent.md               your agent's instructions, in plain English
@@ -48,6 +50,23 @@ where `env` comes from `getCloudflareContext()` (deployed); under `next dev` the
 It reads `AMBASADA_API_KEY`, `AMBASADA_API_URL`, `AMBASADA_COMPANY`, `AMBASADA_WEBHOOK_SECRET`.
 Everything the client can do is in the ambasada-payments skill.
 
+## Who is signed in
+
+Every hosted product gets **Sign in with Ambasada** (Ambasada ID) for free: no keys, no settings.
+The template's header already has the button. In server code:
+
+```ts
+import { currentUser } from "../lib/ambasada.ts";
+
+const user = await currentUser(); // null, or { id, name, avatar_url, builder, pass, member_since, … }
+if (!user) redirect("/api/auth/login?returnTo=/orders");
+await ambasada().store.set(`orders:${user.id}`, orders); // key per-person data by user.id
+```
+
+In a route handler, `ambasada().auth.user(req)` does the same. Client components fetch `/api/auth/me`.
+Ask for the email only if you need it: `/api/auth/login` calls `auth.login(req, { email: true })`.
+Don't build your own login or accounts table, and don't add Clerk, Auth.js or Supabase Auth.
+
 ## Next.js: allowed and banned
 
 Allowed, and enough for any product here:
@@ -93,7 +112,8 @@ File URLs are public: don't put private data in them.
 
 - Local: `.env` in the project (Cloudflare's `.dev.vars` works too). The template writes it with test
   values for `ambasada dev`. Both are in `.gitignore`; keep them there.
-- Deployed: `ambasada deploy` injects `AMBASADA_API_KEY`, `AMBASADA_API_URL` and `AMBASADA_COMPANY` for you.
+- Deployed: `ambasada deploy` injects `AMBASADA_API_KEY`, `AMBASADA_API_URL`, `AMBASADA_COMPANY` and the
+  Sign in with Ambasada credentials (`AMBASADA_AUTH_*`) for you.
   With `--own`, set them yourself: `npx wrangler secret put AMBASADA_API_KEY`.
 - Other services' keys (an OpenAI key, say): same place, read on the server only.
 - Anything named `NEXT_PUBLIC_*` is copied into the browser. Never put a key there.