Revive the dead Stripe billing handlers, and settle the partner price

[thecelestialmismatch]

Description

Two classes of silent failure, found by tracing the money path end to end rather than trusting the green suite.

Stripe — handlers that could never fire in production

What	Why it was dead	Fix
invoice.paid / invoice.payment_failed	Read invoice.subscription, a field Stripe removed in API version 2025-04-30.basil. We pin 2026-07-29.dahlia; the live endpoint runs 2026-02-25.clover. Both are past basil, so the field is absent on every delivery. A failed payment never moved a subscription to past_due; a recovered one never moved it back.	One shared invoiceSubscriptionId() reading parent.subscription_details.subscription, with a legacy fallback and support for the expanded-object form.
Unfunded orders booked as paid	checkout.session.completed recorded status: 'paid' without checking payment_status. ACH/Bacs/SEPA/Klarna fire it on authorisation, funds days out.	Records pending_payment, notifies nobody, promotes on async_payment_succeeded — an event that was not handled at all, along with async_payment_failed.
Refunds and chargebacks	No handler existed. A refunded $499 order sat at paid forever while the admin rollup counted it as revenue and as a paying customer — the exact figure the Sep 1 kill-criteria review reads.	charge.refunded + charge.dispute.created settle the row. A partial refund is logged and left counted rather than erasing a sale over a goodwill credit.
Customer portal	return_url built from NEXT_PUBLIC_APP_URL || 'http://localhost:3000'. That variable is unset in production (measured 2026-08-14, see lib/site-url.ts), so a paying customer finished managing billing and landed on their own machine.	Uses SITE_URL.
Webhook URL in every runbook	All pointed at the apex host, which 308-redirects. Stripe counts a non-2xx as a failed delivery and eventually disables the endpoint.	Instruction surfaces now say www, with the reason inline so it isn't "tidied" back. Dated audit archives left as written history.
/report/thank-you canonical	Hardcoded apex — on the page a buyer lands on immediately after paying.	siteUrl().

Status can no longer walk backwards: a late Stripe retry cannot reset report_delivered or refunded back to paid.

Why the tests never caught the invoice bug: both handlers cast the invoice to Record<string, unknown>, which silences tsc, and the tests hand-built the pre-basil shape { subscription: "sub_123" } — a payload Stripe no longer sends. Green tests over dead code. The rewritten tests were verified to fail against the old implementation (3 failures) before the fix was restored.

Partner price — three public numbers for one offer

/partners advertised "20% revenue share" and "$299 wholesale" on a $499 report (a 40% cut) in adjacent cards, while CLAUDE.md directed 40–50%. docs/gtm/MSP-CHANNEL-RESEARCH.md flagged this as a blocking inconsistency and deliberately left the margin call to the founder.

Settled: retail $499, partners $399 — a flat $100 discount.

• Modelled in dollars, not percent. A percentage forces a rounding decision ($499 × 0.80 = $399.20) and whichever way it rounds, the realised cut misses the published figure — 20.04% rounding down, or a price nobody chose rounding up. $100 is exact.
• It is a discount, not a payout. No money ever leaves, so there is no commission tracking, payout schedule, or 1099s to build.
• Retail stays $499, not $500. The sub-$500 figure keeps the purchase under the common procurement-approval threshold the product is positioned on, and keeps the live Stripe price (price_1Tge3aQK7cyCnCHkfIfVDAGt, unit_amount: 49900) matching the site — so nothing has to be recreated in Stripe and the Payment Link fallback rail keeps working.
• Wholesale is computed from the discount, and the Stripe charge amounts are imported rather than typed — which is exactly how $299 and a published "20%" managed to coexist.

Accepted risk, stated in the code: the Kitecyber source in that research doc puts MSP expectations at a 60–70% gross margin. At $399 a partner clears 20% reselling at $499 and 60% at $999 — the bottom of the band, reached only at the top of the resale range. PARTNER_DISCOUNT_USD is the one constant to revisit if partner sign-ups stall.

Fixes # (n/a — no tracking issue)

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Documentation update

Note: the partner wholesale price moves $299 → $399. Public-facing and worth a look before merge.

Jordan's Test Plan (CMMC Buyer — required before merge)

• npm run build passes in compliance-firewall-agent/
• Brain AI tests pass — 165 passed across 11 files
• No hardcoded secrets (API keys, license keys, passwords)
• Local-only data boundary preserved — prompt content never leaves customer machine
• Compliance patterns untouched — no file under proxy/, patterns/, or classifier/ is in this diff
• SPRS scoring logic unchanged — not touched
• If proxy modified: N/A — proxy not modified, no bench needed
• If Supabase referenced: report_orders holds order metadata (email, amount, Stripe ids) — no CUI, no prompt content

Verification

• Local UI testing — production build renders all routes, middleware compiles
• npm run build succeeds locally
• Linter passes — npm run lint: 0 errors, 31 warnings (all pre-existing, none in changed files)
• Test suite passes — 2963/2963 across 209 files (5 were failing before this branch)

New tests proven to discriminate, not decorate:

• invoice.* tests fail against the old handler (verified: 3 failures, then restored to green)
• lib/pricing/__tests__/partner-offer-coherence.test.ts fails if a retired figure reappears, if wholesale stops being derived from the discount, or if retail leaves $499

The coherence guard caught two real defects during this work: a rounding that would have shipped a 20.04% cut under a "20%" claim, and a blind price sweep that corrupted an unrelated $400K breach cost statistic in Navbar.tsx.

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation — CLAUDE.md, MSP-CHANNEL-RESEARCH.md (resolution recorded against the section that raised it), and every live Stripe runbook
• No TypeScript any types added in compliance-critical code

Not in this PR

• Idle session timeout — the module is written but its middleware wiring is not done, so it is parked rather than merged. An unenforced security control that looks configured is worse than an absent one (the TURNSTILE_SECRET_KEY lesson).
• Printable receipt/invoice — not started.

Founder action still required (cannot be done from code)

STRIPE_WEBHOOK_SECRET was set and deployed during this session, and the live account now shows exactly one enabled endpoint on https://www.houndshield.com/api/stripe/webhook. Two gaps remain:

1. The endpoint's stored api_version reads 2026-02-25.clover, not the 2026-07-29.dahlia selected in the wizard. Low impact today — the Checkout Session fields this code reads are identical across both — but worth correcting.
2. charge.refunded and charge.dispute.created are not yet subscribed. The handlers in this PR are live code with no events reaching them until those two are ticked.

---

Generated by Claude Code

[supabase]

This pull request has been ignored for the connected project qifynzuyrdxmxlumpsrq because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
compliance-firewall-agent	Ready	Preview	Aug 19, 2026 2:04am