@fantastic.dev/better-stripe 0.68.0 → 0.69.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -26,6 +26,22 @@
26
26
  - Remove internal tracker references from public documentation and add a
27
27
  regression check that prevents their reintroduction.
28
28
 
29
+ ## [0.69.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.68.1...v0.69.0) (2026-10-19)
30
+
31
+ ### Features
32
+
33
+ - **example:** product metered billing with headless and component views ([#364](https://github.com/FantasticDevHQ/better-stripe/issues/364)) ([cd978c2](https://github.com/FantasticDevHQ/better-stripe/commit/cd978c22e7a87f36e5bb0c066011b3cd82f2d0cb))
34
+
35
+ ## [0.68.1](https://github.com/FantasticDevHQ/better-stripe/compare/v0.68.0...v0.68.1) (2026-10-19)
36
+
37
+ ### Documentation
38
+
39
+ - align public guides and simplify package maintenance ([#361](https://github.com/FantasticDevHQ/better-stripe/issues/361)) ([f0a07f9](https://github.com/FantasticDevHQ/better-stripe/commit/f0a07f92e1de8b044c1780a9a7551b531b9ff9e3))
40
+
41
+ ### Maintenance
42
+
43
+ - **coverage:** ratchet earned coverage floors ([#362](https://github.com/FantasticDevHQ/better-stripe/issues/362)) ([df7db01](https://github.com/FantasticDevHQ/better-stripe/commit/df7db0112a551702540733b65f9541fcfc280ee9))
44
+
29
45
  ## [0.68.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.67.1...v0.68.0) (2026-10-19)
30
46
 
31
47
  ### Features
package/MIGRATION.md CHANGED
@@ -169,7 +169,7 @@ changes. Further consumer guidance: [Stripe API changelog](https://docs.stripe.c
169
169
  The docs.stripe.com changelog page returned HTTP 403 in this execution
170
170
  environment.
171
171
 
172
- ## Upcoming settlement API extraction
172
+ ## Settlement API extraction
173
173
 
174
174
  Deploy the regenerated component bindings with the package upgrade. Existing
175
175
  transfers remain in the same ledger; new immutable allocation and commission
package/README.md CHANGED
@@ -5,7 +5,7 @@ billing, and Connect marketplaces. It provides checkout, subscriptions, webhook
5
5
  syncing, marketplace fees and splits, payouts, refunds, and disputes, with React
6
6
  hooks and headless UI components.
7
7
 
8
- **Version**: `0.68.0` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
8
+ **Version**: `0.69.0` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
9
9
 
10
10
  Connect platforms use the default GA API version. Non-Connect merchants using
11
11
  customer-only Accounts v2 need preview access and an explicit preview version.
@@ -135,17 +135,7 @@ The [example app](https://github.com/FantasticDevHQ/better-stripe/blob/main/exam
135
135
  demonstrates customer, seller, affiliate, and admin flows, including several checkout
136
136
  integration styles.
137
137
 
138
- ## Contributing
139
-
140
- See the [development guide](docs/development.md) for local setup and code generation,
141
- [testing utilities](docs/testing.md) for fixtures, and the [release guide](docs/releasing.md)
142
- for publishing. Run `pnpm run check:all` before submitting changes.
143
-
144
- ## License
145
-
146
- MIT
147
-
148
- ## Metered usage
138
+ ### Metered usage
149
139
 
150
140
  Use native Stripe billing for pay as you go, included monthly units with overages,
151
141
  and paid prepaid credits. Developers choose units, precision, rates and policy;
@@ -163,3 +153,13 @@ for forms, exact usage, allowances, prepaid balances and paginated history.
163
153
  [The verification matrix](docs/usage-verification.md) records native paid-source
164
154
  proof, packed consumers and account/clock limits. Existing apps should follow
165
155
  [opt-in adoption, model transitions and rollback](docs/usage-rollout.md).
156
+
157
+ ## Contributing
158
+
159
+ See the [development guide](docs/development.md) for local setup and code generation,
160
+ [testing utilities](docs/testing.md) for fixtures, and the [release guide](docs/releasing.md)
161
+ for publishing. Run `pnpm run check:all` before submitting changes.
162
+
163
+ ## License
164
+
165
+ MIT
@@ -1 +1 @@
1
- {"version":3,"file":"subscriptionCheckout.d.ts","sourceRoot":"","sources":["../../../src/client/usage/subscriptionCheckout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAGvD,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC5B,MAAM,wBAAwB,CAAC;AAWhC,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,sBAAsB,EAC7B,GAAG,EAAE,MAAM,GACV,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAqBrC;AAiCD,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,wBAAwB;;YAuED,MAAM,GAAG,UAAU,GAAG,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAK9D"}
1
+ {"version":3,"file":"subscriptionCheckout.d.ts","sourceRoot":"","sources":["../../../src/client/usage/subscriptionCheckout.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,QAAQ,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAGvD,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC5B,MAAM,wBAAwB,CAAC;AAWhC,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,sBAAsB,EAC7B,GAAG,EAAE,MAAM,GACV,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAuBrC;AAiCD,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,wBAAwB;;YAuED,MAAM,GAAG,UAAU,GAAG,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAK9D"}
@@ -7,6 +7,8 @@ export function managedCheckoutParams(terms, key) {
7
7
  throw new UsageSubscriptionError("incompatible_terms", "Managed Checkout requires Checkout collection");
8
8
  return {
9
9
  mode: "subscription",
10
+ // Rates, paid credits and invoice verification retain this currency.
11
+ adaptive_pricing: { enabled: false },
10
12
  customer_account: terms.meters[0].scope.customerAccount,
11
13
  success_url: terms.collection.successUrl,
12
14
  cancel_url: terms.collection.cancelUrl,
@@ -1 +1 @@
1
- {"version":3,"file":"subscriptionCheckout.js","sourceRoot":"","sources":["../../../src/client/usage/subscriptionCheckout.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"subscriptionCheckout.js","sourceRoot":"","sources":["../../../src/client/usage/subscriptionCheckout.ts"],"names":[],"mappings":"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"}
@@ -1 +1 @@
1
- {"version":3,"file":"UsageSummary.d.ts","sourceRoot":"","sources":["../../../src/react/workflows/UsageSummary.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,cAAc,CAAC;IACtB,OAAO,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,EAAE,yBAAyB,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE;QACjB,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;QACtC,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;QACxC,SAAS,EAAE,OAAO,CAAC;QACnB,OAAO,EAAE,OAAO,CAAC;KAClB,KAAK,SAAS,CAAC;CACjB,CAAC;AAeF,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,+BAyKpD"}
1
+ {"version":3,"file":"UsageSummary.d.ts","sourceRoot":"","sources":["../../../src/react/workflows/UsageSummary.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AACxF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,KAAK,EAAE,cAAc,CAAC;IACtB,OAAO,EAAE,iBAAiB,CAAC,iBAAiB,CAAC,GAAG,SAAS,CAAC;IAC1D,QAAQ,CAAC,EAAE,yBAAyB,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE;QACjB,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;QACtC,QAAQ,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;QACxC,SAAS,EAAE,OAAO,CAAC;QACnB,OAAO,EAAE,OAAO,CAAC;KAClB,KAAK,SAAS,CAAC;CACjB,CAAC;AAeF,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,+BA4KpD"}
@@ -49,6 +49,9 @@ export function UsageSummary(props) {
49
49
  group.binding.stripePriceId,
50
50
  group.subscription.subscriptionItemId,
51
51
  group.subscription.period,
52
- ])))), _jsx("p", { children: "Estimate only. Finalized invoices and verified payments determine billing." })] })), !provider || provider.status !== "available" ? (_jsxs("p", { role: "status", children: ["Native aggregation ", provider?.status ?? "unavailable", ". Refresh after provider ingestion."] })) : (_jsxs(_Fragment, { children: [_jsxs("p", { children: ["Native aggregate: ", provider.value.quantity] }), provider.value.stale && (_jsx("p", { role: "status", children: "Native aggregation stale." })), !provider.value.complete && (_jsx("p", { role: "status", children: "Native aggregation partial. More provider pages remain." })), _jsx("p", { children: "Aggregation may be delayed. Provider acceptance does not prove ingestion or payment." })] }))] }));
52
+ ])))), _jsx("p", { children: "Estimate only. Finalized invoices and verified payments determine billing." })] })), !provider || provider.status !== "available" ? (_jsxs("p", { role: "status", children: ["Native aggregation ", provider?.status ?? "unavailable", ".", " ", provider?.status === "unsupported" &&
53
+ provider.reason === "minute_alignment_required"
54
+ ? "Exact summaries do not support partial-minute billing boundaries. Reconcile with the native invoice instead."
55
+ : "Refresh after provider ingestion."] })) : (_jsxs(_Fragment, { children: [_jsxs("p", { children: ["Native aggregate: ", provider.value.quantity] }), provider.value.stale && (_jsx("p", { role: "status", children: "Native aggregation stale." })), !provider.value.complete && (_jsx("p", { role: "status", children: "Native aggregation partial. More provider pages remain." })), _jsx("p", { children: "Aggregation may be delayed. Provider acceptance does not prove ingestion or payment." })] }))] }));
53
56
  }
54
57
  //# sourceMappingURL=UsageSummary.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"UsageSummary.js","sourceRoot":"","sources":["../../../src/react/workflows/UsageSummary.tsx"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"UsageSummary.js","sourceRoot":"","sources":["../../../src/react/workflows/UsageSummary.tsx"],"names":[],"mappings":"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"}
package/docs/README.md CHANGED
@@ -24,8 +24,7 @@ guide for your integration.
24
24
  - [SetupIntent recovery](setup-intent-recovery.md).
25
25
  - [Balance funding state](balance-funding-state.md) and [workflow](balance-funding-workflow.md).
26
26
  - [Example balance funding cutover](example-balance-funding-cutover.md).
27
- - [Native metered billing](metered-usage.md), all three models, public recipes and accounting contracts.
28
- - [Opt-in usage rollout](usage-rollout.md), adoption, drain, backfill limits, model transitions, rollback and release handoff.
27
+ - [Metered billing guides](#metered-usage), all three models, package APIs, runnable examples and rollout.
29
28
 
30
29
  ## Marketplace, settlement, and recovery
31
30
 
@@ -56,33 +55,20 @@ covers sandbox configuration, checkout comparisons, and test flows.
56
55
 
57
56
  ## Metered usage
58
57
 
59
- Start with the [native Stripe setup guide](metering-setup.md), then read the
60
- [shared contracts and sandbox evidence](metered-usage.md).
61
-
62
- [Atomic usage ledger and scoped history](usage-ledger.md) describes acceptance and retention.
63
-
64
- [Native usage catalog](usage-catalog.md) covers provisioning, immutable versions and typed price observations.
65
-
66
- [Durable native delivery](usage-delivery.md) explains host actions, bounded retries, operational holds and asynchronous errors.
67
-
68
- [Usage observations and reconciliation](usage-observations.md) covers exact summaries, paginated audit history, native freshness and invoice observations.
69
-
70
- [Managed metered subscriptions and invoice lifecycle](usage-subscriptions.md) covers all three models, Checkout, renewal, closeout and native test clocks.
71
-
72
- - [Payment-backed prepaid usage](./usage-credits.md)
73
-
74
- - [Included usage and limits](./usage-limits.md) covers atomic caps, reservations, period resets and exact overage estimates.
75
-
76
- - [Usage corrections](./usage-corrections.md) covers native cancellation, quantity restoration and verified invoice adjustments.
77
-
78
- - [Native usage settlement](./usage-settlement.md) covers original paid invoices, issuer-service credit purchases and affiliate recovery.
79
-
80
- - [Metered billing authorization](./usage-security.md) covers server ownership, work deduplication, native proof limits and retained recovery liabilities.
81
-
82
- - [Reusable metered billing UI](usage-react.md) covers all three models, render props, authenticated adapters and bounded history.
83
-
84
- - [Native usage configuration UI](usage-configuration.md) covers reusable forms, managed meter selection, price rows and authorized adapters.
85
-
86
- - [Native metered billing example](usage-example.md), three runnable models, paid evidence and scoped cleanup.
87
-
88
- - [Metered usage verification](usage-verification.md), three-model acceptance, packed consumers, native proof and failure limits.
58
+ - [Native Stripe setup](metering-setup.md), prerequisites, safe credentials and the developer/AI-agent runbook.
59
+ - [Three-model recipes](metered-usage.md), developer-defined units, rates, allowances and paid prepaid credits.
60
+ - [Atomic ledger and history](usage-ledger.md), acceptance, event identity and retention.
61
+ - [Native usage catalog](usage-catalog.md), provisioning, immutable versions and typed price observations.
62
+ - [Durable delivery](usage-delivery.md), internal provider actions, bounded retries, holds and asynchronous errors.
63
+ - [Observations and reconciliation](usage-observations.md), exact summaries, paginated history, freshness and invoices.
64
+ - [Managed subscriptions](usage-subscriptions.md), enrollment, Checkout, renewal, closeout and native test clocks.
65
+ - [Payment-backed prepaid credits](usage-credits.md), verified purchase grants, consumption and recovery.
66
+ - [Included usage and limits](usage-limits.md), atomic caps, reservations, period resets and overage estimates.
67
+ - [Corrections](usage-corrections.md), native cancellation, quantity restoration and verified invoice adjustments.
68
+ - [Settlement](usage-settlement.md), original paid invoices, issuer-service credit purchases and affiliate recovery.
69
+ - [Authorization](usage-security.md), server ownership, work deduplication and retained liabilities.
70
+ - [React workflows](usage-react.md), all three models, render props, authenticated adapters and bounded history.
71
+ - [Configuration UI](usage-configuration.md), reusable forms, managed meter selection and price rows.
72
+ - [Runnable example](usage-example.md), three sandbox flows, paid evidence and scoped cleanup.
73
+ - [Verification](usage-verification.md), packed consumers, native billing proof and documented limits.
74
+ - [Opt-in rollout](usage-rollout.md), adoption, drain, backfill limits, model transitions and rollback.
@@ -2,19 +2,31 @@
2
2
 
3
3
  ### Component-Owned Tables
4
4
 
5
- The component manages 8 domain tables and 1 internal table:
6
-
7
- | Table | Description |
8
- | ------------------ | -------------------------------------------------------- |
9
- | `accounts` | V2 account records with identity and configuration state |
10
- | `products` | Stripe products with optional trial day management |
11
- | `prices` | Stripe prices linked to products |
12
- | `subscriptions` | Subscription lifecycle with first-class trial tracking |
13
- | `checkoutSessions` | Checkout session state (embedded and redirect) |
14
- | `invoices` | Invoice records with subscription metadata |
15
- | `payments` | Payment intent records |
16
- | `payouts` | Payout records for Connect/marketplace |
17
- | `webhookEvents` | Internal ledger for replay protection and observability |
5
+ The component schema is composed from domain modules. It includes provider
6
+ mirrors and retained financial, workflow and usage state. The authoritative table
7
+ inventory is [the component schema](../src/component/schema.ts); table names are
8
+ internal storage contracts, not an invitation for a host to write them directly.
9
+
10
+ | Domain | Component-owned state |
11
+ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
12
+ | Accounts and catalog | Accounts, closed-account provenance, products and prices |
13
+ | Billing and Connect | Subscriptions, checkout sessions, invoices, payments, payouts, refunds, disputes, transfers and reversal operations |
14
+ | Webhooks | Event deduplication and processing state |
15
+ | Settlement and affiliate recovery | Immutable allocations/commission decisions, original policy context, obligations, receipts, offsets and balances |
16
+ | Recipient payouts | Policies, schedule operations, releases, claims, source allocations, snapshots, worker jobs and financial/risk revisions |
17
+ | Financial observations and ownership | Scoped ownership generations, complete source/transfer observations, reversal history and retained references |
18
+ | Recovery and funding | Cost claims/reservations, processing-cost reconciliation, balance-funding operations and durable recovery requests |
19
+ | Operation evidence | Bounded evidence headers and payloads |
20
+ | Usage catalog and subscriptions | Immutable meter/price bindings, enrollment controls, intents, locks and history |
21
+ | Usage ledger and delivery | Scoped events, counters, reservations, transactional outbox, delivery locks/errors/history and provider observations |
22
+ | Usage allowance and credits | Allowance policies/history and payment-backed credit accounts, purchases, grants and history |
23
+ | Usage corrections | Correction operations, claims and auditable history |
24
+ | Payout revision migration | Revision journal, bounded migration jobs and results |
25
+
26
+ The component installs its nested Workflow runtime through
27
+ `@fantastic.dev/better-stripe/convex.config`. Hosts supply internal provider
28
+ actions and authorization where required. See [durable execution](architecture/durable-execution.md)
29
+ and [the extraction boundary](architecture/component-extraction.md).
18
30
 
19
31
  ### App-Layer Tables
20
32
 
@@ -52,12 +64,14 @@ Async hook (scheduled action) --> App calls external APIs
52
64
 
53
65
  ### Package Entry Points
54
66
 
55
- | Entry Point | Contents |
56
- | -------------------------------------------- | -------------------------------------------------------- |
57
- | `@fantastic.dev/better-stripe` | `BetterStripe` class, `registerRoutes`, TypeScript types |
58
- | `@fantastic.dev/better-stripe/react` | React hooks, headless UI components, formatting helpers |
59
- | `@fantastic.dev/better-stripe/testing` | Test fixtures, mock webhooks, `assertTestEnvironment` |
60
- | `@fantastic.dev/better-stripe/convex.config` | Convex component registration |
67
+ | Entry Point | Contents |
68
+ | --------------------------------------------------- | -------------------------------------------------------------------- |
69
+ | `@fantastic.dev/better-stripe` | `BetterStripe` class, `registerRoutes`, TypeScript types |
70
+ | `@fantastic.dev/better-stripe/react` | React hooks, headless UI components, formatting helpers |
71
+ | `@fantastic.dev/better-stripe/testing` | Test fixtures, mock webhooks, `assertTestEnvironment` |
72
+ | `@fantastic.dev/better-stripe/convex.config` | Convex component registration and nested Workflow runtime |
73
+ | `@fantastic.dev/better-stripe/usage` | Shared usage schemas, exact quantity helpers and model configuration |
74
+ | `@fantastic.dev/better-stripe/_generated/component` | Generated component reference types |
61
75
 
62
76
  ### Error Handling
63
77
 
@@ -75,6 +89,11 @@ interface BetterStripeError {
75
89
  }
76
90
  ```
77
91
 
78
- Error codes: `ACCOUNT_NOT_FOUND`, `ACCOUNT_CREATE_FAILED`, `PRODUCT_NOT_FOUND`, `PRICE_NOT_FOUND`, `SUBSCRIPTION_NOT_FOUND`, `SUBSCRIPTION_UPDATE_FAILED`, `CHECKOUT_CREATE_FAILED`, `CHECKOUT_NOT_FOUND`, `PAYMENT_METHOD_FAILED`, `WEBHOOK_VERIFICATION_FAILED`, `WEBHOOK_DUPLICATE_EVENT`, `STRIPE_API_ERROR`, `TEST_ENV_REQUIRED`, `INVALID_CONFIGURATION`.
92
+ The [structured error definitions](../src/client/errors.ts) include account,
93
+ catalog, checkout, subscription, refund, dispute and configuration failures.
94
+ The usage APIs also expose domain-specific errors and explicit held/unknown
95
+ outcomes. See [usage contracts](metered-usage.md) and each workflow's recovery
96
+ contract. A successful transport call does not establish payment or settlement.
79
97
 
80
- > **Note:** All methods that throw their own errors or catch-and-rethrow now use structured `ConvexError(BetterStripeError)` payloads. Methods that let uncaught Stripe SDK errors propagate are a separate policy decision and not yet aligned.
98
+ Methods that allow uncaught Stripe SDK errors to propagate remain a separate
99
+ error path. Do not assume every failure has the structured payload above.
@@ -96,7 +96,7 @@ Scope the idempotency key to one catalog operation and reuse it only with identi
96
96
  | `getActiveSubscription(ctx, { userId, orgId? })` | Get the active subscription for a user or org |
97
97
  | `getTrialStatus(ctx, { subscriptionId })` | Get trial state for a subscription |
98
98
  | `cancelSubscription(ctx, { stripeSubscriptionId, cancelAtPeriodEnd? })` | Cancel subscription immediately or at period end |
99
- | `reactivateSubscription(ctx, { stripeSubscriptionId })` | Reactivate a canceled subscription |
99
+ | `reactivateSubscription(ctx, { stripeSubscriptionId })` | Clear scheduled end-of-period cancellation before the subscription terminates |
100
100
  | `updateSubscriptionQuantity(ctx, { stripeSubscriptionId, quantity })` | Update subscription seat quantity |
101
101
 
102
102
  ### Durable recovery claims
@@ -446,7 +446,7 @@ recovery costs and credits remain host-owned policy. See Stripe's
446
446
  | `uploadDisputeEvidence(ctx, { stripeDisputeId, actor, field, file, stripeAccountId? })` | Since 0.14.0: validate and upload file bytes, then attach the returned file ID to an authorized dispute draft; never submits |
447
447
  | `updateDispute(ctx, { stripeDisputeId, evidence?, metadata?, submit?, stripeAccountId? })` | Submit/stage dispute evidence (`submit: true` finalizes the response) |
448
448
  | `closeDispute(ctx, { stripeDisputeId, stripeAccountId? })` | Accept a dispute (concede the chargeback) — irreversible |
449
- | `reverseTransfers(ctx, { sourceChargeId, percent?, amount? })` | Reverse split/destination transfers for a charge (the primitive behind automatic dispute clawback; also callable manually) |
449
+ | `reverseTransfers(ctx, { sourceChargeId, percent?, amount?, operationId? })` | Reverse split/destination transfers for a charge (the primitive behind automatic dispute clawback; also callable manually) |
450
450
 
451
451
  `uploadDisputeEvidence` shipped in [0.14.0](https://github.com/FantasticDevHQ/better-stripe/releases/tag/v0.14.0).
452
452
  Call it from an authenticated server adapter with a session-derived actor. A seller
@@ -587,7 +587,7 @@ and [uploaded screenshots and provider records](https://github.com/FantasticDevH
587
587
 
588
588
  ## Reversal history and revision maintenance
589
589
 
590
- `stripe.reversalObservations` reads original claimed-slice history and maintains a bounded diagnostic index. Its physical operation references survive release/deletion and distinguish reuse of a business operation ID. Exact bucket/owner pages, original/latest payloads and generation-aware continuation remain unknown coverage. These methods do not execute reversals, certify current ownership or authorize closure. See [financial observations](financial-observations.md#claimed-reversal-history).
590
+ `stripe.reversalObservations` reads original claimed-slice history and maintains a bounded diagnostic index. Its physical operation references survive release/deletion and distinguish reuse of a business operation ID. Exact bucket/owner pages, original/latest payloads and generation-aware continuation remain unknown coverage. These methods do not execute reversals, certify current ownership or authorize closure. See [financial observations](financial-observations.md#claimed-reversal-slice-history).
591
591
 
592
592
  `stripe.payoutRevisionMigration` exposes trusted-host `activateAccount`, `begin`, `resume`, `get` and `results`. Existing destinations keep legacy revision authority until explicitly activated. Activation and inventory are bounded storage maintenance, with held outcomes for ambiguous or unrepresentable legacy authority. Installing the package does not run a migration. See the [migration guide](payout-revision-migration.md) before relying on the tested large-operation path or changing component versions.
593
593
 
@@ -600,3 +600,15 @@ and [uploaded screenshots and provider records](https://github.com/FantasticDevH
600
600
  row reads and no Stripe request. The [read contract](read-contracts.md#bounded-product-and-price-identity)
601
601
  explains duplicate handling and the host authorization boundary. Existing
602
602
  provider-ID getters keep their first-row semantics.
603
+
604
+ ## Native metered billing
605
+
606
+ `stripe.usage` groups the shared ledger/delivery APIs and all three model
607
+ controllers. Start with [typed model recipes](metered-usage.md) and
608
+ [setup](metering-setup.md). Follow the domain contracts for [catalog](usage-catalog.md),
609
+ [subscriptions](usage-subscriptions.md), [ledger](usage-ledger.md),
610
+ [delivery](usage-delivery.md), [observations](usage-observations.md),
611
+ [allowances/limits](usage-limits.md), [paid credits](usage-credits.md),
612
+ [corrections](usage-corrections.md) and [settlement](usage-settlement.md).
613
+ These are trusted host APIs. Browser-selected payer, realm, meter or provider
614
+ references do not establish authorization.
@@ -2,12 +2,12 @@
2
2
 
3
3
  ### Environment Variables
4
4
 
5
- | Variable | Required | Read by | Description |
6
- | -------------------------- | ----------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7
- | `STRIPE_SECRET_KEY` | Yes | Component | Declared in the component's `convex.config.ts` (required) and read by the component (e.g. `getStripeMode`). Also passed explicitly via the `BetterStripe` constructor and `registerRoutes`. The installing app must wire it to the component — see below. |
8
- | `STRIPE_WEBHOOK_SECRET` | Yes | App | Signing secret for the V1 snapshot event destination. Read by `registerRoutes` in the app, not the component. |
9
- | `STRIPE_WEBHOOK_SECRET_V2` | No\* | App | Signing secret for the V2 thin event destination (Connect account events). \*Required whenever your V2 destination has its own secret (the usual case); falls back to `STRIPE_WEBHOOK_SECRET` if unset. |
10
- | `STRIPE_PUBLISHABLE_KEY` | Yes (React) | Frontend | A public, frontend-only key. Supply it from the frontend's own env (`VITE_STRIPE_PUBLISHABLE_KEY` / `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`) and pass it as the `publishableKey` prop to the React components. It is **not** a component env var. |
5
+ | Variable | Required | Read by | Description |
6
+ | -------------------------- | ----------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7
+ | `STRIPE_SECRET_KEY` | Yes | Component | Declared in the component's `convex.config.ts` (required) and read by the component (e.g. `getStripeMode`). Also passed explicitly via the `BetterStripe` constructor and `registerRoutes`. The installing app must wire it to the component — see below. |
8
+ | `STRIPE_WEBHOOK_SECRET` | Yes | App | Signing secret for the V1 snapshot event destination. Read by `registerRoutes` in the app, not the component. |
9
+ | `STRIPE_WEBHOOK_SECRET_V2` | No\* | App | Signing secret for the V2 thin event destination (Connect account events). \*Required whenever your V2 destination has its own secret (the usual case); falls back to `STRIPE_WEBHOOK_SECRET` if unset. |
10
+ | `STRIPE_PUBLISHABLE_KEY` | Yes (React) | Frontend | A public, frontend-only key. Supply it from the frontend's own env (`VITE_STRIPE_PUBLISHABLE_KEY` / `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`) and pass it as the `publishableKey` prop to the React components. The component also accepts it optionally through `app.use` for `stripe.getPublishableKey`; frontend props still need the public key explicitly. |
11
11
 
12
12
  ### Wiring component env vars
13
13
 
@@ -40,11 +40,39 @@ the deployment env — no `app.use` wiring required.
40
40
 
41
41
  ### Stripe API Version
42
42
 
43
- The component pins the Stripe API version internally (`2026-09-30.endive`) using the installed stripe-node 23 SDK's exact API-version type. Upgrading the pinned version requires a package release and changelog entry. Apps do not need to set `STRIPE_API_VERSION`. See [the migration notes](../MIGRATION.md) for removing Dojo's fulfillment-retry patch and upgrading webhook payload versions separately.
43
+ The default API version is `2026-09-30.endive`. The supported customer-only
44
+ Accounts v2 opt-in is `STRIPE_CUSTOMER_PREVIEW_API_VERSION`, currently
45
+ `2026-09-30.preview`. Other values are rejected. This is a constructor option,
46
+ not a `STRIPE_API_VERSION` environment variable. Account eligibility and request
47
+ version are separate requirements; read [Accounts v2 setup](accounts-v2-preview.md).
48
+
49
+ ```ts
50
+ import {
51
+ BetterStripe,
52
+ STRIPE_CUSTOMER_PREVIEW_API_VERSION,
53
+ } from "@fantastic.dev/better-stripe";
54
+ import { components } from "./_generated/api";
55
+
56
+ export const stripe = new BetterStripe(components.betterStripe, {
57
+ STRIPE_SECRET_KEY: process.env.STRIPE_SECRET_KEY,
58
+ // Omit for the default Connect/GA integration.
59
+ stripeApiVersion: STRIPE_CUSTOMER_PREVIEW_API_VERSION,
60
+ });
61
+ ```
62
+
63
+ Use `stripe.registerRoutes(http, config)` to inherit this client's key/version,
64
+ or pass the same `stripeApiVersion` explicitly to standalone `registerRoutes`.
65
+ Pin snapshot event destinations to the matching version. Changing package
66
+ defaults follows the release process; upgrading a client does not migrate existing
67
+ provider destinations. See [migration notes](../MIGRATION.md).
44
68
 
45
69
  ### SDK Management
46
70
 
47
- The component owns the Stripe SDK instance internally via a keyed client cache (keyed by API key). Apps pass `STRIPE_SECRET_KEY`; the component handles versioning and client lifecycle. Apps should not create their own Stripe SDK instances for operations that go through the component.
71
+ The package manages Stripe clients for its public operations. The shared client
72
+ cache is keyed by API key and supported API version. Durable provider adapters
73
+ can create isolated clients with their own retry policy. Pass credentials through
74
+ the documented constructor or internal provider-action boundary; do not journal
75
+ secrets or duplicate the package's Stripe operations in host code.
48
76
 
49
77
  ## TypeScript setup
50
78
 
@@ -2,9 +2,14 @@
2
2
 
3
3
  ### Development toolchain
4
4
 
5
- Install with `pnpm install` from the repository root, then run `pnpm build`
6
- and `pnpm dev` to start the example at http://localhost:5173. The example needs
7
- Node.js 22.12+ and a configured Convex development deployment; see
5
+ Use Node.js 24, as CI does, and the pinned pnpm version in `package.json`.
6
+ The package supports Node.js 20+, but the Vite example requires Node.js 22.12+.
7
+ From the repository root, run `pnpm install --frozen-lockfile` and
8
+ `pnpm run build:clean`. After configuring the example's existing Convex development
9
+ deployment, `pnpm dev` starts its backend watcher and Vite frontend. Use the
10
+ localhost URL Vite prints, normally http://localhost:5173. For a frontend-only
11
+ server against an already deployed backend, run `pnpm run dev:frontend` from
12
+ `example/`. See
8
13
  [the example setup guide](https://github.com/FantasticDevHQ/better-stripe/blob/main/example/README.md).
9
14
 
10
15
  The BetterStripe example separates visitor, customer, affiliate, seller, and
@@ -37,7 +42,8 @@ See [affiliate configuration and testing](https://github.com/FantasticDevHQ/bett
37
42
 
38
43
  The public React exports include `AffiliatePayoutEditor`, `PlanPricingEditor`,
39
44
  `Pagination`, and `useCursorPagination`. The example supplies styling through
40
- render props; its backend owns authorization, rule inheritance, and transfers.
45
+ render props; its backend owns authorization and rule inheritance. The package owns durable
46
+ transfer execution, retained financial records and provider reconciliation.
41
47
  See [the workflow reference](react-workflows.md#percentage-or-fixed-affiliate-payouts)
42
48
  and [the UI reuse audit](react-workflows-audit.md).
43
49
 
@@ -46,6 +52,14 @@ formatting, typechecks, codegen drift check, tests, and repository quality gates
46
52
  used by CI. Policy lives in `repo-gates.config.json`; measured baselines live in
47
53
  `gates/`. Fix failures without weakening the gates or raising existing budgets.
48
54
 
55
+ Use `pnpm run check:package` to clean/rebuild the package and run the artifact
56
+ checks in one command. It verifies public documentation imports and local links,
57
+ recursively linked guides in the actual tarball, and extracted usage consumers
58
+ for public types, runtime accounting and React rendering. It uses deterministic
59
+ fixtures without provider credentials or deployment changes. Native component
60
+ analysis remains a separate authorized development probe in
61
+ [the usage handoff evidence](https://github.com/FantasticDevHQ/better-stripe/tree/main/docs/evidence/usage-handoff).
62
+
49
63
  Coverage checks enforce the committed floors in `gates/coverage-budgets.json`.
50
64
  `pnpm run check:coverage` and `pnpm run check:all` never edit that file or fail
51
65
  because coverage improved. Ordinary feature PRs should leave the budget file alone.
@@ -104,7 +118,13 @@ pnpm codegen:lib # regen src/component/_generated only
104
118
  pnpm codegen:example # regen example/convex/_generated only
105
119
  ```
106
120
 
107
- All three require a configured dev deployment (`CONVEX_DEPLOYMENT` env var, normally set by a prior `npx convex dev`). They write only the local `_generated/` files — they don't push code or data to the deployment.
121
+ All three require a configured dev deployment, normally selected by a prior
122
+ `pnpm exec convex dev` from `example/`. They generate local bindings and, for
123
+ components, upload and analyze definitions against the selected development
124
+ deployment. Codegen does not replace its serving application or run a data
125
+ migration; deploying updated handlers still requires `convex dev` or
126
+ `convex dev --once` from `example/`. Keep secrets and deployment-key overrides
127
+ out of the wrong terminal. See [safe development selection](metering-setup.md#run-the-repository-example).
108
128
 
109
129
  **CI gate.** Two layers verify the committed files are not stale:
110
130