Add Stripe Checkout harness and provider planning

[mickmister]

Summary

This PR turns FullCircle toward an agent-friendly external-service harness by adding a first Stripe Checkout provider slice, signed Stripe webhook delivery helpers, dogfood coverage with a SQLite-backed sample app, and planning docs for Stripe and Soundspace.

What changed

• Added a Stripe provider harness in packages/harness/src/providers/stripe.ts with support for:
  • creating deterministic Checkout Session fixtures
  • retrieving Checkout Session fixtures
  • returning Checkout Session line-item fixtures
  • delivering signed Stripe webhook events and ordered webhook sequences
• Hardened the core harness request path matching so mocks can match requests with query strings, such as Stripe expand[] parameters.
• Added request body parsing for form-encoded and JSON requests in the FullCircle harness server.
• Fixed passthrough bookkeeping so passthrough registrations are tracked separately from mocks.
• Added Stripe provider tests for Checkout Session matching, retrieval, line items, webhook signatures, invalid/missing signature modes, and webhook ordering.
• Added a dogfood acceptance test that exercises a miniature billing app end-to-end:
  • user starts on a Free plan
  • app creates a Stripe Checkout Session through FullCircle
  • FullCircle sends a signed checkout.session.completed webhook
  • app updates a SQLite database
  • test verifies UI state and inserted-row diffs
• Added documentation:
  • Stripe Checkout subscription flow spec for API calls, webhook events, fixture requirements, and implementation checklist
  • Soundspace provider case study covering external service inventory, fixture plans, app seams, and resource/DB injection strategy
  • branch review with concerns and recommended follow-up work
• Updated the test script to run Jest serially before the example app tests, avoiding fixed-port races.

Why

FullCircle is intended to bridge e2e tests and imported provider clients in application servers, so tests can control third-party communications without relying on sandbox keys or ad hoc mocks below the SDK boundary.

The first productization slice focuses on Stripe Checkout subscriptions because it exercises the key capabilities FullCircle needs for real apps:

• matching SDK-originated HTTP requests at the provider boundary
• returning deterministic provider fixtures
• simulating provider-to-app webhook callbacks with valid signatures
• verifying application-visible behavior and database side effects

The Soundspace research and case-study docs capture the broader target: agents should be able to identify third-party dependencies, put them behind FullCircle sessions/providers, inject resource usage, and use database snapshots/diffs while writing e2e tests.

Important implementation details

• Stripe request matching currently supports selected Checkout Session form fields and metadata. The branch review documents follow-up work to expand this for Soundspace's embedded Checkout contract (client_secret, ui_mode, return_url, customer, multiple line items, trials, and promotion codes).
• Webhook delivery signs payloads with Stripe-compatible HMAC-SHA256 Stripe-Signature headers and supports valid, invalid, and missing signature modes for positive and negative tests.
• The dogfood acceptance test intentionally uses SQLite to validate the desired database snapshot/diff direction, while the Soundspace plan notes that Postgres/Supabase adapters will be needed for real Soundspace dogfooding.
• await using is used in tests for reliable harness cleanup and assertion execution; the review recommends adding callback-style helper APIs for older JS/TS projects and agent-generated tests.

Validation

• npm test
• npm run build

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​types/​jest@​29.5.10
	@​types/​node@​20.10.0
	@​kitajs/​html@​3.0.10
	@​kitajs/​ts-html-plugin@​1.3.3
	typescript@​5.3.2

View full report