@plumbus/payments-stripe 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.2.0 — 2026-09-27
+
+### Added
+
+- First release, in the core 0.7.x family. `stripeProvider()` implements the `@plumbus/payments` provider contract with Stripe Connect on Stripe's newest APIs, pinned to API version `2026-08-26.dahlia` (`stripe` 22.x).
+- Sellers as Accounts v2 connected accounts (merchant configuration, `dashboard`, `defaults.responsibilities`), v2 Account Links onboarding, Account Sessions for embedded components, Express login links.
+- Direct charges through Checkout on the seller account with `application_fee_amount`; customers and refunds on the seller account.
+- Webhooks: snapshot events from connected accounts and thin v2 account events, verified against several signing secrets; fetch-on-event resolution for accounts, checkout sessions, refunds, and disputes.
+- Stripe Connect rules at startup (Express requires platform fees and losses; platform losses require platform fees), warnings for platform liability and Radar limits.
+- `plumbus payments webhooks setup` (two event destinations) and `plumbus payments doctor --live` checks (key mode, Accounts v2 access, destinations, events, API version); with `--webhook-url` it checks the destination at that URL and warns about same-named leftovers.
+- Checkout `expires_at` stays a minute inside Stripe's 30-minute–24-hour window; product names are cut without splitting an emoji (a half surrogate pair made the SDK throw `URI malformed`); fee and refunded amount are reported as unknown when Stripe did not expand them, so an unpaid expired session keeps its stored fee; refund changes follow their charge; `findRefund` looks a refund up by its `plumbus_refund_id` on the seller's account.
+- Stripe errors become PlumbusErrors that keep Stripe's message and codes.
+- Charge types and routing: destination charges on the platform (`transfer_data.destination`, `on_behalf_of`), platform charges (`transfer_group`); accounts ask for the recipient configuration (`stripe_transfers`) as needed and onboarding links cover every applied configuration; `transfersEnabled` from the recipient capability; refunds with `reverse_transfer`.
+- Checkout: line items, custom amounts (a `custom_unit_amount` price), embedded pages (`ui_mode: embedded_page`), holds (`capture_method: manual`), saving the method (`setup_future_usage`), and page options (promotion codes, Stripe Tax with `customer_update.address`, billing address, phone, shipping countries, locale, submit type, statement descriptor suffix); discounts, tax, captured amounts, and saved methods read back from sessions.
+- Invoices (created, filled, finalized, sent; an invoice a crashed attempt left behind is finished, not made twice), off-session charges on saved cards (declines and `authentication_required` become outcomes), capture and cancel, card-saving pages, payment method list/detach, client and billing portals (a portal configuration is made for an account that has none), subscriptions through Checkout (inline prices or catalog prices by lookup key, `application_fee_percent`), payment links, transfers (`source_transaction`) and reversals, payouts through Balance Settings (schedules, delay) and instant payouts, dispute evidence and acceptance.
+- Stripe Billing: `syncCatalog` / `checkCatalog` for products (stable ids), prices by lookup key (`transfer_lookup_key` on a change, the old price archived), entitlement features attached to plan products, and billing meters with metered prices; billing customers, active entitlements, and meter events.
+- Webhooks: one snapshot destination from `@self` and `@accounts` with payment intent, payment method, subscription, invoice, transfer, payout, and entitlement events; recipient thin events; routing hints for platform events; `resolveEvent` for every new object, resolving a payment to the page or invoice it belongs to. `webhooks setup` adds missing events to existing destinations and makes a new snapshot destination when an old one lacks `@self`; `doctor --live` reports missing sources, which duplicate to delete, and an out-of-date catalog.
+- Config rules: Stripe's charge-type recommendations (destination for Express and no-dashboard sellers, direct for full) and platform liability for destination charges as warnings.
+- `@plumbus/payments-stripe/testing`: `signStripeWebhook`, `stripeSnapshotEvent`, `stripeThinAccountEvent`, `createStripeHttpStub`.

package/README.md

@@ -0,0 +1,60 @@
+# @plumbus/payments-stripe
+
+Stripe provider for [`@plumbus/payments`](../payments/), built on Stripe's newest APIs:
+
+- sellers are **Accounts v2** connected accounts (full, Express, or no Stripe dashboard — your choice per app, the seller's choice per account), with the merchant and/or recipient configuration their charge type needs;
+- clients pay through **Checkout** (hosted or embedded) on the seller's own account (direct charges) or on your platform paid on to the seller (destination charges), with your application fee — or by invoice, saved card, payment link, or subscription;
+- your platform splits payments with **transfers**, sets payout schedules through **Balance Settings**, and bills its own plans with **Stripe Billing** (prices by lookup key, entitlements, meters);
+- account changes arrive as **thin** v2 events and everything else as **snapshot** events from the platform and sellers' accounts, all verified from the raw body.
+
+Pinned to Stripe API version **`2026-08-26.dahlia`** through the official `stripe` SDK (a dependency — do not add `stripe` to your app).
+
+Peers: `@plumbus/core` **`0.7.x`**, `@plumbus/payments` **`0.2.x`**.
+
+## Install
+
+```bash
+pnpm add @plumbus/payments @plumbus/payments-stripe
+```
+
+## Usage
+
+```ts
+import { stripeProvider } from '@plumbus/payments-stripe';
+
+const provider = stripeProvider({
+  secretKey: () => process.env.STRIPE_SECRET_KEY ?? '',       // sk_… or rk_…
+  webhookSecrets: () => (process.env.STRIPE_WEBHOOK_SECRETS ?? '').split(',').filter(Boolean),
+  publishableKey: process.env.STRIPE_PUBLISHABLE_KEY,         // embedded components only
+});
+// createPayments({ provider, ... }) — see @plumbus/payments
+```
+
+```bash
+plumbus payments webhooks setup --url https://api.example.com/payments/webhooks/stripe
+plumbus payments catalog sync     # with billing: products, prices, features, meters
+plumbus payments doctor --live --webhook-url https://api.example.com/payments/webhooks/stripe
+```
+
+Stripe's Connect rules are checked when the app starts: Express sellers require your platform to pay fees and cover losses; platform-covered losses always require platform-paid fees. Stripe's recommendations (destination charges for Express and no-dashboard sellers) are reported as warnings.
+
+## Documentation
+
+- **Human docs:** [`docs/payments/stripe.md`](../../docs/payments/stripe.md), [`docs/payments/webhooks.md`](../../docs/payments/webhooks.md)
+- **Agent recipes:**
+  - [`instructions/README.md`](./instructions/README.md) — index
+  - [`instructions/framework.md`](./instructions/framework.md) — APIs used, exports, critical rules
+  - [`instructions/configure-stripe.md`](./instructions/configure-stripe.md) — keys, dashboards, charge types, liability, payouts, the billing catalog
+  - [`instructions/webhooks.md`](./instructions/webhooks.md) — destinations, secrets, local forwarding
+  - [`instructions/testing.md`](./instructions/testing.md) — signed events, HTTP stub, test mode
+- **Test app:** [`examples/payments-connect-app`](../../examples/payments-connect-app/) — real Plumbus runtime + local Stripe simulator, 28 end-to-end scenarios
+- **Smoke app:** [`examples/payments-stripe-smoke`](../../examples/payments-stripe-smoke/) — one process, no database
+
+## The Plumbus ecosystem
+
+`@plumbus/payments-stripe` is one package in the Plumbus framework. For the full list of packages and when to use each, see the [Plumbus monorepo README](https://github.com/plumbus-framework/plumbus#packages).
+
+## Links
+
+- **Payments docs** — [docs/payments/](../../docs/payments/)
+- **Issues** — [github.com/plumbus-framework/plumbus/issues](https://github.com/plumbus-framework/plumbus/issues)