better-ship 0.21.0 → 0.22.0

package/dist/stripe/client.d.ts

@@ -0,0 +1,13 @@
+import Stripe from "stripe";
+//#region src/infrastructure/stripe/client.d.ts
+/** Default SDK retries; client configuration and individual requests can override this value. */
+export declare const STRIPE_REQUEST_OPTIONS: Readonly<{
+  maxNetworkRetries: 2;
+}>;
+/**
+ * Construct a native Stripe client with fetch transport and two SDK retries by default.
+ * Native configuration overrides these defaults. Inject the client into application services.
+ */
+export declare function createStripeClient(secretKey: string, options?: Stripe.StripeConfig): Stripe;
+//#endregion
+//# sourceMappingURL=client.d.ts.map

package/dist/stripe/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","names":[],"sources":["../../src/infrastructure/stripe/client.ts"],"mappings":";;;qBAGa,wBAAsB;EAAA;;;;;;wBAMnB,mBAAmB,mBAAmB,UAAS,OAAO,eAAoB"}

package/dist/stripe/client.js

@@ -0,0 +1,20 @@
+import Stripe from "stripe";
+
+//#region src/infrastructure/stripe/client.ts
+/** Default SDK retries; client configuration and individual requests can override this value. */
+const STRIPE_REQUEST_OPTIONS = Object.freeze({ maxNetworkRetries: 2 });
+/**
+* Construct a native Stripe client with fetch transport and two SDK retries by default.
+* Native configuration overrides these defaults. Inject the client into application services.
+*/
+function createStripeClient(secretKey, options = {}) {
+	return new Stripe(secretKey, {
+		httpClient: Stripe.createFetchHttpClient(),
+		...STRIPE_REQUEST_OPTIONS,
+		...options
+	});
+}
+
+//#endregion
+export { STRIPE_REQUEST_OPTIONS, createStripeClient };
+//# sourceMappingURL=client.js.map

package/dist/stripe/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":[],"sources":["../../src/infrastructure/stripe/client.ts"],"sourcesContent":["import Stripe from 'stripe'\n\n/** Default SDK retries; client configuration and individual requests can override this value. */\nexport const STRIPE_REQUEST_OPTIONS = Object.freeze({ maxNetworkRetries: 2 })\n\n/**\n * Construct a native Stripe client with fetch transport and two SDK retries by default.\n * Native configuration overrides these defaults. Inject the client into application services.\n */\nexport function createStripeClient(secretKey: string, options: Stripe.StripeConfig = {}): Stripe {\n  return new Stripe(secretKey, {\n    httpClient: Stripe.createFetchHttpClient(),\n    ...STRIPE_REQUEST_OPTIONS,\n    ...options,\n  })\n}\n"],"mappings":";;;;AAGA,MAAa,yBAAyB,OAAO,OAAO,EAAE,mBAAmB,EAAE,CAAC;;;;;AAM5E,SAAgB,mBAAmB,WAAmB,UAA+B,CAAC,GAAW;CAC/F,OAAO,IAAI,OAAO,WAAW;EAC3B,YAAY,OAAO,sBAAsB;EACzC,GAAG;EACH,GAAG;CACL,CAAC;AACH"}

package/dist/stripe/event-map.d.ts

@@ -0,0 +1,14 @@
+import Stripe from "stripe";
+//#region src/infrastructure/stripe/event-map.d.ts
+type EventObject<K extends Stripe.Event['type']> = Extract<Stripe.Event, {
+  type: K;
+}>['data']['object'];
+/**
+ * Convert verified Stripe events with callbacks typed to each event's object.
+ * Unmapped events return undefined. Applications own validation and payment policy.
+ */
+export declare function stripeEventMap<T>(map: { [K in Stripe.Event['type']]?: (object: EventObject<K>) => T; }): (event: Stripe.Event) => T | undefined;
+/** Identify one Stripe event delivery; different events for one payment retain different IDs. */
+export declare function stripeEventId(event: Stripe.Event): string;
+//#endregion
+//# sourceMappingURL=event-map.d.ts.map

package/dist/stripe/event-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-map.d.ts","names":[],"sources":["../../src/infrastructure/stripe/event-map.ts"],"mappings":";;KAEK,YAAY,UAAU,OAAO,iBAAiB,QACjD,OAAO;EACL,MAAM;;;;;;wBAOM,eAAe,GAAG,QAC/B,KAAK,OAAO,kBAAkB,QAAQ,YAAY,OAAO,QACvD,OAAO,OAAO,UAAU;;wBASb,cAAc,OAAO,OAAO"}

package/dist/stripe/event-map.js

@@ -0,0 +1,19 @@
+//#region src/infrastructure/stripe/event-map.ts
+/**
+* Convert verified Stripe events with callbacks typed to each event's object.
+* Unmapped events return undefined. Applications own validation and payment policy.
+*/
+function stripeEventMap(map) {
+	const handlers = map;
+	return (event) => {
+		return handlers[event.type]?.(event.data.object);
+	};
+}
+/** Identify one Stripe event delivery; different events for one payment retain different IDs. */
+function stripeEventId(event) {
+	return `stripe:event:${event.id}`;
+}
+
+//#endregion
+export { stripeEventId, stripeEventMap };
+//# sourceMappingURL=event-map.js.map

package/dist/stripe/event-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-map.js","names":[],"sources":["../../src/infrastructure/stripe/event-map.ts"],"sourcesContent":["import type Stripe from 'stripe'\n\ntype EventObject<K extends Stripe.Event['type']> = Extract<\n  Stripe.Event,\n  { type: K }\n>['data']['object']\n\n/**\n * Convert verified Stripe events with callbacks typed to each event's object.\n * Unmapped events return undefined. Applications own validation and payment policy.\n */\nexport function stripeEventMap<T>(map: {\n  [K in Stripe.Event['type']]?: (object: EventObject<K>) => T\n}): (event: Stripe.Event) => T | undefined {\n  const handlers: Partial<Record<Stripe.Event['type'], (object: never) => T>> = map\n  return (event) => {\n    // SAFETY: The map binds each event type to its object; indexed lookup loses that correlation.\n    return handlers[event.type]?.(event.data.object as never)\n  }\n}\n\n/** Identify one Stripe event delivery; different events for one payment retain different IDs. */\nexport function stripeEventId(event: Stripe.Event): string {\n  return `stripe:event:${event.id}`\n}\n"],"mappings":";;;;;AAWA,SAAgB,eAAkB,KAES;CACzC,MAAM,WAAwE;CAC9E,QAAQ,UAAU;EAEhB,OAAO,SAAS,MAAM,KAAK,GAAG,MAAM,KAAK,MAAe;CAC1D;AACF;;AAGA,SAAgB,cAAc,OAA6B;CACzD,OAAO,gBAAgB,MAAM;AAC/B"}

package/dist/stripe/payment-service.d.ts

@@ -14,7 +14,7 @@ export type CheckoutResult = Awaited<ReturnType<Stripe['checkout']['sessions']['
 export type PaymentResult = Awaited<ReturnType<Stripe['paymentIntents']['create']>>;
 /**
  * Stripe payment operations, with native types and stable keys for mutations.
- * Rejects with PaymentServiceError or native StripeCardError; unexpected defects propagate.
+ * Rejects with PaymentServiceError for Stripe failures; non-Stripe failures propagate unchanged.
  */
 export interface IPaymentService {
   /** Create a customer; the application owns persistence and reuse of the customer link. */
@@ -23,14 +23,14 @@ export interface IPaymentService {
   createCheckout(input: CheckoutInput, options: PaymentRequestOptions): Promise<CheckoutResult>;
   /** Create checkout in setup mode. The application records consent and verifies the saved method's owner. */
   setupPaymentMethod(input: CheckoutInput, options: PaymentRequestOptions): Promise<CheckoutResult>;
-  /** Confirm a saved method off-session. Native card errors can require customer authentication. */
+  /** Confirm a saved method off-session. PaymentServiceError retains card errors in cause. */
   chargeSavedMethod(input: SavedMethodCharge, options: PaymentRequestOptions): Promise<PaymentResult>;
   /** Retrieve an existing payment without starting another payment attempt. */
   getPayment(paymentId: string, params?: Stripe.PaymentIntentRetrieveParams, options?: Stripe.RequestOptions): Promise<PaymentResult>;
 }
 /**
  * Ported from Typist's StripeClient request boundary; the native SDK now owns retries.
- * Each request defaults to two SDK retries. Native request options can override retries and timeout.
+ * The injected client owns retry and timeout defaults. Native request options can override them.
  */
 export declare class StripePaymentService implements IPaymentService {
   private readonly stripe;
@@ -42,11 +42,10 @@ export declare class StripePaymentService implements IPaymentService {
   createCheckout(input: CheckoutInput, options: PaymentRequestOptions): Promise<CheckoutResult>;
   /** Force setup mode after caller parameters; this operation does not charge the customer. */
   setupPaymentMethod(input: CheckoutInput, options: PaymentRequestOptions): Promise<CheckoutResult>;
-  /** Force confirmation and off-session use; preserve native card failures for application handling. */
+  /** Force confirmation and off-session use; retain native card failures in PaymentServiceError.cause. */
   chargeSavedMethod(input: SavedMethodCharge, options: PaymentRequestOptions): Promise<PaymentResult>;
   /** Preserve every native status and response field when reconciling an existing payment. */
   getPayment(paymentId: string, params?: Stripe.PaymentIntentRetrieveParams, options?: Stripe.RequestOptions): Promise<PaymentResult>;
-  private request;
 }
 //#endregion
 //# sourceMappingURL=payment-service.d.ts.map

package/dist/stripe/payment-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"payment-service.d.ts","names":[],"sources":["../../src/infrastructure/stripe/payment-service.ts"],"mappings":";;;YAKY,wBAAwB,OAAO,iBACzC,SAAS,KAAK,OAAO;;YAGX,gBAAgB,KAAK,OAAO,SAAS;;YAGrC,oBAAoB,KAAK,OAAO,wDAC1C,SAAS,KAAK,OAAO;;YAGX,iBAAiB,QAAQ,WAAW;;YAGpC,iBAAiB,QAAQ,WAAW;;YAGpC,gBAAgB,QAAQ,WAAW;;;;;iBAM9B;;EAEf,eACE,OAAO,OAAO,sBACd,SAAS,wBACR,QAAQ;;EAEX,eAAe,OAAO,eAAe,SAAS,wBAAwB,QAAQ;;EAE9E,mBAAmB,OAAO,eAAe,SAAS,wBAAwB,QAAQ;;EAElF,kBACE,OAAO,mBACP,SAAS,wBACR,QAAQ;;EAEX,WACE,mBACA,SAAS,OAAO,6BAChB,UAAU,OAAO,iBAChB,QAAQ;;;;;;qBAOA,gCAAgC;mBAEd;;EAA7B,YAA6B,QAAQ;;EAGrC,eACE,OAAO,OAAO,sBACd,SAAS,wBACR,QAAQ;;EAOX,eAAe,OAAO,eAAe,SAAS,wBAAwB,QAAQ;;EAU9E,mBACE,OAAO,eACP,SAAS,wBACR,QAAQ;;EAUX,kBACE,OAAO,mBACP,SAAS,wBACR,QAAQ;;EAUX,WACE,mBACA,SAAS,OAAO,6BAChB,UAAU,OAAO,iBAChB,QAAQ;UAMG"}
+{"version":3,"file":"payment-service.d.ts","names":[],"sources":["../../src/infrastructure/stripe/payment-service.ts"],"mappings":";;;YAKY,wBAAwB,OAAO,iBACzC,SAAS,KAAK,OAAO;;YAGX,gBAAgB,KAAK,OAAO,SAAS;;YAGrC,oBAAoB,KAAK,OAAO,wDAC1C,SAAS,KAAK,OAAO;;YAGX,iBAAiB,QAAQ,WAAW;;YAGpC,iBAAiB,QAAQ,WAAW;;YAGpC,gBAAgB,QAAQ,WAAW;;;;;iBAM9B;;EAEf,eACE,OAAO,OAAO,sBACd,SAAS,wBACR,QAAQ;;EAEX,eAAe,OAAO,eAAe,SAAS,wBAAwB,QAAQ;;EAE9E,mBAAmB,OAAO,eAAe,SAAS,wBAAwB,QAAQ;;EAElF,kBACE,OAAO,mBACP,SAAS,wBACR,QAAQ;;EAEX,WACE,mBACA,SAAS,OAAO,6BAChB,UAAU,OAAO,iBAChB,QAAQ;;;;;;qBAOA,gCAAgC;mBAEd;;EAA7B,YAA6B,QAAQ;;EAGrC,eACE,OAAO,OAAO,sBACd,SAAS,wBACR,QAAQ;;EAKX,eAAe,OAAO,eAAe,SAAS,wBAAwB,QAAQ;;EAO9E,mBACE,OAAO,eACP,SAAS,wBACR,QAAQ;;EAOX,kBACE,OAAO,mBACP,SAAS,wBACR,QAAQ;;EAOX,WACE,mBACA,SAAS,OAAO,6BAChB,UAAU,OAAO,iBAChB,QAAQ"}

package/dist/stripe/payment-service.error.js

@@ -18,7 +18,7 @@ function classifyStripeError(error) {
 	if (error.headers?.["stripe-should-retry"] === "false") return "terminal";
 	const status = error.statusCode;
 	if (status !== void 0 && status >= 400 && status < 500 && status !== 409 && status !== 429) return "terminal";
-	if (error instanceof Stripe.errors.StripeAuthenticationError || error instanceof Stripe.errors.StripePermissionError || error instanceof Stripe.errors.StripeInvalidRequestError || error instanceof Stripe.errors.StripeIdempotencyError) return "terminal";
+	if (error instanceof Stripe.errors.StripeAuthenticationError || error instanceof Stripe.errors.StripePermissionError || error instanceof Stripe.errors.StripeInvalidRequestError || error instanceof Stripe.errors.StripeIdempotencyError || error instanceof Stripe.errors.StripeCardError) return "terminal";
 	if (error.headers?.["stripe-should-retry"] === "true") return "transient";
 	if (status === 409 || status === 429 || status !== void 0 && status >= 500) return "transient";
 	if (error instanceof Stripe.errors.StripeConnectionError || error instanceof Stripe.errors.StripeAPIError || error instanceof Stripe.errors.StripeRateLimitError) return "transient";

package/dist/stripe/payment-service.error.js.map

@@ -1 +1 @@
-{"version":3,"file":"payment-service.error.js","names":[],"sources":["../../src/infrastructure/stripe/payment-service.error.ts"],"sourcesContent":["import Stripe from 'stripe'\n\nimport { AppError, type FailureClassification } from '@/core'\n\n/** A final Stripe request failure. The caller logs once; native details remain in cause. */\nexport class PaymentServiceError extends AppError {\n  readonly _tag = 'PaymentServiceError'\n  readonly classification: FailureClassification\n\n  /** Classify the final SDK error without scheduling another payment attempt. */\n  constructor(\n    readonly operation: string,\n    cause: Stripe.errors.StripeError,\n  ) {\n    super(`Stripe request failed: ${operation}`, { cause })\n    this.classification = classifyStripeError(cause)\n  }\n}\n\nfunction classifyStripeError(error: Stripe.errors.StripeError): FailureClassification {\n  if (error.headers?.['stripe-should-retry'] === 'false') return 'terminal'\n  const status = error.statusCode\n  if (status !== undefined && status >= 400 && status < 500 && status !== 409 && status !== 429)\n    return 'terminal'\n  if (\n    error instanceof Stripe.errors.StripeAuthenticationError ||\n    error instanceof Stripe.errors.StripePermissionError ||\n    error instanceof Stripe.errors.StripeInvalidRequestError ||\n    error instanceof Stripe.errors.StripeIdempotencyError\n  )\n    return 'terminal'\n  if (error.headers?.['stripe-should-retry'] === 'true') return 'transient'\n  if (status === 409 || status === 429 || (status !== undefined && status >= 500))\n    return 'transient'\n  if (\n    error instanceof Stripe.errors.StripeConnectionError ||\n    error instanceof Stripe.errors.StripeAPIError ||\n    error instanceof Stripe.errors.StripeRateLimitError\n  )\n    return 'transient'\n  return 'unknown'\n}\n"],"mappings":";;;;;AAKA,IAAa,sBAAb,cAAyC,SAAS;CAMrC;CALX,AAAS,OAAO;CAChB,AAAS;;CAGT,YACE,AAAS,WACT,OACA;EACA,MAAM,0BAA0B,aAAa,EAAE,MAAM,CAAC;EAH7C;EAIT,KAAK,iBAAiB,oBAAoB,KAAK;CACjD;AACF;AAEA,SAAS,oBAAoB,OAAyD;CACpF,IAAI,MAAM,UAAU,2BAA2B,SAAS,OAAO;CAC/D,MAAM,SAAS,MAAM;CACrB,IAAI,WAAW,UAAa,UAAU,OAAO,SAAS,OAAO,WAAW,OAAO,WAAW,KACxF,OAAO;CACT,IACE,iBAAiB,OAAO,OAAO,6BAC/B,iBAAiB,OAAO,OAAO,yBAC/B,iBAAiB,OAAO,OAAO,6BAC/B,iBAAiB,OAAO,OAAO,wBAE/B,OAAO;CACT,IAAI,MAAM,UAAU,2BAA2B,QAAQ,OAAO;CAC9D,IAAI,WAAW,OAAO,WAAW,OAAQ,WAAW,UAAa,UAAU,KACzE,OAAO;CACT,IACE,iBAAiB,OAAO,OAAO,yBAC/B,iBAAiB,OAAO,OAAO,kBAC/B,iBAAiB,OAAO,OAAO,sBAE/B,OAAO;CACT,OAAO;AACT"}
+{"version":3,"file":"payment-service.error.js","names":[],"sources":["../../src/infrastructure/stripe/payment-service.error.ts"],"sourcesContent":["import Stripe from 'stripe'\n\nimport { AppError, type FailureClassification } from '@/core'\n\n/** A final Stripe request failure. The caller logs once; native details remain in cause. */\nexport class PaymentServiceError extends AppError {\n  readonly _tag = 'PaymentServiceError'\n  readonly classification: FailureClassification\n\n  /** Classify the final SDK error without scheduling another payment attempt. */\n  constructor(\n    readonly operation: string,\n    cause: Stripe.errors.StripeError,\n  ) {\n    super(`Stripe request failed: ${operation}`, { cause })\n    this.classification = classifyStripeError(cause)\n  }\n}\n\nfunction classifyStripeError(error: Stripe.errors.StripeError): FailureClassification {\n  if (error.headers?.['stripe-should-retry'] === 'false') return 'terminal'\n  const status = error.statusCode\n  if (status !== undefined && status >= 400 && status < 500 && status !== 409 && status !== 429)\n    return 'terminal'\n  if (\n    error instanceof Stripe.errors.StripeAuthenticationError ||\n    error instanceof Stripe.errors.StripePermissionError ||\n    error instanceof Stripe.errors.StripeInvalidRequestError ||\n    error instanceof Stripe.errors.StripeIdempotencyError ||\n    error instanceof Stripe.errors.StripeCardError\n  )\n    return 'terminal'\n  if (error.headers?.['stripe-should-retry'] === 'true') return 'transient'\n  if (status === 409 || status === 429 || (status !== undefined && status >= 500))\n    return 'transient'\n  if (\n    error instanceof Stripe.errors.StripeConnectionError ||\n    error instanceof Stripe.errors.StripeAPIError ||\n    error instanceof Stripe.errors.StripeRateLimitError\n  )\n    return 'transient'\n  return 'unknown'\n}\n"],"mappings":";;;;;AAKA,IAAa,sBAAb,cAAyC,SAAS;CAMrC;CALX,AAAS,OAAO;CAChB,AAAS;;CAGT,YACE,AAAS,WACT,OACA;EACA,MAAM,0BAA0B,aAAa,EAAE,MAAM,CAAC;EAH7C;EAIT,KAAK,iBAAiB,oBAAoB,KAAK;CACjD;AACF;AAEA,SAAS,oBAAoB,OAAyD;CACpF,IAAI,MAAM,UAAU,2BAA2B,SAAS,OAAO;CAC/D,MAAM,SAAS,MAAM;CACrB,IAAI,WAAW,UAAa,UAAU,OAAO,SAAS,OAAO,WAAW,OAAO,WAAW,KACxF,OAAO;CACT,IACE,iBAAiB,OAAO,OAAO,6BAC/B,iBAAiB,OAAO,OAAO,yBAC/B,iBAAiB,OAAO,OAAO,6BAC/B,iBAAiB,OAAO,OAAO,0BAC/B,iBAAiB,OAAO,OAAO,iBAE/B,OAAO;CACT,IAAI,MAAM,UAAU,2BAA2B,QAAQ,OAAO;CAC9D,IAAI,WAAW,OAAO,WAAW,OAAQ,WAAW,UAAa,UAAU,KACzE,OAAO;CACT,IACE,iBAAiB,OAAO,OAAO,yBAC/B,iBAAiB,OAAO,OAAO,kBAC/B,iBAAiB,OAAO,OAAO,sBAE/B,OAAO;CACT,OAAO;AACT"}

package/dist/stripe/payment-service.js

@@ -1,10 +1,9 @@
-import { PaymentServiceError } from "./payment-service.error.js";
-import Stripe from "stripe";
+import { stripeRequest } from "./request.js";
 
 //#region src/infrastructure/stripe/payment-service.ts
 /**
 * Ported from Typist's StripeClient request boundary; the native SDK now owns retries.
-* Each request defaults to two SDK retries. Native request options can override retries and timeout.
+* The injected client owns retry and timeout defaults. Native request options can override them.
 */
 var StripePaymentService = class {
 	stripe;
@@ -14,56 +13,33 @@ var StripePaymentService = class {
 	}
 	/** Create a customer with a stable application key and preserve the native response. */
 	createCustomer(input, options) {
-		return this.request("customers.create", () => this.stripe.customers.create(input, {
-			maxNetworkRetries: 2,
-			...options
-		}));
+		return stripeRequest("customers.create", () => this.stripe.customers.create(input, options));
 	}
 	/** Force payment mode after caller parameters; return the native Checkout Session. */
 	createCheckout(input, options) {
-		return this.request("checkout.sessions.create", () => this.stripe.checkout.sessions.create({
+		return stripeRequest("checkout.sessions.create", () => this.stripe.checkout.sessions.create({
 			...input,
 			mode: "payment"
-		}, {
-			maxNetworkRetries: 2,
-			...options
-		}));
+		}, options));
 	}
 	/** Force setup mode after caller parameters; this operation does not charge the customer. */
 	setupPaymentMethod(input, options) {
-		return this.request("checkout.sessions.create", () => this.stripe.checkout.sessions.create({
+		return stripeRequest("checkout.sessions.create", () => this.stripe.checkout.sessions.create({
 			...input,
 			mode: "setup"
-		}, {
-			maxNetworkRetries: 2,
-			...options
-		}));
+		}, options));
 	}
-	/** Force confirmation and off-session use; preserve native card failures for application handling. */
+	/** Force confirmation and off-session use; retain native card failures in PaymentServiceError.cause. */
 	chargeSavedMethod(input, options) {
-		return this.request("paymentIntents.create", () => this.stripe.paymentIntents.create({
+		return stripeRequest("paymentIntents.create", () => this.stripe.paymentIntents.create({
 			...input,
 			confirm: true,
 			off_session: true
-		}, {
-			maxNetworkRetries: 2,
-			...options
-		}));
+		}, options));
 	}
 	/** Preserve every native status and response field when reconciling an existing payment. */
 	getPayment(paymentId, params, options) {
-		return this.request("paymentIntents.retrieve", () => this.stripe.paymentIntents.retrieve(paymentId, params, {
-			maxNetworkRetries: 2,
-			...options
-		}));
-	}
-	async request(operation, work) {
-		try {
-			return await work();
-		} catch (cause) {
-			if (!(cause instanceof Stripe.errors.StripeError) || cause instanceof Stripe.errors.StripeCardError) throw cause;
-			throw new PaymentServiceError(operation, cause);
-		}
+		return stripeRequest("paymentIntents.retrieve", () => this.stripe.paymentIntents.retrieve(paymentId, params, options));
 	}
 };
 

package/dist/stripe/payment-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"payment-service.js","names":[],"sources":["../../src/infrastructure/stripe/payment-service.ts"],"sourcesContent":["import Stripe from 'stripe'\n\nimport { PaymentServiceError } from './payment-service.error.ts'\n\n/** Supply the same key and parameters when repeating one durable payment attempt. */\nexport type PaymentRequestOptions = Stripe.RequestOptions &\n  Required<Pick<Stripe.RequestOptions, 'idempotencyKey'>>\n\n/** Native Checkout parameters; the service selects payment or setup mode. */\nexport type CheckoutInput = Omit<Stripe.Checkout.SessionCreateParams, 'mode'>\n\n/** A saved customer method; the service confirms the payment off-session. */\nexport type SavedMethodCharge = Omit<Stripe.PaymentIntentCreateParams, 'confirm' | 'off_session'> &\n  Required<Pick<Stripe.PaymentIntentCreateParams, 'customer' | 'payment_method'>>\n\n/** Native customer response, including Stripe request metadata. */\nexport type CustomerResult = Awaited<ReturnType<Stripe['customers']['create']>>\n\n/** Native Checkout response. Its URL can be null; this does not confirm payment. */\nexport type CheckoutResult = Awaited<ReturnType<Stripe['checkout']['sessions']['create']>>\n\n/** Native PaymentIntent response. Applications decide what each status permits. */\nexport type PaymentResult = Awaited<ReturnType<Stripe['paymentIntents']['create']>>\n\n/**\n * Stripe payment operations, with native types and stable keys for mutations.\n * Rejects with PaymentServiceError or native StripeCardError; unexpected defects propagate.\n */\nexport interface IPaymentService {\n  /** Create a customer; the application owns persistence and reuse of the customer link. */\n  createCustomer(\n    input: Stripe.CustomerCreateParams,\n    options: PaymentRequestOptions,\n  ): Promise<CustomerResult>\n  /** Create one-time payment checkout; application fulfillment requires verified payment confirmation. */\n  createCheckout(input: CheckoutInput, options: PaymentRequestOptions): Promise<CheckoutResult>\n  /** Create checkout in setup mode. The application records consent and verifies the saved method's owner. */\n  setupPaymentMethod(input: CheckoutInput, options: PaymentRequestOptions): Promise<CheckoutResult>\n  /** Confirm a saved method off-session. Native card errors can require customer authentication. */\n  chargeSavedMethod(\n    input: SavedMethodCharge,\n    options: PaymentRequestOptions,\n  ): Promise<PaymentResult>\n  /** Retrieve an existing payment without starting another payment attempt. */\n  getPayment(\n    paymentId: string,\n    params?: Stripe.PaymentIntentRetrieveParams,\n    options?: Stripe.RequestOptions,\n  ): Promise<PaymentResult>\n}\n\n/**\n * Ported from Typist's StripeClient request boundary; the native SDK now owns retries.\n * Each request defaults to two SDK retries. Native request options can override retries and timeout.\n */\nexport class StripePaymentService implements IPaymentService {\n  /** Inject a native SDK instance; its transport, credentials, and API version remain caller-owned. */\n  constructor(private readonly stripe: Stripe) {}\n\n  /** Create a customer with a stable application key and preserve the native response. */\n  createCustomer(\n    input: Stripe.CustomerCreateParams,\n    options: PaymentRequestOptions,\n  ): Promise<CustomerResult> {\n    return this.request('customers.create', () =>\n      this.stripe.customers.create(input, { maxNetworkRetries: 2, ...options }),\n    )\n  }\n\n  /** Force payment mode after caller parameters; return the native Checkout Session. */\n  createCheckout(input: CheckoutInput, options: PaymentRequestOptions): Promise<CheckoutResult> {\n    return this.request('checkout.sessions.create', () =>\n      this.stripe.checkout.sessions.create(\n        { ...input, mode: 'payment' },\n        { maxNetworkRetries: 2, ...options },\n      ),\n    )\n  }\n\n  /** Force setup mode after caller parameters; this operation does not charge the customer. */\n  setupPaymentMethod(\n    input: CheckoutInput,\n    options: PaymentRequestOptions,\n  ): Promise<CheckoutResult> {\n    return this.request('checkout.sessions.create', () =>\n      this.stripe.checkout.sessions.create(\n        { ...input, mode: 'setup' },\n        { maxNetworkRetries: 2, ...options },\n      ),\n    )\n  }\n\n  /** Force confirmation and off-session use; preserve native card failures for application handling. */\n  chargeSavedMethod(\n    input: SavedMethodCharge,\n    options: PaymentRequestOptions,\n  ): Promise<PaymentResult> {\n    return this.request('paymentIntents.create', () =>\n      this.stripe.paymentIntents.create(\n        { ...input, confirm: true, off_session: true },\n        { maxNetworkRetries: 2, ...options },\n      ),\n    )\n  }\n\n  /** Preserve every native status and response field when reconciling an existing payment. */\n  getPayment(\n    paymentId: string,\n    params?: Stripe.PaymentIntentRetrieveParams,\n    options?: Stripe.RequestOptions,\n  ): Promise<PaymentResult> {\n    return this.request('paymentIntents.retrieve', () =>\n      this.stripe.paymentIntents.retrieve(paymentId, params, { maxNetworkRetries: 2, ...options }),\n    )\n  }\n\n  private async request<T>(operation: string, work: () => Promise<T>): Promise<T> {\n    try {\n      return await work()\n    } catch (cause) {\n      if (\n        !(cause instanceof Stripe.errors.StripeError) ||\n        cause instanceof Stripe.errors.StripeCardError\n      )\n        throw cause\n      throw new PaymentServiceError(operation, cause)\n    }\n  }\n}\n"],"mappings":";;;;;;;;AAuDA,IAAa,uBAAb,MAA6D;CAE9B;;CAA7B,YAAY,AAAiB,QAAgB;EAAhB;CAAiB;;CAG9C,eACE,OACA,SACyB;EACzB,OAAO,KAAK,QAAQ,0BAClB,KAAK,OAAO,UAAU,OAAO,OAAO;GAAE,mBAAmB;GAAG,GAAG;EAAQ,CAAC,CAC1E;CACF;;CAGA,eAAe,OAAsB,SAAyD;EAC5F,OAAO,KAAK,QAAQ,kCAClB,KAAK,OAAO,SAAS,SAAS,OAC5B;GAAE,GAAG;GAAO,MAAM;EAAU,GAC5B;GAAE,mBAAmB;GAAG,GAAG;EAAQ,CACrC,CACF;CACF;;CAGA,mBACE,OACA,SACyB;EACzB,OAAO,KAAK,QAAQ,kCAClB,KAAK,OAAO,SAAS,SAAS,OAC5B;GAAE,GAAG;GAAO,MAAM;EAAQ,GAC1B;GAAE,mBAAmB;GAAG,GAAG;EAAQ,CACrC,CACF;CACF;;CAGA,kBACE,OACA,SACwB;EACxB,OAAO,KAAK,QAAQ,+BAClB,KAAK,OAAO,eAAe,OACzB;GAAE,GAAG;GAAO,SAAS;GAAM,aAAa;EAAK,GAC7C;GAAE,mBAAmB;GAAG,GAAG;EAAQ,CACrC,CACF;CACF;;CAGA,WACE,WACA,QACA,SACwB;EACxB,OAAO,KAAK,QAAQ,iCAClB,KAAK,OAAO,eAAe,SAAS,WAAW,QAAQ;GAAE,mBAAmB;GAAG,GAAG;EAAQ,CAAC,CAC7F;CACF;CAEA,MAAc,QAAW,WAAmB,MAAoC;EAC9E,IAAI;GACF,OAAO,MAAM,KAAK;EACpB,SAAS,OAAO;GACd,IACE,EAAE,iBAAiB,OAAO,OAAO,gBACjC,iBAAiB,OAAO,OAAO,iBAE/B,MAAM;GACR,MAAM,IAAI,oBAAoB,WAAW,KAAK;EAChD;CACF;AACF"}
+{"version":3,"file":"payment-service.js","names":[],"sources":["../../src/infrastructure/stripe/payment-service.ts"],"sourcesContent":["import type Stripe from 'stripe'\n\nimport { stripeRequest } from './request.ts'\n\n/** Supply the same key and parameters when repeating one durable payment attempt. */\nexport type PaymentRequestOptions = Stripe.RequestOptions &\n  Required<Pick<Stripe.RequestOptions, 'idempotencyKey'>>\n\n/** Native Checkout parameters; the service selects payment or setup mode. */\nexport type CheckoutInput = Omit<Stripe.Checkout.SessionCreateParams, 'mode'>\n\n/** A saved customer method; the service confirms the payment off-session. */\nexport type SavedMethodCharge = Omit<Stripe.PaymentIntentCreateParams, 'confirm' | 'off_session'> &\n  Required<Pick<Stripe.PaymentIntentCreateParams, 'customer' | 'payment_method'>>\n\n/** Native customer response, including Stripe request metadata. */\nexport type CustomerResult = Awaited<ReturnType<Stripe['customers']['create']>>\n\n/** Native Checkout response. Its URL can be null; this does not confirm payment. */\nexport type CheckoutResult = Awaited<ReturnType<Stripe['checkout']['sessions']['create']>>\n\n/** Native PaymentIntent response. Applications decide what each status permits. */\nexport type PaymentResult = Awaited<ReturnType<Stripe['paymentIntents']['create']>>\n\n/**\n * Stripe payment operations, with native types and stable keys for mutations.\n * Rejects with PaymentServiceError for Stripe failures; non-Stripe failures propagate unchanged.\n */\nexport interface IPaymentService {\n  /** Create a customer; the application owns persistence and reuse of the customer link. */\n  createCustomer(\n    input: Stripe.CustomerCreateParams,\n    options: PaymentRequestOptions,\n  ): Promise<CustomerResult>\n  /** Create one-time payment checkout; application fulfillment requires verified payment confirmation. */\n  createCheckout(input: CheckoutInput, options: PaymentRequestOptions): Promise<CheckoutResult>\n  /** Create checkout in setup mode. The application records consent and verifies the saved method's owner. */\n  setupPaymentMethod(input: CheckoutInput, options: PaymentRequestOptions): Promise<CheckoutResult>\n  /** Confirm a saved method off-session. PaymentServiceError retains card errors in cause. */\n  chargeSavedMethod(\n    input: SavedMethodCharge,\n    options: PaymentRequestOptions,\n  ): Promise<PaymentResult>\n  /** Retrieve an existing payment without starting another payment attempt. */\n  getPayment(\n    paymentId: string,\n    params?: Stripe.PaymentIntentRetrieveParams,\n    options?: Stripe.RequestOptions,\n  ): Promise<PaymentResult>\n}\n\n/**\n * Ported from Typist's StripeClient request boundary; the native SDK now owns retries.\n * The injected client owns retry and timeout defaults. Native request options can override them.\n */\nexport class StripePaymentService implements IPaymentService {\n  /** Inject a native SDK instance; its transport, credentials, and API version remain caller-owned. */\n  constructor(private readonly stripe: Stripe) {}\n\n  /** Create a customer with a stable application key and preserve the native response. */\n  createCustomer(\n    input: Stripe.CustomerCreateParams,\n    options: PaymentRequestOptions,\n  ): Promise<CustomerResult> {\n    return stripeRequest('customers.create', () => this.stripe.customers.create(input, options))\n  }\n\n  /** Force payment mode after caller parameters; return the native Checkout Session. */\n  createCheckout(input: CheckoutInput, options: PaymentRequestOptions): Promise<CheckoutResult> {\n    return stripeRequest('checkout.sessions.create', () =>\n      this.stripe.checkout.sessions.create({ ...input, mode: 'payment' }, options),\n    )\n  }\n\n  /** Force setup mode after caller parameters; this operation does not charge the customer. */\n  setupPaymentMethod(\n    input: CheckoutInput,\n    options: PaymentRequestOptions,\n  ): Promise<CheckoutResult> {\n    return stripeRequest('checkout.sessions.create', () =>\n      this.stripe.checkout.sessions.create({ ...input, mode: 'setup' }, options),\n    )\n  }\n\n  /** Force confirmation and off-session use; retain native card failures in PaymentServiceError.cause. */\n  chargeSavedMethod(\n    input: SavedMethodCharge,\n    options: PaymentRequestOptions,\n  ): Promise<PaymentResult> {\n    return stripeRequest('paymentIntents.create', () =>\n      this.stripe.paymentIntents.create({ ...input, confirm: true, off_session: true }, options),\n    )\n  }\n\n  /** Preserve every native status and response field when reconciling an existing payment. */\n  getPayment(\n    paymentId: string,\n    params?: Stripe.PaymentIntentRetrieveParams,\n    options?: Stripe.RequestOptions,\n  ): Promise<PaymentResult> {\n    return stripeRequest('paymentIntents.retrieve', () =>\n      this.stripe.paymentIntents.retrieve(paymentId, params, options),\n    )\n  }\n}\n"],"mappings":";;;;;;;AAuDA,IAAa,uBAAb,MAA6D;CAE9B;;CAA7B,YAAY,AAAiB,QAAgB;EAAhB;CAAiB;;CAG9C,eACE,OACA,SACyB;EACzB,OAAO,cAAc,0BAA0B,KAAK,OAAO,UAAU,OAAO,OAAO,OAAO,CAAC;CAC7F;;CAGA,eAAe,OAAsB,SAAyD;EAC5F,OAAO,cAAc,kCACnB,KAAK,OAAO,SAAS,SAAS,OAAO;GAAE,GAAG;GAAO,MAAM;EAAU,GAAG,OAAO,CAC7E;CACF;;CAGA,mBACE,OACA,SACyB;EACzB,OAAO,cAAc,kCACnB,KAAK,OAAO,SAAS,SAAS,OAAO;GAAE,GAAG;GAAO,MAAM;EAAQ,GAAG,OAAO,CAC3E;CACF;;CAGA,kBACE,OACA,SACwB;EACxB,OAAO,cAAc,+BACnB,KAAK,OAAO,eAAe,OAAO;GAAE,GAAG;GAAO,SAAS;GAAM,aAAa;EAAK,GAAG,OAAO,CAC3F;CACF;;CAGA,WACE,WACA,QACA,SACwB;EACxB,OAAO,cAAc,iCACnB,KAAK,OAAO,eAAe,SAAS,WAAW,QAAQ,OAAO,CAChE;CACF;AACF"}

package/dist/stripe/request.d.ts

@@ -0,0 +1,9 @@
+//#region src/infrastructure/stripe/request.d.ts
+/**
+ * Invoke one SDK operation; the SDK owns retries configured on its client or request.
+ * Convert every Stripe error to PaymentServiceError without logging; preserve the original error in cause.
+ * Non-Stripe failures propagate unchanged.
+ */
+export declare function stripeRequest<T>(operation: string, work: () => Promise<T>): Promise<T>;
+//#endregion
+//# sourceMappingURL=request.d.ts.map

package/dist/stripe/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","names":[],"sources":["../../src/infrastructure/stripe/request.ts"],"mappings":";;;;;;wBASsB,cAAc,GAAG,mBAAmB,YAAY,QAAQ,KAAK,QAAQ"}

package/dist/stripe/request.js

@@ -0,0 +1,21 @@
+import { PaymentServiceError } from "./payment-service.error.js";
+import Stripe from "stripe";
+
+//#region src/infrastructure/stripe/request.ts
+/**
+* Invoke one SDK operation; the SDK owns retries configured on its client or request.
+* Convert every Stripe error to PaymentServiceError without logging; preserve the original error in cause.
+* Non-Stripe failures propagate unchanged.
+*/
+async function stripeRequest(operation, work) {
+	try {
+		return await work();
+	} catch (cause) {
+		if (!(cause instanceof Stripe.errors.StripeError)) throw cause;
+		throw new PaymentServiceError(operation, cause);
+	}
+}
+
+//#endregion
+export { stripeRequest };
+//# sourceMappingURL=request.js.map

package/dist/stripe/request.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.js","names":[],"sources":["../../src/infrastructure/stripe/request.ts"],"sourcesContent":["import Stripe from 'stripe'\n\nimport { PaymentServiceError } from './payment-service.error.ts'\n\n/**\n * Invoke one SDK operation; the SDK owns retries configured on its client or request.\n * Convert every Stripe error to PaymentServiceError without logging; preserve the original error in cause.\n * Non-Stripe failures propagate unchanged.\n */\nexport async function stripeRequest<T>(operation: string, work: () => Promise<T>): Promise<T> {\n  try {\n    return await work()\n  } catch (cause) {\n    if (!(cause instanceof Stripe.errors.StripeError)) throw cause\n    throw new PaymentServiceError(operation, cause)\n  }\n}\n"],"mappings":";;;;;;;;;AASA,eAAsB,cAAiB,WAAmB,MAAoC;CAC5F,IAAI;EACF,OAAO,MAAM,KAAK;CACpB,SAAS,OAAO;EACd,IAAI,EAAE,iBAAiB,OAAO,OAAO,cAAc,MAAM;EACzD,MAAM,IAAI,oBAAoB,WAAW,KAAK;CAChD;AACF"}

package/dist/testing/payment-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"payment-service.d.ts","names":[],"sources":["../../src/infrastructure/testing/payment-service-contract.ts"],"mappings":";;;;;;;wBAUgB,uBACd,OAAO,cAAc,WAAW,wBAChC,SAAS,QAAQ,WAAW"}
+{"version":3,"file":"payment-service.d.ts","names":[],"sources":["../../src/infrastructure/testing/payment-service-contract.ts"],"mappings":";;;;;;;wBAYgB,uBACd,OAAO,cAAc,WAAW,wBAChC,SAAS,QAAQ,WAAW"}

package/dist/testing/payment-service.js

@@ -1,5 +1,7 @@
+import { PaymentServiceError } from "../stripe/payment-service.error.js";
+import { stripeFixture } from "./stripe.js";
 import Stripe from "stripe";
-import { deepStrictEqual, equal, rejects } from "node:assert/strict";
+import { deepStrictEqual, equal, ok, rejects } from "node:assert/strict";
 
 //#region src/infrastructure/testing/payment-service-contract.ts
 /**
@@ -39,7 +41,7 @@ function paymentServiceContract(test, create) {
 			status: "requires_capture"
 		});
 	});
-	test("card failures retain the native error contract", async () => {
+	test("card failures retain the native error in cause", async () => {
 		const fixture = paymentFixture(create, Response.json({ error: {
 			type: "card_error",
 			code: "authentication_required",
@@ -50,23 +52,21 @@ function paymentServiceContract(test, create) {
 			currency: "usd",
 			customer: "cus_contract",
 			payment_method: "pm_contract"
-		}, { idempotencyKey: "charge:contract" }), Stripe.errors.StripeCardError);
+		}, { idempotencyKey: "charge:contract" }), (error) => {
+			ok(error instanceof PaymentServiceError);
+			ok(error.cause instanceof Stripe.errors.StripeCardError);
+			equal(error.cause.code, "authentication_required");
+			return true;
+		});
 	});
 }
 function paymentFixture(create, response = Response.json({
 	id: "pi_contract",
 	status: "requires_capture"
 })) {
-	const requests = [];
+	const { stripe, requests } = stripeFixture(() => response.clone());
 	return {
-		service: create(new Stripe("sk_test_contract", { httpClient: Stripe.createFetchHttpClient(async (input, init) => {
-			const request = new Request(input, init);
-			requests.push({
-				headers: request.headers,
-				body: new URLSearchParams(new TextDecoder().decode(await request.arrayBuffer()))
-			});
-			return response.clone();
-		}) })),
+		service: create(stripe),
 		requests
 	};
 }

package/dist/testing/payment-service.js.map

@@ -1 +1 @@
-{"version":3,"file":"payment-service.js","names":[],"sources":["../../src/infrastructure/testing/payment-service-contract.ts"],"sourcesContent":["import { deepStrictEqual, equal, rejects } from 'node:assert/strict'\n\nimport Stripe from 'stripe'\n\nimport type { IPaymentService } from '../stripe/payment-service.ts'\n\n/**\n * Test a Stripe payment adapter through native fetch injection without live payments.\n * Each case constructs a fresh SDK instance and adapter; no Vitest dependency is required.\n */\nexport function paymentServiceContract(\n  test: (name: string, run: () => Promise<void>) => void,\n  create: (stripe: Stripe) => IPaymentService,\n): void {\n  test('payment checkout selects payment mode and retains the supplied key', async () => {\n    const fixture = paymentFixture(create)\n    await fixture.service.createCheckout(\n      { customer: 'cus_contract' },\n      { idempotencyKey: 'checkout:contract' },\n    )\n    equal(fixture.requests[0]?.body.get('mode'), 'payment')\n    equal(fixture.requests[0]?.headers.get('idempotency-key'), 'checkout:contract')\n  })\n\n  test('payment method setup selects setup mode', async () => {\n    const fixture = paymentFixture(create)\n    await fixture.service.setupPaymentMethod(\n      { customer: 'cus_contract' },\n      { idempotencyKey: 'setup:contract' },\n    )\n    equal(fixture.requests[0]?.body.get('mode'), 'setup')\n  })\n\n  test('saved method payments confirm off-session', async () => {\n    const fixture = paymentFixture(create)\n    await fixture.service.chargeSavedMethod(\n      { amount: 1000, currency: 'usd', customer: 'cus_contract', payment_method: 'pm_contract' },\n      { idempotencyKey: 'charge:contract' },\n    )\n    equal(fixture.requests[0]?.body.get('confirm'), 'true')\n    equal(fixture.requests[0]?.body.get('off_session'), 'true')\n  })\n\n  test('payment reads preserve native statuses and response fields', async () => {\n    const fixture = paymentFixture(create)\n    const payment = await fixture.service.getPayment('pi_contract')\n    deepStrictEqual(\n      { id: payment.id, status: payment.status },\n      { id: 'pi_contract', status: 'requires_capture' },\n    )\n  })\n\n  test('card failures retain the native error contract', async () => {\n    const response = Response.json(\n      {\n        error: {\n          type: 'card_error',\n          code: 'authentication_required',\n          message: 'Authentication required',\n        },\n      },\n      { status: 402 },\n    )\n    const fixture = paymentFixture(create, response)\n    await rejects(\n      fixture.service.chargeSavedMethod(\n        { amount: 1000, currency: 'usd', customer: 'cus_contract', payment_method: 'pm_contract' },\n        { idempotencyKey: 'charge:contract' },\n      ),\n      Stripe.errors.StripeCardError,\n    )\n  })\n}\n\nfunction paymentFixture(\n  create: (stripe: Stripe) => IPaymentService,\n  response = Response.json({ id: 'pi_contract', status: 'requires_capture' }),\n) {\n  const requests: { headers: Headers; body: URLSearchParams }[] = []\n  const stripe = new Stripe('sk_test_contract', {\n    httpClient: Stripe.createFetchHttpClient(async (input, init) => {\n      const request = new Request(input, init)\n      requests.push({\n        headers: request.headers,\n        body: new URLSearchParams(new TextDecoder().decode(await request.arrayBuffer())),\n      })\n      return response.clone()\n    }),\n  })\n  return { service: create(stripe), requests }\n}\n"],"mappings":";;;;;;;;AAUA,SAAgB,uBACd,MACA,QACM;CACN,KAAK,sEAAsE,YAAY;EACrF,MAAM,UAAU,eAAe,MAAM;EACrC,MAAM,QAAQ,QAAQ,eACpB,EAAE,UAAU,eAAe,GAC3B,EAAE,gBAAgB,oBAAoB,CACxC;EACA,MAAM,QAAQ,SAAS,EAAE,EAAE,KAAK,IAAI,MAAM,GAAG,SAAS;EACtD,MAAM,QAAQ,SAAS,EAAE,EAAE,QAAQ,IAAI,iBAAiB,GAAG,mBAAmB;CAChF,CAAC;CAED,KAAK,2CAA2C,YAAY;EAC1D,MAAM,UAAU,eAAe,MAAM;EACrC,MAAM,QAAQ,QAAQ,mBACpB,EAAE,UAAU,eAAe,GAC3B,EAAE,gBAAgB,iBAAiB,CACrC;EACA,MAAM,QAAQ,SAAS,EAAE,EAAE,KAAK,IAAI,MAAM,GAAG,OAAO;CACtD,CAAC;CAED,KAAK,6CAA6C,YAAY;EAC5D,MAAM,UAAU,eAAe,MAAM;EACrC,MAAM,QAAQ,QAAQ,kBACpB;GAAE,QAAQ;GAAM,UAAU;GAAO,UAAU;GAAgB,gBAAgB;EAAc,GACzF,EAAE,gBAAgB,kBAAkB,CACtC;EACA,MAAM,QAAQ,SAAS,EAAE,EAAE,KAAK,IAAI,SAAS,GAAG,MAAM;EACtD,MAAM,QAAQ,SAAS,EAAE,EAAE,KAAK,IAAI,aAAa,GAAG,MAAM;CAC5D,CAAC;CAED,KAAK,8DAA8D,YAAY;EAE7E,MAAM,UAAU,MADA,eAAe,MACH,CAAC,CAAC,QAAQ,WAAW,aAAa;EAC9D,gBACE;GAAE,IAAI,QAAQ;GAAI,QAAQ,QAAQ;EAAO,GACzC;GAAE,IAAI;GAAe,QAAQ;EAAmB,CAClD;CACF,CAAC;CAED,KAAK,kDAAkD,YAAY;EAWjE,MAAM,UAAU,eAAe,QAVd,SAAS,KACxB,EACE,OAAO;GACL,MAAM;GACN,MAAM;GACN,SAAS;EACX,EACF,GACA,EAAE,QAAQ,IAAI,CAE8B,CAAC;EAC/C,MAAM,QACJ,QAAQ,QAAQ,kBACd;GAAE,QAAQ;GAAM,UAAU;GAAO,UAAU;GAAgB,gBAAgB;EAAc,GACzF,EAAE,gBAAgB,kBAAkB,CACtC,GACA,OAAO,OAAO,eAChB;CACF,CAAC;AACH;AAEA,SAAS,eACP,QACA,WAAW,SAAS,KAAK;CAAE,IAAI;CAAe,QAAQ;AAAmB,CAAC,GAC1E;CACA,MAAM,WAA0D,CAAC;CAWjE,OAAO;EAAE,SAAS,OAAO,IAVN,OAAO,oBAAoB,EAC5C,YAAY,OAAO,sBAAsB,OAAO,OAAO,SAAS;GAC9D,MAAM,UAAU,IAAI,QAAQ,OAAO,IAAI;GACvC,SAAS,KAAK;IACZ,SAAS,QAAQ;IACjB,MAAM,IAAI,gBAAgB,IAAI,YAAY,CAAC,CAAC,OAAO,MAAM,QAAQ,YAAY,CAAC,CAAC;GACjF,CAAC;GACD,OAAO,SAAS,MAAM;EACxB,CAAC,EACH,CAC8B,CAAC;EAAG;CAAS;AAC7C"}
+{"version":3,"file":"payment-service.js","names":[],"sources":["../../src/infrastructure/testing/payment-service-contract.ts"],"sourcesContent":["import { deepStrictEqual, equal, ok, rejects } from 'node:assert/strict'\n\nimport Stripe from 'stripe'\n\nimport { PaymentServiceError } from '../stripe/payment-service.error.ts'\nimport type { IPaymentService } from '../stripe/payment-service.ts'\nimport { stripeFixture } from './stripe-fixture.ts'\n\n/**\n * Test a Stripe payment adapter through native fetch injection without live payments.\n * Each case constructs a fresh SDK instance and adapter; no Vitest dependency is required.\n */\nexport function paymentServiceContract(\n  test: (name: string, run: () => Promise<void>) => void,\n  create: (stripe: Stripe) => IPaymentService,\n): void {\n  test('payment checkout selects payment mode and retains the supplied key', async () => {\n    const fixture = paymentFixture(create)\n    await fixture.service.createCheckout(\n      { customer: 'cus_contract' },\n      { idempotencyKey: 'checkout:contract' },\n    )\n    equal(fixture.requests[0]?.body.get('mode'), 'payment')\n    equal(fixture.requests[0]?.headers.get('idempotency-key'), 'checkout:contract')\n  })\n\n  test('payment method setup selects setup mode', async () => {\n    const fixture = paymentFixture(create)\n    await fixture.service.setupPaymentMethod(\n      { customer: 'cus_contract' },\n      { idempotencyKey: 'setup:contract' },\n    )\n    equal(fixture.requests[0]?.body.get('mode'), 'setup')\n  })\n\n  test('saved method payments confirm off-session', async () => {\n    const fixture = paymentFixture(create)\n    await fixture.service.chargeSavedMethod(\n      { amount: 1000, currency: 'usd', customer: 'cus_contract', payment_method: 'pm_contract' },\n      { idempotencyKey: 'charge:contract' },\n    )\n    equal(fixture.requests[0]?.body.get('confirm'), 'true')\n    equal(fixture.requests[0]?.body.get('off_session'), 'true')\n  })\n\n  test('payment reads preserve native statuses and response fields', async () => {\n    const fixture = paymentFixture(create)\n    const payment = await fixture.service.getPayment('pi_contract')\n    deepStrictEqual(\n      { id: payment.id, status: payment.status },\n      { id: 'pi_contract', status: 'requires_capture' },\n    )\n  })\n\n  test('card failures retain the native error in cause', async () => {\n    const response = Response.json(\n      {\n        error: {\n          type: 'card_error',\n          code: 'authentication_required',\n          message: 'Authentication required',\n        },\n      },\n      { status: 402 },\n    )\n    const fixture = paymentFixture(create, response)\n    await rejects(\n      fixture.service.chargeSavedMethod(\n        { amount: 1000, currency: 'usd', customer: 'cus_contract', payment_method: 'pm_contract' },\n        { idempotencyKey: 'charge:contract' },\n      ),\n      (error) => {\n        ok(error instanceof PaymentServiceError)\n        ok(error.cause instanceof Stripe.errors.StripeCardError)\n        equal(error.cause.code, 'authentication_required')\n        return true\n      },\n    )\n  })\n}\n\nfunction paymentFixture(\n  create: (stripe: Stripe) => IPaymentService,\n  response = Response.json({ id: 'pi_contract', status: 'requires_capture' }),\n) {\n  const { stripe, requests } = stripeFixture(() => response.clone())\n  return { service: create(stripe), requests }\n}\n"],"mappings":";;;;;;;;;;AAYA,SAAgB,uBACd,MACA,QACM;CACN,KAAK,sEAAsE,YAAY;EACrF,MAAM,UAAU,eAAe,MAAM;EACrC,MAAM,QAAQ,QAAQ,eACpB,EAAE,UAAU,eAAe,GAC3B,EAAE,gBAAgB,oBAAoB,CACxC;EACA,MAAM,QAAQ,SAAS,EAAE,EAAE,KAAK,IAAI,MAAM,GAAG,SAAS;EACtD,MAAM,QAAQ,SAAS,EAAE,EAAE,QAAQ,IAAI,iBAAiB,GAAG,mBAAmB;CAChF,CAAC;CAED,KAAK,2CAA2C,YAAY;EAC1D,MAAM,UAAU,eAAe,MAAM;EACrC,MAAM,QAAQ,QAAQ,mBACpB,EAAE,UAAU,eAAe,GAC3B,EAAE,gBAAgB,iBAAiB,CACrC;EACA,MAAM,QAAQ,SAAS,EAAE,EAAE,KAAK,IAAI,MAAM,GAAG,OAAO;CACtD,CAAC;CAED,KAAK,6CAA6C,YAAY;EAC5D,MAAM,UAAU,eAAe,MAAM;EACrC,MAAM,QAAQ,QAAQ,kBACpB;GAAE,QAAQ;GAAM,UAAU;GAAO,UAAU;GAAgB,gBAAgB;EAAc,GACzF,EAAE,gBAAgB,kBAAkB,CACtC;EACA,MAAM,QAAQ,SAAS,EAAE,EAAE,KAAK,IAAI,SAAS,GAAG,MAAM;EACtD,MAAM,QAAQ,SAAS,EAAE,EAAE,KAAK,IAAI,aAAa,GAAG,MAAM;CAC5D,CAAC;CAED,KAAK,8DAA8D,YAAY;EAE7E,MAAM,UAAU,MADA,eAAe,MACH,CAAC,CAAC,QAAQ,WAAW,aAAa;EAC9D,gBACE;GAAE,IAAI,QAAQ;GAAI,QAAQ,QAAQ;EAAO,GACzC;GAAE,IAAI;GAAe,QAAQ;EAAmB,CAClD;CACF,CAAC;CAED,KAAK,kDAAkD,YAAY;EAWjE,MAAM,UAAU,eAAe,QAVd,SAAS,KACxB,EACE,OAAO;GACL,MAAM;GACN,MAAM;GACN,SAAS;EACX,EACF,GACA,EAAE,QAAQ,IAAI,CAE8B,CAAC;EAC/C,MAAM,QACJ,QAAQ,QAAQ,kBACd;GAAE,QAAQ;GAAM,UAAU;GAAO,UAAU;GAAgB,gBAAgB;EAAc,GACzF,EAAE,gBAAgB,kBAAkB,CACtC,IACC,UAAU;GACT,GAAG,iBAAiB,mBAAmB;GACvC,GAAG,MAAM,iBAAiB,OAAO,OAAO,eAAe;GACvD,MAAM,MAAM,MAAM,MAAM,yBAAyB;GACjD,OAAO;EACT,CACF;CACF,CAAC;AACH;AAEA,SAAS,eACP,QACA,WAAW,SAAS,KAAK;CAAE,IAAI;CAAe,QAAQ;AAAmB,CAAC,GAC1E;CACA,MAAM,EAAE,QAAQ,aAAa,oBAAoB,SAAS,MAAM,CAAC;CACjE,OAAO;EAAE,SAAS,OAAO,MAAM;EAAG;CAAS;AAC7C"}

package/dist/testing/stripe.d.ts

@@ -0,0 +1,21 @@
+import Stripe from "stripe";
+//#region src/infrastructure/testing/stripe-fixture.d.ts
+/** One SDK HTTP attempt; query and body expose Stripe's URL-encoded parameters. */
+export type StripeCall = {
+  readonly method: string;
+  readonly path: string;
+  readonly query: URLSearchParams;
+  readonly body: URLSearchParams;
+  readonly headers: Headers;
+};
+type StripeFixture = {
+  stripe: Stripe;
+  requests: readonly StripeCall[];
+};
+/**
+ * Construct the real SDK with a fake fetch transport and an ordered record of HTTP attempts.
+ * The responder receives an unread request. The shared client factory supplies retry defaults.
+ */
+export declare function stripeFixture(respond: (request: Request) => Response | Promise<Response>): StripeFixture;
+//#endregion
+//# sourceMappingURL=stripe.d.ts.map

package/dist/testing/stripe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripe.d.ts","names":[],"sources":["../../src/infrastructure/testing/stripe-fixture.ts"],"mappings":";;;YAKY;WACD;WACA;WACA,OAAO;WACP,MAAM;WACN,SAAS;;KAGf;EAAkB,QAAQ;EAAQ,mBAAmB;;;;;;wBAM1C,cACd,UAAU,SAAS,YAAY,WAAW,QAAQ,YACjD"}

package/dist/testing/stripe.js

@@ -0,0 +1,33 @@
+import { createStripeClient } from "../stripe/client.js";
+import Stripe from "stripe";
+
+//#region src/infrastructure/testing/stripe-fixture.ts
+/**
+* Construct the real SDK with a fake fetch transport and an ordered record of HTTP attempts.
+* The responder receives an unread request. The shared client factory supplies retry defaults.
+*/
+function stripeFixture(respond) {
+	const requests = [];
+	return {
+		stripe: createStripeClient("sk_test_fixture", { httpClient: Stripe.createFetchHttpClient(async (input, init) => {
+			const request = new Request(input, init);
+			const url = new URL(request.url);
+			const call = {
+				method: request.method,
+				path: url.pathname,
+				query: url.searchParams,
+				body: new URLSearchParams(),
+				headers: new Headers(request.headers)
+			};
+			requests.push(call);
+			const body = new TextDecoder().decode(await request.clone().arrayBuffer());
+			for (const [key, value] of new URLSearchParams(body)) call.body.append(key, value);
+			return respond(request);
+		}) }),
+		requests
+	};
+}
+
+//#endregion
+export { stripeFixture };
+//# sourceMappingURL=stripe.js.map

package/dist/testing/stripe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripe.js","names":[],"sources":["../../src/infrastructure/testing/stripe-fixture.ts"],"sourcesContent":["import Stripe from 'stripe'\n\nimport { createStripeClient } from '../stripe/client.ts'\n\n/** One SDK HTTP attempt; query and body expose Stripe's URL-encoded parameters. */\nexport type StripeCall = {\n  readonly method: string\n  readonly path: string\n  readonly query: URLSearchParams\n  readonly body: URLSearchParams\n  readonly headers: Headers\n}\n\ntype StripeFixture = { stripe: Stripe; requests: readonly StripeCall[] }\n\n/**\n * Construct the real SDK with a fake fetch transport and an ordered record of HTTP attempts.\n * The responder receives an unread request. The shared client factory supplies retry defaults.\n */\nexport function stripeFixture(\n  respond: (request: Request) => Response | Promise<Response>,\n): StripeFixture {\n  const requests: StripeCall[] = []\n  const stripe = createStripeClient('sk_test_fixture', {\n    httpClient: Stripe.createFetchHttpClient(async (input, init) => {\n      const request = new Request(input, init)\n      const url = new URL(request.url)\n      const call: StripeCall = {\n        method: request.method,\n        path: url.pathname,\n        query: url.searchParams,\n        body: new URLSearchParams(),\n        headers: new Headers(request.headers),\n      }\n      requests.push(call)\n      const body = new TextDecoder().decode(await request.clone().arrayBuffer())\n      for (const [key, value] of new URLSearchParams(body)) call.body.append(key, value)\n      return respond(request)\n    }),\n  })\n  return { stripe, requests }\n}\n"],"mappings":";;;;;;;;AAmBA,SAAgB,cACd,SACe;CACf,MAAM,WAAyB,CAAC;CAkBhC,OAAO;EAAE,QAjBM,mBAAmB,mBAAmB,EACnD,YAAY,OAAO,sBAAsB,OAAO,OAAO,SAAS;GAC9D,MAAM,UAAU,IAAI,QAAQ,OAAO,IAAI;GACvC,MAAM,MAAM,IAAI,IAAI,QAAQ,GAAG;GAC/B,MAAM,OAAmB;IACvB,QAAQ,QAAQ;IAChB,MAAM,IAAI;IACV,OAAO,IAAI;IACX,MAAM,IAAI,gBAAgB;IAC1B,SAAS,IAAI,QAAQ,QAAQ,OAAO;GACtC;GACA,SAAS,KAAK,IAAI;GAClB,MAAM,OAAO,IAAI,YAAY,CAAC,CAAC,OAAO,MAAM,QAAQ,MAAM,CAAC,CAAC,YAAY,CAAC;GACzE,KAAK,MAAM,CAAC,KAAK,UAAU,IAAI,gBAAgB,IAAI,GAAG,KAAK,KAAK,OAAO,KAAK,KAAK;GACjF,OAAO,QAAQ,OAAO;EACxB,CAAC,EACH,CACc;EAAG;CAAS;AAC5B"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "better-ship",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "Foundation for applications on Cloudflare Workers: logger, errors, message bus, infrastructure adapters, and UI primitives",
   "license": "Apache-2.0",
   "repository": {
@@ -44,13 +44,17 @@
     "./sentry/client": "./dist/sentry/client.js",
     "./sentry/server": "./dist/sentry/server.js",
     "./sentry/vite": "./dist/sentry/vite.js",
+    "./stripe/client": "./dist/stripe/client.js",
+    "./stripe/event-map": "./dist/stripe/event-map.js",
     "./stripe/payment-service": "./dist/stripe/payment-service.js",
     "./stripe/payment-service.error": "./dist/stripe/payment-service.error.js",
     "./stripe/payment-webhook": "./dist/stripe/payment-webhook.js",
+    "./stripe/request": "./dist/stripe/request.js",
     "./tanstack": "./dist/tanstack.js",
     "./tanstack/server": "./dist/tanstack/server.js",
     "./testing/outbox-repository": "./dist/testing/outbox-repository.js",
     "./testing/payment-service": "./dist/testing/payment-service.js",
+    "./testing/stripe": "./dist/testing/stripe.js",
     "./ui": "./dist/ui.js",
     "./package.json": "./package.json"
   },

package/src/infrastructure/stripe/client.ts

@@ -0,0 +1,16 @@
+import Stripe from 'stripe'
+
+/** Default SDK retries; client configuration and individual requests can override this value. */
+export const STRIPE_REQUEST_OPTIONS = Object.freeze({ maxNetworkRetries: 2 })
+
+/**
+ * Construct a native Stripe client with fetch transport and two SDK retries by default.
+ * Native configuration overrides these defaults. Inject the client into application services.
+ */
+export function createStripeClient(secretKey: string, options: Stripe.StripeConfig = {}): Stripe {
+  return new Stripe(secretKey, {
+    httpClient: Stripe.createFetchHttpClient(),
+    ...STRIPE_REQUEST_OPTIONS,
+    ...options,
+  })
+}

package/src/infrastructure/stripe/event-map.ts

@@ -0,0 +1,25 @@
+import type Stripe from 'stripe'
+
+type EventObject<K extends Stripe.Event['type']> = Extract<
+  Stripe.Event,
+  { type: K }
+>['data']['object']
+
+/**
+ * Convert verified Stripe events with callbacks typed to each event's object.
+ * Unmapped events return undefined. Applications own validation and payment policy.
+ */
+export function stripeEventMap<T>(map: {
+  [K in Stripe.Event['type']]?: (object: EventObject<K>) => T
+}): (event: Stripe.Event) => T | undefined {
+  const handlers: Partial<Record<Stripe.Event['type'], (object: never) => T>> = map
+  return (event) => {
+    // SAFETY: The map binds each event type to its object; indexed lookup loses that correlation.
+    return handlers[event.type]?.(event.data.object as never)
+  }
+}
+
+/** Identify one Stripe event delivery; different events for one payment retain different IDs. */
+export function stripeEventId(event: Stripe.Event): string {
+  return `stripe:event:${event.id}`
+}

package/src/infrastructure/stripe/payment-service.error.ts

@@ -26,7 +26,8 @@ function classifyStripeError(error: Stripe.errors.StripeError): FailureClassific
     error instanceof Stripe.errors.StripeAuthenticationError ||
     error instanceof Stripe.errors.StripePermissionError ||
     error instanceof Stripe.errors.StripeInvalidRequestError ||
-    error instanceof Stripe.errors.StripeIdempotencyError
+    error instanceof Stripe.errors.StripeIdempotencyError ||
+    error instanceof Stripe.errors.StripeCardError
   )
     return 'terminal'
   if (error.headers?.['stripe-should-retry'] === 'true') return 'transient'

package/src/infrastructure/stripe/payment-service.ts

@@ -1,6 +1,6 @@
-import Stripe from 'stripe'
+import type Stripe from 'stripe'
 
-import { PaymentServiceError } from './payment-service.error.ts'
+import { stripeRequest } from './request.ts'
 
 /** Supply the same key and parameters when repeating one durable payment attempt. */
 export type PaymentRequestOptions = Stripe.RequestOptions &
@@ -24,7 +24,7 @@ export type PaymentResult = Awaited<ReturnType<Stripe['paymentIntents']['create'
 
 /**
  * Stripe payment operations, with native types and stable keys for mutations.
- * Rejects with PaymentServiceError or native StripeCardError; unexpected defects propagate.
+ * Rejects with PaymentServiceError for Stripe failures; non-Stripe failures propagate unchanged.
  */
 export interface IPaymentService {
   /** Create a customer; the application owns persistence and reuse of the customer link. */
@@ -36,7 +36,7 @@ export interface IPaymentService {
   createCheckout(input: CheckoutInput, options: PaymentRequestOptions): Promise<CheckoutResult>
   /** Create checkout in setup mode. The application records consent and verifies the saved method's owner. */
   setupPaymentMethod(input: CheckoutInput, options: PaymentRequestOptions): Promise<CheckoutResult>
-  /** Confirm a saved method off-session. Native card errors can require customer authentication. */
+  /** Confirm a saved method off-session. PaymentServiceError retains card errors in cause. */
   chargeSavedMethod(
     input: SavedMethodCharge,
     options: PaymentRequestOptions,
@@ -51,7 +51,7 @@ export interface IPaymentService {
 
 /**
  * Ported from Typist's StripeClient request boundary; the native SDK now owns retries.
- * Each request defaults to two SDK retries. Native request options can override retries and timeout.
+ * The injected client owns retry and timeout defaults. Native request options can override them.
  */
 export class StripePaymentService implements IPaymentService {
   /** Inject a native SDK instance; its transport, credentials, and API version remain caller-owned. */
@@ -62,18 +62,13 @@ export class StripePaymentService implements IPaymentService {
     input: Stripe.CustomerCreateParams,
     options: PaymentRequestOptions,
   ): Promise<CustomerResult> {
-    return this.request('customers.create', () =>
-      this.stripe.customers.create(input, { maxNetworkRetries: 2, ...options }),
-    )
+    return stripeRequest('customers.create', () => this.stripe.customers.create(input, options))
   }
 
   /** Force payment mode after caller parameters; return the native Checkout Session. */
   createCheckout(input: CheckoutInput, options: PaymentRequestOptions): Promise<CheckoutResult> {
-    return this.request('checkout.sessions.create', () =>
-      this.stripe.checkout.sessions.create(
-        { ...input, mode: 'payment' },
-        { maxNetworkRetries: 2, ...options },
-      ),
+    return stripeRequest('checkout.sessions.create', () =>
+      this.stripe.checkout.sessions.create({ ...input, mode: 'payment' }, options),
     )
   }
 
@@ -82,24 +77,18 @@ export class StripePaymentService implements IPaymentService {
     input: CheckoutInput,
     options: PaymentRequestOptions,
   ): Promise<CheckoutResult> {
-    return this.request('checkout.sessions.create', () =>
-      this.stripe.checkout.sessions.create(
-        { ...input, mode: 'setup' },
-        { maxNetworkRetries: 2, ...options },
-      ),
+    return stripeRequest('checkout.sessions.create', () =>
+      this.stripe.checkout.sessions.create({ ...input, mode: 'setup' }, options),
     )
   }
 
-  /** Force confirmation and off-session use; preserve native card failures for application handling. */
+  /** Force confirmation and off-session use; retain native card failures in PaymentServiceError.cause. */
   chargeSavedMethod(
     input: SavedMethodCharge,
     options: PaymentRequestOptions,
   ): Promise<PaymentResult> {
-    return this.request('paymentIntents.create', () =>
-      this.stripe.paymentIntents.create(
-        { ...input, confirm: true, off_session: true },
-        { maxNetworkRetries: 2, ...options },
-      ),
+    return stripeRequest('paymentIntents.create', () =>
+      this.stripe.paymentIntents.create({ ...input, confirm: true, off_session: true }, options),
     )
   }
 
@@ -109,21 +98,8 @@ export class StripePaymentService implements IPaymentService {
     params?: Stripe.PaymentIntentRetrieveParams,
     options?: Stripe.RequestOptions,
   ): Promise<PaymentResult> {
-    return this.request('paymentIntents.retrieve', () =>
-      this.stripe.paymentIntents.retrieve(paymentId, params, { maxNetworkRetries: 2, ...options }),
+    return stripeRequest('paymentIntents.retrieve', () =>
+      this.stripe.paymentIntents.retrieve(paymentId, params, options),
     )
   }
-
-  private async request<T>(operation: string, work: () => Promise<T>): Promise<T> {
-    try {
-      return await work()
-    } catch (cause) {
-      if (
-        !(cause instanceof Stripe.errors.StripeError) ||
-        cause instanceof Stripe.errors.StripeCardError
-      )
-        throw cause
-      throw new PaymentServiceError(operation, cause)
-    }
-  }
 }

package/src/infrastructure/stripe/request.ts

@@ -0,0 +1,17 @@
+import Stripe from 'stripe'
+
+import { PaymentServiceError } from './payment-service.error.ts'
+
+/**
+ * Invoke one SDK operation; the SDK owns retries configured on its client or request.
+ * Convert every Stripe error to PaymentServiceError without logging; preserve the original error in cause.
+ * Non-Stripe failures propagate unchanged.
+ */
+export async function stripeRequest<T>(operation: string, work: () => Promise<T>): Promise<T> {
+  try {
+    return await work()
+  } catch (cause) {
+    if (!(cause instanceof Stripe.errors.StripeError)) throw cause
+    throw new PaymentServiceError(operation, cause)
+  }
+}

package/src/infrastructure/testing/payment-service-contract.ts

@@ -1,8 +1,10 @@
-import { deepStrictEqual, equal, rejects } from 'node:assert/strict'
+import { deepStrictEqual, equal, ok, rejects } from 'node:assert/strict'
 
 import Stripe from 'stripe'
 
+import { PaymentServiceError } from '../stripe/payment-service.error.ts'
 import type { IPaymentService } from '../stripe/payment-service.ts'
+import { stripeFixture } from './stripe-fixture.ts'
 
 /**
  * Test a Stripe payment adapter through native fetch injection without live payments.
@@ -50,7 +52,7 @@ export function paymentServiceContract(
     )
   })
 
-  test('card failures retain the native error contract', async () => {
+  test('card failures retain the native error in cause', async () => {
     const response = Response.json(
       {
         error: {
@@ -67,7 +69,12 @@ export function paymentServiceContract(
         { amount: 1000, currency: 'usd', customer: 'cus_contract', payment_method: 'pm_contract' },
         { idempotencyKey: 'charge:contract' },
       ),
-      Stripe.errors.StripeCardError,
+      (error) => {
+        ok(error instanceof PaymentServiceError)
+        ok(error.cause instanceof Stripe.errors.StripeCardError)
+        equal(error.cause.code, 'authentication_required')
+        return true
+      },
     )
   })
 }
@@ -76,16 +83,6 @@ function paymentFixture(
   create: (stripe: Stripe) => IPaymentService,
   response = Response.json({ id: 'pi_contract', status: 'requires_capture' }),
 ) {
-  const requests: { headers: Headers; body: URLSearchParams }[] = []
-  const stripe = new Stripe('sk_test_contract', {
-    httpClient: Stripe.createFetchHttpClient(async (input, init) => {
-      const request = new Request(input, init)
-      requests.push({
-        headers: request.headers,
-        body: new URLSearchParams(new TextDecoder().decode(await request.arrayBuffer())),
-      })
-      return response.clone()
-    }),
-  })
+  const { stripe, requests } = stripeFixture(() => response.clone())
   return { service: create(stripe), requests }
 }

package/src/infrastructure/testing/stripe-fixture.ts

@@ -0,0 +1,42 @@
+import Stripe from 'stripe'
+
+import { createStripeClient } from '../stripe/client.ts'
+
+/** One SDK HTTP attempt; query and body expose Stripe's URL-encoded parameters. */
+export type StripeCall = {
+  readonly method: string
+  readonly path: string
+  readonly query: URLSearchParams
+  readonly body: URLSearchParams
+  readonly headers: Headers
+}
+
+type StripeFixture = { stripe: Stripe; requests: readonly StripeCall[] }
+
+/**
+ * Construct the real SDK with a fake fetch transport and an ordered record of HTTP attempts.
+ * The responder receives an unread request. The shared client factory supplies retry defaults.
+ */
+export function stripeFixture(
+  respond: (request: Request) => Response | Promise<Response>,
+): StripeFixture {
+  const requests: StripeCall[] = []
+  const stripe = createStripeClient('sk_test_fixture', {
+    httpClient: Stripe.createFetchHttpClient(async (input, init) => {
+      const request = new Request(input, init)
+      const url = new URL(request.url)
+      const call: StripeCall = {
+        method: request.method,
+        path: url.pathname,
+        query: url.searchParams,
+        body: new URLSearchParams(),
+        headers: new Headers(request.headers),
+      }
+      requests.push(call)
+      const body = new TextDecoder().decode(await request.clone().arrayBuffer())
+      for (const [key, value] of new URLSearchParams(body)) call.body.append(key, value)
+      return respond(request)
+    }),
+  })
+  return { stripe, requests }
+}