@fantastic.dev/better-stripe 0.29.0 → 0.30.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 (158) hide show
  1. package/CHANGELOG.md +16 -0
  2. package/MIGRATION.md +8 -0
  3. package/README.md +10 -1
  4. package/dist/client/connect/payoutActivationProof.d.ts.map +1 -1
  5. package/dist/client/connect/payoutActivationProof.js +88 -42
  6. package/dist/client/connect/payoutActivationProof.js.map +1 -1
  7. package/dist/client/connect/payoutAdoption.d.ts +3 -0
  8. package/dist/client/connect/payoutAdoption.d.ts.map +1 -1
  9. package/dist/client/connect/payoutAdoption.js +218 -183
  10. package/dist/client/connect/payoutAdoption.js.map +1 -1
  11. package/dist/client/connect/payoutAdoptionCollection.d.ts +21 -0
  12. package/dist/client/connect/payoutAdoptionCollection.d.ts.map +1 -0
  13. package/dist/client/connect/payoutAdoptionCollection.js +44 -0
  14. package/dist/client/connect/payoutAdoptionCollection.js.map +1 -0
  15. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +26 -6
  16. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  17. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +13 -3
  18. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  19. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +3745 -0
  20. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -0
  21. package/dist/client/connect/payoutLargeAdoptionTestHelpers.js +55 -0
  22. package/dist/client/connect/payoutLargeAdoptionTestHelpers.js.map +1 -0
  23. package/dist/client/connect/payoutOutcomeBatches.d.ts +5 -0
  24. package/dist/client/connect/payoutOutcomeBatches.d.ts.map +1 -0
  25. package/dist/client/connect/payoutOutcomeBatches.js +21 -0
  26. package/dist/client/connect/payoutOutcomeBatches.js.map +1 -0
  27. package/dist/client/connect/payoutPolicyState.d.ts +14 -0
  28. package/dist/client/connect/payoutPolicyState.d.ts.map +1 -0
  29. package/dist/client/connect/payoutPolicyState.js +19 -0
  30. package/dist/client/connect/payoutPolicyState.js.map +1 -0
  31. package/dist/client/connect/payoutQualification.js +1 -1
  32. package/dist/client/connect/payoutQualification.js.map +1 -1
  33. package/dist/client/connect/payoutReconciliation.d.ts +11 -6
  34. package/dist/client/connect/payoutReconciliation.d.ts.map +1 -1
  35. package/dist/client/connect/payoutReconciliation.js +62 -16
  36. package/dist/client/connect/payoutReconciliation.js.map +1 -1
  37. package/dist/client/connect/payoutResumableProof.d.ts +17 -0
  38. package/dist/client/connect/payoutResumableProof.d.ts.map +1 -0
  39. package/dist/client/connect/payoutResumableProof.js +25 -0
  40. package/dist/client/connect/payoutResumableProof.js.map +1 -0
  41. package/dist/client/connect/payoutSyncTestHelpers.d.ts +13 -3
  42. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  43. package/dist/client/connect/transferReceipt.d.ts +6 -2
  44. package/dist/client/connect/transferReceipt.d.ts.map +1 -1
  45. package/dist/client/connect/transferReceipt.js +3 -3
  46. package/dist/client/connect/transferReceipt.js.map +1 -1
  47. package/dist/client/payoutPolicy.d.ts.map +1 -1
  48. package/dist/client/payoutPolicy.js +24 -14
  49. package/dist/client/payoutPolicy.js.map +1 -1
  50. package/dist/component/_generated/component.d.ts +72 -0
  51. package/dist/component/_generated/component.d.ts.map +1 -1
  52. package/dist/component/earnings/triggers.d.ts +12 -4
  53. package/dist/component/earnings/triggers.d.ts.map +1 -1
  54. package/dist/component/payoutPolicy/adoption.d.ts.map +1 -1
  55. package/dist/component/payoutPolicy/adoption.js +12 -7
  56. package/dist/component/payoutPolicy/adoption.js.map +1 -1
  57. package/dist/component/payoutPolicy/mutations.d.ts +12 -0
  58. package/dist/component/payoutPolicy/mutations.d.ts.map +1 -1
  59. package/dist/component/payoutPolicy/queries.d.ts +2 -0
  60. package/dist/component/payoutPolicy/queries.d.ts.map +1 -1
  61. package/dist/component/payoutPolicy/schema.d.ts +31 -7
  62. package/dist/component/payoutPolicy/schema.d.ts.map +1 -1
  63. package/dist/component/payoutPolicy/schema.js +2 -0
  64. package/dist/component/payoutPolicy/schema.js.map +1 -1
  65. package/dist/component/payoutRelease/adoption.d.ts +3 -1
  66. package/dist/component/payoutRelease/adoption.d.ts.map +1 -1
  67. package/dist/component/payoutRelease/adoption.js +33 -16
  68. package/dist/component/payoutRelease/adoption.js.map +1 -1
  69. package/dist/component/payoutRelease/fees.d.ts.map +1 -1
  70. package/dist/component/payoutRelease/fees.js +7 -0
  71. package/dist/component/payoutRelease/fees.js.map +1 -1
  72. package/dist/component/payoutRelease/mutations.d.ts +59 -0
  73. package/dist/component/payoutRelease/mutations.d.ts.map +1 -1
  74. package/dist/component/payoutRelease/mutations.js +25 -80
  75. package/dist/component/payoutRelease/mutations.js.map +1 -1
  76. package/dist/component/payoutRelease/outcome.d.ts +69 -0
  77. package/dist/component/payoutRelease/outcome.d.ts.map +1 -0
  78. package/dist/component/payoutRelease/outcome.js +94 -0
  79. package/dist/component/payoutRelease/outcome.js.map +1 -0
  80. package/dist/component/payoutRelease/planning.d.ts.map +1 -1
  81. package/dist/component/payoutRelease/planning.js +5 -2
  82. package/dist/component/payoutRelease/planning.js.map +1 -1
  83. package/dist/component/payoutRelease/queries.d.ts +2 -2
  84. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  85. package/dist/component/payoutRelease/queries.js +2 -0
  86. package/dist/component/payoutRelease/queries.js.map +1 -1
  87. package/dist/component/payoutSnapshots/adoption.d.ts +88 -0
  88. package/dist/component/payoutSnapshots/adoption.d.ts.map +1 -0
  89. package/dist/component/payoutSnapshots/adoption.js +49 -0
  90. package/dist/component/payoutSnapshots/adoption.js.map +1 -0
  91. package/dist/component/payoutSnapshots/financial.d.ts +31 -19
  92. package/dist/component/payoutSnapshots/financial.d.ts.map +1 -1
  93. package/dist/component/payoutSnapshots/financial.js +28 -14
  94. package/dist/component/payoutSnapshots/financial.js.map +1 -1
  95. package/dist/component/payoutSnapshots/localState.d.ts +20 -16
  96. package/dist/component/payoutSnapshots/localState.d.ts.map +1 -1
  97. package/dist/component/payoutSnapshots/localState.js +13 -4
  98. package/dist/component/payoutSnapshots/localState.js.map +1 -1
  99. package/dist/component/payoutSnapshots/mutations.d.ts.map +1 -1
  100. package/dist/component/payoutSnapshots/mutations.js +1 -1
  101. package/dist/component/payoutSnapshots/mutations.js.map +1 -1
  102. package/dist/component/payoutSnapshots/queries.d.ts.map +1 -1
  103. package/dist/component/payoutSnapshots/queries.js +6 -4
  104. package/dist/component/payoutSnapshots/queries.js.map +1 -1
  105. package/dist/component/payoutSnapshots/schema.d.ts +5 -1
  106. package/dist/component/payoutSnapshots/schema.d.ts.map +1 -1
  107. package/dist/component/payoutSnapshots/schema.js +2 -0
  108. package/dist/component/payoutSnapshots/schema.js.map +1 -1
  109. package/dist/component/schema.d.ts +13 -3
  110. package/dist/react/index.d.ts +1 -0
  111. package/dist/react/index.d.ts.map +1 -1
  112. package/dist/react/index.js +1 -0
  113. package/dist/react/index.js.map +1 -1
  114. package/dist/react/lib/payout-format.d.ts +5 -0
  115. package/dist/react/lib/payout-format.d.ts.map +1 -0
  116. package/dist/react/lib/payout-format.js +13 -0
  117. package/dist/react/lib/payout-format.js.map +1 -0
  118. package/dist/react/workflows/Payouts.js +4 -4
  119. package/dist/react/workflows/Payouts.js.map +1 -1
  120. package/docs/react-workflows.md +9 -4
  121. package/docs/settlement.md +61 -8
  122. package/package.json +1 -1
  123. package/src/client/connect/payoutActivationProof.ts +123 -53
  124. package/src/client/connect/payoutAdoption.ts +299 -215
  125. package/src/client/connect/payoutAdoptionCollection.ts +78 -0
  126. package/src/client/connect/payoutAdoptionConcurrency.test.ts +266 -0
  127. package/src/client/connect/payoutCacheIdentity.test.ts +93 -0
  128. package/src/client/connect/payoutLargeAdoption.test.ts +541 -0
  129. package/src/client/connect/payoutLargeAdoptionTestHelpers.ts +74 -0
  130. package/src/client/connect/payoutOutcomeBatches.test.ts +40 -0
  131. package/src/client/connect/payoutOutcomeBatches.ts +24 -0
  132. package/src/client/connect/payoutPolicyState.ts +36 -0
  133. package/src/client/connect/payoutQualification.ts +10 -4
  134. package/src/client/connect/payoutReconciliation.ts +86 -7
  135. package/src/client/connect/payoutResumableProof.ts +41 -0
  136. package/src/client/connect/transferReceipt.ts +3 -2
  137. package/src/client/connect/transferReceiptBaseline.test.ts +55 -0
  138. package/src/client/payoutPolicy.ts +37 -23
  139. package/src/component/_generated/api.ts +4 -0
  140. package/src/component/_generated/component.ts +85 -0
  141. package/src/component/payout-snapshots.test.ts +45 -1
  142. package/src/component/payoutPolicy/adoption.ts +20 -7
  143. package/src/component/payoutPolicy/schema.ts +2 -0
  144. package/src/component/payoutRelease/adoption.ts +57 -27
  145. package/src/component/payoutRelease/fees.ts +9 -0
  146. package/src/component/payoutRelease/mutations.ts +26 -96
  147. package/src/component/payoutRelease/outcome.ts +119 -0
  148. package/src/component/payoutRelease/planning.ts +5 -2
  149. package/src/component/payoutRelease/queries.ts +2 -0
  150. package/src/component/payoutSnapshots/adoption.ts +73 -0
  151. package/src/component/payoutSnapshots/financial.ts +33 -20
  152. package/src/component/payoutSnapshots/localState.ts +17 -3
  153. package/src/component/payoutSnapshots/mutations.ts +8 -1
  154. package/src/component/payoutSnapshots/queries.ts +8 -6
  155. package/src/component/payoutSnapshots/schema.ts +2 -0
  156. package/src/react/index.ts +1 -0
  157. package/src/react/lib/payout-format.ts +16 -0
  158. package/src/react/workflows/Payouts.tsx +7 -5
@@ -44,23 +44,29 @@ export async function collectedSources(
44
44
  new Set(observations.map((o) => o.stripeTransferId)).size !== h.sourceCount
45
45
  )
46
46
  throw new Error("Financial payout collection membership is incomplete.");
47
+ const cachedRows = await ctx.db
48
+ .query("payoutSnapshotSources")
49
+ .withIndex("by_snapshot", (q) => q.eq("snapshotId", h._id))
50
+ .take(h.sourceCount + 1);
51
+ const byId = new Map(cachedRows.map((row) => [row.stripeTransferId, row]));
52
+ if (cachedRows.length !== h.sourceCount || byId.size !== h.sourceCount)
53
+ throw new Error("Financial payout collection membership is incomplete.");
47
54
  const rows = new Map<string, Doc<"transfers">>();
55
+ const allocations = new Map<string, Doc<"payoutSourceAllocations"> | null>();
48
56
  for (const o of observations) {
49
- const cached = await ctx.db
50
- .query("payoutSnapshotSources")
51
- .withIndex("by_snapshot_transfer", (q) =>
52
- q.eq("snapshotId", h._id).eq("stripeTransferId", o.stripeTransferId),
53
- )
54
- .unique();
55
- const row = await ctx.db
56
- .query("transfers")
57
- .withIndex("by_stripe_transfer_id", (q) =>
58
- q.eq("stripeTransferId", o.stripeTransferId),
59
- )
60
- .unique();
57
+ const cached = byId.get(o.stripeTransferId);
58
+ const row = cached?.transferDocId
59
+ ? await ctx.db.get("transfers", cached.transferDocId)
60
+ : await ctx.db
61
+ .query("transfers")
62
+ .withIndex("by_stripe_transfer_id", (q) =>
63
+ q.eq("stripeTransferId", o.stripeTransferId),
64
+ )
65
+ .unique();
61
66
  if (
62
67
  !cached ||
63
68
  !row ||
69
+ row.stripeTransferId !== o.stripeTransferId ||
64
70
  cached.needsCheck ||
65
71
  cached.ledgerFingerprint !== o.ledgerFingerprint ||
66
72
  cached.expectedPaid !== cached.paidAmount ||
@@ -68,25 +74,32 @@ export async function collectedSources(
68
74
  )
69
75
  throw new Error("Financial payout collection source changed.");
70
76
  if (h.readOnly) {
71
- const allocation = await ctx.db
72
- .query("payoutSourceAllocations")
73
- .withIndex("by_transfer", (q) =>
74
- q.eq("stripeTransferId", o.stripeTransferId),
75
- )
76
- .unique();
77
+ const knownAllocation = cached.allocationDocId
78
+ ? await ctx.db.get("payoutSourceAllocations", cached.allocationDocId)
79
+ : null;
80
+ const allocation =
81
+ knownAllocation ??
82
+ (await ctx.db
83
+ .query("payoutSourceAllocations")
84
+ .withIndex("by_transfer", (q) =>
85
+ q.eq("stripeTransferId", o.stripeTransferId),
86
+ )
87
+ .unique());
77
88
  if (
78
89
  (allocation?.paidAmount ?? 0) !== cached.paidAmount ||
79
90
  (allocation?.reservedAmount ?? 0) !== cached.reservedAmount ||
80
91
  (allocation &&
81
- (allocation.accountId !== scope.accountId ||
92
+ (allocation.stripeTransferId !== o.stripeTransferId ||
93
+ allocation.accountId !== scope.accountId ||
82
94
  allocation.ownerKey !== scope.ownerKey ||
83
95
  allocation.currency !== o.currency))
84
96
  )
85
97
  throw new Error("Financial payout collection allocation changed.");
98
+ allocations.set(o.stripeTransferId, allocation);
86
99
  }
87
100
  rows.set(o.stripeTransferId, row);
88
101
  }
89
- return rows;
102
+ return { transfers: rows, allocations };
90
103
  }
91
104
  export async function bindCollection(
92
105
  ctx: MutationCtx,
@@ -53,9 +53,14 @@ export async function cacheSource(
53
53
  id: string,
54
54
  counts: Counts,
55
55
  provided?: Doc<"transfers">,
56
+ providedAllocation?: Doc<"payoutSourceAllocations">,
56
57
  ) {
58
+ const old = await sourceCache(ctx, h, id);
57
59
  const row =
58
60
  provided ??
61
+ (old?.transferDocId
62
+ ? await ctx.db.get("transfers", old.transferDocId)
63
+ : null) ??
59
64
  (await ctx.db
60
65
  .query("transfers")
61
66
  .withIndex("by_stripe_transfer_id", (q) => q.eq("stripeTransferId", id))
@@ -67,17 +72,20 @@ export async function cacheSource(
67
72
  amount(row.amount);
68
73
  amount(row.reversedAmount ?? 0);
69
74
  amount(row.reversalClaimedAmount ?? 0);
70
- const allocated = await sourceById(ctx, id);
75
+ const allocated = providedAllocation ?? (await sourceById(ctx, id));
71
76
  if (
72
77
  allocated &&
73
- (allocated.accountId !== h.accountId || allocated.ownerKey !== h.ownerKey)
78
+ (allocated.stripeTransferId !== id ||
79
+ allocated.accountId !== h.accountId ||
80
+ allocated.ownerKey !== h.ownerKey)
74
81
  )
75
82
  throw new CollectionError("allocation_identity_changed");
76
- const old = await sourceCache(ctx, h, id);
77
83
  const allocationPresent = allocated !== null;
78
84
  const fields = {
79
85
  stripeTransferId: id,
80
86
  ledgerFingerprint: transferFingerprint(row),
87
+ transferDocId: row._id,
88
+ allocationDocId: allocated?._id,
81
89
  sourceCreatedAt: row._creationTime,
82
90
  currency: row.currency,
83
91
  amount: row.amount,
@@ -98,6 +106,12 @@ export async function cacheSource(
98
106
  throw new CollectionError("allocation_removed");
99
107
  if (!old.allocationPresent && allocationPresent)
100
108
  counts.allocationCount = add(counts.allocationCount, 1);
109
+ if (
110
+ Object.entries(fields).every(
111
+ ([key, value]) => old[key as keyof typeof fields] === value,
112
+ )
113
+ )
114
+ return old;
101
115
  await ctx.db.patch("payoutSnapshotSources", old._id, fields);
102
116
  return { ...old, ...fields };
103
117
  }
@@ -139,7 +139,14 @@ export const advance = mutation({
139
139
  .withIndex("by_account", (q) => q.eq("accountId", h!.accountId))
140
140
  .paginate({ cursor: h.allocationCursor ?? null, numItems: batch });
141
141
  for (const row of page.page)
142
- await cacheSource(ctx, h, row.stripeTransferId, counts);
142
+ await cacheSource(
143
+ ctx,
144
+ h,
145
+ row.stripeTransferId,
146
+ counts,
147
+ undefined,
148
+ row,
149
+ );
143
150
  patch.allocationCursor = page.continueCursor;
144
151
  patch.phase = page.isDone ? "fees" : "allocations";
145
152
  } else if (h.phase === "fees") {
@@ -47,12 +47,14 @@ export const sources = query({
47
47
  .paginate(args.paginationOpts);
48
48
  const rows = [];
49
49
  for (const cached of page.page) {
50
- const row = await ctx.db
51
- .query("transfers")
52
- .withIndex("by_stripe_transfer_id", (q) =>
53
- q.eq("stripeTransferId", cached.stripeTransferId),
54
- )
55
- .unique();
50
+ const row = cached.transferDocId
51
+ ? await ctx.db.get("transfers", cached.transferDocId)
52
+ : await ctx.db
53
+ .query("transfers")
54
+ .withIndex("by_stripe_transfer_id", (q) =>
55
+ q.eq("stripeTransferId", cached.stripeTransferId),
56
+ )
57
+ .unique();
56
58
  if (!row || transferFingerprint(row) !== cached.ledgerFingerprint)
57
59
  throw new Error("Payout collection source changed.");
58
60
  rows.push(row);
@@ -74,6 +74,8 @@ export const snapshotSourcesTable = defineTable({
74
74
  snapshotId: v.id("payoutSnapshots"),
75
75
  stripeTransferId: v.string(),
76
76
  ledgerFingerprint: v.string(),
77
+ transferDocId: v.optional(v.id("transfers")),
78
+ allocationDocId: v.optional(v.id("payoutSourceAllocations")),
77
79
  sourceCreatedAt: v.number(),
78
80
  currency: v.string(),
79
81
  amount: v.number(),
@@ -295,6 +295,7 @@ export { SaveCard } from "./workflows/SaveCard.js";
295
295
  export type { SaveCardProps, SaveCardFormState } from "./workflows/SaveCard.js";
296
296
 
297
297
  export { createUseCurrencyEarnings } from "./hooks/useCurrencyEarnings.js";
298
+ export { formatPayoutAmount } from "./lib/payout-format.js";
298
299
  export type {
299
300
  CurrencyEarningsTotal,
300
301
  CurrencyPayoutTotal,
@@ -0,0 +1,16 @@
1
+ import { formatPrice } from "./price-helpers.js";
2
+
3
+ /** Display observed ordinary Stripe balances without implying payout eligibility.
4
+ * Unknown precision remains explicit raw units rather than guessing a divisor.
5
+ */
6
+ export function formatPayoutAmount(
7
+ amount: number,
8
+ currency: string,
9
+ locale = "en-US",
10
+ ): string {
11
+ try {
12
+ return formatPrice(amount, currency, locale);
13
+ } catch {
14
+ return `${currency.toUpperCase()} ${amount} minor units (display unavailable)`;
15
+ }
16
+ }
@@ -12,7 +12,7 @@ import {
12
12
  type CollectionProps,
13
13
  type WorkflowColumn,
14
14
  } from "./Collection.js";
15
- import { formatPrice } from "../lib/price-helpers.js";
15
+ import { formatPayoutAmount } from "../lib/payout-format.js";
16
16
  export type PayoutRow = RecipientPayoutRow;
17
17
  export type PayoutSnapshot = Pick<
18
18
  RecipientPayoutSnapshot,
@@ -130,7 +130,7 @@ export function PayoutHistory<Row extends PayoutHistoryRow>(
130
130
  id: "amount",
131
131
  label: "Amount",
132
132
  align: "end",
133
- cell: (row) => formatPrice(row.amount, row.currency),
133
+ cell: (row) => formatPayoutAmount(row.amount, row.currency),
134
134
  },
135
135
  { id: "status", label: "Status", cell: (row) => row.status },
136
136
  {
@@ -176,15 +176,17 @@ function NativePayouts({
176
176
  {data.balances.map((balance) => (
177
177
  <div key={balance.currency}>
178
178
  <dt>Available</dt>
179
- <dd>{formatPrice(balance.available, balance.currency)}</dd>
179
+ <dd>
180
+ {formatPayoutAmount(balance.available, balance.currency)}
181
+ </dd>
180
182
  <dt>Pending</dt>
181
- <dd>{formatPrice(balance.pending, balance.currency)}</dd>
183
+ <dd>{formatPayoutAmount(balance.pending, balance.currency)}</dd>
182
184
  </div>
183
185
  ))}
184
186
  <dt>Next payout</dt>
185
187
  <dd>
186
188
  {nextPayout
187
- ? `${formatPrice(nextPayout.amount, nextPayout.currency)} · ${date(nextPayout.arrivalDate)}`
189
+ ? `${formatPayoutAmount(nextPayout.amount, nextPayout.currency)} · ${date(nextPayout.arrivalDate)}`
188
190
  : "Not scheduled"}
189
191
  </dd>
190
192
  </dl>