@fantastic.dev/better-stripe 0.87.0 → 0.88.1

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 (126) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +1 -1
  3. package/dist/client/billing/renewalAggregate/readMaterial.d.ts.map +1 -1
  4. package/dist/client/billing/renewalAggregate/readMaterial.js +4 -3
  5. package/dist/client/billing/renewalAggregate/readMaterial.js.map +1 -1
  6. package/dist/client/billing/renewalObservation/active-scheduled.d.ts +6 -0
  7. package/dist/client/billing/renewalObservation/active-scheduled.d.ts.map +1 -0
  8. package/dist/client/billing/renewalObservation/active-scheduled.js +37 -0
  9. package/dist/client/billing/renewalObservation/active-scheduled.js.map +1 -0
  10. package/dist/client/billing/renewalObservation/common.d.ts +47 -0
  11. package/dist/client/billing/renewalObservation/common.d.ts.map +1 -0
  12. package/dist/client/billing/renewalObservation/common.js +39 -0
  13. package/dist/client/billing/renewalObservation/common.js.map +1 -0
  14. package/dist/client/billing/renewalObservation/configured-baseline.d.ts +76 -0
  15. package/dist/client/billing/renewalObservation/configured-baseline.d.ts.map +1 -0
  16. package/dist/client/billing/renewalObservation/configured-baseline.js +26 -0
  17. package/dist/client/billing/renewalObservation/configured-baseline.js.map +1 -0
  18. package/dist/client/billing/renewalObservation/coupon-discount-joins.d.ts +53 -0
  19. package/dist/client/billing/renewalObservation/coupon-discount-joins.d.ts.map +1 -0
  20. package/dist/client/billing/renewalObservation/coupon-discount-joins.js +103 -0
  21. package/dist/client/billing/renewalObservation/coupon-discount-joins.js.map +1 -0
  22. package/dist/client/billing/renewalObservation/invoice-tax-identity.d.ts +52 -0
  23. package/dist/client/billing/renewalObservation/invoice-tax-identity.d.ts.map +1 -0
  24. package/dist/client/billing/renewalObservation/invoice-tax-identity.js +49 -0
  25. package/dist/client/billing/renewalObservation/invoice-tax-identity.js.map +1 -0
  26. package/dist/client/billing/renewalObservation/pending-and-stage.d.ts +76 -0
  27. package/dist/client/billing/renewalObservation/pending-and-stage.d.ts.map +1 -0
  28. package/dist/client/billing/renewalObservation/pending-and-stage.js +36 -0
  29. package/dist/client/billing/renewalObservation/pending-and-stage.js.map +1 -0
  30. package/dist/client/billing/renewalObservation/phase-price-normalization.d.ts +57 -0
  31. package/dist/client/billing/renewalObservation/phase-price-normalization.d.ts.map +1 -0
  32. package/dist/client/billing/renewalObservation/phase-price-normalization.js +70 -0
  33. package/dist/client/billing/renewalObservation/phase-price-normalization.js.map +1 -0
  34. package/dist/client/billing/renewalObservation/planProjection.d.ts +8 -0
  35. package/dist/client/billing/renewalObservation/planProjection.d.ts.map +1 -0
  36. package/dist/client/billing/renewalObservation/planProjection.js +150 -0
  37. package/dist/client/billing/renewalObservation/planProjection.js.map +1 -0
  38. package/dist/client/billing/renewalObservation/reference-catalog.d.ts +37 -0
  39. package/dist/client/billing/renewalObservation/reference-catalog.d.ts.map +1 -0
  40. package/dist/client/billing/renewalObservation/reference-catalog.js +109 -0
  41. package/dist/client/billing/renewalObservation/reference-catalog.js.map +1 -0
  42. package/dist/client/billing/renewalObservation/schedule-templates.d.ts +74 -0
  43. package/dist/client/billing/renewalObservation/schedule-templates.d.ts.map +1 -0
  44. package/dist/client/billing/renewalObservation/schedule-templates.js +72 -0
  45. package/dist/client/billing/renewalObservation/schedule-templates.js.map +1 -0
  46. package/dist/client/billing/renewalObservation/scheduled-context.d.ts +44 -0
  47. package/dist/client/billing/renewalObservation/scheduled-context.d.ts.map +1 -0
  48. package/dist/client/billing/renewalObservation/scheduled-context.js +64 -0
  49. package/dist/client/billing/renewalObservation/scheduled-context.js.map +1 -0
  50. package/dist/client/billing/renewalObservation/scheduled-identity.d.ts +53 -0
  51. package/dist/client/billing/renewalObservation/scheduled-identity.d.ts.map +1 -0
  52. package/dist/client/billing/renewalObservation/scheduled-identity.js +95 -0
  53. package/dist/client/billing/renewalObservation/scheduled-identity.js.map +1 -0
  54. package/dist/client/billing/renewalObservation/scheduled-normalization.d.ts +59 -0
  55. package/dist/client/billing/renewalObservation/scheduled-normalization.d.ts.map +1 -0
  56. package/dist/client/billing/renewalObservation/scheduled-normalization.js +29 -0
  57. package/dist/client/billing/renewalObservation/scheduled-normalization.js.map +1 -0
  58. package/dist/client/billing/renewalObservation/settings-normalization.d.ts +54 -0
  59. package/dist/client/billing/renewalObservation/settings-normalization.d.ts.map +1 -0
  60. package/dist/client/billing/renewalObservation/settings-normalization.js +53 -0
  61. package/dist/client/billing/renewalObservation/settings-normalization.js.map +1 -0
  62. package/dist/client/billing/renewalObservation/stage-runner.d.ts +4 -0
  63. package/dist/client/billing/renewalObservation/stage-runner.d.ts.map +1 -0
  64. package/dist/client/billing/renewalObservation/stage-runner.js +34 -0
  65. package/dist/client/billing/renewalObservation/stage-runner.js.map +1 -0
  66. package/dist/client/billing/renewalObservation/weeklyPending.d.ts +13 -0
  67. package/dist/client/billing/renewalObservation/weeklyPending.d.ts.map +1 -0
  68. package/dist/client/billing/renewalObservation/weeklyPending.js +55 -0
  69. package/dist/client/billing/renewalObservation/weeklyPending.js.map +1 -0
  70. package/dist/client/billing/renewalPriceReplacement.d.ts.map +1 -1
  71. package/dist/client/billing/renewalPriceReplacement.js +7 -3
  72. package/dist/client/billing/renewalPriceReplacement.js.map +1 -1
  73. package/dist/client/billing/renewalV2/index.d.ts +383 -0
  74. package/dist/client/billing/renewalV2/index.d.ts.map +1 -1
  75. package/dist/client/billing/renewalV2/index.js +8 -3
  76. package/dist/client/billing/renewalV2/index.js.map +1 -1
  77. package/dist/client/billing/renewalV2/observation.d.ts +19 -0
  78. package/dist/client/billing/renewalV2/observation.d.ts.map +1 -0
  79. package/dist/client/billing/renewalV2/observation.js +95 -0
  80. package/dist/client/billing/renewalV2/observation.js.map +1 -0
  81. package/dist/client/billing/renewalV2/observationInput.d.ts +77 -0
  82. package/dist/client/billing/renewalV2/observationInput.d.ts.map +1 -0
  83. package/dist/client/billing/renewalV2/observationInput.js +140 -0
  84. package/dist/client/billing/renewalV2/observationInput.js.map +1 -0
  85. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +16 -16
  86. package/dist/client/connect/payoutSyncTestHelpers.d.ts +16 -16
  87. package/dist/client/renewal.d.ts +2 -0
  88. package/dist/client/renewal.d.ts.map +1 -1
  89. package/dist/client/renewal.js +1 -0
  90. package/dist/client/renewal.js.map +1 -1
  91. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  92. package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
  93. package/dist/component/balanceFunding/workflowValidators.d.ts +16 -16
  94. package/dist/component/earnings/triggers.d.ts +16 -16
  95. package/dist/component/usage/allowance.fixtures.d.ts +16 -16
  96. package/docs/client-api.md +26 -0
  97. package/docs/renewal-context-reads.md +10 -0
  98. package/docs/renewal-material-observation.md +124 -0
  99. package/docs/renewal-phase-assembly.md +7 -0
  100. package/docs/renewal-price-replacements.md +3 -0
  101. package/package.json +1 -1
  102. package/src/client/billing/renewalAggregate/readMaterial.ts +5 -3
  103. package/src/client/billing/renewalObservation/active-scheduled.ts +67 -0
  104. package/src/client/billing/renewalObservation/common.ts +83 -0
  105. package/src/client/billing/renewalObservation/configured-baseline.ts +55 -0
  106. package/src/client/billing/renewalObservation/coupon-discount-joins.ts +163 -0
  107. package/src/client/billing/renewalObservation/invoice-tax-identity.ts +65 -0
  108. package/src/client/billing/renewalObservation/pending-and-stage.ts +89 -0
  109. package/src/client/billing/renewalObservation/phase-price-normalization.ts +106 -0
  110. package/src/client/billing/renewalObservation/planProjection.ts +177 -0
  111. package/src/client/billing/renewalObservation/reference-catalog.ts +150 -0
  112. package/src/client/billing/renewalObservation/schedule-templates.ts +118 -0
  113. package/src/client/billing/renewalObservation/scheduled-context.ts +98 -0
  114. package/src/client/billing/renewalObservation/scheduled-identity.ts +175 -0
  115. package/src/client/billing/renewalObservation/scheduled-normalization.ts +49 -0
  116. package/src/client/billing/renewalObservation/settings-normalization.ts +60 -0
  117. package/src/client/billing/renewalObservation/stage-runner.ts +30 -0
  118. package/src/client/billing/renewalObservation/weeklyPending.ts +81 -0
  119. package/src/client/billing/renewalPriceReplacement.ts +7 -3
  120. package/src/client/billing/renewalV2/index.ts +14 -6
  121. package/src/client/billing/renewalV2/observation.boundary-review.test.ts +49 -0
  122. package/src/client/billing/renewalV2/observation.test.ts +334 -0
  123. package/src/client/billing/renewalV2/observation.ts +149 -0
  124. package/src/client/billing/renewalV2/observationInput.ts +167 -0
  125. package/src/client/billing/renewalV2/rawRetention.test.ts +293 -0
  126. package/src/client/renewal.ts +7 -0
@@ -5,14 +5,6 @@ export declare function savePreparationHandler(ctx: MutationCtx, args: Infer<typ
5
5
  preparationId: import("convex/values").GenericId<"balanceFundingPreparations">;
6
6
  }>;
7
7
  export declare function beginHandler(ctx: MutationCtx, args: Infer<typeof beginArgs>): Promise<{
8
- reason: "identity_changed" | "revision_changed" | "scope_busy";
9
- retryable: false;
10
- status: "conflict";
11
- } | {
12
- reason: "policy_invalid";
13
- retryable: false;
14
- status: "rejected";
15
- } | {
16
8
  operation: {
17
9
  accountId: string;
18
10
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -23,6 +15,14 @@ export declare function beginHandler(ctx: MutationCtx, args: Infer<typeof beginA
23
15
  } | {
24
16
  enabled: boolean;
25
17
  status: "unchanged";
18
+ } | {
19
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
20
+ retryable: false;
21
+ status: "conflict";
22
+ } | {
23
+ reason: "policy_invalid";
24
+ retryable: false;
25
+ status: "rejected";
26
26
  } | {
27
27
  reason: "provider_pending";
28
28
  retryable: true;
@@ -60,22 +60,6 @@ export declare const phaseRef: import("convex/values").VObject<{
60
60
  }, "required", "accountId" | "definitionVersion" | "operationId" | "phase" | "providerApiVersion" | "providerKey" | "scopeKey" | "stripeSubscriptionId" | "version">;
61
61
  export type FundingPhaseRef = Infer<typeof phaseRef>;
62
62
  export declare const workflowStartResult: import("convex/values").VUnion<{
63
- reason: "history_incomplete" | "provider_outcome_unknown";
64
- retryable: false;
65
- status: "unknown";
66
- } | {
67
- reason: "identity_changed" | "revision_changed" | "scope_busy";
68
- retryable: false;
69
- status: "conflict";
70
- } | {
71
- reason: "invalid_scope" | "policy_invalid" | "unsupported_source";
72
- retryable: false;
73
- status: "rejected";
74
- } | {
75
- reason: "provider_pending";
76
- retryable: true;
77
- status: "not_ready";
78
- } | {
79
63
  operation: {
80
64
  accountId: string;
81
65
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -92,6 +76,22 @@ export declare const workflowStartResult: import("convex/values").VUnion<{
92
76
  version: number;
93
77
  };
94
78
  status: "canceled";
79
+ } | {
80
+ reason: "history_incomplete" | "provider_outcome_unknown";
81
+ retryable: false;
82
+ status: "unknown";
83
+ } | {
84
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
85
+ retryable: false;
86
+ status: "conflict";
87
+ } | {
88
+ reason: "invalid_scope" | "policy_invalid" | "unsupported_source";
89
+ retryable: false;
90
+ status: "rejected";
91
+ } | {
92
+ reason: "provider_pending";
93
+ retryable: true;
94
+ status: "not_ready";
95
95
  }, [import("convex/values").VObject<{
96
96
  operation: {
97
97
  accountId: string;
@@ -372,14 +372,6 @@ export declare const mutation: import("convex-helpers/server/customFunctions").C
372
372
  preparationId: import("convex/values").GenericId<"balanceFundingPreparations">;
373
373
  requestKey: string;
374
374
  result?: {
375
- reason: "identity_changed" | "revision_changed" | "scope_busy";
376
- retryable: false;
377
- status: "conflict";
378
- } | {
379
- reason: "policy_invalid";
380
- retryable: false;
381
- status: "rejected";
382
- } | {
383
375
  operation: {
384
376
  accountId: string;
385
377
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -390,6 +382,14 @@ export declare const mutation: import("convex-helpers/server/customFunctions").C
390
382
  } | {
391
383
  enabled: boolean;
392
384
  status: "unchanged";
385
+ } | {
386
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
387
+ retryable: false;
388
+ status: "conflict";
389
+ } | {
390
+ reason: "policy_invalid";
391
+ retryable: false;
392
+ status: "rejected";
393
393
  } | {
394
394
  reason: "provider_pending";
395
395
  retryable: true;
@@ -3270,14 +3270,6 @@ export declare const mutation: import("convex-helpers/server/customFunctions").C
3270
3270
  preparationId: import("convex/values").GenericId<"balanceFundingPreparations">;
3271
3271
  requestKey: string;
3272
3272
  result?: {
3273
- reason: "identity_changed" | "revision_changed" | "scope_busy";
3274
- retryable: false;
3275
- status: "conflict";
3276
- } | {
3277
- reason: "policy_invalid";
3278
- retryable: false;
3279
- status: "rejected";
3280
- } | {
3281
3273
  operation: {
3282
3274
  accountId: string;
3283
3275
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -3288,6 +3280,14 @@ export declare const mutation: import("convex-helpers/server/customFunctions").C
3288
3280
  } | {
3289
3281
  enabled: boolean;
3290
3282
  status: "unchanged";
3283
+ } | {
3284
+ reason: "identity_changed" | "revision_changed" | "scope_busy";
3285
+ retryable: false;
3286
+ status: "conflict";
3287
+ } | {
3288
+ reason: "policy_invalid";
3289
+ retryable: false;
3290
+ status: "rejected";
3291
3291
  } | {
3292
3292
  reason: "provider_pending";
3293
3293
  retryable: true;
@@ -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_...`).
@@ -31,6 +31,16 @@ and complete records under immutable authorization. An explicitly chosen attach
31
31
  key may equal the logical key; no key is silently reused, derived or generated.
32
32
  A future configure key must differ from the attachment key.
33
33
 
34
+ Preparation validates the original Subscription, target Price and optional
35
+ billing Customer, then retains their complete captured JSON bodies. Eligible
36
+ unknown fields, including own JSON keys such as `__proto__`, remain in the
37
+ snapshot and binding; validation does not replace the retained body with a
38
+ selected-field view. Unsupported fields in strict schemas still reject.
39
+
40
+ Older snapshots that already omitted a field cannot recover it or establish
41
+ retroactive full-record provenance. Reconstructing a changed full record does
42
+ not migrate its old binding or authorize a retry.
43
+
34
44
  ## Fixed acquisition profile
35
45
 
36
46
  The initial profile supports platform requests using the configured
@@ -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.
@@ -60,6 +60,13 @@ full-baseline and default-preservation checks apply. Actual subscription
60
60
  association is required; the constructor does not replace it with null to pass
61
61
  the original preparation checks.
62
62
 
63
+ Fresh Subscription, target Price and billing Customer comparisons use their
64
+ complete captured JSON bodies, including eligible unknown fields. Only the
65
+ Subscription's root Schedule association is handled separately by the existing
66
+ ownership checks. Parsed semantic views do not permit unknown-field drift or
67
+ replace the retained raw baseline. Unsupported strict-schema fields still
68
+ reject, and snapshot equality remains an unsigned data comparison.
69
+
63
70
  Success is `projected_configure_request`, with version `2`, the complete
64
71
  normalized two-phase payload and `providerQualification: "required"`. C4
65
72
  (`renewal-baseline`) binds the entire original Schedule body. C5
@@ -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.87.0",
3
+ "version": "0.88.1",
4
4
  "description": "Convex component for Stripe Accounts v2, subscriptions, metered billing and Connect marketplaces, with React workflows.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -68,14 +68,16 @@ export function validateReadMaterial(
68
68
  }
69
69
  const { schedule: originalSchedule, ...original } =
70
70
  prepared.providerSnapshot.subscription;
71
- const { schedule: freshSchedule, ...fresh } = source;
71
+ // Compare complete captured bodies, not parser outputs that may omit own keys.
72
+ const { schedule: freshSchedule, ...fresh } =
73
+ args.freshSubscription as typeof source;
72
74
  if (scheduleId ? originalSchedule !== null : freshSchedule !== null)
73
75
  conflict("schedule_association_mismatch");
74
76
  if (!equal(original, fresh)) conflict("original_source_drift");
75
77
  const target = renewalPrice.safeParse(args.targetPrice);
76
78
  if (!target.success || !target.data.active)
77
79
  unsupported("unsupported_target_price");
78
- if (!equal(target.data, prepared.providerSnapshot.targetPrice))
80
+ if (!equal(args.targetPrice, prepared.providerSnapshot.targetPrice))
79
81
  conflict("target_price_drift");
80
82
  if (
81
83
  prepared.providerSnapshot.billingCustomer === undefined ||
@@ -84,7 +86,7 @@ export function validateReadMaterial(
84
86
  unsupported("missing_retained_billing_customer");
85
87
  const customer = renewalBillingCustomer.safeParse(args.billingCustomer);
86
88
  if (!customer.success) unsupported("unsupported_billing_customer");
87
- if (!equal(customer.data, prepared.providerSnapshot.billingCustomer))
89
+ if (!equal(args.billingCustomer, prepared.providerSnapshot.billingCustomer))
88
90
  conflict("billing_customer_drift");
89
91
  const referenceContext = {
90
92
  customerAccountId: prepared.expected.customerAccountId,
@@ -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
+ }