@vibes.diy/prompts 14.3.174 → 14.3.176

package/llms/stripe.md

@@ -36,11 +36,15 @@ merchant. An app where *each visitor* collects money into *their own* Stripe
 account is a platform (Stripe Connect) and is a different thing this recipe
 does not build — say so plainly and build the one-merchant half.
 
-## 1. Bring your own Stripe key, and explain how
+## 1. The setup item: the owner's Stripe secret key
 
-The owner gets a key from Stripe, once. The steps are written for someone
-who has never opened Stripe, so each one is a link to the exact page and uses
-the words that page uses:
+The owner gets a key from Stripe, once. The Setup surface it lands on — the
+owner-only entry in the app's navigation, the verdict from `/setup`, the
+re-read on focus that unlocks the Pay buttons in place — is the use-vibe
+docs' *Some apps need setup before they work*; this recipe contributes one
+item to it. The Stripe item is the secret key: the backend answers missing-key while ctx.secrets.STRIPE_SECRET_KEY is absent, and its steps link Stripe's API keys page by URL and name STRIPE_SECRET_KEY in so many words.
+The steps are written for someone who has never opened Stripe, so each one is
+a link to the exact page and uses the words that page uses:
 
 1. Open Stripe's **API keys** page in test mode:
    <https://dashboard.stripe.com/test/apikeys> (sign in, or create a Stripe
@@ -54,34 +58,29 @@ the words that page uses:
 3. Come back to the app. The Pay buttons work the moment the key is saved; no
    redeploy. In test mode the card `4242 4242 4242 4242` with any future date
    pays.
-4. To go live, take the **live** secret key from
-   <https://dashboard.stripe.com/apikeys> (**Reveal live key**, `sk_live_`)
-   and set it the same way; setting an existing key replaces it.
-
-The app carries those steps in its own UI, because the person reading them is
-the person who has to do them — and it fills in the vibe's real handle and
-slug, which the backend knows as `ctx.appInfo`, so the Settings link and the
-terminal command are copy-ready rather than templates. The Settings tab opens
-in another tab, so the app re-reads `/status` whenever it regains focus or
-becomes visible again: the owner saves the key, comes back, and the card gives
-way to the Pay buttons without a reload.
-
-When the key is missing, the app shows the owner the setup steps for a Stripe secret key instead of an error, and the steps link to Stripe's API keys page and to this vibe's own Settings tab by URL.
-
-The backend answers `{ ok: false, reason: "missing-key" }` when
-`ctx.secrets.STRIPE_SECRET_KEY` is absent, and `/status` carries
-`ownerHandle` and `appSlug` so the client can render the numbered steps
-with real links: `https://dashboard.stripe.com/test/apikeys` for the key,
-`https://vibes.diy/vibes/mine/<ownerHandle>/<appSlug>/settings` for where
-it goes, and `STRIPE_SECRET_KEY` in so many words. "Open the Stripe
-dashboard" and "the Settings page" are not instructions; a person who has
-never seen either would have to search for both. A visitor who is not the
-owner sees a calmer sentence — payments are not set up yet — never the steps.
+4. Go live. When a test payment goes through, switch to your live key to take
+   real payments: open Stripe's **API keys** page in live mode,
+   <https://dashboard.stripe.com/apikeys>, press **Reveal live key** beside
+   **Secret key** (it starts with `sk_live_`), and set `STRIPE_SECRET_KEY` to
+   it the same way; setting an existing key replaces it. This step stays on
+   the Setup screen after the item is done, with a badge that reads *Test
+   mode* until the live key is in.
+
+Those steps are the item's copy on the Setup surface, with the vibe's real
+handle and slug filled in from the `ownerHandle` and `appSlug` the `/setup`
+route hands over. `https://dashboard.stripe.com/test/apikeys` for the key,
+`https://vibes.diy/vibes/mine/<ownerHandle>/<appSlug>/settings` for where it
+goes, and `STRIPE_SECRET_KEY` in so many words: "Open the Stripe dashboard"
+and "the Settings page" are directions to search for, and a person who has
+never seen either has to go looking. In the consumer flow, a Pay button whose
+key is not set reads *Checkout is not open yet*; the owner's Setup entry is
+where the steps are.
 
 Only the owner can set or rotate a secret, and handlers see the current value on
 every invocation — so the pay button starts working the moment the key lands,
 with no redeploy. There is no publishable key, no webhook signing secret and no
-second secret of any kind in this recipe: one key, held by the server.
+second secret of any kind in this recipe: one key, held by the server. Later,
+the same Setup entry is where the owner swaps the test key for the live one.
 
 ## 2. The key never reaches the browser, and neither does Stripe.js
 
@@ -308,11 +307,16 @@ async function settle(ctx, order) {
 export async function fetch(request, ctx) {
   const url = new URL(request.url);
 
-  // Is Stripe set up? The owner gets the steps; everyone else gets a sentence.
-  if (url.pathname === "/status" && request.method === "GET") {
+  // The setup verdict: ready for everyone, the items (and the handle + slug the Setup screen
+  // links with) for the owner alone.
+  if (url.pathname === "/setup" && request.method === "GET") {
     const owner = ctx.userInfo?.userHandle === ctx.appInfo.ownerHandle;
-    // ownerHandle + appSlug let the setup card link this vibe's own Settings tab.
-    return json({ ok: true, configured: Boolean(ctx.secrets.STRIPE_SECRET_KEY), owner, ownerHandle: ctx.appInfo.ownerHandle, appSlug: ctx.appInfo.appSlug });
+    const items = [{ id: "stripe-key", label: "Stripe secret key", done: Boolean(ctx.secrets.STRIPE_SECRET_KEY) }];
+    const ready = items.every((item) => item.done);
+    if (!owner) return json({ ok: true, ready, owner });
+    // `live` is the Go-live step's badge: a test key takes test payments, a live key real ones.
+    const live = (ctx.secrets.STRIPE_SECRET_KEY ?? "").startsWith("sk_live_");
+    return json({ ok: true, ready, owner, live, items, ownerHandle: ctx.appInfo.ownerHandle, appSlug: ctx.appInfo.appSlug });
   }
 
   // Start a purchase: the order first, then a Checkout Session for exactly that order.
@@ -421,32 +425,68 @@ export function orders(doc, oldDoc, user, ctx) {
 
 ### `App.jsx`
 ```jsx app=stripe-dues
-import React, { useEffect, useState } from "react";
+import React, { useEffect, useRef, useState } from "react";
 import { useFireproof } from "use-fireproof";
 import { apiFetch, useVibe } from "use-vibes";
-import { Badge, Button, Heading, Stack, Text } from "@vibes.diy/pouf";
+import { Badge, Button, Heading, Row, Stack, Text } from "@vibes.diy/pouf";
 
-// The owner's setup card: every step is a link to the exact page, in that page's own words.
-function SetupSteps({ status }) {
-  const vibe = `${status.ownerHandle}/${status.appSlug}`;
+// The setup verdict, read on mount and again whenever the app comes back into view: the owner
+// sets the key in another tab and returns, and the Pay buttons unlock without a reload.
+function useSetup() {
+  const [setup, setSetup] = useState(null); // { ready, owner, items?, ownerHandle?, appSlug? }
+  const latest = useRef(0);
+  useEffect(() => {
+    // Mount, focus and visibility reads overlap; only the latest one may land, or a slow stale
+    // answer overwrites a fresh one.
+    const load = () => {
+      const n = ++latest.current;
+      apiFetch("/setup").then((r) => r.json()).catch(() => ({ ready: false, owner: false })).then((s) => { if (n === latest.current) setSetup(s); });
+    };
+    load();
+    const onVisible = () => { if (document.visibilityState === "visible") load(); };
+    document.addEventListener("visibilitychange", onVisible);
+    window.addEventListener("focus", load);
+    return () => { document.removeEventListener("visibilitychange", onVisible); window.removeEventListener("focus", load); };
+  }, []);
+  return setup;
+}
+
+// The Setup surface, the owner's alone: one item, every step a link to the exact page in that
+// page's own words, with this vibe's real handle and slug filled in.
+function SetupScreen({ setup }) {
+  const vibe = `${setup.ownerHandle}/${setup.appSlug}`;
   const settingsUrl = `https://vibes.diy/vibes/mine/${vibe}/settings`;
+  const key = setup.items.find((item) => item.id === "stripe-key");
   return (
-    <ol>
-      <li>
-        Open Stripe's <a href="https://dashboard.stripe.com/test/apikeys" target="_blank" rel="noreferrer">API keys page (test mode)</a>,
-        use your Stripe account (the page offers to create one), and under <b>Standard keys</b> press <b>Reveal test key</b> beside <b>Secret key</b>.
-        Copy it; it starts with <code>sk_test_</code>.
-      </li>
-      <li>
-        Open <a href={settingsUrl} target="_blank" rel="noreferrer">this vibe's Settings tab</a> (My Vibes → this vibe → Settings).
-        Under <b>Secrets</b>, enter the key <code>STRIPE_SECRET_KEY</code>, paste the value, and save.
-        From a terminal instead: <code>npx vibes-diy secrets set STRIPE_SECRET_KEY --vibe {vibe}</code>.
-      </li>
-      <li>
-        Come back here: the Pay buttons work as soon as the key is saved. In test mode the card 4242 4242 4242 4242 pays.
-        To go live, do the same with the <a href="https://dashboard.stripe.com/apikeys" target="_blank" rel="noreferrer">live key</a>.
-      </li>
-    </ol>
+    <Stack>
+      <Heading>Setup</Heading>
+      <Row gap={2}>
+        <Text>{key.label}</Text>
+        <Badge tone={key.done ? "up" : "info"}>{key.done ? "Done" : "To do"}</Badge>
+      </Row>
+      <ol>
+        <li>
+          Open Stripe's <a href="https://dashboard.stripe.com/test/apikeys" target="_blank" rel="noreferrer">API keys page (test mode)</a>,
+          use your Stripe account (the page offers to create one), and under <b>Standard keys</b> press <b>Reveal test key</b> beside <b>Secret key</b>.
+          Copy it; it starts with <code>sk_test_</code>.
+        </li>
+        <li>
+          Open <a href={settingsUrl} target="_blank" rel="noreferrer">this vibe's Settings tab</a> (My Vibes → this vibe → Settings).
+          Under <b>Secrets</b>, enter the key <code>STRIPE_SECRET_KEY</code>, paste the value, and save.
+          From a terminal instead: <code>npx vibes-diy secrets set STRIPE_SECRET_KEY --vibe {vibe}</code>.
+        </li>
+        <li>
+          Come back here: the Pay buttons work as soon as the key is saved. In test mode the card 4242 4242 4242 4242 pays.
+        </li>
+        <li>
+          {/* The Go-live step stays here once the item is done; its badge says which key is in. */}
+          <Badge tone={setup.live ? "up" : "info"}>{setup.live ? "Live" : "Test mode"}</Badge>{" "}
+          When a test payment goes through, switch to your live key to take real payments: open Stripe's{" "}
+          <a href="https://dashboard.stripe.com/apikeys" target="_blank" rel="noreferrer">API keys page (live mode)</a>, press <b>Reveal live key</b> beside <b>Secret key</b>
+          (it starts with <code>sk_live_</code>), and set <code>STRIPE_SECRET_KEY</code> to it the same way.
+        </li>
+      </ol>
+    </Stack>
   );
 }
 
@@ -454,23 +494,13 @@ export default function App() {
   const { me } = useVibe("orders");
   const { useLiveQuery } = useFireproof("orders");
   const { docs: orders } = useLiveQuery("type", { key: "order" });
-  const [status, setStatus] = useState(null); // { configured, owner, ownerHandle, appSlug } from the backend
+  const setup = useSetup();
+  const [screen, setScreen] = useState("membership");
   const [error, setError] = useState(null);
 
-  // Read status on mount, and again whenever the app comes back into view: the owner sets the key
-  // in another tab and returns, and the setup card has to give way to the buttons without a reload.
-  useEffect(() => {
-    const load = () => apiFetch("/status").then((r) => r.json()).then(setStatus).catch(() => setStatus({ configured: false, owner: false }));
-    load();
-    const onVisible = () => { if (document.visibilityState === "visible") load(); };
-    document.addEventListener("visibilitychange", onVisible);
-    window.addEventListener("focus", load);
-    return () => { document.removeEventListener("visibilitychange", onVisible); window.removeEventListener("focus", load); };
-  }, []);
-
-  // Back from Stripe: ask the backend to read the session and settle the order.
-  // Back from Stripe. The wrapper hands the app its fragment just after first render and fires
-  // hashchange, so read the hash now AND on every change — a mount-only read can miss it.
+  // Back from Stripe: ask the backend to read the session and settle the order. The wrapper hands
+  // the app its fragment just after first render and fires hashchange, so read the hash now AND on
+  // every change — a mount-only read can miss it.
   useEffect(() => {
     const confirm = () => {
       const m = /#paid=([\w-]+)/.exec(location.hash);
@@ -506,36 +536,43 @@ export default function App() {
     }
   };
 
-  const configured = status?.configured === true;
-  if (status && !configured && status.owner) {
-    return (
-      <Stack>
-        <Heading>Set up payments</Heading>
-        <Text>Add your Stripe secret key once and the Pay buttons go live for everyone.</Text>
-        <SetupSteps status={status} />
-      </Stack>
-    );
-  }
-
+  const ready = setup?.ready === true;
   const mine = orders.filter((o) => o.buyerHandle === me?.userHandle);
   const paid = mine.some((o) => o.kind === "dues" && o.status === "paid");
   return (
     <Stack>
-      <Heading>Membership</Heading>
-      {paid ? (
-        <Badge tone="up">Dues paid</Badge>
+      <Row gap={2}>
+        <Button variant="quiet" onClick={() => setScreen("membership")}>Membership</Button>
+        {/* The Setup entry: the owner's alone, highlighted while an item is still to do, quiet once done. */}
+        {setup?.owner && (
+          <Button variant={ready ? "quiet" : "solid"} onClick={() => setScreen("setup")}>
+            Setup{ready ? "" : " · to do"}
+          </Button>
+        )}
+      </Row>
+      {screen === "setup" && setup?.owner ? (
+        <SetupScreen setup={setup} />
       ) : (
-        <Button onClick={() => pay("dues")} disabled={!configured || busy} loading={busy}>
-          Pay $40 dues — Stripe opens in a new tab
-        </Button>
-      )}
-      {error && <Text>{error}</Text>}
-      {status?.owner && (
-        <ul>
-          {orders.map((o) => (
-            <li key={o._id}>@{o.buyerHandle} · {o.title} · {(o.amount / 100).toFixed(2)} {o.currency.toUpperCase()} · {o.status}</li>
-          ))}
-        </ul>
+        <Stack>
+          <Heading>Membership</Heading>
+          {paid ? (
+            <Badge tone="up">Dues paid</Badge>
+          ) : ready ? (
+            <Button onClick={() => pay("dues")} disabled={busy} loading={busy}>
+              Pay $40 dues — Stripe opens in a new tab
+            </Button>
+          ) : (
+            <Text muted>Checkout is not open yet.</Text>
+          )}
+          {error && <Text>{error}</Text>}
+          {setup?.owner && (
+            <ul>
+              {orders.map((o) => (
+                <li key={o._id}>@{o.buyerHandle} · {o.title} · {(o.amount / 100).toFixed(2)} {o.currency.toUpperCase()} · {o.status}</li>
+              ))}
+            </ul>
+          )}
+        </Stack>
       )}
     </Stack>
   );

package/llms/use-vibe.md

@@ -81,6 +81,83 @@ function PromptBar({ database }) {
 
 Don't gate management UI on a display flag directly. Encode the rule in `access.js` (e.g. `ctx.requireRole("owner")` — the owner is auto-seeded into the reserved `owner` role) and gate the UI on `can.*` for that database — the verdict reflects the same rule. Per-row edit/delete affordances: `{can.edit(doc).ok && <EditButton doc={doc} />}`. By default every signed-in visitor is a first-class participant who creates and edits their own data; reserve `requireRole("owner")` for genuinely owner-published apps and per-object channels for peer-to-peer sharing. Public-vs-private and the allowed-user list are the owner's runtime sharing settings, not `access.js`.
 
+## Some apps need setup before they work
+
+Most apps work the moment they open. Some need their owner to do one thing first — paste a key, save a billing portal, connect an account — and that is a property of the app, not of any one integration, so every app that has it takes the same shape. An app has at most one **Setup** surface, and the backend's verdict decides its state, never a display flag. The integration skills (Stripe, Spotify, YouTube) each contribute one item to it: what the app needs, how the backend checks it, and the linked steps in the provider's own words.
+
+**The backend answers what the app needs and whether each item is done.** A `/setup` route in `backend.js`, called with `apiFetch` so `ctx.userInfo` is set, lists the items — the key is present, the portal is saved, the account is connected — with `done` read from `ctx.secrets` or the connection, and `ready` when every item is done. An item whose verdict costs a provider call (is the portal saved?) is asked on the owner's call alone and kept in a document the backend writes; a visitor's read takes the kept value, so visitor traffic spends nothing of the provider's and a blip there keeps the last verdict. The Setup surface is the owner's alone: the backend decides who the owner is, and non-owners never receive the items. Each step is a link to the exact page in that page's own words, with the vibe's real handle and slug filled in from what the backend hands the client. The route carries `ownerHandle` and `appSlug` from `ctx.appInfo`, so the Settings link (`https://vibes.diy/vibes/mine/<ownerHandle>/<appSlug>/settings`, **Secrets**) and the CLI line (`npx vibes-diy secrets set KEY --vibe <ownerHandle>/<appSlug>`) are copy-ready rather than templates.
+
+```js
+// backend.js — the verdict for everyone, the items for the owner alone
+if (url.pathname === "/setup" && request.method === "GET") {
+  const owner = ctx.userInfo?.userHandle === ctx.appInfo.ownerHandle;
+  const items = [{ id: "stripe-key", label: "Stripe secret key", done: Boolean(ctx.secrets.STRIPE_SECRET_KEY) }];
+  const ready = items.every((item) => item.done);
+  if (!owner) return json({ ok: true, ready, owner });
+  return json({ ok: true, ready, owner, items, ownerHandle: ctx.appInfo.ownerHandle, appSlug: ctx.appInfo.appSlug });
+}
+```
+
+**What the page shows, in four states.** Not done, owner: a **Setup** entry in the app's own navigation, highlighted while incomplete (an app with no navigation shows a top banner that opens it), and the Setup screen lists each item with its linked steps. Not done, non-owner: the feature reads as *not open yet*, nothing else. Done, owner: the Setup entry stays, quiet and reachable — later it is where a key is rotated or test turns into live. Done, non-owner: invisible. The owner's steps live on the Setup surface and nowhere else, and a feature that depends on them reads as not open yet in the consumer flow. The consumer flow is the buyer's, the reader's, the listener's, the same page for everyone; a coffee-order page whose step 3, Payment, turned into the owner's three-link chore is the shape this replaces. The page reads the verdict on mount and again whenever it regains focus or becomes visible, so the feature unlocks in place with no reload — the steps open Settings and the provider in other tabs, and the owner comes back to a feature that works.
+
+```jsx
+// App.jsx — one hook, one surface, the verdict decides what each person sees
+// (imports: useEffect, useRef, useState from react; apiFetch from use-vibes; pouf components)
+function useSetup() {
+  const [setup, setSetup] = useState(null);
+  const latest = useRef(0);
+  useEffect(() => {
+    // Mount, focus and visibility reads overlap; only the latest one may land, or a slow stale
+    // answer overwrites a fresh one.
+    const load = () => {
+      const n = ++latest.current;
+      apiFetch("/setup").then((r) => r.json()).catch(() => ({ ready: false, owner: false })).then((s) => { if (n === latest.current) setSetup(s); });
+    };
+    load();
+    const onVisible = () => { if (document.visibilityState === "visible") load(); };
+    document.addEventListener("visibilitychange", onVisible);
+    window.addEventListener("focus", load);
+    return () => { document.removeEventListener("visibilitychange", onVisible); window.removeEventListener("focus", load); };
+  }, []);
+  return setup;
+}
+
+function SetupScreen({ setup }) {
+  const vibe = `${setup.ownerHandle}/${setup.appSlug}`;
+  return (
+    <Stack>
+      <Heading>Setup</Heading>
+      {setup.items.map((item) => (
+        <Stack key={item.id}>
+          <Row gap={2}><Text>{item.label}</Text><Badge tone={item.done ? "up" : "info"}>{item.done ? "Done" : "To do"}</Badge></Row>
+          {/* the skill's steps: each one a link to the exact page, in that page's own words */}
+          <ol>
+            <li>Open Stripe's <a href="https://dashboard.stripe.com/test/apikeys" target="_blank" rel="noreferrer">API keys page (test mode)</a> and press <b>Reveal test key</b> beside <b>Secret key</b>.</li>
+            <li>Open <a href={`https://vibes.diy/vibes/mine/${vibe}/settings`} target="_blank" rel="noreferrer">this vibe's Settings tab</a>; under <b>Secrets</b>, enter <code>STRIPE_SECRET_KEY</code>, paste the value, and save.</li>
+          </ol>
+        </Stack>
+      ))}
+    </Stack>
+  );
+}
+
+export default function App() {
+  const setup = useSetup();
+  const [screen, setScreen] = useState("home");
+  return (
+    <Stack>
+      <Row gap={2}>
+        <Button variant="quiet" onClick={() => setScreen("home")}>Home</Button>
+        {setup?.owner && <Button variant={setup.ready ? "quiet" : "solid"} onClick={() => setScreen("setup")}>Setup{setup.ready ? "" : " · to do"}</Button>}
+      </Row>
+      {screen === "setup" && setup?.owner ? <SetupScreen setup={setup} /> : setup?.ready ? <PayButton /> : <Text muted>Checkout is not open yet.</Text>}
+    </Stack>
+  );
+}
+```
+
+Not the same thing: a *visitor's* first-run answers — who are you, which team — are per-person onboarding (the pouf onboarding block), saved as that person's own document, and stay as they are. Owner setup is the app's, done once, and lives on the Setup surface.
+
 ## The server is still the authority
 
 `can.*` is a fast preview, not the final word. A write can still be refused server-side (the server compares the change with the saved record, and the source may be stale, async, or unevaluable — in which case `can.*` optimistically returns `ok` and defers to the server). Write optimistically: `put()` saves locally at once and never rejects for access. A refused write converges to the server's version on its own, and the platform tells the visitor, so most apps need nothing more. For feedback beside the control, read the put's receipt (`const { synced } = await database.put(doc)`, then `synced.on(...)`), or `doc._synced.status` on a row — see the fireproof skill.