@ambasada/skills 0.5.0 → 0.6.0

package/package.json

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

@@ -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/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.