@fantastic.dev/better-stripe 0.75.0 → 0.77.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.
@@ -0,0 +1,272 @@
1
+ import { expect, it } from "vitest";
2
+
3
+ import * as sdk from "../index.js";
4
+
5
+ it("exports a pure captured Checkout payment qualifier from the public SDK", () => {
6
+ expect(sdk).toHaveProperty(
7
+ "qualifyCapturedCheckoutPayment",
8
+ expect.any(Function),
9
+ );
10
+ });
11
+
12
+ const expected = {
13
+ stripeSessionId: "cs_original",
14
+ customerAccountId: "acct_buyer",
15
+ livemode: false,
16
+ };
17
+
18
+ function session() {
19
+ return {
20
+ id: "cs_original",
21
+ object: "checkout.session",
22
+ mode: "payment",
23
+ subscription: null,
24
+ status: "complete",
25
+ payment_status: "paid",
26
+ customer_account: "acct_buyer",
27
+ livemode: false,
28
+ amount_total: 3500,
29
+ currency: "usd",
30
+ metadata: { originalRequest: "host-request" },
31
+ payment_intent: {
32
+ id: "pi_original",
33
+ object: "payment_intent",
34
+ status: "succeeded",
35
+ customer_account: "acct_buyer",
36
+ livemode: false,
37
+ amount: 3500,
38
+ amount_received: 3500,
39
+ currency: "usd",
40
+ metadata: { originalPayment: "host-payment" },
41
+ latest_charge: {
42
+ id: "ch_original",
43
+ object: "charge",
44
+ payment_intent: "pi_original",
45
+ livemode: false,
46
+ status: "succeeded",
47
+ paid: true,
48
+ captured: true,
49
+ amount: 3500,
50
+ amount_captured: 3500,
51
+ currency: "usd",
52
+ },
53
+ },
54
+ };
55
+ }
56
+
57
+ function change(input: object, path: string, value: unknown) {
58
+ const keys = path.split(".");
59
+ let current = input as Record<string, unknown>;
60
+ for (const key of keys.slice(0, -1))
61
+ current = current[key] as Record<string, unknown>;
62
+ current[keys[keys.length - 1]!] = value;
63
+ }
64
+
65
+ it("qualifies the retrieved original without invoice, fees or balance data", () => {
66
+ const input = session();
67
+ const before = structuredClone(input);
68
+ expect(sdk.qualifyCapturedCheckoutPayment(input, expected)).toEqual({
69
+ status: "ready",
70
+ stripeSessionId: "cs_original",
71
+ stripePaymentIntentId: "pi_original",
72
+ stripeChargeId: "ch_original",
73
+ customerAccountId: "acct_buyer",
74
+ livemode: false,
75
+ amount: 3500,
76
+ currency: "usd",
77
+ sessionMetadata: { originalRequest: "host-request" },
78
+ paymentIntentMetadata: { originalPayment: "host-payment" },
79
+ });
80
+ expect(input).toEqual(before);
81
+ });
82
+
83
+ it.each([
84
+ ["id", "cs_foreign"],
85
+ ["object", "payment_intent"],
86
+ ["mode", "subscription"],
87
+ ["subscription", "sub_contradiction"],
88
+ ["status", "open"],
89
+ ["status", "expired"],
90
+ ["status", null],
91
+ ["payment_status", "unpaid"],
92
+ ["payment_status", "no_payment_required"],
93
+ ["payment_intent", "pi_original"],
94
+ ["payment_intent", null],
95
+ ["payment_intent.id", "bad"],
96
+ ["payment_intent.object", "charge"],
97
+ ["payment_intent.status", "processing"],
98
+ ["payment_intent.status", "requires_capture"],
99
+ ["payment_intent.status", "canceled"],
100
+ ["payment_intent.latest_charge", "ch_original"],
101
+ ["payment_intent.latest_charge", null],
102
+ ["payment_intent.latest_charge.id", "bad"],
103
+ ["payment_intent.latest_charge.object", "payment_intent"],
104
+ ["payment_intent.latest_charge.payment_intent", "pi_foreign"],
105
+ ["payment_intent.latest_charge.status", "failed"],
106
+ ["payment_intent.latest_charge.paid", false],
107
+ ["payment_intent.latest_charge.captured", false],
108
+ ["customer_account", "acct_foreign"],
109
+ ["customer_account", undefined],
110
+ ["payment_intent.customer_account", "acct_foreign"],
111
+ ["payment_intent.customer_account", undefined],
112
+ ["livemode", true],
113
+ ["payment_intent.livemode", true],
114
+ ["payment_intent.latest_charge.livemode", true],
115
+ ["currency", "USD"],
116
+ ["currency", ""],
117
+ ["payment_intent.currency", "eur"],
118
+ ["payment_intent.latest_charge.currency", "eur"],
119
+ ["metadata", { invalid: 1 }],
120
+ ["payment_intent.metadata", { invalid: null }],
121
+ ["amount_total", 3499],
122
+ ["payment_intent.amount", 3499],
123
+ ["payment_intent.amount_received", 3499],
124
+ ["payment_intent.latest_charge.amount", 3499],
125
+ ["payment_intent.latest_charge.amount_captured", 3499],
126
+ ] as const)("withholds inconsistent or incomplete %s = %j", (path, value) => {
127
+ const input = session();
128
+ change(input, path, value);
129
+ expect(sdk.qualifyCapturedCheckoutPayment(input, expected).status).toBe(
130
+ "unavailable",
131
+ );
132
+ });
133
+
134
+ it.each([null, undefined, {}, "session", []])(
135
+ "rejects malformed input %j",
136
+ (input) => {
137
+ expect(sdk.qualifyCapturedCheckoutPayment(input, expected)).toEqual({
138
+ status: "unavailable",
139
+ reason: "invalid_evidence",
140
+ });
141
+ },
142
+ );
143
+
144
+ it.each(["stripeSessionId", "customerAccountId", "livemode"] as const)(
145
+ "rejects malformed expected %s at runtime",
146
+ (key) => {
147
+ const input = { ...expected, [key]: null };
148
+ expect(
149
+ sdk.qualifyCapturedCheckoutPayment(session(), input as never),
150
+ ).toEqual({
151
+ status: "unavailable",
152
+ reason: "invalid_context",
153
+ });
154
+ },
155
+ );
156
+
157
+ it.each(["", "bad", "cs_"])(
158
+ "rejects malformed Session selector %j",
159
+ (stripeSessionId) => {
160
+ expect(
161
+ sdk.qualifyCapturedCheckoutPayment(session(), {
162
+ ...expected,
163
+ stripeSessionId,
164
+ }),
165
+ ).toEqual({
166
+ status: "unavailable",
167
+ reason: "invalid_context",
168
+ });
169
+ },
170
+ );
171
+ it.each(["", "cus_buyer", "acct_"])(
172
+ "rejects malformed V2 account selector %j",
173
+ (customerAccountId) => {
174
+ expect(
175
+ sdk.qualifyCapturedCheckoutPayment(session(), {
176
+ ...expected,
177
+ customerAccountId,
178
+ }),
179
+ ).toEqual({
180
+ status: "unavailable",
181
+ reason: "invalid_context",
182
+ });
183
+ },
184
+ );
185
+
186
+ it("does not substitute customer-v1 presentation for V2 account authority", () => {
187
+ const input = session();
188
+ Object.assign(input, { customer: "cus_buyer", customer_account: undefined });
189
+ Object.assign(input.payment_intent, {
190
+ customer: "cus_buyer",
191
+ customer_account: undefined,
192
+ });
193
+ expect(sdk.qualifyCapturedCheckoutPayment(input, expected).status).toBe(
194
+ "unavailable",
195
+ );
196
+ });
197
+
198
+ it("rejects coherent live evidence against expected test scope", () => {
199
+ const input = session();
200
+ input.livemode =
201
+ input.payment_intent.livemode =
202
+ input.payment_intent.latest_charge.livemode =
203
+ true;
204
+ expect(sdk.qualifyCapturedCheckoutPayment(input, expected)).toEqual({
205
+ status: "unavailable",
206
+ reason: "identity_mismatch",
207
+ });
208
+ expect(
209
+ sdk.qualifyCapturedCheckoutPayment(input, { ...expected, livemode: true })
210
+ .status,
211
+ ).toBe("ready");
212
+ });
213
+
214
+ it.each([0, -1, 0.5, Number.MAX_SAFE_INTEGER + 1, NaN, Infinity, "3500"])(
215
+ "rejects coherently invalid gross amount %j",
216
+ (amount) => {
217
+ const input = session();
218
+ for (const path of [
219
+ "amount_total",
220
+ "payment_intent.amount",
221
+ "payment_intent.amount_received",
222
+ "payment_intent.latest_charge.amount",
223
+ "payment_intent.latest_charge.amount_captured",
224
+ ])
225
+ change(input, path, amount);
226
+ expect(sdk.qualifyCapturedCheckoutPayment(input, expected).status).toBe(
227
+ "unavailable",
228
+ );
229
+ },
230
+ );
231
+
232
+ it.each([
233
+ ["jpy", 3500],
234
+ ["kwd", 3501],
235
+ ["usd", Number.MAX_SAFE_INTEGER],
236
+ ] as const)(
237
+ "preserves integer original provider units for %s",
238
+ (currency, amount) => {
239
+ const input = session();
240
+ input.currency =
241
+ input.payment_intent.currency =
242
+ input.payment_intent.latest_charge.currency =
243
+ currency;
244
+ input.amount_total =
245
+ input.payment_intent.amount =
246
+ input.payment_intent.amount_received =
247
+ input.payment_intent.latest_charge.amount =
248
+ input.payment_intent.latest_charge.amount_captured =
249
+ amount;
250
+ expect(sdk.qualifyCapturedCheckoutPayment(input, expected)).toMatchObject({
251
+ status: "ready",
252
+ amount,
253
+ currency,
254
+ });
255
+ },
256
+ );
257
+
258
+ it("keeps captured history after refunds/disputes without asserting eligibility", () => {
259
+ const input = session();
260
+ Object.assign(input.payment_intent.latest_charge, {
261
+ refunded: true,
262
+ amount_refunded: 3500,
263
+ disputed: true,
264
+ balance_transaction: null,
265
+ application_fee: null,
266
+ invoice: null,
267
+ });
268
+ const result = sdk.qualifyCapturedCheckoutPayment(input, expected);
269
+ expect(result).toMatchObject({ status: "ready", amount: 3500 });
270
+ expect(result).not.toHaveProperty("refundable");
271
+ expect(result).not.toHaveProperty("payable");
272
+ });
@@ -0,0 +1,120 @@
1
+ import { z } from "zod";
2
+
3
+ const id = (prefix: string) =>
4
+ z
5
+ .string()
6
+ .max(255)
7
+ .regex(new RegExp(`^${prefix}_[A-Za-z0-9_]+$`));
8
+ const amount = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
9
+ const currency = z.string().regex(/^[a-z]{3}$/);
10
+ const metadata = z.record(z.string(), z.string());
11
+ const expectedSchema = z.object({
12
+ stripeSessionId: id("cs"),
13
+ customerAccountId: id("acct"),
14
+ livemode: z.boolean(),
15
+ });
16
+ const evidenceSchema = z.object({
17
+ id: id("cs"),
18
+ object: z.literal("checkout.session"),
19
+ mode: z.literal("payment"),
20
+ subscription: z.null(),
21
+ status: z.literal("complete"),
22
+ payment_status: z.literal("paid"),
23
+ customer_account: id("acct"),
24
+ livemode: z.boolean(),
25
+ amount_total: amount,
26
+ currency,
27
+ metadata,
28
+ payment_intent: z.object({
29
+ id: id("pi"),
30
+ object: z.literal("payment_intent"),
31
+ status: z.literal("succeeded"),
32
+ customer_account: id("acct"),
33
+ livemode: z.boolean(),
34
+ amount,
35
+ amount_received: amount,
36
+ currency,
37
+ metadata,
38
+ latest_charge: z.object({
39
+ id: id("ch"),
40
+ object: z.literal("charge"),
41
+ payment_intent: id("pi"),
42
+ status: z.literal("succeeded"),
43
+ paid: z.literal(true),
44
+ captured: z.literal(true),
45
+ livemode: z.boolean(),
46
+ amount,
47
+ amount_captured: amount,
48
+ currency,
49
+ }),
50
+ }),
51
+ });
52
+
53
+ /** Server-owned original selectors, not browser authorization or signed-event proof. */
54
+ export type CapturedCheckoutPaymentExpected = z.infer<typeof expectedSchema>;
55
+
56
+ export type CapturedCheckoutPaymentObservation =
57
+ | {
58
+ status: "ready";
59
+ stripeSessionId: string;
60
+ stripePaymentIntentId: string;
61
+ stripeChargeId: string;
62
+ customerAccountId: string;
63
+ livemode: boolean;
64
+ /** Integer original provider minor units, never converted to major-unit decimals. */
65
+ amount: number;
66
+ currency: string;
67
+ sessionMetadata: Record<string, string>;
68
+ paymentIntentMetadata: Record<string, string>;
69
+ }
70
+ | {
71
+ status: "unavailable";
72
+ reason: "invalid_context" | "invalid_evidence" | "identity_mismatch";
73
+ };
74
+
75
+ /**
76
+ * Qualify an already retrieved Session with payment_intent.latest_charge expanded.
77
+ * No I/O or writes. Captured history is not fulfillment, refund or settlement authority.
78
+ */
79
+ export function qualifyCapturedCheckoutPayment(
80
+ session: unknown,
81
+ expected: CapturedCheckoutPaymentExpected,
82
+ ): CapturedCheckoutPaymentObservation {
83
+ const scope = expectedSchema.safeParse(expected);
84
+ if (!scope.success)
85
+ return { status: "unavailable", reason: "invalid_context" };
86
+ const parsed = evidenceSchema.safeParse(session);
87
+ if (!parsed.success)
88
+ return { status: "unavailable", reason: "invalid_evidence" };
89
+ const paid = parsed.data;
90
+ const pi = paid.payment_intent;
91
+ const charge = pi.latest_charge;
92
+ if (
93
+ paid.id !== scope.data.stripeSessionId ||
94
+ paid.customer_account !== scope.data.customerAccountId ||
95
+ pi.customer_account !== scope.data.customerAccountId ||
96
+ paid.livemode !== scope.data.livemode ||
97
+ pi.livemode !== scope.data.livemode ||
98
+ charge.livemode !== scope.data.livemode ||
99
+ charge.payment_intent !== pi.id ||
100
+ pi.amount !== paid.amount_total ||
101
+ pi.amount_received !== paid.amount_total ||
102
+ charge.amount !== paid.amount_total ||
103
+ charge.amount_captured !== paid.amount_total ||
104
+ pi.currency !== paid.currency ||
105
+ charge.currency !== paid.currency
106
+ )
107
+ return { status: "unavailable", reason: "identity_mismatch" };
108
+ return {
109
+ status: "ready",
110
+ stripeSessionId: paid.id,
111
+ stripePaymentIntentId: pi.id,
112
+ stripeChargeId: charge.id,
113
+ customerAccountId: paid.customer_account,
114
+ livemode: paid.livemode,
115
+ amount: paid.amount_total,
116
+ currency: paid.currency,
117
+ sessionMetadata: paid.metadata,
118
+ paymentIntentMetadata: pi.metadata,
119
+ };
120
+ }
@@ -1,3 +1,8 @@
1
+ export { qualifyCapturedCheckoutPayment } from "./billing/capturedCheckoutPayment.js";
2
+ export type {
3
+ CapturedCheckoutPaymentExpected,
4
+ CapturedCheckoutPaymentObservation,
5
+ } from "./billing/capturedCheckoutPayment.js";
1
6
  export type {
2
7
  ProductIdentityResult,
3
8
  PriceIdentityResult,