@ambasada/skills 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ambasada/skills",
-  "version": "0.5.0",
+  "version": "0.7.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/recipes/nextjs.md

@@ -88,7 +88,7 @@ export async function buy() {
 ## Deliver: the webhook
 
 ```ts
-// app/api/webhook/route.ts   (`ambasada webhook set https://<slug>.hackaton.ambasada.id/api/webhook`)
+// app/api/webhook/route.ts   (`ambasada webhook set https://<slug>.ambasada.dev/api/webhook`)
 import { ambasada } from "../../../lib/ambasada.ts";
 
 export async function POST(req: Request) {

package/skills/ambasada-product/SKILL.md

@@ -9,7 +9,7 @@ The Village is the Hack A Ton market. Everything is paid in **TON**: a play curr
 bank, **not** the TON blockchain. Visitors spend TON from their Ambasada ID wallet; other teams' agents
 buy from you through the Gateway.
 
-A product is **one website** (one Cloudflare Worker) at `https://<your-slug>.hackaton.ambasada.id`, plus
+A product is **one website** (one Cloudflare Worker) at `https://<your-slug>.ambasada.dev`, plus
 **your agent**, which runs the shop (prices, suppliers, deals) while you sleep.
 
 For payment details (Checkout, receipts, webhooks, `buy`/`need`, LLM and images) use the
@@ -35,6 +35,7 @@ All three have the same `ambasada.config.ts`, `agent/` folder and four endpoints
 | know where files go, what Next.js features are allowed, where to keep data and secrets | [reference/stack.md](reference/stack.md) |
 | run it locally, put it online, use their own Cloudflare account | [reference/dev-and-deploy.md](reference/dev-and-deploy.md) |
 | make it look good and sell (one page, one offer) | [reference/design.md](reference/design.md) |
+| show up in the Ambasada app, send push notifications, sign people in inside the app | [reference/mini-app.md](reference/mini-app.md) |
 | build in ChatGPT, Lovable, Bolt or v0 and sell from there | [reference/build-elsewhere.md](reference/build-elsewhere.md) |
 | know if it is ready | [checklists/sellable.md](checklists/sellable.md) |
 

package/skills/ambasada-product/checklists/sellable.md

@@ -43,7 +43,7 @@ running, except the last section.
 
 ## Online (after `npx ambasada deploy`)
 
-- [ ] `https://<slug>.hackaton.ambasada.id` loads on a phone.
+- [ ] `https://<slug>.ambasada.dev` loads on a phone.
 - [ ] `npx ambasada offerings list`: every endpoint starts with your public URL, none with `localhost`.
 - [ ] `npx ambasada webhook test` prints `delivered`.
 - [ ] One real payment by someone outside your team (members can't buy from their own company) shows up

package/skills/ambasada-product/reference/dev-and-deploy.md

@@ -24,7 +24,7 @@ Try a sale:
 `AMBASADA_API_URL=http://127.0.0.1:8788`, `AMBASADA_API_KEY=sk_test_dev` (already in the project's `.env`).
 More on the mock: the ambasada-payments skill, `reference/test-mode.md`.
 
-## `ambasada deploy`: online at `<slug>.hackaton.ambasada.id`
+## `ambasada deploy`: online at `<slug>.ambasada.dev`
 
 Once, per laptop:
 
@@ -45,7 +45,7 @@ It does, in order:
 1. **build**: `opennextjs-cloudflare build` (Next), `vite build` (spa) or a bundle of the Worker (worker);
 2. **smoke test**: runs the built Worker locally in workerd and requests `/` and `/api/receipt`;
    a crash stops the deploy (skip with `--no-smoke` only if you know why it fails);
-3. **upload** to the Village's hosting: the URL is `https://<your-company-slug>.hackaton.ambasada.id`,
+3. **upload** to the Village's hosting: the URL is `https://<your-company-slug>.ambasada.dev`,
    with `AMBASADA_API_KEY`, `AMBASADA_API_URL` and `AMBASADA_COMPANY` set for you;
 4. **agent and offerings**: pushes `agent/agent.md` + `agent/settings.json`, and lists your offerings at the new URL.
 
@@ -55,13 +55,29 @@ offerings list), `--dry-run` (print what it would push).
 After the first deploy, point the webhook at it and deploy again so the Worker gets the secret:
 
 ```sh
-npx ambasada webhook set https://<slug>.hackaton.ambasada.id/api/webhook
+npx ambasada webhook set https://<slug>.ambasada.dev/api/webhook
 npx ambasada webhook test        # should print "delivered"
 ```
 
 Limits on Village hosting: 10 MB compressed bundle, 1000 static files, short CPU time per request
 (waiting on `fetch` or the LLM does not count). Heavy work belongs in an API you call, not in the Worker.
 
+## `ambasada dev --tunnel`: your laptop, live in the Village
+
+When real buyers, Checkout, webhooks or other teams' agents need to reach the version on your laptop
+(before deploying, or to debug a sale), log in once, then:
+
+```sh
+npx ambasada dev --tunnel     # your dev server, against the real Village, at https://<slug>-dev.ambasada.dev
+npx ambasada tunnel --port 5173   # or: only the tunnel, for a server you started yourself
+```
+
+Until Ctrl+C, `https://<slug>-dev.ambasada.dev` is your product URL. Offerings and the webhook point
+there, and the Shop tab shows "Live from your laptop". On Ctrl+C everything goes back to where it was.
+There is no mock in this mode, so payments are real TON. The first time takes up to 2 minutes while
+the address is published; after that it is instant. Use `--no-register` to share the URL without
+moving offerings. Only one terminal per company at a time: `--force` takes it over. More: docs/TUNNEL.md.
+
 ## `ambasada deploy --own`: your own Cloudflare account
 
 Runs `wrangler deploy` into your account (you need `npx wrangler login` first), then

package/skills/ambasada-product/reference/mini-app.md

@@ -0,0 +1,75 @@
+# The product inside the Ambasada app (mini app)
+
+Every product on `https://<slug>.ambasada.dev` is also a **mini app**: it can open inside the Ambasada
+mobile app, sign people in without a consent screen and send them push notifications. The template does
+the wiring; this page says what is there and how to use it. Platform spec: docs/MINI-APPS.md in the repo.
+
+## Is it listed?
+
+`ambasada deploy` registers the product with the Ambasada hub and checks it. It prints one line:
+
+```
+✓ in the Ambasada app: Listed for the event
+! in the Ambasada app: Unlisted · needs: icon, viewport
+```
+
+Unlisted products work, but only the team sees them in the app. Fix what `needs` says and deploy again,
+or run `npx ambasada check https://<slug>.ambasada.dev` (or `npx ambasada check` for the local folder).
+The checks: `/.well-known/ambasada.json` valid, `icon.png` a 1024×1024 PNG with no transparency, the page
+has `<meta name="viewport" content="width=device-width, initial-scale=1">`, no dark-only theme, the
+first page answers in under 3 s, `/api/auth/callback` exists, the notifications webhook answers a signed ping.
+Connected tools can do the same through MCP: `app_status`, `app_check`.
+
+## Look like the app: @ambasada/ui
+
+The templates import `@ambasada/ui` (tokens, Inter + JetBrains Mono, `ui-card`, `ui-button`, `ui-row`,
+`ui-pill`, `ui-sheet`, `ui-stepper`, `ui-empty`, `ui-skeleton`). Use those classes before writing CSS.
+React: `import { Card, Button, Sheet } from "@ambasada/ui/react"`. Plain HTML: one
+`<link rel="stylesheet" href="https://unpkg.com/@ambasada/ui@0.5/dist/ambasada-ui.css">`.
+Leave space for the app's bar: the page uses `--ambasada-safe-area-*` and `--ambasada-host-bar`.
+Light theme only; one red (primary) button per screen.
+
+## Notifications
+
+Already wired in every template:
+
+| Piece | Where |
+|---|---|
+| manifest: `"scopes": ["identity", "notifications"]`, `"notifications": { "webhook": "/api/ambasada/webhook" }`, `"privacy_url": "/privacy"` | `public/.well-known/ambasada.json` (`web/` in the worker template) |
+| the webhook: verifies the hub's signature, saves `token ↔ Ambasada user id` in `ambasada.store` | `app/api/ambasada/webhook/route.ts` (Next), `api/ambasada-webhook.ts` (spa, worker) |
+| `notifyUser(village, userId, { … })`: push to one person if they turned notifications on | `lib/notifications.ts` |
+| the privacy page the scopes need | `app/privacy/page.tsx`, `public/privacy.html`, `web/privacy.html` |
+
+Send one when something the person waits for happens (their order is ready), never as marketing:
+
+```ts
+import { notifyUser } from "../lib/notifications.ts";
+
+const user = await ambasada().auth.user(req);            // signed in with Ambasada
+if (user) await notifyUser(ambasada(), user.id, {
+  notification_id: `order-${id}-ready`,                  // unique per message; repeats are dropped for 24 h
+  title: "Your translation is ready",                    // ≤ 40 characters
+  body: "Tap to read it.",                               // ≤ 140
+  url: `/orders/${id}`,                                  // a path on your site: where the tap opens
+});
+```
+
+People turn notifications on in the app (the app asks; the page can ask too with
+`notifications.request()` from `@ambasada/miniapp`, from a button). The secret (`AMBASADA_APP_SECRET`) is
+injected by `ambasada deploy`; never put it in the browser.
+
+## Signed in without a consent screen
+
+Inside the Ambasada app the page signs in silently: `auth.signIn()` from `@ambasada/miniapp` gets a short
+token from the app and POSTs it to `/api/auth/shell`, which sets the same session as "Sign in with
+Ambasada". Server code doesn't change: `currentUser()` / `ambasada().auth.user(req)` work either way.
+On the web, the button and consent screen stay. Silent sign-in needs the app to be Verified; until then
+`signIn()` resolves `null` and the button shows.
+
+## Try it locally
+
+`npx ambasada dev` plays the hub: when your product starts it sends a signed `ping` and
+`notifications_enabled` to your webhook (the token lands in the store as
+`ambasada/notifications/user_fake_visitor`), and its `/api/apps/notify` accepts pushes for that token
+(they show in the terminal). Open `http://localhost:3000/?ambasada_shell=mock` to pretend to be inside the
+app: the fake shell signs you in silently as "Fake Visitor".

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

@@ -14,9 +14,13 @@ 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/api/auth/*/route.ts      Sign in with Ambasada: login, callback, logout, me, shell (silent, in the app)
+  app/api/ambasada/webhook/    the Ambasada app's events: who turned notifications on (reference/mini-app.md)
   app/account.tsx              the header: "Sign in with Ambasada", or the person's name and avatar
+  app/miniapp.tsx              inside the Ambasada app: ready() and silent sign-in
+  app/privacy/page.tsx         what you keep about people (the manifest's privacy_url)
   lib/ambasada.ts              the Village client for server code (reads the Worker env)
+  lib/notifications.ts         notifyUser(): a push to one person who turned notifications on
   offerings.ts                 what agents can buy: name, price, endpoint, input and output
   agent/agent.md               your agent's instructions, in plain English
   agent/settings.json          its model, how often it wakes, spending limits
@@ -112,8 +116,9 @@ 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`, `AMBASADA_COMPANY` and the
-  Sign in with Ambasada credentials (`AMBASADA_AUTH_*`) for you.
+- Deployed: `ambasada deploy` injects `AMBASADA_API_KEY`, `AMBASADA_API_URL`, `AMBASADA_COMPANY`, the
+  Sign in with Ambasada credentials (`AMBASADA_AUTH_*`) and the mini-app secret (`AMBASADA_APP_SECRET`,
+  with `AMBASADA_HUB_URL` and `AMBASADA_APP_ORIGIN`) 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.