@vibes.diy/prompts 14.3.156 → 14.3.159

package/llms/stripe-subscriptions.md

@@ -0,0 +1,633 @@
+# Stripe subscriptions — a paid membership that follows Stripe's state
+
+When someone asks for **recurring money** — a paid newsletter, a members-only
+club, a monthly coaching community, a subscription tier — build it on **Stripe
+Checkout in subscription mode** from `backend.js`, with the secret key the owner
+supplies, and keep the member's access a mirror of what Stripe says about their
+subscription. This is a `backend.js` feature (see the backend docs for the
+general handler contract) and a sibling of the `stripe` skill, which takes a
+one-time payment; this page is the recipe for money that keeps moving, where the
+question is never "did they pay" but "are they entitled right now".
+
+**This skill comes in only when the person asks for a subscription.** A feed
+with a "members" label, a club page, a course — each of those is free until the
+person says people pay monthly, yearly, or "subscribe". What you may do unasked
+is **offer** it: on an app with members-only content, the closing row's
+capability option is `▸ [pay] Charge a monthly membership with Stripe`, gold
+when nothing else fits better, and a tap on it is the ask. Words that are the
+ask: "subscription", "subscribe", "monthly", "per month", "yearly", "membership
+fee", "paid tier", "paywall", "recurring". A one-time charge — dues once a year,
+a ticket, a deposit — is the `stripe` skill, not this one.
+
+**One merchant, many members.** Every member pays the owner's Stripe account,
+whose key is on the vibe. A member is a signed-in person whose membership is a
+record between them and the owner, and the members-only content is a channel
+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
+
+The owner sets up Stripe once:
+
+1. Open the Stripe dashboard and sign in (or create a Stripe account). Turn on
+   **Test mode** until the app is working.
+2. Go to Developers, then API keys, and reveal the **Secret key**. Set it on
+   the vibe as `STRIPE_SECRET_KEY` — the vibe's settings page, or
+   `vibes-diy secrets set STRIPE_SECRET_KEY <the key>`.
+3. Go to Settings, then Billing, then **Customer portal**, and save it with
+   **Cancel at end of billing period** on. 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, repeat steps 2 and 3 with Test mode off.
+
+The app carries those steps in its own UI, because the person reading them is
+the person who has to do them.
+
+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.
+
+The backend answers `{ ok: false, reason: "missing-key" }` when
+`ctx.secrets.STRIPE_SECRET_KEY` is absent, and the client renders the numbered
+steps, naming the Stripe dashboard, `STRIPE_SECRET_KEY` and the Customer Portal
+in so many words. 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.
+
+## 2. The key never reaches the browser, and neither does Stripe.js
+
+Every Stripe request is made in backend.js with ctx.fetch and ctx.secrets.STRIPE_SECRET_KEY; App.jsx never calls api.stripe.com and never loads Stripe.js.
+
+The client talks to the app's own `/_api/...` routes, and the backend is the
+only place that knows the key exists. Stripe Checkout and the Customer Portal
+are pages Stripe hosts: the backend mints a URL, the page opens it, Stripe does
+the card, the retries, the invoices and the cancellation screen. Nothing about
+a card ever touches the app.
+
+Checkout opens in a new tab with window.open, because the app runs inside a frame that cannot navigate the page around it.
+
+The same goes for the portal. Open the tab inside the click handler, before any
+`await`, and check it for `null` before asking the backend for anything; hold
+the button busy until the tab is on its way. Say in the button's copy that
+Stripe opens in a new tab.
+
+## 3. One membership, then one Checkout Session
+
+The membership exists before the money moves, and there is **one record per
+member**, `membership-<handle>`, rewritten in place by every attempt, renewal
+and lapse. `/subscribe` runs as the signed-in member (the page calls it with
+`apiFetch`), claims that record in `pending` with the plan — against the
+revision it just read, so a concurrent press conflicts and is handed the
+attempt that won — and asks Stripe for a session for exactly that record:
+
+- `mode=subscription`, with an inline recurring price:
+  `line_items[0][price_data][recurring][interval]=month` (or `year`),
+  `unit_amount` in the smallest unit, a product name. The owner never creates
+  products in the dashboard first.
+- `client_reference_id` carries the record's `_id` and `metadata[attempt]`
+  its attempt number.
+- `success_url` and `cancel_url` are the app's public address with a fragment,
+  `#subscribed` and `#cancelled`; the record is the caller's own, so no id
+  rides the URL.
+- `Idempotency-Key` is `<record id>:<attempt>`, so two first presses that both
+  got past the claim (a record that does not exist yet has no revision to
+  claim) mint one session at Stripe; and a second press on an open attempt
+  reuses its session for the day rather than minting another.
+
+Amounts are integers in the currency's smallest unit: $5 a month is unit_amount 500, never 5.0.
+
+The price lives in the app's own plan list on the server; the browser sends a
+plan name, never an amount. One subscription per person: `/subscribe` refuses
+while the member's subscription is **live at Stripe** — `active`, `trialing`,
+`past_due`, `unpaid` or `paused`, entitled or not — because a lapsed member
+whose card Stripe is still retrying must not be sold a second subscription
+that bills beside the first once it recovers. Those members are sent to the
+portal (§ 7) to fix the card or cancel.
+
+The routes read the `club` database, which `access.js` binds, so `backend.js`
+declares `config.fetch.unfilteredReads` for it — and owes the obligation that
+comes with it: every route reads exactly one record, `membership-<caller>`,
+and no route lists memberships for anyone. The owner's roster is the page's
+own live query, scoped by the access function's `memberships` channel to the
+owner role.
+
+## 4. Entitlement is Stripe's status plus one number, the grace period
+
+A membership is entitled while Stripe's status is active or trialing, and while it is past_due until current_period_start plus GRACE_DAYS; canceled, unpaid, paused and incomplete lock it at once.
+
+`GRACE_DAYS` is the recipe's one knob. Stripe retries a failed renewal for a
+few days and most retries succeed, so a short grace (five days is the default)
+keeps a member whose card bounced once from being locked out while Stripe is
+still collecting. Set it to zero and a failed renewal locks the moment it
+fails. Nothing else about entitlement is configurable, on purpose:
+
+- `active` and `trialing` are entitled. A member who cancelled **at period
+  end** stays `active` with `cancel_at_period_end: true` until the date, so
+  they keep what they paid for; the page shows "ends on …".
+- `past_due` is entitled until `current_period_start + GRACE_DAYS`, then
+  locked. The anchor is the period **start**, not the end: when a renewal
+  fails Stripe has already opened the new period, so `current_period_end` is
+  a month or a year away and would hand a lapsed member the whole interval.
+  `current_period_start` is the moment the renewal was due, which is the
+  moment the grace clock should start.
+- `canceled`, `unpaid`, `paused`, `incomplete` and `incomplete_expired` are
+  locked at once. With the portal set to cancel at period end (§ 1 step 3), a
+  cancellation never cuts into paid time, because Stripe keeps the status
+  `active` until the period closes.
+
+The backend computes `entitled` and writes it on the membership document;
+nothing else does, and a value computed only for a response is not
+entitlement. Read `current_period_start` and `current_period_end` as
+`sub.current_period_start ?? sub.items?.data?.[0]?.current_period_start` (and
+the same for the end) — newer Stripe API versions carry them on the
+subscription item, older ones on the subscription — and they are Unix
+**seconds**, so multiply by 1000 once.
+
+## 5. Members-only content is a grant the backend writes
+
+Members-only content is a grant the backend writes from Stripe's subscription, never a flag a browser sets.
+
+**Memberships and the posts they unlock live in one database.** Grants are
+reduced per database — a channel granted by a record in one database opens
+nothing in another — so the `club` database holds both the `membership`
+records and the `post` records, and one access function handles both types.
+A members-only feed built with its posts in a second database would grant a
+paying member a channel that no post is on.
+
+The access state is the union of every current document's grants, so the
+membership document is where entitlement becomes structural: when
+`doc.entitled` is true the access function grants the member the `members`
+channel, and when the backend rewrites the document with `entitled: false` the
+grant is gone on the next sync. Members-only posts route to `members`, nothing
+reads them without the grant, and a browser can neither set `entitled` nor
+move `status`, because every update of an existing membership requires
+`ctx.requireBackend()`. The page gates its "members only" view on the live
+membership record and on `can.*` for anything it writes; the server enforces
+the same rule whatever the page shows.
+
+## 6. Two things keep the mirror true: the return, and the sweep
+
+Both are the backend reading Stripe with the key.
+
+- **The return.** When the app opens with `#subscribed=<id>` in its address,
+  the page calls `/confirm`; the route reads the Checkout Session back, takes
+  its `subscription` and `customer` ids, reads the subscription, and writes
+  status, period end, `cancel_at_period_end` and `entitled` onto the
+  membership. Read the hash on mount **and** on `hashchange`: the wrapper hands
+  the app its fragment just after first render.
+
+A scheduled sweep refreshes every live subscription from Stripe, so a failed renewal or a cancellation reaches the app without a webhook.
+
+- **The sweep.** Every half hour `scheduled` reads each membership whose
+  subscription is not in a terminal state, re-reads it from Stripe, recomputes
+  `entitled`, and writes the document when anything changed — including when
+  nothing at Stripe changed but the grace period ran out. A pending membership
+  whose session was never completed is settled the same way as the one-time
+  recipe's orders: expired after a day. The work is bounded by the number of
+  members.
+
+Why not a webhook: a webhook write arrives with no identity and would need
+`allowAnonymous` on the one record that grants access. Reading the
+subscription back with the key the app already holds is the same proof from
+the same source, on a route that can only write what Stripe reports.
+
+## 7. Cancel, change a card, see invoices: the Customer Portal
+
+Cancelling and changing a card happen in Stripe's Customer Portal, opened from a backend-minted billing_portal session, never in a form the app writes itself.
+
+`/portal` runs as the signed-in member, reads their record, and `POST`s
+`/v1/billing_portal/sessions` with `customer` and a `return_url` of the app's
+address; the page opens the returned `url` in a new tab. The portal handles
+cancel-at-period-end, card changes, invoices and receipts, and the next sweep
+or the member's return (`#portal` in the fragment calls `/refresh`) brings the
+new state home. The app never writes `status: "canceled"` itself, in the page
+or in a route: a Cancel button in the app is a link to the portal. The portal
+button shows whenever Stripe knows the member (the record carries a
+`customerId`), entitled or not — a lapsed member needs it most, to update the
+card or to cancel. A visitor who is not signed in gets a `Sign in to join`
+button wired to `useViewer().requestLogin()`, never a Join button that fails
+with a sign-in error.
+
+## 8. Errors keep their reason
+
+Stripe's refusals come back as JSON with `error.message`; return it as
+`{ ok: false, reason: "stripe", message }` so the page can show the owner
+*why*. The portal's "No configuration provided" message is the one that means
+step 3 of setup was skipped. A refused `ctx.fetch` — the
+`{ vibesEgressDenied: true }` shape — is a platform refusal; log it and answer
+`{ ok: false, reason: "unavailable" }`. `api.stripe.com` is CORS-open to the
+app's origin, so nothing here needs the curated list.
+
+## Complete backend.js
+
+### `backend.js`
+```js app=stripe-membership
+// A paid membership that mirrors Stripe: hosted Checkout in subscription mode, entitlement
+// recomputed from the subscription's status, members-only access as a grant the backend writes.
+// ONE database holds the memberships and the posts they unlock: grants are reduced per database,
+// so a channel granted in one database opens nothing in another.
+export const config = {
+  scheduled: { interval: "30m" },
+  // The routes read the member's own record; access.js binds the database, so the fetch lane needs
+  // this declaration, and every route owes the check it waives: it reads membership-<caller> only.
+  fetch: { unfilteredReads: { dbs: ["club"], why: "the /subscribe, /confirm, /refresh and /portal routes read the signed-in member's own membership record, membership-<their handle>, and nothing else" } },
+};
+
+const STRIPE = "https://api.stripe.com/v1";
+const DB = "club";
+const SESSION_TTL_MS = 24 * 60 * 60 * 1000;
+// The one knob: how long a past_due member stays in while Stripe retries the card. Zero locks
+// the moment a renewal fails.
+const GRACE_DAYS = 5;
+const PLANS = {
+  monthly: { title: "Club membership (monthly)", amount: 500, currency: "usd", interval: "month" },
+  yearly: { title: "Club membership (yearly)", amount: 5000, currency: "usd", interval: "year" },
+};
+// Nothing at Stripe will change these again; everything else is live and re-read.
+const TERMINAL = new Set(["canceled", "incomplete_expired"]);
+
+function json(body, status = 200) {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+}
+
+function appUrl(ctx, hash) {
+  return `https://vibes.diy/vibe/${ctx.appInfo.ownerHandle}/${ctx.appInfo.appSlug}${hash}`;
+}
+
+// One record per member, named for them: every attempt, renewal and lapse rewrites it in place.
+function membershipId(handle) {
+  return `membership-${handle}`;
+}
+
+async function stripe(ctx, method, path, form, headers = {}) {
+  const key = ctx.secrets.STRIPE_SECRET_KEY;
+  if (!key) return { ok: false, reason: "missing-key" };
+  const res = await ctx.fetch(`${STRIPE}${path}`, {
+    method,
+    headers: { authorization: `Bearer ${key}`, ...(form ? { "content-type": "application/x-www-form-urlencoded" } : {}), ...headers },
+    body: form ? form.toString() : undefined,
+  });
+  const body = await res.json().catch(() => null);
+  if (!res.ok) {
+    if (body?.vibesEgressDenied) {
+      ctx.log("warn", "stripe egress denied", { gate: body.gate });
+      return { ok: false, reason: "unavailable" };
+    }
+    return { ok: false, reason: "stripe", message: body?.error?.message ?? `HTTP ${res.status}` };
+  }
+  return { ok: true, body };
+}
+
+// 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) {
+  const item = sub.items?.data?.[0];
+  const periodStart = (sub.current_period_start ?? item?.current_period_start ?? 0) * 1000;
+  const periodEnd = (sub.current_period_end ?? item?.current_period_end ?? 0) * 1000;
+  return { status: sub.status, currentPeriodStart: periodStart, currentPeriodEnd: periodEnd, cancelAtPeriodEnd: sub.cancel_at_period_end === true, customerId: sub.customer };
+}
+
+// The entitlement rule, stated once. active/trialing in; past_due in until the grace period after
+// the failed renewal — the START of the current period, which Stripe opens when it invoices the
+// renewal, not its end, which is an interval away; everything else out.
+function isEntitled(m, now = Date.now()) {
+  if (m.status === "active" || m.status === "trialing") return true;
+  if (m.status === "past_due") return now < m.currentPeriodStart + GRACE_DAYS * 24 * 60 * 60 * 1000;
+  return false;
+}
+
+// Re-read the member's subscription and write the record back when anything the app keeps
+// changed — including entitlement lapsing with nothing new at Stripe.
+async function refresh(ctx, m) {
+  if (!m.subscriptionId) return m;
+  const sub = await stripe(ctx, "GET", `/subscriptions/${m.subscriptionId}`);
+  if (!sub.ok) return m; // a refusal changes nothing; the next read tries again
+  const next = { ...m, ...mirror(sub.body), syncedAt: Date.now() };
+  next.entitled = isEntitled(next);
+  const changed = ["status", "currentPeriodStart", "currentPeriodEnd", "cancelAtPeriodEnd", "entitled"].some((k) => next[k] !== m[k]);
+  if (!changed) return m;
+  await ctx.db.put(next, { db: DB, id: m._id, ifRev: m._rev });
+  return next;
+}
+
+// A record still waiting on its Checkout Session: bind the subscription Stripe created, or expire
+// the attempt after a day.
+async function settlePending(ctx, m) {
+  if (m.status !== "pending") return m;
+  if (!m.sessionId) {
+    if (Date.now() - m.sessionCreatedAt > SESSION_TTL_MS) {
+      const expired = { ...m, status: "expired", entitled: false };
+      await ctx.db.put(expired, { db: DB, id: m._id, ifRev: m._rev });
+      return expired;
+    }
+    return m;
+  }
+  const session = await stripe(ctx, "GET", `/checkout/sessions/${m.sessionId}`);
+  if (!session.ok) return m;
+  const s = session.body;
+  if (s.id !== m.sessionId || s.client_reference_id !== m._id) {
+    ctx.log("warn", "stripe session does not match its membership", { membershipId: m._id });
+    return m;
+  }
+  if (s.status === "expired") {
+    const expired = { ...m, status: "expired", entitled: false };
+    await ctx.db.put(expired, { db: DB, id: m._id, ifRev: m._rev });
+    return expired;
+  }
+  if (!s.subscription) return m; // not completed yet
+  const bound = { ...m, subscriptionId: s.subscription, customerId: s.customer };
+  await ctx.db.put(bound, { db: DB, id: m._id, ifRev: m._rev });
+  return refresh(ctx, await ctx.db.get(m._id, { db: DB }));
+}
+
+export async function fetch(request, ctx) {
+  const url = new URL(request.url);
+  const me = ctx.userInfo?.userHandle;
+
+  if (url.pathname === "/status" && request.method === "GET") {
+    return json({ ok: true, configured: Boolean(ctx.secrets.STRIPE_SECRET_KEY), owner: me === ctx.appInfo.ownerHandle, graceDays: GRACE_DAYS });
+  }
+
+  if (!me) return json({ ok: false, reason: "sign-in" }, 401);
+  const id = membershipId(me);
+  const current = await ctx.db.get(id, { db: DB }); // null before the first attempt
+
+  if (url.pathname === "/subscribe" && request.method === "POST") {
+    if (!ctx.secrets.STRIPE_SECRET_KEY) return json({ ok: false, reason: "missing-key" }, 503);
+    const { plan } = await request.json();
+    const price = PLANS[plan];
+    if (!price) return json({ ok: false, reason: "unknown-plan" }, 400);
+    // A subscription that is live at Stripe — entitled or not — is managed in the portal, never
+    // doubled: a past_due member whose grace ran out still has a subscription Stripe is retrying.
+    if (current?.subscriptionId && !TERMINAL.has(current.status)) return json({ ok: false, reason: "already-member" }, 409);
+    // A second press, a retry, another tab: the open attempt is reused, never repeated.
+    if (current?.status === "pending" && current.sessionUrl && Date.now() - current.sessionCreatedAt < SESSION_TTL_MS) {
+      return json({ ok: true, url: current.sessionUrl });
+    }
+
+    const attempt = (current?.attempt ?? 0) + 1;
+    const membership = {
+      _id: id,
+      type: "membership",
+      memberHandle: me,
+      plan,
+      amount: price.amount,
+      currency: price.currency,
+      status: "pending",
+      entitled: false,
+      attempt,
+      customerId: current?.customerId, // a returning member keeps their Stripe customer
+      sessionId: undefined,
+      sessionUrl: undefined,
+      subscriptionId: undefined,
+      createdAt: current?.createdAt ?? Date.now(),
+      sessionCreatedAt: Date.now(),
+    };
+    // The record is claimed against the revision we read: a concurrent press conflicts here and
+    // is handed the attempt that won instead of starting its own.
+    try {
+      await ctx.db.put(membership, { db: DB, id, ifRev: current?._rev });
+    } catch (err) {
+      if (err.code !== "conflict") throw err;
+      const won = await ctx.db.get(id, { db: DB });
+      return won?.sessionUrl ? json({ ok: true, url: won.sessionUrl }) : json({ ok: false, reason: "retry" }, 409);
+    }
+
+    const form = new URLSearchParams({
+      mode: "subscription",
+      "line_items[0][quantity]": "1",
+      "line_items[0][price_data][currency]": price.currency,
+      "line_items[0][price_data][unit_amount]": String(price.amount),
+      "line_items[0][price_data][recurring][interval]": price.interval,
+      "line_items[0][price_data][product_data][name]": price.title,
+      client_reference_id: id,
+      "metadata[attempt]": String(attempt),
+      success_url: appUrl(ctx, "#subscribed"),
+      cancel_url: appUrl(ctx, "#cancelled"),
+    });
+    // The idempotency key names the attempt, so two first presses that both got past the claim
+    // (a record that does not exist yet has no revision to claim) mint ONE session at Stripe.
+    const session = await stripe(ctx, "POST", "/checkout/sessions", form, { "idempotency-key": `${id}:${attempt}` });
+    if (!session.ok) return json(session, session.reason === "stripe" ? 502 : 503);
+    const claimed = await ctx.db.get(id, { db: DB });
+    await ctx.db.put({ ...claimed, sessionId: session.body.id, sessionUrl: session.body.url }, { db: DB, id, ifRev: claimed._rev });
+    return json({ ok: true, url: session.body.url });
+  }
+
+  // Back from Checkout: bind the subscription and mirror it.
+  if (url.pathname === "/confirm" && request.method === "POST") {
+    if (!current) return json({ ok: false, reason: "not-found" }, 404);
+    const settled = await settlePending(ctx, current);
+    return json({ ok: true, status: settled.status, entitled: settled.entitled === true });
+  }
+
+  // Back from the portal, or a "check again": re-read my subscription now.
+  if (url.pathname === "/refresh" && request.method === "POST") {
+    if (!current?.subscriptionId) return json({ ok: true, entitled: false });
+    const next = await refresh(ctx, current);
+    return json({ ok: true, status: next.status, entitled: next.entitled === true });
+  }
+
+  // Cancel, change a card, see invoices: Stripe's own portal, for this member's customer.
+  if (url.pathname === "/portal" && request.method === "POST") {
+    if (!current?.customerId) return json({ ok: false, reason: "no-membership" }, 404);
+    const form = new URLSearchParams({ customer: current.customerId, return_url: appUrl(ctx, "#portal") });
+    const portal = await stripe(ctx, "POST", "/billing_portal/sessions", form);
+    if (!portal.ok) return json(portal, portal.reason === "stripe" ? 502 : 503);
+    return json({ ok: true, url: portal.body.url });
+  }
+
+  return json({ ok: false, reason: "not-found" }, 404);
+}
+
+// The sweep: every live subscription re-read, entitlement recomputed, pending attempts settled.
+export async function scheduled(event, ctx) {
+  if (!ctx.secrets.STRIPE_SECRET_KEY) return;
+  let after;
+  let changed = 0;
+  do {
+    const page = await ctx.db.query({ db: DB, field: "type", key: "membership", limit: 100, after });
+    for (const m of page) {
+      if (TERMINAL.has(m.status) || m.status === "expired") continue;
+      const next = m.status === "pending" ? await settlePending(ctx, m) : await refresh(ctx, m);
+      if (next !== m) changed += 1;
+    }
+    after = page.next;
+  } while (after);
+  ctx.log("info", "stripe subscription sweep", { changed, at: event.scheduledTime });
+}
+```
+
+## access.js — the grant follows the record
+
+### `access.js`
+```js app=stripe-membership
+// One function for the one database: the membership record that carries the grant, and the posts
+// the grant unlocks. Grants are reduced per database, so these two types have to share one.
+export function club(doc, oldDoc, user, ctx) {
+  if (!user?.userHandle) throw { forbidden: "sign in" };
+  if (oldDoc && oldDoc.type !== doc.type) throw { forbidden: "a record keeps its type" };
+
+  // One membership record per member, named for them, written only by backend.js.
+  if (doc.type === "membership") {
+    if (doc._id !== `membership-${doc.memberHandle}`) throw { forbidden: "a membership is named for its member" };
+    if (oldDoc) {
+      // Only backend.js changes an existing membership — claiming an attempt, binding the session,
+      // mirroring Stripe, recomputing entitlement — so neither status nor entitled is a member's to edit.
+      ctx.requireBackend();
+      if (doc.memberHandle !== oldDoc.memberHandle) throw { forbidden: "a membership keeps its member" };
+    } else {
+      if (doc.memberHandle !== user.userHandle) throw { forbidden: "a membership belongs to its member" };
+      if (doc.status !== "pending" || doc.entitled) throw { forbidden: "a membership starts pending" };
+      ctx.requireBackend("fetch"); // the /subscribe route writes it, so the amount is the server's
+    }
+    const mine = `user:${doc.memberHandle}`;
+    // The grant IS the entitlement: while the backend says entitled, the member holds `members`;
+    // the rewrite that says otherwise takes it away on the next sync.
+    const granted = doc.entitled === true ? [mine, "members"] : [mine];
+    return { channels: [mine, "memberships"], grant: { users: { [doc.memberHandle]: granted }, roles: { owner: ["memberships", "members"] } } };
+  }
+
+  // A post: the owner writes it; members read it on the channel their membership record grants.
+  if (doc.type === "post") {
+    if (oldDoc && doc.authorHandle !== oldDoc.authorHandle) throw { forbidden: "a post keeps its author" };
+    ctx.requireRole("owner");
+    return { channels: [doc.membersOnly ? "members" : "public"], grant: { public: ["public"] } };
+  }
+
+  throw { forbidden: "unknown document type" };
+}
+```
+
+## App.jsx sketch
+
+### `App.jsx`
+```jsx app=stripe-membership
+import React, { useEffect, useState } from "react";
+import { useFireproof } from "use-fireproof";
+import { apiFetch, useViewer } from "use-vibes";
+import { Badge, Button, Heading, Stack, Text } from "@vibes.diy/pouf";
+
+const SETUP_STEPS = [
+  "Open the Stripe dashboard, turn on Test mode, and reveal the Secret key under Developers → API keys.",
+  "Set it on this vibe as STRIPE_SECRET_KEY: the Settings page, or `vibes-diy secrets set STRIPE_SECRET_KEY`.",
+  "Under Settings → Billing → Customer portal, save the portal with Cancel at end of billing period on.",
+];
+
+export default function App() {
+  const { viewer, requestLogin } = useViewer();
+  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 [busy, setBusy] = useState(false);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    apiFetch("/status").then((r) => r.json()).then(setStatus).catch(() => setStatus({ configured: false, owner: false }));
+  }, []);
+
+  // Back from Stripe: the fragment arrives just after first render and on hashchange, so read both.
+  useEffect(() => {
+    const settle = () => {
+      const subscribed = /#subscribed\b/.test(location.hash);
+      const portal = /#portal\b/.test(location.hash);
+      if (!subscribed && !portal) return;
+      history.replaceState(null, "", location.pathname);
+      apiFetch(subscribed ? "/confirm" : "/refresh", { method: "POST", headers: { "content-type": "application/json" }, body: "{}" });
+    };
+    settle();
+    window.addEventListener("hashchange", settle);
+    return () => window.removeEventListener("hashchange", settle);
+  }, []);
+
+  // Open a Stripe page in a new tab: the tab first, inside the click, then the backend for its URL.
+  const openStripe = async (path, body) => {
+    setError(null);
+    const tab = window.open("", "_blank");
+    if (!tab) {
+      setError("Your browser blocked the Stripe tab. Allow pop-ups for this page and try again.");
+      return;
+    }
+    setBusy(true);
+    try {
+      const res = await apiFetch(path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+      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.");
+        return;
+      }
+      tab.location.href = data.url;
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  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>
+        <ol>{SETUP_STEPS.map((s) => <li key={s}>{s}</li>)}</ol>
+      </Stack>
+    );
+  }
+
+  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>
+      ) : (
+        <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>
+          ) : (
+            <Button onClick={() => openStripe("/subscribe", { plan: "monthly" })} disabled={!configured || busy} loading={busy}>
+              Join — Stripe opens in a new tab
+            </Button>
+          )}
+        </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>
+  );
+}
+```
+
+The posts list shows only what the viewer can read: a member sees the
+members-only posts because the grant on their membership record admits them to the
+`members` channel, and a lapsed member sees the public ones and the Join
+button. The owner's roster at the bottom is the app's mirror of Stripe; the
+two agree because the app only ever copies Stripe's answer.

package/llms/stripe.d.ts

@@ -0,0 +1,2 @@
+import type { LlmConfig } from "./types.js";
+export declare const stripeConfig: LlmConfig;

package/llms/stripe.js

@@ -0,0 +1,21 @@
+export const stripeConfig = {
+    name: "stripe",
+    label: "Stripe payments",
+    description: "Taking real money through Stripe Checkout, ONLY when the person asks to charge, sell, take a deposit, collect dues or sell tickets — one-time charges on the owner's own STRIPE_SECRET_KEY (a monthly or yearly subscription is the stripe-subscriptions skill): the setup steps the app shows when the key is missing, the key kept in backend.js with no Stripe.js in the page, one pending order then one Checkout Session opened in a new tab, an order marked paid only after the backend reads the session back from Stripe and matches it to the order, integer amounts in cents, and a scheduled sweep that settles orders whose buyer never came back. A storefront, plans page or booking page that only records orders takes no payment and does not need this; offer it as the [pay] option instead",
+    cues: [
+        "stripe",
+        "take payments",
+        "take payment",
+        "accept payments",
+        "pay with card",
+        "card payment",
+        "credit card",
+        "checkout",
+        "deposit",
+        "dues",
+        "sell tickets",
+        "charge",
+        "paywall",
+    ],
+};
+//# sourceMappingURL=stripe.js.map

package/llms/stripe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripe.js","sourceRoot":"","sources":["../../jsr/llms/stripe.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,YAAY,GAAc;IACrC,IAAI,EAAE,QAAQ;IACd,KAAK,EAAE,iBAAiB;IACxB,WAAW,EACT,ixBAAixB;IACnxB,IAAI,EAAE;QACJ,QAAQ;QACR,eAAe;QACf,cAAc;QACd,iBAAiB;QACjB,eAAe;QACf,cAAc;QACd,aAAa;QACb,UAAU;QACV,SAAS;QACT,MAAM;QACN,cAAc;QACd,QAAQ;QACR,SAAS;KACV;CACF,CAAC"}