@plumbus/payments-stripe 0.2.0

package/instructions/framework.md

@@ -0,0 +1,62 @@
+# @plumbus/payments-stripe — Framework
+
+`stripeProvider()` implements the `@plumbus/payments` provider contract with Stripe Connect and Stripe Billing. The app never imports `stripe` for money movement; it calls the payments capabilities and helpers.
+
+**Peers:** `"@plumbus/core": "0.7.x"`, `"@plumbus/payments": "0.2.x"` — copy literally. The official `stripe` SDK (22.x) is a dependency of this package; do not add it to the app.
+
+## Stripe APIs used (newest only)
+
+| Need | Stripe API |
+|---|---|
+| Seller accounts | Accounts **v2** (`/v2/core/accounts`): `merchant` configuration (card payments, direct charges) and/or `recipient` configuration (`stripe_transfers`, destination charges and transfers), `dashboard`, `defaults.responsibilities` |
+| Hosted onboarding | Account Links **v2** (`/v2/core/account_links`, `account_onboarding`, every applied configuration) |
+| Embedded seller components | Account Sessions (`/v1/account_sessions`) |
+| Express dashboard link | Login Links (`/v1/accounts/:id/login_links`) |
+| Payment pages | Checkout Sessions (`mode: payment`, `ui_mode: hosted_page \| embedded_page`): direct charges on the seller account (`Stripe-Account`) with `application_fee_amount`; destination charges on the platform with `transfer_data.destination` (+ `on_behalf_of`); platform charges with `transfer_group` |
+| Custom amounts | Prices with `custom_unit_amount` |
+| Holds and saved cards | `capture_method: manual`, `setup_future_usage: off_session`, off-session PaymentIntents, capture and cancel |
+| Card-saving pages | Checkout Sessions `mode: setup`; Payment Methods list/detach |
+| Invoices | Invoices (`send_invoice`) + Invoice Items, finalize, send, void; Invoice Payments |
+| Payment links | Payment Links |
+| Subscriptions | Checkout Sessions `mode: subscription`, Subscriptions update/cancel |
+| Client and billing portals | Billing Portal sessions (a configuration is made when an account has none) |
+| Transfers | Transfers (`source_transaction`), transfer reversals |
+| Payouts | Balance Settings (schedule, delay), Balance (`instant_available`), Payouts |
+| Disputes | Disputes update (evidence, submit) and close |
+| Your plans | Products (stable ids), Prices by lookup key, Entitlement Features, Product Features, Active Entitlements, Billing Meters and meter events |
+| Clients and billing customers | Customers (on the seller account for direct charges, on the platform otherwise) |
+| Refunds | Refunds (`refund_application_fee`, `reverse_transfer` for destination charges) |
+| Account webhooks | **Thin** v2 events `v2.core.account…` via an event destination (`@self`) |
+| Everything else | **Snapshot** events from the platform (`@self`) and sellers' accounts (`@accounts`) via one event destination |
+| Destinations | Event Destinations **v2** (`plumbus payments webhooks setup`) |
+
+Pinned API version: `STRIPE_API_VERSION` (`2026-08-26.dahlia`). Snapshot destinations must render events in this version; `doctor` checks it. Not supported, by design: OAuth "connect an existing Stripe account" (v1-only), legacy Standard/Express/Custom account types, private-preview features.
+
+## Public exports
+
+```ts
+import {
+  stripeProvider,
+  STRIPE_API_VERSION,
+  STRIPE_SNAPSHOT_EVENTS,
+  STRIPE_THIN_EVENTS,
+  STRIPE_DESTINATION_NAMES,
+} from '@plumbus/payments-stripe';
+import {
+  signStripeWebhook,
+  stripeSnapshotEvent,
+  stripeThinAccountEvent,
+  createStripeHttpStub,
+} from '@plumbus/payments-stripe/testing';
+```
+
+`(await provider.client())` returns the configured `Stripe` instance for Stripe-only reads the neutral API does not cover. Do not use it to create charges, refunds, transfers, subscriptions, or accounts.
+
+## Critical rules
+
+1. **Stripe rules are enforced at startup:** Express needs `fees: 'platform'` and `losses: 'platform'`; `losses: 'platform'` always needs `fees: 'platform'`. Stripe's recommendations (destination charges for Express and no-dashboard sellers, direct for full) are warnings.
+2. **Keys are read on first use.** Pass `secretKey` / `webhookSecrets` as functions reading env or a secret manager; the mode (live/test) comes from the key prefix, and events from the other mode are ignored.
+3. **Both destinations sign with their own secret.** Pass every secret in `webhookSecrets` (plus the old ones during a rotation).
+4. **Stripe errors keep Stripe's message.** Invalid requests surface as `validation` errors with `metadata.stripeCode`; outages as retryable `internal` errors.
+5. **Only objects created through this package are tracked.** Payments a seller makes in their own dashboard are ignored (their refunds/disputes too, unless the charge is ours), and so are platform objects without this package's metadata.
+6. **Run `plumbus payments catalog sync` after changing `billing`.** Subscriptions to plans find their prices by lookup key; a missing one fails with `stripe_price_missing`.

package/instructions/testing.md

@@ -0,0 +1,41 @@
+# Testing with @plumbus/payments-stripe
+
+Unit tests never call Stripe. For app logic, prefer the neutral fake (`@plumbus/payments/testing`). Use this package's helpers when you need real Stripe signatures or want to assert the requests Stripe would receive.
+
+## Signed events
+
+```ts
+import { signStripeWebhook, stripeSnapshotEvent, stripeThinAccountEvent } from '@plumbus/payments-stripe/testing';
+
+const delivery = signStripeWebhook({
+  payload: stripeSnapshotEvent({
+    type: 'checkout.session.completed',
+    account: 'acct_seller',
+    object: { id: 'cs_test_1', object: 'checkout.session' },
+  }),
+  secret: 'whsec_test',
+});
+// deliverTestWebhook(payments, ctx, delivery) or app.inject({ method: 'POST', url, headers: delivery.headers, payload: delivery.rawBody })
+```
+
+`stripeThinAccountEvent({ type: 'v2.core.account.updated', accountId })` builds a thin notification. `signStripeWebhook({ timestamp })` produces stale signatures for negative tests.
+
+## Stubbing Stripe's API
+
+```ts
+import { createStripeHttpStub } from '@plumbus/payments-stripe/testing';
+
+const stub = createStripeHttpStub()
+  .on('POST /v2/core/accounts', () => ({ id: 'acct_seller', object: 'v2.core.account', livemode: false /* … */ }))
+  .on('GET /v1/checkout/sessions/*', () => ({ id: 'cs_test_1', status: 'complete', payment_status: 'paid' /* … */ }))
+  .on('POST /v1/refunds', () => ({ status: 400, body: { error: { type: 'invalid_request_error', message: '…' } } }));
+
+const provider = stripeProvider({ secretKey: 'sk_test_x', webhookSecrets: ['whsec_test'], httpClient: stub.httpClient, maxNetworkRetries: 0 });
+// stub.requests: method, path, query, headers (stripe-account, idempotency-key, stripe-version), body
+```
+
+Unmatched routes answer 404, and the first route that matches answers (register one handler per route and keep changing state in variables). v1 bodies are form fields (`line_items[0][price_data][unit_amount]`); v2 bodies are JSON. Platform requests have no `stripe-account` header; seller requests (direct charges, payouts) do.
+
+## Live test mode (optional, manual)
+
+With a **test** key and the Stripe CLI forwarding (see [webhooks.md](./webhooks.md)): onboard a seller with Stripe's test onboarding data, create a charge, pay with card `4242 4242 4242 4242`, and watch `payments.charge.paid`. Never run this against live keys. In the Plumbus repo, `examples/payments-connect-app` runs this on the real runtime (`node scripts/dev.mjs --stripe`), and its `scripts/e2e.mjs` runs 28 scenarios — every payments feature, including destination charges, transfers, payouts, and platform billing with `catalog sync` — against a local Stripe simulator without keys.

package/instructions/webhooks.md

@@ -0,0 +1,44 @@
+# Stripe webhooks for @plumbus/payments
+
+One route (`POST /payments/webhooks/stripe`) receives two Stripe **event destinations**:
+
+| Destination | Payload | `events_from` | Events |
+|---|---|---|---|
+| `plumbus-payments-sellers` | snapshot, version `2026-08-26.dahlia` | `@self` (your platform) and `@accounts` (connected accounts) | `STRIPE_SNAPSHOT_EVENTS`: checkout.session.*, payment_intent.*, refund.*, charge.refunded, charge.refund.updated, charge.dispute.*, payment_method.*, customer.subscription.*, invoice.*, transfer.*, payout.*, entitlements.active_entitlement_summary.updated |
+| `plumbus-payments-accounts` | thin | `@self` | `STRIPE_THIN_EVENTS`: v2.core.account.created/updated/closed and `[requirements]`, `[configuration.merchant]`, `[configuration.recipient]`, `[defaults]`, `[identity]` updates |
+
+Events from your platform's own account (destination and platform charges, transfers, your plans) carry no seller account. The adapter reads routing hints from the event's object — the `plumbus_tenant_id` metadata this package stamps on every Stripe object, the customer, payment, or subscription — so the route can find the tenant.
+
+## Production / staging
+
+```bash
+plumbus payments webhooks setup --url https://api.example.com/payments/webhooks/stripe
+```
+
+- Creates both destinations (skips ones that already exist for that URL) and prints each **signing secret once**.
+- **After upgrading this package, run it again.** It adds the events a newer release needs to existing destinations. A snapshot destination from an earlier release takes events only from `@accounts`, and Stripe cannot change a destination's sources: setup creates a new one (add its secret) and `doctor --live` names the old one to delete.
+- Put both secrets in `STRIPE_WEBHOOK_SECRETS` (comma-separated). During a rotation, list old and new secrets until Stripe stops signing with the old one.
+- Verify: `plumbus payments doctor --live --webhook-url https://api.example.com/payments/webhooks/stripe`.
+
+Do not create these destinations by hand with different names; `doctor` looks for the names above.
+
+## Local development with the Stripe CLI
+
+```bash
+stripe listen --latest \
+  --forward-to localhost:3000/payments/webhooks/stripe \
+  --forward-connect-to localhost:3000/payments/webhooks/stripe \
+  --thin-events 'v2.core.account.created,v2.core.account.updated,v2.core.account.closed,v2.core.account[requirements].updated,v2.core.account[configuration.merchant].updated,v2.core.account[configuration.merchant].capability_status_updated,v2.core.account[configuration.recipient].updated,v2.core.account[configuration.recipient].capability_status_updated' \
+  --forward-thin-to localhost:3000/payments/webhooks/stripe
+```
+
+Put the printed `whsec_…` secret in `STRIPE_WEBHOOK_SECRETS`. `--forward-to` carries your platform's own events (destination charges, plans, transfers); platform objects the app did not create are recorded as ignored — that is expected.
+
+## How the route behaves
+
+- Invalid signature / missing header → `400`, nothing recorded.
+- Event from the other mode (test vs live), unrelated type, unknown seller, or a platform object without a tenant → `200`, recorded as `ignored` with a reason (`livemode_mismatch`, `unhandled_type`, `unknown_seller_account`, `unknown_platform_object`).
+- Relevant event → `200`, recorded and queued; the worker re-reads Stripe and applies it. The same event delivered again → `200`, `duplicate` — unless its processing had failed; then it is queued again (resend it from the Dashboard to retry).
+- Recording fails (database down) → `500`, so Stripe retries.
+
+Inspect deliveries in the `PaymentProviderEvent` table (`status`, `ignoredReason`, `error`).

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@plumbus/payments-stripe",
+  "version": "0.2.0",
+  "description": "Stripe provider for @plumbus/payments — Connect with Accounts v2 sellers (direct and destination charges, transfers, payouts), Checkout, invoices, subscriptions, Stripe Billing plans and meters, and snapshot + thin webhook verification.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "instructions",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "plumbus",
+    "payments",
+    "stripe",
+    "stripe-connect",
+    "stripe-billing"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/plumbus-framework/plumbus.git",
+    "directory": "packages/payments-stripe"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "dependencies": {
+    "stripe": "^22.6.2"
+  },
+  "peerDependencies": {
+    "@plumbus/core": "0.7.x",
+    "@plumbus/payments": "0.2.x"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.4",
+    "@plumbus/payments": "0.2.0",
+    "@plumbus/core": "0.7.7"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsc -b --watch",
+    "test": "vitest run",
+    "lint": "biome lint src",
+    "format": "biome format --write src",
+    "format:check": "biome format src",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json"
+  }
+}