@fantastic.dev/better-stripe 0.32.0 → 0.33.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 (51) hide show
  1. package/CHANGELOG.md +7 -0
  2. package/README.md +7 -1
  3. package/dist/client/billing/checkoutPages.d.ts +26 -0
  4. package/dist/client/billing/checkoutPages.d.ts.map +1 -0
  5. package/dist/client/billing/checkoutPages.js +111 -0
  6. package/dist/client/billing/checkoutPages.js.map +1 -0
  7. package/dist/client/connect/refundContext.d.ts +6 -0
  8. package/dist/client/connect/refundContext.d.ts.map +1 -0
  9. package/dist/client/connect/refundContext.js +109 -0
  10. package/dist/client/connect/refundContext.js.map +1 -0
  11. package/dist/client/connect/refundContextHistory.d.ts +20 -0
  12. package/dist/client/connect/refundContextHistory.d.ts.map +1 -0
  13. package/dist/client/connect/refundContextHistory.js +55 -0
  14. package/dist/client/connect/refundContextHistory.js.map +1 -0
  15. package/dist/client/connect/refundContextTypes.d.ts +39 -0
  16. package/dist/client/connect/refundContextTypes.d.ts.map +1 -0
  17. package/dist/client/connect/refundContextTypes.js +15 -0
  18. package/dist/client/connect/refundContextTypes.js.map +1 -0
  19. package/dist/client/connect/refundTarget.d.ts +14 -0
  20. package/dist/client/connect/refundTarget.d.ts.map +1 -0
  21. package/dist/client/connect/refundTarget.js +17 -0
  22. package/dist/client/connect/refundTarget.js.map +1 -0
  23. package/dist/client/connect/refunds.d.ts +17 -1
  24. package/dist/client/connect/refunds.d.ts.map +1 -1
  25. package/dist/client/connect/refunds.js +7 -17
  26. package/dist/client/connect/refunds.js.map +1 -1
  27. package/dist/client/index.d.ts +2 -0
  28. package/dist/client/index.d.ts.map +1 -1
  29. package/dist/client/index.js.map +1 -1
  30. package/dist/client/invoiceReads.d.ts +7 -1
  31. package/dist/client/invoiceReads.d.ts.map +1 -1
  32. package/dist/client/invoiceReads.js +11 -1
  33. package/dist/client/invoiceReads.js.map +1 -1
  34. package/dist/component/payoutRelease/queries.d.ts +2 -2
  35. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  36. package/docs/checkout-session-pages.md +71 -0
  37. package/docs/read-contracts.md +28 -0
  38. package/docs/refund-context.md +84 -0
  39. package/package.json +4 -2
  40. package/src/client/billing/checkoutPages.test.ts +251 -0
  41. package/src/client/billing/checkoutPages.ts +135 -0
  42. package/src/client/connect/refundContext.ts +140 -0
  43. package/src/client/connect/refundContextHistory.ts +84 -0
  44. package/src/client/connect/refundContextTypes.ts +56 -0
  45. package/src/client/connect/refundTarget.ts +39 -0
  46. package/src/client/connect/refunds.test.ts +72 -0
  47. package/src/client/connect/refunds.ts +8 -22
  48. package/src/client/index.ts +9 -0
  49. package/src/client/invoiceReads.ts +17 -1
  50. package/src/client/refund-context-shapes.test.ts +127 -0
  51. package/src/client/refund-context.test.ts +404 -0
@@ -0,0 +1,404 @@
1
+ import type Stripe from "stripe";
2
+ import { afterEach, expect, it, vi } from "vitest";
3
+ import {
4
+ refundContextFixture as fixture,
5
+ refund,
6
+ page,
7
+ expectUnavailable,
8
+ } from "../../tests/fixtures/refund-context.js";
9
+ afterEach(() => vi.restoreAllMocks());
10
+
11
+ it("uses captured principal rather than authorized amount for a partial capture", async () => {
12
+ const f = fixture();
13
+ expect(await f.read()).toMatchObject({
14
+ status: "ready",
15
+ capturedAmount: 1000,
16
+ refundedAmount: 0,
17
+ remainingRefundableAmount: 1000,
18
+ });
19
+ expect(f.intentRead).toHaveBeenCalledTimes(1);
20
+ expect(f.chargeRead).toHaveBeenCalledTimes(1);
21
+ expect(f.refundRead).toHaveBeenCalledTimes(1);
22
+ });
23
+
24
+ it.each([
25
+ undefined,
26
+ null,
27
+ {},
28
+ { type: "seller" },
29
+ { type: "seller", accountId: "cus_legacy" },
30
+ { type: "buyer", accountId: "acct_store" },
31
+ { type: "admin", accountId: "acct_store" },
32
+ ])("rejects malformed actor %j before any lookup", async (actor) => {
33
+ const f = fixture();
34
+ await expect(
35
+ f.readRaw({ stripePaymentIntentId: "pi_one", actor }),
36
+ ).rejects.toThrow(/actor/i);
37
+ expect(f.runQuery).not.toHaveBeenCalled();
38
+ expect(f.intentRead).not.toHaveBeenCalled();
39
+ expect(f.chargeRead).not.toHaveBeenCalled();
40
+ expect(f.refundRead).not.toHaveBeenCalled();
41
+ });
42
+
43
+ it.each(["", " pi_one", "pi_one ", "ch_one", "pi_bad?"])(
44
+ "rejects noncanonical PI %j before any lookup",
45
+ async (stripePaymentIntentId) => {
46
+ const f = fixture();
47
+ await expect(f.read({ ...f.opts, stripePaymentIntentId })).rejects.toThrow(
48
+ /stripePaymentIntentId|canonical/i,
49
+ );
50
+ expect(f.runQuery).not.toHaveBeenCalled();
51
+ expect(f.intentRead).not.toHaveBeenCalled();
52
+ },
53
+ );
54
+
55
+ it.each([0, 1.5, 11, Number.NaN])(
56
+ "rejects invalid history budget %j before lookup",
57
+ async (maxRefundPages) => {
58
+ const f = fixture();
59
+ await expect(f.read({ ...f.opts, maxRefundPages })).rejects.toThrow(
60
+ /maxRefundPages|budget/i,
61
+ );
62
+ expect(f.runQuery).not.toHaveBeenCalled();
63
+ expect(f.intentRead).not.toHaveBeenCalled();
64
+ },
65
+ );
66
+
67
+ it.each(["", " acct_scope", "cus_legacy"])(
68
+ "rejects malformed connected scope %j before lookup",
69
+ async (stripeAccountId) => {
70
+ const f = fixture();
71
+ await expect(f.read({ ...f.opts, stripeAccountId })).rejects.toThrow(
72
+ /stripeAccountId|account/i,
73
+ );
74
+ expect(f.runQuery).not.toHaveBeenCalled();
75
+ expect(f.intentRead).not.toHaveBeenCalled();
76
+ },
77
+ );
78
+
79
+ it.each(["foreign", "affiliate", "other"])(
80
+ "denies %s seller before provider reads",
81
+ async (role) => {
82
+ const f = fixture();
83
+ f.runQuery.mockResolvedValue({
84
+ stripePaymentIntentId: "pi_one",
85
+ accountId: "acct_buyer",
86
+ splitRecipients: [{ destinationAccountId: "acct_store", role }],
87
+ amount: 2000,
88
+ currency: "usd",
89
+ });
90
+ await expect(f.read()).rejects.toThrow(/not authorized|unauthorized/i);
91
+ expect(f.intentRead).not.toHaveBeenCalled();
92
+ expect(f.chargeRead).not.toHaveBeenCalled();
93
+ expect(f.refundRead).not.toHaveBeenCalled();
94
+ },
95
+ );
96
+
97
+ it("allows the original store leg without granting minor legs authority", async () => {
98
+ const f = fixture();
99
+ f.runQuery.mockResolvedValue({
100
+ stripePaymentIntentId: "pi_one",
101
+ accountId: "acct_buyer",
102
+ splitRecipients: [
103
+ { destinationAccountId: "acct_store", role: "store" },
104
+ { destinationAccountId: "acct_affiliate", role: "affiliate" },
105
+ ],
106
+ amount: 2000,
107
+ currency: "usd",
108
+ });
109
+ expect(await f.read()).toMatchObject({
110
+ status: "ready",
111
+ remainingRefundableAmount: 1000,
112
+ });
113
+ });
114
+
115
+ it("requires original component target correlation even for an explicit admin", async () => {
116
+ const f = fixture();
117
+ f.runQuery.mockResolvedValue(null);
118
+ expectUnavailable(await f.read({ ...f.opts, actor: { type: "admin" } }));
119
+ expect(f.intentRead).not.toHaveBeenCalled();
120
+ });
121
+
122
+ it.each([
123
+ { stripePaymentIntentId: "pi_other", accountId: "acct_buyer" },
124
+ { stripePaymentIntentId: "pi_one", accountId: "cus_legacy" },
125
+ { stripePaymentIntentId: "pi_one", accountId: undefined },
126
+ ])(
127
+ "holds unavailable original target %j before provider lookup",
128
+ async (fields) => {
129
+ const f = fixture();
130
+ f.runQuery.mockResolvedValue({
131
+ ...fields,
132
+ destinationAccountId: "acct_store",
133
+ amount: 2000,
134
+ currency: "usd",
135
+ });
136
+ expectUnavailable(await f.read());
137
+ expect(f.intentRead).not.toHaveBeenCalled();
138
+ },
139
+ );
140
+
141
+ it.each([
142
+ { id: "pi_other" },
143
+ { customer_account: "acct_other" },
144
+ { customer_account: null },
145
+ { status: "processing" as const },
146
+ ])(
147
+ "holds mismatched or incomplete PI %j before charge lookup",
148
+ async (fields) => {
149
+ const f = fixture();
150
+ f.intentRead.mockResolvedValue({ ...f.payment, ...fields });
151
+ expectUnavailable(await f.read());
152
+ expect(f.chargeRead).not.toHaveBeenCalled();
153
+ expect(f.refundRead).not.toHaveBeenCalled();
154
+ },
155
+ );
156
+
157
+ it.each([
158
+ { id: "ch_other" },
159
+ { payment_intent: "pi_other" },
160
+ { currency: "kwd" },
161
+ { amount_captured: 999 },
162
+ { amount_captured: -1 },
163
+ { amount_captured: 1.5 },
164
+ { amount_captured: Number.MAX_SAFE_INTEGER + 1 },
165
+ { amount: 999 },
166
+ { amount_refunded: -1 },
167
+ { amount_refunded: 1001 },
168
+ { amount_refunded: 1.5 },
169
+ { paid: false },
170
+ { captured: false },
171
+ { disputed: true },
172
+ ])("holds unsupported original charge %j", async (fields) => {
173
+ const f = fixture();
174
+ f.chargeRead.mockResolvedValue({ ...f.charge, ...fields });
175
+ expectUnavailable(await f.read());
176
+ expect(f.refundRead).not.toHaveBeenCalled();
177
+ });
178
+
179
+ it("does not invent a V2 buyer field on Stripe23 Charge and validates supplied legacy customer correlation", async () => {
180
+ const f = fixture();
181
+ f.intentRead.mockResolvedValue({ ...f.payment, customer: "cus_original" });
182
+ f.chargeRead.mockResolvedValue({ ...f.charge, customer: "cus_other" });
183
+ expectUnavailable(await f.read());
184
+ expect(f.refundRead).not.toHaveBeenCalled();
185
+ });
186
+
187
+ it("keeps connected request scope separate from the original buyer", async () => {
188
+ const f = fixture();
189
+ expect(
190
+ await f.read({ ...f.opts, stripeAccountId: "acct_provider_scope" }),
191
+ ).toMatchObject({ status: "ready", remainingRefundableAmount: 1000 });
192
+ expect(f.intentRead).toHaveBeenCalledWith("pi_one", undefined, {
193
+ stripeAccount: "acct_provider_scope",
194
+ });
195
+ expect(f.chargeRead).toHaveBeenCalledWith("ch_one", undefined, {
196
+ stripeAccount: "acct_provider_scope",
197
+ });
198
+ expect(f.refundRead).toHaveBeenCalledWith(
199
+ { payment_intent: "pi_one", limit: 100 },
200
+ { stripeAccount: "acct_provider_scope" },
201
+ );
202
+ });
203
+
204
+ it("supports a completed partial refund followed by its remaining full refund", async () => {
205
+ const f = fixture();
206
+ f.chargeRead.mockResolvedValue({ ...f.charge, amount_refunded: 200 });
207
+ f.refundRead.mockResolvedValue(page([refund("re_partial", 200)]));
208
+ expect(await f.read()).toMatchObject({
209
+ status: "ready",
210
+ capturedAmount: 1000,
211
+ refundedAmount: 200,
212
+ remainingRefundableAmount: 800,
213
+ });
214
+ f.chargeRead.mockResolvedValue({
215
+ ...f.charge,
216
+ amount_refunded: 1000,
217
+ refunded: true,
218
+ });
219
+ f.refundRead.mockResolvedValue(
220
+ page([refund("re_partial", 200), refund("re_rest", 800)]),
221
+ );
222
+ expect(await f.read()).toMatchObject({
223
+ status: "ready",
224
+ capturedAmount: 1000,
225
+ refundedAmount: 1000,
226
+ remainingRefundableAmount: 0,
227
+ });
228
+ });
229
+
230
+ it.each(["jpy", "kwd", "isk"])(
231
+ "retains exact original %s units",
232
+ async (currency) => {
233
+ const f = fixture();
234
+ f.intentRead.mockResolvedValue({
235
+ ...f.payment,
236
+ currency,
237
+ amount: 1234,
238
+ amount_received: 1234,
239
+ });
240
+ f.chargeRead.mockResolvedValue({
241
+ ...f.charge,
242
+ currency,
243
+ amount: 1234,
244
+ amount_captured: 1234,
245
+ amount_refunded: 234,
246
+ });
247
+ f.runQuery.mockResolvedValue({
248
+ stripePaymentIntentId: "pi_one",
249
+ accountId: "acct_buyer",
250
+ destinationAccountId: "acct_store",
251
+ amount: 1234,
252
+ currency,
253
+ });
254
+ f.refundRead.mockResolvedValue(
255
+ page([{ ...refund("re_units", 234), currency }]),
256
+ );
257
+ expect(await f.read()).toMatchObject({
258
+ status: "ready",
259
+ capturedAmount: 1234,
260
+ refundedAmount: 234,
261
+ remainingRefundableAmount: 1000,
262
+ });
263
+ },
264
+ );
265
+
266
+ it.each(["pending", "requires_action", null, "future_state"])(
267
+ "keeps refund state %j unavailable",
268
+ async (status) => {
269
+ const f = fixture();
270
+ f.chargeRead.mockResolvedValue({ ...f.charge, amount_refunded: 200 });
271
+ f.refundRead.mockResolvedValue(
272
+ page([refund("re_pending", 200, status as Stripe.Refund["status"])]),
273
+ );
274
+ expectUnavailable(await f.read());
275
+ },
276
+ );
277
+
278
+ it.each(["failed", "canceled"])(
279
+ "does not subtract %s refund principal",
280
+ async (status) => {
281
+ const f = fixture();
282
+ f.refundRead.mockResolvedValue(
283
+ page([refund("re_failed", 200, status as Stripe.Refund["status"])]),
284
+ );
285
+ expect(await f.read()).toMatchObject({
286
+ status: "ready",
287
+ refundedAmount: 0,
288
+ remainingRefundableAmount: 1000,
289
+ });
290
+ },
291
+ );
292
+
293
+ it.each([
294
+ { charge: "ch_other" },
295
+ { payment_intent: "pi_other" },
296
+ { currency: "kwd" },
297
+ { amount: -1 },
298
+ { amount: 1.5 },
299
+ ])("holds inconsistent refund %j", async (fields) => {
300
+ const f = fixture();
301
+ f.refundRead.mockResolvedValue(
302
+ page([{ ...refund("re_bad", 100), ...fields }]),
303
+ );
304
+ expectUnavailable(await f.read());
305
+ });
306
+
307
+ it("does not expose a numeric remainder from inconsistent live counters", async () => {
308
+ const f = fixture();
309
+ f.chargeRead.mockResolvedValue({ ...f.charge, amount_refunded: 500 });
310
+ f.refundRead.mockResolvedValue(page([refund("re_observed", 200)]));
311
+ expectUnavailable(await f.read());
312
+ });
313
+
314
+ it("exhausts bounded pages and preserves the original payment scope", async () => {
315
+ const f = fixture();
316
+ f.chargeRead.mockResolvedValue({
317
+ ...f.charge,
318
+ amount_refunded: 1000,
319
+ refunded: true,
320
+ });
321
+ f.refundRead
322
+ .mockResolvedValueOnce(page([refund("re_first", 400)], true))
323
+ .mockResolvedValueOnce(page([refund("re_last", 600)]));
324
+ expect(await f.read({ ...f.opts, maxRefundPages: 2 })).toMatchObject({
325
+ status: "ready",
326
+ remainingRefundableAmount: 0,
327
+ });
328
+ expect(f.refundRead).toHaveBeenNthCalledWith(
329
+ 2,
330
+ { payment_intent: "pi_one", limit: 100, starting_after: "re_first" },
331
+ undefined,
332
+ );
333
+ });
334
+
335
+ it("holds exhausted history rather than returning a partial refundable balance", async () => {
336
+ const f = fixture();
337
+ f.refundRead.mockResolvedValue(page([refund("re_first", 200)], true));
338
+ expectUnavailable(await f.read({ ...f.opts, maxRefundPages: 1 }));
339
+ expect(f.refundRead).toHaveBeenCalledTimes(1);
340
+ });
341
+
342
+ it("holds a nonterminal empty provider page", async () => {
343
+ const f = fixture();
344
+ f.refundRead.mockResolvedValue(page([], true));
345
+ expectUnavailable(await f.read());
346
+ expect(f.refundRead).toHaveBeenCalledTimes(1);
347
+ });
348
+
349
+ it("holds duplicate or nonadvancing provider pages", async () => {
350
+ const f = fixture();
351
+ f.refundRead.mockResolvedValue(page([refund("re_repeated", 200)], true));
352
+ expectUnavailable(await f.read({ ...f.opts, maxRefundPages: 2 }));
353
+ expect(f.refundRead).toHaveBeenCalledTimes(2);
354
+ });
355
+
356
+ it("preserves provider error identity instead of inventing a zero balance", async () => {
357
+ const f = fixture();
358
+ const error = new Error("Fixture provider unavailable");
359
+ f.refundRead.mockRejectedValue(error);
360
+ await expect(f.read()).rejects.toBe(error);
361
+ });
362
+
363
+ it.each([900, 1000])(
364
+ "holds a non-last duplicate across pages at counter %i without silently deduplicating",
365
+ async (amount_refunded) => {
366
+ const f = fixture();
367
+ f.chargeRead.mockResolvedValue({ ...f.charge, amount_refunded });
368
+ f.refundRead
369
+ .mockResolvedValueOnce(
370
+ page([refund("re_a", 100), refund("re_b", 200)], true),
371
+ )
372
+ .mockResolvedValueOnce(page([refund("re_a", 100), refund("re_c", 600)]));
373
+ expectUnavailable(await f.read({ ...f.opts, maxRefundPages: 2 }));
374
+ },
375
+ );
376
+
377
+ it.each([
378
+ { data: null },
379
+ { data: {} },
380
+ { has_more: null },
381
+ { has_more: "false" },
382
+ { object: "refund" },
383
+ ])("holds malformed refund envelope %j", async (fields) => {
384
+ const f = fixture();
385
+ f.refundRead.mockResolvedValue({
386
+ ...page([]),
387
+ ...fields,
388
+ } as Stripe.Response<Stripe.ApiList<Stripe.Refund>>);
389
+ expectUnavailable(await f.read());
390
+ expect(f.refundRead).toHaveBeenCalledTimes(1);
391
+ });
392
+
393
+ it("holds oversized provider pages instead of processing an unbounded envelope", async () => {
394
+ const f = fixture();
395
+ f.refundRead.mockResolvedValue(
396
+ page(
397
+ Array.from({ length: 101 }, (_, i) =>
398
+ refund(`re_large_${i}`, 0, "failed"),
399
+ ),
400
+ ),
401
+ );
402
+ expectUnavailable(await f.read());
403
+ expect(f.refundRead).toHaveBeenCalledTimes(1);
404
+ });