@fantastic.dev/better-stripe 0.59.0 → 0.60.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 (230) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +5 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +676 -50
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +322 -9
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +644 -18
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +338 -25
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/index.d.ts +4 -0
  12. package/dist/client/index.d.ts.map +1 -1
  13. package/dist/client/paymentSource/resolver.d.ts +12 -1
  14. package/dist/client/paymentSource/resolver.d.ts.map +1 -1
  15. package/dist/client/paymentSource/resolver.fixtures.d.ts +220 -0
  16. package/dist/client/paymentSource/resolver.fixtures.d.ts.map +1 -0
  17. package/dist/client/paymentSource/resolver.fixtures.js +189 -0
  18. package/dist/client/paymentSource/resolver.fixtures.js.map +1 -0
  19. package/dist/client/paymentSource/resolver.js +28 -3
  20. package/dist/client/paymentSource/resolver.js.map +1 -1
  21. package/dist/client/settlement/execution.d.ts +25 -0
  22. package/dist/client/settlement/execution.d.ts.map +1 -1
  23. package/dist/client/settlement/execution.js +2 -0
  24. package/dist/client/settlement/execution.js.map +1 -1
  25. package/dist/client/usage/catalogPrices.d.ts +1 -1
  26. package/dist/client/usage/catalogPrices.d.ts.map +1 -1
  27. package/dist/client/usage/catalogPrices.js +4 -4
  28. package/dist/client/usage/catalogPrices.js.map +1 -1
  29. package/dist/client/usage/client.d.ts +2 -2
  30. package/dist/client/usage/client.js +2 -2
  31. package/dist/client/usage/creditCapacity.d.ts.map +1 -1
  32. package/dist/client/usage/creditCapacity.js +7 -1
  33. package/dist/client/usage/creditCapacity.js.map +1 -1
  34. package/dist/client/usage/creditClient.d.ts +3 -0
  35. package/dist/client/usage/creditClient.d.ts.map +1 -1
  36. package/dist/client/usage/creditDelivery.d.ts.map +1 -1
  37. package/dist/client/usage/creditDelivery.js +4 -1
  38. package/dist/client/usage/creditDelivery.js.map +1 -1
  39. package/dist/client/usage/creditLifecycle.d.ts.map +1 -1
  40. package/dist/client/usage/creditLifecycle.js +2 -1
  41. package/dist/client/usage/creditLifecycle.js.map +1 -1
  42. package/dist/client/usage/creditNative.d.ts +3 -0
  43. package/dist/client/usage/creditNative.d.ts.map +1 -1
  44. package/dist/client/usage/creditNative.js +3 -0
  45. package/dist/client/usage/creditNative.js.map +1 -1
  46. package/dist/client/usage/creditProvider.d.ts.map +1 -1
  47. package/dist/client/usage/creditProvider.js +2 -1
  48. package/dist/client/usage/creditProvider.js.map +1 -1
  49. package/dist/client/usage/creditRead.d.ts +1 -0
  50. package/dist/client/usage/creditRead.d.ts.map +1 -1
  51. package/dist/client/usage/creditReconciliation.d.ts.map +1 -1
  52. package/dist/client/usage/creditReconciliation.js +11 -3
  53. package/dist/client/usage/creditReconciliation.js.map +1 -1
  54. package/dist/client/usage/creditRevenue.d.ts +22 -0
  55. package/dist/client/usage/creditRevenue.d.ts.map +1 -0
  56. package/dist/client/usage/creditRevenue.js +118 -0
  57. package/dist/client/usage/creditRevenue.js.map +1 -0
  58. package/dist/client/usage/creditSettlement.d.ts +29 -0
  59. package/dist/client/usage/creditSettlement.d.ts.map +1 -0
  60. package/dist/client/usage/creditSettlement.fixtures.d.ts +216 -0
  61. package/dist/client/usage/creditSettlement.fixtures.d.ts.map +1 -0
  62. package/dist/client/usage/creditSettlement.fixtures.js +59 -0
  63. package/dist/client/usage/creditSettlement.fixtures.js.map +1 -0
  64. package/dist/client/usage/creditSettlement.js +70 -0
  65. package/dist/client/usage/creditSettlement.js.map +1 -0
  66. package/dist/client/usage/creditTransport.fixtures.d.ts +8 -1
  67. package/dist/client/usage/creditTransport.fixtures.d.ts.map +1 -1
  68. package/dist/client/usage/creditTransport.fixtures.js +27 -5
  69. package/dist/client/usage/creditTransport.fixtures.js.map +1 -1
  70. package/dist/client/usage/index.d.ts +4 -0
  71. package/dist/client/usage/index.d.ts.map +1 -1
  72. package/dist/client/usage/invoiceSale.d.ts +22 -0
  73. package/dist/client/usage/invoiceSale.d.ts.map +1 -0
  74. package/dist/client/usage/invoiceSale.fixtures.d.ts +285 -0
  75. package/dist/client/usage/invoiceSale.fixtures.d.ts.map +1 -0
  76. package/dist/client/usage/invoiceSale.fixtures.js +104 -0
  77. package/dist/client/usage/invoiceSale.fixtures.js.map +1 -0
  78. package/dist/client/usage/invoiceSale.js +117 -0
  79. package/dist/client/usage/invoiceSale.js.map +1 -0
  80. package/dist/client/usage/observationClient.d.ts +2 -2
  81. package/dist/client/usage/observationClient.d.ts.map +1 -1
  82. package/dist/client/usage/settlement.d.ts +32 -0
  83. package/dist/client/usage/settlement.d.ts.map +1 -0
  84. package/dist/client/usage/settlement.js +60 -0
  85. package/dist/client/usage/settlement.js.map +1 -0
  86. package/dist/client/usage/settlementClient.d.ts +51 -0
  87. package/dist/client/usage/settlementClient.d.ts.map +1 -0
  88. package/dist/client/usage/settlementClient.js +35 -0
  89. package/dist/client/usage/settlementClient.js.map +1 -0
  90. package/dist/client/usage/subscriptionCancellation.d.ts.map +1 -1
  91. package/dist/client/usage/subscriptionCancellation.js +3 -2
  92. package/dist/client/usage/subscriptionCancellation.js.map +1 -1
  93. package/dist/client/usage/subscriptionCheckout.d.ts.map +1 -1
  94. package/dist/client/usage/subscriptionCheckout.js +3 -2
  95. package/dist/client/usage/subscriptionCheckout.js.map +1 -1
  96. package/dist/client/usage/subscriptionLifecycle.d.ts +1 -0
  97. package/dist/client/usage/subscriptionLifecycle.d.ts.map +1 -1
  98. package/dist/client/usage/subscriptionLifecycle.js +3 -2
  99. package/dist/client/usage/subscriptionLifecycle.js.map +1 -1
  100. package/dist/client/usage/subscriptionProvider.d.ts +2 -0
  101. package/dist/client/usage/subscriptionProvider.d.ts.map +1 -1
  102. package/dist/client/usage/subscriptionProvider.js +9 -2
  103. package/dist/client/usage/subscriptionProvider.js.map +1 -1
  104. package/dist/component/_generated/component.d.ts +146 -0
  105. package/dist/component/_generated/component.d.ts.map +1 -1
  106. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  107. package/dist/component/balanceFunding/mutations.d.ts +27 -27
  108. package/dist/component/earnings/triggers.d.ts +172 -12
  109. package/dist/component/earnings/triggers.d.ts.map +1 -1
  110. package/dist/component/financialObservations/settlementHelpers.d.ts.map +1 -1
  111. package/dist/component/financialObservations/settlementHelpers.js +2 -0
  112. package/dist/component/financialObservations/settlementHelpers.js.map +1 -1
  113. package/dist/component/recoveryWorkflow/helpers.d.ts +25 -0
  114. package/dist/component/recoveryWorkflow/helpers.d.ts.map +1 -1
  115. package/dist/component/recoveryWorkflow/mutations.d.ts +25 -0
  116. package/dist/component/recoveryWorkflow/mutations.d.ts.map +1 -1
  117. package/dist/component/recoveryWorkflow/queries.d.ts +50 -0
  118. package/dist/component/recoveryWorkflow/queries.d.ts.map +1 -1
  119. package/dist/component/recoveryWorkflow/schema.d.ts +566 -10
  120. package/dist/component/recoveryWorkflow/schema.d.ts.map +1 -1
  121. package/dist/component/schema.d.ts +322 -9
  122. package/dist/component/settlement/mutations.d.ts +50 -0
  123. package/dist/component/settlement/mutations.d.ts.map +1 -1
  124. package/dist/component/settlement/mutations.js +8 -1
  125. package/dist/component/settlement/mutations.js.map +1 -1
  126. package/dist/component/settlement/queries.d.ts +25 -0
  127. package/dist/component/settlement/queries.d.ts.map +1 -1
  128. package/dist/component/settlement/schema.d.ts +128 -1
  129. package/dist/component/settlement/schema.d.ts.map +1 -1
  130. package/dist/component/settlement/schema.js +22 -0
  131. package/dist/component/settlement/schema.js.map +1 -1
  132. package/dist/component/usage/allowance.fixtures.d.ts +4212 -0
  133. package/dist/component/usage/allowance.fixtures.d.ts.map +1 -0
  134. package/dist/component/usage/allowance.fixtures.js +67 -0
  135. package/dist/component/usage/allowance.fixtures.js.map +1 -0
  136. package/dist/component/usageCredits/accounting.fixtures.d.ts +4235 -0
  137. package/dist/component/usageCredits/accounting.fixtures.d.ts.map +1 -0
  138. package/dist/component/usageCredits/accounting.fixtures.js +89 -0
  139. package/dist/component/usageCredits/accounting.fixtures.js.map +1 -0
  140. package/dist/component/usageCredits/helpers.d.ts +7 -0
  141. package/dist/component/usageCredits/helpers.d.ts.map +1 -1
  142. package/dist/component/usageCredits/helpers.js +5 -0
  143. package/dist/component/usageCredits/helpers.js.map +1 -1
  144. package/dist/component/usageCredits/mutations.d.ts +6 -0
  145. package/dist/component/usageCredits/mutations.d.ts.map +1 -1
  146. package/dist/component/usageCredits/mutations.js +70 -7
  147. package/dist/component/usageCredits/mutations.js.map +1 -1
  148. package/dist/component/usageCredits/purchase.d.ts +1 -0
  149. package/dist/component/usageCredits/purchase.d.ts.map +1 -1
  150. package/dist/component/usageCredits/queries.d.ts +10 -0
  151. package/dist/component/usageCredits/queries.d.ts.map +1 -1
  152. package/dist/component/usageCredits/schema.d.ts +24 -4
  153. package/dist/component/usageCredits/schema.d.ts.map +1 -1
  154. package/dist/component/usageCredits/schema.js +4 -0
  155. package/dist/component/usageCredits/schema.js.map +1 -1
  156. package/dist/component/usageSubscriptions/history.d.ts.map +1 -1
  157. package/dist/component/usageSubscriptions/history.js +3 -1
  158. package/dist/component/usageSubscriptions/history.js.map +1 -1
  159. package/dist/component/usageSubscriptions/mutations.d.ts +5 -0
  160. package/dist/component/usageSubscriptions/mutations.d.ts.map +1 -1
  161. package/dist/component/usageSubscriptions/mutations.js +19 -0
  162. package/dist/component/usageSubscriptions/mutations.js.map +1 -1
  163. package/dist/component/usageSubscriptions/queries.d.ts +2 -0
  164. package/dist/component/usageSubscriptions/queries.d.ts.map +1 -1
  165. package/dist/component/usageSubscriptions/schema.d.ts +7 -2
  166. package/dist/component/usageSubscriptions/schema.d.ts.map +1 -1
  167. package/dist/component/usageSubscriptions/schema.js +1 -0
  168. package/dist/component/usageSubscriptions/schema.js.map +1 -1
  169. package/docs/README.md +4 -0
  170. package/docs/settlement.md +4 -0
  171. package/docs/usage-credits.md +6 -1
  172. package/docs/usage-security.md +130 -0
  173. package/docs/usage-settlement.md +162 -0
  174. package/package.json +3 -1
  175. package/src/client/index.ts +9 -0
  176. package/src/client/paymentSource/resolver.fixtures.ts +216 -0
  177. package/src/client/paymentSource/resolver.test.ts +11 -207
  178. package/src/client/paymentSource/resolver.ts +54 -2
  179. package/src/client/settlement/execution.ts +24 -0
  180. package/src/client/usage/catalogPrices.ts +4 -2
  181. package/src/client/usage/client.ts +2 -2
  182. package/src/client/usage/creditBackingIsolation.test.ts +110 -0
  183. package/src/client/usage/creditCapacity.test.ts +80 -1
  184. package/src/client/usage/creditCapacity.ts +10 -1
  185. package/src/client/usage/creditDelivery.ts +4 -0
  186. package/src/client/usage/creditLifecycle.ts +2 -0
  187. package/src/client/usage/creditNative.ts +5 -0
  188. package/src/client/usage/creditProofBounds.test.ts +187 -0
  189. package/src/client/usage/creditProvider.test.ts +74 -0
  190. package/src/client/usage/creditProvider.ts +2 -0
  191. package/src/client/usage/creditReconciliation.ts +18 -3
  192. package/src/client/usage/creditRevenue.test.ts +105 -0
  193. package/src/client/usage/creditRevenue.ts +163 -0
  194. package/src/client/usage/creditSettlement.fixtures.ts +70 -0
  195. package/src/client/usage/creditSettlement.test.ts +66 -0
  196. package/src/client/usage/creditSettlement.ts +94 -0
  197. package/src/client/usage/creditSettlementRecovery.test.ts +173 -0
  198. package/src/client/usage/creditTransport.fixtures.ts +31 -5
  199. package/src/client/usage/index.ts +9 -0
  200. package/src/client/usage/invoiceSale.fixtures.ts +103 -0
  201. package/src/client/usage/invoiceSale.test.ts +184 -0
  202. package/src/client/usage/invoiceSale.ts +155 -0
  203. package/src/client/usage/settlement.test.ts +179 -0
  204. package/src/client/usage/settlement.ts +81 -0
  205. package/src/client/usage/settlementClient.ts +84 -0
  206. package/src/client/usage/subscriptionCancellation.ts +3 -2
  207. package/src/client/usage/subscriptionCheckout.ts +7 -2
  208. package/src/client/usage/subscriptionClient.test.ts +60 -1
  209. package/src/client/usage/subscriptionLifecycle.ts +3 -2
  210. package/src/client/usage/subscriptionProvider.ts +27 -3
  211. package/src/component/_generated/component.ts +150 -1
  212. package/src/component/financialObservations/settlementHelpers.ts +2 -0
  213. package/src/component/settlement/mutations.ts +10 -1
  214. package/src/component/settlement/schema.ts +26 -0
  215. package/src/component/settlement/settlement-claims.test.ts +54 -0
  216. package/src/component/usage/allowance.fixtures.ts +77 -0
  217. package/src/component/usage/allowance.test.ts +3 -66
  218. package/src/component/usage/allowanceBounds.test.ts +79 -0
  219. package/src/component/usage/historyIsolation.test.ts +124 -0
  220. package/src/component/usageCredits/accounting.fixtures.ts +96 -0
  221. package/src/component/usageCredits/accounting.test.ts +176 -82
  222. package/src/component/usageCredits/freshness.test.ts +33 -0
  223. package/src/component/usageCredits/helpers.ts +8 -0
  224. package/src/component/usageCredits/mutations.ts +83 -5
  225. package/src/component/usageCredits/quotas.test.ts +63 -0
  226. package/src/component/usageCredits/schema.ts +10 -0
  227. package/src/component/usageSubscriptions/history.test.ts +57 -0
  228. package/src/component/usageSubscriptions/history.ts +3 -1
  229. package/src/component/usageSubscriptions/mutations.ts +23 -0
  230. package/src/component/usageSubscriptions/schema.ts +1 -0
@@ -200,3 +200,77 @@ it("cancels an unpaid original purchase and never recreates its payment intent",
200
200
  ),
201
201
  ).toHaveLength(1);
202
202
  });
203
+
204
+ it("rejects captured credit purchases whose payment or charge uses a foreign mapped Customer", async () => {
205
+ for (const field of ["paymentCustomer", "chargeCustomer"] as const) {
206
+ const f = creditFixture();
207
+ await f.ready();
208
+ await f.t.action((ctx) =>
209
+ ensureCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
210
+ );
211
+ f.state.paid = true;
212
+ f.state[field] = "cus_other";
213
+ await expect(
214
+ f.t.action((ctx) =>
215
+ observeCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
216
+ ),
217
+ ).rejects.toThrow(/scope|identity|verified/i);
218
+ expect(
219
+ f.calls.filter(
220
+ (c) => c.path === "/v1/billing/credit_grants" && c.method === "POST",
221
+ ),
222
+ ).toHaveLength(0);
223
+ }
224
+ });
225
+
226
+ it("rejects adoption of a paid grant whose mapped Customer differs from its original payer binding", async () => {
227
+ const f = creditFixture();
228
+ await f.ready();
229
+ await f.t.action((ctx) =>
230
+ ensureCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
231
+ );
232
+ f.state.paid = true;
233
+ let failed = false;
234
+ await expect(
235
+ f.t.action((ctx) =>
236
+ observeCreditPurchase(
237
+ f.stripe,
238
+ f.component,
239
+ {
240
+ runQuery: ctx.runQuery,
241
+ runAction: ctx.runAction,
242
+ runMutation: async (
243
+ reference: Parameters<NonNullable<RunCtx["runMutation"]>>[0],
244
+ args: Record<string, unknown>,
245
+ ) => {
246
+ if (
247
+ String(
248
+ (reference as unknown as Record<symbol, string>)[
249
+ Symbol.for("toReferencePath")
250
+ ],
251
+ ).endsWith("/usageCredits/mutations/pinGrant") &&
252
+ !failed
253
+ ) {
254
+ failed = true;
255
+ throw new Error("simulated persistence failure");
256
+ }
257
+ return ctx.runMutation(reference, args);
258
+ },
259
+ } as RunCtx,
260
+ f.purchase,
261
+ ),
262
+ ),
263
+ ).rejects.toThrow();
264
+ expect(f.state.grant).toBeDefined();
265
+ f.state.grant!.customer = "cus_other";
266
+ await expect(
267
+ f.t.action((ctx) =>
268
+ observeCreditPurchase(f.stripe, f.component, ctx as RunCtx, f.purchase),
269
+ ),
270
+ ).rejects.toThrow(/grant|identity/i);
271
+ expect(
272
+ f.calls.filter(
273
+ (c) => c.path === "/v1/billing/credit_grants" && c.method === "POST",
274
+ ),
275
+ ).toHaveLength(1);
276
+ });
@@ -15,6 +15,7 @@ import { grantCreditProof } from "./creditProofs.js";
15
15
  import {
16
16
  creditCall,
17
17
  creditCreateWindow,
18
+ nativeCustomerId,
18
19
  creditRequire,
19
20
  discoverCredit,
20
21
  paymentIdentity,
@@ -191,6 +192,7 @@ function grantProof(
191
192
  creditRequire(
192
193
  grant.object === "billing.credit_grant" &&
193
194
  grant.customer_account === terms.scope.customerAccount &&
195
+ nativeCustomerId(grant.customer) === terms.binding.stripeCustomerId &&
194
196
  grant.livemode === terms.scope.livemode &&
195
197
  grant.metadata?.bsUsageCredit === key &&
196
198
  grant.category === "paid" &&
@@ -11,6 +11,7 @@ import {
11
11
  } from "./creditTerms.js";
12
12
  import {
13
13
  creditCall,
14
+ nativeCustomerId,
14
15
  creditRequire,
15
16
  verifyCreditRealm,
16
17
  paymentIdentity,
@@ -29,8 +30,7 @@ export async function reconcileCreditPurchase(
29
30
  input: UsageCreditPurchaseOptions,
30
31
  ) {
31
32
  return creditCall(async () => {
32
- const terms = creditPurchaseTerms(input),
33
- startedAt = Date.now();
33
+ const terms = creditPurchaseTerms(input);
34
34
  let source = await findCreditPurchase(component, ctx, input);
35
35
  if (!source.row.creditGrantId) {
36
36
  await observeCreditPurchase(stripe, component, ctx, input);
@@ -43,6 +43,12 @@ export async function reconcileCreditPurchase(
43
43
  reason: "credit_purchase_not_ready",
44
44
  retryable: true,
45
45
  };
46
+ const proofStartedAt = Date.now();
47
+ const startedAt = (await runMutationOrThrow(
48
+ ctx,
49
+ componentRef(component, "usageCredits/mutations/beginObservation"),
50
+ { inputJson: JSON.stringify(input) },
51
+ )) as number;
46
52
  await verifyCreditRealm(stripe, terms, false);
47
53
  const payment = await stripe.paymentIntents.retrieve(
48
54
  purchase.paymentIntentId,
@@ -76,6 +82,8 @@ export async function reconcileCreditPurchase(
76
82
  creditRequire(
77
83
  nativeGrant.id === purchase.creditGrantId &&
78
84
  nativeGrant.customer_account === terms.scope.customerAccount &&
85
+ nativeCustomerId(nativeGrant.customer) ===
86
+ terms.binding.stripeCustomerId &&
79
87
  nativeGrant.livemode === terms.scope.livemode &&
80
88
  nativeGrant.metadata?.bsUsageCredit === purchase.key &&
81
89
  nativeGrant.amount.monetary?.value === terms.amount &&
@@ -114,6 +122,12 @@ export async function reconcileCreditPurchase(
114
122
  available.currency === ledger.currency,
115
123
  "Native credit summary currency mismatch",
116
124
  );
125
+ creditRequire(
126
+ Array.isArray(transactions.data) &&
127
+ transactions.data.length <= 100 &&
128
+ typeof transactions.has_more === "boolean",
129
+ "Native credit transaction proof budget exceeded",
130
+ );
117
131
  let granted = 0,
118
132
  applied = 0,
119
133
  expired = 0,
@@ -200,12 +214,13 @@ export async function reconcileCreditPurchase(
200
214
  inputJson: JSON.stringify(input),
201
215
  proofJson: JSON.stringify(proof),
202
216
  startedAt,
217
+ proofStartedAt,
203
218
  },
204
219
  )) as string;
205
220
  const result = JSON.parse(resultJson) as UsageCreditReconciliation;
206
221
  return {
207
222
  status: "available" as const,
208
- observedAt: Math.floor(startedAt / 1000),
223
+ observedAt: Math.floor(proofStartedAt / 1000),
209
224
  value: result,
210
225
  };
211
226
  });
@@ -0,0 +1,105 @@
1
+ import { afterEach, expect, it, vi } from "vitest";
2
+ import { BetterStripe } from "../index.js";
3
+ import type { RunCtx } from "../helpers.js";
4
+ import { creditFixture } from "./creditTransport.fixtures.js";
5
+ afterEach(() => vi.useRealTimers());
6
+ it("recognizes only the original verified paid credit purchase, without creating a second sale as units are consumed", async () => {
7
+ const f = creditFixture(),
8
+ client = new BetterStripe(f.component),
9
+ options = { stripeSecretKey: "sk_test_credit", httpClient: f.httpClient };
10
+ const view = await f.ready();
11
+ await f.t.action((ctx) =>
12
+ client.usage.purchaseCredits(ctx as RunCtx, f.purchase, options),
13
+ );
14
+ f.state.paid = true;
15
+ await f.t.action((ctx) =>
16
+ client.usage.observeCreditPurchase(ctx as RunCtx, f.purchase, options),
17
+ );
18
+ const read = () =>
19
+ f.t.action((ctx) =>
20
+ client.usage.getCreditPurchaseRevenue(ctx as RunCtx, f.purchase, options),
21
+ );
22
+ const first = await read();
23
+ expect(first).toMatchObject({
24
+ status: "ready",
25
+ value: {
26
+ paymentIntentId: "pi_topup1",
27
+ chargeId: "ch_topup1",
28
+ creditGrantId: "credgr_topup1",
29
+ gross: 20,
30
+ processingFee: 1,
31
+ ownership: "issuer",
32
+ stripePriceId: "price_calls",
33
+ stripeProductId: "prod_calls",
34
+ },
35
+ });
36
+ const event = {
37
+ ...f.purchase,
38
+ sourceEventId: "consume1",
39
+ quantity: "6",
40
+ occurredAt: 700,
41
+ };
42
+ const {
43
+ ownership: _ownership,
44
+ purchaseId: _purchase,
45
+ rollover: _rollover,
46
+ ...usage
47
+ } = event;
48
+ const subscription = view.bindings[0].subscription;
49
+ const reservation = await f.t.action((ctx) =>
50
+ client.usage.reserveCredits(ctx as RunCtx, { event: usage, subscription }),
51
+ );
52
+ await f.t.action((ctx) =>
53
+ client.usage.record(ctx as RunCtx, {
54
+ event: usage,
55
+ subscription,
56
+ reservationId: reservation.reservationId,
57
+ }),
58
+ );
59
+ expect(await read()).toEqual(first);
60
+ f.state.refunded = true;
61
+ expect(await read()).toMatchObject({
62
+ status: "rejected",
63
+ reason: "payment_not_payable",
64
+ });
65
+ expect(
66
+ f.calls.filter(
67
+ (c) => c.path === "/v1/payment_intents" && c.method === "POST",
68
+ ),
69
+ ).toHaveLength(1);
70
+ });
71
+
72
+ it("holds foreign mapped native customers and missing processing fees", async () => {
73
+ for (const condition of [
74
+ "payment_customer",
75
+ "charge_customer",
76
+ "fee_pending",
77
+ "dispute",
78
+ ]) {
79
+ const f = creditFixture(),
80
+ client = new BetterStripe(f.component),
81
+ options = { stripeSecretKey: "sk_test_credit", httpClient: f.httpClient };
82
+ await f.ready();
83
+ await f.t.action((ctx) =>
84
+ client.usage.purchaseCredits(ctx as RunCtx, f.purchase, options),
85
+ );
86
+ f.state.paid = true;
87
+ await f.t.action((ctx) =>
88
+ client.usage.observeCreditPurchase(ctx as RunCtx, f.purchase, options),
89
+ );
90
+ if (condition === "payment_customer") f.state.paymentCustomer = "cus_other";
91
+ if (condition === "charge_customer") f.state.chargeCustomer = "cus_other";
92
+ if (condition === "fee_pending") f.state.feePending = true;
93
+ if (condition === "dispute") f.state.disputed = true;
94
+ const result = await f.t.action((ctx) =>
95
+ client.usage.getCreditPurchaseRevenue(ctx as RunCtx, f.purchase, options),
96
+ );
97
+ expect(result.status, condition).not.toBe("ready");
98
+ if (condition === "fee_pending")
99
+ expect(result).toMatchObject({
100
+ status: "not_ready",
101
+ reason: "fee_pending",
102
+ retryable: true,
103
+ });
104
+ }
105
+ });
@@ -0,0 +1,163 @@
1
+ import { verifyPinnedUsagePrice } from "./catalogPrices.js";
2
+ import type Stripe from "stripe";
3
+ import type { Component, RunCtx } from "../helpers.js";
4
+ import type { FinancialOutcome } from "../financialOutcomes/contracts.js";
5
+ import type { UsageCreditPurchaseOptions } from "./creditTerms.js";
6
+ import { UsageCreditRecoveryError } from "./creditTerms.js";
7
+ import { findCreditPurchase } from "./creditRead.js";
8
+ import {
9
+ verifyCreditRealm,
10
+ paymentIdentity,
11
+ verifiedCreditPayment,
12
+ } from "./creditNative.js";
13
+ import { paymentCreditProof } from "./creditProofs.js";
14
+ import { saleAmountFailure } from "../paymentSource/economics.js";
15
+ export type UsageCreditRevenue = {
16
+ purchaseId: string;
17
+ paymentIntentId: string;
18
+ chargeId: string;
19
+ creditGrantId: string;
20
+ stripeAccountId: string;
21
+ customerAccount: string;
22
+ livemode: boolean;
23
+ stripePriceId: string;
24
+ stripeProductId: string;
25
+ gross: number;
26
+ processingFee: number;
27
+ currency: string;
28
+ ownership: "issuer";
29
+ };
30
+ /** Original issuer-service revenue only. Credit consumption never creates a second sale. */
31
+ export async function getCreditPurchaseRevenue(
32
+ stripe: Stripe,
33
+ component: Component,
34
+ ctx: RunCtx,
35
+ input: UsageCreditPurchaseOptions,
36
+ ): Promise<FinancialOutcome<UsageCreditRevenue>> {
37
+ try {
38
+ const { row, terms } = await findCreditPurchase(component, ctx, input);
39
+ if (row.state === "frozen" || row.state === "canceled")
40
+ return {
41
+ status: "rejected",
42
+ reason: "payment_not_payable",
43
+ retryable: false,
44
+ };
45
+ if (
46
+ row.state !== "ready" ||
47
+ !row.paymentIntentId ||
48
+ !row.paymentProofJson ||
49
+ !row.creditGrantId
50
+ )
51
+ return {
52
+ status: "not_ready",
53
+ reason: "provider_pending",
54
+ retryable: true,
55
+ };
56
+ await verifyCreditRealm(stripe, terms, false);
57
+ const [payment, price] = await Promise.all([
58
+ stripe.paymentIntents.retrieve(row.paymentIntentId, {
59
+ expand: ["latest_charge.balance_transaction"],
60
+ }),
61
+ stripe.prices.retrieve(terms.binding.stripePriceId, {
62
+ expand: ["tiers"],
63
+ }),
64
+ ]);
65
+ paymentIdentity(payment, terms, row.key, row.paymentIntentId);
66
+ const proof = verifiedCreditPayment(payment, terms),
67
+ retained = paymentCreditProof.parse(JSON.parse(row.paymentProofJson));
68
+ if (
69
+ !proof ||
70
+ proof.chargeId !== retained.chargeId ||
71
+ price.id !== terms.binding.stripePriceId
72
+ )
73
+ return {
74
+ status: "conflict",
75
+ reason: "identity_changed",
76
+ retryable: false,
77
+ };
78
+ verifyPinnedUsagePrice(
79
+ price,
80
+ {
81
+ stripeAccountId: terms.scope.stripeAccountId,
82
+ livemode: terms.scope.livemode,
83
+ },
84
+ terms.binding.plan,
85
+ terms.scope.meterId,
86
+ false,
87
+ );
88
+ const charge = payment.latest_charge;
89
+ if (!charge || typeof charge === "string")
90
+ return {
91
+ status: "not_ready",
92
+ reason: "provider_pending",
93
+ retryable: true,
94
+ };
95
+ const customerId = (value: string | { id: string } | null | undefined) =>
96
+ typeof value === "string" ? value : value?.id;
97
+ if (
98
+ customerId(payment.customer) !== terms.binding.stripeCustomerId ||
99
+ customerId(charge.customer) !== terms.binding.stripeCustomerId ||
100
+ charge.transfer
101
+ )
102
+ return {
103
+ status: "conflict",
104
+ reason: "identity_changed",
105
+ retryable: false,
106
+ };
107
+ const balanceRef = charge.balance_transaction;
108
+ if (!balanceRef)
109
+ return { status: "not_ready", reason: "fee_pending", retryable: true };
110
+ const balance =
111
+ typeof balanceRef === "string"
112
+ ? await stripe.balanceTransactions.retrieve(balanceRef)
113
+ : balanceRef;
114
+ const sourceId =
115
+ typeof balance.source === "string" ? balance.source : balance.source?.id;
116
+ if (
117
+ (typeof balanceRef === "string" && balance.id !== balanceRef) ||
118
+ balance.object !== "balance_transaction" ||
119
+ sourceId !== charge.id ||
120
+ saleAmountFailure(payment, charge, balance) ||
121
+ balance.amount !== terms.amount ||
122
+ balance.net !== balance.amount - balance.fee ||
123
+ !Number.isSafeInteger(balance.amount) ||
124
+ !Number.isSafeInteger(balance.net)
125
+ )
126
+ return {
127
+ status: "rejected",
128
+ reason: "unsupported_source",
129
+ retryable: false,
130
+ };
131
+ return {
132
+ status: "ready",
133
+ value: {
134
+ purchaseId: terms.purchaseId,
135
+ paymentIntentId: proof.paymentIntentId,
136
+ chargeId: proof.chargeId,
137
+ creditGrantId: row.creditGrantId,
138
+ stripeAccountId: terms.scope.stripeAccountId,
139
+ customerAccount: terms.scope.customerAccount,
140
+ livemode: terms.scope.livemode,
141
+ stripePriceId: price.id,
142
+ stripeProductId:
143
+ typeof price.product === "string" ? price.product : price.product.id,
144
+ gross: terms.amount,
145
+ processingFee: balance.fee,
146
+ currency: payment.currency,
147
+ ownership: "issuer",
148
+ },
149
+ };
150
+ } catch (error) {
151
+ if (error instanceof UsageCreditRecoveryError)
152
+ return {
153
+ status: "rejected",
154
+ reason: "payment_not_payable",
155
+ retryable: false,
156
+ };
157
+ return {
158
+ status: "unknown",
159
+ reason: "provider_outcome_unknown",
160
+ retryable: false,
161
+ };
162
+ }
163
+ }
@@ -0,0 +1,70 @@
1
+ import type { SourceHttpClient } from "../paymentSource/resolver.fixtures.js";
2
+ import { BetterStripe } from "../index.js";
3
+ import type { RunCtx } from "../helpers.js";
4
+ import { creditFixture } from "./creditTransport.fixtures.js";
5
+ export async function fixture(
6
+ affiliate: { basisPoints?: number; fixedAmount?: number } = {
7
+ basisPoints: 1000,
8
+ },
9
+ ) {
10
+ const native: Record<string, unknown>[] = [];
11
+ const response = (data: unknown) =>
12
+ new Response(JSON.stringify(data), {
13
+ headers: { "content-type": "application/json" },
14
+ });
15
+ const f = creditFixture(async (input, init) => {
16
+ const path = new URL(input).pathname;
17
+ if (path === "/v1/charges/ch_topup1")
18
+ return response({ id: "ch_topup1", created: 700 });
19
+ if (path !== "/v1/transfers") return;
20
+ if ((init?.method ?? "GET") === "GET")
21
+ return response({ object: "list", data: native, has_more: false });
22
+ const body = new URLSearchParams(String(init?.body ?? ""));
23
+ const transfer = {
24
+ id: `tr_${native.length}`,
25
+ amount: Number(body.get("amount")),
26
+ currency: body.get("currency"),
27
+ destination: body.get("destination"),
28
+ source_transaction: body.get("source_transaction"),
29
+ metadata: {
30
+ bsRole: body.get("metadata[bsRole]"),
31
+ bsSourceCharge: body.get("metadata[bsSourceCharge]"),
32
+ },
33
+ };
34
+ native.push(transfer);
35
+ return response(transfer);
36
+ });
37
+ const client = new BetterStripe(f.component),
38
+ options = {
39
+ stripeSecretKey: "sk_test_credit",
40
+ httpClient: f.httpClient as SourceHttpClient,
41
+ };
42
+ const view = await f.ready();
43
+ await f.t.action((ctx) =>
44
+ client.usage.purchaseCredits(ctx as RunCtx, f.purchase, options),
45
+ );
46
+ f.state.paid = true;
47
+ await f.t.action((ctx) =>
48
+ client.usage.observeCreditPurchase(ctx as RunCtx, f.purchase, options),
49
+ );
50
+ const input = {
51
+ ...f.purchase,
52
+ policy: {
53
+ affiliate: { destinationAccountId: "acct_affiliate", ...affiliate },
54
+ },
55
+ };
56
+ const settle = () =>
57
+ f.t.action((ctx) =>
58
+ client.usage.settleCreditPurchase(ctx as RunCtx, input, options),
59
+ );
60
+ return {
61
+ ...f,
62
+ httpClient: f.httpClient as SourceHttpClient,
63
+ native,
64
+ client,
65
+ options,
66
+ view,
67
+ input,
68
+ settle,
69
+ };
70
+ }
@@ -0,0 +1,66 @@
1
+ import { afterEach, expect, it, vi } from "vitest";
2
+ import type { RunCtx } from "../helpers.js";
3
+ import { fixture } from "./creditSettlement.fixtures.js";
4
+ afterEach(() => vi.useRealTimers());
5
+ it("pays an issuer-service purchase affiliate once and never pays again for credit consumption", async () => {
6
+ const f = await fixture(),
7
+ { native, client, options, view, input, settle } = f;
8
+ const first = await settle();
9
+ expect(first).toMatchObject({
10
+ status: "settled",
11
+ gross: 20,
12
+ processingFee: 1,
13
+ platformNet: 18,
14
+ creditSource: { purchaseId: "topup1", creditGrantId: "credgr_topup1" },
15
+ transfers: [{ role: "affiliate", amount: 1 }],
16
+ });
17
+ const event = {
18
+ scope: f.purchase.scope,
19
+ binding: f.purchase.binding,
20
+ sourceEventId: "consume1",
21
+ quantity: "6",
22
+ occurredAt: 700,
23
+ },
24
+ subscription = view.bindings[0].subscription;
25
+ const reservation = await f.t.action((ctx) =>
26
+ client.usage.reserveCredits(ctx as RunCtx, { event, subscription }),
27
+ );
28
+ await f.t.action((ctx) =>
29
+ client.usage.record(ctx as RunCtx, {
30
+ event,
31
+ subscription,
32
+ reservationId: reservation.reservationId,
33
+ }),
34
+ );
35
+ expect(await settle()).toEqual(first);
36
+ expect(native).toHaveLength(1);
37
+ f.state.processingFee = 2;
38
+ expect(await settle()).toMatchObject({
39
+ status: "conflict",
40
+ reason: "identity_changed",
41
+ });
42
+ expect(native).toHaveLength(1);
43
+ f.state.processingFee = 1;
44
+ f.state.refunded = true;
45
+ expect(await settle()).toMatchObject({
46
+ status: "rejected",
47
+ reason: "payment_not_payable",
48
+ });
49
+ expect(native).toHaveLength(1);
50
+ for (const unsupported of [
51
+ {
52
+ ...input,
53
+ policy: { ...input.policy, creatorAccountId: "acct_reseller" },
54
+ },
55
+ { ...input, ownership: "reseller" },
56
+ ])
57
+ expect(
58
+ await f.t.action((ctx) =>
59
+ client.usage.settleCreditPurchase(
60
+ ctx as RunCtx,
61
+ unsupported as typeof input,
62
+ options,
63
+ ),
64
+ ),
65
+ ).toMatchObject({ status: "rejected", reason: "unsupported_source" });
66
+ });
@@ -0,0 +1,94 @@
1
+ import { componentRef } from "../webhooks/helpers.js";
2
+ import type { ResolvedSettlement } from "../settlement/execution.js";
3
+ import { z } from "zod";
4
+ import { getCreditPurchaseRevenue } from "./creditRevenue.js";
5
+ import { allocateSale } from "../settlement/allocation.js";
6
+ import { executeResolvedTransfers } from "../settlement/execution.js";
7
+ import type Stripe from "stripe";
8
+ import type { Component, RunCtx } from "../helpers.js";
9
+ import type { UsageCreditPurchaseOptions } from "./creditTerms.js";
10
+ import type { SaleAllocationOptions } from "../settlement/allocation.js";
11
+ export type UsageCreditSettlementOptions = UsageCreditPurchaseOptions & {
12
+ policy: {
13
+ affiliate?: SaleAllocationOptions["affiliate"];
14
+ feeBasisPoints?: number;
15
+ };
16
+ };
17
+ const policySchema = z.strictObject({
18
+ feeBasisPoints: z.number().int().min(0).max(10000).optional(),
19
+ affiliate: z
20
+ .strictObject({
21
+ destinationAccountId: z.string().min(1).max(100),
22
+ basisPoints: z.number().int().min(0).max(10000).optional(),
23
+ fixedAmount: z
24
+ .number()
25
+ .int()
26
+ .nonnegative()
27
+ .max(Number.MAX_SAFE_INTEGER)
28
+ .optional(),
29
+ })
30
+ .optional(),
31
+ });
32
+ /** Retain issuer revenue; an authorized affiliate is paid from the original purchase only. No reseller redemption. */
33
+ export async function settleCreditPurchase(
34
+ stripe: Stripe,
35
+ component: Component,
36
+ ctx: RunCtx,
37
+ input: UsageCreditSettlementOptions,
38
+ ) {
39
+ const { policy, ...purchase } = input;
40
+ const parsed = policySchema.safeParse(policy);
41
+ if (!parsed.success || purchase.ownership !== "issuer")
42
+ return {
43
+ status: "rejected" as const,
44
+ reason: "unsupported_source" as const,
45
+ retryable: false as const,
46
+ };
47
+ const source = await getCreditPurchaseRevenue(
48
+ stripe,
49
+ component,
50
+ ctx,
51
+ purchase,
52
+ );
53
+ if (source.status !== "ready") return source;
54
+ const value = source.value;
55
+ const prior = (await ctx.runQuery(
56
+ componentRef(component, "settlement/queries/getSettlementAllocation"),
57
+ { sourceChargeId: value.chargeId },
58
+ )) as ResolvedSettlement | null;
59
+ if (
60
+ prior &&
61
+ (prior.gross !== value.gross ||
62
+ prior.currency !== value.currency ||
63
+ prior.processingFee !== value.processingFee)
64
+ )
65
+ return {
66
+ status: "conflict" as const,
67
+ reason: "identity_changed" as const,
68
+ retryable: false as const,
69
+ };
70
+ const allocation = allocateSale({
71
+ ...parsed.data,
72
+ creatorAccountId: value.stripeAccountId,
73
+ gross: value.gross,
74
+ processingFee: value.processingFee,
75
+ });
76
+ return executeResolvedTransfers(stripe, component, ctx, {
77
+ sourceChargeId: value.chargeId,
78
+ paymentIntentId: value.paymentIntentId,
79
+ creditSource: {
80
+ stripeAccountId: value.stripeAccountId,
81
+ customerAccount: value.customerAccount,
82
+ livemode: value.livemode,
83
+ purchaseId: value.purchaseId,
84
+ creditGrantId: value.creditGrantId,
85
+ stripePriceId: value.stripePriceId,
86
+ stripeProductId: value.stripeProductId,
87
+ },
88
+ gross: value.gross,
89
+ currency: value.currency,
90
+ processingFee: value.processingFee,
91
+ platformNet: allocation.platformNet + allocation.creatorNet,
92
+ transfers: allocation.transfers.filter((leg) => leg.role !== "store"),
93
+ });
94
+ }