stripe 20.4.1 -> 22.4.0, with the API version pinned first

[Jan0707]

Closes Phase 5. This was the last item, and it was waiting on a payment-path review — which pinning the API version largely removes the need for. See the last section.

The plan item said "check the pinned API version". There wasn't one

server/utils/stripe.ts called new Stripe(config.stripeSecretKey) with no options, so the SDK sent whichever version it bundled:

SDK	bundled API version
20.4.1 (was installed)	2026-02-25.clover
22.4.0 (target)	2026-07-29.dahlia

So this was never "a library upgrade that happens to touch types" — it would have silently moved checkout and webhooks onto a different Stripe API major, with nothing in the diff saying so.

Two commits, and the order is the point

1. Pin the Stripe API version explicitly — sets apiVersion: '2026-02-25.clover'. Verified as a no-op by reading the SDK's own default out of node_modules and comparing: identical strings, so nothing about today's behaviour changes.
2. stripe 20.4.1 -> 22.4.0 — the bump, with the wire held constant by the pin.

What is left for a reviewer is now one line, clover → dahlia, rather than a version bump with an API migration hidden inside it.

The cast is the price of that split

SDK 22 types apiVersion as the single literal it bundles, so holding clover cannot type-check:

server/utils/stripe.ts(24,63): error TS2322: Type '"2026-02-25.clover"' is not assignable to type '"2026-07-29.dahlia"'.

That was the only type error the entire upgrade produced — which is itself the useful finding: our code is already dahlia-compatible. Resolved with as Stripe.LatestApiVersion, and the cost is written into the file: TypeScript no longer rejects a nonsense version string there.

Named honestly: types now describe dahlia while the wire speaks clover. That cannot break existing calls, but it would let TypeScript accept a dahlia-only field that clover rejects at runtime. It is the argument for doing the dahlia move soon rather than eventually.

Checked against the API surface, not the changelog summary

The app's entire Stripe surface is checkout.sessions.create, webhooks.constructEvent, and the Stripe.Event / Stripe.Checkout.Session types. Each dahlia breaking change against the params buildStripeSessionParams actually sends:

dahlia breaking change	our exposure
dynamic_tax_rates removed from line_items[]	not used — no occurrence in the repo
twint.setup_future_usage enum widened	not used
Issuing / PaymentRecord / Radar / V2 Core	none of those resources are called

SDK 22's own breaking changes are clear too: we already use new Stripe(), pass params as a single first argument, and use no callbacks, no per-request host override, and none of the dropped type aliases.

Nine new tests, because the webhook is the one silent failure

tickets/webhook.post.ts is how a paid order becomes a fulfilled order. If verification breaks, the site keeps taking money and stops issuing tickets — and no gate and no visitor would see it. SDK 21 added "throw an error when using the wrong webhook parsing method", so that was the change to worry about.

test/stripeWebhook.test.ts, no network and no real keys (Stripe's own generateTestHeaderString and createFetchHttpClient):

• a correctly signed payload verifies and parses, including metadata.order_id
• a payload modified after signing is rejected
• a signature from a different secret is rejected
• a signature older than the replay tolerance is rejected
• a Buffer body works, which is what readRawBody provides
• the outgoing request carries Stripe-Version: 2026-02-25.clover — proof the pin reaches the wire
• negative control: an unpinned client sends something different. Without this, the assertion above cannot distinguish "the pin is honoured" from "the SDK sends clover anyway"
• the checkout request posts amount, currency and metadata[order_id] intact under SDK 22's rewritten argument parsing
• {CHECKOUT_SESSION_ID} survives unescaped for Stripe to substitute

The signature tests are mutually validating rather than individually trusted: the same payload and secret verify, and each single perturbation fails, so the signing helper cannot be a no-op.

And a runtime probe, because of Pinia

Pinia 4 passed every local gate and failed only on a real request under NODE_ENV=production, because bundling changed how it initialised. SDK 22 reworked its entry points and made Stripe a true ES6 class — same class of risk, and a green build says nothing about it.

Booted .output/server/index.mjs under NODE_ENV=production with dummy credentials and posted to /api/tickets/webhook:

probe	result
forged signature t=1,v1=deadbeef	400 Invalid signature
valid signature, same payload	200 {"received":true}

Both were needed — an endpoint that rejects everything passes the first, one that verifies nothing passes the second.

Verification

npm test 100 passing / 11 files (was 91/10) · prettier:check clean · lint 0 errors, 127 warnings · typecheck ratchet steady at 263 · build exit 0 · npm audit 0 vulnerabilities · plus the production-bundle probe. All on Node 24.19.0.

What still wants your colleague

Moving clover → dahlia. It is now one line, it deletes the cast, and it removes the types/wire mismatch. The evidence above says it is a no-op for this app's surface — but "the changelog says our fields are untouched" is not the same as someone who knows the checkout flow confirming it. That is the review this item was waiting for, now reduced to a single decision instead of being bundled with an SDK major. Logged in the backlog with a note that two tests naming clover are designed to fail when it moves.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JkKMceYAzAYLrSyC42FWTf

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
programmierbar-website	Ready	Preview	Aug 5, 2026 2:25pm

[Copilot]

Pull request overview

This PR upgrades the Nuxt app’s Stripe SDK from 20.x to 22.4.0 while explicitly pinning the Stripe API version to prevent a silent API-version migration during the dependency bump. It also adds focused Vitest coverage around webhook signature verification and Checkout Session request construction to guard against the primary “silent failure” mode in the payment path.

Changes:

• Pin Stripe API version via apiVersion when constructing the Stripe client.
• Upgrade stripe dependency to ^22.4.0 (with corresponding lockfile updates).
• Add a new Vitest suite to validate webhook signature verification behavior and to assert the pinned Stripe-Version header is sent on checkout requests.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
nuxt-app/server/utils/stripe.ts	Pins Stripe API version and centralizes Stripe client construction.
nuxt-app/test/stripeWebhook.test.ts	Adds tests for webhook signature verification and checkout request/header behavior under Stripe SDK 22.
nuxt-app/package.json	Bumps stripe dependency to ^22.4.0.
nuxt-app/package-lock.json	Updates lockfile for the Stripe bump and transitive dependency metadata changes.
docs/dependency-upgrade-plan.md	Documents the Stripe upgrade approach and follow-up plan for clover → dahlia.

Files not reviewed (1)

• nuxt-app/package-lock.json: Generated file

Suppressed comments (1)

nuxt-app/test/stripeWebhook.test.ts:178

• This assertion checks the decoded request body, so what it really guarantees is that {CHECKOUT_SESSION_ID} is preserved after form decoding (i.e. not double-URL-encoded). The current test name/comment reads like it is asserting the raw wire encoding, which is confusing for application/x-www-form-urlencoded.

    it('keeps the {CHECKOUT_SESSION_ID} placeholder unescaped for Stripe to substitute', async () => {
        const { sent } = await capture(PARAMS)

        expect(sent.body).toContain('success_url=https://example.com/success?session_id={CHECKOUT_SESSION_ID}')

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.