@fantastic.dev/better-stripe 0.45.0 → 0.45.2
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 +14 -0
- package/MIGRATION.md +6 -4
- package/README.md +8 -6
- package/docs/affiliate-clawbacks.md +3 -3
- package/docs/architecture/component-extraction.md +415 -0
- package/docs/architecture/durable-execution.md +200 -0
- package/docs/architecture/recovery-workflow.md +69 -0
- package/docs/balance-funding-state.md +114 -0
- package/docs/balance-funding-workflow.md +53 -0
- package/docs/example-balance-funding-cutover.md +94 -0
- package/docs/example-recovery-cutover.md +21 -0
- package/docs/processing-cost-reconciliation.md +23 -0
- package/docs/release-handoff.md +196 -0
- package/docs/releasing.md +41 -0
- package/package.json +12 -2
- package/src/component/durableExecution/crossDomain.test.ts +241 -0
- package/src/component/durableExecution/crossDomainBoundaries.test.ts +233 -0
- package/src/component/durableExecution/crossDomainDisputes.test.ts +108 -0
- package/src/component/durableExecution/crossDomainMigration.test.ts +192 -0
- package/src/component/durableExecution/crossDomainWebhooks.test.ts +122 -0
- package/src/testing/crossDomain/fixture.ts +96 -0
- package/src/testing/crossDomain/host.ts +288 -0
- package/src/testing/crossDomain/transport.ts +293 -0
package/CHANGELOG.md
CHANGED
|
@@ -26,6 +26,20 @@
|
|
|
26
26
|
- Remove internal tracker references from public documentation and add a
|
|
27
27
|
regression check that prevents their reintroduction.
|
|
28
28
|
|
|
29
|
+
## [0.45.2](https://github.com/FantasticDevHQ/better-stripe/compare/v0.45.1...v0.45.2) (2026-10-17)
|
|
30
|
+
|
|
31
|
+
### Bug Fixes
|
|
32
|
+
|
|
33
|
+
- ship complete migration guides and release handoff ([a619b66](https://github.com/FantasticDevHQ/better-stripe/commit/a619b66335d1898fadf6790bc8b878ad7324ce57))
|
|
34
|
+
- ship workflow migration guides and release handoff ([08c870c](https://github.com/FantasticDevHQ/better-stripe/commit/08c870cdcc8cb5e841b0ca522cd58ce8867a7270))
|
|
35
|
+
|
|
36
|
+
## [0.45.1](https://github.com/FantasticDevHQ/better-stripe/compare/v0.45.0...v0.45.1) (2026-10-17)
|
|
37
|
+
|
|
38
|
+
### Tests
|
|
39
|
+
|
|
40
|
+
- verify cross-domain durable execution invariants ([392080f](https://github.com/FantasticDevHQ/better-stripe/commit/392080f5d166ad731864ac0db4897fe6a1b7de63))
|
|
41
|
+
- verify cross-domain durable execution invariants ([c814519](https://github.com/FantasticDevHQ/better-stripe/commit/c8145194ac0b9fb51b92109ffd2d6be5cf44488f))
|
|
42
|
+
|
|
29
43
|
## [0.45.0](https://github.com/FantasticDevHQ/better-stripe/compare/v0.44.0...v0.45.0) (2026-10-17)
|
|
30
44
|
|
|
31
45
|
### Features
|
package/MIGRATION.md
CHANGED
|
@@ -1,4 +1,6 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Upgrading BetterStripe and Stripe Endive
|
|
2
|
+
|
|
3
|
+
This guide describes the current source API. Select a reviewed, published package version through the normal release process; a merged PR or local tarball is not proof of npm publication. See the [component migration and release handoff](docs/release-handoff.md) before switching existing financial workers.
|
|
2
4
|
|
|
3
5
|
## Combined payout eligibility preview
|
|
4
6
|
|
|
@@ -35,7 +37,7 @@ null after upgrading these readers. Component bindings must be regenerated and
|
|
|
35
37
|
the component deployed; no table migration or schedule change is required.
|
|
36
38
|
See [collection restart safeguards](docs/settlement.md#resumable-local-collections).
|
|
37
39
|
|
|
38
|
-
Install `@fantastic.dev/better-stripe
|
|
40
|
+
Install the reviewed, published version of `@fantastic.dev/better-stripe`. The old
|
|
39
41
|
`@getdojo/better-stripe` name is deprecated. Replace imports and the component
|
|
40
42
|
config import with the new name, retaining your existing component instance
|
|
41
43
|
name (for example `betterStripe`) so its stored data remains attached. Run
|
|
@@ -45,8 +47,8 @@ Node.js 20 or newer is required by stripe-node 23.
|
|
|
45
47
|
The package depends on `stripe ~23.0.0`, whose supported API is exactly
|
|
46
48
|
`2026-09-30.endive`. The typed `STRIPE_API_VERSION` constant in
|
|
47
49
|
`src/client/constants.ts` pins app clients, component actions, and webhook
|
|
48
|
-
resource refreshes. This SDK and pin
|
|
49
|
-
|
|
50
|
+
resource refreshes. This SDK and pin predate the durable workflow extraction. Review the chosen
|
|
51
|
+
release's changelog for its fulfillment retry and V2/React compatibility changes.
|
|
50
52
|
Leave `stripeApiVersion` unset to use this pin. The legacy string override is
|
|
51
53
|
retained for compatibility, but overriding it does not change the SDK's types
|
|
52
54
|
or convert webhook payloads and can make requests inconsistent with them.
|
package/README.md
CHANGED
|
@@ -4,6 +4,8 @@ A reusable [Convex component](https://docs.convex.dev/components) for the Stripe
|
|
|
4
4
|
|
|
5
5
|
Built for Convex + Next.js applications. Follows the conventions established by [`@convex-dev/stripe`](https://github.com/get-convex/stripe) and [`@convex-dev/better-auth`](https://github.com/get-convex/better-auth).
|
|
6
6
|
|
|
7
|
+
For the component extraction upgrade, see the [migration and release handoff](docs/release-handoff.md), including nested runtime wiring, held operations and rollback boundaries.
|
|
8
|
+
|
|
7
9
|
## Accounts v2 customer preview
|
|
8
10
|
|
|
9
11
|
Choose the setup that matches your Stripe account:
|
|
@@ -70,7 +72,7 @@ claim execution are completed.
|
|
|
70
72
|
|
|
71
73
|
## Status
|
|
72
74
|
|
|
73
|
-
**Version**: `0.45.
|
|
75
|
+
**Version**: `0.45.2` <!-- x-release-please-version --> (pre-1.0). API may change between minor versions until 1.0.
|
|
74
76
|
|
|
75
77
|
Used in production by its authors. Webhook pipeline is covered by unit tests and a live E2E harness (`npm run e2e:webhooks`) that fires real Stripe-signed events and asserts the ledger.
|
|
76
78
|
|
|
@@ -98,7 +100,7 @@ The private `example` workspace isn't published.
|
|
|
98
100
|
Install with `pnpm install` from the repository root, then run `pnpm build`
|
|
99
101
|
and `pnpm dev` to start the example at http://localhost:5173. The example needs
|
|
100
102
|
Node.js 22.12+ and a configured Convex development deployment; see
|
|
101
|
-
[the example setup guide](example/README.md).
|
|
103
|
+
[the example setup guide](https://github.com/FantasticDevHQ/better-stripe/blob/main/example/README.md).
|
|
102
104
|
|
|
103
105
|
The BetterStripe example separates visitor, customer, affiliate, seller, and
|
|
104
106
|
platform-admin workflows. Fresh fictional Maya and Sasha stores explicitly
|
|
@@ -117,7 +119,7 @@ Hosted Checkout, Embedded Checkout, custom Checkout Sessions with Payment Elemen
|
|
|
117
119
|
Payment Intents with Payment Element, and the preview Embedded Checkout Form,
|
|
118
120
|
with pros and cons for each. `createCheckoutSession` accepts `uiMode` values
|
|
119
121
|
`"redirect"`, `"embedded"`, `"custom"`, and `"form"`; the latter two map to Stripe's
|
|
120
|
-
`elements` and preview `form` modes. See [the integration examples](example/README.md#compare-integration-styles).
|
|
122
|
+
`elements` and preview `form` modes. See [the integration examples](https://github.com/FantasticDevHQ/better-stripe/blob/main/example/README.md#compare-integration-styles).
|
|
121
123
|
|
|
122
124
|
Admins can configure store-plan monthly prices and sale fees. Monthly price changes
|
|
123
125
|
create new Stripe Prices; existing store subscriptions keep their current price.
|
|
@@ -126,7 +128,7 @@ optional price, product, store, plan, and platform defaults. Unconfigured payout
|
|
|
126
128
|
are zero. Subscription commission terms are **Forever** or **One-time**, with
|
|
127
129
|
Forever as the default. The example saves the selected term in Stripe subscription
|
|
128
130
|
metadata and its Convex ledger, then applies it when paid invoices settle.
|
|
129
|
-
See [affiliate configuration and testing](example/README.md#seller-product-and-subscription-affiliate-payouts).
|
|
131
|
+
See [affiliate configuration and testing](https://github.com/FantasticDevHQ/better-stripe/blob/main/example/README.md#seller-product-and-subscription-affiliate-payouts).
|
|
130
132
|
|
|
131
133
|
The public React exports include `AffiliatePayoutEditor`, `PlanPricingEditor`,
|
|
132
134
|
`Pagination`, and `useCursorPagination`. The example supplies styling through
|
|
@@ -355,7 +357,7 @@ presentation and confirmation, not financial authorization. Do not use closure
|
|
|
355
357
|
as an automatic delete-and-recreate onboarding reset. Existing active-account
|
|
356
358
|
getters keep their signatures and exclude completed closures; historical readers
|
|
357
359
|
retain original financial references. The Vite reference's
|
|
358
|
-
[closed-account authorization example](example/README.md#closed-account-history)
|
|
360
|
+
[closed-account authorization example](https://github.com/FantasticDevHQ/better-stripe/blob/main/example/README.md#closed-account-history)
|
|
359
361
|
shows where the host's authenticated-actor check belongs.
|
|
360
362
|
|
|
361
363
|
| Method | Description |
|
|
@@ -1717,7 +1719,7 @@ Error codes: `ACCOUNT_NOT_FOUND`, `ACCOUNT_CREATE_FAILED`, `PRODUCT_NOT_FOUND`,
|
|
|
1717
1719
|
- [Convex Component Authoring](https://docs.convex.dev/components/authoring)
|
|
1718
1720
|
- [Stripe Webhook Event Reference](https://docs.stripe.com/api/events/types)
|
|
1719
1721
|
- [Stripe Testing Guide](https://docs.stripe.com/testing)
|
|
1720
|
-
- [Example checkout tests](example/README.md#test-the-integration-examples), including successful payments, declines, insufficient funds, and 3D Secure
|
|
1722
|
+
- [Example checkout tests](https://github.com/FantasticDevHQ/better-stripe/blob/main/example/README.md#test-the-integration-examples), including successful payments, declines, insufficient funds, and 3D Secure
|
|
1721
1723
|
|
|
1722
1724
|
## License
|
|
1723
1725
|
|
|
@@ -285,9 +285,9 @@ refund/dispute ordering, partial disputes, lost/won events, receipt matching,
|
|
|
285
285
|
payout reservations, migration and ownership enforcement. React tests verify
|
|
286
286
|
native/headless figures and unconfirmed restoration states.
|
|
287
287
|
|
|
288
|
-
[Verification report](evidence/affiliate-recovery-verification.md),
|
|
289
|
-
[UI recording](evidence/affiliate-recovery.webm) and
|
|
290
|
-
[screenshot](evidence/affiliate-recovery.png) show simulated fixtures and both
|
|
288
|
+
[Verification report](https://github.com/FantasticDevHQ/better-stripe/blob/main/docs/evidence/affiliate-recovery-verification.md),
|
|
289
|
+
[UI recording](https://github.com/FantasticDevHQ/better-stripe/blob/main/docs/evidence/affiliate-recovery.webm) and
|
|
290
|
+
[screenshot](https://github.com/FantasticDevHQ/better-stripe/blob/main/docs/evidence/affiliate-recovery.png) show simulated fixtures and both
|
|
291
291
|
presentations. Reproduce with the frontend running, from `example/`:
|
|
292
292
|
|
|
293
293
|
```sh
|
|
@@ -0,0 +1,415 @@
|
|
|
1
|
+
# Component extraction and durable execution contracts
|
|
2
|
+
|
|
3
|
+
Status: accepted design record. The implementation and cross-domain acceptance
|
|
4
|
+
suite have merged. The proposal sections below preserve the design
|
|
5
|
+
history reviewed against main `e9994a9`; their illustrative signatures are not
|
|
6
|
+
an export inventory. Use the [release handoff](../release-handoff.md) and linked
|
|
7
|
+
domain guides for the implemented APIs, defaults and migration boundaries.
|
|
8
|
+
|
|
9
|
+
## Ownership decision
|
|
10
|
+
|
|
11
|
+
BetterStripe owns reusable Stripe protocols, provider verification, immutable
|
|
12
|
+
financial allocations, recovery reservations and durable operation state. The
|
|
13
|
+
host authenticates callers and selects business policy before invoking them.
|
|
14
|
+
Opaque host identifiers never imply authorization.
|
|
15
|
+
|
|
16
|
+
| Workstream | Package responsibility | Host responsibility |
|
|
17
|
+
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
|
|
18
|
+
| Balance funding | Persist restoration settings, serialize a subscription operation, apply and verify provider changes | Authorize subscription/account, capture consent, choose enable/disable |
|
|
19
|
+
| Recovery preparation | Atomically reserve a bounded batch and seal when complete | Select same-currency scope, source and debit/credit policy |
|
|
20
|
+
| Settlement/recovery execution | Resume original allocations, reconcile provider receipts, finish existing ledgers | Select recipients, rates, eligible sales and uncollectible policy |
|
|
21
|
+
| Processing costs | Verify original funding provenance, calculate an explicitly selected liability policy, reconcile claim revisions | Decide who owes retained processing/dispute costs |
|
|
22
|
+
| Catalog, portal and accounts | Typed Stripe calls, lookup-key adoption, scoped cache refresh, capability normalization | Tier names, product allowlists, proration/cancellation policy, merchant eligibility |
|
|
23
|
+
| Reporting and scheduling | Bounded component readers and operation status | User/store joins, entitlements, referral attribution, projections and cron cadence |
|
|
24
|
+
|
|
25
|
+
Do not copy `storeSales`, `sellerCosts`, `storePlanCatalog` or `users` into the
|
|
26
|
+
component. Keep host IDs as strings only where needed for correlation. Never
|
|
27
|
+
parse `example:store:*`, role names or tier names in package code. Existing
|
|
28
|
+
settlement, transfer and cost-recovery tables remain the money ledger. A
|
|
29
|
+
workflow journal records execution progress, not a second balance.
|
|
30
|
+
|
|
31
|
+
## Public contract conventions
|
|
32
|
+
|
|
33
|
+
New methods live on domain clients and take `ctx` plus a validated options
|
|
34
|
+
object. Existing `costRecovery` methods and stateless `prepareBalanceFunding`
|
|
35
|
+
and `setBalanceFunding` remain available during migration. New orchestration
|
|
36
|
+
methods must not silently change their behavior or automatically enable preview
|
|
37
|
+
features. The following signatures specify the interfaces to implement.
|
|
38
|
+
Referenced existing types retain their definitions in the linked source files
|
|
39
|
+
below.
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
type OperationScope = {
|
|
43
|
+
accountId: string;
|
|
44
|
+
scopeKey: string; // Host-selected opaque correlation key.
|
|
45
|
+
};
|
|
46
|
+
type OperationRef = OperationScope & {
|
|
47
|
+
operationId: string; // Durable, unique within this component installation.
|
|
48
|
+
version: number; // Positive safe integer, not a queue attempt count.
|
|
49
|
+
};
|
|
50
|
+
type Unavailable =
|
|
51
|
+
| {
|
|
52
|
+
status: "not_ready";
|
|
53
|
+
reason: "provider_pending" | "fee_pending" | "history_incomplete";
|
|
54
|
+
retryable: true;
|
|
55
|
+
}
|
|
56
|
+
| {
|
|
57
|
+
status: "conflict";
|
|
58
|
+
reason: "scope_busy" | "revision_changed" | "identity_changed";
|
|
59
|
+
retryable: false;
|
|
60
|
+
}
|
|
61
|
+
| {
|
|
62
|
+
status: "rejected";
|
|
63
|
+
reason: "invalid_scope" | "unsupported_source" | "policy_invalid";
|
|
64
|
+
retryable: false;
|
|
65
|
+
};
|
|
66
|
+
type OperationStatus = OperationRef & {
|
|
67
|
+
state:
|
|
68
|
+
"pending" | "running" | "unknown" | "succeeded" | "failed" | "canceled";
|
|
69
|
+
cancelRequested: boolean;
|
|
70
|
+
failureCode?: string; // Safe package code, never a raw provider message.
|
|
71
|
+
};
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The shared outcomes workstream owns shared outcomes and adapters for existing
|
|
75
|
+
readiness types. Preserve existing result shapes; add explicit conversions where
|
|
76
|
+
needed. A caller handles `scope_busy` by reading the active operation, and
|
|
77
|
+
`revision_changed` by reading fresh state and asking policy to decide. They
|
|
78
|
+
never trigger blind action retries. Provider transport errors retain their
|
|
79
|
+
identity internally. A provider write with an uncertain outcome moves the
|
|
80
|
+
operation to `unknown`; it is not a successful, rejected or canceled money
|
|
81
|
+
movement. Exhausted bounded history stays unknown.
|
|
82
|
+
|
|
83
|
+
The additive SDK adapters return `FinancialOutcome<T>`, with ready data in
|
|
84
|
+
`value`, and preserve existing reader result shapes. The shared
|
|
85
|
+
`FinancialUnavailable` contract extends the examples above with terminal
|
|
86
|
+
`payment_not_payable` and `currency_mismatch` reasons. It also exposes
|
|
87
|
+
`unknown/provider_outcome_unknown` and `unknown/history_incomplete`, both
|
|
88
|
+
nonretryable. Unknown writes require reconciliation, including after bounded
|
|
89
|
+
history exhaustion. The pure retry decision accepts only validated pending
|
|
90
|
+
outcomes and explicit limits. See [financial readiness](../read-contracts.md#financial-readiness-and-bounded-retries).
|
|
91
|
+
|
|
92
|
+
Derive account, subscription, invoice and source identities on the server.
|
|
93
|
+
Validate complete immutable arguments on every replay, including currency,
|
|
94
|
+
target, provider version and policy snapshot. Status/cancel lookups must match
|
|
95
|
+
the saved account and scope; an operation ID alone never selects a foreign
|
|
96
|
+
scope. All amounts and revisions use checked safe integers. A missing fee is not
|
|
97
|
+
zero. Reject mixed currency and unsupported funding provenance before reserving
|
|
98
|
+
or transferring money.
|
|
99
|
+
|
|
100
|
+
## Balance-funding state and execution
|
|
101
|
+
|
|
102
|
+
The funding state workstream owns component state under
|
|
103
|
+
`src/component/balanceFunding/`; the funding workflow workstream owns provider
|
|
104
|
+
orchestration and its domain client. Use these additive method contracts:
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
// Server-only. preparation is the existing BalanceFundingPreparation type.
|
|
108
|
+
balanceFunding.prepare(ctx, {
|
|
109
|
+
accountId,
|
|
110
|
+
scopeKey,
|
|
111
|
+
stripeSubscriptionId,
|
|
112
|
+
consent: true,
|
|
113
|
+
requestKey,
|
|
114
|
+
}); // => OperationStatus | Unavailable, saves intent before provisioning
|
|
115
|
+
balanceFunding.savePreparation(ctx, {
|
|
116
|
+
accountId,
|
|
117
|
+
scopeKey,
|
|
118
|
+
preparation,
|
|
119
|
+
consentAt,
|
|
120
|
+
}); // => { preparationId: string }, exact replay returns the same record
|
|
121
|
+
balanceFunding.begin(ctx, {
|
|
122
|
+
accountId,
|
|
123
|
+
scopeKey,
|
|
124
|
+
preparationId,
|
|
125
|
+
enabled,
|
|
126
|
+
consent,
|
|
127
|
+
requestKey,
|
|
128
|
+
}); // => { status: "accepted", operation: OperationRef }
|
|
129
|
+
// or { status: "unchanged", enabled } or Unavailable
|
|
130
|
+
balanceFunding.start(ctx, { ...operation }); // => OperationStatus
|
|
131
|
+
balanceFunding.getOperation(ctx, { ...operation }); // => OperationStatus | null
|
|
132
|
+
balanceFunding.requestCancel(ctx, { ...operation }); // => OperationStatus
|
|
133
|
+
|
|
134
|
+
type PreparationLookup =
|
|
135
|
+
| {
|
|
136
|
+
status: "prepared";
|
|
137
|
+
operation: OperationRef;
|
|
138
|
+
stripeSubscriptionId: string;
|
|
139
|
+
preparationId: string;
|
|
140
|
+
}
|
|
141
|
+
| {
|
|
142
|
+
status: "pending" | "running" | "unknown" | "failed" | "canceled";
|
|
143
|
+
operation: OperationRef;
|
|
144
|
+
};
|
|
145
|
+
balanceFunding.getPreparation(ctx, {
|
|
146
|
+
...operation, // Account, scope, operation ID and version are all required.
|
|
147
|
+
stripeSubscriptionId,
|
|
148
|
+
}); // => PreparationLookup | Unavailable | null
|
|
149
|
+
|
|
150
|
+
balanceFunding.findPreparationOperation(ctx, {
|
|
151
|
+
accountId,
|
|
152
|
+
scopeKey,
|
|
153
|
+
stripeSubscriptionId,
|
|
154
|
+
requestKey,
|
|
155
|
+
providerApiVersion,
|
|
156
|
+
consent: true,
|
|
157
|
+
}); // => OperationStatus | Unavailable | null; read-only request recovery
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
`getPreparation` reads the result of an existing preparation operation. It never
|
|
161
|
+
provisions a payment method or captures restoration settings. It validates the
|
|
162
|
+
saved account, subscription, scope, operation ID and version together; an
|
|
163
|
+
existing foreign or contradictory binding returns `invalid_scope` or
|
|
164
|
+
`identity_changed`, never a foreign preparation reference. `null` means no
|
|
165
|
+
matching operation was found, not proof that a provider write did not happen or
|
|
166
|
+
permission to start a new one. Pending, running, unknown, failed and canceled
|
|
167
|
+
results expose no preparation ID. Only a successfully verified and durably
|
|
168
|
+
saved preparation returns `prepared`, with the original server-owned ID.
|
|
169
|
+
Replays keep that result stable. Status and lookup results expose neither
|
|
170
|
+
restoration settings nor credentials.
|
|
171
|
+
|
|
172
|
+
Before recapturing provider settings or consent time, the runtime queries
|
|
173
|
+
`findPreparationOperation` with the original public request key. It validates
|
|
174
|
+
saved prepare-kind, account, scope, subscription, API version and consent binding,
|
|
175
|
+
returning only safe operation identity/state. Unknown or failed intents retain
|
|
176
|
+
their original identity; a new key never permits recapturing already-enabled
|
|
177
|
+
restoration or replacing unresolved preparation. A null lookup is not proof that
|
|
178
|
+
no provider effect happened. Full low-level captured snapshots remain immutable.
|
|
179
|
+
|
|
180
|
+
If a prepare response is lost, repeat `prepare` with the original request key
|
|
181
|
+
and unchanged payload to recover the same operation, then call `getPreparation`
|
|
182
|
+
for its reference. Hold pending or unknown work and reconcile that operation;
|
|
183
|
+
do not create another payment method. Pass the returned preparation ID to
|
|
184
|
+
`begin`. `begin` independently validates its saved account/subscription binding
|
|
185
|
+
and verified state before accepting the new setting intent. A browser-supplied
|
|
186
|
+
ID alone proves neither ownership nor readiness. `savePreparation` remains the
|
|
187
|
+
explicit path for verified legacy imports, not the new preparation handoff.
|
|
188
|
+
|
|
189
|
+
`accountId` must equal the preparation's `customerAccount`; scope identifies one
|
|
190
|
+
subscription. Enforce one active operation per account/subscription even if a
|
|
191
|
+
host supplies a different scope alias. The component validates that binding and
|
|
192
|
+
refuses conflicting preparation data. Capture original payment-method ID and
|
|
193
|
+
payment-method types once, including null versus empty values. Never recapture
|
|
194
|
+
restoration settings from an already enabled subscription. A changed
|
|
195
|
+
subscription needs an explicit new preparation after the old operation is
|
|
196
|
+
reconciled, not an overwrite.
|
|
197
|
+
|
|
198
|
+
`requestKey` identifies one host intent. The component binds it to the complete
|
|
199
|
+
payload. The same request returns the same operation even after completion; a
|
|
200
|
+
changed payload conflicts. A completed disable followed by a new enable uses a
|
|
201
|
+
new request key and operation version. Same-target calls while pending reuse the
|
|
202
|
+
active operation; opposing targets conflict. An already satisfied state may
|
|
203
|
+
return unchanged only when no unresolved operation exists.
|
|
204
|
+
|
|
205
|
+
Begin durably before any provider write. Persist a stable provider key per
|
|
206
|
+
phase, including prepare/create/attach and apply/enable/disable. Preparation
|
|
207
|
+
provisioning also needs a durable intent before provisioning so a lost prepare
|
|
208
|
+
response cannot create another payment method. The `prepare` entry point owns
|
|
209
|
+
that intent and saves the original settings before create/attach. Keep
|
|
210
|
+
`savePreparation` for verified legacy records. Replays use the saved restoration
|
|
211
|
+
and request snapshot.
|
|
212
|
+
|
|
213
|
+
The completion mutation compares operation identity, version, target and
|
|
214
|
+
provider receipt before updating the setting. An old action cannot finish a
|
|
215
|
+
newer version. If Stripe succeeds but the finish mutation fails, read current
|
|
216
|
+
subscription and payment-method ownership and reconcile the same operation.
|
|
217
|
+
External changes that match neither original nor intended settings produce an
|
|
218
|
+
explicit conflict. A configured preview API version is required at prepare and
|
|
219
|
+
apply time. A runtime must carry the selected API version and request scope
|
|
220
|
+
through all action steps. The runtime composition workstream must prove a
|
|
221
|
+
supported credential execution boundary. Do not assume a nested component can
|
|
222
|
+
read host environment variables. One supported design may invoke a host provider
|
|
223
|
+
action reference that creates the SDK from runtime host environment and returns
|
|
224
|
+
only a nonsecret validated receipt. If component-local credential access is
|
|
225
|
+
unsupported, keep ledgers and orchestration component-owned while provider steps
|
|
226
|
+
run in those host actions. Redact secrets from action results, durable
|
|
227
|
+
arguments, journals, status and logs. Never persist Stripe secrets in workflow
|
|
228
|
+
arguments or copy them into operation state.
|
|
229
|
+
|
|
230
|
+
## Atomic recovery preparation
|
|
231
|
+
|
|
232
|
+
The recovery preparation workstream adds the following method to the existing
|
|
233
|
+
cost-recovery client:
|
|
234
|
+
|
|
235
|
+
```ts
|
|
236
|
+
costRecovery.prepareGroup(ctx, {
|
|
237
|
+
...groupOptions, // Existing RecoveryGroupOptions, including currency and limits.
|
|
238
|
+
limit: 100, // Optional, same bounded validation as reserve.
|
|
239
|
+
});
|
|
240
|
+
// => { status: "prepared", group, isDone: boolean } | Unavailable
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Each invocation runs one component mutation. It checks immutable group identity
|
|
244
|
+
and active-scope ownership, derives the next reservation identity, reserves at
|
|
245
|
+
most the permitted batch and seals only when the target equals the reserved
|
|
246
|
+
amount. A sealed group's replay returns the original group with `isDone: true`.
|
|
247
|
+
An open group returns `isDone: false` until another bounded invocation
|
|
248
|
+
completes. Do not derive batch IDs in host code from an independently read
|
|
249
|
+
`pendingOperations`. Persist or derive a monotonic batch sequence in the atomic
|
|
250
|
+
mutation; empty batches and finished reservations cannot recycle an old ID.
|
|
251
|
+
|
|
252
|
+
Preserve the existing signed accounting equation for each claim and balance:
|
|
253
|
+
`amountDue = collectedAmount + reservedAmount + outstanding`. Claim updates use
|
|
254
|
+
revision checks. Group identity, source gross/fees, currency and debit/credit
|
|
255
|
+
limits cannot change on retry. The active group excludes another boundary for
|
|
256
|
+
the same account/scope/currency through transactional state, not queue
|
|
257
|
+
concurrency. A foreign active group returns `scope_busy`. The host may choose to
|
|
258
|
+
defer recovery for an otherwise eligible sale; the package never chooses that
|
|
259
|
+
business policy.
|
|
260
|
+
|
|
261
|
+
The recovery workflow workstream adds `costRecovery.startGroup(ctx, { ...scope,
|
|
262
|
+
groupKey, requestKey, releaseUncollectible })` returning `OperationStatus |
|
|
263
|
+
Unavailable`. Preparation must finish before execution. Resolve the source kind
|
|
264
|
+
from the sealed group; never infer it from metadata strings. The settlement
|
|
265
|
+
caller provides its separately pinned allocation to existing settlement
|
|
266
|
+
execution, including the sealed recovery adjustment. Verify the same group's
|
|
267
|
+
scope and authorized adjustment before use. Invoice collection reuses
|
|
268
|
+
`attachInvoice` and `reconcileInvoice`. Preserve the explicit uncollectible-
|
|
269
|
+
release policy and bounded `finish` continuation. A failed workflow never
|
|
270
|
+
automatically releases an uncertain reservation.
|
|
271
|
+
|
|
272
|
+
The provenance resolver workstream resolves original
|
|
273
|
+
invoice/payment/subscription/price provenance with bounded complete provider
|
|
274
|
+
history and typed unavailable outcomes. Reject partial or ambiguous funding
|
|
275
|
+
instead of guessing. The explicit-policy pure deficit helper requires explicit
|
|
276
|
+
liability and rounding policy. The processing-cost reconciliation workstream
|
|
277
|
+
uses both in revision-guarded cost claim reconciliation and retains the original
|
|
278
|
+
recovery receipt for rollback. Current tier prices, affiliate rates or webhook
|
|
279
|
+
arrival order cannot rewrite an original allocation or prove original funding.
|
|
280
|
+
|
|
281
|
+
## Durable execution decision and composition exit gate
|
|
282
|
+
|
|
283
|
+
Use [Workflow](https://github.com/convex/workflow) for multi-step funding and
|
|
284
|
+
recovery sequences. Keep handlers deterministic and perform provider I/O in
|
|
285
|
+
action steps. Workflow already uses Workpool for step scheduling. Add a separate
|
|
286
|
+
[Workpool](https://github.com/convex/workpool) only for independent bounded jobs
|
|
287
|
+
that need their own concurrency/retry policy. Avoid double-queueing each step.
|
|
288
|
+
|
|
289
|
+
The runtime composition workstream must demonstrate nested installation inside
|
|
290
|
+
BetterStripe with pinned compatible versions, generated references, credential
|
|
291
|
+
access/API-version propagation, start/status/cancel and nested-component test
|
|
292
|
+
registration. Until those checks pass, this is an implementation choice to
|
|
293
|
+
validate, not a compatibility claim. If composition fails, document the specific
|
|
294
|
+
failure and revise this decision before adding a host-owned execution service or
|
|
295
|
+
starting dependent workflows.
|
|
296
|
+
|
|
297
|
+
A pool-wide concurrency cap is capacity control. Component scope claims provide
|
|
298
|
+
serialization. Stripe writes still need stable keys, authoritative
|
|
299
|
+
reconciliation and existing financial ledgers. Retry only classified transient
|
|
300
|
+
or explicitly not-ready steps with bounded attempts/backoff; do not retry every
|
|
301
|
+
financial action by default. Never generate new money-operation IDs in a retried
|
|
302
|
+
step.
|
|
303
|
+
|
|
304
|
+
Cancellation stops future work where possible. An in-flight action can complete.
|
|
305
|
+
Record `cancelRequested` separately, then reconcile its receipt before reporting
|
|
306
|
+
terminal `canceled`. Completed provider effects remain ledger facts;
|
|
307
|
+
cancellation is not refund, reversal or reservation release. Unknown work keeps
|
|
308
|
+
its scope claim until reconciliation. Resume/restart keeps the original
|
|
309
|
+
operation and phase keys. A new workflow-run ID is never permission to repeat a
|
|
310
|
+
provider effect.
|
|
311
|
+
|
|
312
|
+
Persist definition version with operation state. Retain executable old
|
|
313
|
+
definitions until their operations finish or migrate through a tested compatible
|
|
314
|
+
transition. Reject incompatible resumes. Cleanup may remove terminal execution
|
|
315
|
+
history only after durable receipts and replay identities survive elsewhere;
|
|
316
|
+
never delete financial ledgers or key bindings to satisfy workflow retention
|
|
317
|
+
limits.
|
|
318
|
+
|
|
319
|
+
## Migration and rollback
|
|
320
|
+
|
|
321
|
+
The funding cutover workstream imports balance-funding preparations and active
|
|
322
|
+
operations in bounded, idempotent pages. Preserve original restoration values,
|
|
323
|
+
operation version, consent, target and pending state. Preserve exact legacy
|
|
324
|
+
provider keys, including `example_balance_${subscriptionId}_${version}` and
|
|
325
|
+
their phase suffixes. Preserve `example_balance_prepare_${subscriptionId}` for
|
|
326
|
+
interrupted legacy preparation. A new namespace is safe only for genuinely new
|
|
327
|
+
operations. An unknown legacy operation requires reconciliation before switching
|
|
328
|
+
writers.
|
|
329
|
+
|
|
330
|
+
The financial cutover workstream reuses `costRecovery.importClaim` for verified
|
|
331
|
+
opening collections and preserves original claim/group/operation identities.
|
|
332
|
+
Imports use stable source keys and immutable payload comparison. An exact page
|
|
333
|
+
retry is a no-op; conflicting scope, amounts or receipts fail without partial
|
|
334
|
+
writes. Never import a live claim as a new opening balance. Host
|
|
335
|
+
authorization/mapping runs before imports. Use server-side checkpoints and per-
|
|
336
|
+
scope reconciliation, not a browser cursor, as migration evidence. Keep host
|
|
337
|
+
reporting projections replay-safe by source identity.
|
|
338
|
+
|
|
339
|
+
For every scope: pause old entry points that start new effects, retain authorized
|
|
340
|
+
receipt reconciliation and finish for existing operations, reconcile in-flight
|
|
341
|
+
operations, import and verify state, then enable one new writer. Reconciliation
|
|
342
|
+
must retain the original operation and phase keys; it cannot start a replacement
|
|
343
|
+
effect or admit a new intent. Retire the remaining old mutation entry points
|
|
344
|
+
only after the verified handoff accounts for their operations. Queries may
|
|
345
|
+
read projections, but never sum old and new balances. Record migration version
|
|
346
|
+
and source checkpoint. Do not delete legacy restoration/provenance until
|
|
347
|
+
rollback and retention needs end. Rollback first stops new starts, drains or
|
|
348
|
+
reconciles pending work and establishes one owner. Restore old writers only
|
|
349
|
+
after a tested reverse mapping supports new state. Reverting code alone is
|
|
350
|
+
unsafe after new operations exist.
|
|
351
|
+
|
|
352
|
+
## Parallel implementation and integration
|
|
353
|
+
|
|
354
|
+
Each agent claims its ticket, uses an isolated `codex/<issue-number>-<slug>`
|
|
355
|
+
worktree, and starts dependent work only after blockers merge. Domain agents own
|
|
356
|
+
their client/component domain files, schema fragments and co-located tests. Host
|
|
357
|
+
cutover agents own their specified example domains. The contracts workstream
|
|
358
|
+
owns this ADR; the shared outcomes workstream owns shared outcome definitions.
|
|
359
|
+
Resolve interface changes here before implementing incompatible callers.
|
|
360
|
+
|
|
361
|
+
The coordinator is the shared-file integration owner. Serialize edits to
|
|
362
|
+
`src/client/index.ts`, `src/component/schema.ts`,
|
|
363
|
+
`src/component/convex.config.ts`, package manifests/lockfile and
|
|
364
|
+
`_generated/**`. Domain PRs propose minimal shared patches and coordinate them
|
|
365
|
+
before pushing. Integrate each domain's exports and registration with its
|
|
366
|
+
implementation, before dependent cutovers. The release workstream performs final
|
|
367
|
+
consolidation, not the first registration of earlier APIs. Generate types
|
|
368
|
+
through actual codegen; never hand-edit generated files. Do not publish npm or
|
|
369
|
+
operate live money as part of these implementation tickets.
|
|
370
|
+
|
|
371
|
+
## Required acceptance evidence
|
|
372
|
+
|
|
373
|
+
The following are behavioral fixtures for implementation tests, not a new
|
|
374
|
+
parallel model of production state. Domain PRs turn the relevant rows into tests
|
|
375
|
+
against real component mutations/actions. The integration verification
|
|
376
|
+
workstream verifies their combined behavior.
|
|
377
|
+
|
|
378
|
+
| Fixture | Required observation |
|
|
379
|
+
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
380
|
+
| Same request key and payload arrives twice | One operation, one original payload, same phase keys |
|
|
381
|
+
| Prepare response is lost after successful provisioning | Replay finds the same operation; scoped lookup returns the original preparation ID; begin uses it without another create/attach |
|
|
382
|
+
| Preparation lookup is pending, unknown or foreign | No preparation reference or new provider effect; pending/unknown holds and foreign scope rejects |
|
|
383
|
+
| Same key with a different account, currency or target | Conflict before provider mutation |
|
|
384
|
+
| Enable pending, then disable requested | Scope remains owned by enable; disable conflicts |
|
|
385
|
+
| Stripe applies enable, component finish fails | Replay verifies provider state and finishes the original version |
|
|
386
|
+
| Old action finishes after another version | No newer setting or ledger update |
|
|
387
|
+
| Recovery needs 101 claims at batch limit 100 | Two bounded calls, distinct reservation IDs, one sealed target |
|
|
388
|
+
| Empty reservation or already finished group replay | No reused batch identity, extra collection or release |
|
|
389
|
+
| Two recovery groups compete for one scope | One active boundary; loser receives scope_busy |
|
|
390
|
+
| Cancellation races a successful provider call | Receipt reconciled; successful money effect retained |
|
|
391
|
+
| Queue retry occurs after provider key retention expires | Verify full authoritative receipts or hold unknown; never blind recreate |
|
|
392
|
+
| Migration page retries or conflicts | Exact replay is a no-op; conflict rolls back the page |
|
|
393
|
+
| Migration pauses starts with an in-flight provider result | New effects stay paused while original receipt reconciliation and finish remain authorized |
|
|
394
|
+
| Legacy funding is enabled with original card settings | Import preserves card restoration and pending provider key |
|
|
395
|
+
| Definition upgrade resumes an old operation | Compatible old definition runs or explicit hold; no effect replay |
|
|
396
|
+
| Provider history is partial, multi-funded or foreign | Explicit unavailable/rejected result; no inferred zero or guessed source |
|
|
397
|
+
|
|
398
|
+
Run `pnpm run check:all` for every implementation handoff. Preserve all gate
|
|
399
|
+
floors and budgets. Put sanitized logs/results directly in each ready PR and
|
|
400
|
+
report unavailable provider/deployment checks honestly. Unit mocks cannot
|
|
401
|
+
establish live Stripe eligibility or nested deployment compatibility. Require
|
|
402
|
+
sandbox integration evidence for those claims before consumer cutover.
|
|
403
|
+
|
|
404
|
+
## Current source anchors
|
|
405
|
+
|
|
406
|
+
- [Funding provider protocol](../../src/client/billing/balanceFunding.ts) and
|
|
407
|
+
[example pending-operation mutations](../../example/convex/storeBalance/funding/internal/mutations.ts).
|
|
408
|
+
- [Recovery client](../../src/client/costRecovery.ts),
|
|
409
|
+
[reservation and sealing mutations](../../src/component/costRecovery/reservations.ts),
|
|
410
|
+
[sale preparation](../../example/convex/settlement/recovery.ts) and
|
|
411
|
+
[invoice preparation](../../example/convex/sellerCosts/recoveryInvoices/mutations.ts).
|
|
412
|
+
- [Settlement execution](../../src/client/settlement/execution.ts) and
|
|
413
|
+
[existing public settlement contract](../settlement.md).
|
|
414
|
+
- [Component environment configuration](../../src/component/convex.config.ts) and
|
|
415
|
+
[existing read/provider contracts](../read-contracts.md).
|