@fantastic.dev/better-stripe 0.45.1 → 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 +7 -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
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
# Component migration and release handoff
|
|
2
|
+
|
|
3
|
+
This guide covers the component extraction and its verified cross-domain boundaries.
|
|
4
|
+
It describes the reviewed source surface, not a claim that a particular npm
|
|
5
|
+
version has been published. Select the actual reviewed release candidate and
|
|
6
|
+
verify its public artifact before installing it in an application. Existing
|
|
7
|
+
public methods remain available; adopting a durable workflow is an explicit
|
|
8
|
+
host cutover, not an automatic migration on deployment.
|
|
9
|
+
|
|
10
|
+
## Installation and nested runtime
|
|
11
|
+
|
|
12
|
+
Use Node.js 20 or newer and Convex `^1.46.0`. The example development toolchain
|
|
13
|
+
has its own newer Node requirement. BetterStripe pins Workflow `0.4.10` and
|
|
14
|
+
Workpool `0.4.14`; Workflow installs its nested Workpool and Batch Worker.
|
|
15
|
+
Install BetterStripe once under the existing component instance name:
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
// convex/convex.config.ts
|
|
19
|
+
import betterStripe from "@fantastic.dev/better-stripe/convex.config";
|
|
20
|
+
import { defineApp } from "convex/server";
|
|
21
|
+
import { v } from "convex/values";
|
|
22
|
+
|
|
23
|
+
const app = defineApp({ env: { STRIPE_SECRET_KEY: v.string() } });
|
|
24
|
+
app.use(betterStripe, {
|
|
25
|
+
env: { STRIPE_SECRET_KEY: app.env.STRIPE_SECRET_KEY },
|
|
26
|
+
});
|
|
27
|
+
export default app;
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Keep the original instance name when upgrading so stored data remains attached.
|
|
31
|
+
Regenerate app/component bindings using supported Convex codegen in the
|
|
32
|
+
selected development deployment, then validate the application before rollout.
|
|
33
|
+
Do not edit generated references. The native tree is
|
|
34
|
+
`betterStripe/workflow/workpool/batchWorker`; hosts do not install a sibling
|
|
35
|
+
Workpool or enqueue Workflow steps again. The shared manager limits concurrent
|
|
36
|
+
steps to two and disables automatic action retries.
|
|
37
|
+
|
|
38
|
+
Component configuration is consumed by Convex's bundler. Its upstream Batch
|
|
39
|
+
Worker dependency has an extensionless import that is not a supported standalone
|
|
40
|
+
Node ESM entry point. Verify config types and Convex bundling separately from
|
|
41
|
+
ordinary root, React and testing runtime imports. Do not use a raw Node import
|
|
42
|
+
of the config as the installation test.
|
|
43
|
+
|
|
44
|
+
## Public surface and ownership
|
|
45
|
+
|
|
46
|
+
The root, `react`, `testing`, `convex.config`/`convex.config.js` and
|
|
47
|
+
`_generated/component`/`_generated/component.js` package paths are preserved.
|
|
48
|
+
Domain types are exported from the root. Schema tables, functions and nested
|
|
49
|
+
runtime references are registered by the component; host applications keep
|
|
50
|
+
business data and authenticated authorization adapters.
|
|
51
|
+
|
|
52
|
+
| Area | Public entry point | Host responsibility |
|
|
53
|
+
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
|
54
|
+
| Catalog | `adoptProduct`, `getStripePriceByLookupKey`, `ensurePrice` | Product ownership, allowed tiers, immutable price version policy and caller idempotency namespace |
|
|
55
|
+
| Portal and accounts | Portal configuration/session methods and account configuration helpers | Authorize the account; select provider configuration, allowed products and redirect policy |
|
|
56
|
+
| Payment provenance | `getVerifiedPaymentSource` | Authorize scope and select the intended original payment, never infer ownership from metadata alone |
|
|
57
|
+
| Recovery preparation | `costRecovery.prepareGroup` | Choose same-currency scope, source and maximum debit/credit; repeat bounded preparation until done |
|
|
58
|
+
| [Recovery execution](architecture/recovery-workflow.md) | `costRecovery.startGroup`, `getGroupOperation`, `resumeGroup`, `requestGroupCancel` | Authorize immutable allocation, provider action, completion projection and release policy |
|
|
59
|
+
| [Processing costs](processing-cost-reconciliation.md) | `costRecovery.startProcessingCostReconciliation`, `getProcessingCostReconciliation`, `resumeProcessingCostReconciliation` | Choose deficit policy, pin independent main/rollback revisions, provide verified legacy import and database projection hooks |
|
|
60
|
+
| [Balance funding](balance-funding-workflow.md) | `balanceFundingWorkflow.prepare`, `apply`, `inspect`, `resume`, `cancel` | Authorize account/subscription, record consent, select the explicit preview configuration and preserve original restoration settings |
|
|
61
|
+
|
|
62
|
+
`prepareBalanceFunding`, `setBalanceFunding`, reserve/seal/finish, invoice
|
|
63
|
+
attachment/reconciliation, existing readers and settlement APIs remain available.
|
|
64
|
+
Do not run independent old and new executors for the same financial identity.
|
|
65
|
+
The [design record](architecture/component-extraction.md) explains the ownership
|
|
66
|
+
split; its historical proposal signatures are not the current export inventory.
|
|
67
|
+
|
|
68
|
+
## Provider boundary and configuration defaults
|
|
69
|
+
|
|
70
|
+
The ordinary Stripe client defaults to `2026-09-30.endive`. Balance funding
|
|
71
|
+
requires explicit `stripeApiVersion: STRIPE_CUSTOMER_PREVIEW_API_VERSION`, which
|
|
72
|
+
selects `2026-09-30.preview`; this is not enabled by default. Actual Stripe
|
|
73
|
+
account/preview eligibility must be verified separately. Pin provider/API and
|
|
74
|
+
definition versions on every operation. Keep compatible old host actions and
|
|
75
|
+
workflow definitions available while their operations may resume.
|
|
76
|
+
|
|
77
|
+
A host internal action accepts only a scoped operation reference and versions.
|
|
78
|
+
It reads credentials at execution time. For example, this processing-cost
|
|
79
|
+
adapter delegates provider verification to the package:
|
|
80
|
+
|
|
81
|
+
```ts
|
|
82
|
+
// convex/billing/actions.ts
|
|
83
|
+
import { BetterStripe } from "@fantastic.dev/better-stripe";
|
|
84
|
+
import { v } from "convex/values";
|
|
85
|
+
import { components } from "../_generated/api";
|
|
86
|
+
import { internalAction, env } from "../_generated/server";
|
|
87
|
+
|
|
88
|
+
export const observeCost = internalAction({
|
|
89
|
+
args: {
|
|
90
|
+
accountId: v.string(),
|
|
91
|
+
scopeKey: v.string(),
|
|
92
|
+
currency: v.string(),
|
|
93
|
+
operationId: v.string(),
|
|
94
|
+
version: v.number(),
|
|
95
|
+
providerApiVersion: v.string(),
|
|
96
|
+
definitionVersion: v.number(),
|
|
97
|
+
},
|
|
98
|
+
returns: v.any(),
|
|
99
|
+
handler: (ctx, args) => {
|
|
100
|
+
const stripe = new BetterStripe(components.betterStripe);
|
|
101
|
+
return stripe.costRecovery.observeProcessingCosts(ctx, args, {
|
|
102
|
+
stripeSecretKey: env.STRIPE_SECRET_KEY,
|
|
103
|
+
});
|
|
104
|
+
},
|
|
105
|
+
});
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
An authorized host mutation passes `internal.billing.actions.observeCost` as the
|
|
109
|
+
provider reference when starting reconciliation. The package converts the
|
|
110
|
+
reference to a serializable function handle. Never put credentials, raw provider
|
|
111
|
+
responses, exception messages, consent restoration settings or host metadata in
|
|
112
|
+
workflow arguments, journals or completion context. The provider bridge validates
|
|
113
|
+
closed receipts and sanitizes exceptions before journaling. The action above
|
|
114
|
+
is a read-only provider adapter; it is not a browser-authorized endpoint.
|
|
115
|
+
|
|
116
|
+
Recovery and processing-cost workflows default to three readiness observations
|
|
117
|
+
with a 1,000ms delay. Recovery requires an explicit immutable `releaseUncollectible` policy; enabling it authorizes release on an uncollectible invoice, so choose it in the host and never infer it from cancellation. Configured attempts are bounded to 1–20 and delay to
|
|
118
|
+
1–86,400,000ms. Only known retryable `not_ready` observations retry. The exported
|
|
119
|
+
`financialRetryDecision` is a pure decision helper and schedules nothing;
|
|
120
|
+
its `maxRetries` counts additional attempts. Conflicts, rejection and unknown
|
|
121
|
+
effects never authorize blind replay. Domain SDK write phases disable automatic
|
|
122
|
+
Stripe network retries as well as Workflow action retries.
|
|
123
|
+
|
|
124
|
+
## Status, resume, cancellation and retention
|
|
125
|
+
|
|
126
|
+
Processing-cost reconciliation exposes status and resume, with no generic cancellation API. Pause new host admissions when stopping those observations. Funding and recovery have their own explicit cancellation methods.
|
|
127
|
+
|
|
128
|
+
Operation status is scoped by the saved account, opaque scope, operation ID and
|
|
129
|
+
version; funding also binds the original subscription. Authorize status and
|
|
130
|
+
control calls in the host. Polling status does not itself perform provider work.
|
|
131
|
+
|
|
132
|
+
- `not_ready` means a known readiness condition can receive the bounded retry.
|
|
133
|
+
- `conflict` requires an explicit fresh host decision; resume does not silently refresh revisions or change identity.
|
|
134
|
+
- `unknown` holds uncertain effects and reservations. Reconciliation can use known IDs and positive receipts; absent or unchanged provider state does not prove no write happened.
|
|
135
|
+
- A saved verified receipt takes priority over provider re-observation when finishing a failed database step. Resume preserves original operation keys and versions.
|
|
136
|
+
- Cancellation stops future dispatch where possible and cannot abort a provider call already in flight. It is neither a refund nor proof that funds were released. Recovery cancellation before dispatch keeps sealed reservations held; its completion projection is success-only.
|
|
137
|
+
|
|
138
|
+
There is no universal time-based permission to delete financial operation or
|
|
139
|
+
receipt evidence. Workflow journal cleanup is separate from financial ledger
|
|
140
|
+
retention. Keep definitions, provider handles, phase keys, import checkpoints,
|
|
141
|
+
original restoration snapshots and receipts while any operation can resume.
|
|
142
|
+
Missing, cleaned or incompatible history stays held for reconciliation; it must
|
|
143
|
+
not allocate a fresh provider attempt. Ordinary public domain methods do not
|
|
144
|
+
expose a journal cleanup shortcut. See the [runtime retention limits](architecture/durable-execution.md#definition-versions-and-retention-limits)
|
|
145
|
+
and the domain guides for the exact continuation paths.
|
|
146
|
+
|
|
147
|
+
## Cutover and rollback
|
|
148
|
+
|
|
149
|
+
1. Inventory existing scopes, pending groups, legacy worker keys, original restoration settings, receipts and host projections. Retain original identifiers and namespace new request keys. Verify package/API compatibility in an isolated development deployment.
|
|
150
|
+
2. Pause old dispatchers for each identity before enabling the replacement. Drain in-flight workers and obtain positive receipt evidence. Funding's quiescence confirmation is an operator attestation bound to the exact paused snapshot; matching current settings alone is insufficient.
|
|
151
|
+
3. Import only verified legacy records with their original provider keys, owner, source economics and revisions. Keep historical source rows. Unknown, ambiguous, incomplete or unmapped records remain held and observable; never invent a collected group, substitute a current price, zero costs or forgive a claim.
|
|
152
|
+
4. Enable the new host adapter for verified identities. Replayed callbacks must use operation ID/version and commit database projections atomically with component completion. Keep existing claim/reservation/transfer ledgers as the money authority; host job tables are metadata only.
|
|
153
|
+
5. Check bounded status/counts and reconcile held records before retiring compatibility paths. Schedule host reporting and observation jobs explicitly; the component does not inherit a host cron cadence.
|
|
154
|
+
|
|
155
|
+
To roll back a rollout, pause new admissions and dispatchers, preserve journals
|
|
156
|
+
and receipts, and reconcile all in-flight or unknown operations using their
|
|
157
|
+
original keys and definitions. Reverting application code is not a financial
|
|
158
|
+
rollback. Do not reactivate an old executor for an imported identity or delete
|
|
159
|
+
new tables, checkpoints or restoration data. If the older release cannot read
|
|
160
|
+
new operation state, keep the compatible executor deployed for reconciliation
|
|
161
|
+
and perform an explicitly authorized per-identity repair. A failed or canceled
|
|
162
|
+
workflow alone cannot justify releasing reservations or replaying a write.
|
|
163
|
+
|
|
164
|
+
The [funding cutover runbook](example-balance-funding-cutover.md) documents
|
|
165
|
+
paused imports, quiescence, bounded backfill and restoration. The
|
|
166
|
+
[recovery cutover runbook](example-recovery-cutover.md) covers exact legacy
|
|
167
|
+
mirrors, partial finish-only continuation, blocked counts, affiliate offsets,
|
|
168
|
+
refund races and held cancellation. These example functions use demo personas;
|
|
169
|
+
production hosts must derive authorization from authenticated sessions.
|
|
170
|
+
|
|
171
|
+
## Verification and release
|
|
172
|
+
|
|
173
|
+
Run `pnpm run check:all` without lowering floors or raising budgets. Build and
|
|
174
|
+
pack the candidate, inspect its file inventory, install that actual tarball in
|
|
175
|
+
a clean consumer, typecheck with `skipLibCheck: false`, and test root/React/testing
|
|
176
|
+
runtime imports plus native Convex config bundling and generated component
|
|
177
|
+
references. The packed-doc regression follows local Markdown links from the
|
|
178
|
+
README and migration guide against the actual tarball, not a workspace symlink.
|
|
179
|
+
A local pack is consumer proof, not npm publication.
|
|
180
|
+
|
|
181
|
+
The merged cross-domain suite under `src/component/durableExecution/` and the
|
|
182
|
+
example domain suites cover replay, concurrency, independent revisions,
|
|
183
|
+
callback atomicity, provider success before persistence failure, restart,
|
|
184
|
+
legacy adoption and held unknown/cancel boundaries. Tests and native checks use
|
|
185
|
+
synthetic transports or dummy keys. They do not establish live Stripe preview
|
|
186
|
+
eligibility, exactly-once external effects or production migration completion.
|
|
187
|
+
Keep sanitized test, consumer and native evidence directly in the integration PR.
|
|
188
|
+
|
|
189
|
+
Follow [the release process](releasing.md). Use a Conventional Commit PR title;
|
|
190
|
+
Release Please owns package version, manifest, README version line and changelog.
|
|
191
|
+
Do not hand-bump them for this handoff. Preserve its generated release description
|
|
192
|
+
and standalone notes delimiters; put review evidence in comments. Recheck the
|
|
193
|
+
actual release candidate and required CI before any merge. After separately
|
|
194
|
+
authorized publication, verify the npm version, integrity/provenance and public
|
|
195
|
+
artifact. A successful workflow with Publish skipped is not publication. This
|
|
196
|
+
handoff does not publish npm, create a tag, deploy production or run a live backfill.
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# Maintaining release descriptions
|
|
2
|
+
|
|
3
|
+
Release Please reads a release PR's description when its normal release workflow
|
|
4
|
+
creates a tag. It needs standalone `---` lines around the version notes. Replacing
|
|
5
|
+
the description with review evidence can make a merged release PR unrecognizable,
|
|
6
|
+
skip publication and cause the existing automation to generate another release.
|
|
7
|
+
A successful workflow with a skipped Publish job does not establish publication.
|
|
8
|
+
|
|
9
|
+
Prefer PR comments for test logs, review evidence and acceptance updates. Keep the
|
|
10
|
+
generated description intact. When release notes need an editorial correction,
|
|
11
|
+
keep the exact candidate version, notes boundaries and existing checked acceptance
|
|
12
|
+
evidence. The local helper builds the description without writing to GitHub:
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
node scripts/release-description.mjs build 0.37.0 evidence.md CHANGELOG.md > release-body.md
|
|
16
|
+
node scripts/release-description.mjs check 0.37.0 release-body.md
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Use the candidate's actual package version instead of the example version. The
|
|
20
|
+
helper selects only that version's changelog notes. It appends the supplied evidence
|
|
21
|
+
unchanged after the closing delimiter. It refuses missing notes, conflicting
|
|
22
|
+
version headings, HTML details/summary release selectors inside notes, and evidence
|
|
23
|
+
containing standalone separators, which would change
|
|
24
|
+
Release Please's parse boundaries. Resolve such input explicitly before updating a
|
|
25
|
+
PR. This local check supports a single-package release; it does not claim to parse
|
|
26
|
+
all Release Please formats.
|
|
27
|
+
|
|
28
|
+
Before changing a release PR description, save its current body and preserve all
|
|
29
|
+
reviewer acceptance and evidence. Run the local check again on the fresh remote
|
|
30
|
+
body after updating it. Do not replace a newer reviewed body with an older local
|
|
31
|
+
copy. Preserve the generated footer and any bot metadata. Independent acceptance
|
|
32
|
+
and the exact-head merge guard still apply. This helper does not merge, enable
|
|
33
|
+
auto-merge, create tags, invoke workflows or publish npm packages.
|
|
34
|
+
|
|
35
|
+
The 0.36 description incident demonstrated this failure. Its run skipped Publish;
|
|
36
|
+
the next generated 0.37 PR automatically merged before independent candidate
|
|
37
|
+
acceptance. Keep that timing distinction in the release evidence. Correct inaccurate
|
|
38
|
+
notes through an ordinary reviewed PR and complete the normal reviewed release and
|
|
39
|
+
public-artifact verification before application adoption. Never substitute a local
|
|
40
|
+
tarball, a workflow conclusion or a later audit for the required public artifact or
|
|
41
|
+
premerge acceptance.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fantastic.dev/better-stripe",
|
|
3
|
-
"version": "0.45.
|
|
3
|
+
"version": "0.45.2",
|
|
4
4
|
"description": "A Convex component for Stripe V2 Accounts API integration.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"stripe",
|
|
@@ -71,7 +71,17 @@
|
|
|
71
71
|
"docs/refund-command-evidence.md",
|
|
72
72
|
"docs/personal-account-mapping.md",
|
|
73
73
|
"docs/financial-ownership.md",
|
|
74
|
-
"docs/financial-observations.md"
|
|
74
|
+
"docs/financial-observations.md",
|
|
75
|
+
"docs/architecture/component-extraction.md",
|
|
76
|
+
"docs/architecture/durable-execution.md",
|
|
77
|
+
"docs/architecture/recovery-workflow.md",
|
|
78
|
+
"docs/balance-funding-state.md",
|
|
79
|
+
"docs/balance-funding-workflow.md",
|
|
80
|
+
"docs/processing-cost-reconciliation.md",
|
|
81
|
+
"docs/example-balance-funding-cutover.md",
|
|
82
|
+
"docs/example-recovery-cutover.md",
|
|
83
|
+
"docs/releasing.md",
|
|
84
|
+
"docs/release-handoff.md"
|
|
75
85
|
],
|
|
76
86
|
"scripts": {
|
|
77
87
|
"build": "tsc --project ./tsconfig.build.json",
|