@fantastic.dev/better-stripe 0.83.1 → 0.85.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 (35) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +1 -1
  3. package/dist/client/billing/renewalV2/binding.d.ts +3 -0
  4. package/dist/client/billing/renewalV2/binding.d.ts.map +1 -0
  5. package/dist/client/billing/renewalV2/binding.js +18 -0
  6. package/dist/client/billing/renewalV2/binding.js.map +1 -0
  7. package/dist/client/billing/renewalV2/index.d.ts +63 -0
  8. package/dist/client/billing/renewalV2/index.d.ts.map +1 -0
  9. package/dist/client/billing/renewalV2/index.js +124 -0
  10. package/dist/client/billing/renewalV2/index.js.map +1 -0
  11. package/dist/client/billing/renewalV2/receipt.d.ts +36 -0
  12. package/dist/client/billing/renewalV2/receipt.d.ts.map +1 -0
  13. package/dist/client/billing/renewalV2/receipt.js +131 -0
  14. package/dist/client/billing/renewalV2/receipt.js.map +1 -0
  15. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +32 -32
  16. package/dist/client/connect/payoutSyncTestHelpers.d.ts +16 -16
  17. package/dist/client/renewal.d.ts +2 -0
  18. package/dist/client/renewal.d.ts.map +1 -1
  19. package/dist/client/renewal.js +1 -0
  20. package/dist/client/renewal.js.map +1 -1
  21. package/dist/client/usage/observationClient.d.ts +2 -2
  22. package/dist/client/usage/observationClient.d.ts.map +1 -1
  23. package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
  24. package/dist/component/balanceFunding/workflowValidators.d.ts +16 -16
  25. package/dist/component/earnings/triggers.d.ts +16 -16
  26. package/dist/component/usageCredits/accounting.fixtures.d.ts +16 -16
  27. package/docs/renewal-context-reads.md +134 -0
  28. package/docs/renewal-phase-assembly.md +5 -0
  29. package/package.json +1 -1
  30. package/src/client/billing/renewalV2/binding.ts +25 -0
  31. package/src/client/billing/renewalV2/index.test.ts +414 -0
  32. package/src/client/billing/renewalV2/index.ts +214 -0
  33. package/src/client/billing/renewalV2/receipt.test.ts +289 -0
  34. package/src/client/billing/renewalV2/receipt.ts +163 -0
  35. package/src/client/renewal.ts +13 -0
@@ -1 +1 @@
1
- {"version":3,"file":"renewal.js","sourceRoot":"","sources":["../../src/client/renewal.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,OAAO,EAAE,8BAA8B,EAAE,MAAM,sCAAsC,CAAC;AAMtF,OAAO,EAAE,gCAAgC,EAAE,MAAM,oCAAoC,CAAC"}
1
+ {"version":3,"file":"renewal.js","sourceRoot":"","sources":["../../src/client/renewal.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,OAAO,EAAE,8BAA8B,EAAE,MAAM,sCAAsC,CAAC;AAMtF,OAAO,EAAE,gCAAgC,EAAE,MAAM,oCAAoC,CAAC;AAMtF,OAAO,EACL,gCAAgC,EAChC,kCAAkC,EAClC,2CAA2C,GAC5C,MAAM,8BAA8B,CAAC"}
@@ -59,10 +59,10 @@ export declare class UsageObservationClient extends UsageDeliveryClient {
59
59
  retryable: boolean;
60
60
  };
61
61
  correctionHistory: {
62
- reason?: undefined;
63
62
  status: "available";
64
63
  observedAt: number;
65
64
  value: import("./correctionRead.js").UsageCorrectionHistoryPage;
65
+ reason?: undefined;
66
66
  retryable?: undefined;
67
67
  legacyHistoryMissing?: undefined;
68
68
  } | {
@@ -84,10 +84,10 @@ export declare class UsageObservationClient extends UsageDeliveryClient {
84
84
  retryable: boolean;
85
85
  };
86
86
  correctionHistory: {
87
- reason?: undefined;
88
87
  status: "available";
89
88
  observedAt: number;
90
89
  value: import("./correctionRead.js").UsageCorrectionHistoryPage;
90
+ reason?: undefined;
91
91
  retryable?: undefined;
92
92
  legacyHistoryMissing?: undefined;
93
93
  } | {
@@ -1 +1 @@
1
- {"version":3,"file":"observationClient.d.ts","sourceRoot":"","sources":["../../../src/client/usage/observationClient.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAG5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAI5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAE1E,OAAO,EAGL,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC/B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAA4B,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE7E,MAAM,MAAM,0BAA0B,GAAG,uBAAuB,GAAG;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AACF,8EAA8E;AAC9E,qBAAa,sBAAuB,SAAQ,mBAAmB;IACvD,UAAU,CACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,WAAW,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GACrE,OAAO,CAAC,iBAAiB,CAAC,CAY5B;IACK,gBAAgB,CACpB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,yBAAyB,CAAC,CA0BpC;IACK,oBAAoB,CACxB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,yBAAyB,CAAC,CA4BpC;IACK,mBAAmB,CACvB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,gBAAgB,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;;;;;;;;;;;OAkCnE;IACK,qBAAqB,CACzB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,gBAAgB,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;;;;;;;;OA+BnE;IACK,gBAAgB,CACpB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,uBAAuB,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,EACvD,OAAO,EAAE,4BAA4B,mHAgBtC;IACK,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,0BAA0B;;;;;YAqBhE,MAAM,EAAE,aAAa;YACrB,MAAM;YACN,SAAS;;;;oBAIG,WAAW;;;;;;;;oBAKX,aAAa;;;;;OAM9B;IACK,SAAS,CACb,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,0BAA0B,EACjC,OAAO,EAAE,4BAA4B;;;;;YArBjC,MAAM,EAAE,aAAa;YACrB,MAAM;YACN,SAAS;;;;oBAIG,WAAW;;;;;;;;oBAKX,aAAa;;;;;OAc9B;CACF"}
1
+ {"version":3,"file":"observationClient.d.ts","sourceRoot":"","sources":["../../../src/client/usage/observationClient.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAG5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAI5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,uBAAuB,CAAC;AAE1E,OAAO,EAGL,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC/B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAA4B,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE7E,MAAM,MAAM,0BAA0B,GAAG,uBAAuB,GAAG;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AACF,8EAA8E;AAC9E,qBAAa,sBAAuB,SAAQ,mBAAmB;IACvD,UAAU,CACd,GAAG,EAAE,MAAM,EACX,KAAK,EAAE;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,WAAW,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,GACrE,OAAO,CAAC,iBAAiB,CAAC,CAY5B;IACK,gBAAgB,CACpB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,yBAAyB,CAAC,CA0BpC;IACK,oBAAoB,CACxB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,uBAAuB,EAC9B,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,yBAAyB,CAAC,CA4BpC;IACK,mBAAmB,CACvB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,gBAAgB,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;;;;;;;;;;;OAkCnE;IACK,qBAAqB,CACzB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,gBAAgB,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;;;;;;;;OA+BnE;IACK,gBAAgB,CACpB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,uBAAuB,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,EACvD,OAAO,EAAE,4BAA4B,mHAgBtC;IACK,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,0BAA0B;;;;;YAqBhE,MAAM,EAAE,aAAa;YACrB,MAAM;YACN,SAAS;;;oBAIG,WAAW;;;;;;;;;oBAKX,aAAa;;;;;OAM9B;IACK,SAAS,CACb,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,0BAA0B,EACjC,OAAO,EAAE,4BAA4B;;;;;YArBjC,MAAM,EAAE,aAAa;YACrB,MAAM;YACN,SAAS;;;oBAIG,WAAW;;;;;;;;;oBAKX,aAAa;;;;;OAc9B;CACF"}
@@ -5,6 +5,14 @@ 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
+ } | {
8
16
  operation: {
9
17
  accountId: string;
10
18
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -15,14 +23,6 @@ export declare function beginHandler(ctx: MutationCtx, args: Infer<typeof beginA
15
23
  } | {
16
24
  enabled: boolean;
17
25
  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,6 +372,14 @@ 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
+ } | {
375
383
  operation: {
376
384
  accountId: string;
377
385
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -382,14 +390,6 @@ export declare const mutation: import("convex-helpers/server/customFunctions").C
382
390
  } | {
383
391
  enabled: boolean;
384
392
  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,6 +3270,14 @@ 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
+ } | {
3273
3281
  operation: {
3274
3282
  accountId: string;
3275
3283
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -3280,14 +3288,6 @@ export declare const mutation: import("convex-helpers/server/customFunctions").C
3280
3288
  } | {
3281
3289
  enabled: boolean;
3282
3290
  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,14 +2351,6 @@ export declare function setupCredits(): 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
- } | {
2362
2354
  operation: {
2363
2355
  accountId: string;
2364
2356
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -2369,6 +2361,14 @@ export declare function setupCredits(): Promise<{
2369
2361
  } | {
2370
2362
  enabled: boolean;
2371
2363
  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,14 +2379,6 @@ export declare function setupCredits(): 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
- } | {
2390
2382
  operation: {
2391
2383
  accountId: string;
2392
2384
  operationId: import("convex/values").GenericId<"balanceFundingOperations">;
@@ -2397,6 +2389,14 @@ export declare function setupCredits(): Promise<{
2397
2389
  } | {
2398
2390
  enabled: boolean;
2399
2391
  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;
@@ -144,3 +144,137 @@ redirects and broken connections can leave a remote outcome unknown; callers
144
144
  must retain the original request identity rather than rotate or resend
145
145
  automatically. These transport safeguards do not qualify a renewal provider
146
146
  profile or authorize attachment, configuration or entitlement changes.
147
+
148
+ ## Additive async V2 preparation
149
+
150
+ Use the explicitly named V2 functions when compact SHA-256 consistency bindings
151
+ are needed. Existing V1 functions and retained V1 records keep their current
152
+ format and synchronous behavior.
153
+
154
+ ```ts
155
+ import {
156
+ prepareRenewalPriceReplacementV2,
157
+ prepareRenewalScheduleAttachmentV2,
158
+ } from "@fantastic.dev/better-stripe";
159
+
160
+ const preparedV2 = await prepareRenewalPriceReplacementV2({
161
+ subscription: context.subscription,
162
+ targetPrice: context.targetPrice,
163
+ billingCustomer: context.billingCustomer,
164
+ expected,
165
+ key: logicalKey,
166
+ });
167
+ const attachRequestV2 = await prepareRenewalScheduleAttachmentV2({
168
+ prepared: preparedV2,
169
+ apiVersion: context.apiVersion,
170
+ attachKey,
171
+ firstDispatchedAt,
172
+ });
173
+ ```
174
+
175
+ Both functions are pure. They perform no provider request, generate no key,
176
+ persist no record and establish no provider qualification. The V2 attachment
177
+ builder accepts only a complete V2 preparation. It reconstructs that preparation
178
+ from its full provider snapshot, expected selectors and retained logical key,
179
+ and compares the entire result before constructing the request. A matching
180
+ digest alone is insufficient. V1 preparations are rejected by this builder;
181
+ there is no automatic migration or fallback. Existing V1 projection, receipt
182
+ and configure consumers do not accept V2 records. V2 adds pure preparation,
183
+ request and attachment-receipt construction, without a V2 writer or configure
184
+ consumer.
185
+
186
+ V2 retains the same raw preparation semantic checks and bounded JSON policy as
187
+ V1. It adds a limit of 500,000 UTF-8 bytes on each exact encoded hash preimage,
188
+ including its domain tuple. A record can therefore fit V1's character limit
189
+ and exceed V2's byte limit. Inputs are captured before awaiting hashing; changes
190
+ to the original caller object during the await cannot change the result. Web
191
+ Crypto SHA-256 must be available. Missing or rejected digest operations fail
192
+ without an alternate algorithm or synchronous fallback.
193
+
194
+ For a fixed family, the hash input is the UTF-8 encoding of the current bounded
195
+ `renewalSnapshot` canonical copy followed by `JSON.stringify`, applied to
196
+ `["betterstripe-renewal-binding", 2, family, completePreimage]`. Object keys use
197
+ the existing ordering, including JavaScript's numeric-index enumeration;
198
+ arrays retain their order and negative zero serializes as zero. The output is
199
+ `family:v2:sha256:` followed by the full 64 lowercase hexadecimal digest.
200
+ Families are selected internally: `renewal` for preparation and
201
+ `renewal-attach` for the attachment request and `renewal-attach-receipt` for the
202
+ complete attachment receipt.
203
+
204
+ The preparation preimage contains version, platform scope, expected selectors,
205
+ quantity and complete provider snapshot. Its logical key is separately retained
206
+ and validated, as in V1; changing only that valid key does not change the
207
+ preparation digest. Hosts must protect original key lineage through immutable
208
+ authorization and storage. The attachment preimage binds its entire unsigned
209
+ request, including stage, scope, actual API version, logical binding, POST path,
210
+ complete payload, explicit attachment key and original first-dispatch time.
211
+ Neither digest authenticates a caller, proves provenance, acknowledges a POST
212
+ or guarantees provider replay. Hosts retain the complete original records.
213
+
214
+ ### V2 attachment receipt consistency
215
+
216
+ `constructRenewalScheduleAttachmentReceiptV2` constructs unsigned receipt data
217
+ from raw preparation inputs, the complete actual dispatch and the retained
218
+ Schedule body:
219
+
220
+ ```ts
221
+ import { constructRenewalScheduleAttachmentReceiptV2 } from "@fantastic.dev/better-stripe";
222
+
223
+ const receiptV2 = await constructRenewalScheduleAttachmentReceiptV2({
224
+ attachRequest: {
225
+ preparation: {
226
+ subscription: context.subscription,
227
+ targetPrice: context.targetPrice,
228
+ billingCustomer: context.billingCustomer,
229
+ expected,
230
+ key: logicalKey,
231
+ },
232
+ apiVersion: context.apiVersion,
233
+ attachKey,
234
+ firstDispatchedAt,
235
+ },
236
+ actualDispatch: {
237
+ scope: "platform",
238
+ apiVersion: context.apiVersion,
239
+ method: "POST",
240
+ path: "/v1/subscription_schedules",
241
+ payload: { from_subscription: expected.subscriptionId },
242
+ key: attachKey,
243
+ firstDispatchedAt,
244
+ },
245
+ providerSnapshot: retainedScheduleBody,
246
+ });
247
+ ```
248
+
249
+ Supply the original raw preparation and dispatch facts from protected host
250
+ storage. The constructor rebuilds C1 and C2 itself. It accepts neither a prepared
251
+ record in place of raw preparation nor caller-supplied verification flags. All
252
+ seven dispatch fields must equal the rebuilt request, including its complete
253
+ payload, explicit key and original first-dispatch time. A retained billing
254
+ Customer is required.
255
+
256
+ The Schedule must match the expected subscription, Customer, customer account
257
+ and mode. Available expanded identity relations must agree, including their
258
+ declared Customer, subscription and Schedule references. Deleted identities
259
+ reject. The complete Schedule body, including unknown JSON fields, remains in
260
+ the receipt and its `renewal-attach-receipt` binding. The receipt also binds its
261
+ entire rebuilt attachment request and logical binding. Its version is `2` and
262
+ stage is `attached_unconfigured`.
263
+
264
+ The constructor captures all raw inputs before its first await. Closed input
265
+ objects require own data properties and reject unexpected names; the captured
266
+ copy is checked again before hashing. Raw provider records retain the existing
267
+ bounded JSON policy. Each digest preimage, including its domain tuple and all
268
+ nested records, remains limited to 500,000 UTF-8 bytes.
269
+
270
+ This pure function performs no HTTP request or storage operation. Matching data
271
+ does not authenticate a response, prove that a POST succeeded, establish
272
+ ownership, qualify a provider profile or authorize configuration. A coherent
273
+ unsigned forgery can pass. No transport status or observation time is invented.
274
+ Hosts must separately establish acknowledgement provenance and preserve the
275
+ original records. Existing V1 configure and receipt consumers still reject V2;
276
+ there is no migration, writer or V2 configure executor.
277
+
278
+ These helpers retain ordinary provider and caller metadata within their JSON
279
+ limits. They do not redact, encrypt or certify that input or output is safe to
280
+ log. Do not place secrets in metadata, and protect retained full records.
@@ -6,6 +6,11 @@ not a public package entrypoint. It complements the public
6
6
  [preparation contract](renewal-price-replacements.md) and internal
7
7
  [preservation mappings](renewal-preservation-mappings.md).
8
8
 
9
+ This aggregate consumes V1 records. The public
10
+ [V2 attachment receipt constructor](renewal-context-reads.md#v2-attachment-receipt-consistency)
11
+ produces separate unsigned consistency data; it does not migrate records or
12
+ enable this projector to accept V2 receipts.
13
+
9
14
  A candidate always has `providerQualification: "required"`. This describes a
10
15
  remaining requirement, not authorization to dispatch. Host-supplied flags cannot
11
16
  prove provider behavior, ownership, original configuration or historical intent.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.83.1",
3
+ "version": "0.85.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,25 @@
1
+ import { renewalSnapshot } from "../renewalReplacementSnapshot.js";
2
+
3
+ /** Internal fixed-family encoding. This is consistency, not authorization. */
4
+ export async function renewalBindingV2(
5
+ family: "renewal" | "renewal-attach" | "renewal-attach-receipt",
6
+ preimage: unknown,
7
+ ): Promise<string> {
8
+ // Finish all input capture and canonical bytes before the first await.
9
+ const text = JSON.stringify(
10
+ renewalSnapshot(["betterstripe-renewal-binding", 2, family, preimage]),
11
+ );
12
+ const bytes = new TextEncoder().encode(text);
13
+ if (bytes.byteLength > 500_000)
14
+ throw new Error("Renewal V2 binding exceeds its UTF-8 preimage budget.");
15
+ const subtle = globalThis.crypto?.subtle;
16
+ if (!subtle || typeof subtle.digest !== "function")
17
+ throw new Error("Renewal V2 requires Web Crypto SHA-256.");
18
+ const digest = await subtle.digest("SHA-256", bytes);
19
+ if (!(digest instanceof ArrayBuffer) || digest.byteLength !== 32)
20
+ throw new Error("Renewal V2 received an invalid SHA-256 result.");
21
+ const hex = Array.from(new Uint8Array(digest), (byte) =>
22
+ byte.toString(16).padStart(2, "0"),
23
+ ).join("");
24
+ return `${family}:v2:sha256:${hex}`;
25
+ }