@fantastic.dev/better-stripe 0.111.0 → 0.113.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 (87) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +1 -1
  3. package/dist/client/billing/renewalAttach/internal/observation/freshActor.d.ts +564 -0
  4. package/dist/client/billing/renewalAttach/internal/observation/freshActor.d.ts.map +1 -1
  5. package/dist/client/billing/renewalAttach/internal/observation/freshActor.js +103 -21
  6. package/dist/client/billing/renewalAttach/internal/observation/freshActor.js.map +1 -1
  7. package/dist/client/billing/renewalAttach/internal/observation/freshTransport.d.ts +18 -1
  8. package/dist/client/billing/renewalAttach/internal/observation/freshTransport.d.ts.map +1 -1
  9. package/dist/client/billing/renewalAttach/internal/observation/freshTransport.js +54 -1
  10. package/dist/client/billing/renewalAttach/internal/observation/freshTransport.js.map +1 -1
  11. package/dist/client/billing/renewalAttach/internal/observation/invocation.d.ts +4 -0
  12. package/dist/client/billing/renewalAttach/internal/observation/invocation.d.ts.map +1 -1
  13. package/dist/client/billing/renewalAttach/internal/observation/invocation.js +1 -0
  14. package/dist/client/billing/renewalAttach/internal/observation/invocation.js.map +1 -1
  15. package/dist/client/billing/renewalAttach/internal/observation/readerAuthorization.d.ts +4 -0
  16. package/dist/client/billing/renewalAttach/internal/observation/readerAuthorization.d.ts.map +1 -1
  17. package/dist/client/billing/renewalAttach/internal/observation/readerAuthorization.js +6 -1
  18. package/dist/client/billing/renewalAttach/internal/observation/readerAuthorization.js.map +1 -1
  19. package/dist/client/billing/renewalAttach/internal/observation/witnessAuthorization.d.ts +38 -0
  20. package/dist/client/billing/renewalAttach/internal/observation/witnessAuthorization.d.ts.map +1 -0
  21. package/dist/client/billing/renewalAttach/internal/observation/witnessAuthorization.js +172 -0
  22. package/dist/client/billing/renewalAttach/internal/observation/witnessAuthorization.js.map +1 -0
  23. package/dist/client/billing/renewalAttach/internal/observation/witnessData.d.ts +135 -0
  24. package/dist/client/billing/renewalAttach/internal/observation/witnessData.d.ts.map +1 -0
  25. package/dist/client/billing/renewalAttach/internal/observation/witnessData.js +143 -0
  26. package/dist/client/billing/renewalAttach/internal/observation/witnessData.js.map +1 -0
  27. package/dist/client/billing/renewalAttach/internal/observation/witnessOperation.d.ts +85 -0
  28. package/dist/client/billing/renewalAttach/internal/observation/witnessOperation.d.ts.map +1 -0
  29. package/dist/client/billing/renewalAttach/internal/observation/witnessOperation.js +121 -0
  30. package/dist/client/billing/renewalAttach/internal/observation/witnessOperation.js.map +1 -0
  31. package/dist/client/billing/renewalAttach/internal/operations/witnessProfiles.d.ts +44 -0
  32. package/dist/client/billing/renewalAttach/internal/operations/witnessProfiles.d.ts.map +1 -0
  33. package/dist/client/billing/renewalAttach/internal/operations/witnessProfiles.js +4 -0
  34. package/dist/client/billing/renewalAttach/internal/operations/witnessProfiles.js.map +1 -0
  35. package/dist/client/billing/renewalAttach/internal/producer/configureJournalWork.d.ts +1 -1
  36. package/dist/client/billing/renewalAttach/internal/producer/configureLineage.d.ts +21 -21
  37. package/dist/client/billing/renewalAttach/internal/producer/journalWorkFactory.d.ts +3 -3
  38. package/dist/client/billing/renewalAttach/internal/producer/operationFactory.d.ts +1 -1
  39. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +32 -32
  40. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +16 -16
  41. package/dist/component/_generated/api.d.ts +24 -0
  42. package/dist/component/_generated/api.d.ts.map +1 -1
  43. package/dist/component/_generated/api.js.map +1 -1
  44. package/dist/component/_generated/component.d.ts +94 -10
  45. package/dist/component/_generated/component.d.ts.map +1 -1
  46. package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
  47. package/dist/component/balanceFunding/queries.d.ts +1 -1
  48. package/dist/component/financialObservations/settlementHelpers.d.ts +3 -3
  49. package/dist/component/renewalWitnesses/mutations.d.ts +45 -0
  50. package/dist/component/renewalWitnesses/mutations.d.ts.map +1 -0
  51. package/dist/component/renewalWitnesses/mutations.js +14 -0
  52. package/dist/component/renewalWitnesses/mutations.js.map +1 -0
  53. package/dist/component/renewalWitnesses/queries.d.ts +39 -0
  54. package/dist/component/renewalWitnesses/queries.d.ts.map +1 -0
  55. package/dist/component/renewalWitnesses/queries.js +11 -0
  56. package/dist/component/renewalWitnesses/queries.js.map +1 -0
  57. package/dist/component/usage/allowance.fixtures.d.ts +16 -16
  58. package/docs/renewal-example-authorization.md +74 -0
  59. package/docs/renewal-witness-protocol.md +61 -10
  60. package/package.json +1 -1
  61. package/src/client/billing/renewalAttach/internal/observation/freshActor.ts +142 -19
  62. package/src/client/billing/renewalAttach/internal/observation/freshTransport.ts +90 -1
  63. package/src/client/billing/renewalAttach/internal/observation/invocation.ts +2 -0
  64. package/src/client/billing/renewalAttach/internal/observation/readerAuthorization.ts +6 -1
  65. package/src/client/billing/renewalAttach/internal/observation/witnessAcquisition.integration.test.ts +348 -0
  66. package/src/client/billing/renewalAttach/internal/observation/witnessActor.integration.test.ts +204 -0
  67. package/src/client/billing/renewalAttach/internal/observation/witnessAuthorization.ts +239 -0
  68. package/src/client/billing/renewalAttach/internal/observation/witnessCapabilities.integration.test.ts +231 -0
  69. package/src/client/billing/renewalAttach/internal/observation/witnessData.ts +189 -0
  70. package/src/client/billing/renewalAttach/internal/observation/witnessHistorical.integration.test.ts +98 -0
  71. package/src/client/billing/renewalAttach/internal/observation/witnessImmutable.integration.test.ts +78 -0
  72. package/src/client/billing/renewalAttach/internal/observation/witnessInvoice.integration.test.ts +85 -0
  73. package/src/client/billing/renewalAttach/internal/observation/witnessLifecycle.integration.test.ts +264 -0
  74. package/src/client/billing/renewalAttach/internal/observation/witnessOperation.ts +205 -0
  75. package/src/client/billing/renewalAttach/internal/observation/witnessProfile.integration.test.ts +93 -0
  76. package/src/client/billing/renewalAttach/internal/observation/witnessRPCControls.integration.test.ts +256 -0
  77. package/src/client/billing/renewalAttach/internal/operations/witnessProfiles.ts +58 -0
  78. package/src/client/billing/renewalAttach/internal/test-fixtures/invoiceObservation.ts +3 -1
  79. package/src/client/billing/renewalAttach/internal/test-fixtures/producerConfigureAdmission.ts +8 -0
  80. package/src/client/billing/renewalAttach/internal/test-fixtures/producerInitialOperation.ts +28 -11
  81. package/src/client/billing/renewalAttach/internal/test-fixtures/witnessHistory.ts +70 -0
  82. package/src/client/billing/renewalAttach/internal/test-fixtures/witnessObservation.ts +353 -0
  83. package/src/component/_generated/api.ts +24 -0
  84. package/src/component/_generated/component.ts +98 -10
  85. package/src/component/renewalWitnesses/mutations.ts +17 -0
  86. package/src/component/renewalWitnesses/queries.ts +11 -0
  87. package/src/component/renewalWitnesses/routes.test.ts +154 -0
@@ -1,4 +1,18 @@
1
1
  import { getFunctionAddress } from "convex/server";
2
+ import { types } from "node:util";
3
+ import { closed } from "../c10/ownData.js";
4
+ import {
5
+ witnessIdentity,
6
+ witnessText,
7
+ } from "../../../../../shared/renewalWitness.js";
8
+ import {
9
+ captureWitnessProfile,
10
+ witnessProfileGuard,
11
+ witnessAddress,
12
+ type WitnessMode,
13
+ type WitnessProfile,
14
+ } from "./witnessAuthorization.js";
15
+ import { createWitnessOperation } from "./witnessOperation.js";
2
16
  import {
3
17
  captureInvoiceObservationProfile,
4
18
  invoiceProfileGuard,
@@ -45,16 +59,77 @@ export async function captureFreshInvoiceRenewalObservation(
45
59
  const profile = captureInvoiceObservationProfile(root);
46
60
  return captureFreshObservation(root, raw, profile);
47
61
  }
62
+ type WitnessSpec = Readonly<{
63
+ profile: WitnessProfile;
64
+ mode: WitnessMode;
65
+ identity: ReturnType<typeof witnessIdentity>;
66
+ }>;
67
+ export async function captureFreshWitnessRenewalObservation(
68
+ root: object,
69
+ raw: unknown,
70
+ ) {
71
+ need(arguments.length === 2);
72
+ return captureWitnessObservation(root, raw, "retain");
73
+ }
74
+ export async function captureHistoricalWitnessRenewalObservation(
75
+ root: object,
76
+ raw: unknown,
77
+ ) {
78
+ need(arguments.length === 2);
79
+ return captureWitnessObservation(root, raw, "read");
80
+ }
81
+ function captureWitnessObservation(
82
+ root: object,
83
+ raw: unknown,
84
+ mode: WitnessMode,
85
+ ) {
86
+ const profile = captureWitnessProfile(root, mode);
87
+ need(!types.isProxy(raw));
88
+ const input = closed(raw, [
89
+ "actualActionCtx",
90
+ "parentOperationId",
91
+ "operationId",
92
+ "witnessId",
93
+ ]);
94
+ const identity = witnessIdentity({
95
+ componentScope: profile.freshProfile.historyEntry.componentScope,
96
+ witnessId: witnessText(input.witnessId),
97
+ parentOperationId: input.parentOperationId,
98
+ operationId: input.operationId,
99
+ });
100
+ return captureFreshObservation(
101
+ root,
102
+ {
103
+ actualActionCtx: input.actualActionCtx,
104
+ parentOperationId: identity.parentOperationId,
105
+ operationId: identity.operationId,
106
+ },
107
+ profile.invoiceProfile,
108
+ { profile, mode, identity },
109
+ );
110
+ }
48
111
  async function captureFreshObservation(
49
112
  root: object,
50
113
  raw: unknown,
51
114
  invoiceProfile: InvoiceObservationProfile | null,
115
+ witnessSpec: WitnessSpec | null = null,
52
116
  ) {
53
117
  const profile = captureFreshObservationProfile(root);
118
+ const witnessQueryAddress =
119
+ witnessSpec && witnessAddress(witnessSpec.profile.authorizationQuery);
54
120
  const invoiceAddress =
55
121
  invoiceProfile &&
56
122
  JSON.stringify(getFunctionAddress(invoiceProfile.authorizationQuery));
57
123
  const invoiceGuard = () => {
124
+ if (witnessSpec) {
125
+ witnessProfileGuard(witnessSpec.profile, witnessSpec.mode);
126
+ need(
127
+ witnessSpec.profile.freshProfile === profile &&
128
+ witnessSpec.profile.invoiceProfile === invoiceProfile &&
129
+ witnessAddress(witnessSpec.profile.authorizationQuery) ===
130
+ witnessQueryAddress,
131
+ );
132
+ }
58
133
  if (invoiceProfile) {
59
134
  invoiceProfileGuard(invoiceProfile);
60
135
  need(
@@ -90,9 +165,42 @@ async function captureFreshObservation(
90
165
  profile,
91
166
  invoiceProfile,
92
167
  );
168
+ const witness =
169
+ witnessSpec &&
170
+ createWitnessOperation(
171
+ token,
172
+ witnessSpec.profile,
173
+ witnessSpec.mode,
174
+ witnessSpec.identity,
175
+ );
176
+ if (witnessSpec?.mode === "read") await witness!.load();
93
177
  let invoiceResult: Awaited<
94
178
  ReturnType<typeof transport.acquireInvoices>
95
179
  > | null = null;
180
+ async function analyze(reads: ObservationReads | null) {
181
+ return state.owned(async () => {
182
+ try {
183
+ const evidence = await inspectRenewalEvidenceV1({
184
+ version: 1,
185
+ apiVersion: "2026-09-30.endive",
186
+ configuration: captured.history.record.configuration,
187
+ configureReceipt: captured.history.rawConfigureReceipt,
188
+ reads,
189
+ invoiceContext: invoiceResult?.context ?? null,
190
+ historicalSnapshot: null,
191
+ });
192
+ if (witnessSpec?.mode !== "read") return evidence;
193
+ const historical = await witness!.historicalEvidence();
194
+ return {
195
+ ...evidence,
196
+ identity: evidence.identity ?? historical.identity,
197
+ historicalMaterial: historical.material,
198
+ };
199
+ } catch {
200
+ return null;
201
+ }
202
+ }, transport.guard);
203
+ }
96
204
  async function release(
97
205
  status:
98
206
  | "fresh_observation_data"
@@ -107,8 +215,33 @@ async function captureFreshObservation(
107
215
  ) {
108
216
  await transport.finalizeInvoices();
109
217
  transport.guard();
218
+ let witnessRetention: Awaited<
219
+ ReturnType<ReturnType<typeof createWitnessOperation>["retain"]>
220
+ > | null = null;
221
+ if (witnessSpec?.mode === "retain") {
222
+ need(
223
+ status === "fresh_observation_data" &&
224
+ reads &&
225
+ evidence?.currentMaterial.predicate ===
226
+ "current_target_material_match" &&
227
+ couponInventory === "complete",
228
+ );
229
+ if (invoiceProfile)
230
+ need(
231
+ invoiceResult?.status === "complete" && invoiceResult.context,
232
+ );
233
+ witnessRetention = await witness!.retain();
234
+ await transport.finalizeInvoices();
235
+ } else if (witnessSpec?.mode === "read" && evidence === null)
236
+ evidence = await analyze(reads);
237
+ if (witness) await witness.finalize();
110
238
  const output = captureReaderQueryDATA({
111
239
  status,
240
+ ...(witnessSpec?.mode === "retain"
241
+ ? { witnessRetention }
242
+ : witnessSpec?.mode === "read"
243
+ ? { witness: { descriptor: witness!.descriptor() } }
244
+ : {}),
112
245
  ...(invoiceProfile
113
246
  ? {
114
247
  invoiceContext: invoiceResult?.context ?? null,
@@ -130,11 +263,14 @@ async function captureFreshObservation(
130
263
  operationalAuthority: false as const,
131
264
  });
132
265
  transport.guard();
266
+ witness?.guard();
133
267
  return output;
134
268
  }
135
269
  const base: unknown[] = [];
136
270
  for (const row of baseReadRows(captured.history.record)) {
271
+ witness?.guard();
137
272
  const result = await transport.read(row);
273
+ witness?.guard();
138
274
  if (result.kind === "provider_rejected")
139
275
  return await release(
140
276
  "observation_provider_rejected",
@@ -164,23 +300,6 @@ async function captureFreshObservation(
164
300
  "PROVIDER_IDENTITY_CONFLICT",
165
301
  );
166
302
  }
167
- async function analyze() {
168
- return state.owned(async () => {
169
- try {
170
- return await inspectRenewalEvidenceV1({
171
- version: 1,
172
- apiVersion: "2026-09-30.endive",
173
- configuration: captured.history.record.configuration,
174
- configureReceipt: captured.history.rawConfigureReceipt,
175
- reads,
176
- invoiceContext: invoiceResult?.context ?? null,
177
- historicalSnapshot: null,
178
- });
179
- } catch {
180
- return null;
181
- }
182
- }, transport.guard);
183
- }
184
303
  let ids: readonly string[];
185
304
  try {
186
305
  validateBaseRouting(captured.history.record, reads);
@@ -189,7 +308,7 @@ async function captureFreshObservation(
189
308
  reads.subscription,
190
309
  );
191
310
  } catch {
192
- const analysis = await analyze();
311
+ const analysis = await analyze(reads);
193
312
  return await release(
194
313
  "unsupported_observation_profile",
195
314
  reads,
@@ -200,7 +319,9 @@ async function captureFreshObservation(
200
319
  }
201
320
  for (const id of ids) {
202
321
  const row = couponReadRow(id, 5 + reads.coupons.length);
322
+ witness?.guard();
203
323
  const result = await transport.read(row);
324
+ witness?.guard();
204
325
  if (result.kind === "provider_rejected")
205
326
  return await release(
206
327
  "observation_provider_rejected",
@@ -214,7 +335,9 @@ async function captureFreshObservation(
214
335
  reads.coupons.push(result.body);
215
336
  }
216
337
  if (invoiceProfile) {
338
+ witness?.guard();
217
339
  invoiceResult = await transport.acquireInvoices();
340
+ witness?.guard();
218
341
  if (invoiceResult.status === "provider_rejected")
219
342
  return await release(
220
343
  "observation_provider_rejected",
@@ -225,7 +348,7 @@ async function captureFreshObservation(
225
348
  invoiceResult.failure,
226
349
  );
227
350
  }
228
- const evidence = await analyze();
351
+ const evidence = await analyze(reads);
229
352
  return await release(
230
353
  "fresh_observation_data",
231
354
  reads,
@@ -21,6 +21,7 @@ import {
21
21
  captureInitialJournalSelection,
22
22
  } from "../producer/classOwnedActionRoot.js";
23
23
  import { readObservationInvocation } from "./invocation.js";
24
+ import { captureReaderQueryDATA } from "./readerAuthorization.js";
24
25
  import { closed, freeze } from "../c10/ownData.js";
25
26
  import {
26
27
  baseReadRows,
@@ -47,6 +48,42 @@ const method = Object.getOwnPropertyDescriptor(
47
48
  "rawRequest",
48
49
  )?.value;
49
50
  const nativeThen = Promise.prototype.then;
51
+ type Acquisition = Readonly<{
52
+ reads: ObservationReads;
53
+ invoiceContext: InvoiceContextV1 | null;
54
+ }>;
55
+ type TransportCell = Readonly<{
56
+ profile: FreshObservationProfile;
57
+ invoiceProfile: InvoiceObservationProfile | null;
58
+ guard(): void;
59
+ consume(): Acquisition;
60
+ }>;
61
+ const actualTransports = new WeakMap<object, TransportCell | null>();
62
+ /** Only the original factory registers this guard after actual SDK selection. */
63
+ export function readFreshObservationTransport(
64
+ token: object,
65
+ profile: FreshObservationProfile,
66
+ invoiceProfile: InvoiceObservationProfile | null,
67
+ ) {
68
+ const cell = actualTransports.get(token);
69
+ freshNeed(
70
+ cell && cell.profile === profile && cell.invoiceProfile === invoiceProfile,
71
+ );
72
+ cell.guard();
73
+ return cell;
74
+ }
75
+ /** Returned DATA cannot register or replenish this once-consumed acquisition. */
76
+ export function consumeFreshObservationAcquisition(
77
+ token: object,
78
+ profile: FreshObservationProfile,
79
+ invoiceProfile: InvoiceObservationProfile | null,
80
+ ) {
81
+ return readFreshObservationTransport(
82
+ token,
83
+ profile,
84
+ invoiceProfile,
85
+ ).consume();
86
+ }
50
87
  export function captureFreshObservationProfile(
51
88
  root: object,
52
89
  ): FreshObservationProfile {
@@ -84,6 +121,9 @@ export function captureFreshGetTransport(
84
121
  freshNeed(arguments.length === 2 || arguments.length === 3);
85
122
  const state = readObservationInvocation(token),
86
123
  captured = state.readCaptured();
124
+ freshNeed(!actualTransports.has(token));
125
+ // Reserve before any Source callback or SDK selection; failed setup stays unavailable.
126
+ actualTransports.set(token, null);
87
127
  freshNeed(state.historyEntry === profile.historyEntry);
88
128
  const covers = profile.coversObservation;
89
129
  const invoiceAddress =
@@ -93,6 +133,7 @@ export function captureFreshGetTransport(
93
133
  typeof createInvoiceAuthorization
94
134
  > | null = null;
95
135
  let invoiceUsed = false;
136
+ let completeInvoiceContext: InvoiceContextV1 | null = null;
96
137
  function profileGuard() {
97
138
  if (invoiceProfile) {
98
139
  invoiceProfileGuard(invoiceProfile);
@@ -149,6 +190,53 @@ export function captureFreshGetTransport(
149
190
  let ordinal = 0,
150
191
  busy = false,
151
192
  ended = false;
193
+ let acquisitionConsumed = false;
194
+ actualTransports.set(
195
+ token,
196
+ Object.freeze({
197
+ profile,
198
+ invoiceProfile,
199
+ guard,
200
+ consume() {
201
+ guard();
202
+ freshNeed(
203
+ !acquisitionConsumed &&
204
+ !busy &&
205
+ !ended &&
206
+ ordinal >= 4 &&
207
+ bodies.length === ordinal,
208
+ );
209
+ const reads: ObservationReads = {
210
+ schedule: bodies[0],
211
+ subscription: bodies[1],
212
+ targetPrice: bodies[2],
213
+ billingCustomer: bodies[3],
214
+ coupons: bodies.slice(4),
215
+ };
216
+ validateBaseRouting(captured.history.record, reads);
217
+ const ids = observationCouponIds(
218
+ captured.history.record,
219
+ reads.subscription,
220
+ );
221
+ freshNeed(ordinal === 4 + ids.length);
222
+ ids.forEach((id, index) =>
223
+ validateCoupon(captured.history.record, id, reads.coupons[index]),
224
+ );
225
+ freshNeed(
226
+ invoiceProfile === null
227
+ ? !invoiceUsed
228
+ : completeInvoiceContext !== null,
229
+ );
230
+ const acquired = captureReaderQueryDATA({
231
+ reads,
232
+ invoiceContext: completeInvoiceContext,
233
+ });
234
+ acquisitionConsumed = true;
235
+ guard();
236
+ return acquired;
237
+ },
238
+ }),
239
+ );
152
240
  function expected() {
153
241
  if (ordinal < 4) return base[ordinal];
154
242
  const reads: ObservationReads = {
@@ -364,9 +452,10 @@ export function captureFreshGetTransport(
364
452
  });
365
453
  }
366
454
  }
455
+ completeInvoiceContext = plan.context();
367
456
  return Object.freeze({
368
457
  status: "complete",
369
- context: plan.context(),
458
+ context: completeInvoiceContext,
370
459
  reason: null,
371
460
  failure: null,
372
461
  });
@@ -33,6 +33,7 @@ type CapturedHistory = Readonly<{
33
33
  export interface ObservationInvocationState {
34
34
  readonly binding: object;
35
35
  readonly historyEntry: ObservationHistorySourceEntry;
36
+ readonly startedAt: Readonly<{ wallMs: number; ns: bigint }>;
36
37
  guard(): void;
37
38
  check(): { wallMs: number; ns: bigint };
38
39
  close(): void;
@@ -273,6 +274,7 @@ export async function captureObservationInvocation(
273
274
  Object.freeze({
274
275
  binding,
275
276
  historyEntry: entry,
277
+ startedAt: lifetime.startedAt,
276
278
  guard() {
277
279
  lifetime.check();
278
280
  guard();
@@ -175,5 +175,10 @@ export function createObservationReaderLifetime() {
175
175
  throw error;
176
176
  }
177
177
  }
178
- return Object.freeze({ check, close, owned });
178
+ return Object.freeze({
179
+ startedAt: Object.freeze({ ...initial }),
180
+ check,
181
+ close,
182
+ owned,
183
+ });
179
184
  }