@fantastic.dev/better-stripe 0.31.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 (57) hide show
  1. package/CHANGELOG.md +13 -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/billing/invoicePaymentPages.d.ts +28 -0
  8. package/dist/client/billing/invoicePaymentPages.d.ts.map +1 -0
  9. package/dist/client/billing/invoicePaymentPages.js +124 -0
  10. package/dist/client/billing/invoicePaymentPages.js.map +1 -0
  11. package/dist/client/connect/refundContext.d.ts +6 -0
  12. package/dist/client/connect/refundContext.d.ts.map +1 -0
  13. package/dist/client/connect/refundContext.js +109 -0
  14. package/dist/client/connect/refundContext.js.map +1 -0
  15. package/dist/client/connect/refundContextHistory.d.ts +20 -0
  16. package/dist/client/connect/refundContextHistory.d.ts.map +1 -0
  17. package/dist/client/connect/refundContextHistory.js +55 -0
  18. package/dist/client/connect/refundContextHistory.js.map +1 -0
  19. package/dist/client/connect/refundContextTypes.d.ts +39 -0
  20. package/dist/client/connect/refundContextTypes.d.ts.map +1 -0
  21. package/dist/client/connect/refundContextTypes.js +15 -0
  22. package/dist/client/connect/refundContextTypes.js.map +1 -0
  23. package/dist/client/connect/refundTarget.d.ts +14 -0
  24. package/dist/client/connect/refundTarget.d.ts.map +1 -0
  25. package/dist/client/connect/refundTarget.js +17 -0
  26. package/dist/client/connect/refundTarget.js.map +1 -0
  27. package/dist/client/connect/refunds.d.ts +17 -1
  28. package/dist/client/connect/refunds.d.ts.map +1 -1
  29. package/dist/client/connect/refunds.js +7 -17
  30. package/dist/client/connect/refunds.js.map +1 -1
  31. package/dist/client/index.d.ts +6 -6
  32. package/dist/client/index.d.ts.map +1 -1
  33. package/dist/client/index.js +2 -7
  34. package/dist/client/index.js.map +1 -1
  35. package/dist/client/invoiceReads.d.ts +20 -0
  36. package/dist/client/invoiceReads.d.ts.map +1 -0
  37. package/dist/client/invoiceReads.js +25 -0
  38. package/dist/client/invoiceReads.js.map +1 -0
  39. package/docs/checkout-session-pages.md +71 -0
  40. package/docs/invoice-payment-pages.md +43 -0
  41. package/docs/read-contracts.md +44 -0
  42. package/docs/refund-context.md +84 -0
  43. package/package.json +5 -2
  44. package/src/client/billing/checkoutPages.test.ts +251 -0
  45. package/src/client/billing/checkoutPages.ts +135 -0
  46. package/src/client/billing/invoicePaymentPages.test.ts +354 -0
  47. package/src/client/billing/invoicePaymentPages.ts +165 -0
  48. package/src/client/connect/refundContext.ts +140 -0
  49. package/src/client/connect/refundContextHistory.ts +84 -0
  50. package/src/client/connect/refundContextTypes.ts +56 -0
  51. package/src/client/connect/refundTarget.ts +39 -0
  52. package/src/client/connect/refunds.test.ts +72 -0
  53. package/src/client/connect/refunds.ts +8 -22
  54. package/src/client/index.ts +16 -12
  55. package/src/client/invoiceReads.ts +45 -0
  56. package/src/client/refund-context-shapes.test.ts +127 -0
  57. package/src/client/refund-context.test.ts +404 -0
@@ -0,0 +1,84 @@
1
+ import type Stripe from "stripe";
2
+ import { refundObjectId } from "./refundTarget.js";
3
+ import type { RefundContextUnavailableReason } from "./refundContextTypes.js";
4
+
5
+ type HistoryResult =
6
+ | { status: "complete"; refundedAmount: number }
7
+ | { status: "unavailable"; reason: RefundContextUnavailableReason };
8
+ const unavailable = (
9
+ reason: RefundContextUnavailableReason,
10
+ ): HistoryResult => ({ status: "unavailable", reason });
11
+
12
+ /** All bounded pages must agree with the captured charge; loaded previews cannot establish a remainder. */
13
+ export async function readRefundHistory(
14
+ stripe: Stripe,
15
+ opts: {
16
+ paymentIntentId: string;
17
+ chargeId: string;
18
+ currency: string;
19
+ capturedAmount: number;
20
+ maxRefundPages: number;
21
+ stripeAccountId?: string;
22
+ },
23
+ ): Promise<HistoryResult> {
24
+ let refundedAmount = 0;
25
+ let cursor: string | undefined;
26
+ const seen = new Set<string>();
27
+ for (let count = 0; count < opts.maxRefundPages; count++) {
28
+ const page = await stripe.refunds.list(
29
+ {
30
+ payment_intent: opts.paymentIntentId,
31
+ limit: 100,
32
+ ...(cursor ? { starting_after: cursor } : {}),
33
+ },
34
+ opts.stripeAccountId
35
+ ? { stripeAccount: opts.stripeAccountId }
36
+ : undefined,
37
+ );
38
+ if (
39
+ !page ||
40
+ page.object !== "list" ||
41
+ !Array.isArray(page.data) ||
42
+ page.data.length > 100 ||
43
+ typeof page.has_more !== "boolean" ||
44
+ (page.has_more && !page.data.length)
45
+ )
46
+ return unavailable("refund_history_incomplete");
47
+ for (const refund of page.data) {
48
+ if (
49
+ !refund ||
50
+ refund.object !== "refund" ||
51
+ typeof refund.id !== "string" ||
52
+ !/^re_[A-Za-z0-9_]+$/.test(refund.id) ||
53
+ seen.has(refund.id)
54
+ )
55
+ return unavailable("refund_history_incomplete");
56
+ seen.add(refund.id);
57
+ if (
58
+ refundObjectId(refund.charge) !== opts.chargeId ||
59
+ refundObjectId(refund.payment_intent) !== opts.paymentIntentId ||
60
+ refund.currency !== opts.currency ||
61
+ !Number.isSafeInteger(refund.amount) ||
62
+ refund.amount < 0
63
+ )
64
+ return unavailable("refund_scope_mismatch");
65
+ if (refund.status === "pending" || refund.status === "requires_action")
66
+ return unavailable("refund_pending");
67
+ if (
68
+ refund.status !== "succeeded" &&
69
+ refund.status !== "failed" &&
70
+ refund.status !== "canceled"
71
+ )
72
+ return unavailable("refund_state_unknown");
73
+ if (refund.status === "succeeded") refundedAmount += refund.amount;
74
+ if (
75
+ !Number.isSafeInteger(refundedAmount) ||
76
+ refundedAmount > opts.capturedAmount
77
+ )
78
+ return unavailable("refund_counter_mismatch");
79
+ }
80
+ if (!page.has_more) return { status: "complete", refundedAmount };
81
+ cursor = page.data[page.data.length - 1]!.id;
82
+ }
83
+ return unavailable("refund_history_incomplete");
84
+ }
@@ -0,0 +1,56 @@
1
+ import { z } from "zod";
2
+ import type { RefundActor } from "./refundActor.js";
3
+
4
+ const accountId = z.string().regex(/^acct_[A-Za-z0-9_]+$/);
5
+ /** New observations require an explicit actor; legacy createRefund omission is not inherited. */
6
+ export const refundContextOptionsSchema = z
7
+ .object({
8
+ stripePaymentIntentId: z.string().regex(/^pi_[A-Za-z0-9_]+$/),
9
+ actor: z.discriminatedUnion("type", [
10
+ z.object({ type: z.literal("admin") }).strict(),
11
+ z.object({ type: z.literal("seller"), accountId }).strict(),
12
+ ]),
13
+ stripeAccountId: accountId.optional(),
14
+ maxRefundPages: z.number().int().min(1).max(10).default(5),
15
+ })
16
+ .strict();
17
+
18
+ export type RefundContextOptions = {
19
+ stripePaymentIntentId: string;
20
+ actor: RefundActor;
21
+ /** Server-owned provider request scope, distinct from the buyer and merchant accounts. */
22
+ stripeAccountId?: string;
23
+ /** Complete bounded history or unavailable, never a partial refund balance. Default 5, maximum 10. */
24
+ maxRefundPages?: number;
25
+ };
26
+ export type RefundContextUnavailableReason =
27
+ | "payment_unavailable"
28
+ | "buyer_unavailable"
29
+ | "payment_scope_mismatch"
30
+ | "payment_not_succeeded"
31
+ | "charge_unavailable"
32
+ | "charge_scope_mismatch"
33
+ | "buyer_mismatch"
34
+ | "currency_mismatch"
35
+ | "amount_unavailable"
36
+ | "charge_not_captured"
37
+ | "charge_disputed"
38
+ | "refund_pending"
39
+ | "refund_state_unknown"
40
+ | "refund_history_incomplete"
41
+ | "refund_scope_mismatch"
42
+ | "refund_counter_mismatch";
43
+ export type RefundContext =
44
+ | { status: "unavailable"; reason: RefundContextUnavailableReason }
45
+ | {
46
+ status: "ready";
47
+ stripePaymentIntentId: string;
48
+ stripeChargeId: string;
49
+ customerAccount: string;
50
+ currency: string;
51
+ capturedAmount: number;
52
+ refundedAmount: number;
53
+ remainingRefundableAmount: number;
54
+ /** Milliseconds; an observation, not a reservation or immutable snapshot. */
55
+ observedAt: number;
56
+ };
@@ -0,0 +1,39 @@
1
+ import type Stripe from "stripe";
2
+
3
+ export function refundObjectId(
4
+ value: string | { id: string } | null | undefined,
5
+ ) {
6
+ return typeof value === "string" ? value : value?.id;
7
+ }
8
+ export type RefundTargetOptions = {
9
+ stripePaymentIntentId?: string;
10
+ stripeChargeId?: string;
11
+ stripeAccountId?: string;
12
+ };
13
+ /** Shared target resolution; caller authorization and observation validation remain separate. */
14
+ export async function readRefundPayment(
15
+ stripe: Stripe,
16
+ opts: RefundTargetOptions,
17
+ ) {
18
+ if (!opts.stripePaymentIntentId) return null;
19
+ return stripe.paymentIntents.retrieve(
20
+ opts.stripePaymentIntentId,
21
+ undefined,
22
+ opts.stripeAccountId ? { stripeAccount: opts.stripeAccountId } : undefined,
23
+ );
24
+ }
25
+ /** Resolve only the selected original charge; does not create refunds or inspect fees. */
26
+ export async function readRefundCharge(
27
+ stripe: Stripe,
28
+ opts: RefundTargetOptions,
29
+ payment: Stripe.PaymentIntent | null,
30
+ ) {
31
+ const chargeId =
32
+ opts.stripeChargeId ?? refundObjectId(payment?.latest_charge);
33
+ if (!chargeId) return null;
34
+ return stripe.charges.retrieve(
35
+ chargeId,
36
+ undefined,
37
+ opts.stripeAccountId ? { stripeAccount: opts.stripeAccountId } : undefined,
38
+ );
39
+ }
@@ -362,5 +362,77 @@ describe("createRefund — actor scoping (BTS-35)", () => {
362
362
  stripePaymentIntentId: "pi_1",
363
363
  });
364
364
  expect(stripe.refunds.create).toHaveBeenCalledTimes(1);
365
+ expect(stripe.paymentIntents.retrieve).not.toHaveBeenCalled();
366
+ expect(stripe.charges.retrieve).toHaveBeenCalledTimes(2);
367
+ expect(stripe.refunds.create).toHaveBeenCalledWith(
368
+ { charge: "ch_1", reverse_transfer: true },
369
+ undefined,
370
+ );
371
+ });
372
+ });
373
+
374
+ it("keeps explicit charge-first lookup and original request/idempotency flags", async () => {
375
+ const stripe = makeStripe({ transfer: "tr_one", application_fee: "fee_one" });
376
+ await createRefund(asStripe(stripe), makeComponent(), noCtx, {
377
+ stripeChargeId: "ch_1",
378
+ stripeAccountId: "acct_request_scope",
379
+ idempotencyKey: "refund_same_intent",
380
+ amount: 123,
381
+ });
382
+ expect(stripe.paymentIntents.retrieve).not.toHaveBeenCalled();
383
+ expect(stripe.charges.retrieve).toHaveBeenCalledTimes(1);
384
+ expect(stripe.refunds.create).toHaveBeenCalledWith(
385
+ {
386
+ charge: "ch_1",
387
+ amount: 123,
388
+ refund_application_fee: true,
389
+ reverse_transfer: true,
390
+ },
391
+ {
392
+ stripeAccount: "acct_request_scope",
393
+ idempotencyKey: "refund_same_intent",
394
+ },
395
+ );
396
+ });
397
+
398
+ it("rejects both target selectors before authorization, lookup or money movement", async () => {
399
+ const stripe = makeStripe({});
400
+ const ctx = makeCtx();
401
+ await expect(
402
+ createRefund(asStripe(stripe), makeComponent(), ctx, {
403
+ stripePaymentIntentId: "pi_1",
404
+ stripeChargeId: "ch_1",
405
+ actor: { type: "seller", accountId: "acct_store" },
406
+ }),
407
+ ).rejects.toMatchObject({ data: { code: "REFUND_CREATE_FAILED" } });
408
+ expect(ctx.runQuery).not.toHaveBeenCalled();
409
+ expect(stripe.paymentIntents.retrieve).not.toHaveBeenCalled();
410
+ expect(stripe.charges.retrieve).not.toHaveBeenCalled();
411
+ expect(stripe.refunds.create).not.toHaveBeenCalled();
412
+ });
413
+
414
+ it("preserves structured createRefund error wrapping on charge-only lookup failure", async () => {
415
+ const stripe = makeStripe({});
416
+ const failure = Object.assign(new Error("Fixture provider failure"), {
417
+ type: "StripeAPIError",
418
+ code: "api_error",
419
+ });
420
+ stripe.charges.retrieve.mockRejectedValue(failure);
421
+ await expect(
422
+ createRefund(asStripe(stripe), makeComponent(), noCtx, {
423
+ stripeChargeId: "ch_1",
424
+ }),
425
+ ).rejects.toMatchObject({
426
+ data: {
427
+ code: "REFUND_CREATE_FAILED",
428
+ message: "Failed to create refund",
429
+ stripeError: {
430
+ type: "StripeAPIError",
431
+ code: "api_error",
432
+ message: "Fixture provider failure",
433
+ },
434
+ },
365
435
  });
436
+ expect(stripe.paymentIntents.retrieve).not.toHaveBeenCalled();
437
+ expect(stripe.refunds.create).not.toHaveBeenCalled();
366
438
  });
@@ -10,6 +10,7 @@ import type {
10
10
  } from "../types.js";
11
11
  import { componentRef } from "../webhooks/helpers.js";
12
12
  import { type RefundActor, isRefundAuthorized } from "./refundActor.js";
13
+ import { readRefundPayment, readRefundCharge } from "./refundTarget.js";
13
14
 
14
15
  export type { RefundActor } from "./refundActor.js";
15
16
 
@@ -126,9 +127,6 @@ export async function createRefund(
126
127
  await assertRefundAuthorized(stripe, component, ctx, opts);
127
128
 
128
129
  try {
129
- const accountRequestOpts = opts.stripeAccountId
130
- ? { stripeAccount: opts.stripeAccountId }
131
- : undefined;
132
130
  const createRequestOpts =
133
131
  opts.stripeAccountId !== undefined || opts.idempotencyKey !== undefined
134
132
  ? {
@@ -141,22 +139,9 @@ export async function createRefund(
141
139
  }
142
140
  : undefined;
143
141
 
144
- // Resolve the charge to gate the marketplace flags on what it can honour.
145
- let chargeId = opts.stripeChargeId;
146
- if (!chargeId && opts.stripePaymentIntentId) {
147
- const pi = await stripe.paymentIntents.retrieve(
148
- opts.stripePaymentIntentId,
149
- undefined,
150
- accountRequestOpts,
151
- );
152
- chargeId =
153
- typeof pi.latest_charge === "string"
154
- ? pi.latest_charge
155
- : (pi.latest_charge?.id ?? undefined);
156
- }
157
- const charge = chargeId
158
- ? await stripe.charges.retrieve(chargeId, undefined, accountRequestOpts)
159
- : undefined;
142
+ // Preserve the original target and marketplace flags through shared read-only resolution.
143
+ const payment = await readRefundPayment(stripe, opts);
144
+ const charge = await readRefundCharge(stripe, opts, payment);
160
145
 
161
146
  const refundApplicationFee =
162
147
  (opts.refundApplicationFee ?? true) && Boolean(charge?.application_fee);
@@ -193,7 +178,7 @@ export async function createRefund(
193
178
  * no ledger row), a seller is denied rather than allowed. No-ops for admin /
194
179
  * omitted actors.
195
180
  */
196
- async function assertRefundAuthorized(
181
+ export async function assertRefundAuthorized(
197
182
  stripe: Stripe,
198
183
  component: Component,
199
184
  ctx: RunCtx,
@@ -203,9 +188,9 @@ async function assertRefundAuthorized(
203
188
  stripeAccountId?: string;
204
189
  actor?: RefundActor;
205
190
  },
206
- ): Promise<void> {
191
+ ): Promise<StripeComponentPayment | null> {
207
192
  const { actor } = opts;
208
- if (!actor || actor.type === "admin") return; // unrestricted
193
+ if (!actor || actor.type === "admin") return null; // legacy createRefund remains unrestricted
209
194
 
210
195
  // Resolve the PaymentIntent id that keys the payments ledger. A charge-only
211
196
  // refund resolves through the charge's `payment_intent`.
@@ -253,6 +238,7 @@ async function assertRefundAuthorized(
253
238
  `Refund not authorized: seller ${actor.accountId} may not refund a sale routed to another account`,
254
239
  );
255
240
  }
241
+ return payment;
256
242
  }
257
243
 
258
244
  export async function getRefundByStripeId(
@@ -14,7 +14,7 @@ import type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js"
14
14
  export type { CreateCheckoutSessionOptions } from "./billing/checkoutOptions.js";
15
15
  import * as intentsImpl from "./billing/intents.js";
16
16
  export type * from "./billing/intents.js";
17
- import { ReadContractClient } from "./readContracts.js";
17
+ import { InvoiceReadClient } from "./invoiceReads.js";
18
18
  import { CostRecoveryClient } from "./costRecovery.js";
19
19
  export * from "./charge-currency.js";
20
20
  export * from "./costRecovery.js";
@@ -55,11 +55,18 @@ export type {
55
55
  CouponReadOptions,
56
56
  } from "./billing/providerReads.js";
57
57
  import * as providerReads from "./billing/providerReads.js";
58
- import * as invoicePages from "./billing/invoicePages.js";
58
+ export type {
59
+ InvoicePaymentPageOptions,
60
+ ProviderInvoicePaymentPage,
61
+ } from "./billing/invoicePaymentPages.js";
59
62
  export type {
60
63
  InvoicePageOptions,
61
64
  ProviderInvoicePage,
62
65
  } from "./billing/invoicePages.js";
66
+ export type {
67
+ CheckoutSessionPageOptions,
68
+ ProviderCheckoutSessionPage,
69
+ } from "./billing/checkoutPages.js";
63
70
  export type { CreateAccountOptions } from "./core/accounts.js";
64
71
  import { buildAsyncHookRoutes } from "./webhooks/asyncHooks.js";
65
72
  import * as saleContextImpl from "./settlement/verifiedSale.js";
@@ -118,6 +125,11 @@ export {
118
125
  disputeEvidenceCountdown,
119
126
  } from "./connect/disputes.js";
120
127
  export type { RefundActor } from "./connect/refunds.js";
128
+ export type {
129
+ RefundContextOptions,
130
+ RefundContext,
131
+ RefundContextUnavailableReason,
132
+ } from "./connect/refundContextTypes.js";
121
133
  import type { RefundActor } from "./connect/refunds.js";
122
134
  export type { AccountBalance } from "./connect/payouts.js";
123
135
  export type { WedgedReversalClaim } from "./connect/transfers.js";
@@ -219,7 +231,7 @@ export type BetterStripeComponent = ComponentApi;
219
231
 
220
232
  // BETTER STRIPE CLIENT
221
233
 
222
- export class BetterStripe extends ReadContractClient {
234
+ export class BetterStripe extends InvoiceReadClient {
223
235
  readonly stripeApiVersion: SupportedStripeApiVersion;
224
236
  private _apiKey?: string;
225
237
  private _triggers?: SyncTriggers;
@@ -285,7 +297,7 @@ export class BetterStripe extends ReadContractClient {
285
297
  return registerClientRoutes(this, http, config);
286
298
  }
287
299
 
288
- private stripe(): Stripe {
300
+ protected stripe(): Stripe {
289
301
  return getStripeClient(this.apiKey, this.stripeApiVersion);
290
302
  }
291
303
 
@@ -1022,14 +1034,6 @@ export class BetterStripe extends ReadContractClient {
1022
1034
  return invoicePreviewImpl.getUpcomingInvoicePreview(this.stripe(), opts);
1023
1035
  }
1024
1036
 
1025
- /** Provider page only; the host authorizes scope and verifies historical completeness. */
1026
- async getInvoicePageFromStripe(
1027
- _ctx: RunCtx,
1028
- opts: invoicePages.InvoicePageOptions,
1029
- ) {
1030
- return invoicePages.getInvoicePageFromStripe(this.stripe(), opts);
1031
- }
1032
-
1033
1037
  async getInvoiceFromStripe(ctx: RunCtx, opts: { stripeInvoiceId: string }) {
1034
1038
  return invoicesImpl.getInvoiceFromStripe(this.stripe(), ctx, opts);
1035
1039
  }
@@ -0,0 +1,45 @@
1
+ import type Stripe from "stripe";
2
+ import { ReadContractClient } from "./readContracts.js";
3
+ import type { RunCtx } from "./helpers.js";
4
+ import { getRefundContext } from "./connect/refundContext.js";
5
+ import type { RefundContextOptions } from "./connect/refundContextTypes.js";
6
+ import * as invoicePages from "./billing/invoicePages.js";
7
+ import * as invoicePaymentPages from "./billing/invoicePaymentPages.js";
8
+ import * as checkoutPages from "./billing/checkoutPages.js";
9
+
10
+ /** Provider billing history readers inherited by BetterStripe; hosts authorize their caller. */
11
+ export abstract class InvoiceReadClient extends ReadContractClient {
12
+ protected abstract stripe(): Stripe;
13
+
14
+ /** Required-actor observation only; the host authorizes community scope and revalidates creation. */
15
+ async getRefundContext(ctx: RunCtx, opts: RefundContextOptions) {
16
+ return getRefundContext(this.stripe(), this.component, ctx, opts);
17
+ }
18
+
19
+ /** Buyer-scoped discovery, not an atomic snapshot or a claim of complete purchase coverage. */
20
+ async getCheckoutSessionPageFromStripe(
21
+ _ctx: RunCtx,
22
+ opts: checkoutPages.CheckoutSessionPageOptions,
23
+ ) {
24
+ return checkoutPages.getCheckoutSessionPageFromStripe(this.stripe(), opts);
25
+ }
26
+
27
+ /** Provider page only; the host authorizes scope and verifies historical completeness. */
28
+ async getInvoicePageFromStripe(
29
+ _ctx: RunCtx,
30
+ opts: invoicePages.InvoicePageOptions,
31
+ ) {
32
+ return invoicePages.getInvoicePageFromStripe(this.stripe(), opts);
33
+ }
34
+
35
+ /** Checks known invoice buyer/subscription scope; does not establish refund eligibility. */
36
+ async getInvoicePaymentPageFromStripe(
37
+ _ctx: RunCtx,
38
+ opts: invoicePaymentPages.InvoicePaymentPageOptions,
39
+ ) {
40
+ return invoicePaymentPages.getInvoicePaymentPageFromStripe(
41
+ this.stripe(),
42
+ opts,
43
+ );
44
+ }
45
+ }
@@ -0,0 +1,127 @@
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.each([{ object: "payment_method" }, { object: undefined }])(
12
+ "holds malformed PI discriminator %j before charge lookup",
13
+ async (fields) => {
14
+ const f = fixture();
15
+ f.intentRead.mockResolvedValue({
16
+ ...f.payment,
17
+ ...fields,
18
+ } as Stripe.Response<Stripe.PaymentIntent>);
19
+ expectUnavailable(await f.read());
20
+ expect(f.chargeRead).not.toHaveBeenCalled();
21
+ },
22
+ );
23
+
24
+ it.each([
25
+ { object: "payment_intent" },
26
+ { object: undefined },
27
+ { status: "failed" },
28
+ { status: undefined },
29
+ { paid: "true" },
30
+ { captured: "false" },
31
+ { disputed: undefined },
32
+ { disputed: null },
33
+ { refunded: undefined },
34
+ { refunded: "false" },
35
+ ])("holds malformed charge flags and discriminator %j", async (fields) => {
36
+ const f = fixture();
37
+ f.chargeRead.mockResolvedValue({
38
+ ...f.charge,
39
+ ...fields,
40
+ } as Stripe.Response<Stripe.Charge>);
41
+ expectUnavailable(await f.read());
42
+ expect(f.refundRead).not.toHaveBeenCalled();
43
+ });
44
+
45
+ it.each([
46
+ undefined,
47
+ {},
48
+ { id: "cus_same" },
49
+ { id: "acct_wrong", object: "customer" },
50
+ { id: "cus_valid", object: "account" },
51
+ ])(
52
+ "does not equate malformed legacy customer references %j",
53
+ async (customer) => {
54
+ const f = fixture();
55
+ f.intentRead.mockResolvedValue({
56
+ ...f.payment,
57
+ customer,
58
+ } as Stripe.Response<Stripe.PaymentIntent>);
59
+ f.chargeRead.mockResolvedValue({
60
+ ...f.charge,
61
+ customer,
62
+ } as Stripe.Response<Stripe.Charge>);
63
+ expectUnavailable(await f.read());
64
+ expect(f.refundRead).not.toHaveBeenCalled();
65
+ },
66
+ );
67
+
68
+ it("accepts canonical nullable or expanded legacy customer correlation without inventing a Charge buyer field", async () => {
69
+ const f = fixture();
70
+ f.intentRead.mockResolvedValue({ ...f.payment, customer: "cus_legacy" });
71
+ f.chargeRead.mockResolvedValue({
72
+ ...f.charge,
73
+ customer: { id: "cus_legacy", object: "customer" } as Stripe.Customer,
74
+ });
75
+ expect(await f.read()).toMatchObject({
76
+ status: "ready",
77
+ remainingRefundableAmount: 1000,
78
+ });
79
+ });
80
+
81
+ it.each(["charge", undefined])(
82
+ "holds a malformed refund object %s",
83
+ async (object) => {
84
+ const f = fixture();
85
+ f.refundRead.mockResolvedValue(
86
+ page([
87
+ {
88
+ ...refund("re_bad", 0, "failed"),
89
+ object,
90
+ } as unknown as Stripe.Refund,
91
+ ]),
92
+ );
93
+ expectUnavailable(await f.read());
94
+ },
95
+ );
96
+
97
+ it.each([
98
+ { refunded: false, amount: 1000 },
99
+ { refunded: true, amount: 200 },
100
+ ])(
101
+ "holds contradictory full-refund lifecycle flags %j",
102
+ async ({ refunded, amount }) => {
103
+ const f = fixture();
104
+ f.chargeRead.mockResolvedValue({
105
+ ...f.charge,
106
+ amount_refunded: amount,
107
+ refunded,
108
+ });
109
+ f.refundRead.mockResolvedValue(page([refund("re_returned", amount)]));
110
+ expectUnavailable(await f.read());
111
+ },
112
+ );
113
+
114
+ it.each([false, true])(
115
+ "holds a zero capture instead of a ready free-payment observation (refunded=%s)",
116
+ async (refunded) => {
117
+ const f = fixture();
118
+ f.intentRead.mockResolvedValue({ ...f.payment, amount_received: 0 });
119
+ f.chargeRead.mockResolvedValue({
120
+ ...f.charge,
121
+ amount_captured: 0,
122
+ refunded,
123
+ });
124
+ expectUnavailable(await f.read());
125
+ expect(f.refundRead).not.toHaveBeenCalled();
126
+ },
127
+ );