@fantastic.dev/better-stripe 0.84.0 → 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 (33) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +1 -1
  3. package/dist/client/billing/renewalV2/binding.d.ts +1 -1
  4. package/dist/client/billing/renewalV2/binding.d.ts.map +1 -1
  5. package/dist/client/billing/renewalV2/binding.js.map +1 -1
  6. package/dist/client/billing/renewalV2/index.d.ts +25 -0
  7. package/dist/client/billing/renewalV2/index.d.ts.map +1 -1
  8. package/dist/client/billing/renewalV2/index.js +55 -1
  9. package/dist/client/billing/renewalV2/index.js.map +1 -1
  10. package/dist/client/billing/renewalV2/receipt.d.ts +36 -0
  11. package/dist/client/billing/renewalV2/receipt.d.ts.map +1 -0
  12. package/dist/client/billing/renewalV2/receipt.js +131 -0
  13. package/dist/client/billing/renewalV2/receipt.js.map +1 -0
  14. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +32 -32
  15. package/dist/client/connect/payoutSyncTestHelpers.d.ts +16 -16
  16. package/dist/client/renewal.d.ts +2 -2
  17. package/dist/client/renewal.d.ts.map +1 -1
  18. package/dist/client/renewal.js +1 -1
  19. package/dist/client/renewal.js.map +1 -1
  20. package/dist/client/usage/observationClient.d.ts +2 -2
  21. package/dist/client/usage/observationClient.d.ts.map +1 -1
  22. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  23. package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
  24. package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
  25. package/dist/component/earnings/triggers.d.ts +16 -16
  26. package/docs/renewal-context-reads.md +69 -3
  27. package/docs/renewal-phase-assembly.md +5 -0
  28. package/package.json +1 -1
  29. package/src/client/billing/renewalV2/binding.ts +1 -1
  30. package/src/client/billing/renewalV2/index.ts +104 -1
  31. package/src/client/billing/renewalV2/receipt.test.ts +289 -0
  32. package/src/client/billing/renewalV2/receipt.ts +163 -0
  33. package/src/client/renewal.ts +3 -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;
@@ -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;
@@ -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;
@@ -179,8 +179,9 @@ from its full provider snapshot, expected selectors and retained logical key,
179
179
  and compares the entire result before constructing the request. A matching
180
180
  digest alone is insufficient. V1 preparations are rejected by this builder;
181
181
  there is no automatic migration or fallback. Existing V1 projection, receipt
182
- and configure consumers do not accept V2 records. This release adds preparation
183
- and request construction only, without a V2 writer or receipt constructor.
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.
184
185
 
185
186
  V2 retains the same raw preparation semantic checks and bounded JSON policy as
186
187
  V1. It adds a limit of 500,000 UTF-8 bytes on each exact encoded hash preimage,
@@ -197,7 +198,8 @@ the existing ordering, including JavaScript's numeric-index enumeration;
197
198
  arrays retain their order and negative zero serializes as zero. The output is
198
199
  `family:v2:sha256:` followed by the full 64 lowercase hexadecimal digest.
199
200
  Families are selected internally: `renewal` for preparation and
200
- `renewal-attach` for the attachment request.
201
+ `renewal-attach` for the attachment request and `renewal-attach-receipt` for the
202
+ complete attachment receipt.
201
203
 
202
204
  The preparation preimage contains version, platform scope, expected selectors,
203
205
  quantity and complete provider snapshot. Its logical key is separately retained
@@ -209,6 +211,70 @@ complete payload, explicit attachment key and original first-dispatch time.
209
211
  Neither digest authenticates a caller, proves provenance, acknowledges a POST
210
212
  or guarantees provider replay. Hosts retain the complete original records.
211
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
+
212
278
  These helpers retain ordinary provider and caller metadata within their JSON
213
279
  limits. They do not redact, encrypt or certify that input or output is safe to
214
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.84.0",
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",
@@ -2,7 +2,7 @@ import { renewalSnapshot } from "../renewalReplacementSnapshot.js";
2
2
 
3
3
  /** Internal fixed-family encoding. This is consistency, not authorization. */
4
4
  export async function renewalBindingV2(
5
- family: "renewal" | "renewal-attach",
5
+ family: "renewal" | "renewal-attach" | "renewal-attach-receipt",
6
6
  preimage: unknown,
7
7
  ): Promise<string> {
8
8
  // Finish all input capture and canonical bytes before the first await.
@@ -5,9 +5,18 @@ import {
5
5
  type PreparedRenewalPriceReplacement,
6
6
  } from "../renewalPriceReplacement.js";
7
7
  import { renewalSnapshot } from "../renewalReplacementSnapshot.js";
8
- import { supportedVersion, timestamp } from "../renewalAggregate/shared.js";
8
+ import {
9
+ supportedVersion,
10
+ timestamp,
11
+ resourceId,
12
+ equal,
13
+ } from "../renewalAggregate/shared.js";
9
14
  import { idempotencyOptions } from "../../core/idempotency.js";
10
15
  import { renewalBindingV2 } from "./binding.js";
16
+ import {
17
+ captureAttachmentReceipt,
18
+ assertAttachmentIdentity,
19
+ } from "./receipt.js";
11
20
 
12
21
  export type PrepareRenewalPriceReplacementV2Options =
13
22
  PrepareRenewalPriceReplacementOptions;
@@ -109,3 +118,97 @@ export async function prepareRenewalScheduleAttachmentV2(
109
118
  const binding = await renewalBindingV2("renewal-attach", request);
110
119
  return { ...request, requestIdentity: { key, binding } };
111
120
  }
121
+
122
+ export type ConstructRenewalScheduleAttachmentReceiptV2Options = {
123
+ attachRequest: {
124
+ preparation: PrepareRenewalPriceReplacementV2Options;
125
+ apiVersion: string;
126
+ attachKey: string;
127
+ firstDispatchedAt: number;
128
+ };
129
+ actualDispatch: Pick<
130
+ PreparedRenewalScheduleAttachmentV2,
131
+ | "scope"
132
+ | "apiVersion"
133
+ | "method"
134
+ | "path"
135
+ | "payload"
136
+ | "key"
137
+ | "firstDispatchedAt"
138
+ >;
139
+ providerSnapshot: Record<string, unknown>;
140
+ };
141
+ export type RenewalScheduleAttachmentReceiptV2 = {
142
+ version: 2;
143
+ stage: "attached_unconfigured";
144
+ scope: "platform";
145
+ logicalBinding: string;
146
+ request: PreparedRenewalScheduleAttachmentV2;
147
+ scheduleId: string;
148
+ subscriptionId: string;
149
+ customerAccountId: string;
150
+ livemode: boolean;
151
+ providerSnapshot: Record<string, unknown>;
152
+ binding: string;
153
+ };
154
+
155
+ /** Pure unsigned consistency data. Does not authenticate or acknowledge a POST. */
156
+ export async function constructRenewalScheduleAttachmentReceiptV2(
157
+ options: ConstructRenewalScheduleAttachmentReceiptV2Options,
158
+ ): Promise<RenewalScheduleAttachmentReceiptV2> {
159
+ const args = captureAttachmentReceipt(options);
160
+ const prepared = await prepareRenewalPriceReplacementV2({
161
+ ...args.attachRequest.preparation,
162
+ expected: args.attachRequest.preparation
163
+ .expected as PrepareRenewalPriceReplacementOptions["expected"],
164
+ });
165
+ const request = await prepareRenewalScheduleAttachmentV2({
166
+ prepared,
167
+ apiVersion: args.attachRequest.apiVersion,
168
+ attachKey: args.attachRequest.attachKey,
169
+ firstDispatchedAt: args.attachRequest.firstDispatchedAt,
170
+ });
171
+ const { scope, apiVersion, method, path, payload, key, firstDispatchedAt } =
172
+ request;
173
+ if (
174
+ !equal(args.actualDispatch, {
175
+ scope,
176
+ apiVersion,
177
+ method,
178
+ path,
179
+ payload,
180
+ key,
181
+ firstDispatchedAt,
182
+ })
183
+ )
184
+ throw Error(
185
+ "Renewal attachment dispatch does not match its complete request.",
186
+ );
187
+ const billingCustomer = prepared.providerSnapshot.billingCustomer;
188
+ if (!billingCustomer)
189
+ throw Error("Renewal attachment requires its retained billing Customer.");
190
+ const scheduleId = resourceId("sub_sched").parse(args.providerSnapshot.id);
191
+ assertAttachmentIdentity(args.providerSnapshot, {
192
+ scheduleId,
193
+ subscriptionId: prepared.expected.subscriptionId,
194
+ billingCustomerId: billingCustomer.id,
195
+ customerAccountId: prepared.expected.customerAccountId,
196
+ livemode: prepared.expected.livemode,
197
+ });
198
+ const receipt = {
199
+ version: 2 as const,
200
+ stage: "attached_unconfigured" as const,
201
+ scope: "platform" as const,
202
+ logicalBinding: prepared.requestIdentity.binding,
203
+ request,
204
+ scheduleId,
205
+ subscriptionId: prepared.expected.subscriptionId,
206
+ customerAccountId: prepared.expected.customerAccountId,
207
+ livemode: prepared.expected.livemode,
208
+ providerSnapshot: args.providerSnapshot,
209
+ };
210
+ return {
211
+ ...receipt,
212
+ binding: await renewalBindingV2("renewal-attach-receipt", receipt),
213
+ };
214
+ }