@vibes.diy/prompts 5.5.0 → 5.5.3

package/llms/backend.md

@@ -15,6 +15,20 @@ all — normal CRUD flows through Fireproof directly. Reach for it only when the
 app needs a server-side action: accepting a webhook, deriving/aggregating
 documents in reaction to writes, or periodic work.
 
+## When to use which handler — signal words
+
+- **`fetch`** — "webhook", "OAuth", "callback", "API endpoint", "receive",
+  "form POST", "Stripe/GitHub/Sonos sends us…". Something **external → us**.
+- **`onChange`** — "when X is created", "after a write", "notify", "send an
+  email", "aggregate", "moderate", "sync to…". An **internal write → a side
+  effect**.
+- **`scheduled`** — "every N minutes", "poll", "check periodically", "cron",
+  "cleanup", "digest". **Timer-driven**, no user in the loop.
+
+An app can need more than one — a payments app wants `fetch` (webhook receipt)
+**and** `onChange` (email on the new order). If none of these signal words fit
+the request, the app needs no `backend.js` — don't emit one.
+
 ## Output format
 
 `backend.js` is a separate file, exactly like `access.js`: one prose line, the
@@ -70,6 +84,7 @@ await ctx.db.put(doc, { db: "notes", id: "optional-id" }); // resolves to the do
 await ctx.db.delete(docId, { db: "notes" });
 const docs = await ctx.db.query({ db: "notes" }); // latest non-deleted docs (each with _id)
 const text = await ctx.callAI("prompt", { model: "openrouter/auto", max_tokens: 500 }); // server-side AI call
+const res = await ctx.fetch("https://api.example.com/x", { headers }); // outbound HTTP — use this, not bare fetch()
 ```
 
 - `{ db }` names the Fireproof database (same names `App.jsx` uses with
@@ -90,10 +105,16 @@ const text = await ctx.callAI("prompt", { model: "openrouter/auto", max_tokens:
   (`Authorization: Bearer ${ctx.secrets.KEY}` to an admitted API). Never write a
   value anywhere users can read it (a doc, a response body). Only the owner can
   set or rotate secrets; handlers see the current values on every invocation.
-- **Outbound `fetch()` is policy-gated**: `backend.js` can call external https
-  APIs that either (a) are CORS-open — the platform forwards the request exactly
-  as a browser on the app's own page could (same preflight rules, same
-  `Access-Control-Allow-Origin` check, browser-forbidden headers like `Cookie`
+- **Make every outbound HTTP call with `ctx.fetch(...)`, never a bare `fetch(...)`.**
+  It takes the same arguments as the web `fetch` and returns a `Response`. Why not
+  bare `fetch`: a backend that exports a `fetch` handler creates a module-scoped
+  `fetch` binding, so a bare `fetch(url)` anywhere in the file resolves to **your
+  own handler** — a `fetch` handler calling out recurses into itself, and a
+  `scheduled`/`onChange` call passes the URL where a `Request` is expected. `ctx.fetch`
+  always reaches the real HTTP client. **It is policy-gated**: `backend.js` can call
+  external https APIs that either (a) are CORS-open — the platform forwards the
+  request exactly as a browser on the app's own page could (same preflight rules,
+  same `Access-Control-Allow-Origin` check, browser-forbidden headers like `Cookie`
   are stripped) — or (b) are on the platform's curated list (`api.github.com` is
   seeded; additions are a PR to the platform repo). A denied call returns
   `403 {"vibesEgressDenied":true,"gate":"floor"|"owner-blocked"|"cors"|"rate-limit","host":...}` —
@@ -101,7 +122,7 @@ const text = await ctx.callAI("prompt", { model: "openrouter/auto", max_tokens:
   request a curated-list addition, or ask about owner blessing. Limits: https
   on port 443 only, 15s per request, 10MB responses, per-vibe rate caps
   (30/10s, 300/min). Make all outbound calls **before returning** the Response —
-  a `fetch()` fired while a streamed body is still being pulled after the
+  a `ctx.fetch()` fired while a streamed body is still being pulled after the
   handler returned is unsupported and gets denied. Interactive frontend AI
   calls stay in `App.jsx` via `callAI`; server-side AI belongs to `ctx.callAI`.
 - **`ctx.callAI(prompt, options?)` is the server-side AI call.** It resolves to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibes.diy/prompts",
-  "version": "5.5.0",
+  "version": "5.5.3",
   "type": "module",
   "main": "./index.js",
   "description": "",
@@ -24,9 +24,9 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@adviser/cement": "~0.5.34",
-    "@vibes.diy/call-ai-v2": "^5.5.0",
-    "@vibes.diy/identity": "^5.5.0",
-    "@vibes.diy/use-vibes-types": "^5.5.0",
+    "@vibes.diy/call-ai-v2": "^5.5.3",
+    "@vibes.diy/identity": "^5.5.3",
+    "@vibes.diy/use-vibes-types": "^5.5.3",
     "arktype": "~2.2.3",
     "json-schema-faker": "~0.6.2"
   },