@ssheleg/sheleg-dev 0.4.0

package/plugins/sheleg-dev/skills/stripe-billing/references/stripe-agent-toolchain.md

@@ -0,0 +1,173 @@
+# Stripe's own agent toolchain
+
+**Load this when** starting a Stripe integration from nothing, or when the
+agent is about to guess an API shape, a parameter name or a current best
+practice. Stripe ships tooling built for agents; using it is faster and more
+accurate than recalling the API from training data.
+
+*Read from `docs.stripe.com/agents`, `/skills`, `/mcp` and the CLI's own
+`--help` on 2026-08-11, against Stripe CLI 1.45.2 and the Claude Code plugin
+`stripe@claude-plugins-official` 0.5.1. Re-check before quoting a version.*
+
+## Contents
+
+- [The four pieces](#the-four-pieces)
+- [CLI](#cli)
+- [Getting keys without an account](#getting-keys-without-an-account)
+- [Skills and plugins](#skills-and-plugins)
+- [MCP server](#mcp-server)
+- [Plain-text documentation](#plain-text-documentation)
+- [Key handling for agents](#key-handling-for-agents)
+- [When none of it is available](#when-none-of-it-is-available)
+
+## The four pieces
+
+| Piece | What it gives an agent | Entry point |
+|---|---|---|
+| **CLI** | resource discovery, webhook forwarding, event triggers, logs, sandboxes | `npm install -g @stripe/cli` |
+| **Skills / plugin** | Stripe's own instructions: product choice, billing, tax, security, Connect | `stripe agent setup` |
+| **MCP server** | live calls against the account, doc search, an implementation planner | `https://mcp.stripe.com` |
+| **Plain-text docs** | any page as Markdown | append `.md` to a `docs.stripe.com` URL |
+
+## CLI
+
+```bash
+npm install -g @stripe/cli          # v1.43.3+ for `stripe docs`
+stripe login                        # browser consent — a human step
+stripe agent setup                  # detects Claude Code / Codex / Cursor, installs plugins
+stripe agent setup --status --json  # read-only: what is already installed
+```
+
+Discovery commands worth knowing before writing any call — they answer from the
+installed CLI rather than from memory:
+
+```bash
+stripe --map                        # the whole command tree
+stripe resources                    # every API resource
+stripe <resource> --help            # operations and common parameters
+stripe help <resource> <operation>  # the full parameter list
+stripe docs                         # read docs.stripe.com in the terminal
+```
+
+Development loop:
+
+```bash
+stripe listen --forward-to localhost:3000/api/billing/webhook
+stripe trigger checkout.session.completed
+stripe logs tail                    # watch API requests, including 403s from a restricted key
+```
+
+## Getting keys without an account
+
+```bash
+stripe sandbox create --from-git    # resolves the email from git config
+stripe sandbox create --email you@example.com
+```
+
+Provisions a sandbox through a proof-of-work challenge — **no browser, no
+signup** — and writes the test keys into the current CLI profile, so subsequent
+commands work immediately. Falls back to browser login on server errors. If a
+key is already configured, the same command opens the sandbox management page
+instead.
+
+This is the honest answer to "I want to try the integration before I have an
+account", and it is far better than inventing placeholder ids.
+
+## Skills and plugins
+
+`stripe agent setup` installs the official plugin for each detected harness. The
+per-harness commands, if you prefer them explicit:
+
+```bash
+claude plugin install stripe@claude-plugins-official   # Claude Code
+codex plugin add stripe@openai-curated                 # Codex
+# Cursor: run /add-plugin stripe inside the agent
+npx skills add https://docs.stripe.com                 # any other agent — manual, no auto-update
+```
+
+Manually installed skills do not auto-update: `npx skills update -y`.
+
+The machine-readable index is
+`https://docs.stripe.com/.well-known/skills/index.json`; individual files sit
+under `https://docs.stripe.com/.well-known/skills/<filepath>`. Seven skills at
+the time of writing: `stripe-best-practices`, `stripe-docs`, `stripe-apps`,
+`stripe-projects`, `stripe-directory`, `connect-recommend`, `upgrade-stripe`.
+
+**Division of labour with this skill.** `stripe-best-practices` decides *which
+Stripe primitive* and states Stripe's own rules (product catalogue modelling,
+tax, dynamic payment methods, Metronome for new usage-based billing, key
+hygiene). `stripe-docs` looks things up. This skill covers what happens on
+*your* side of the boundary — reconciling Stripe's state into your database.
+When they disagree about anything Stripe-side, Stripe's skill wins.
+
+## MCP server
+
+```bash
+claude mcp add --transport http stripe https://mcp.stripe.com/
+claude /mcp                         # OAuth consent — a human step
+```
+
+Other clients take `{"url": "https://mcp.stripe.com"}` (Cursor `~/.cursor/mcp.json`,
+VS Code `.vscode/mcp.json` with `"type": "http"`). Clients without OAuth may
+send a **restricted** key as `Authorization: Bearer rk_…`; connected-account
+calls add a `Stripe-Account: acct_…` header.
+
+Tools worth reaching for by name:
+
+| Tool | Use |
+|---|---|
+| `stripe_implementation_planner` | a tailored integration plan before any code |
+| `search_stripe_documentation` | current docs, in preference to a web search |
+| `stripe_api_search` / `stripe_api_details` | find a method, then read its exact parameters |
+| `stripe_api_read` / `stripe_api_write` | call the API without a per-endpoint tool |
+| `create_refund`, `get_stripe_account_info`, `stripe_report` | the dedicated ones |
+
+Two cautions from Stripe's own page, both worth honouring: **enable human
+confirmation for tool calls**, and be careful combining this server with other
+MCP servers — tool output is untrusted input and prompt injection is the
+documented risk. OAuth sessions are listed and revocable in Dashboard user
+settings; administrators can revoke other users' sessions and enable or disable
+MCP access per environment.
+
+## Plain-text documentation
+
+Append `.md` to any documentation URL:
+
+```
+https://docs.stripe.com/billing/subscriptions/webhooks.md
+https://docs.stripe.com/api/subscriptions/update.md
+```
+
+Cheaper and cleaner than fetching the rendered page, and it is the same content
+`stripe docs` reads in the terminal.
+
+## Key handling for agents
+
+Stripe's security reference is blunt about this, and it applies doubly to code
+an agent writes:
+
+- Prefer **restricted keys** (`rk_`) over secret keys (`sk_`), one per service,
+  minimum permissions. Migrate by watching `stripe logs tail` and adding
+  permissions until the 403s stop.
+- Keys live in a **secrets vault** where the platform has one (AWS Secrets
+  Manager, GCP Secret Manager, Azure Key Vault); environment variables are the
+  fallback, not the goal. On Vercel, mark them sensitive.
+- Never in source, never in logs, never in error messages, never in client-side
+  code. `sk_live_…` or `rk_live_…` in a repository is an incident, not a lint
+  warning — a pre-commit hook for `sk_`/`rk_` is cheap.
+- Separate keys per environment, and rotate when someone with access leaves.
+
+## When none of it is available
+
+The toolchain is an accelerator, not a dependency. With no CLI, no MCP and no
+network:
+
+- write the integration from the invariants in `SKILL.md` — they are the part
+  that does not change between API versions;
+- pin the API version the installed SDK ships with, and say in a comment that
+  it was not verified against the changelog;
+- use the SDK's own type definitions as the parameter reference (they are
+  generated from the same spec the docs are);
+- state plainly which facts could not be verified, rather than asserting a
+  parameter name you recall. A wrong parameter fails loudly; a wrong *default*
+  bills someone.

package/plugins/sheleg-dev/skills/stripe-billing/references/subscription-lifecycle.md

@@ -0,0 +1,294 @@
+# Subscription lifecycle — code for each stage
+
+**Load this when** implementing checkout, the verify fallback, renewal grants,
+seat or plan changes, cancellation, or refund clawback. Every snippet is the
+shape that survived production; the reasoning for each is in `SKILL.md`.
+
+## Contents
+
+- [Data model](#data-model)
+- [Creating the checkout session](#creating-the-checkout-session)
+- [The verify fallback](#the-verify-fallback)
+- [Granting on renewal](#granting-on-renewal)
+- [Seat and quantity changes](#seat-and-quantity-changes)
+- [Plan changes](#plan-changes)
+- [Trials](#trials)
+- [Cancellation and reactivation](#cancellation-and-reactivation)
+- [The customer portal](#the-customer-portal)
+- [Refund clawback](#refund-clawback)
+- [Reconciliation job](#reconciliation-job)
+- [Non-Stripe subscriptions](#non-stripe-subscriptions)
+
+## Data model
+
+The minimum that makes every later question answerable:
+
+| Column | Note |
+|---|---|
+| `stripeSubscriptionId` | **unique** — this constraint is your idempotency |
+| `stripeSubscriptionItemId` | needed for every quantity update and usage report |
+| `stripePriceId`, `stripeProductId` | what they are on, denormalised for queries |
+| `status` | your own enum, mapped from Stripe's — never Stripe's string raw |
+| `currentPeriodStart`, `currentPeriodEnd` | from the **item**, not the subscription |
+| `cancelAtPeriodEnd` | drives the UI; distinct from `status` |
+| `quantity` | seats; 1 for flat plans |
+| `pricingType` | `flat` \| `tiered` \| `metered` — decides which paths apply |
+| `lastGrantedPeriodStart` | the double-grant guard |
+| `paymentSource` | `stripe` \| something else; the reconciliation job reads it |
+
+Map status once, in one function, and log the unknown case rather than
+defaulting silently:
+
+```ts
+const MAP: Record<string, Status> = {
+  active: "active", trialing: "trialing", past_due: "past_due",
+  unpaid: "unpaid", canceled: "canceled", incomplete: "incomplete",
+  incomplete_expired: "canceled", paused: "canceled",
+};
+export function mapStatus(s: string): Status {
+  const m = MAP[s];
+  if (!m) log.warn("unknown Stripe subscription status", { s });
+  return m ?? "incomplete";
+}
+```
+
+## Creating the checkout session
+
+```ts
+const metadata = { userId, productId, quantity: String(quantity) };
+
+const session = await stripe.checkout.sessions.create({
+  customer: customerId,
+  mode: "subscription",
+  line_items: [{ price: priceId, quantity }],
+  // Do NOT pass payment_method_types — Stripe picks eligible methods from
+  // Dashboard settings, and hardcoding ['card'] costs conversion.
+  metadata,
+  subscription_data: { metadata },
+  success_url: `${origin}/onboarding?session_id={CHECKOUT_SESSION_ID}`,
+  cancel_url: `${origin}/pricing`,
+});
+```
+
+Before that call, in order:
+
+1. authenticate, and check the account is in a state allowed to transact
+   (blocked, deletion-scheduled and delinquent accounts should not reach Stripe);
+2. rate-limit per user — this endpoint creates objects in someone else's system;
+3. validate `productId` against an allowlist; reject anything else with 400;
+4. clamp quantity server-side (`Math.floor`, min 1, a hard max);
+5. refuse a duplicate: an active subscription to the same product answers 409
+   with the existing id, not a second checkout;
+6. validate any caller-supplied `successUrl`/`cancelUrl` against your own
+   origin, and fall back to the default on mismatch.
+
+## The verify fallback
+
+The success page calls this; it is also how local development works at all.
+
+```ts
+const s = await stripe.checkout.sessions.retrieve(sessionId);
+
+if (s.metadata?.userId !== callerId) return json({ error: "not yours" }, 403);
+if (s.status !== "complete")          return json({ error: "not complete" }, 400);
+if (s.payment_status === "unpaid")    return json({ error: "not paid" }, 402);
+
+const existing = await db.subscription.findUnique({ where: { stripeSubscriptionId } });
+if (existing) return json({ subscription: existing, created: false });
+
+try {
+  const created = await grantExactlyAsTheWebhookWould();
+  return json({ subscription: created, created: true });
+} catch (err) {
+  if (isUniqueViolation(err)) {                    // the webhook won the race
+    return json({ subscription: await reread(), created: false });
+  }
+  throw err;
+}
+```
+
+The ownership check is the security-critical line: without it, any authenticated
+user who learns a `cs_…` id claims someone else's purchase. Rate-limit it too —
+it costs an API call per request.
+
+While the race is open, render a "confirming your payment" state. Sending the
+user back to the plan chooser shows a paywall to somebody who just paid.
+
+## Granting on renewal
+
+```ts
+if (invoice.billing_reason !== "subscription_cycle") return;   // see webhook-events.md
+
+await db.$transaction(async (tx) => {
+  const sub = await tx.subscription.findUnique({ where: { id }, select: { lastGrantedPeriodStart: true } });
+  if (sub?.lastGrantedPeriodStart && sub.lastGrantedPeriodStart >= periodStart) return;  // replay
+
+  await tx.subscription.update({ where: { id }, data: { lastGrantedPeriodStart: periodStart } });
+  await tx.wallet.update({ where: { userId }, data: { credit: { increment: allowance } } });
+  await tx.auditLog.create({ data: { userId, action: "grant", amount: allowance,
+    source: "subscription-renewal", metadata: { invoiceId: invoice.id } } });
+});
+```
+
+Marker and grant in **one** transaction. Two statements outside a transaction is
+the same bug as read-then-write, one level up.
+
+## Seat and quantity changes
+
+```ts
+const item = (await stripe.subscriptions.retrieve(subId)).items.data[0];
+
+try {
+  await stripe.subscriptions.update(subId, {
+    items: [{ id: item.id, quantity: newQuantity }],
+    proration_behavior: "always_invoice",
+    payment_behavior: "error_if_incomplete",     // upgrades only
+  });
+} catch (err) {
+  if (err.type === "StripeCardError" || err.code === "invoice_payment_intent_requires_action") {
+    return json({ error: "payment failed", code: "payment_failed" }, 402);
+  }
+  throw err;
+}
+
+try {
+  await db.subscription.update({ where: { id }, data: { quantity: newQuantity } });
+} catch (dbErr) {
+  await stripe.subscriptions.update(subId, {                  // compensating revert
+    items: [{ id: item.id, quantity: oldQuantity }],
+    proration_behavior: "none",                               // do not re-bill the revert
+  }).catch((e) => log.error("CRITICAL: revert failed, Stripe and DB disagree", { subId, e }));
+  throw dbErr;
+}
+```
+
+- **Downgrades** need no `payment_behavior`; they produce a credit.
+- **Reducing below what is in use** is a business decision, not an API call.
+  Answer 409 with the list of things that must be released first, and let the
+  user choose which — picking for them deletes the wrong one.
+- **`preview` before charging.** A separate read-only action that quotes the
+  prorated amount (`stripe.invoices.createPreview`) turns "why was I charged
+  $17.43" into a number the user already agreed to.
+- Do not add seats to a subscription flagged `cancel_at_period_end` — reactivate
+  first, or the seats vanish at period end.
+
+## Plan changes
+
+Same shape as a quantity change, with `items: [{ id: item.id, price: newPriceId }]`.
+Two extra decisions:
+
+- **Immediate or at period end.** Immediate is `proration_behavior:
+  "always_invoice"`. At period end is a subscription schedule, not an update —
+  the difference is whether the customer is charged today.
+- **What happens to the current period's allowance.** Grant the difference
+  pro-rata for the remaining time, and write the marker so the next renewal does
+  not grant twice. Granting the full new allowance on an upgrade is a free month
+  for anyone who upgrades on the last day.
+
+## Trials
+
+`subscription_data: { trial_period_days: N }` on the session. A trialing
+subscription has `status: "trialing"` — entitlement logic must treat it as
+active or trials do not work, and `mapStatus` must not collapse it into
+`active` or you cannot tell them apart in reporting.
+
+`customer.subscription.trial_will_end` fires three days out. When the trial
+converts, `invoice.paid` arrives with `billing_reason: "subscription_cycle"`.
+
+## Cancellation and reactivation
+
+```ts
+await stripe.subscriptions.update(subId, { cancel_at_period_end: true });
+// local: cancelAtPeriodEnd = true, status stays "active"
+```
+
+If the local write fails after Stripe succeeded, say so honestly ("submitted,
+syncing shortly") and let reconciliation fix it. Reverting Stripe here would
+un-cancel a subscription the user asked to end.
+
+Reactivation is `cancel_at_period_end: false`, and is only meaningful while the
+period is still running. Past that, it is a new subscription.
+
+Immediate cancellation (`stripe.subscriptions.cancel`) is for refunds and abuse.
+Everything it must clean up belongs in the
+`customer.subscription.deleted` handler, not next to the API call.
+
+## The customer portal
+
+```ts
+const portal = await stripe.billingPortal.sessions.create({
+  customer: customerId,
+  return_url: `${origin}/billing?portal_return=true`,
+});
+```
+
+The portal is a second writer with no CSRF token and no notion of your database.
+Everything a user does there reaches you as a webhook, later. Two consequences:
+the billing page must refresh from the webhook-updated row on return, and any
+invariant you enforce in your own UI (seat minimums, plan eligibility) must be
+configured in the portal too, or it can be violated there.
+
+Users with no `stripeCustomerId` get a 400 with a plain message, not a crash.
+
+## Refund clawback
+
+```ts
+const totalRefunded = charge.amount_refunded / 100;
+const increment = totalRefunded - stored.refundedTotal;
+if (increment <= 0) return;
+
+const { count } = await db.purchase.updateMany({
+  where: { id: stored.id, refundedTotal: stored.refundedTotal },
+  data:  { refundedTotal: totalRefunded },
+});
+if (count === 0) return;                       // concurrent delivery won
+
+try {
+  await clawBack(stored.userId, increment);    // idempotent, keyed on charge id + total
+} catch (err) {
+  await db.purchase.update({ where: { id: stored.id },
+    data: { refundedTotal: stored.refundedTotal } });   // put the marker back
+  throw err;
+}
+```
+
+Clamp the deduction at zero. A user who already spent the credit goes to a
+negative balance or to a collections decision — pick one deliberately and log
+which. Silently deducting into negative is how a support ticket becomes a
+dispute.
+
+If you pay referral or affiliate commission on purchases, reverse it
+proportionally, computing the target from the **original** commission rather
+than the current balance — otherwise partial refunds compound.
+
+## Reconciliation job
+
+```ts
+for await (const sub of stripe.subscriptions.list({ customer, status: "all", limit: 100 })) {
+  // create / update / grant-if-period-advanced — sequential on purpose:
+  // each iteration opens a transaction and may call an external API.
+}
+for (const local of localRows) {
+  if (local.status === "canceled") continue;
+  if (seenInStripe.has(local.stripeSubscriptionId)) continue;
+  if (isNonStripeBacked(local)) continue;         // ← the guard that matters
+  await cancelLocally(local);
+}
+```
+
+Run it nightly per active customer, and expose it as a "Sync now" button. Any
+grant it performs must reuse the webhook's idempotency marker.
+
+## Non-Stripe subscriptions
+
+Comped accounts, manual invoices, crypto and app-store purchases all end up in
+the same table. Give them a `paymentSource` and synthetic ids with a recognisable
+prefix, and make every Stripe-facing path skip them explicitly:
+
+```ts
+const isDev     = (id: string) => id.startsWith("dev_sub_");
+const isNonStripe = (row) => row.paymentSource !== "stripe" || row.stripeSubscriptionId.startsWith("bal_sub_");
+```
+
+The reconciliation job is where this bites: without the guard it finds rows
+Stripe has never heard of and cancels every one of them.

package/plugins/sheleg-dev/skills/stripe-billing/references/testing-and-local-dev.md

@@ -0,0 +1,214 @@
+# Testing and local development
+
+**Load this when** setting up local webhooks, writing the first billing test, or
+deciding whether an existing suite would actually catch a money defect.
+
+## Contents
+
+- [Local webhooks](#local-webhooks)
+- [Triggering events](#triggering-events)
+- [The skip-billing branch](#the-skip-billing-branch)
+- [Test cards](#test-cards)
+- [What to mock](#what-to-mock)
+- [A webhook idempotency test](#a-webhook-idempotency-test)
+- [Mutation testing — the only proof that counts](#mutation-testing--the-only-proof-that-counts)
+- [Asserting on source](#asserting-on-source)
+- [Staging verification by hand](#staging-verification-by-hand)
+- [Production readiness](#production-readiness)
+
+## Local webhooks
+
+Stripe cannot reach `localhost`. Two ways in, and the first is better:
+
+```bash
+stripe listen --forward-to localhost:3000/api/billing/webhook
+# ⇒ prints "Ready! Your webhook signing secret is whsec_…"
+```
+
+That secret is **not** the one on the Dashboard endpoint. Using the Dashboard's
+value against forwarded events produces a signature failure on every delivery,
+which looks exactly like a code bug. Put the `stripe listen` value in the local
+env and nowhere else.
+
+Filter the firehose when debugging one flow:
+
+```bash
+stripe listen --events checkout.session.completed,invoice.paid \
+  --forward-to localhost:3000/api/billing/webhook
+```
+
+A public tunnel (`cloudflared tunnel --url http://localhost:3000`, `ngrok`) plus
+a real Dashboard endpoint is the other path. Use it when you need Stripe's own
+retry behaviour, or when the flow involves a hosted redirect back to a public
+URL.
+
+## Triggering events
+
+```bash
+stripe trigger checkout.session.completed
+stripe trigger invoice.payment_failed
+stripe trigger customer.subscription.deleted
+stripe trigger --help          # the full list of supported fixtures
+```
+
+`stripe trigger` creates real objects in test mode, which is its strength and
+its limit: the payload is Stripe's fixture, not yours, so `metadata.userId` is
+absent and a handler that requires it will bail. For the paths that depend on
+your own metadata, drive the handler directly from a saved payload (below).
+
+Re-delivery is the cheapest idempotency check you own: in the Dashboard, find a
+delivered event and press **Resend**. The balance must not move, and the log
+must say "duplicate".
+
+## The skip-billing branch
+
+```ts
+const SKIP_BILLING = process.env.SKIP_BILLING === "true";
+if (SKIP_BILLING) {
+  if (process.env.NODE_ENV === "production") throw new Error("SKIP_BILLING in production");
+  // create a local subscription with an obviously fake id
+}
+```
+
+- Assert at the **branch**, not only in configuration. A config file is one
+  merge away from being wrong; the throw is not.
+- Fake ids get a recognisable prefix (`dev_sub_…`) and a predicate
+  (`isDevSubscription`) that every Stripe-facing path consults. Without it,
+  cancel, portal and reconciliation all call Stripe with an id it has never
+  seen.
+- Provide the upgrade path: when billing is switched on for an account that
+  already holds a fake subscription, replace it with a real one in a transaction
+  rather than leaving two.
+
+## Test cards
+
+Full list: the official `stripe:test-cards` skill, or
+`docs.stripe.com/testing.md`. The four that matter for billing:
+
+| Card | Behaviour |
+|---|---|
+| `4242 4242 4242 4242` | succeeds |
+| `4000 0000 0000 0341` | attaches fine, **fails on the first charge** — the renewal path |
+| `4000 0000 0000 9995` | declined for insufficient funds — the upgrade 402 path |
+| `4000 0025 0000 3155` | requires 3DS authentication |
+
+The second one is the one people skip and the one that catches the most: it is
+how you see dunning, `past_due` and your own recovery messaging without waiting
+a month.
+
+Test clocks (`stripe.testHelpers.testClocks`) advance a customer through
+renewals, trial ends and dunning in seconds. They are the only honest way to
+test a yearly plan.
+
+## What to mock
+
+Mock at the **SDK boundary**, never at your own handler's. The point of these
+tests is that your handler does the right thing with a payload Stripe would
+actually send.
+
+```ts
+vi.mock("@/lib/stripe", () => ({
+  getStripe: () => ({
+    webhooks: { constructEvent: () => savedEventFixture },   // signature already verified
+    subscriptions: { retrieve: vi.fn().mockResolvedValue(savedSubscription) },
+  }),
+}));
+```
+
+Save real payloads: run the flow once against test mode, copy the event JSON out
+of the Dashboard, and commit it as a fixture. Hand-written payloads drift from
+reality in exactly the fields that matter — `parent.subscription_details`, the
+item-level period, `billing_reason`.
+
+Make the database mock **stateful** where the test is about state. An
+idempotency test against a mock that returns "not found" every time proves
+nothing:
+
+```ts
+const seen = new Set<string>();
+processedWebhookEvent: {
+  create: async ({ data }) => {
+    if (seen.has(data.id)) throw p2002();     // reproduce the unique constraint
+    seen.add(data.id); return data;
+  },
+}
+```
+
+## A webhook idempotency test
+
+```ts
+it("credits exactly once when the same event is delivered twice", async () => {
+  const req = () => new Request("http://x/api/billing/webhook", {
+    method: "POST", headers: { "stripe-signature": "t=1,v1=deadbeef" }, body: "{}",
+  });
+
+  const first  = await POST(req());
+  const second = await POST(req());
+
+  expect(await first.json()).toMatchObject({ received: true });
+  expect(await second.json()).toMatchObject({ duplicate: true });
+  expect(creditSpy).toHaveBeenCalledTimes(1);        // ← the assertion that matters
+});
+```
+
+Drive the **real** exported handler. A test that calls a private helper proves
+the helper works and says nothing about the route Stripe posts to.
+
+## Mutation testing — the only proof that counts
+
+For every guard, delete it and re-run. A test that still passes is decoration.
+
+| Delete this | A real test fails with |
+|---|---|
+| the ownership check in the verify route | "session does not belong to user" |
+| `if (billing_reason !== "subscription_cycle") return` | a grant on a proration invoice |
+| the claim-before-work call | two credits for one event |
+| `releaseEventClaim` in the catch | the retry finds it "processed" and nothing happens |
+| the cumulative subtraction in the refund path | a refund larger than the charge |
+| `payment_behavior: "error_if_incomplete"` | an upgrade recorded despite a decline |
+| the non-Stripe guard in reconciliation | comped subscriptions cancelled |
+
+Do this once per guard, write down what failed, and you have a suite you can
+believe. Skip it and you have a green build.
+
+## Asserting on source
+
+Some invariants are one line whose *absence* is the whole defect, and no runtime
+assertion is cheaper than reading the file:
+
+```ts
+const SRC = readFileSync("src/lib/stripe.ts", "utf8");
+it("constructs the client with retries and a pinned version", () => {
+  expect(SRC).toMatch(/maxNetworkRetries:\s*[1-3]\b/);
+  expect(SRC).toMatch(/apiVersion:\s*"[\d-]+\.\w+"/);
+});
+```
+
+Use this sparingly — it is a ratchet against regression, not a substitute for
+behavioural tests — but it is the right tool for "this option must never be
+removed".
+
+## Staging verification by hand
+
+Before the first real charge, on staging, with a real key in test mode:
+
+- [ ] complete a checkout; the subscription appears locally within seconds
+- [ ] in the Dashboard, **Resend** that event; nothing changes and the log says duplicate
+- [ ] cancel from the **customer portal**; local state follows
+- [ ] pay a renewal with the `…0341` card; `past_due` is set and the user is told
+- [ ] refund half a charge in the Dashboard; the clawback is half, not all
+- [ ] refund the other half; the total clawed back equals the charge, not more
+- [ ] add a seat with the `…9995` card; a 402, and nothing changed locally
+- [ ] stop the app, deliver an event, restart; Stripe's retry lands it
+- [ ] point the app at an empty database and run reconciliation; nothing is cancelled
+
+## Production readiness
+
+- [ ] webhook endpoint registered for live mode, subscribed to exactly the events you handle
+- [ ] `STRIPE_WEBHOOK_SECRET` is the **live endpoint's** secret, not `stripe listen`'s
+- [ ] the live key is a restricted key with only the permissions the app uses
+- [ ] `STRIPE_PRODUCT_MODE` and the key are both live, and something asserts they agree
+- [ ] the price conformance job is scheduled and its findings reach a human
+- [ ] the reconciliation job is scheduled
+- [ ] alerts exist for: signature failures, handler 5xx, endpoint disabled by Stripe
+- [ ] a runbook names who to page when Stripe and the database disagree