@vibes.diy/prompts 14.3.175 → 14.3.176

package/llms/stripe-subscriptions.md

@@ -26,11 +26,15 @@ that record grants. An app where each visitor sells their own subscriptions is
 a platform (Stripe Connect) and a different thing — say so and build the
 one-merchant half.
 
-## 1. Bring your own Stripe key, turn on the portal, and explain how
+## 1. The setup items: the owner's Stripe secret key, and the Customer portal
 
-The owner sets up 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 sets up Stripe once. The Setup surface the two items land on — the
+owner-only entry in the app's navigation, the verdict from `/setup`, the
+re-read on focus that unlocks the Join buttons in place — is the use-vibe
+docs' *Some apps need setup before they work*; this recipe contributes two
+items to it. The Stripe items are the secret key and the Customer portal: the backend answers missing-key while ctx.secrets.STRIPE_SECRET_KEY is absent, reads whether a portal configuration has been saved, and its steps link Stripe's API keys page and Stripe's Customer portal settings 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
@@ -46,33 +50,35 @@ page uses:
    **Cancellations**, turn on **Cancel subscriptions** and choose **At end of
    billing period**, then press **Save**. The app sends members there to cancel
    or change a card, and the portal does not exist until it is saved once.
-4. To go live, take the **live** secret key from
-   <https://dashboard.stripe.com/apikeys> (**Reveal live key**, `sk_live_`),
-   set it the same way, and save the portal once more at
-   <https://dashboard.stripe.com/settings/billing/portal>.
-
-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 Join buttons without a reload.
-
-When the key is missing, the app shows the owner the setup steps for a Stripe secret key and the Customer Portal instead of an error, and the steps link to Stripe's API keys page, Stripe's Customer portal settings and 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, `https://dashboard.stripe.com/test/settings/billing/portal` for the
-portal, 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 — memberships are not open yet — never the steps. A portal that was never saved
-answers a Stripe error whose message says so; keep that sentence (§ 7) and the
-owner reads step 3 off it.
+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_`), set `STRIPE_SECRET_KEY` to it
+   the same way, and save the **Customer portal** once more in live mode at
+   <https://dashboard.stripe.com/settings/billing/portal> — test-mode settings
+   stay in test mode. This step stays on the Setup screen after both items
+   are done, with a badge that reads *Test mode* until the live key is in.
+
+Those steps are the items' 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, `https://dashboard.stripe.com/test/settings/billing/portal` for the
+portal, 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. The portal item is checked with one read
+of `GET /v1/billing_portal/configurations?is_default=true&active=true` — the
+active default is the configuration `/portal` opens, and a portal that was
+never saved has none — made only on the **owner's** `/setup` call and kept in
+a `setup` document the backend writes, so the owner sees the item turn to
+*Done* the moment they press Save and a visitor's read costs Stripe nothing. A
+refused read (a wrong key, a platform refusal, Stripe down) keeps the last
+verdict and rides the item as `problem`, which the Setup screen shows the
+owner in Stripe's own words; only a successful empty answer means not saved.
+A portal that was skipped answers a Stripe error whose message says so (§ 8).
+In the consumer flow, a Join button whose items are not done reads
+*Memberships are not open yet*; the owner's Setup entry is where the steps
+are, and later it is where the owner swaps the test key for the live one.
 
 ## 2. The key never reaches the browser, and neither does Stripe.js
 
@@ -298,6 +304,22 @@ async function stripe(ctx, method, path, form, headers = {}) {
   return { ok: true, body };
 }
 
+// Has the owner saved the Customer portal? Stripe is asked only on the OWNER's call, and the answer
+// is kept in a document the backend writes, so a visitor's /setup read never reaches Stripe and a
+// blip at Stripe keeps the last verdict. The /portal route opens the ACTIVE DEFAULT configuration,
+// so that is the one asked for; a refused read is a problem shown to the owner, never "not saved".
+const PORTAL_STATE = "setup:stripe-portal";
+async function portalSaved(ctx, owner) {
+  const kept = await ctx.db.get(PORTAL_STATE, { db: DB });
+  const known = kept?.saved === true;
+  if (!owner || !ctx.secrets.STRIPE_SECRET_KEY) return { done: known };
+  const configurations = await stripe(ctx, "GET", "/billing_portal/configurations?is_default=true&active=true&limit=1");
+  if (!configurations.ok) return { done: known, problem: configurations.message ?? "Stripe could not be reached; the last verdict stands." };
+  const saved = (configurations.body.data?.length ?? 0) > 0;
+  if (known !== saved) await ctx.db.put({ _id: PORTAL_STATE, type: "setup", saved, checkedAt: Date.now() }, { db: DB, id: PORTAL_STATE, ifRev: kept?._rev });
+  return { done: saved };
+}
+
 // Stripe's answer, reduced to the facts the app keeps. The period bounds are Unix seconds, and
 // newer API versions carry them on the subscription item rather than the subscription.
 function mirror(sub) {
@@ -364,9 +386,19 @@ export async function fetch(request, ctx) {
   const url = new URL(request.url);
   const me = ctx.userInfo?.userHandle;
 
-  if (url.pathname === "/status" && request.method === "GET") {
-    // 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: me === ctx.appInfo.ownerHandle, graceDays: GRACE_DAYS, ownerHandle: ctx.appInfo.ownerHandle, appSlug: ctx.appInfo.appSlug });
+  // 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 = me === ctx.appInfo.ownerHandle;
+    const items = [
+      { id: "stripe-key", label: "Stripe secret key", done: Boolean(ctx.secrets.STRIPE_SECRET_KEY) },
+      { id: "stripe-portal", label: "Customer portal", ...(await portalSaved(ctx, owner)) },
+    ];
+    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, graceDays: GRACE_DAYS, ownerHandle: ctx.appInfo.ownerHandle, appSlug: ctx.appInfo.appSlug });
   }
 
   if (!me) return json({ ok: false, reason: "sign-in" }, 401);
@@ -375,6 +407,9 @@ export async function fetch(request, ctx) {
 
   if (url.pathname === "/subscribe" && request.method === "POST") {
     if (!ctx.secrets.STRIPE_SECRET_KEY) return json({ ok: false, reason: "missing-key" }, 503);
+    // The portal is where a member cancels, so nobody joins before it exists: the KEPT verdict,
+    // never a Stripe read per press.
+    if ((await ctx.db.get(PORTAL_STATE, { db: DB }))?.saved !== true) return json({ ok: false, reason: "setup-incomplete" }, 503);
     const { plan } = await request.json();
     const price = PLANS[plan];
     if (!price) return json({ ok: false, reason: "unknown-plan" }, 400);
@@ -516,6 +551,13 @@ export function club(doc, oldDoc, user, ctx) {
     return { channels: [doc.membersOnly ? "members" : "public"], grant: { public: ["public"] } };
   }
 
+  // The setup verdict the backend keeps (the portal's saved state): written by backend.js alone,
+  // read on the owner's channel.
+  if (doc.type === "setup") {
+    ctx.requireBackend();
+    return { channels: ["memberships"] };
+  }
+
   throw { forbidden: "unknown document type" };
 }
 ```
@@ -524,37 +566,77 @@ export function club(doc, oldDoc, user, ctx) {
 
 ### `App.jsx`
 ```jsx app=stripe-membership
-import React, { useEffect, useState } from "react";
+import React, { useEffect, useRef, useState } from "react";
 import { useFireproof } from "use-fireproof";
 import { apiFetch, useViewer } 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 setup verdict, read on mount and again whenever the app comes back into view: the owner
+// sets the key or saves the portal in another tab and returns, and the Join buttons unlock without
+// a reload.
+function useSetup() {
+  const [setup, setSetup] = useState(null); // { ready, owner, items?, graceDays?, 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 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 surface, the owner's alone: two items, 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`;
   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>
-        Open Stripe's <a href="https://dashboard.stripe.com/test/settings/billing/portal" target="_blank" rel="noreferrer">Customer portal settings</a>:
-        under <b>Cancellations</b> turn on <b>Cancel subscriptions</b>, choose <b>At end of billing period</b>, and press <b>Save</b>.
-        Members use that page to cancel or change a card.
-      </li>
-      <li>
-        Come back here: the Join 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> and the live portal.
-      </li>
-    </ol>
+    <Stack>
+      <Heading>Setup</Heading>
+      {setup.items.map((item) => (
+        <Row key={item.id} gap={2}>
+          <Text>{item.label}</Text>
+          <Badge tone={item.done ? "up" : "info"}>{item.done ? "Done" : "To do"}</Badge>
+          {item.problem && <Text muted>{item.problem}</Text>}
+        </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>
+          Open Stripe's <a href="https://dashboard.stripe.com/test/settings/billing/portal" target="_blank" rel="noreferrer">Customer portal settings</a>:
+          under <b>Cancellations</b> turn on <b>Cancel subscriptions</b>, choose <b>At end of billing period</b>, and press <b>Save</b>.
+          Members use that page to cancel or change a card.
+        </li>
+        <li>
+          Come back here: the Join buttons work as soon as both items are done. In test mode the card 4242 4242 4242 4242 pays.
+        </li>
+        <li>
+          {/* The Go-live step stays here once the items are 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>), set <code>STRIPE_SECRET_KEY</code> to it the same way, and save the{" "}
+          <a href="https://dashboard.stripe.com/settings/billing/portal" target="_blank" rel="noreferrer">Customer portal settings (live mode)</a> once more.
+        </li>
+      </ol>
+    </Stack>
   );
 }
 
@@ -563,21 +645,11 @@ export default function App() {
   const { useLiveQuery } = useFireproof("club"); // memberships AND posts: one database, one grant set
   const { docs: memberships } = useLiveQuery("type", { key: "membership" });
   const { docs: posts } = useLiveQuery("type", { key: "post" });
-  const [status, setStatus] = useState(null); // { configured, owner, graceDays } from the backend
+  const setup = useSetup();
+  const [screen, setScreen] = useState("club");
   const [busy, setBusy] = useState(false);
   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: the fragment arrives just after first render and on hashchange, so read both.
   useEffect(() => {
     const settle = () => {
@@ -606,7 +678,7 @@ export default function App() {
       const data = await res.json();
       if (!data.ok) {
         tab.close();
-        setError(data.reason === "stripe" ? data.message : data.reason === "already-member" ? "You already have a membership — manage it below." : "Memberships are not available right now.");
+        setError(data.reason === "stripe" ? data.message : data.reason === "already-member" ? "You already have a membership — manage it below." : "Memberships are not open yet.");
         return;
       }
       tab.location.href = data.url;
@@ -615,63 +687,70 @@ export default function App() {
     }
   };
 
-  const configured = status?.configured === true;
-  if (status && !configured && status.owner) {
-    return (
-      <Stack>
-        <Heading>Set up memberships</Heading>
-        <Text>Three steps in Stripe, once, and the Join buttons go live for everyone.</Text>
-        <SetupSteps status={status} />
-      </Stack>
-    );
-  }
-
+  const ready = setup?.ready === true;
   const mine = viewer ? memberships.find((m) => m._id === `membership-${viewer.userHandle}`) : undefined;
   const entitled = mine?.entitled === true;
   const ends = mine?.currentPeriodEnd ? new Date(mine.currentPeriodEnd).toLocaleDateString() : null;
 
   return (
     <Stack>
-      <Heading>The club</Heading>
-      {!viewer ? (
-        <Stack>
-          <Text>Members read every post. Join for $5 a month, cancel any time.</Text>
-          <Button onClick={() => requestLogin()}>Sign in to join</Button>
-        </Stack>
-      ) : entitled ? (
-        <Badge tone="up">{mine.cancelAtPeriodEnd ? `Member until ${ends}` : mine.status === "past_due" ? "Payment due — please update your card" : "Member"}</Badge>
+      <Row gap={2}>
+        <Button variant="quiet" onClick={() => setScreen("club")}>The club</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} />
       ) : (
         <Stack>
-          <Text>Members read every post. Join for $5 a month, cancel any time.</Text>
-          {mine?.subscriptionId && mine.status !== "canceled" ? (
-            <Text>Your last payment did not go through. Update your card below to keep reading.</Text>
+          <Heading>The club</Heading>
+          {!viewer ? (
+            <Stack>
+              <Text>Members read every post. Join for $5 a month, cancel any time.</Text>
+              <Button onClick={() => requestLogin()}>Sign in to join</Button>
+            </Stack>
+          ) : entitled ? (
+            <Badge tone="up">{mine.cancelAtPeriodEnd ? `Member until ${ends}` : mine.status === "past_due" ? "Payment due — please update your card" : "Member"}</Badge>
           ) : (
-            <Button onClick={() => openStripe("/subscribe", { plan: "monthly" })} disabled={!configured || busy} loading={busy}>
-              Join — Stripe opens in a new tab
+            <Stack>
+              <Text>Members read every post. Join for $5 a month, cancel any time.</Text>
+              {mine?.subscriptionId && mine.status !== "canceled" ? (
+                <Text>Your last payment did not go through. Update your card below to keep reading.</Text>
+              ) : ready ? (
+                <Button onClick={() => openStripe("/subscribe", { plan: "monthly" })} disabled={busy} loading={busy}>
+                  Join — Stripe opens in a new tab
+                </Button>
+              ) : (
+                <Text muted>Memberships are not open yet.</Text>
+              )}
+            </Stack>
+          )}
+          {/* The portal is reachable whenever Stripe knows this member, entitled or not: a lapsed
+              member needs it most, to update the card or to cancel. */}
+          {mine?.customerId && (
+            <Button variant="quiet" onClick={() => openStripe("/portal", {})} disabled={busy} loading={busy}>
+              Manage membership — Stripe opens in a new tab
             </Button>
           )}
+          {error && <Text>{error}</Text>}
+          <ul>
+            {posts.map((p) => (
+              <li key={p._id}>{p.membersOnly && <Badge tone="info">Members</Badge>} {p.title}</li>
+            ))}
+          </ul>
+          {setup?.owner && (
+            <ul>
+              {memberships.map((m) => (
+                <li key={m._id}>@{m.memberHandle} · {m.plan} · {m.status}{m.entitled ? " · entitled" : ""}{m.currentPeriodEnd ? ` · until ${new Date(m.currentPeriodEnd).toLocaleDateString()}` : ""}</li>
+              ))}
+            </ul>
+          )}
         </Stack>
       )}
-      {/* The portal is reachable whenever Stripe knows this member, entitled or not: a lapsed
-          member needs it most, to update the card or to cancel. */}
-      {mine?.customerId && (
-        <Button variant="quiet" onClick={() => openStripe("/portal", {})} disabled={busy} loading={busy}>
-          Manage membership — Stripe opens in a new tab
-        </Button>
-      )}
-      {error && <Text>{error}</Text>}
-      <ul>
-        {posts.map((p) => (
-          <li key={p._id}>{p.membersOnly && <Badge tone="info">Members</Badge>} {p.title}</li>
-        ))}
-      </ul>
-      {status?.owner && (
-        <ul>
-          {memberships.map((m) => (
-            <li key={m._id}>@{m.memberHandle} · {m.plan} · {m.status}{m.entitled ? " · entitled" : ""}{m.currentPeriodEnd ? ` · until ${new Date(m.currentPeriodEnd).toLocaleDateString()}` : ""}</li>
-          ))}
-        </ul>
-      )}
     </Stack>
   );
 }