@fantastic.dev/better-stripe 0.48.1 → 0.50.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 +34 -0
  2. package/README.md +1 -1
  3. package/dist/client/billing/invoicePaymentPages.d.ts +2 -5
  4. package/dist/client/billing/invoicePaymentPages.d.ts.map +1 -1
  5. package/dist/client/billing/invoicePaymentPages.js +2 -58
  6. package/dist/client/billing/invoicePaymentPages.js.map +1 -1
  7. package/dist/client/billing/invoicePaymentRead.d.ts +17 -0
  8. package/dist/client/billing/invoicePaymentRead.d.ts.map +1 -0
  9. package/dist/client/billing/invoicePaymentRead.js +25 -0
  10. package/dist/client/billing/invoicePaymentRead.js.map +1 -0
  11. package/dist/client/billing/invoicePaymentShared.d.ts +22 -0
  12. package/dist/client/billing/invoicePaymentShared.d.ts.map +1 -0
  13. package/dist/client/billing/invoicePaymentShared.js +62 -0
  14. package/dist/client/billing/invoicePaymentShared.js.map +1 -0
  15. package/dist/client/billing/setup-intent-read.d.ts +22 -0
  16. package/dist/client/billing/setup-intent-read.d.ts.map +1 -0
  17. package/dist/client/billing/setup-intent-read.js +63 -0
  18. package/dist/client/billing/setup-intent-read.js.map +1 -0
  19. package/dist/client/billing/subscription-payment-method.d.ts +28 -0
  20. package/dist/client/billing/subscription-payment-method.d.ts.map +1 -0
  21. package/dist/client/billing/subscription-payment-method.js +101 -0
  22. package/dist/client/billing/subscription-payment-method.js.map +1 -0
  23. package/dist/client/index.d.ts +9 -0
  24. package/dist/client/index.d.ts.map +1 -1
  25. package/dist/client/index.js +10 -0
  26. package/dist/client/index.js.map +1 -1
  27. package/dist/client/invoiceReads.d.ts +3 -0
  28. package/dist/client/invoiceReads.d.ts.map +1 -1
  29. package/dist/client/invoiceReads.js +5 -0
  30. package/dist/client/invoiceReads.js.map +1 -1
  31. package/dist/component/_generated/component.d.ts +1 -0
  32. package/dist/component/_generated/component.d.ts.map +1 -1
  33. package/dist/component/connect/queries.d.ts +1 -0
  34. package/dist/component/connect/queries.d.ts.map +1 -1
  35. package/dist/component/connect/queries.js +10 -4
  36. package/dist/component/connect/queries.js.map +1 -1
  37. package/dist/component/refundHistory/queries.d.ts +1 -1
  38. package/docs/invoice-payment-pages.md +62 -0
  39. package/docs/react-workflows.md +9 -0
  40. package/docs/read-contracts.md +45 -0
  41. package/docs/setup-intent-recovery.md +27 -0
  42. package/docs/subscription-payment-methods.md +121 -0
  43. package/package.json +4 -2
  44. package/src/client/billing/invoicePaymentPages.ts +9 -74
  45. package/src/client/billing/invoicePaymentRead.test.ts +233 -0
  46. package/src/client/billing/invoicePaymentRead.ts +44 -0
  47. package/src/client/billing/invoicePaymentReadTransport.test.ts +101 -0
  48. package/src/client/billing/invoicePaymentShared.ts +84 -0
  49. package/src/client/billing/setup-intent-read.test.ts +284 -0
  50. package/src/client/billing/setup-intent-read.ts +97 -0
  51. package/src/client/billing/subscription-payment-method.test.ts +460 -0
  52. package/src/client/billing/subscription-payment-method.ts +177 -0
  53. package/src/client/index.ts +39 -0
  54. package/src/client/invoiceReads.ts +9 -0
  55. package/src/component/_generated/component.ts +1 -1
  56. package/src/component/connect/payment-unique.test.ts +195 -0
  57. package/src/component/connect/queries.ts +9 -4
@@ -0,0 +1,460 @@
1
+ import Stripe from "stripe";
2
+ import { expect, it, vi } from "vitest";
3
+
4
+ import { STRIPE_API_VERSION } from "../constants.js";
5
+ import type { RunCtx } from "../helpers.js";
6
+ import { BetterStripe } from "../index.js";
7
+ import { components } from "../setup.test.js";
8
+
9
+ function fixture() {
10
+ const requests: {
11
+ path: string;
12
+ method: string;
13
+ body: string;
14
+ realm: string | null;
15
+ key: string | null;
16
+ }[] = [];
17
+ const original = {
18
+ id: "sub_original",
19
+ object: "subscription",
20
+ customer_account: "acct_original",
21
+ managed_payments: null,
22
+ default_payment_method: "pm_old",
23
+ status: "active",
24
+ };
25
+ const other = {
26
+ ...original,
27
+ id: "sub_other",
28
+ default_payment_method: "pm_other",
29
+ };
30
+ const card = {
31
+ id: "pm_original",
32
+ object: "payment_method",
33
+ type: "card",
34
+ customer_account: "acct_original",
35
+ };
36
+ const responses = new Map<string, Response>();
37
+ const beforeReply = new Map<string, () => void>();
38
+ const counts = new Map<string, number>();
39
+ const sdk = new Stripe("sk_test_subscription_card_fixture", {
40
+ apiVersion: STRIPE_API_VERSION,
41
+ maxNetworkRetries: 0,
42
+ httpClient: Stripe.createFetchHttpClient(async (url, init) => {
43
+ const path = new URL(String(url)).pathname;
44
+ const headers = new Headers(init?.headers);
45
+ const method = init?.method ?? "GET";
46
+ const body = String(init?.body ?? "");
47
+ requests.push({
48
+ path,
49
+ method,
50
+ body,
51
+ realm: headers.get("Stripe-Account"),
52
+ key: headers.get("Idempotency-Key"),
53
+ });
54
+ const requestKey = `${method} ${path}`;
55
+ const ordinal = (counts.get(requestKey) ?? 0) + 1;
56
+ counts.set(requestKey, ordinal);
57
+ beforeReply.get(`${requestKey} ${ordinal}`)?.();
58
+ const override =
59
+ responses.get(
60
+ `${headers.get("Stripe-Account") ?? "platform"} ${requestKey} ${ordinal}`,
61
+ ) ?? responses.get(`${requestKey} ${ordinal}`);
62
+ if (override) return override.clone();
63
+ if (method === "POST" && path === "/v1/subscriptions/sub_original") {
64
+ original.default_payment_method =
65
+ new URLSearchParams(body).get("default_payment_method") ??
66
+ original.default_payment_method;
67
+ }
68
+ const data = path.includes("/payment_methods/")
69
+ ? card
70
+ : path.endsWith("sub_other")
71
+ ? other
72
+ : original;
73
+ return new Response(JSON.stringify(data), {
74
+ status: 200,
75
+ headers: { "content-type": "application/json" },
76
+ });
77
+ }),
78
+ });
79
+ class Client extends BetterStripe {
80
+ protected override stripe() {
81
+ return sdk;
82
+ }
83
+ }
84
+ const client = new Client(components.betterStripe, {
85
+ STRIPE_SECRET_KEY: "sk_test_subscription_card_fixture",
86
+ });
87
+ const ctx: RunCtx = {
88
+ runQuery: async () => {
89
+ throw new Error("Unexpected component read");
90
+ },
91
+ };
92
+ const opts = {
93
+ stripeSubscriptionId: original.id,
94
+ customerAccount: original.customer_account,
95
+ paymentMethodId: card.id,
96
+ idempotencyKey: "subscription-card-original-command",
97
+ };
98
+ return {
99
+ client,
100
+ ctx,
101
+ opts,
102
+ original,
103
+ other,
104
+ card,
105
+ requests,
106
+ responses,
107
+ beforeReply,
108
+ sdk,
109
+ };
110
+ }
111
+
112
+ it("retains the actual public subscription provider read as a V2 payer positive control", async () => {
113
+ const f = fixture();
114
+ const result = await f.client.getSubscriptionFromStripe(f.ctx, {
115
+ stripeSubscriptionId: f.original.id,
116
+ });
117
+ expect(result).toMatchObject({
118
+ id: f.original.id,
119
+ customer_account: f.opts.customerAccount,
120
+ managed_payments: null,
121
+ });
122
+ expect(f.requests).toMatchObject([
123
+ { method: "GET", path: "/v1/subscriptions/sub_original" },
124
+ ]);
125
+ });
126
+
127
+ it("changes only the explicit existing subscription card and confirms through a fresh read", async () => {
128
+ const f = fixture();
129
+ const otherBefore = structuredClone(f.other);
130
+ expect(f.client).toHaveProperty(
131
+ "updateSubscriptionDefaultPaymentMethod",
132
+ expect.any(Function),
133
+ );
134
+ const result = await f.client.updateSubscriptionDefaultPaymentMethod(
135
+ f.ctx,
136
+ f.opts,
137
+ );
138
+ expect(result).toMatchObject({
139
+ status: "updated",
140
+ stripeSubscriptionId: f.opts.stripeSubscriptionId,
141
+ customerAccount: f.opts.customerAccount,
142
+ paymentMethodId: f.opts.paymentMethodId,
143
+ });
144
+ expect(f.other).toEqual(otherBefore);
145
+ expect(f.requests.map(({ method, path }) => ({ method, path }))).toEqual([
146
+ { method: "GET", path: "/v1/subscriptions/sub_original" },
147
+ { method: "GET", path: "/v1/payment_methods/pm_original" },
148
+ { method: "POST", path: "/v1/subscriptions/sub_original" },
149
+ { method: "GET", path: "/v1/subscriptions/sub_original" },
150
+ ]);
151
+ expect(f.requests[2]).toMatchObject({
152
+ body: "default_payment_method=pm_original",
153
+ key: f.opts.idempotencyKey,
154
+ });
155
+ });
156
+
157
+ function jsonResponse(body: object, status = 200) {
158
+ return new Response(JSON.stringify(body), {
159
+ status,
160
+ headers: { "content-type": "application/json" },
161
+ });
162
+ }
163
+
164
+ it.each([
165
+ ["subscription", "unavailable", "subscription_mismatch"],
166
+ ["payer", "unavailable", "payer_mismatch"],
167
+ ["legacy", "unsupported", "non_v2_payer"],
168
+ ["method", "unavailable", "method_mismatch"],
169
+ ["owner", "unavailable", "method_owner_mismatch"],
170
+ ["type", "unsupported", "non_card_method"],
171
+ ] as const)(
172
+ "rejects original %s conflicts before POST",
173
+ async (variant, status, reason) => {
174
+ const f = fixture();
175
+ if (variant === "subscription") f.original.id = "sub_foreign";
176
+ if (variant === "payer") f.original.customer_account = "acct_foreign";
177
+ if (variant === "legacy")
178
+ Object.assign(f.original, {
179
+ customer_account: null,
180
+ customer: "cus_legacy",
181
+ });
182
+ if (variant === "method") f.card.id = "pm_other";
183
+ if (variant === "owner") f.card.customer_account = "acct_foreign";
184
+ if (variant === "type") f.card.type = "sepa_debit";
185
+ expect(
186
+ await f.client.updateSubscriptionDefaultPaymentMethod(f.ctx, f.opts),
187
+ ).toEqual({ status, reason });
188
+ expect(f.requests.every((r) => r.method === "GET")).toBe(true);
189
+ },
190
+ );
191
+
192
+ it.each(["enabled", "missing", "malformed"] as const)(
193
+ "does not guess ordinary Managed Payments state from %s",
194
+ async (variant) => {
195
+ const f = fixture();
196
+ if (variant === "missing")
197
+ Reflect.deleteProperty(f.original, "managed_payments");
198
+ else
199
+ Object.assign(f.original, {
200
+ managed_payments: { enabled: variant === "enabled" ? true : "false" },
201
+ });
202
+ expect(
203
+ await f.client.updateSubscriptionDefaultPaymentMethod(f.ctx, f.opts),
204
+ ).toEqual({
205
+ status: "unsupported",
206
+ reason:
207
+ variant === "enabled" ? "managed_payments" : "unknown_managed_payments",
208
+ });
209
+ expect(f.requests).toHaveLength(1);
210
+ },
211
+ );
212
+
213
+ it("supports explicitly disabled Managed Payments and scopes every request to the same realm", async () => {
214
+ const f = fixture();
215
+ Object.assign(f.original, { managed_payments: { enabled: false } });
216
+ expect(
217
+ await f.client.updateSubscriptionDefaultPaymentMethod(f.ctx, {
218
+ ...f.opts,
219
+ connectedAccountId: "acct_merchant",
220
+ }),
221
+ ).toMatchObject({ status: "updated" });
222
+ expect(f.requests).toHaveLength(4);
223
+ expect(f.requests.every((r) => r.realm === "acct_merchant")).toBe(true);
224
+ expect(f.requests[2]?.key).toBe(f.opts.idempotencyKey);
225
+ });
226
+
227
+ it.each(["pre-read", "post", "fresh-read"] as const)(
228
+ "keeps %s provider failure distinct from confirmation",
229
+ async (phase) => {
230
+ const f = fixture();
231
+ const request =
232
+ phase === "pre-read"
233
+ ? "GET /v1/subscriptions/sub_original 1"
234
+ : phase === "post"
235
+ ? "POST /v1/subscriptions/sub_original 1"
236
+ : "GET /v1/subscriptions/sub_original 2";
237
+ f.responses.set(
238
+ request,
239
+ jsonResponse(
240
+ { error: { type: "api_error", message: "Synthetic unavailable" } },
241
+ 503,
242
+ ),
243
+ );
244
+ expect(
245
+ await f.client.updateSubscriptionDefaultPaymentMethod(f.ctx, f.opts),
246
+ ).toEqual(
247
+ phase === "pre-read"
248
+ ? { status: "unavailable", reason: "provider_read_unavailable" }
249
+ : { status: "unknown", reason: "provider_write_unconfirmed" },
250
+ );
251
+ },
252
+ );
253
+
254
+ it("does not confirm an old idempotent POST reply after a later card selection", async () => {
255
+ const f = fixture();
256
+ f.responses.set(
257
+ "POST /v1/subscriptions/sub_original 1",
258
+ jsonResponse({
259
+ ...f.original,
260
+ default_payment_method: f.opts.paymentMethodId,
261
+ }),
262
+ );
263
+ f.responses.set(
264
+ "GET /v1/subscriptions/sub_original 2",
265
+ jsonResponse({
266
+ ...f.original,
267
+ default_payment_method: "pm_later_selection",
268
+ }),
269
+ );
270
+ expect(
271
+ await f.client.updateSubscriptionDefaultPaymentMethod(f.ctx, f.opts),
272
+ ).toEqual({ status: "unknown", reason: "response_mismatch" });
273
+ expect(f.requests[f.requests.length - 1]?.method).toBe("GET");
274
+ });
275
+
276
+ it("accepts expanded card proof only when the original payer still agrees", async () => {
277
+ const f = fixture();
278
+ f.responses.set(
279
+ "POST /v1/subscriptions/sub_original 1",
280
+ jsonResponse({ ...f.original, default_payment_method: f.card }),
281
+ );
282
+ f.responses.set(
283
+ "GET /v1/subscriptions/sub_original 2",
284
+ jsonResponse({ ...f.original, default_payment_method: f.card }),
285
+ );
286
+ expect(
287
+ await f.client.updateSubscriptionDefaultPaymentMethod(f.ctx, f.opts),
288
+ ).toMatchObject({ status: "updated" });
289
+ });
290
+
291
+ it("does not confirm a response with a contradictory expanded card owner", async () => {
292
+ const f = fixture();
293
+ f.responses.set(
294
+ "POST /v1/subscriptions/sub_original 1",
295
+ jsonResponse({
296
+ ...f.original,
297
+ default_payment_method: { ...f.card, customer_account: "acct_foreign" },
298
+ }),
299
+ );
300
+ expect(
301
+ await f.client.updateSubscriptionDefaultPaymentMethod(f.ctx, f.opts),
302
+ ).toEqual({ status: "unknown", reason: "response_mismatch" });
303
+ });
304
+
305
+ it("forwards the unchanged original idempotency key and never touches the other subscription", async () => {
306
+ const f = fixture();
307
+ const other = structuredClone(f.other);
308
+ for (let i = 0; i < 2; i++)
309
+ expect(
310
+ await f.client.updateSubscriptionDefaultPaymentMethod(f.ctx, f.opts),
311
+ ).toMatchObject({ status: "updated" });
312
+ expect(
313
+ f.requests
314
+ .filter((r) => r.method === "POST")
315
+ .map((r) => ({ body: r.body, key: r.key })),
316
+ ).toEqual([
317
+ { body: "default_payment_method=pm_original", key: f.opts.idempotencyKey },
318
+ { body: "default_payment_method=pm_original", key: f.opts.idempotencyKey },
319
+ ]);
320
+ expect(f.other).toEqual(other);
321
+ });
322
+
323
+ it.each([
324
+ "paymentMethodId",
325
+ "stripeSubscriptionId",
326
+ "customerAccount",
327
+ "idempotencyKey",
328
+ ] as const)(
329
+ "rejects a malformed %s without provider traffic",
330
+ async (field) => {
331
+ const f = fixture();
332
+ expect(
333
+ await f.client.updateSubscriptionDefaultPaymentMethod(f.ctx, {
334
+ ...f.opts,
335
+ [field]: " bad selector ",
336
+ }),
337
+ ).toEqual({ status: "unavailable", reason: "invalid_selector" });
338
+ expect(f.requests).toHaveLength(0);
339
+ },
340
+ );
341
+
342
+ it("does not borrow a card from platform scope when it is absent in the selected connected realm", async () => {
343
+ const f = fixture();
344
+ f.responses.set(
345
+ "acct_merchant GET /v1/payment_methods/pm_original 1",
346
+ jsonResponse(
347
+ {
348
+ error: {
349
+ type: "invalid_request_error",
350
+ code: "resource_missing",
351
+ message: "No method in selected realm",
352
+ },
353
+ },
354
+ 404,
355
+ ),
356
+ );
357
+ expect(
358
+ await f.client.updateSubscriptionDefaultPaymentMethod(f.ctx, {
359
+ ...f.opts,
360
+ connectedAccountId: "acct_merchant",
361
+ }),
362
+ ).toEqual({ status: "unavailable", reason: "provider_read_unavailable" });
363
+ expect(
364
+ f.requests.every((r) => r.realm === "acct_merchant" && r.method === "GET"),
365
+ ).toBe(true);
366
+ expect(f.requests).toHaveLength(2);
367
+ });
368
+
369
+ it("keeps a lost accepted write unknown rather than inventing provider failure or success", async () => {
370
+ const f = fixture();
371
+ f.beforeReply.set("POST /v1/subscriptions/sub_original 1", () => {
372
+ f.original.default_payment_method = f.opts.paymentMethodId;
373
+ });
374
+ f.responses.set(
375
+ "POST /v1/subscriptions/sub_original 1",
376
+ jsonResponse(
377
+ {
378
+ error: {
379
+ type: "api_error",
380
+ message: "Synthetic response lost after acceptance",
381
+ },
382
+ },
383
+ 503,
384
+ ),
385
+ );
386
+ expect(
387
+ await f.client.updateSubscriptionDefaultPaymentMethod(f.ctx, f.opts),
388
+ ).toEqual({ status: "unknown", reason: "provider_write_unconfirmed" });
389
+ expect(f.original.default_payment_method).toBe(f.opts.paymentMethodId);
390
+ expect(f.requests.filter((r) => r.method === "POST")).toHaveLength(1);
391
+ });
392
+
393
+ it.each(["id", "payer", "managed", "method"] as const)(
394
+ "does not confirm fresh %s drift after a valid update reply",
395
+ async (variant) => {
396
+ const f = fixture();
397
+ const current = {
398
+ ...f.original,
399
+ default_payment_method: f.opts.paymentMethodId,
400
+ };
401
+ const contradiction =
402
+ variant === "id"
403
+ ? { id: "sub_foreign" }
404
+ : variant === "payer"
405
+ ? { customer_account: "acct_foreign" }
406
+ : variant === "managed"
407
+ ? { managed_payments: { enabled: true } }
408
+ : { default_payment_method: "pm_later_selection" };
409
+ f.responses.set(
410
+ "GET /v1/subscriptions/sub_original 2",
411
+ jsonResponse({ ...current, ...contradiction }),
412
+ );
413
+ expect(
414
+ await f.client.updateSubscriptionDefaultPaymentMethod(f.ctx, f.opts),
415
+ ).toEqual({ status: "unknown", reason: "response_mismatch" });
416
+ },
417
+ );
418
+
419
+ it("propagates unexpected programming failures instead of calling them a provider outcome", async () => {
420
+ const f = fixture();
421
+ vi.spyOn(f.sdk.subscriptions, "retrieve").mockRejectedValue(
422
+ new Error("Unexpected synthetic implementation failure"),
423
+ );
424
+ await expect(
425
+ f.client.updateSubscriptionDefaultPaymentMethod(f.ctx, f.opts),
426
+ ).rejects.toThrow("Unexpected synthetic implementation failure");
427
+ expect(f.requests).toHaveLength(0);
428
+ });
429
+
430
+ it("retains the invocation's original tuple when the caller changes its options during a read", async () => {
431
+ const f = fixture();
432
+ const input: Parameters<
433
+ BetterStripe["updateSubscriptionDefaultPaymentMethod"]
434
+ >[1] = { ...f.opts };
435
+ const original = { ...input };
436
+ const other = structuredClone(f.other);
437
+ f.beforeReply.set("GET /v1/payment_methods/pm_original 1", () => {
438
+ input.stripeSubscriptionId = f.other.id;
439
+ input.customerAccount = "acct_replacement";
440
+ input.paymentMethodId = "pm_replacement";
441
+ input.idempotencyKey = "replacement-command";
442
+ input.connectedAccountId = "acct_replacement_realm";
443
+ });
444
+ const result = await f.client.updateSubscriptionDefaultPaymentMethod(
445
+ f.ctx,
446
+ input,
447
+ );
448
+ expect(f.requests.filter((r) => r.method === "POST")).toMatchObject([
449
+ {
450
+ path: `/v1/subscriptions/${original.stripeSubscriptionId}`,
451
+ key: original.idempotencyKey,
452
+ },
453
+ ]);
454
+ expect(result).toMatchObject({
455
+ status: "updated",
456
+ stripeSubscriptionId: original.stripeSubscriptionId,
457
+ });
458
+ expect(f.requests.every((r) => r.realm === null)).toBe(true);
459
+ expect(f.other).toEqual(other);
460
+ });
@@ -0,0 +1,177 @@
1
+ import Stripe from "stripe";
2
+
3
+ import { getSubscriptionFromStripe } from "./providerReads.js";
4
+
5
+ /** Trusted host selectors only; authenticate and freeze this entire tuple before calling. */
6
+ export type SubscriptionPaymentMethodOptions = {
7
+ stripeSubscriptionId: string;
8
+ customerAccount: string;
9
+ paymentMethodId: string;
10
+ idempotencyKey: string;
11
+ connectedAccountId?: string;
12
+ };
13
+
14
+ export type SubscriptionPaymentMethodResult =
15
+ | {
16
+ status: "updated";
17
+ stripeSubscriptionId: string;
18
+ customerAccount: string;
19
+ paymentMethodId: string;
20
+ observedAt: number;
21
+ }
22
+ | {
23
+ status: "unsupported";
24
+ reason:
25
+ | "managed_payments"
26
+ | "unknown_managed_payments"
27
+ | "non_v2_payer"
28
+ | "non_card_method";
29
+ }
30
+ | {
31
+ status: "unavailable";
32
+ reason:
33
+ | "invalid_selector"
34
+ | "subscription_mismatch"
35
+ | "payer_mismatch"
36
+ | "method_mismatch"
37
+ | "method_owner_mismatch"
38
+ | "provider_read_unavailable";
39
+ }
40
+ | {
41
+ status: "unknown";
42
+ reason: "provider_write_unconfirmed" | "response_mismatch";
43
+ };
44
+
45
+ function isValidOptions(opts: SubscriptionPaymentMethodOptions) {
46
+ const identifiers: [string, RegExp][] = [
47
+ [opts.stripeSubscriptionId, /^sub_[A-Za-z0-9_]+$/],
48
+ [opts.customerAccount, /^acct_[A-Za-z0-9_]+$/],
49
+ [opts.paymentMethodId, /^pm_[A-Za-z0-9_]+$/],
50
+ ];
51
+ if (opts.connectedAccountId !== undefined)
52
+ identifiers.push([opts.connectedAccountId, /^acct_[A-Za-z0-9_]+$/]);
53
+ return (
54
+ identifiers.every(
55
+ ([value, pattern]) =>
56
+ typeof value === "string" && value.length <= 255 && pattern.test(value),
57
+ ) &&
58
+ typeof opts.idempotencyKey === "string" &&
59
+ opts.idempotencyKey.length > 0 &&
60
+ opts.idempotencyKey.length <= 255 &&
61
+ opts.idempotencyKey.trim() === opts.idempotencyKey &&
62
+ !/[\u0000-\u001f\u007f]/.test(opts.idempotencyKey)
63
+ );
64
+ }
65
+
66
+ function originalSubscriptionFailure(
67
+ subscription: Stripe.Subscription,
68
+ opts: SubscriptionPaymentMethodOptions,
69
+ ): Extract<
70
+ SubscriptionPaymentMethodResult,
71
+ { status: "unsupported" | "unavailable" }
72
+ > | null {
73
+ if (subscription.id !== opts.stripeSubscriptionId)
74
+ return { status: "unavailable", reason: "subscription_mismatch" };
75
+ if (typeof subscription.customer_account !== "string")
76
+ return { status: "unsupported", reason: "non_v2_payer" };
77
+ if (subscription.customer_account !== opts.customerAccount)
78
+ return { status: "unavailable", reason: "payer_mismatch" };
79
+ if (subscription.managed_payments?.enabled === true)
80
+ return { status: "unsupported", reason: "managed_payments" };
81
+ if (
82
+ subscription.managed_payments !== null &&
83
+ subscription.managed_payments?.enabled !== false
84
+ )
85
+ return { status: "unsupported", reason: "unknown_managed_payments" };
86
+ return null;
87
+ }
88
+
89
+ function isConfirmedSelection(
90
+ subscription: Stripe.Subscription,
91
+ opts: SubscriptionPaymentMethodOptions,
92
+ ) {
93
+ if (originalSubscriptionFailure(subscription, opts)) return false;
94
+ const method = subscription.default_payment_method;
95
+ return typeof method === "string"
96
+ ? method === opts.paymentMethodId
97
+ : method?.id === opts.paymentMethodId &&
98
+ method.type === "card" &&
99
+ method.customer_account === opts.customerAccount;
100
+ }
101
+
102
+ /** Platform reads reuse the existing provider reader; explicit Connect scope stays unchanged on every call. */
103
+ function readOriginalSubscription(
104
+ stripe: Stripe,
105
+ opts: SubscriptionPaymentMethodOptions,
106
+ ) {
107
+ return opts.connectedAccountId === undefined
108
+ ? getSubscriptionFromStripe(stripe, {
109
+ stripeSubscriptionId: opts.stripeSubscriptionId,
110
+ })
111
+ : stripe.subscriptions.retrieve(
112
+ opts.stripeSubscriptionId,
113
+ {},
114
+ { stripeAccount: opts.connectedAccountId },
115
+ );
116
+ }
117
+
118
+ /** One SDK update, then a fresh observation. No package retry, shared default update, charge or component write. */
119
+ export async function updateSubscriptionDefaultPaymentMethod(
120
+ stripe: Stripe,
121
+ input: SubscriptionPaymentMethodOptions,
122
+ ): Promise<SubscriptionPaymentMethodResult> {
123
+ const opts: SubscriptionPaymentMethodOptions = {
124
+ stripeSubscriptionId: input.stripeSubscriptionId,
125
+ customerAccount: input.customerAccount,
126
+ paymentMethodId: input.paymentMethodId,
127
+ idempotencyKey: input.idempotencyKey,
128
+ connectedAccountId: input.connectedAccountId,
129
+ };
130
+ if (!isValidOptions(opts))
131
+ return { status: "unavailable", reason: "invalid_selector" };
132
+ const realm =
133
+ opts.connectedAccountId === undefined
134
+ ? undefined
135
+ : { stripeAccount: opts.connectedAccountId };
136
+ let isDispatched = false;
137
+ try {
138
+ const original = await readOriginalSubscription(stripe, opts);
139
+ const failure = originalSubscriptionFailure(original, opts);
140
+ if (failure) return failure;
141
+ const method = await stripe.paymentMethods.retrieve(
142
+ opts.paymentMethodId,
143
+ {},
144
+ realm,
145
+ );
146
+ if (method.id !== opts.paymentMethodId)
147
+ return { status: "unavailable", reason: "method_mismatch" };
148
+ if (method.type !== "card")
149
+ return { status: "unsupported", reason: "non_card_method" };
150
+ if (method.customer_account !== opts.customerAccount)
151
+ return { status: "unavailable", reason: "method_owner_mismatch" };
152
+ isDispatched = true;
153
+ const updated = await stripe.subscriptions.update(
154
+ opts.stripeSubscriptionId,
155
+ { default_payment_method: opts.paymentMethodId },
156
+ { ...realm, idempotencyKey: opts.idempotencyKey },
157
+ );
158
+ if (!isConfirmedSelection(updated, opts))
159
+ return { status: "unknown", reason: "response_mismatch" };
160
+ // An idempotent POST can replay an old selection. Only a new GET can confirm current state.
161
+ const current = await readOriginalSubscription(stripe, opts);
162
+ if (!isConfirmedSelection(current, opts))
163
+ return { status: "unknown", reason: "response_mismatch" };
164
+ return {
165
+ status: "updated",
166
+ stripeSubscriptionId: opts.stripeSubscriptionId,
167
+ customerAccount: opts.customerAccount,
168
+ paymentMethodId: opts.paymentMethodId,
169
+ observedAt: Date.now(),
170
+ };
171
+ } catch (error) {
172
+ if (!(error instanceof Stripe.errors.StripeError)) throw error;
173
+ if (isDispatched)
174
+ return { status: "unknown", reason: "provider_write_unconfirmed" };
175
+ return { status: "unavailable", reason: "provider_read_unavailable" };
176
+ }
177
+ }
@@ -1,3 +1,9 @@
1
+ import * as setupIntentRead from "./billing/setup-intent-read.js";
2
+ export type {
3
+ SetupIntentReadOptions,
4
+ SetupIntentObservation,
5
+ } from "./billing/setup-intent-read.js";
6
+ import * as subscriptionPaymentMethod from "./billing/subscription-payment-method.js";
1
7
  import type {
2
8
  AccountByStripeIdOptions,
3
9
  SubscriptionByStripeIdOptions,
@@ -80,6 +86,10 @@ export type {
80
86
  CouponReadOptions,
81
87
  } from "./billing/providerReads.js";
82
88
  import * as providerReads from "./billing/providerReads.js";
89
+ export type {
90
+ InvoicePaymentReadOptions,
91
+ ProviderInvoicePaymentRead,
92
+ } from "./billing/invoicePaymentRead.js";
83
93
  export type {
84
94
  InvoicePaymentPageOptions,
85
95
  ProviderInvoicePaymentPage,
@@ -1123,6 +1133,30 @@ export class BetterStripe extends PaymentSourceClient {
1123
1133
  ) {
1124
1134
  return providerReads.getCheckoutSessionFromStripe(this.stripe(), opts);
1125
1135
  }
1136
+ /** Host-authorized existing subscription card selection; never an account-wide default. */
1137
+ updateSubscriptionDefaultPaymentMethod(
1138
+ _ctx: RunCtx,
1139
+ opts: subscriptionPaymentMethod.SubscriptionPaymentMethodOptions,
1140
+ ) {
1141
+ return subscriptionPaymentMethod.updateSubscriptionDefaultPaymentMethod(
1142
+ this.stripe(),
1143
+ opts,
1144
+ );
1145
+ }
1146
+
1147
+ /** Qualified existing setup observation. Host must authenticate the original request. */
1148
+ getSetupIntentFromStripe(
1149
+ ctx: RunCtx,
1150
+ opts: setupIntentRead.SetupIntentReadOptions,
1151
+ ) {
1152
+ return setupIntentRead.getSetupIntentFromStripe(
1153
+ this.stripe(),
1154
+ this.component,
1155
+ ctx,
1156
+ opts,
1157
+ );
1158
+ }
1159
+
1126
1160
  async getSubscriptionFromStripe(
1127
1161
  _ctx: RunCtx,
1128
1162
  opts: providerReads.SubscriptionReadOptions,
@@ -1776,3 +1810,8 @@ export class BetterStripe extends PaymentSourceClient {
1776
1810
  return { syncWebhook, asyncWebhook };
1777
1811
  }
1778
1812
  }
1813
+
1814
+ export type {
1815
+ SubscriptionPaymentMethodOptions,
1816
+ SubscriptionPaymentMethodResult,
1817
+ } from "./billing/subscription-payment-method.js";