feat(paykit): harden subscription checkout sessions

[Pascoooo]

Summary

This PR hardens subscription Checkout Sessions without adding app-specific billing behavior.

It is stacked on #201 (subscription-quantity). After #201 merges, this branch should be rebased so this PR contains only the checkout hardening commit.

Changes

• Add optional subscription Checkout options for idempotency, promotion codes, automatic tax, billing address collection, Tax ID collection, and customer update behavior.
• Return checkoutSessionId from subscription checkout results.
• Add a server-side expireCheckoutSession PayKit method that verifies provider customer ownership before expiring a Stripe Checkout Session.
• Pass Checkout hardening options through the provider contract and Stripe provider.
• Add generic PayKit error codes for checkout session not found, customer mismatch, and non-expireable sessions.
• Add a changeset for a minor paykitjs release.

Out of scope

• Automatic resume of open Checkout Sessions.
• Application-level storage of checkout attempts.
• Fooodly-specific org mapping or reconciliation.
• Annual/monthly multi-price logic.

Verification

• pnpm --filter paykitjs typecheck
• pnpm lint
• pnpm test:unit
• pnpm --filter paykitjs build
• pnpm exec oxfmt --check <touched files>

Note: pnpm format:check currently fails on this Windows shell because the quoted glob is not expanded for oxfmt, so touched files were checked explicitly instead.

---

Summary by cubic

Hardens subscription Checkout Sessions and adds quantity-aware subscriptions across paykitjs. Adds a secure server method to expire Stripe sessions, returns checkoutSessionId from subscribe, and avoids top‑level eval during runtime init.

• New Features

  • Checkout hardening for subscription Checkout: promotion codes, automatic tax, billing/tax ID collection, customer update, and idempotency; passed through the provider to Stripe.
  • New server method expireCheckoutSession that verifies customer ownership, treats already-expired sessions as idempotent, and expires only open sessions.
  • subscribe now returns checkoutSessionId and supports quantity; quantity is persisted and synced across create/update/schedule flows.
  • Added PayKit error codes: checkout session not found, customer mismatch, and not-expireable.

• Migration

  • Custom providers: implement expireCheckoutSession; add quantity to createSubscription, updateSubscription, scheduleSubscriptionChange, and createSubscriptionCheckout; include quantity in returned subscriptions.
  • API usage: subscribe accepts checkout and quantity; handle checkoutSessionId in the result.

^{Written for commit 0dc710c. Summary will update on new commits.}

[vercel]

@Pascoooo is attempting to deploy a commit to the maxktz Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 0d6cb282-a344-49ac-b886-975f2b766d0f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Pascoooo]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.