@fantastic.dev/better-stripe 0.92.0 → 0.93.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 (84) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +1 -1
  3. package/dist/client/billing/renewalAttach/internal/producer/classOwnedActionRoot.d.ts +30 -0
  4. package/dist/client/billing/renewalAttach/internal/producer/classOwnedActionRoot.d.ts.map +1 -0
  5. package/dist/client/billing/renewalAttach/internal/producer/classOwnedActionRoot.js +113 -0
  6. package/dist/client/billing/renewalAttach/internal/producer/classOwnedActionRoot.js.map +1 -0
  7. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +594 -32
  8. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +281 -0
  10. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  11. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +594 -32
  12. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  13. package/dist/client/connect/payoutSyncTestHelpers.d.ts +281 -0
  14. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  15. package/dist/client/index.d.ts +3 -2
  16. package/dist/client/index.d.ts.map +1 -1
  17. package/dist/client/index.js +16 -3
  18. package/dist/client/index.js.map +1 -1
  19. package/dist/component/_generated/api.d.ts +6 -0
  20. package/dist/component/_generated/api.d.ts.map +1 -1
  21. package/dist/component/_generated/api.js.map +1 -1
  22. package/dist/component/_generated/component.d.ts +406 -0
  23. package/dist/component/_generated/component.d.ts.map +1 -1
  24. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  25. package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
  26. package/dist/component/balanceFunding/workflowValidators.d.ts +16 -16
  27. package/dist/component/earnings/triggers.d.ts +294 -0
  28. package/dist/component/earnings/triggers.d.ts.map +1 -1
  29. package/dist/component/financialObservations/settlementHelpers.d.ts +3 -3
  30. package/dist/component/renewalOperations/helpers.d.ts +236 -0
  31. package/dist/component/renewalOperations/helpers.d.ts.map +1 -0
  32. package/dist/component/renewalOperations/helpers.js +457 -0
  33. package/dist/component/renewalOperations/helpers.js.map +1 -0
  34. package/dist/component/renewalOperations/mutations.d.ts +252 -0
  35. package/dist/component/renewalOperations/mutations.d.ts.map +1 -0
  36. package/dist/component/renewalOperations/mutations.js +340 -0
  37. package/dist/component/renewalOperations/mutations.js.map +1 -0
  38. package/dist/component/renewalOperations/queries.d.ts +163 -0
  39. package/dist/component/renewalOperations/queries.d.ts.map +1 -0
  40. package/dist/component/renewalOperations/queries.js +167 -0
  41. package/dist/component/renewalOperations/queries.js.map +1 -0
  42. package/dist/component/renewalOperations/schema.d.ts +1988 -0
  43. package/dist/component/renewalOperations/schema.d.ts.map +1 -0
  44. package/dist/component/renewalOperations/schema.js +227 -0
  45. package/dist/component/renewalOperations/schema.js.map +1 -0
  46. package/dist/component/schema.d.ts +281 -0
  47. package/dist/component/schema.js +5 -0
  48. package/dist/component/schema.js.map +1 -1
  49. package/dist/component/usage/allowance.fixtures.d.ts +281 -0
  50. package/dist/component/usage/allowance.fixtures.d.ts.map +1 -1
  51. package/dist/component/usageCredits/accounting.fixtures.d.ts +297 -16
  52. package/dist/component/usageCredits/accounting.fixtures.d.ts.map +1 -1
  53. package/dist/shared/renewalOperationJournal.d.ts +43 -0
  54. package/dist/shared/renewalOperationJournal.d.ts.map +1 -0
  55. package/dist/shared/renewalOperationJournal.js +294 -0
  56. package/dist/shared/renewalOperationJournal.js.map +1 -0
  57. package/docs/renewal-context-reads.md +152 -0
  58. package/package.json +1 -1
  59. package/src/client/billing/renewalAttach/internal/operationJournal.integration.test.ts +380 -0
  60. package/src/client/billing/renewalAttach/internal/producer/classOwnedActionRoot.ts +155 -0
  61. package/src/client/index.ts +24 -3
  62. package/src/component/_generated/api.ts +6 -0
  63. package/src/component/_generated/component.ts +450 -0
  64. package/src/component/renewalOperations/acknowledgement.fixtures.ts +552 -0
  65. package/src/component/renewalOperations/acknowledgement.test.ts +573 -0
  66. package/src/component/renewalOperations/acknowledgementReads.test.ts +442 -0
  67. package/src/component/renewalOperations/acknowledgementV2.test.ts +493 -0
  68. package/src/component/renewalOperations/acknowledgementV2Publication.test.ts +373 -0
  69. package/src/component/renewalOperations/basisBinding.test.ts +567 -0
  70. package/src/component/renewalOperations/basisLifecycle.test.ts +569 -0
  71. package/src/component/renewalOperations/boundHistory.test.ts +474 -0
  72. package/src/component/renewalOperations/helpers.ts +592 -0
  73. package/src/component/renewalOperations/historyReads.test.ts +595 -0
  74. package/src/component/renewalOperations/initialBasis.test.ts +578 -0
  75. package/src/component/renewalOperations/journal.test.ts +567 -0
  76. package/src/component/renewalOperations/mutations.ts +456 -0
  77. package/src/component/renewalOperations/payload.test.ts +589 -0
  78. package/src/component/renewalOperations/payloadEncoding.test.ts +592 -0
  79. package/src/component/renewalOperations/queries.ts +204 -0
  80. package/src/component/renewalOperations/schema.ts +268 -0
  81. package/src/component/renewalOperations/timingPolicy.fixtures.ts +193 -0
  82. package/src/component/renewalOperations/timingPolicy.test.ts +523 -0
  83. package/src/component/schema.ts +11 -0
  84. package/src/shared/renewalOperationJournal.ts +333 -0
@@ -0,0 +1,456 @@
1
+ import type { Infer } from "convex/values";
2
+ import { mutation } from "../_generated/server.js";
3
+ import {
4
+ admitJournalValue,
5
+ admitJournalStrings,
6
+ canonicalJournalEvent,
7
+ canonicalInitialBasis,
8
+ canonicalJournalRecord,
9
+ } from "../../shared/renewalOperationJournal.js";
10
+ import {
11
+ findOperation,
12
+ validateOperationalAttachSource,
13
+ originalRecord,
14
+ currentReservation,
15
+ checkedInitialBasis,
16
+ reservationFields,
17
+ reservationMatches,
18
+ eventChain,
19
+ validateAttachAcknowledgement,
20
+ validateAttachReceiptEventDATA,
21
+ validateKnownAcknowledgement,
22
+ validateV2KnownAcknowledgement,
23
+ } from "./helpers.js";
24
+ import {
25
+ creationArgs,
26
+ creationResult,
27
+ reserveArgs,
28
+ reserveResult,
29
+ appendArgs,
30
+ eventReceipt,
31
+ retainAcknowledgementArgs,
32
+ retentionReceipt,
33
+ knownAcknowledgement,
34
+ bindInitialBasisArgs,
35
+ basisBindingReceipt,
36
+ initialBasisDescriptor,
37
+ } from "./schema.js";
38
+
39
+ /** Trusted host component API. Authorization policy remains outside the SDK. */
40
+ export const createAuthorizedOperation = mutation({
41
+ args: creationArgs,
42
+ returns: creationResult,
43
+ handler: async (ctx, args) => {
44
+ const full = canonicalJournalRecord(args.recordJSON);
45
+ admitJournalStrings([
46
+ full.authorizationScope,
47
+ full.authorizationId,
48
+ full.logicalOperationId,
49
+ full.requestBinding,
50
+ ]);
51
+ const conflict = {
52
+ status: "conflict" as const,
53
+ reason: "identity_changed" as const,
54
+ };
55
+ if (
56
+ full.authorizationScope !== args.authorizationScope ||
57
+ full.logicalOperationId !== args.logicalOperationId ||
58
+ full.authorizationRevision !== args.authorizationRevision
59
+ )
60
+ return conflict;
61
+ await validateOperationalAttachSource(full);
62
+ const existing = await findOperation(
63
+ ctx,
64
+ args.authorizationScope,
65
+ args.logicalOperationId,
66
+ );
67
+ if (existing) {
68
+ const original = await originalRecord(ctx, existing);
69
+ if (original.json !== full.json) return conflict;
70
+ if (existing.recordVersion === 2) {
71
+ const current = await currentReservation(ctx, existing, original);
72
+ if (current) {
73
+ const events = await eventChain(ctx, current);
74
+ await validateV2KnownAcknowledgement(
75
+ ctx,
76
+ existing,
77
+ original,
78
+ current,
79
+ events,
80
+ );
81
+ }
82
+ }
83
+ return { status: "existing" as const, operationId: existing._id };
84
+ }
85
+ const payloadId = await ctx.db.insert("renewalOperationPayloads", {
86
+ codecVersion: 1,
87
+ json: full.json,
88
+ });
89
+ const operationId = await ctx.db.insert("renewalOperations", {
90
+ ...("recordVersion" in full && full.recordVersion === 2
91
+ ? { recordVersion: 2 as const }
92
+ : {}),
93
+ authorizationScope: full.authorizationScope,
94
+ authorizationId: full.authorizationId,
95
+ authorizationRevision: full.authorizationRevision,
96
+ logicalOperationId: full.logicalOperationId,
97
+ requestBinding: full.requestBinding,
98
+ payloadId,
99
+ revision: 0,
100
+ state: "PREPARED",
101
+ });
102
+ // Link the actual operation before this transaction commits.
103
+ await ctx.db.patch("renewalOperationPayloads", payloadId, {
104
+ owner: { kind: "operation", operationId },
105
+ });
106
+ return { status: "created" as const, operationId };
107
+ },
108
+ });
109
+
110
+ /** First CAS only. The transient acquired result is never stored or echoed. */
111
+ export const reserveAttempt = mutation({
112
+ args: reserveArgs,
113
+ returns: reserveResult,
114
+ handler: async (ctx, args) => {
115
+ const conflict = {
116
+ disposition: "conflict" as const,
117
+ reason: "identity_changed" as const,
118
+ };
119
+ const row = await ctx.db.get("renewalOperations", args.operationId);
120
+ if (!row || args.expectedRevision !== 0) return conflict;
121
+ const full = await originalRecord(ctx, row);
122
+ const supplied = canonicalJournalRecord(args.recordJSON);
123
+ if (
124
+ supplied.json !== full.json ||
125
+ args.expectedRequestBinding !== full.requestBinding
126
+ )
127
+ return conflict;
128
+ const fields = reservationFields(row, full);
129
+ if (args.stage !== fields.stage) return conflict;
130
+ const current = await currentReservation(ctx, row, full);
131
+ if (current) {
132
+ if ("recordVersion" in current) {
133
+ const events = await eventChain(ctx, current);
134
+ await validateV2KnownAcknowledgement(ctx, row, full, current, events);
135
+ }
136
+ return {
137
+ disposition: "existing" as const,
138
+ committedRevision: 1 as const,
139
+ reservation: current,
140
+ };
141
+ }
142
+ // This read of PREPARED and both writes commit atomically under Convex OCC.
143
+ // A competing committed winner makes a rerun return existing above.
144
+ if (row.knownAcknowledgement !== undefined) return conflict;
145
+ const attemptId = await ctx.db.insert("renewalOperationAttempts", {
146
+ ...fields,
147
+ lastSequence: 0,
148
+ });
149
+ await ctx.db.patch("renewalOperations", row._id, {
150
+ revision: 1,
151
+ state: "RESERVED",
152
+ activeAttemptId: attemptId,
153
+ });
154
+ return {
155
+ disposition: "acquired" as const,
156
+ previousRevision: 0 as const,
157
+ committedRevision: 1 as const,
158
+ reservation: { ...fields, attemptId, recordJSON: full.json },
159
+ };
160
+ },
161
+ });
162
+
163
+ /** Storage consistency only. A stored row is not actual C10 fulfillment. */
164
+ export const appendStageEvent = mutation({
165
+ args: appendArgs,
166
+ returns: eventReceipt,
167
+ handler: async (ctx, args) => {
168
+ admitJournalValue(args);
169
+ const row = await ctx.db.get(
170
+ "renewalOperations",
171
+ args.reservation.operationId,
172
+ );
173
+ if (!row) throw Error("RENEWAL_JOURNAL_CONFLICT");
174
+ const full = await originalRecord(ctx, row);
175
+ const reservation = await currentReservation(ctx, row, full);
176
+ if (!reservation || !reservationMatches(reservation, args.reservation))
177
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
178
+ if (
179
+ row.recordVersion === 2 &&
180
+ checkedInitialBasis(row, reservation.attemptId, reservation) === null
181
+ )
182
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
183
+ if (
184
+ !Number.isSafeInteger(args.expectedSequence) ||
185
+ args.expectedSequence < 0 ||
186
+ args.expectedSequence > 2 ||
187
+ args.event.sequence !== args.expectedSequence + 1
188
+ )
189
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
190
+ const incoming = await canonicalJournalEvent(
191
+ args.event.sequence,
192
+ args.event.dataJSON,
193
+ );
194
+ if (incoming.binding !== args.event.binding)
195
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
196
+ const events = await eventChain(ctx, reservation);
197
+ const known =
198
+ "recordVersion" in reservation
199
+ ? await validateV2KnownAcknowledgement(
200
+ ctx,
201
+ row,
202
+ full,
203
+ reservation,
204
+ events,
205
+ )
206
+ : null;
207
+ if (known !== null && incoming.sequence === 3) {
208
+ try {
209
+ validateAttachReceiptEventDATA(incoming.json, known.admitted.receipt);
210
+ } catch {
211
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
212
+ }
213
+ }
214
+ // Known receipt3 publication must match the full retained C3/source, even
215
+ // on the identical-event duplicate branch below. Generic no-known DATA is
216
+ // deliberately unchanged.
217
+ if (
218
+ !("recordVersion" in reservation) &&
219
+ row.knownAcknowledgement !== undefined &&
220
+ incoming.sequence === 3
221
+ ) {
222
+ try {
223
+ const payload = await ctx.db.get(
224
+ "renewalOperationPayloads",
225
+ row.knownAcknowledgement.receiptPayloadId,
226
+ );
227
+ if (!payload) throw Error("RENEWAL_JOURNAL_CONFLICT");
228
+ const admitted = await validateAttachAcknowledgement(
229
+ full,
230
+ reservation,
231
+ events,
232
+ payload.json,
233
+ );
234
+ await validateKnownAcknowledgement(
235
+ ctx,
236
+ row,
237
+ reservation,
238
+ events,
239
+ admitted,
240
+ );
241
+ validateAttachReceiptEventDATA(incoming.json, admitted.receipt);
242
+ } catch {
243
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
244
+ }
245
+ }
246
+ const prior = events.find((event) => event.sequence === incoming.sequence);
247
+ if (prior) {
248
+ if (
249
+ prior.binding !== incoming.binding ||
250
+ prior.dataJSON !== incoming.json
251
+ )
252
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
253
+ const { dataJSON: _dataJSON, ...receipt } = prior;
254
+ void _dataJSON;
255
+ return { ...receipt, reservation };
256
+ }
257
+ if (args.expectedSequence !== events.length)
258
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
259
+ const payloadId = await ctx.db.insert("renewalOperationPayloads", {
260
+ codecVersion: 1,
261
+ json: incoming.json,
262
+ owner: {
263
+ kind: "event",
264
+ operationId: reservation.operationId,
265
+ attemptId: reservation.attemptId,
266
+ stage: reservation.stage,
267
+ sequence: incoming.sequence,
268
+ },
269
+ });
270
+ const fields = {
271
+ operationId: reservation.operationId,
272
+ attemptId: reservation.attemptId,
273
+ stage: reservation.stage,
274
+ sourcePayloadId: reservation.payloadId,
275
+ sequence: incoming.sequence,
276
+ binding: incoming.binding,
277
+ payloadId,
278
+ };
279
+ const eventId = await ctx.db.insert("renewalOperationEvents", fields);
280
+ await ctx.db.patch("renewalOperationAttempts", reservation.attemptId, {
281
+ lastSequence: incoming.sequence,
282
+ });
283
+ return { ...fields, eventId, reservation };
284
+ },
285
+ });
286
+
287
+ /** ATTACH retention at the checked head, with immutable known-DATA repeats. */
288
+ export const retainProviderAcknowledgement = mutation({
289
+ args: retainAcknowledgementArgs,
290
+ returns: retentionReceipt,
291
+ handler: async (ctx, args) => {
292
+ admitJournalValue(args);
293
+ try {
294
+ const row = await ctx.db.get("renewalOperations", args.operationId);
295
+ if (!row) throw Error("RENEWAL_JOURNAL_CONFLICT");
296
+ const full = await originalRecord(ctx, row);
297
+ const reservation = await currentReservation(ctx, row, full);
298
+ if (
299
+ !reservation ||
300
+ reservation.attemptId !== args.attemptId ||
301
+ reservation.stage !== "attach"
302
+ )
303
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
304
+ if (
305
+ "recordVersion" in reservation &&
306
+ checkedInitialBasis(row, reservation.attemptId, reservation) === null
307
+ )
308
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
309
+ const events = await eventChain(ctx, reservation);
310
+ const head = events.length;
311
+ if (
312
+ (head !== 2 && head !== 3) ||
313
+ args.expectedSequence > head ||
314
+ (row.knownAcknowledgement === undefined &&
315
+ args.expectedSequence !== head)
316
+ )
317
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
318
+ const admitted = await validateAttachAcknowledgement(
319
+ full,
320
+ reservation,
321
+ events,
322
+ args.receiptJSON,
323
+ );
324
+ const checkedKnown =
325
+ "recordVersion" in reservation
326
+ ? await validateV2KnownAcknowledgement(
327
+ ctx,
328
+ row,
329
+ full,
330
+ reservation,
331
+ events,
332
+ )
333
+ : null;
334
+ if (
335
+ checkedKnown !== null &&
336
+ checkedKnown.admitted.receiptJSON !== admitted.receiptJSON
337
+ )
338
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
339
+ const retained =
340
+ checkedKnown === null
341
+ ? await validateKnownAcknowledgement(
342
+ ctx,
343
+ row,
344
+ reservation,
345
+ events,
346
+ admitted,
347
+ )
348
+ : checkedKnown.retained;
349
+ if (retained !== null) {
350
+ const result: Infer<typeof retentionReceipt> = {
351
+ status: "retained",
352
+ operationId: row._id,
353
+ ...retained,
354
+ };
355
+ return result;
356
+ }
357
+ const receiptPayloadId = await ctx.db.insert("renewalOperationPayloads", {
358
+ codecVersion: 1,
359
+ json: admitted.receiptJSON,
360
+ owner: {
361
+ kind: "receipt",
362
+ operationId: row._id,
363
+ attemptId: reservation.attemptId,
364
+ stage: "attach",
365
+ },
366
+ });
367
+ const known: Infer<typeof knownAcknowledgement> = {
368
+ schemaVersion: 1,
369
+ stage: "attach",
370
+ attemptId: reservation.attemptId,
371
+ sourcePayloadId: reservation.payloadId,
372
+ dispatchEventId: events[0].eventId,
373
+ dispatchPayloadId: events[0].payloadId,
374
+ responseEventId: events[1].eventId,
375
+ responsePayloadId: events[1].payloadId,
376
+ receiptPayloadId,
377
+ receiptBinding: admitted.receiptBinding,
378
+ };
379
+ await ctx.db.patch("renewalOperations", row._id, {
380
+ knownAcknowledgement: known,
381
+ });
382
+ const result: Infer<typeof retentionReceipt> = {
383
+ status: "retained",
384
+ operationId: row._id,
385
+ ...known,
386
+ };
387
+ return result;
388
+ } catch {
389
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
390
+ }
391
+ },
392
+ });
393
+
394
+ /** Atomic first basis DATA binding; never mints a clock, Origin or Owner. */
395
+ export const bindInitialBasis = mutation({
396
+ args: bindInitialBasisArgs,
397
+ returns: basisBindingReceipt,
398
+ handler: async (ctx, args) => {
399
+ admitJournalValue(args);
400
+ try {
401
+ const row = await ctx.db.get("renewalOperations", args.operationId);
402
+ if (!row || row.recordVersion !== 2)
403
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
404
+ const full = await originalRecord(ctx, row);
405
+ const reservation = await currentReservation(ctx, row, full);
406
+ if (
407
+ !reservation ||
408
+ !("recordVersion" in reservation) ||
409
+ reservation.attemptId !== args.attemptId
410
+ )
411
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
412
+ const normalized = canonicalInitialBasis(args.policyJSON, args.basisJSON);
413
+ if (normalized.policyJSON !== reservation.timingPolicyJSON)
414
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
415
+ const existing = checkedInitialBasis(
416
+ row,
417
+ reservation.attemptId,
418
+ reservation,
419
+ );
420
+ const initialBasis: Infer<typeof initialBasisDescriptor> = {
421
+ version: 1,
422
+ attemptId: reservation.attemptId,
423
+ sourcePayloadId: reservation.payloadId,
424
+ stage: "attach",
425
+ policyJSON: normalized.policyJSON,
426
+ basisJSON: normalized.basisJSON,
427
+ };
428
+ if (existing !== null) {
429
+ const events = await eventChain(ctx, reservation);
430
+ await validateV2KnownAcknowledgement(
431
+ ctx,
432
+ row,
433
+ full,
434
+ reservation,
435
+ events,
436
+ );
437
+ if (
438
+ existing.policyJSON !== initialBasis.policyJSON ||
439
+ existing.basisJSON !== initialBasis.basisJSON
440
+ )
441
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
442
+ }
443
+ const result = {
444
+ status: "bound" as const,
445
+ operationId: row._id,
446
+ initialBasis: existing ?? initialBasis,
447
+ };
448
+ admitJournalValue(result);
449
+ if (existing === null)
450
+ await ctx.db.patch("renewalOperations", row._id, { initialBasis });
451
+ return result;
452
+ } catch {
453
+ throw Error("RENEWAL_JOURNAL_CONFLICT");
454
+ }
455
+ },
456
+ });