@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.
- package/CHANGELOG.md +13 -0
- package/README.md +7 -1
- package/dist/client/billing/checkoutPages.d.ts +26 -0
- package/dist/client/billing/checkoutPages.d.ts.map +1 -0
- package/dist/client/billing/checkoutPages.js +111 -0
- package/dist/client/billing/checkoutPages.js.map +1 -0
- package/dist/client/billing/invoicePaymentPages.d.ts +28 -0
- package/dist/client/billing/invoicePaymentPages.d.ts.map +1 -0
- package/dist/client/billing/invoicePaymentPages.js +124 -0
- package/dist/client/billing/invoicePaymentPages.js.map +1 -0
- package/dist/client/connect/refundContext.d.ts +6 -0
- package/dist/client/connect/refundContext.d.ts.map +1 -0
- package/dist/client/connect/refundContext.js +109 -0
- package/dist/client/connect/refundContext.js.map +1 -0
- package/dist/client/connect/refundContextHistory.d.ts +20 -0
- package/dist/client/connect/refundContextHistory.d.ts.map +1 -0
- package/dist/client/connect/refundContextHistory.js +55 -0
- package/dist/client/connect/refundContextHistory.js.map +1 -0
- package/dist/client/connect/refundContextTypes.d.ts +39 -0
- package/dist/client/connect/refundContextTypes.d.ts.map +1 -0
- package/dist/client/connect/refundContextTypes.js +15 -0
- package/dist/client/connect/refundContextTypes.js.map +1 -0
- package/dist/client/connect/refundTarget.d.ts +14 -0
- package/dist/client/connect/refundTarget.d.ts.map +1 -0
- package/dist/client/connect/refundTarget.js +17 -0
- package/dist/client/connect/refundTarget.js.map +1 -0
- package/dist/client/connect/refunds.d.ts +17 -1
- package/dist/client/connect/refunds.d.ts.map +1 -1
- package/dist/client/connect/refunds.js +7 -17
- package/dist/client/connect/refunds.js.map +1 -1
- package/dist/client/index.d.ts +6 -6
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js +2 -7
- package/dist/client/index.js.map +1 -1
- package/dist/client/invoiceReads.d.ts +20 -0
- package/dist/client/invoiceReads.d.ts.map +1 -0
- package/dist/client/invoiceReads.js +25 -0
- package/dist/client/invoiceReads.js.map +1 -0
- package/docs/checkout-session-pages.md +71 -0
- package/docs/invoice-payment-pages.md +43 -0
- package/docs/read-contracts.md +44 -0
- package/docs/refund-context.md +84 -0
- package/package.json +5 -2
- package/src/client/billing/checkoutPages.test.ts +251 -0
- package/src/client/billing/checkoutPages.ts +135 -0
- package/src/client/billing/invoicePaymentPages.test.ts +354 -0
- package/src/client/billing/invoicePaymentPages.ts +165 -0
- package/src/client/connect/refundContext.ts +140 -0
- package/src/client/connect/refundContextHistory.ts +84 -0
- package/src/client/connect/refundContextTypes.ts +56 -0
- package/src/client/connect/refundTarget.ts +39 -0
- package/src/client/connect/refunds.test.ts +72 -0
- package/src/client/connect/refunds.ts +8 -22
- package/src/client/index.ts +16 -12
- package/src/client/invoiceReads.ts +45 -0
- package/src/client/refund-context-shapes.test.ts +127 -0
- 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
|
-
//
|
|
145
|
-
|
|
146
|
-
|
|
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<
|
|
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(
|
package/src/client/index.ts
CHANGED
|
@@ -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 {
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
+
);
|