@fantastic.dev/better-stripe 0.86.0 → 0.88.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 (133) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +1 -1
  3. package/dist/client/billing/renewalObservation/active-scheduled.d.ts +6 -0
  4. package/dist/client/billing/renewalObservation/active-scheduled.d.ts.map +1 -0
  5. package/dist/client/billing/renewalObservation/active-scheduled.js +37 -0
  6. package/dist/client/billing/renewalObservation/active-scheduled.js.map +1 -0
  7. package/dist/client/billing/renewalObservation/common.d.ts +47 -0
  8. package/dist/client/billing/renewalObservation/common.d.ts.map +1 -0
  9. package/dist/client/billing/renewalObservation/common.js +39 -0
  10. package/dist/client/billing/renewalObservation/common.js.map +1 -0
  11. package/dist/client/billing/renewalObservation/configured-baseline.d.ts +76 -0
  12. package/dist/client/billing/renewalObservation/configured-baseline.d.ts.map +1 -0
  13. package/dist/client/billing/renewalObservation/configured-baseline.js +26 -0
  14. package/dist/client/billing/renewalObservation/configured-baseline.js.map +1 -0
  15. package/dist/client/billing/renewalObservation/coupon-discount-joins.d.ts +53 -0
  16. package/dist/client/billing/renewalObservation/coupon-discount-joins.d.ts.map +1 -0
  17. package/dist/client/billing/renewalObservation/coupon-discount-joins.js +103 -0
  18. package/dist/client/billing/renewalObservation/coupon-discount-joins.js.map +1 -0
  19. package/dist/client/billing/renewalObservation/invoice-tax-identity.d.ts +52 -0
  20. package/dist/client/billing/renewalObservation/invoice-tax-identity.d.ts.map +1 -0
  21. package/dist/client/billing/renewalObservation/invoice-tax-identity.js +49 -0
  22. package/dist/client/billing/renewalObservation/invoice-tax-identity.js.map +1 -0
  23. package/dist/client/billing/renewalObservation/pending-and-stage.d.ts +76 -0
  24. package/dist/client/billing/renewalObservation/pending-and-stage.d.ts.map +1 -0
  25. package/dist/client/billing/renewalObservation/pending-and-stage.js +36 -0
  26. package/dist/client/billing/renewalObservation/pending-and-stage.js.map +1 -0
  27. package/dist/client/billing/renewalObservation/phase-price-normalization.d.ts +57 -0
  28. package/dist/client/billing/renewalObservation/phase-price-normalization.d.ts.map +1 -0
  29. package/dist/client/billing/renewalObservation/phase-price-normalization.js +70 -0
  30. package/dist/client/billing/renewalObservation/phase-price-normalization.js.map +1 -0
  31. package/dist/client/billing/renewalObservation/planProjection.d.ts +8 -0
  32. package/dist/client/billing/renewalObservation/planProjection.d.ts.map +1 -0
  33. package/dist/client/billing/renewalObservation/planProjection.js +150 -0
  34. package/dist/client/billing/renewalObservation/planProjection.js.map +1 -0
  35. package/dist/client/billing/renewalObservation/reference-catalog.d.ts +37 -0
  36. package/dist/client/billing/renewalObservation/reference-catalog.d.ts.map +1 -0
  37. package/dist/client/billing/renewalObservation/reference-catalog.js +109 -0
  38. package/dist/client/billing/renewalObservation/reference-catalog.js.map +1 -0
  39. package/dist/client/billing/renewalObservation/schedule-templates.d.ts +74 -0
  40. package/dist/client/billing/renewalObservation/schedule-templates.d.ts.map +1 -0
  41. package/dist/client/billing/renewalObservation/schedule-templates.js +72 -0
  42. package/dist/client/billing/renewalObservation/schedule-templates.js.map +1 -0
  43. package/dist/client/billing/renewalObservation/scheduled-context.d.ts +44 -0
  44. package/dist/client/billing/renewalObservation/scheduled-context.d.ts.map +1 -0
  45. package/dist/client/billing/renewalObservation/scheduled-context.js +64 -0
  46. package/dist/client/billing/renewalObservation/scheduled-context.js.map +1 -0
  47. package/dist/client/billing/renewalObservation/scheduled-identity.d.ts +53 -0
  48. package/dist/client/billing/renewalObservation/scheduled-identity.d.ts.map +1 -0
  49. package/dist/client/billing/renewalObservation/scheduled-identity.js +95 -0
  50. package/dist/client/billing/renewalObservation/scheduled-identity.js.map +1 -0
  51. package/dist/client/billing/renewalObservation/scheduled-normalization.d.ts +59 -0
  52. package/dist/client/billing/renewalObservation/scheduled-normalization.d.ts.map +1 -0
  53. package/dist/client/billing/renewalObservation/scheduled-normalization.js +29 -0
  54. package/dist/client/billing/renewalObservation/scheduled-normalization.js.map +1 -0
  55. package/dist/client/billing/renewalObservation/settings-normalization.d.ts +54 -0
  56. package/dist/client/billing/renewalObservation/settings-normalization.d.ts.map +1 -0
  57. package/dist/client/billing/renewalObservation/settings-normalization.js +53 -0
  58. package/dist/client/billing/renewalObservation/settings-normalization.js.map +1 -0
  59. package/dist/client/billing/renewalObservation/stage-runner.d.ts +4 -0
  60. package/dist/client/billing/renewalObservation/stage-runner.d.ts.map +1 -0
  61. package/dist/client/billing/renewalObservation/stage-runner.js +34 -0
  62. package/dist/client/billing/renewalObservation/stage-runner.js.map +1 -0
  63. package/dist/client/billing/renewalObservation/weeklyPending.d.ts +13 -0
  64. package/dist/client/billing/renewalObservation/weeklyPending.d.ts.map +1 -0
  65. package/dist/client/billing/renewalObservation/weeklyPending.js +55 -0
  66. package/dist/client/billing/renewalObservation/weeklyPending.js.map +1 -0
  67. package/dist/client/billing/renewalV2/binding.d.ts +1 -1
  68. package/dist/client/billing/renewalV2/binding.d.ts.map +1 -1
  69. package/dist/client/billing/renewalV2/binding.js.map +1 -1
  70. package/dist/client/billing/renewalV2/configureInput.d.ts +1 -0
  71. package/dist/client/billing/renewalV2/configureInput.d.ts.map +1 -1
  72. package/dist/client/billing/renewalV2/configureInput.js +3 -3
  73. package/dist/client/billing/renewalV2/configureInput.js.map +1 -1
  74. package/dist/client/billing/renewalV2/configureReceipt.d.ts +19 -0
  75. package/dist/client/billing/renewalV2/configureReceipt.d.ts.map +1 -0
  76. package/dist/client/billing/renewalV2/configureReceipt.js +91 -0
  77. package/dist/client/billing/renewalV2/configureReceipt.js.map +1 -0
  78. package/dist/client/billing/renewalV2/index.d.ts +417 -0
  79. package/dist/client/billing/renewalV2/index.d.ts.map +1 -1
  80. package/dist/client/billing/renewalV2/index.js +73 -3
  81. package/dist/client/billing/renewalV2/index.js.map +1 -1
  82. package/dist/client/billing/renewalV2/observation.d.ts +19 -0
  83. package/dist/client/billing/renewalV2/observation.d.ts.map +1 -0
  84. package/dist/client/billing/renewalV2/observation.js +95 -0
  85. package/dist/client/billing/renewalV2/observation.js.map +1 -0
  86. package/dist/client/billing/renewalV2/observationInput.d.ts +77 -0
  87. package/dist/client/billing/renewalV2/observationInput.d.ts.map +1 -0
  88. package/dist/client/billing/renewalV2/observationInput.js +140 -0
  89. package/dist/client/billing/renewalV2/observationInput.js.map +1 -0
  90. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +32 -32
  91. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +16 -16
  92. package/dist/client/renewal.d.ts +4 -2
  93. package/dist/client/renewal.d.ts.map +1 -1
  94. package/dist/client/renewal.js +2 -1
  95. package/dist/client/renewal.js.map +1 -1
  96. package/dist/client/usage/observationClient.d.ts +2 -2
  97. package/dist/client/usage/observationClient.d.ts.map +1 -1
  98. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  99. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  100. package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
  101. package/dist/component/usage/allowance.fixtures.d.ts +16 -16
  102. package/docs/client-api.md +26 -0
  103. package/docs/renewal-context-reads.md +5 -1
  104. package/docs/renewal-material-observation.md +124 -0
  105. package/docs/renewal-phase-assembly.md +68 -0
  106. package/docs/renewal-price-replacements.md +3 -0
  107. package/package.json +1 -1
  108. package/src/client/billing/renewalObservation/active-scheduled.ts +67 -0
  109. package/src/client/billing/renewalObservation/common.ts +83 -0
  110. package/src/client/billing/renewalObservation/configured-baseline.ts +55 -0
  111. package/src/client/billing/renewalObservation/coupon-discount-joins.ts +163 -0
  112. package/src/client/billing/renewalObservation/invoice-tax-identity.ts +65 -0
  113. package/src/client/billing/renewalObservation/pending-and-stage.ts +89 -0
  114. package/src/client/billing/renewalObservation/phase-price-normalization.ts +106 -0
  115. package/src/client/billing/renewalObservation/planProjection.ts +177 -0
  116. package/src/client/billing/renewalObservation/reference-catalog.ts +150 -0
  117. package/src/client/billing/renewalObservation/schedule-templates.ts +118 -0
  118. package/src/client/billing/renewalObservation/scheduled-context.ts +98 -0
  119. package/src/client/billing/renewalObservation/scheduled-identity.ts +175 -0
  120. package/src/client/billing/renewalObservation/scheduled-normalization.ts +49 -0
  121. package/src/client/billing/renewalObservation/settings-normalization.ts +60 -0
  122. package/src/client/billing/renewalObservation/stage-runner.ts +30 -0
  123. package/src/client/billing/renewalObservation/weeklyPending.ts +81 -0
  124. package/src/client/billing/renewalV2/binding.ts +4 -1
  125. package/src/client/billing/renewalV2/configureInput.ts +3 -3
  126. package/src/client/billing/renewalV2/configureReceipt.test.ts +558 -0
  127. package/src/client/billing/renewalV2/configureReceipt.ts +96 -0
  128. package/src/client/billing/renewalV2/index.ts +131 -6
  129. package/src/client/billing/renewalV2/observation.boundary-review.test.ts +49 -0
  130. package/src/client/billing/renewalV2/observation.test.ts +334 -0
  131. package/src/client/billing/renewalV2/observation.ts +149 -0
  132. package/src/client/billing/renewalV2/observationInput.ts +167 -0
  133. package/src/client/renewal.ts +10 -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;
@@ -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;
@@ -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;
@@ -7,6 +7,32 @@ snapshots for an exact cross-product renewal request. It performs no provider I/
7
7
  and supplies no schedule writer. See the [renewal replacement contract](./renewal-price-replacements.md)
8
8
  for its selectors, private binding, required staged protocol and preservation gate.
9
9
 
10
+ ### Pure renewal material observation
11
+
12
+ ```ts
13
+ inspectRenewalScheduleMaterialV2(
14
+ options: InspectRenewalScheduleMaterialV2Options,
15
+ ): Promise<RenewalScheduleMaterialObservationV2>
16
+ ```
17
+
18
+ This standalone package export accepts complete raw `configuration`, five current
19
+ `reads` categories and optional raw `configureReceipt`. It rebuilds V2 bindings
20
+ and compares full material without provider I/O or trusted-store verification.
21
+ Its relations are `attached_unconfigured_match`, `pending_material_match`,
22
+ `current_target_material_match`, `terminal_facts_only`, `unknown` and `conflict`.
23
+ Acknowledgement and authentication remain unestablished. It is not a method on
24
+ `BetterStripe` or a schedule writer.
25
+
26
+ Both original and current `latest_invoice` fields are required. An `I0` to `I1`
27
+ change remains `conflict` with `effective_full_material_drift`; the five-read API
28
+ has no owned invoice-history proof. Pending without a raw configure response is
29
+ limited to the classic, changed-cadence, explicit-phase-start, one-week consistency
30
+ rule. Other unproved future durations remain unknown. See the
31
+ [material observation guide](renewal-material-observation.md) for complete input
32
+ fields, result limits, capture errors and the 500000-byte/10000-node/depth-40 bounds.
33
+
34
+ ### Component-backed methods
35
+
10
36
  All methods are available on the `BetterStripe` class instance. Methods that call the Stripe API are actions; methods that only read Convex data are queries.
11
37
 
12
38
  Methods named `get<Entity>` take the component document ID (exception: `getInvoice`, which takes the Stripe invoice ID); methods named `get<Entity>ByStripeId` take the Stripe ID (`acct_...`, `prod_...`, `price_...`, `cs_...`, `sub_...`).
@@ -182,7 +182,8 @@ there is no automatic migration or fallback. Existing V1 projection, receipt
182
182
  and configure consumers do not accept V2 records. V2 adds pure preparation,
183
183
  request and attachment-receipt construction, plus
184
184
  [raw configuration projection](renewal-phase-assembly.md#raw-v2-configuration-projection).
185
- It does not add a provider writer or configured-response receipt constructor.
185
+ It also adds [configured-response receipt consistency](renewal-phase-assembly.md#raw-v2-configuration-receipts).
186
+ These constructors do not add a provider writer.
186
187
 
187
188
  V2 retains the same raw preparation semantic checks and bounded JSON policy as
188
189
  V1. It adds a limit of 500,000 UTF-8 bytes on each exact encoded hash preimage,
@@ -204,6 +205,9 @@ complete attachment receipt.
204
205
  Configuration projection also selects `renewal-baseline`, `renewal-defaults`
205
206
  and `renewal-configure` internally for its complete baseline, defaults and
206
207
  unsigned request. No caller-supplied family selector is exposed.
208
+ Configured-response receipts select `renewal-configured-baseline` for the full
209
+ response body, `renewal-configured-defaults` when that body owns default settings,
210
+ and `renewal-configure-receipt` for the complete unsigned receipt.
207
211
 
208
212
  The preparation preimage contains version, platform scope, expected selectors,
209
213
  quantity and complete provider snapshot. Its logical key is separately retained
@@ -0,0 +1,124 @@
1
+ # Compare renewal schedule material
2
+
3
+ `inspectRenewalScheduleMaterialV2` compares supplied, complete subscription and
4
+ schedule reads against a raw V2 renewal configuration. It performs no provider
5
+ calls, writes, scheduling, authorization or trusted-store verification. Its result
6
+ is an unsigned material relation, not proof of a configure POST, payment,
7
+ entitlement, consent, exclusive causality or an atomic exclusion of other writers.
8
+
9
+ ```ts
10
+ import {
11
+ inspectRenewalScheduleMaterialV2,
12
+ type InspectRenewalScheduleMaterialV2Options,
13
+ } from "@fantastic.dev/better-stripe";
14
+
15
+ const input: InspectRenewalScheduleMaterialV2Options = {
16
+ configuration: retainedRawConfiguration,
17
+ reads: {
18
+ schedule: currentOwnedSchedule,
19
+ subscription: currentOriginalSubscription,
20
+ targetPrice: currentTargetPrice,
21
+ billingCustomer: currentBillingCustomer,
22
+ coupons: completeCurrentCoupons,
23
+ },
24
+ // Optional complete raw input to constructRenewalConfigurationReceiptV2.
25
+ configureReceipt: retainedRawConfigurationResponse,
26
+ };
27
+ const relation = await inspectRenewalScheduleMaterialV2(input);
28
+ ```
29
+
30
+ `configuration` is the full raw input accepted by
31
+ [`projectRenewalConfigurationV2`](renewal-phase-assembly.md), including the original
32
+ preparation, raw attachment receipt input, fresh preconfigure reads, observed time,
33
+ retained dispatch time and caller-owned key. The observer rebuilds the preparation,
34
+ attachment and desired request internally. It does not accept a caller-validated
35
+ context, desired-request handle or an authenticated-receipt flag.
36
+
37
+ The optional `configureReceipt` is the complete raw input to
38
+ `constructRenewalConfigurationReceiptV2`. Its nested `configuration` must equal the
39
+ root configuration, including optional-field presence. The observer rebuilds the
40
+ receipt and classifies its complete historical response before comparing current
41
+ reads. This binds supplied data consistently; it does not authenticate who returned
42
+ or stored that response. Supplying it never changes
43
+ `acknowledgementEstablished: false` or `authenticationEstablished: false`.
44
+
45
+ ## Results and complete material
46
+
47
+ Every result has `providerQualificationRequired: true`. The `predicate` is one of:
48
+
49
+ | Predicate | Meaning |
50
+ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
51
+ | `attached_unconfigured_match` | The complete attached single-phase material still matches. |
52
+ | `pending_material_match` | Current paid material and the exact future phase match, with a supported independently bound future end. |
53
+ | `current_target_material_match` | The target phase is current and the uniquely identified target item, native period and complete retained material match. |
54
+ | `terminal_facts_only` | A terminal status was supplied; effectiveness remains `unknown`. |
55
+ | `unknown` | Required evidence or a supported mapping is missing. |
56
+ | `conflict` | Supplied material contradicts the retained operation. |
57
+
58
+ A current target match can identify a successor subscription item. It does not
59
+ require the original `si_` ID to survive the schedule transition. It requires the
60
+ linked original subscription and buyer, exact phase and native item period,
61
+ price/product, quantity, currency, full Price/Plan mapping, settings, discounts,
62
+ taxes, customer material and supported expanded-reference counterparts. Matching
63
+ only a price or future phase is insufficient. Unknown retained fields and counters
64
+ remain comparison material; they are not silently dropped or incremented.
65
+
66
+ ### Invoice-pointer limitation
67
+
68
+ This API accepts five current-read categories. It has no invoice inventory, full
69
+ invoice/line history or owned successor-invoice proof. Both the original and current
70
+ subscription must contain their own `latest_invoice` field. An original `I0` and
71
+ current `I1` produce `conflict` with `effective_full_material_drift` when the other
72
+ active-material checks pass. This can describe a normal renewal that this limited
73
+ comparison cannot prove. Omitting the field does not make it supported; missing
74
+ fields produce `unknown` with `missing_latest_invoice`.
75
+
76
+ A positive active-material example therefore requires coherent invoice pointers
77
+ under the existing complete comparison. It does not prove that real renewals keep
78
+ that pointer unchanged. An optional raw configure receipt does not authorize an
79
+ `I0` to `I1` change. Admitting such changes requires separately defined owned
80
+ invoice-history evidence. This helper is not the complete renewal-observation or
81
+ renewal-replacement workflow.
82
+
83
+ ### Pending without a configure response
84
+
85
+ A complete current-target match can be established from supplied reads without a
86
+ configure response. A pending match without that response has a narrower supported
87
+ class: classic billing, changed cadence, an ordinary anchor, a one-week licensed
88
+ target with explicit `phase_start`, and no trial, threshold, cancellation, pause or
89
+ other supported period-resetting condition. Every complete current-paid and future
90
+ settings guard must still pass.
91
+
92
+ For this class the observer infers the future end as the retained boundary plus
93
+ 604800 UTC seconds, with safe-integer checks, then compares the actual future end.
94
+ This is a bounded consistency inference from Stripe's
95
+ [phase duration](https://docs.stripe.com/billing/subscriptions/subscription-schedules)
96
+ and [UTC billing-anchor](https://docs.stripe.com/billing/subscriptions/billing-cycle)
97
+ contracts. It is not a provider-qualified observation of the exact calculation.
98
+ No host calendar, invoice calculation or caller-supplied expected end is used.
99
+
100
+ Monthly/yearly, multi-week, flexible, automatic-anchor, calendar-edge and other
101
+ unproved future durations remain `unknown` with `future_duration_not_bound` unless
102
+ the complete historical raw configuration response binds the end under the
103
+ supported comparison rules. Reads never become a configure POST acknowledgement.
104
+ Released, canceled and completed facts do not establish terminal effectiveness.
105
+ A supplied schedule status must be a string. Arrays, objects, null and numeric
106
+ statuses return `unknown` with `invalid_schedule_status`; an unrecognized string
107
+ keeps `unknown` with `unsupported_schedule_status`. Values are never coerced into
108
+ a known terminal status.
109
+
110
+ ## Capture and limits
111
+
112
+ The entire input is captured synchronously before asynchronous binding work.
113
+ Later caller mutations do not change that invocation. Roots must be plain or
114
+ null-prototype objects with closed own data fields. Getters, symbols, hidden
115
+ properties, sparse arrays, non-finite values and non-JSON objects are rejected;
116
+ SDK `lastResponse` metadata is not stripped from untrusted bare response inputs.
117
+
118
+ The whole submitted input, including repeated raw configuration material, is
119
+ limited to 500000 string/key characters, serialized characters and UTF-8 bytes,
120
+ 10000 nodes and depth 40. These are this API's actual input bounds, not a claim
121
+ about whole-process memory or other SDK methods. Invalid raw capture rejects with
122
+ a fixed error; safe but insufficient material returns `unknown` or `conflict`
123
+ with a fixed reason. No raw provider error is logged or returned. The host remains
124
+ responsible for retaining its immutable request and response data when reads fail.
@@ -84,6 +84,74 @@ effectiveness. Protect original records and enforce host authorization and all
84
84
  provider qualification gates before dispatch. Existing V1 APIs and record
85
85
  formats are unchanged.
86
86
 
87
+ ## Raw V2 configuration receipts
88
+
89
+ `constructRenewalConfigurationReceiptV2` records unsigned operation consistency
90
+ from raw configuration inputs and a retained response:
91
+
92
+ ```ts
93
+ import { constructRenewalConfigurationReceiptV2 } from "@fantastic.dev/better-stripe";
94
+
95
+ const receipt = await constructRenewalConfigurationReceiptV2({
96
+ configuration: originalRawConfigurationInputs,
97
+ actualDispatch: {
98
+ scope: "platform",
99
+ apiVersion,
100
+ method: "POST",
101
+ path: projectedRequest.path,
102
+ payload: projectedRequest.payload,
103
+ key: projectedRequest.key,
104
+ firstDispatchedAt: projectedRequest.firstDispatchedAt,
105
+ },
106
+ providerSnapshot: retainedConfiguredScheduleBody,
107
+ transport: {
108
+ status: retainedStatus,
109
+ ...(retainedRequestId === undefined
110
+ ? {}
111
+ : { requestId: retainedRequestId }),
112
+ },
113
+ });
114
+ ```
115
+
116
+ `configuration` is the complete raw input to `projectRenewalConfigurationV2`,
117
+ including its repeated original preparation and raw attachment receipt inputs.
118
+ Do not supply a projected request, stored receipt or verification handle in its
119
+ place. The constructor captures the entire input before its first await and
120
+ rebuilds C6 internally. Any returned C6 Failure rejects C9 with a fixed error;
121
+ C6's own Failure union remains unchanged. All seven actual dispatch fields,
122
+ including the complete payload, key and first-dispatch time, must equal C6.
123
+
124
+ Transport is closed `{ status, requestId? }`. Status must be an integer from
125
+ 200 through 299. A present request ID must contain 1–255 characters; omit it
126
+ when absent. Null, empty or explicitly undefined IDs reject. Supply the complete
127
+ plain JSON Schedule body rather than an SDK wrapper: any own `lastResponse`
128
+ property, including hidden metadata, rejects. The public bounded JSON limits and
129
+ own-data constructor checks remain; captured required fields are checked again
130
+ before hashing.
131
+
132
+ Available response identity relations must agree with C6's Schedule,
133
+ Subscription, Customer, account and mode. The complete response body, including
134
+ unknown safe JSON keys, remains in C7 (`renewal-configured-baseline`). C8
135
+ (`renewal-configured-defaults`) is present only when the response owns
136
+ `default_settings`: absent stays absent, own null is hashed as null, and a present
137
+ object is hashed in full. C9 (`renewal-configure-receipt`) binds the complete
138
+ unsigned receipt, including the full C6 request, response, exact transport and
139
+ C7/optional C8. Each exact UTF-8 preimage retains the 500,000-byte limit; the
140
+ whole input and result retain the existing JSON traversal and size limits.
141
+
142
+ The result uses version `2`, stage `configure_acknowledged` and verification
143
+ `owned_response_only`. These are unsigned data-format literals. They do not
144
+ authenticate acknowledgement or ownership. A caller can manufacture coherent
145
+ data that passes. This operation-only constructor does not require response
146
+ phases or defaults to match the requested configuration and cannot certify that
147
+ they were applied. Full phase/material comparison, response acquisition and
148
+ same-call provenance, authorization, custody, provider qualification and renewal
149
+ effectiveness remain separate requirements.
150
+
151
+ No provider call, retry, key rotation, storage write, V1 conversion or native
152
+ qualification occurs. Keep the original operation records protected, and do not
153
+ treat the receipt or a matching digest as permission to write or grant service.
154
+
87
155
  A candidate always has `providerQualification: "required"`. This describes a
88
156
  remaining requirement, not authorization to dispatch. Host-supplied flags cannot
89
157
  prove provider behavior, ownership, original configuration or historical intent.
@@ -48,6 +48,9 @@ The internal [preservation mappings](renewal-preservation-mappings.md) document
48
48
  field projection boundaries separately from complete schedule eligibility.
49
49
  The internal [phase assembly contract](renewal-phase-assembly.md) describes
50
50
  preflight, acknowledged baselines and non-dispatchable configuration candidates.
51
+ The public [material observer](renewal-material-observation.md) compares supplied
52
+ V2 material without provider calls. Its invoice-pointer and no-response duration
53
+ limits leave the complete renewal workflow outside that pure helper.
51
54
 
52
55
  The subscription's actual `currency` must match both prices' default `currency`.
53
56
  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.86.0",
3
+ "version": "0.88.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",
@@ -0,0 +1,67 @@
1
+ import {
2
+ object,
3
+ array,
4
+ need,
5
+ clone,
6
+ get,
7
+ equal,
8
+ timestamp,
9
+ planTemplateForPrice,
10
+ type ObserverCandidateResult,
11
+ } from "./common.js";
12
+ import type { pending } from "./pending-and-stage.js";
13
+ export function active(
14
+ state: Extract<ReturnType<typeof pending>, { kind: "continue" }>["state"],
15
+ ): ObserverCandidateResult {
16
+ const {
17
+ rawReads,
18
+ base,
19
+ originalItem,
20
+ sub,
21
+ target,
22
+ context,
23
+ actualItem,
24
+ current,
25
+ actualItemDiscounts,
26
+ normalizeSub,
27
+ sourceWithAssociation,
28
+ targetTemplate,
29
+ } = state;
30
+ // BEGIN original 927-961
31
+ const effectiveTemplate = clone(sourceWithAssociation),
32
+ expectedItem = clone(originalItem);
33
+ expectedItem.id = actualItem.id;
34
+ expectedItem.price = clone(target);
35
+ const targetPlanTemplate = planTemplateForPrice(target, context);
36
+ need(targetPlanTemplate, "unproven_target_plan_price_mapping", "unknown");
37
+ // Expected comparison view from explicit field mapping; raw actual Plan stays in rawReads.
38
+ expectedItem.plan = targetPlanTemplate;
39
+ expectedItem.current_period_start = current.start_date;
40
+ expectedItem.current_period_end = current.end_date;
41
+ get(effectiveTemplate, "items").data = [expectedItem];
42
+ if (targetTemplate.billing_cycle_anchor === "phase_start")
43
+ effectiveTemplate.billing_cycle_anchor = current.start_date;
44
+ const normalizedActual = normalizeSub(sub, "target", target),
45
+ normalizedExpected = normalizeSub(effectiveTemplate, "original", target);
46
+ get(normalizedExpected, "items").data = [
47
+ {
48
+ ...object(array(get(normalizedExpected, "items").data)[0]),
49
+ discounts: actualItemDiscounts,
50
+ },
51
+ ];
52
+ need(
53
+ equal(normalizedActual, normalizedExpected),
54
+ "effective_full_material_drift",
55
+ );
56
+ return {
57
+ ...base,
58
+ predicate: "active_effective_match",
59
+ observedItemId: String(actualItem.id),
60
+ nativePeriod: {
61
+ start: timestamp.parse(current.start_date),
62
+ end: timestamp.parse(current.end_date),
63
+ },
64
+ rawReads,
65
+ };
66
+ // END original 927-961
67
+ }
@@ -0,0 +1,83 @@
1
+ import { renewalSnapshot } from "../renewalReplacementSnapshot.js";
2
+ import {
3
+ equal,
4
+ referenceId,
5
+ productId,
6
+ timestamp,
7
+ } from "../renewalAggregate/shared.js";
8
+ import { planMatchesPrice, planTemplateForPrice } from "./planProjection.js";
9
+ export type O = Record<string, unknown>;
10
+ export class Stop extends Error {
11
+ constructor(
12
+ readonly reason: string,
13
+ readonly kind: "unknown" | "conflict" = "conflict",
14
+ ) {
15
+ super(reason);
16
+ }
17
+ }
18
+ export const object = (v: unknown): O => {
19
+ if (!v || typeof v !== "object" || Array.isArray(v))
20
+ throw new Stop("incomplete_object", "unknown");
21
+ return v as O;
22
+ };
23
+ export const array = (v: unknown): unknown[] => {
24
+ if (!Array.isArray(v)) throw new Stop("incomplete_array", "unknown");
25
+ return v;
26
+ };
27
+ export function need(
28
+ value: unknown,
29
+ reason: string,
30
+ kind: "unknown" | "conflict" = "conflict",
31
+ ): asserts value {
32
+ if (!value) throw new Stop(reason, kind);
33
+ }
34
+ export const clone = <T>(v: T): T => renewalSnapshot(v);
35
+ export const get = (v: O, key: string) => object(v[key]);
36
+ export function compareFullBaseline(left: unknown, right: unknown) {
37
+ let same = false;
38
+ try {
39
+ same = equal(left, right);
40
+ } catch {}
41
+ return { equal: same, acknowledgementEstablished: false as const };
42
+ }
43
+ export type ObserverCandidateResult = {
44
+ candidateOnly: true;
45
+ providerQualification: "required";
46
+ configureAcknowledged: false;
47
+ configureDispatchOutcome: "unknown";
48
+ providerCallsRequested: false;
49
+ predicate:
50
+ | "terminal_facts_only"
51
+ | "attached_unconfigured_match"
52
+ | "active_effective_match"
53
+ | "configured_baseline_material_match"
54
+ | "confirmed_pending"
55
+ | "unknown"
56
+ | "conflict";
57
+ reason?: string;
58
+ observedItemId?: string;
59
+ nativePeriod?: { start: number; end: number };
60
+ providerStatus?: unknown;
61
+ effectiveness?: "unknown";
62
+ rawReads?: unknown;
63
+ comparableSchedule?: unknown;
64
+ proofTargetEnd?: number;
65
+ proofStage?: "original" | "target";
66
+ };
67
+ /** Private SOURCE candidate only; no transport, public integration or ack adapter. */
68
+
69
+ export {
70
+ renewalSnapshot,
71
+ equal,
72
+ referenceId,
73
+ productId,
74
+ timestamp,
75
+ planMatchesPrice,
76
+ planTemplateForPrice,
77
+ };
78
+ export type Purpose = "baseline" | "live";
79
+ export type Evidence = {
80
+ targetEnd: number;
81
+ comparable: unknown;
82
+ stage: "original" | "target";
83
+ };
@@ -0,0 +1,55 @@
1
+ import { need, get, equal, type ObserverCandidateResult } from "./common.js";
2
+ import type { templates } from "./schedule-templates.js";
3
+ export function baseline(
4
+ state: Extract<ReturnType<typeof templates>, { kind: "continue" }>["state"],
5
+ ) {
6
+ const {
7
+ rawReads,
8
+ base,
9
+ purpose,
10
+ originalItem,
11
+ sub,
12
+ current,
13
+ currentOriginal,
14
+ activeTarget,
15
+ normalizeSub,
16
+ sourceWithAssociation,
17
+ targetPhase,
18
+ comparableSchedule,
19
+ } = state;
20
+ // BEGIN original 851-879
21
+ if (purpose === "baseline") {
22
+ need(
23
+ currentOriginal ||
24
+ (activeTarget &&
25
+ current.start_date === targetPhase.start_date &&
26
+ current.end_date === targetPhase.end_date),
27
+ "configured_ack_phase_relation_unproven",
28
+ "unknown",
29
+ );
30
+ need(
31
+ equal(
32
+ normalizeSub(sub, "original", get(originalItem, "price")),
33
+ normalizeSub(
34
+ sourceWithAssociation,
35
+ "original",
36
+ get(originalItem, "price"),
37
+ ),
38
+ ),
39
+ "historical_original_material_drift",
40
+ );
41
+ return {
42
+ kind: "result" as const,
43
+ result: {
44
+ ...base,
45
+ predicate: "configured_baseline_material_match",
46
+ rawReads,
47
+ comparableSchedule,
48
+ proofTargetEnd: Number(targetPhase.end_date),
49
+ proofStage: currentOriginal ? "original" : "target",
50
+ } as ObserverCandidateResult,
51
+ };
52
+ }
53
+ // END original 851-879
54
+ return { kind: "continue" as const, state: { ...state } };
55
+ }