@fantastic.dev/better-stripe 0.81.0 → 0.83.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/renewalAggregate/configure.d.ts +35 -0
- package/dist/client/billing/renewalAggregate/configure.d.ts.map +1 -0
- package/dist/client/billing/renewalAggregate/configure.js +96 -0
- package/dist/client/billing/renewalAggregate/configure.js.map +1 -0
- package/dist/client/billing/renewalAggregate/index.d.ts +3 -0
- package/dist/client/billing/renewalAggregate/index.d.ts.map +1 -0
- package/dist/client/billing/renewalAggregate/index.js +3 -0
- package/dist/client/billing/renewalAggregate/index.js.map +1 -0
- package/dist/client/billing/renewalAggregate/phaseContext.d.ts +176 -0
- package/dist/client/billing/renewalAggregate/phaseContext.d.ts.map +1 -0
- package/dist/client/billing/renewalAggregate/phaseContext.js +112 -0
- package/dist/client/billing/renewalAggregate/phaseContext.js.map +1 -0
- package/dist/client/billing/renewalAggregate/phases.d.ts +7 -0
- package/dist/client/billing/renewalAggregate/phases.d.ts.map +1 -0
- package/dist/client/billing/renewalAggregate/phases.js +192 -0
- package/dist/client/billing/renewalAggregate/phases.js.map +1 -0
- package/dist/client/billing/renewalAggregate/preflight.d.ts +594 -0
- package/dist/client/billing/renewalAggregate/preflight.d.ts.map +1 -0
- package/dist/client/billing/renewalAggregate/preflight.js +164 -0
- package/dist/client/billing/renewalAggregate/preflight.js.map +1 -0
- package/dist/client/billing/renewalAggregate/profile.d.ts +8 -0
- package/dist/client/billing/renewalAggregate/profile.d.ts.map +1 -0
- package/dist/client/billing/renewalAggregate/profile.js +60 -0
- package/dist/client/billing/renewalAggregate/profile.js.map +1 -0
- package/dist/client/billing/renewalAggregate/receipt.d.ts +40 -0
- package/dist/client/billing/renewalAggregate/receipt.d.ts.map +1 -0
- package/dist/client/billing/renewalAggregate/receipt.js +62 -0
- package/dist/client/billing/renewalAggregate/receipt.js.map +1 -0
- package/dist/client/billing/renewalAggregate/shared.d.ts +51 -0
- package/dist/client/billing/renewalAggregate/shared.d.ts.map +1 -0
- package/dist/client/billing/renewalAggregate/shared.js +87 -0
- package/dist/client/billing/renewalAggregate/shared.js.map +1 -0
- package/dist/client/billing/renewalAggregate/sourceDiscounts.d.ts +42 -0
- package/dist/client/billing/renewalAggregate/sourceDiscounts.d.ts.map +1 -0
- package/dist/client/billing/renewalAggregate/sourceDiscounts.js +90 -0
- package/dist/client/billing/renewalAggregate/sourceDiscounts.js.map +1 -0
- package/dist/client/billing/renewalAggregate/sourceSettings.d.ts +136 -0
- package/dist/client/billing/renewalAggregate/sourceSettings.d.ts.map +1 -0
- package/dist/client/billing/renewalAggregate/sourceSettings.js +82 -0
- package/dist/client/billing/renewalAggregate/sourceSettings.js.map +1 -0
- package/dist/client/billing/renewalAggregate/taxRetention.d.ts +8 -0
- package/dist/client/billing/renewalAggregate/taxRetention.d.ts.map +1 -0
- package/dist/client/billing/renewalAggregate/taxRetention.js +23 -0
- package/dist/client/billing/renewalAggregate/taxRetention.js.map +1 -0
- package/dist/client/billing/renewalAttach/couponJoins.d.ts +23 -0
- package/dist/client/billing/renewalAttach/couponJoins.d.ts.map +1 -0
- package/dist/client/billing/renewalAttach/couponJoins.js +76 -0
- package/dist/client/billing/renewalAttach/couponJoins.js.map +1 -0
- package/dist/client/billing/renewalAttach/index.d.ts +3 -0
- package/dist/client/billing/renewalAttach/index.d.ts.map +1 -0
- package/dist/client/billing/renewalAttach/index.js +3 -0
- package/dist/client/billing/renewalAttach/index.js.map +1 -0
- package/dist/client/billing/renewalAttach/reader.d.ts +141 -0
- package/dist/client/billing/renewalAttach/reader.d.ts.map +1 -0
- package/dist/client/billing/renewalAttach/reader.js +80 -0
- package/dist/client/billing/renewalAttach/reader.js.map +1 -0
- package/dist/client/billing/renewalAttach/request.d.ts +30 -0
- package/dist/client/billing/renewalAttach/request.d.ts.map +1 -0
- package/dist/client/billing/renewalAttach/request.js +39 -0
- package/dist/client/billing/renewalAttach/request.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 -5
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +3 -3
- package/dist/client/index.js.map +1 -1
- package/dist/client/renewal.d.ts +8 -0
- package/dist/client/renewal.d.ts.map +1 -0
- package/dist/client/renewal.js +4 -0
- package/dist/client/renewal.js.map +1 -0
- package/dist/client/renewalContextClient.d.ts +130 -0
- package/dist/client/renewalContextClient.d.ts.map +1 -0
- package/dist/client/renewalContextClient.js +10 -0
- package/dist/client/renewalContextClient.js.map +1 -0
- package/dist/client/usage/observationClient.d.ts +2 -2
- package/dist/client/usage/observationClient.d.ts.map +1 -1
- package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
- package/dist/component/balanceFunding/mutations.d.ts +43 -43
- 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/renewal-context-reads.md +113 -0
- package/docs/renewal-phase-assembly.md +180 -0
- package/docs/renewal-price-replacements.md +57 -16
- package/package.json +1 -1
- package/src/client/billing/renewalAggregate/configure.test.ts +372 -0
- package/src/client/billing/renewalAggregate/configure.ts +164 -0
- package/src/client/billing/renewalAggregate/index.ts +2 -0
- package/src/client/billing/renewalAggregate/phaseContext.ts +144 -0
- package/src/client/billing/renewalAggregate/phases.ts +247 -0
- package/src/client/billing/renewalAggregate/preflight.test.ts +233 -0
- package/src/client/billing/renewalAggregate/preflight.ts +211 -0
- package/src/client/billing/renewalAggregate/profile.ts +76 -0
- package/src/client/billing/renewalAggregate/receipt.ts +76 -0
- package/src/client/billing/renewalAggregate/shared.ts +106 -0
- package/src/client/billing/renewalAggregate/sourceAndTaxRetention.test.ts +247 -0
- package/src/client/billing/renewalAggregate/sourceDiscounts.ts +112 -0
- package/src/client/billing/renewalAggregate/sourceSettings.ts +88 -0
- package/src/client/billing/renewalAggregate/taxRetention.ts +28 -0
- package/src/client/billing/renewalAttach/couponEvidence.test.ts +104 -0
- package/src/client/billing/renewalAttach/couponJoins.ts +95 -0
- package/src/client/billing/renewalAttach/index.ts +9 -0
- package/src/client/billing/renewalAttach/reader.test.ts +409 -0
- package/src/client/billing/renewalAttach/reader.ts +131 -0
- package/src/client/billing/renewalAttach/request.ts +49 -0
- package/src/client/index.ts +3 -8
- package/src/client/renewal.ts +13 -0
- package/src/client/renewalContextClient.ts +23 -0
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# Renewal context reads and attachment request preparation
|
|
2
|
+
|
|
3
|
+
`BetterStripe.readRenewalPriceReplacementContext` reads the original provider
|
|
4
|
+
subscription, authorized target price and correlated billing Customer. Hosts
|
|
5
|
+
must authorize the caller and exact original selectors before invoking it on
|
|
6
|
+
the server. This method does not create or update provider resources, persist
|
|
7
|
+
operation ownership or establish financial preservation.
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
const context = await betterStripe.readRenewalPriceReplacementContext(ctx, {
|
|
11
|
+
expected,
|
|
12
|
+
});
|
|
13
|
+
const prepared = prepareRenewalPriceReplacement({
|
|
14
|
+
subscription: context.subscription,
|
|
15
|
+
targetPrice: context.targetPrice,
|
|
16
|
+
billingCustomer: context.billingCustomer,
|
|
17
|
+
expected,
|
|
18
|
+
key: logicalKey,
|
|
19
|
+
});
|
|
20
|
+
const attachRequest = prepareRenewalScheduleAttachment({
|
|
21
|
+
prepared,
|
|
22
|
+
apiVersion: context.apiVersion,
|
|
23
|
+
attachKey,
|
|
24
|
+
firstDispatchedAt,
|
|
25
|
+
});
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
The two preparation functions are pure exports. The host supplies and durably
|
|
29
|
+
retains the logical key, explicit attachment key, original first-dispatch time
|
|
30
|
+
and complete records under immutable authorization. An explicitly chosen attach
|
|
31
|
+
key may equal the logical key; no key is silently reused, derived or generated.
|
|
32
|
+
A future configure key must differ from the attachment key.
|
|
33
|
+
|
|
34
|
+
## Fixed acquisition profile
|
|
35
|
+
|
|
36
|
+
The initial profile supports platform requests using the configured
|
|
37
|
+
`2026-09-30.endive` API and Stripe 23 read shapes. Other versions reject before
|
|
38
|
+
reading. The public class selects the maintained single-attempt client,
|
|
39
|
+
including protection against the SDK's closed-connection special retry; every
|
|
40
|
+
read also requests zero automatic retries. Failures remain visible. There is no
|
|
41
|
+
fallback expansion, alternate endpoint or stale cache after a failed read.
|
|
42
|
+
|
|
43
|
+
The method performs these planned GETs in order:
|
|
44
|
+
|
|
45
|
+
1. Retrieve the exact subscription with `discounts`, `items.data.discounts`
|
|
46
|
+
and `items.data.price` expanded.
|
|
47
|
+
2. Retrieve the exact target price.
|
|
48
|
+
3. Retrieve the actual subscription's Customer, correlated to the authorized
|
|
49
|
+
customer-configured account and mode.
|
|
50
|
+
4. Retrieve each distinct coupon referenced by the expanded subscription/item
|
|
51
|
+
discounts, in first-occurrence order. Each level is capped at 20 discounts,
|
|
52
|
+
so at most 40 coupon GETs follow the three original reads.
|
|
53
|
+
|
|
54
|
+
Discounts must be expanded and have an actual coupon source. There is no
|
|
55
|
+
Discount retrieval endpoint used here. The item path
|
|
56
|
+
`items.data.discounts.source.coupon` exceeds the provider's four-property
|
|
57
|
+
expansion limit. Explicit coupon GET joins are part of the initial read plan,
|
|
58
|
+
including when a coupon was already expanded. Same-ID undeleted coupon results
|
|
59
|
+
expand string references in the canonical context. If a coupon was already
|
|
60
|
+
expanded, its complete canonical JSON must equal the separate GET result.
|
|
61
|
+
Duration, applicability, unknown fields and ordered arrays must agree; object
|
|
62
|
+
key order does not matter. Minimal expanded references and original-only or
|
|
63
|
+
GET-only fields are conservatively rejected as unsupported read-shape drift.
|
|
64
|
+
The join never merges or overwrites existing full source facts. Repeated
|
|
65
|
+
references are each compared, even when their coupon GET is deduplicated.
|
|
66
|
+
Contradictory available mode facts reject before a coupon GET.
|
|
67
|
+
|
|
68
|
+
All other full JSON fields, array ordering and unknown provider data are
|
|
69
|
+
retained within the existing bounded snapshot policy. No missing values become
|
|
70
|
+
null or empty lists. The result records `readProfile: "renewal-context-v1"`, a
|
|
71
|
+
server observation time and `providerQualification: "required"`. It does not
|
|
72
|
+
promise that multiple reads were atomic or that a context remains fresh later.
|
|
73
|
+
A preparation supplied from a different expansion/read shape must not be
|
|
74
|
+
silently rebound to this profile during a future writer invocation.
|
|
75
|
+
|
|
76
|
+
A nonnull observed `subscription.schedule` is returned as an observation. It is
|
|
77
|
+
not adopted as an acknowledgement of attachment. The existing initial pure
|
|
78
|
+
preparation still requires an unattached original. A later explicit replay of
|
|
79
|
+
an unknown attachment result needs a distinct material-state guard permitting
|
|
80
|
+
the actual nonnull association while preserving the original retained snapshot.
|
|
81
|
+
This reader does not fabricate a null association to bypass that guard.
|
|
82
|
+
|
|
83
|
+
## Bound request and remaining writer contract
|
|
84
|
+
|
|
85
|
+
The pure builder validates the retained logical preparation and explicit key.
|
|
86
|
+
It binds version, attach stage, platform scope, actual API version, logical
|
|
87
|
+
binding, method/path, complete payload `{ from_subscription: subscriptionId }`,
|
|
88
|
+
key and original first-dispatch time. It generates no phase, metadata, arbitrary
|
|
89
|
+
create option, receipt or provider acknowledgement.
|
|
90
|
+
|
|
91
|
+
No attachment writer is exposed by these helpers. There are currently no
|
|
92
|
+
accepted provider execution profiles. A positive structural preflight remains
|
|
93
|
+
insufficient to authorize a POST; callers cannot unlock one with a qualification
|
|
94
|
+
flag. Direct existing forever discount IDs are representable by the projection
|
|
95
|
+
helpers, while actual mirroring and preservation require separate provider
|
|
96
|
+
qualification. Empty discount reads do not prove suppression versus inheritance
|
|
97
|
+
and remain unsupported at projection preflight, even when the Customer has no
|
|
98
|
+
observed discount. Reading such facts does not qualify their transition.
|
|
99
|
+
|
|
100
|
+
A future writer must reacquire this full scoped context before its one POST.
|
|
101
|
+
Initial dispatch requires no attached schedule. Explicit lost-response replay
|
|
102
|
+
must use the same retained full request/key/time, permit a newly observed
|
|
103
|
+
nonnull association without adopting it by shape, and keep provider conflicts
|
|
104
|
+
visible. A local replay age limit below 24 hours cannot guarantee replay after
|
|
105
|
+
provider pruning. No retries, configure chaining or cancel/release rollback are
|
|
106
|
+
implemented here. A successful future attachment acknowledgement must remain
|
|
107
|
+
`attached_unconfigured`; target pending/effective states require separately
|
|
108
|
+
qualified configuration and observation.
|
|
109
|
+
|
|
110
|
+
See the [replacement contract](renewal-price-replacements.md) and
|
|
111
|
+
[phase assembly](renewal-phase-assembly.md) for baseline, replay and observation
|
|
112
|
+
boundaries. Read comparison is best effort and cannot exclude concurrent
|
|
113
|
+
Dashboard or other provider writers.
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
# Renewal phase assembly
|
|
2
|
+
|
|
3
|
+
The internal `renewalAggregate` module classifies an original subscription and
|
|
4
|
+
builds a bound two-phase configure candidate. It makes no provider call and is
|
|
5
|
+
not a public package entrypoint. It complements the public
|
|
6
|
+
[preparation contract](renewal-price-replacements.md) and internal
|
|
7
|
+
[preservation mappings](renewal-preservation-mappings.md).
|
|
8
|
+
|
|
9
|
+
A candidate always has `providerQualification: "required"`. This describes a
|
|
10
|
+
remaining requirement, not authorization to dispatch. Host-supplied flags cannot
|
|
11
|
+
prove provider behavior, ownership, original configuration or historical intent.
|
|
12
|
+
The HTTP executor must reject unqualified required contexts before a write.
|
|
13
|
+
|
|
14
|
+
## Original-source preflight
|
|
15
|
+
|
|
16
|
+
`preflightRenewalReplacement` accepts:
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
{
|
|
20
|
+
prepared,
|
|
21
|
+
freshSubscription,
|
|
22
|
+
targetPrice,
|
|
23
|
+
billingCustomer,
|
|
24
|
+
apiVersion,
|
|
25
|
+
observedAt,
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`prepared` is the privately retained `PreparedRenewalPriceReplacement`, including
|
|
30
|
+
its original snapshots and logical key. The function reconstructs that binding
|
|
31
|
+
instead of trusting its string. Source, target and correlated billing Customer
|
|
32
|
+
reads must agree with the retained snapshots. A missing retained billing Customer
|
|
33
|
+
is unsupported by this aggregate profile.
|
|
34
|
+
|
|
35
|
+
The host obtains fresh provider reads, authorizes the original buyer and target,
|
|
36
|
+
and retains consent and exclusive operation ownership. `observedAt` is a bounded
|
|
37
|
+
Unix timestamp within the original paid item period. It neither proves freshness
|
|
38
|
+
nor changes the expected renewal boundary. Use the actual configured
|
|
39
|
+
`BetterStripe.stripeApiVersion`; this profile supports `2026-09-30.endive` and
|
|
40
|
+
rejects an explicit preview version instead of silently replacing it.
|
|
41
|
+
|
|
42
|
+
Preflight checks exact customer account, customer, subscription, item, current
|
|
43
|
+
price/product, quantity, current period, target and currency. It rejects known
|
|
44
|
+
unsupported original cancellation, trial, pending, threshold, managed and special
|
|
45
|
+
billing state. Legacy source and explicit payment-setting restrictions from
|
|
46
|
+
preparation continue to apply. Valid product IDs may be custom nonblank IDs.
|
|
47
|
+
|
|
48
|
+
The paid-item profile requires an explicitly read `current_trial: null`. A
|
|
49
|
+
nonnull current or future item trial rejects even when the overall subscription
|
|
50
|
+
status is `active`. Missing item-trial evidence is unsupported, not replaced with
|
|
51
|
+
an invented null. Historical subscription trial fields remain in the snapshot.
|
|
52
|
+
|
|
53
|
+
Known financial settings are classified before attachment, including actual
|
|
54
|
+
subscription automatic tax and liability, collection method, invoice settings,
|
|
55
|
+
default payment method, routing and item settings. Invoice `days_until_due` is
|
|
56
|
+
read from the top-level Subscription field in Stripe 23, not from an invented
|
|
57
|
+
Subscription invoice-settings field. Available expanded payment-method customer,
|
|
58
|
+
account and mode facts must correlate with the original buyer.
|
|
59
|
+
|
|
60
|
+
Disabled automatic-tax reasons, unknown liability/collection/issuer enums,
|
|
61
|
+
malformed invoice settings, deleted routing references, invalid transfer
|
|
62
|
+
percentages and incompatible automatic/manual tax combinations reject at this
|
|
63
|
+
stage. A mapping that is knowably unsupported must not be deferred until after a
|
|
64
|
+
mutating attach. Fields available only on the acknowledged schedule are checked
|
|
65
|
+
later, without inventing a phase or acknowledgement during source preflight.
|
|
66
|
+
|
|
67
|
+
Success is `preflighted_for_projection`, with the exact selectors, quantity and
|
|
68
|
+
computed profile. Unsupported source settings return `unsupported`; observed
|
|
69
|
+
binding or source drift returns `conflict`. Success is not pending or effective.
|
|
70
|
+
|
|
71
|
+
## Acknowledged configure candidate
|
|
72
|
+
|
|
73
|
+
`projectRenewalConfiguration` takes the same source inputs plus:
|
|
74
|
+
|
|
75
|
+
```ts
|
|
76
|
+
{
|
|
77
|
+
attachReceipt,
|
|
78
|
+
schedule,
|
|
79
|
+
configureKey,
|
|
80
|
+
firstDispatchedAt,
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The host retains an immutable attach request and its successful provider
|
|
85
|
+
acknowledgement. The attach request binds version, stage, platform scope, actual
|
|
86
|
+
API version, logical identity, POST path, exact `from_subscription` payload,
|
|
87
|
+
explicit key and retained first-dispatch time. Its receipt binds that request,
|
|
88
|
+
the exact acknowledged schedule, subscription, customer account and mode, and the
|
|
89
|
+
complete bounded provider schedule snapshot. These records are unsigned server
|
|
90
|
+
data, not signatures or a provider history service. A schedule found by GET or a
|
|
91
|
+
nonnull subscription association does not establish this operation's ownership.
|
|
92
|
+
|
|
93
|
+
Supply the actual post-attach subscription association. The aggregate validator
|
|
94
|
+
requires the exact acknowledged schedule ID and explicitly permits that known
|
|
95
|
+
transition from the retained original `schedule: null`. It does not replace a
|
|
96
|
+
fresh schedule field with null to reuse the preparation validator.
|
|
97
|
+
|
|
98
|
+
The fresh schedule must still match the complete acknowledged baseline and
|
|
99
|
+
defaults. It must be active, platform scoped, linked to the original buyer and
|
|
100
|
+
subscription, and contain the one expected current phase. Current schedule and
|
|
101
|
+
phase boundaries must agree with the retained paid item period. Unrelated future
|
|
102
|
+
phases, drift, cancellation/release state, active pause configuration and unknown
|
|
103
|
+
mapping fields reject. Unchanged defaults are validated even though the configure
|
|
104
|
+
payload leaves them untouched.
|
|
105
|
+
|
|
106
|
+
Effective collection method, automatic tax and invoice issuer are derived from
|
|
107
|
+
actual phase/default/subscription reads and checked against the already-qualified
|
|
108
|
+
original source context. Metadata actions must already match current original
|
|
109
|
+
subscription/item values. Flattened subscription metadata is not converted into
|
|
110
|
+
new phase actions.
|
|
111
|
+
|
|
112
|
+
An unsupported mapping discovered after a valid acknowledgement returns
|
|
113
|
+
`attached_unconfigured` with the owned schedule ID and reason. The host retains
|
|
114
|
+
the receipt. The SDK does not conceal the gap by releasing/canceling the schedule,
|
|
115
|
+
rolling back, using another subscription POST or claiming success. Receipt,
|
|
116
|
+
association and baseline drift remain conflicts.
|
|
117
|
+
|
|
118
|
+
## Tax values and override levels
|
|
119
|
+
|
|
120
|
+
This finite profile requires explicit tax-rate arrays on original subscription
|
|
121
|
+
and item reads and on acknowledged phase and item reads. Null or absent
|
|
122
|
+
hierarchies are unsupported, not converted into empty arrays. Such cases require
|
|
123
|
+
a separately established inheritance mapping before they can become eligible.
|
|
124
|
+
|
|
125
|
+
Ordered original subscription `default_tax_rates` IDs must match the current
|
|
126
|
+
phase's ordered default IDs. Ordered original item IDs must match the phase
|
|
127
|
+
item's IDs. An empty item array means no explicit item override, so the
|
|
128
|
+
subscription or phase default applies. The renderer uses the supported Emptyable
|
|
129
|
+
clear representation for an acknowledged explicit empty item array.
|
|
130
|
+
|
|
131
|
+
The comparison preserves override level as well as IDs. Introducing an item
|
|
132
|
+
override equal to current phase defaults is rejected, as is removing an original
|
|
133
|
+
item override while its current effective IDs happen to remain the same. Current
|
|
134
|
+
effective equality cannot authorize changing future inheritance behavior.
|
|
135
|
+
Automatic tax cannot coexist with nonempty manual phase or item rates.
|
|
136
|
+
|
|
137
|
+
## Phases, profile and request identity
|
|
138
|
+
|
|
139
|
+
The current phase keeps the provider's exact original start/end, original price,
|
|
140
|
+
quantity, currency, accepted settings and existing discount IDs. Its existing
|
|
141
|
+
known `proration_behavior` is preserved. Top-level update proration is `none`.
|
|
142
|
+
The future phase starts at that verified end, selects the exact target price and
|
|
143
|
+
same quantity, preserves accepted settings/redemptions, and has transition
|
|
144
|
+
proration `none`. It uses the target price's recurring interval/count as a
|
|
145
|
+
duration instead of a locally calculated future end date. End behavior is
|
|
146
|
+
`release`; defaults and arbitrary schedule metadata are not rewritten.
|
|
147
|
+
|
|
148
|
+
The computed profile records actual API version, known classic/flexible billing
|
|
149
|
+
mode, same/changed cadence and ordinary/calendar-edge anchor class. Cadence is the
|
|
150
|
+
exact interval and count, not an amount comparison or an assumed month/year
|
|
151
|
+
conversion. Same cadence uses automatic future anchoring; changed cadence uses
|
|
152
|
+
`phase_start` at the verified renewal only for the supported configuration class.
|
|
153
|
+
Changed cadence with an explicit anchor configuration is unsupported. Reapplying
|
|
154
|
+
a current `phase_start` anchor is rejected unless it agrees with the retained
|
|
155
|
+
numeric original anchor and current phase start.
|
|
156
|
+
|
|
157
|
+
Known monthly/yearly anchors on days 29–31 are classified as calendar edges.
|
|
158
|
+
Unknown modes/configurations, invalid numeric anchors and unqualified profiles
|
|
159
|
+
reject. Classification and synthetic dates do not prove month-end, leap-year,
|
|
160
|
+
invoice, proration, computed phase-end or release behavior on Stripe.
|
|
161
|
+
|
|
162
|
+
Success is `projected_configure_request`. Its complete normalized POST payload is
|
|
163
|
+
bound with stage, platform scope, actual API version, path, explicit configure
|
|
164
|
+
key, logical identity, full attach-receipt identity, full acknowledged baseline,
|
|
165
|
+
unchanged defaults fingerprint and retained first-dispatch time. The configure
|
|
166
|
+
key must differ from the attach key. Keys and times are not silently generated,
|
|
167
|
+
rotated or reset. Bindings and snapshots can contain private billing data; retain
|
|
168
|
+
them only on the trusted server, not in browser responses or logs.
|
|
169
|
+
|
|
170
|
+
The original item ID is bound for authorization. A future price transition is
|
|
171
|
+
not assumed to preserve that ID. Effectiveness requires an observer to correlate
|
|
172
|
+
the owned configured provider phase with the unique target successor item on the
|
|
173
|
+
original subscription. A POST acknowledgement, matching price, elapsed time,
|
|
174
|
+
clock advance, manual release or browser redirect alone is insufficient.
|
|
175
|
+
|
|
176
|
+
Provider qualification, single-attempt HTTP dispatch, retained-key lost-response
|
|
177
|
+
recovery and observation remain separate gates. Snapshot equality is not atomic
|
|
178
|
+
provider compare-and-swap; host serialization cannot exclude Dashboard or other
|
|
179
|
+
provider writers. Required consumer contexts outside this finite profile remain
|
|
180
|
+
open instead of being replaced by a provenance flag or hidden fallback.
|
|
@@ -46,6 +46,8 @@ Product IDs may be provider-valid custom nonblank IDs, as well as generated
|
|
|
46
46
|
`prod_` IDs. Original and target product selectors must still match exactly.
|
|
47
47
|
The internal [preservation mappings](renewal-preservation-mappings.md) document
|
|
48
48
|
field projection boundaries separately from complete schedule eligibility.
|
|
49
|
+
The internal [phase assembly contract](renewal-phase-assembly.md) describes
|
|
50
|
+
preflight, acknowledged baselines and non-dispatchable configuration candidates.
|
|
49
51
|
|
|
50
52
|
The subscription's actual `currency` must match both prices' default `currency`.
|
|
51
53
|
This helper does not select `currency_options` or infer an alternative amount.
|
|
@@ -167,25 +169,64 @@ field is not proof of a lossless provider transition. The configure mapper must
|
|
|
167
169
|
resolve every applicable row before the first mutation; no response-object spread
|
|
168
170
|
or extra `subscriptions.update` workaround is permitted.
|
|
169
171
|
|
|
170
|
-
| Original setting | Required mapping or explicit unsupported boundary
|
|
171
|
-
| ----------------------------------- |
|
|
172
|
-
| 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.
|
|
173
|
-
| 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.
|
|
174
|
-
| Discounts | Preserve existing discount IDs, order, duration and item/subscription precedence. Omission
|
|
175
|
-
| 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.
|
|
176
|
-
| 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.
|
|
177
|
-
| 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.
|
|
178
|
-
| 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.
|
|
179
|
-
| 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.
|
|
180
|
-
| 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.
|
|
181
|
-
| 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.
|
|
182
|
-
| 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.
|
|
183
|
-
| 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.
|
|
184
|
-
| 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.
|
|
185
|
-
| 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.
|
|
172
|
+
| Original setting | Required mapping or explicit unsupported boundary |
|
|
173
|
+
| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
174
|
+
| 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. |
|
|
175
|
+
| 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. |
|
|
176
|
+
| Discounts | Preserve existing discount IDs, order, duration and item/subscription precedence. Omission and provider empty-string clearing have different write semantics. Current empty discount reads do not prove historical suppression or inheritance; those contexts remain unsupported. Re-redeeming a coupon can restart duration. Establish target-product eligibility and provenance before supporting a discounted transition. |
|
|
177
|
+
| 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. |
|
|
178
|
+
| 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. |
|
|
179
|
+
| 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. |
|
|
180
|
+
| 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. |
|
|
181
|
+
| 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. |
|
|
182
|
+
| 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. |
|
|
183
|
+
| 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. |
|
|
184
|
+
| 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. |
|
|
185
|
+
| 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. |
|
|
186
|
+
| 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. |
|
|
187
|
+
| 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. |
|
|
186
188
|
|
|
187
189
|
The completed mapper specification and recovery contract must independently fit
|
|
188
190
|
the configure/reconciliation ticket's estimate before write implementation starts.
|
|
189
191
|
Split further when needed, preserving the complete cross-product renewal outcome.
|
|
190
192
|
Unsupported boundaries must remain visible to the host and in acceptance criteria.
|
|
191
193
|
Controlled unit tests alone cannot qualify live preservation or consumer policy.
|
|
194
|
+
|
|
195
|
+
## Provider context reads and retained attachment requests
|
|
196
|
+
|
|
197
|
+
The [renewal context reader](renewal-context-reads.md) acquires a fixed provider
|
|
198
|
+
read profile and prepares an immutable attachment request. It does not attach a
|
|
199
|
+
schedule. Provider qualification and the remaining attachment, configuration and
|
|
200
|
+
observation stages are still required before this becomes a usable replacement
|
|
201
|
+
workflow.
|
|
202
|
+
|
|
203
|
+
## Unknown configuration outcomes and observation
|
|
204
|
+
|
|
205
|
+
A future explicit replay of an unknown configure result must retain the same
|
|
206
|
+
complete request, key and original first-dispatch time. It may dispatch only
|
|
207
|
+
while the freshly read owned schedule still equals the complete retained
|
|
208
|
+
preconfigure baseline, preserved defaults and original subscription material,
|
|
209
|
+
and elapsed time is less than 24 hours. This local limit is not permanent
|
|
210
|
+
provider replay assurance. A changed or already applied schedule is handed to
|
|
211
|
+
observation; it must not be reprojected into another initial request.
|
|
212
|
+
|
|
213
|
+
A provider GET is not a POST acknowledgement. Sufficient exact provider evidence
|
|
214
|
+
may eventually recover pending or effective state without an acknowledgement;
|
|
215
|
+
otherwise the outcome remains unknown. If a configure acknowledgement exists,
|
|
216
|
+
retain its complete canonical baseline and correlate subsequent observations
|
|
217
|
+
with it. Pending requires the exact future phase, original boundary, current
|
|
218
|
+
paid terms/defaults and linked buyer/subscription.
|
|
219
|
+
Effective state while the target phase is current requires a unique authorized
|
|
220
|
+
target item, matching quantity, currency, applicable period/settings and owned
|
|
221
|
+
phase/subscription relation. Do not require the old item ID to survive a price
|
|
222
|
+
transition. Before implementing this observer, define and independently review
|
|
223
|
+
fixed normalization covering the full retained desired request and
|
|
224
|
+
provider-computed phase-end/duration evidence. Context reading does not provide
|
|
225
|
+
that observer normalization.
|
|
226
|
+
|
|
227
|
+
Canceled, released or completed facts alone do not prove effectiveness. Manual
|
|
228
|
+
release, missing historical correlation, matching price or wall time leave
|
|
229
|
+
causal effectiveness unknown. Preserve acknowledged receipts through read
|
|
230
|
+
failure. No automatic replay, key rotation, stage chaining, cancel/release or
|
|
231
|
+
rollback follows an unknown result. Snapshot equality is not atomic provider
|
|
232
|
+
compare-and-swap or proof that other writers were excluded.
|
package/package.json
CHANGED