@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.
Files changed (110) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +1 -1
  3. package/dist/client/billing/renewalAggregate/configure.d.ts +35 -0
  4. package/dist/client/billing/renewalAggregate/configure.d.ts.map +1 -0
  5. package/dist/client/billing/renewalAggregate/configure.js +96 -0
  6. package/dist/client/billing/renewalAggregate/configure.js.map +1 -0
  7. package/dist/client/billing/renewalAggregate/index.d.ts +3 -0
  8. package/dist/client/billing/renewalAggregate/index.d.ts.map +1 -0
  9. package/dist/client/billing/renewalAggregate/index.js +3 -0
  10. package/dist/client/billing/renewalAggregate/index.js.map +1 -0
  11. package/dist/client/billing/renewalAggregate/phaseContext.d.ts +176 -0
  12. package/dist/client/billing/renewalAggregate/phaseContext.d.ts.map +1 -0
  13. package/dist/client/billing/renewalAggregate/phaseContext.js +112 -0
  14. package/dist/client/billing/renewalAggregate/phaseContext.js.map +1 -0
  15. package/dist/client/billing/renewalAggregate/phases.d.ts +7 -0
  16. package/dist/client/billing/renewalAggregate/phases.d.ts.map +1 -0
  17. package/dist/client/billing/renewalAggregate/phases.js +192 -0
  18. package/dist/client/billing/renewalAggregate/phases.js.map +1 -0
  19. package/dist/client/billing/renewalAggregate/preflight.d.ts +594 -0
  20. package/dist/client/billing/renewalAggregate/preflight.d.ts.map +1 -0
  21. package/dist/client/billing/renewalAggregate/preflight.js +164 -0
  22. package/dist/client/billing/renewalAggregate/preflight.js.map +1 -0
  23. package/dist/client/billing/renewalAggregate/profile.d.ts +8 -0
  24. package/dist/client/billing/renewalAggregate/profile.d.ts.map +1 -0
  25. package/dist/client/billing/renewalAggregate/profile.js +60 -0
  26. package/dist/client/billing/renewalAggregate/profile.js.map +1 -0
  27. package/dist/client/billing/renewalAggregate/receipt.d.ts +40 -0
  28. package/dist/client/billing/renewalAggregate/receipt.d.ts.map +1 -0
  29. package/dist/client/billing/renewalAggregate/receipt.js +62 -0
  30. package/dist/client/billing/renewalAggregate/receipt.js.map +1 -0
  31. package/dist/client/billing/renewalAggregate/shared.d.ts +51 -0
  32. package/dist/client/billing/renewalAggregate/shared.d.ts.map +1 -0
  33. package/dist/client/billing/renewalAggregate/shared.js +87 -0
  34. package/dist/client/billing/renewalAggregate/shared.js.map +1 -0
  35. package/dist/client/billing/renewalAggregate/sourceDiscounts.d.ts +42 -0
  36. package/dist/client/billing/renewalAggregate/sourceDiscounts.d.ts.map +1 -0
  37. package/dist/client/billing/renewalAggregate/sourceDiscounts.js +90 -0
  38. package/dist/client/billing/renewalAggregate/sourceDiscounts.js.map +1 -0
  39. package/dist/client/billing/renewalAggregate/sourceSettings.d.ts +136 -0
  40. package/dist/client/billing/renewalAggregate/sourceSettings.d.ts.map +1 -0
  41. package/dist/client/billing/renewalAggregate/sourceSettings.js +82 -0
  42. package/dist/client/billing/renewalAggregate/sourceSettings.js.map +1 -0
  43. package/dist/client/billing/renewalAggregate/taxRetention.d.ts +8 -0
  44. package/dist/client/billing/renewalAggregate/taxRetention.d.ts.map +1 -0
  45. package/dist/client/billing/renewalAggregate/taxRetention.js +23 -0
  46. package/dist/client/billing/renewalAggregate/taxRetention.js.map +1 -0
  47. package/dist/client/billing/renewalAttach/couponJoins.d.ts +23 -0
  48. package/dist/client/billing/renewalAttach/couponJoins.d.ts.map +1 -0
  49. package/dist/client/billing/renewalAttach/couponJoins.js +76 -0
  50. package/dist/client/billing/renewalAttach/couponJoins.js.map +1 -0
  51. package/dist/client/billing/renewalAttach/index.d.ts +3 -0
  52. package/dist/client/billing/renewalAttach/index.d.ts.map +1 -0
  53. package/dist/client/billing/renewalAttach/index.js +3 -0
  54. package/dist/client/billing/renewalAttach/index.js.map +1 -0
  55. package/dist/client/billing/renewalAttach/reader.d.ts +141 -0
  56. package/dist/client/billing/renewalAttach/reader.d.ts.map +1 -0
  57. package/dist/client/billing/renewalAttach/reader.js +80 -0
  58. package/dist/client/billing/renewalAttach/reader.js.map +1 -0
  59. package/dist/client/billing/renewalAttach/request.d.ts +30 -0
  60. package/dist/client/billing/renewalAttach/request.d.ts.map +1 -0
  61. package/dist/client/billing/renewalAttach/request.js +39 -0
  62. package/dist/client/billing/renewalAttach/request.js.map +1 -0
  63. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +32 -32
  64. package/dist/client/connect/payoutSyncTestHelpers.d.ts +16 -16
  65. package/dist/client/index.d.ts +3 -5
  66. package/dist/client/index.d.ts.map +1 -1
  67. package/dist/client/index.js +3 -3
  68. package/dist/client/index.js.map +1 -1
  69. package/dist/client/renewal.d.ts +8 -0
  70. package/dist/client/renewal.d.ts.map +1 -0
  71. package/dist/client/renewal.js +4 -0
  72. package/dist/client/renewal.js.map +1 -0
  73. package/dist/client/renewalContextClient.d.ts +130 -0
  74. package/dist/client/renewalContextClient.d.ts.map +1 -0
  75. package/dist/client/renewalContextClient.js +10 -0
  76. package/dist/client/renewalContextClient.js.map +1 -0
  77. package/dist/client/usage/observationClient.d.ts +2 -2
  78. package/dist/client/usage/observationClient.d.ts.map +1 -1
  79. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  80. package/dist/component/balanceFunding/mutations.d.ts +43 -43
  81. package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
  82. package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
  83. package/dist/component/earnings/triggers.d.ts +16 -16
  84. package/docs/renewal-context-reads.md +113 -0
  85. package/docs/renewal-phase-assembly.md +180 -0
  86. package/docs/renewal-price-replacements.md +57 -16
  87. package/package.json +1 -1
  88. package/src/client/billing/renewalAggregate/configure.test.ts +372 -0
  89. package/src/client/billing/renewalAggregate/configure.ts +164 -0
  90. package/src/client/billing/renewalAggregate/index.ts +2 -0
  91. package/src/client/billing/renewalAggregate/phaseContext.ts +144 -0
  92. package/src/client/billing/renewalAggregate/phases.ts +247 -0
  93. package/src/client/billing/renewalAggregate/preflight.test.ts +233 -0
  94. package/src/client/billing/renewalAggregate/preflight.ts +211 -0
  95. package/src/client/billing/renewalAggregate/profile.ts +76 -0
  96. package/src/client/billing/renewalAggregate/receipt.ts +76 -0
  97. package/src/client/billing/renewalAggregate/shared.ts +106 -0
  98. package/src/client/billing/renewalAggregate/sourceAndTaxRetention.test.ts +247 -0
  99. package/src/client/billing/renewalAggregate/sourceDiscounts.ts +112 -0
  100. package/src/client/billing/renewalAggregate/sourceSettings.ts +88 -0
  101. package/src/client/billing/renewalAggregate/taxRetention.ts +28 -0
  102. package/src/client/billing/renewalAttach/couponEvidence.test.ts +104 -0
  103. package/src/client/billing/renewalAttach/couponJoins.ts +95 -0
  104. package/src/client/billing/renewalAttach/index.ts +9 -0
  105. package/src/client/billing/renewalAttach/reader.test.ts +409 -0
  106. package/src/client/billing/renewalAttach/reader.ts +131 -0
  107. package/src/client/billing/renewalAttach/request.ts +49 -0
  108. package/src/client/index.ts +3 -8
  109. package/src/client/renewal.ts +13 -0
  110. 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 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. |
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.81.0",
3
+ "version": "0.83.0",
4
4
  "description": "Convex component for Stripe Accounts v2, subscriptions, metered billing and Connect marketplaces, with React workflows.",
5
5
  "keywords": [
6
6
  "stripe",