@fantastic.dev/better-stripe 0.79.0 → 0.80.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 +12 -0
- package/README.md +1 -1
- package/dist/client/billing/renewalPriceReplacement.d.ts +131 -0
- package/dist/client/billing/renewalPriceReplacement.d.ts.map +1 -0
- package/dist/client/billing/renewalPriceReplacement.js +90 -0
- package/dist/client/billing/renewalPriceReplacement.js.map +1 -0
- package/dist/client/billing/renewalReplacementSchema.d.ts +124 -0
- package/dist/client/billing/renewalReplacementSchema.d.ts.map +1 -0
- package/dist/client/billing/renewalReplacementSchema.js +121 -0
- package/dist/client/billing/renewalReplacementSchema.js.map +1 -0
- package/dist/client/billing/renewalReplacementSnapshot.d.ts +3 -0
- package/dist/client/billing/renewalReplacementSnapshot.d.ts.map +1 -0
- package/dist/client/billing/renewalReplacementSnapshot.js +69 -0
- package/dist/client/billing/renewalReplacementSnapshot.js.map +1 -0
- package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +32 -32
- package/dist/client/connect/payoutSyncTestHelpers.d.ts +16 -16
- package/dist/client/index.d.ts +3 -0
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +1 -0
- package/dist/client/index.js.map +1 -1
- package/dist/client/usage/observationClient.d.ts +2 -2
- package/dist/client/usage/observationClient.d.ts.map +1 -1
- package/dist/component/balanceFunding/mutations.d.ts +16 -16
- package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
- package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
- package/dist/component/earnings/triggers.d.ts +16 -16
- package/docs/client-api.md +5 -0
- package/docs/renewal-price-replacements.md +186 -0
- package/package.json +1 -1
- package/src/client/billing/renewal-price-replacement.test.ts +457 -0
- package/src/client/billing/renewalPriceReplacement.ts +127 -0
- package/src/client/billing/renewalReplacementSchema.ts +129 -0
- package/src/client/billing/renewalReplacementSnapshot.ts +85 -0
- package/src/client/index.ts +6 -0
|
@@ -372,14 +372,6 @@ export declare const mutation: import("convex-helpers/server/customFunctions").C
|
|
|
372
372
|
preparationId: import("convex/values").GenericId<"balanceFundingPreparations">;
|
|
373
373
|
requestKey: string;
|
|
374
374
|
result?: {
|
|
375
|
-
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
376
|
-
retryable: false;
|
|
377
|
-
status: "conflict";
|
|
378
|
-
} | {
|
|
379
|
-
reason: "policy_invalid";
|
|
380
|
-
retryable: false;
|
|
381
|
-
status: "rejected";
|
|
382
|
-
} | {
|
|
383
375
|
operation: {
|
|
384
376
|
accountId: string;
|
|
385
377
|
operationId: import("convex/values").GenericId<"balanceFundingOperations">;
|
|
@@ -390,6 +382,14 @@ export declare const mutation: import("convex-helpers/server/customFunctions").C
|
|
|
390
382
|
} | {
|
|
391
383
|
enabled: boolean;
|
|
392
384
|
status: "unchanged";
|
|
385
|
+
} | {
|
|
386
|
+
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
387
|
+
retryable: false;
|
|
388
|
+
status: "conflict";
|
|
389
|
+
} | {
|
|
390
|
+
reason: "policy_invalid";
|
|
391
|
+
retryable: false;
|
|
392
|
+
status: "rejected";
|
|
393
393
|
} | {
|
|
394
394
|
reason: "provider_pending";
|
|
395
395
|
retryable: true;
|
|
@@ -3270,14 +3270,6 @@ export declare const mutation: import("convex-helpers/server/customFunctions").C
|
|
|
3270
3270
|
preparationId: import("convex/values").GenericId<"balanceFundingPreparations">;
|
|
3271
3271
|
requestKey: string;
|
|
3272
3272
|
result?: {
|
|
3273
|
-
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
3274
|
-
retryable: false;
|
|
3275
|
-
status: "conflict";
|
|
3276
|
-
} | {
|
|
3277
|
-
reason: "policy_invalid";
|
|
3278
|
-
retryable: false;
|
|
3279
|
-
status: "rejected";
|
|
3280
|
-
} | {
|
|
3281
3273
|
operation: {
|
|
3282
3274
|
accountId: string;
|
|
3283
3275
|
operationId: import("convex/values").GenericId<"balanceFundingOperations">;
|
|
@@ -3288,6 +3280,14 @@ export declare const mutation: import("convex-helpers/server/customFunctions").C
|
|
|
3288
3280
|
} | {
|
|
3289
3281
|
enabled: boolean;
|
|
3290
3282
|
status: "unchanged";
|
|
3283
|
+
} | {
|
|
3284
|
+
reason: "identity_changed" | "revision_changed" | "scope_busy";
|
|
3285
|
+
retryable: false;
|
|
3286
|
+
status: "conflict";
|
|
3287
|
+
} | {
|
|
3288
|
+
reason: "policy_invalid";
|
|
3289
|
+
retryable: false;
|
|
3290
|
+
status: "rejected";
|
|
3291
3291
|
} | {
|
|
3292
3292
|
reason: "provider_pending";
|
|
3293
3293
|
retryable: true;
|
package/docs/client-api.md
CHANGED
|
@@ -2,6 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
## Client API reference
|
|
4
4
|
|
|
5
|
+
The pure `prepareRenewalPriceReplacement` export qualifies trusted provider-read
|
|
6
|
+
snapshots for an exact cross-product renewal request. It performs no provider I/O
|
|
7
|
+
and supplies no schedule writer. See the [renewal replacement contract](./renewal-price-replacements.md)
|
|
8
|
+
for its selectors, private binding, required staged protocol and preservation gate.
|
|
9
|
+
|
|
5
10
|
All methods are available on the `BetterStripe` class instance. Methods that call the Stripe API are actions; methods that only read Convex data are queries.
|
|
6
11
|
|
|
7
12
|
Methods named `get<Entity>` take the component document ID (exception: `getInvoice`, which takes the Stripe invoice ID); methods named `get<Entity>ByStripeId` take the Stripe ID (`acct_...`, `prod_...`, `price_...`, `cs_...`, `sub_...`).
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
# Exact price replacement at renewal
|
|
2
|
+
|
|
3
|
+
`prepareRenewalPriceReplacement` is a pure server-side preparation contract. It
|
|
4
|
+
qualifies supplied provider reads and binds the original and target. It performs
|
|
5
|
+
no reads, writes, authorization, scheduling or reconciliation. A `prepared` result
|
|
6
|
+
is **not** permission to write, a pending price change or an effective change.
|
|
7
|
+
Its `preservation: "requires_schedule_validation"` field makes that distinction
|
|
8
|
+
explicit. Schedule execution is not supplied by this preparation helper.
|
|
9
|
+
|
|
10
|
+
Use this contract for one original platform-owned subscription with an Accounts v2
|
|
11
|
+
customer account and one complete, licensed recurring item. The selected target
|
|
12
|
+
can belong to another product. The host authorizes the original buyer,
|
|
13
|
+
subscription and target, decides upgrade/downgrade direction and timing, and keeps
|
|
14
|
+
consent and durable dispatch claims. An `acct_` customer account does not imply a
|
|
15
|
+
`Stripe-Account` request header. This contract does not select a connected scope.
|
|
16
|
+
|
|
17
|
+
```ts
|
|
18
|
+
import { prepareRenewalPriceReplacement } from "@fantastic.dev/better-stripe";
|
|
19
|
+
|
|
20
|
+
// Trusted server reads, including an expanded original item price.
|
|
21
|
+
// Authorize these selectors and the operation before obtaining provider reads.
|
|
22
|
+
const prepared = prepareRenewalPriceReplacement({
|
|
23
|
+
subscription: retrievedOriginalSubscription,
|
|
24
|
+
targetPrice: retrievedApprovedTargetPrice,
|
|
25
|
+
expected: authorizedOriginalAndTarget,
|
|
26
|
+
key: retainedLogicalOperationKey,
|
|
27
|
+
});
|
|
28
|
+
// Persist privately with immutable consent and original authorization.
|
|
29
|
+
// No schedule has been created by this call.
|
|
30
|
+
await hostOperationStore.savePrepared(prepared);
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
`expected` includes `customerAccountId`, `subscriptionId`, `itemId`,
|
|
34
|
+
`currentPriceId`, `currentProductId`, `targetPriceId`, `targetProductId`,
|
|
35
|
+
`periodStart`, `periodEnd` and `livemode`. Current period timestamps come from the
|
|
36
|
+
original **item** in Stripe 23, not a top-level subscription period field. The
|
|
37
|
+
helper checks every selector against the reads. It preserves quantity and binds
|
|
38
|
+
complete JSON provider snapshots, including fields that later schedule validation
|
|
39
|
+
must classify. The original price remains unchanged. Archived original prices may
|
|
40
|
+
remain valid paid terms; the target must be active and different, in the original
|
|
41
|
+
currency. Different products and recurring cadences are represented without
|
|
42
|
+
inventing tier ordering or financial arithmetic. Representation does not certify
|
|
43
|
+
that a future writer supports every cadence, billing mode or setting.
|
|
44
|
+
|
|
45
|
+
The subscription's actual `currency` must match both prices' default `currency`.
|
|
46
|
+
This helper does not select `currency_options` or infer an alternative amount.
|
|
47
|
+
Alternative-currency contexts need a separate explicit mapping and are rejected
|
|
48
|
+
here rather than accepted because the two default price currencies happen to match.
|
|
49
|
+
|
|
50
|
+
An optional `billingCustomer` input adds an authoritative ancestor billing read.
|
|
51
|
+
Stripe documents that `customer_account` responses also identify a v1 `customer`,
|
|
52
|
+
and that customer-configured accounts can be retrieved through the v1 Customers
|
|
53
|
+
endpoint. See [the customer-account bridge](https://docs.stripe.com/accounts-v2/use-accounts-as-customers#reference-accounts-in-customers-v1-integrations).
|
|
54
|
+
Supply the full undeleted Customer with an explicitly read, expanded `discount`
|
|
55
|
+
field. The helper checks its `cus_` ID against the subscription's `customer`, its
|
|
56
|
+
`customer_account` against the authorized `acct_` selector, and its `livemode`.
|
|
57
|
+
Its complete JSON joins the private canonical snapshot. Missing discount evidence
|
|
58
|
+
is rejected when a billing customer is supplied; omitted ancestor evidence leaves
|
|
59
|
+
preparation incomplete for any writer that needs it.
|
|
60
|
+
|
|
61
|
+
An explicit ancestor `discount: null` proves only the observed absence of that
|
|
62
|
+
discount. It does not distinguish historical phase discount suppression from
|
|
63
|
+
inheritance, and does not authorize freezing or suppressing future customer
|
|
64
|
+
discounts. That unresolved distinction remains a schedule-validation boundary.
|
|
65
|
+
|
|
66
|
+
The helper requires an active, renewing, single-item original. Unrelated attached
|
|
67
|
+
schedules, cancellation intent, paused collection, pending updates, explicit legacy
|
|
68
|
+
payment sources, custom payment settings and nonnull application fees are rejected
|
|
69
|
+
at this pre-attach boundary. Explicitly disabled default payment settings are
|
|
70
|
+
accepted as a snapshot, not as proof of retained provider semantics. Historical
|
|
71
|
+
trial timestamps are retained; active trials are outside this boundary. Unknown
|
|
72
|
+
or unsupported execution settings must be rejected before a write, even if their
|
|
73
|
+
JSON was valid during preparation.
|
|
74
|
+
|
|
75
|
+
## Identity and ownership
|
|
76
|
+
|
|
77
|
+
The required caller key must be nonblank, at most 255 characters and contain no
|
|
78
|
+
line breaks. `requestIdentity.binding` is an opaque versioned canonical snapshot,
|
|
79
|
+
not a signature, authorization token, reservation or historical lookup. Object key
|
|
80
|
+
order does not change it; source or target changes do. Keep the complete prepared
|
|
81
|
+
operation immutable. The SDK has no historical binding store. An authorized host
|
|
82
|
+
could construct another binding for the same key; doing so is not safe replay.
|
|
83
|
+
|
|
84
|
+
Full snapshots and bindings can contain private provider metadata and customer
|
|
85
|
+
data. Store them on the trusted server. Do not expose them to the browser, logs or
|
|
86
|
+
PR evidence. Return only the necessary display summary and an authorized host
|
|
87
|
+
operation reference to the UI. The helper copies bounded finite plain JSON and
|
|
88
|
+
rejects executable, cyclic or excessively large inputs.
|
|
89
|
+
|
|
90
|
+
Preparation describes observed data. It does not establish that a read is fresh,
|
|
91
|
+
that the provider returned it, or that the host authenticated its owner. Re-read
|
|
92
|
+
and compare material state immediately before dispatch. A read fingerprint is not
|
|
93
|
+
an atomic compare-and-swap token. Host serialization cannot exclude independent
|
|
94
|
+
Dashboard or other provider writers; detected drift must remain a conflict.
|
|
95
|
+
|
|
96
|
+
## Required execution protocol
|
|
97
|
+
|
|
98
|
+
Stripe documents two distinct writes: create with `from_subscription`, then update
|
|
99
|
+
the resulting schedule with the unchanged current phase and future target phase.
|
|
100
|
+
Omitted phase settings can be unset. See [Stripe's subscription schedule guide](https://docs.stripe.com/billing/subscriptions/subscription-schedules#changing-subscriptions).
|
|
101
|
+
The Portal's own period-end downgrade is limited to same-product prices, as
|
|
102
|
+
documented in [Portal configuration](https://docs.stripe.com/customer-management/configure-portal).
|
|
103
|
+
|
|
104
|
+
The following is the required protocol for subsequent execution work, not a set
|
|
105
|
+
of methods implemented by this preparation helper:
|
|
106
|
+
|
|
107
|
+
| Stage | Required evidence and result |
|
|
108
|
+
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
109
|
+
| Prepare | Authorized exact original/target/period and immutable private snapshots. No mutation. |
|
|
110
|
+
| Attach | One explicit creation POST with the retained attach-stage key and exact normalized payload. Return and durably retain the acknowledged original schedule receipt. Attachment alone is incomplete. |
|
|
111
|
+
| Configure | Use that acknowledged receipt, fresh validated reads and a separately retained configure-stage key bound to the complete update. One explicit update POST. No implicit attachment. |
|
|
112
|
+
| Observe | Read the known owned schedule and original subscription. Confirm the exact target/boundary/settings before reporting pending. Require provider current subscription/item/price identity before reporting effective. |
|
|
113
|
+
|
|
114
|
+
Every future stage record must include its version, logical preparation binding,
|
|
115
|
+
actual configured Stripe API version, explicit platform scope and complete
|
|
116
|
+
normalized payload. The attach payload is exactly
|
|
117
|
+
`{ from_subscription: expected.subscriptionId }`, with no inline phase or metadata
|
|
118
|
+
options. Attach and configure use distinct explicitly supplied provider keys;
|
|
119
|
+
neither key is silently generated from the logical key. Each stage binding covers
|
|
120
|
+
the stage, logical binding, API version, scope and payload. Configure additionally
|
|
121
|
+
binds the acknowledged schedule ID, complete acknowledged baseline and unchanged
|
|
122
|
+
schedule-default fingerprint, not just the attach request's identity.
|
|
123
|
+
|
|
124
|
+
The trusted host durably retains the original first-dispatch time with each
|
|
125
|
+
immutable stage request. Replay must retain it, not start another retention clock.
|
|
126
|
+
An acknowledged receipt retains that exact request, original subscription/account,
|
|
127
|
+
schedule ID, livemode and full acknowledged provider response. These are unsigned
|
|
128
|
+
server-owned records, not browser-supplied provenance or a second business ledger.
|
|
129
|
+
|
|
130
|
+
The original item ID authorizes the prewrite request. Stripe's phase update shape
|
|
131
|
+
accepts price and quantity without an item-ID selector, so a transition is not
|
|
132
|
+
assumed to retain the same `si_` ID. A future observer must correlate any successor
|
|
133
|
+
item through the retained owned schedule's exact target phase and original
|
|
134
|
+
subscription/account. Matching target price alone is insufficient. Manual release
|
|
135
|
+
or ambiguous completion must stay unknown until authoritative completion
|
|
136
|
+
correlation is available; no wall-clock fallback is allowed.
|
|
137
|
+
|
|
138
|
+
Each invocation permits at most one **mutating POST**, with automatic transport
|
|
139
|
+
retries disabled for its reads and write. It must not chain attachment and
|
|
140
|
+
configuration, rotate keys, fall back to unkeyed creation, or cancel/release a
|
|
141
|
+
partial schedule as hidden rollback. The host explicitly invokes each stage and
|
|
142
|
+
persists its identity before dispatch and its acknowledged receipt afterward.
|
|
143
|
+
|
|
144
|
+
A lost attach response is unknown. A nonnull `subscription.schedule` must neither
|
|
145
|
+
prove ownership nor automatically prevent explicit same-key recovery of the
|
|
146
|
+
original acknowledged response. Matching shape alone never authorizes adopting a
|
|
147
|
+
schedule. Retained provider idempotency can recover an acknowledged receipt only
|
|
148
|
+
under its documented rules. [Keys can be pruned after at least 24 hours](https://docs.stripe.com/api/idempotent_requests);
|
|
149
|
+
there is no permanent replay guarantee. Do not silently reissue after retention.
|
|
150
|
+
|
|
151
|
+
After an unknown configuration result, exact reads of the retained owned schedule
|
|
152
|
+
can confirm pending, conflict or uncertainty. A failed observation must not erase
|
|
153
|
+
an already acknowledged receipt or invent success. Keep attached-unconfigured,
|
|
154
|
+
unknown, confirmed pending, effective, canceled and released states distinct.
|
|
155
|
+
Wall time, a future phase or a browser return alone never proves effectiveness,
|
|
156
|
+
payment, entitlement or commission eligibility.
|
|
157
|
+
|
|
158
|
+
## Preservation matrix and implementation gate
|
|
159
|
+
|
|
160
|
+
This table is the mapping contract for the next write slices. A representable
|
|
161
|
+
field is not proof of a lossless provider transition. The configure mapper must
|
|
162
|
+
resolve every applicable row before the first mutation; no response-object spread
|
|
163
|
+
or extra `subscriptions.update` workaround is permitted.
|
|
164
|
+
|
|
165
|
+
| Original setting | Required mapping or explicit unsupported boundary |
|
|
166
|
+
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
167
|
+
| Item and period | Verify complete single-item identity, expanded original price/product, quantity and item period. Keep current start/end and paid item unchanged; bind the target to that exact end. Metered/tiered or missing quantities need a separate supported contract. |
|
|
168
|
+
| Null and inheritance | Preserve the distinction between schedule defaults, phase overrides and customer fallback. Extract expanded IDs. Send empty-string clears only for fields declared `Emptyable`; never universally turn null into omission, zero or an empty string. |
|
|
169
|
+
| Discounts | Preserve existing discount IDs, order, duration and item/subscription precedence. Omission may inherit customer discounts; an explicit empty-string list suppresses inheritance. Re-redeeming a coupon can restart duration. Establish target-product eligibility and provenance before supporting a discounted transition. |
|
|
170
|
+
| Tax | Project only writable enabled/liability values and tax-rate IDs at their original level. Do not copy read-only disabled reasons. Preserve manual versus automatic mode and liability scope; unresolved combinations reject. |
|
|
171
|
+
| Trial | Retain historical dates. Active/future trials need an exact phase timeline plus proof of retained `trial_settings`. Never force `trial_end: now`, add a free phase or blindly resend past timestamps. |
|
|
172
|
+
| Cancellation | `cancel_at` and `cancel_at_period_end` have no direct phase equivalents. Reject cancellation intent until an exact supported mapping exists. `end_behavior` is not a substitute, and must not clear the original intent. |
|
|
173
|
+
| Payment method | Normalize an expanded method to its ID at the same defaults/phase level. Null may mean fallback and is not a writable clear in every location. Do not freeze a customer default into a new explicit override. |
|
|
174
|
+
| Legacy sources and payment settings | No direct phase/default write for `default_source` or `payment_settings`. Absence of a write field does not prove Stripe loses the subscription value. Explicit nondefault cases need retained-field proof or fail before attachment; never translate a legacy source to a payment-method ID. |
|
|
175
|
+
| Application fee | Phase/default fee writes have a connected-account prerequisite. Nonnull fee, including zero, is outside this platform contract until ownership and retention are qualified. Do not add a connected header or silently drop the fee. |
|
|
176
|
+
| Routing | `transfer_data` and `on_behalf_of` are separate from fee ownership. Preserve destination/account IDs and exact percentage/omission semantics where supported. Do not infer zero/full transfer or compute financial splits. |
|
|
177
|
+
| Invoice/collection | Preserve collection mode, due-day semantics, issuer/tax IDs and supported custom invoice fields at their original level. Auto-charge null days are not a writable null. Unknown issuer values and unsupported clear/inheritance cases reject. |
|
|
178
|
+
| Anchor, billing mode and thresholds | A numeric subscription anchor cannot be copied into a phase enum. Prove unchanged current boundary and target-cadence behavior. Preserve migrated billing mode; map thresholds only when their effect on renewal is supported. No automatic anchor reset. |
|
|
179
|
+
| Metadata and extra invoice items | Retain reserved and host metadata without turning subscription metadata into repeated phase-entry changes. Additional invoice items can charge again in a new phase; reject nonempty additions until no-duplicate semantics are supported. |
|
|
180
|
+
| Other provider states | Pending updates/setup, pauses, managed billing and special schedules need explicit supported classification. Similar field names are not equivalent. A field missing from the phase schema is a verification gap, not proof it is discarded. |
|
|
181
|
+
|
|
182
|
+
The completed mapper specification and recovery contract must independently fit
|
|
183
|
+
the configure/reconciliation ticket's estimate before write implementation starts.
|
|
184
|
+
Split further when needed, preserving the complete cross-product renewal outcome.
|
|
185
|
+
Unsupported boundaries must remain visible to the host and in acceptance criteria.
|
|
186
|
+
Controlled unit tests alone cannot qualify live preservation or consumer policy.
|
package/package.json
CHANGED