@fantastic.dev/better-stripe 0.81.0 → 0.82.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 (71) hide show
  1. package/CHANGELOG.md +6 -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/connect/payoutAdoptionTestHelpers.d.ts +32 -32
  48. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +16 -16
  49. package/dist/component/balanceFunding/mutations.d.ts +43 -43
  50. package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
  51. package/dist/component/payoutRelease/queries.d.ts +2 -2
  52. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  53. package/dist/component/processingCostReconciliation/rollback.d.ts +1 -1
  54. package/dist/component/usage/allowance.fixtures.d.ts +16 -16
  55. package/docs/renewal-phase-assembly.md +180 -0
  56. package/docs/renewal-price-replacements.md +2 -0
  57. package/package.json +1 -1
  58. package/src/client/billing/renewalAggregate/configure.test.ts +372 -0
  59. package/src/client/billing/renewalAggregate/configure.ts +164 -0
  60. package/src/client/billing/renewalAggregate/index.ts +2 -0
  61. package/src/client/billing/renewalAggregate/phaseContext.ts +144 -0
  62. package/src/client/billing/renewalAggregate/phases.ts +247 -0
  63. package/src/client/billing/renewalAggregate/preflight.test.ts +233 -0
  64. package/src/client/billing/renewalAggregate/preflight.ts +211 -0
  65. package/src/client/billing/renewalAggregate/profile.ts +76 -0
  66. package/src/client/billing/renewalAggregate/receipt.ts +76 -0
  67. package/src/client/billing/renewalAggregate/shared.ts +106 -0
  68. package/src/client/billing/renewalAggregate/sourceAndTaxRetention.test.ts +247 -0
  69. package/src/client/billing/renewalAggregate/sourceDiscounts.ts +112 -0
  70. package/src/client/billing/renewalAggregate/sourceSettings.ts +88 -0
  71. package/src/client/billing/renewalAggregate/taxRetention.ts +28 -0
@@ -22,14 +22,6 @@ export declare const begin: import("convex/server").RegisteredMutation<"public",
22
22
  requestKey: string;
23
23
  scopeKey: string;
24
24
  }, Promise<{
25
- reason: "identity_changed" | "revision_changed" | "scope_busy";
26
- retryable: false;
27
- status: "conflict";
28
- } | {
29
- reason: "policy_invalid";
30
- retryable: false;
31
- status: "rejected";
32
- } | {
33
25
  operation: {
34
26
  accountId: string;
35
27
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -40,6 +32,14 @@ export declare const begin: import("convex/server").RegisteredMutation<"public",
40
32
  } | {
41
33
  enabled: boolean;
42
34
  status: "unchanged";
35
+ } | {
36
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
37
+ retryable: false;
38
+ status: "conflict";
39
+ } | {
40
+ reason: "policy_invalid";
41
+ retryable: false;
42
+ status: "rejected";
43
43
  } | {
44
44
  reason: "provider_pending";
45
45
  retryable: true;
@@ -395,14 +395,6 @@ export declare const prepare: import("convex/server").RegisteredMutation<"public
395
395
  requestKey: string;
396
396
  scopeKey: string;
397
397
  }, Promise<{
398
- reason: "identity_changed" | "revision_changed" | "scope_busy";
399
- retryable: false;
400
- status: "conflict";
401
- } | {
402
- reason: "policy_invalid";
403
- retryable: false;
404
- status: "rejected";
405
- } | {
406
398
  operation: {
407
399
  accountId: string;
408
400
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -413,6 +405,14 @@ export declare const prepare: import("convex/server").RegisteredMutation<"public
413
405
  } | {
414
406
  enabled: boolean;
415
407
  status: "unchanged";
408
+ } | {
409
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
410
+ retryable: false;
411
+ status: "conflict";
412
+ } | {
413
+ reason: "policy_invalid";
414
+ retryable: false;
415
+ status: "rejected";
416
416
  } | {
417
417
  reason: "provider_pending";
418
418
  retryable: true;
@@ -595,6 +595,22 @@ export declare const startWorkflow: import("convex/server").RegisteredMutation<"
595
595
  } & {
596
596
  providerAction: string;
597
597
  }, Promise<{
598
+ reason: "history_incomplete" | "provider_outcome_unknown";
599
+ retryable: false;
600
+ status: "unknown";
601
+ } | {
602
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
603
+ retryable: false;
604
+ status: "conflict";
605
+ } | {
606
+ reason: "invalid_scope" | "policy_invalid" | "unsupported_source";
607
+ retryable: false;
608
+ status: "rejected";
609
+ } | {
610
+ reason: "provider_pending";
611
+ retryable: true;
612
+ status: "not_ready";
613
+ } | {
598
614
  operation: {
599
615
  accountId: string;
600
616
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -611,7 +627,16 @@ export declare const startWorkflow: import("convex/server").RegisteredMutation<"
611
627
  version: number;
612
628
  };
613
629
  status: "canceled";
614
- } | {
630
+ }>>;
631
+ export declare const resumeWorkflow: import("convex/server").RegisteredMutation<"public", {
632
+ accountId: string;
633
+ definitionVersion: string;
634
+ operationId: import("convex/values").GenericId<"balanceFundingOperations">;
635
+ providerApiVersion: string;
636
+ scopeKey: string;
637
+ stripeSubscriptionId: string;
638
+ version: number;
639
+ }, Promise<{
615
640
  reason: "history_incomplete" | "provider_outcome_unknown";
616
641
  retryable: false;
617
642
  status: "unknown";
@@ -627,16 +652,7 @@ export declare const startWorkflow: import("convex/server").RegisteredMutation<"
627
652
  reason: "provider_pending";
628
653
  retryable: true;
629
654
  status: "not_ready";
630
- }>>;
631
- export declare const resumeWorkflow: import("convex/server").RegisteredMutation<"public", {
632
- accountId: string;
633
- definitionVersion: string;
634
- operationId: import("convex/values").GenericId<"balanceFundingOperations">;
635
- providerApiVersion: string;
636
- scopeKey: string;
637
- stripeSubscriptionId: string;
638
- version: number;
639
- }, Promise<{
655
+ } | {
640
656
  operation: {
641
657
  accountId: string;
642
658
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -653,22 +669,6 @@ export declare const resumeWorkflow: import("convex/server").RegisteredMutation<
653
669
  version: number;
654
670
  };
655
671
  status: "canceled";
656
- } | {
657
- reason: "history_incomplete" | "provider_outcome_unknown";
658
- retryable: false;
659
- status: "unknown";
660
- } | {
661
- reason: "identity_changed" | "revision_changed" | "scope_busy";
662
- retryable: false;
663
- status: "conflict";
664
- } | {
665
- reason: "invalid_scope" | "policy_invalid" | "unsupported_source";
666
- retryable: false;
667
- status: "rejected";
668
- } | {
669
- reason: "provider_pending";
670
- retryable: true;
671
- status: "not_ready";
672
672
  }>>;
673
673
  export declare const cancelWorkflow: import("convex/server").RegisteredMutation<"public", {
674
674
  accountId: string;
@@ -2,14 +2,6 @@ import type { Infer } from "convex/values";
2
2
  import type { MutationCtx } from "../_generated/server.js";
3
3
  import { prepareArgs, finishPreparationArgs } from "./mutationValidators.js";
4
4
  export declare function prepareHandler(ctx: MutationCtx, args: Infer<typeof prepareArgs>): Promise<{
5
- reason: "identity_changed" | "revision_changed" | "scope_busy";
6
- retryable: false;
7
- status: "conflict";
8
- } | {
9
- reason: "policy_invalid";
10
- retryable: false;
11
- status: "rejected";
12
- } | {
13
5
  operation: {
14
6
  accountId: string;
15
7
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -20,6 +12,14 @@ export declare function prepareHandler(ctx: MutationCtx, args: Infer<typeof prep
20
12
  } | {
21
13
  enabled: boolean;
22
14
  status: "unchanged";
15
+ } | {
16
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
17
+ retryable: false;
18
+ status: "conflict";
19
+ } | {
20
+ reason: "policy_invalid";
21
+ retryable: false;
22
+ status: "rejected";
23
23
  } | {
24
24
  reason: "provider_pending";
25
25
  retryable: true;
@@ -163,10 +163,10 @@ export declare const snapshot: import("convex/server").RegisteredQuery<"public",
163
163
  accountId: string;
164
164
  ownerKey: string;
165
165
  }, Promise<{
166
- status: "held";
167
- reason: "snapshot_limit";
168
166
  transfers?: undefined;
169
167
  claims?: undefined;
168
+ status: "held";
169
+ reason: "snapshot_limit";
170
170
  } | {
171
171
  reason?: undefined;
172
172
  status: "ready";
@@ -1 +1 @@
1
- {"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../src/component/payoutRelease/queries.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAIlB,CAAC;AACH,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAiBd,CAAC;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BlB,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;GAQf,CAAC;AAEH,4FAA4F;AAC5F,eAAO,MAAM,QAAQ;;;;YAsBE,MAAM;YAAmB,gBAAgB;;;;;YAS3C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAE1B,CAAC"}
1
+ {"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../../src/component/payoutRelease/queries.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAIlB,CAAC;AACH,eAAO,MAAM,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UAiBd,CAAC;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BlB,CAAC;AAEH,eAAO,MAAM,IAAI;;;;;;;GAQf,CAAC;AAEH,4FAA4F;AAC5F,eAAO,MAAM,QAAQ;;;;;;YAsBE,MAAM;YAAmB,gBAAgB;;;YAS3C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAE1B,CAAC"}
@@ -14,7 +14,7 @@ export declare function checkRollback(ctx: MutationCtx, op: Doc<"processingCostR
14
14
  readonly bindFunding?: undefined;
15
15
  } | {
16
16
  reason?: undefined;
17
- readonly retryable?: undefined;
17
+ retryable?: undefined;
18
18
  readonly status: "ready";
19
19
  readonly bindFunding: boolean;
20
20
  }>;
@@ -2351,6 +2351,14 @@ export declare function setupAllowance(): Promise<{
2351
2351
  preparationId: import("convex/values").GenericId<"balanceFundingPreparations">;
2352
2352
  requestKey: string;
2353
2353
  result?: {
2354
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
2355
+ retryable: false;
2356
+ status: "conflict";
2357
+ } | {
2358
+ reason: "policy_invalid";
2359
+ retryable: false;
2360
+ status: "rejected";
2361
+ } | {
2354
2362
  operation: {
2355
2363
  accountId: string;
2356
2364
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -2361,14 +2369,6 @@ export declare function setupAllowance(): Promise<{
2361
2369
  } | {
2362
2370
  enabled: boolean;
2363
2371
  status: "unchanged";
2364
- } | {
2365
- reason: "identity_changed" | "revision_changed" | "scope_busy";
2366
- retryable: false;
2367
- status: "conflict";
2368
- } | {
2369
- reason: "policy_invalid";
2370
- retryable: false;
2371
- status: "rejected";
2372
2372
  } | {
2373
2373
  reason: "provider_pending";
2374
2374
  retryable: true;
@@ -2379,6 +2379,14 @@ export declare function setupAllowance(): Promise<{
2379
2379
  payload: import("convex/values").VString<string, "required">;
2380
2380
  preparationId: import("convex/values").VId<import("convex/values").GenericId<"balanceFundingPreparations">, "required">;
2381
2381
  result: import("convex/values").VUnion<{
2382
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
2383
+ retryable: false;
2384
+ status: "conflict";
2385
+ } | {
2386
+ reason: "policy_invalid";
2387
+ retryable: false;
2388
+ status: "rejected";
2389
+ } | {
2382
2390
  operation: {
2383
2391
  accountId: string;
2384
2392
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -2389,14 +2397,6 @@ export declare function setupAllowance(): Promise<{
2389
2397
  } | {
2390
2398
  enabled: boolean;
2391
2399
  status: "unchanged";
2392
- } | {
2393
- reason: "identity_changed" | "revision_changed" | "scope_busy";
2394
- retryable: false;
2395
- status: "conflict";
2396
- } | {
2397
- reason: "policy_invalid";
2398
- retryable: false;
2399
- status: "rejected";
2400
2400
  } | {
2401
2401
  reason: "provider_pending";
2402
2402
  retryable: true;
@@ -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.
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.82.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",