@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.
- package/CHANGELOG.md +7 -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/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 +2 -0
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/index.js.map +1 -1
- package/dist/client/invoiceReads.d.ts +7 -1
- package/dist/client/invoiceReads.d.ts.map +1 -1
- package/dist/client/invoiceReads.js +11 -1
- package/dist/client/invoiceReads.js.map +1 -1
- package/dist/component/payoutRelease/queries.d.ts +2 -2
- package/dist/component/payoutRelease/queries.d.ts.map +1 -1
- package/docs/checkout-session-pages.md +71 -0
- package/docs/read-contracts.md +28 -0
- package/docs/refund-context.md +84 -0
- package/package.json +4 -2
- package/src/client/billing/checkoutPages.test.ts +251 -0
- package/src/client/billing/checkoutPages.ts +135 -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 +9 -0
- package/src/client/invoiceReads.ts +17 -1
- package/src/client/refund-context-shapes.test.ts +127 -0
- package/src/client/refund-context.test.ts +404 -0
|
@@ -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
|
@@ -63,6 +63,10 @@ export type {
|
|
|
63
63
|
InvoicePageOptions,
|
|
64
64
|
ProviderInvoicePage,
|
|
65
65
|
} from "./billing/invoicePages.js";
|
|
66
|
+
export type {
|
|
67
|
+
CheckoutSessionPageOptions,
|
|
68
|
+
ProviderCheckoutSessionPage,
|
|
69
|
+
} from "./billing/checkoutPages.js";
|
|
66
70
|
export type { CreateAccountOptions } from "./core/accounts.js";
|
|
67
71
|
import { buildAsyncHookRoutes } from "./webhooks/asyncHooks.js";
|
|
68
72
|
import * as saleContextImpl from "./settlement/verifiedSale.js";
|
|
@@ -121,6 +125,11 @@ export {
|
|
|
121
125
|
disputeEvidenceCountdown,
|
|
122
126
|
} from "./connect/disputes.js";
|
|
123
127
|
export type { RefundActor } from "./connect/refunds.js";
|
|
128
|
+
export type {
|
|
129
|
+
RefundContextOptions,
|
|
130
|
+
RefundContext,
|
|
131
|
+
RefundContextUnavailableReason,
|
|
132
|
+
} from "./connect/refundContextTypes.js";
|
|
124
133
|
import type { RefundActor } from "./connect/refunds.js";
|
|
125
134
|
export type { AccountBalance } from "./connect/payouts.js";
|
|
126
135
|
export type { WedgedReversalClaim } from "./connect/transfers.js";
|
|
@@ -1,13 +1,29 @@
|
|
|
1
1
|
import type Stripe from "stripe";
|
|
2
2
|
import { ReadContractClient } from "./readContracts.js";
|
|
3
3
|
import type { RunCtx } from "./helpers.js";
|
|
4
|
+
import { getRefundContext } from "./connect/refundContext.js";
|
|
5
|
+
import type { RefundContextOptions } from "./connect/refundContextTypes.js";
|
|
4
6
|
import * as invoicePages from "./billing/invoicePages.js";
|
|
5
7
|
import * as invoicePaymentPages from "./billing/invoicePaymentPages.js";
|
|
8
|
+
import * as checkoutPages from "./billing/checkoutPages.js";
|
|
6
9
|
|
|
7
|
-
/** Provider
|
|
10
|
+
/** Provider billing history readers inherited by BetterStripe; hosts authorize their caller. */
|
|
8
11
|
export abstract class InvoiceReadClient extends ReadContractClient {
|
|
9
12
|
protected abstract stripe(): Stripe;
|
|
10
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
|
+
|
|
11
27
|
/** Provider page only; the host authorizes scope and verifies historical completeness. */
|
|
12
28
|
async getInvoicePageFromStripe(
|
|
13
29
|
_ctx: RunCtx,
|
|
@@ -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
|
+
);
|