@dineway-ai/plugin-payment 0.2.1

package/src/stripe/checkout-provider.ts

@@ -0,0 +1,567 @@
+import Stripe from "stripe";
+
+import type {
+	StripeAddress,
+	StripeCancelPaymentIntentInput,
+	StripeCapturePaymentIntentInput,
+	StripeCheckoutProvider,
+	StripeIncrementAuthorizationInput,
+	StripePaymentIntentInput,
+	StripePaymentIntentOperationResult,
+	StripePaymentIntentResult,
+	StripePaymentIntentStatus,
+	StripeTaxCalculationInput,
+	StripeTaxCalculationResult,
+	StripeTaxLineBreakdown,
+} from "../types.js";
+import { stripeProviderFailure } from "./errors.js";
+
+const CURRENCY_PATTERN = /^[A-Z]{3}$/i;
+
+export interface StripeCheckoutTaxCalculationResponse {
+	id: string | null;
+	apiVersion: string;
+	livemode: boolean;
+	currency: string;
+	expiresAt: number | null;
+	amountTotalMinor: number;
+	taxAmountExclusiveMinor: number;
+	taxAmountInclusiveMinor: number;
+	lineItems: Array<{
+		reference: string;
+		amountMinor: number;
+		taxMinor: number;
+		quantity: number;
+		taxBehavior: "exclusive" | "inclusive";
+		taxCode: string;
+		breakdown: StripeTaxLineBreakdown[];
+	}>;
+}
+
+export interface StripeCheckoutPaymentIntentResponse {
+	id: string;
+	apiVersion: string;
+	clientSecret: string | null;
+	livemode: boolean;
+	status: StripePaymentIntentStatus;
+	amountMinor: number;
+	amountReceivedMinor: number;
+	amountCapturableMinor: number;
+	currency: string;
+	incrementalAuthorizationSupported?: boolean | null;
+}
+
+export interface StripeCheckoutClient {
+	createTaxCalculation(
+		params: Stripe.Tax.CalculationCreateParams,
+		options: Pick<Stripe.RequestOptions, "idempotencyKey">,
+	): Promise<StripeCheckoutTaxCalculationResponse>;
+	createPaymentIntent(
+		params: Stripe.PaymentIntentCreateParams,
+		options: Pick<Stripe.RequestOptions, "idempotencyKey">,
+	): Promise<StripeCheckoutPaymentIntentResponse>;
+	capturePaymentIntent?(
+		paymentIntentId: string,
+		params: Stripe.PaymentIntentCaptureParams,
+		options: Pick<Stripe.RequestOptions, "idempotencyKey">,
+	): Promise<StripeCheckoutPaymentIntentResponse>;
+	incrementAuthorization?(
+		paymentIntentId: string,
+		params: Stripe.PaymentIntentIncrementAuthorizationParams,
+		options: Pick<Stripe.RequestOptions, "idempotencyKey">,
+	): Promise<StripeCheckoutPaymentIntentResponse>;
+	cancelPaymentIntent?(
+		paymentIntentId: string,
+		params: Stripe.PaymentIntentCancelParams,
+		options: Pick<Stripe.RequestOptions, "idempotencyKey">,
+	): Promise<StripeCheckoutPaymentIntentResponse>;
+}
+
+export type StripeCheckoutClientFactory = (secretKey: string) => StripeCheckoutClient;
+
+export class StripeNodeCheckoutProvider implements StripeCheckoutProvider {
+	constructor(
+		private readonly createClient: StripeCheckoutClientFactory = createStripeCheckoutClient,
+	) {}
+
+	async calculateTax(input: StripeTaxCalculationInput): Promise<StripeTaxCalculationResult> {
+		try {
+			assertTaxCalculationInput(input);
+			const calculation = await this.createClient(input.secretKey).createTaxCalculation(
+				{
+					currency: input.currency.toLowerCase(),
+					customer_details: {
+						address: stripeAddress(input.customerAddress),
+						address_source: input.customerAddressSource,
+					},
+					ship_from_details: { address: stripeAddress(input.shipFromAddress) },
+					line_items: input.lines.map((line) => ({
+						amount: line.amountMinor,
+						quantity: line.quantity,
+						reference: line.reference,
+						tax_behavior: line.taxBehavior,
+						...(line.taxCode ? { tax_code: line.taxCode } : {}),
+					})),
+					...(input.taxDate === undefined ? {} : { tax_date: input.taxDate }),
+					expand: ["line_items"],
+				},
+				{ idempotencyKey: input.idempotencyKey },
+			);
+			assertTaxCalculationResponse(input, calculation);
+			const linesByReference = new Map(
+				calculation.lineItems.map((line) => [line.reference, line] as const),
+			);
+			return {
+				ok: true,
+				calculationId: calculation.id,
+				apiVersion: calculation.apiVersion,
+				livemode: calculation.livemode,
+				currency: calculation.currency.toUpperCase(),
+				expiresAt: calculation.expiresAt,
+				amountTotalMinor: calculation.amountTotalMinor,
+				taxAmountExclusiveMinor: calculation.taxAmountExclusiveMinor,
+				taxAmountInclusiveMinor: calculation.taxAmountInclusiveMinor,
+				lines: input.lines.map((line) => {
+					const projected = linesByReference.get(line.reference);
+					if (!projected) throw new Error("Stripe Tax response omitted a requested line");
+					return projected;
+				}),
+			};
+		} catch (error) {
+			return stripeProviderFailure(error);
+		}
+	}
+
+	async createPaymentIntent(input: StripePaymentIntentInput): Promise<StripePaymentIntentResult> {
+		try {
+			assertPaymentIntentInput(input);
+			const paymentIntent = await this.createClient(input.secretKey).createPaymentIntent(
+				{
+					amount: input.amountMinor,
+					currency: input.currency.toLowerCase(),
+					automatic_payment_methods: { enabled: true },
+					...(input.captureMethod ? { capture_method: input.captureMethod } : {}),
+					...(input.requestIncrementalAuthorizationSupport || input.requestOvercapture
+						? {
+								payment_method_options: {
+									card: {
+										...(input.requestIncrementalAuthorizationSupport
+											? { request_incremental_authorization: "if_available" as const }
+											: {}),
+										...(input.requestOvercapture
+											? { request_overcapture: "if_available" as const }
+											: {}),
+									},
+								},
+							}
+						: {}),
+					description: input.description,
+					...(input.metadata ? { metadata: input.metadata } : {}),
+					...(input.receiptEmail ? { receipt_email: input.receiptEmail } : {}),
+				},
+				{ idempotencyKey: input.idempotencyKey },
+			);
+			assertPaymentIntentResponse(input, paymentIntent);
+			return {
+				ok: true,
+				paymentIntentId: paymentIntent.id,
+				apiVersion: paymentIntent.apiVersion,
+				clientSecret: paymentIntent.clientSecret,
+				livemode: paymentIntent.livemode,
+				status: paymentIntent.status,
+				amountMinor: paymentIntent.amountMinor,
+				amountReceivedMinor: paymentIntent.amountReceivedMinor,
+				amountCapturableMinor: paymentIntent.amountCapturableMinor,
+				currency: paymentIntent.currency.toUpperCase(),
+				...(paymentIntent.incrementalAuthorizationSupported === undefined
+					? {}
+					: { incrementalAuthorizationSupported: paymentIntent.incrementalAuthorizationSupported }),
+			};
+		} catch (error) {
+			return stripeProviderFailure(error);
+		}
+	}
+
+	async capturePaymentIntent(
+		input: StripeCapturePaymentIntentInput,
+	): Promise<StripePaymentIntentOperationResult> {
+		try {
+			assertOperationInput(input, true);
+			const client = this.createClient(input.secretKey);
+			if (!client.capturePaymentIntent) throw new Error("Stripe capture is unavailable");
+			const paymentIntent = await client.capturePaymentIntent(
+				input.paymentIntentId,
+				{
+					amount_to_capture: input.amountMinor,
+					...(input.metadata ? { metadata: input.metadata } : {}),
+				},
+				{ idempotencyKey: input.idempotencyKey },
+			);
+			assertCaptureResponse(input, paymentIntent);
+			return operationSuccess(paymentIntent);
+		} catch (error) {
+			return stripeProviderFailure(error);
+		}
+	}
+
+	async incrementAuthorization(
+		input: StripeIncrementAuthorizationInput,
+	): Promise<StripePaymentIntentOperationResult> {
+		try {
+			assertOperationInput(input, true);
+			const client = this.createClient(input.secretKey);
+			if (!client.incrementAuthorization) {
+				throw new Error("Stripe incremental authorization is unavailable");
+			}
+			const paymentIntent = await client.incrementAuthorization(
+				input.paymentIntentId,
+				{
+					amount: input.amountMinor,
+					...(input.metadata ? { metadata: input.metadata } : {}),
+				},
+				{ idempotencyKey: input.idempotencyKey },
+			);
+			assertIncrementResponse(input, paymentIntent);
+			return operationSuccess(paymentIntent);
+		} catch (error) {
+			return stripeProviderFailure(error);
+		}
+	}
+
+	async cancelPaymentIntent(
+		input: StripeCancelPaymentIntentInput,
+	): Promise<StripePaymentIntentOperationResult> {
+		try {
+			assertOperationInput(input, false);
+			const client = this.createClient(input.secretKey);
+			if (!client.cancelPaymentIntent) throw new Error("Stripe cancellation is unavailable");
+			const paymentIntent = await client.cancelPaymentIntent(
+				input.paymentIntentId,
+				{ cancellation_reason: input.reason ?? "requested_by_customer" },
+				{ idempotencyKey: input.idempotencyKey },
+			);
+			assertCancelResponse(input, paymentIntent);
+			return operationSuccess(paymentIntent);
+		} catch (error) {
+			return stripeProviderFailure(error);
+		}
+	}
+}
+
+function createStripeCheckoutClient(secretKey: string): StripeCheckoutClient {
+	const stripe = new Stripe(secretKey, {
+		appInfo: { name: "Dineway Payments" },
+		maxNetworkRetries: 1,
+		timeout: 15_000,
+		typescript: true,
+	});
+	return {
+		async createTaxCalculation(params, options) {
+			const calculation = await stripe.tax.calculations.create(params, options);
+			const expandedLines = calculation.line_items;
+			const lines =
+				expandedLines &&
+				!expandedLines.has_more &&
+				expandedLines.data.length === params.line_items.length
+					? expandedLines.data
+					: calculation.id
+						? await stripe.tax.calculations
+								.listLineItems(calculation.id, { limit: 100 })
+								.autoPagingToArray({ limit: 100 })
+						: [];
+			return {
+				id: calculation.id,
+				apiVersion: calculation.lastResponse.apiVersion ?? Stripe.API_VERSION,
+				livemode: calculation.livemode,
+				currency: calculation.currency,
+				expiresAt: calculation.expires_at,
+				amountTotalMinor: calculation.amount_total,
+				taxAmountExclusiveMinor: calculation.tax_amount_exclusive,
+				taxAmountInclusiveMinor: calculation.tax_amount_inclusive,
+				lineItems: lines.map((line) => ({
+					reference: line.reference,
+					amountMinor: line.amount,
+					taxMinor: line.amount_tax,
+					quantity: line.quantity,
+					taxBehavior: line.tax_behavior,
+					taxCode: line.tax_code,
+					breakdown: (line.tax_breakdown ?? []).map((item) => ({
+						amountMinor: item.amount,
+						taxableAmountMinor: item.taxable_amount,
+						taxabilityReason: item.taxability_reason,
+						sourcing: item.sourcing,
+						jurisdiction: {
+							countryCode: item.jurisdiction.country,
+							regionCode: item.jurisdiction.state,
+							displayName: item.jurisdiction.display_name,
+							level: item.jurisdiction.level,
+						},
+						rate: item.tax_rate_details
+							? {
+									displayName: item.tax_rate_details.display_name,
+									percentage: item.tax_rate_details.percentage_decimal,
+									taxType: item.tax_rate_details.tax_type,
+								}
+							: null,
+					})),
+				})),
+			};
+		},
+		async createPaymentIntent(params, options) {
+			return projectPaymentIntent(await stripe.paymentIntents.create(params, options));
+		},
+		async capturePaymentIntent(paymentIntentId, params, options) {
+			return projectPaymentIntent(
+				await stripe.paymentIntents.capture(paymentIntentId, params, options),
+			);
+		},
+		async incrementAuthorization(paymentIntentId, params, options) {
+			return projectPaymentIntent(
+				await stripe.paymentIntents.incrementAuthorization(paymentIntentId, params, options),
+			);
+		},
+		async cancelPaymentIntent(paymentIntentId, params, options) {
+			return projectPaymentIntent(
+				await stripe.paymentIntents.cancel(paymentIntentId, params, options),
+			);
+		},
+	};
+}
+
+function projectPaymentIntent(
+	paymentIntent: Stripe.Response<Stripe.PaymentIntent>,
+): StripeCheckoutPaymentIntentResponse {
+	const incrementalAuthorizationSupported = readIncrementalAuthorizationSupported(paymentIntent);
+	return {
+		id: paymentIntent.id,
+		apiVersion: paymentIntent.lastResponse.apiVersion ?? Stripe.API_VERSION,
+		clientSecret: paymentIntent.client_secret,
+		livemode: paymentIntent.livemode,
+		status: paymentIntent.status,
+		amountMinor: paymentIntent.amount,
+		amountReceivedMinor: paymentIntent.amount_received,
+		amountCapturableMinor: paymentIntent.amount_capturable,
+		currency: paymentIntent.currency,
+		...(incrementalAuthorizationSupported === undefined
+			? {}
+			: { incrementalAuthorizationSupported }),
+	};
+}
+
+function stripeAddress(address: StripeAddress) {
+	return {
+		country: address.countryCode.toUpperCase(),
+		...(address.line1 ? { line1: address.line1 } : {}),
+		...(address.line2 ? { line2: address.line2 } : {}),
+		...(address.city ? { city: address.city } : {}),
+		...(address.region ? { state: address.region } : {}),
+		...(address.postalCode ? { postal_code: address.postalCode } : {}),
+	};
+}
+
+function assertTaxCalculationInput(input: StripeTaxCalculationInput): void {
+	if (!input.secretKey.trim() || !input.idempotencyKey.trim() || !CURRENCY_PATTERN.test(input.currency)) {
+		throw new Error("Stripe Tax credentials or currency are invalid");
+	}
+	if (input.lines.length === 0 || input.lines.length > 100) {
+		throw new Error("Stripe Tax requires between one and 100 lines");
+	}
+	const references = new Set<string>();
+	for (const line of input.lines) {
+		if (!line.reference || references.has(line.reference)) {
+			throw new Error("Stripe Tax line references must be non-empty and unique");
+		}
+		references.add(line.reference);
+		if (!Number.isSafeInteger(line.amountMinor) || line.amountMinor <= 0) {
+			throw new Error("Stripe Tax line amounts must be positive safe integers");
+		}
+		if (!Number.isSafeInteger(line.quantity) || line.quantity <= 0) {
+			throw new Error("Stripe Tax line quantities must be positive safe integers");
+		}
+	}
+}
+
+function assertTaxCalculationResponse(
+	input: StripeTaxCalculationInput,
+	response: StripeCheckoutTaxCalculationResponse,
+): asserts response is StripeCheckoutTaxCalculationResponse & { id: string } {
+	if (!response.id || !response.apiVersion) throw new Error("Stripe Tax response is incomplete");
+	if (response.currency.toUpperCase() !== input.currency.toUpperCase()) {
+		throw new Error("Stripe Tax response currency does not match the request");
+	}
+	for (const amount of [
+		response.amountTotalMinor,
+		response.taxAmountExclusiveMinor,
+		response.taxAmountInclusiveMinor,
+	]) {
+		if (!Number.isSafeInteger(amount) || amount < 0) {
+			throw new Error("Stripe Tax response contains an invalid amount");
+		}
+	}
+	const responseLines = new Map(response.lineItems.map((line) => [line.reference, line] as const));
+	if (response.lineItems.length !== input.lines.length || responseLines.size !== input.lines.length) {
+		throw new Error("Stripe Tax response line set does not match the request");
+	}
+	let calculatedTaxMinor = 0;
+	let calculatedTotalMinor = 0;
+	for (const line of input.lines) {
+		const responseLine = responseLines.get(line.reference);
+		if (
+			!responseLine ||
+			responseLine.amountMinor !== line.amountMinor ||
+			responseLine.quantity !== line.quantity ||
+			responseLine.taxBehavior !== line.taxBehavior ||
+			(line.taxCode !== null && responseLine.taxCode !== line.taxCode) ||
+			!Number.isSafeInteger(responseLine.taxMinor) ||
+			responseLine.taxMinor < 0
+		) {
+			throw new Error("Stripe Tax response line does not match the request");
+		}
+		calculatedTaxMinor += responseLine.taxMinor;
+		calculatedTotalMinor += responseLine.amountMinor;
+	}
+	if (
+		calculatedTaxMinor !== response.taxAmountExclusiveMinor + response.taxAmountInclusiveMinor ||
+		calculatedTotalMinor + response.taxAmountExclusiveMinor !== response.amountTotalMinor
+	) {
+		throw new Error("Stripe Tax response totals are inconsistent");
+	}
+}
+
+function assertPaymentIntentInput(input: StripePaymentIntentInput): void {
+	if (
+		!input.secretKey.trim() ||
+		!input.idempotencyKey.trim() ||
+		!Number.isSafeInteger(input.amountMinor) ||
+		input.amountMinor <= 0 ||
+		!CURRENCY_PATTERN.test(input.currency) ||
+		!input.description.trim() ||
+		input.description.length > 500 ||
+		!validMetadata(input.metadata)
+	) {
+		throw new Error("Stripe PaymentIntent input is invalid");
+	}
+}
+
+function assertPaymentIntentResponse(
+	input: StripePaymentIntentInput,
+	response: StripeCheckoutPaymentIntentResponse,
+): asserts response is StripeCheckoutPaymentIntentResponse & { clientSecret: string } {
+	if (!response.id || !response.apiVersion || !response.clientSecret) {
+		throw new Error("Stripe PaymentIntent response is incomplete");
+	}
+	if (
+		response.amountMinor !== input.amountMinor ||
+		response.currency.toUpperCase() !== input.currency.toUpperCase()
+	) {
+		throw new Error("Stripe PaymentIntent response does not match the request");
+	}
+}
+
+function assertOperationInput(
+	input: StripeCancelPaymentIntentInput | StripeCapturePaymentIntentInput | StripeIncrementAuthorizationInput,
+	requireAmount: boolean,
+): void {
+	if (
+		!input.secretKey.trim() ||
+		!input.idempotencyKey.trim() ||
+		!input.paymentIntentId.startsWith("pi_") ||
+		!CURRENCY_PATTERN.test(input.currency) ||
+		!validMetadata(input.metadata)
+	) {
+		throw new Error("Stripe PaymentIntent operation input is invalid");
+	}
+	if (requireAmount) {
+		const amount = (input as StripeCapturePaymentIntentInput).amountMinor;
+		if (!Number.isSafeInteger(amount) || amount <= 0) {
+			throw new Error("Stripe PaymentIntent operation amount is invalid");
+		}
+	}
+}
+
+function assertCaptureResponse(
+	input: StripeCapturePaymentIntentInput,
+	response: StripeCheckoutPaymentIntentResponse,
+): void {
+	assertMatchingOperationResponse(input, response);
+	if (
+		response.amountMinor < input.amountMinor ||
+		response.amountReceivedMinor !== input.amountMinor ||
+		response.amountReceivedMinor > response.amountMinor
+	) {
+		throw new Error("Stripe capture response amount is invalid");
+	}
+}
+
+function assertIncrementResponse(
+	input: StripeIncrementAuthorizationInput,
+	response: StripeCheckoutPaymentIntentResponse,
+): void {
+	assertMatchingOperationResponse(input, response);
+	if (
+		response.amountMinor !== input.amountMinor ||
+		response.amountReceivedMinor + response.amountCapturableMinor > response.amountMinor
+	) {
+		throw new Error("Stripe incremental authorization response is invalid");
+	}
+}
+
+function assertCancelResponse(
+	input: StripeCancelPaymentIntentInput,
+	response: StripeCheckoutPaymentIntentResponse,
+): void {
+	assertMatchingOperationResponse(input, response);
+	if (response.status !== "canceled" || response.amountCapturableMinor !== 0) {
+		throw new Error("Stripe cancellation response is invalid");
+	}
+}
+
+function assertMatchingOperationResponse(
+	input: StripeCancelPaymentIntentInput | StripeCapturePaymentIntentInput | StripeIncrementAuthorizationInput,
+	response: StripeCheckoutPaymentIntentResponse,
+): void {
+	if (
+		!response.id.startsWith("pi_") ||
+		!response.apiVersion ||
+		response.id !== input.paymentIntentId ||
+		response.currency.toUpperCase() !== input.currency.toUpperCase()
+	) {
+		throw new Error("Stripe PaymentIntent operation response does not match the request");
+	}
+}
+
+function operationSuccess(response: StripeCheckoutPaymentIntentResponse) {
+	return {
+		ok: true as const,
+		paymentIntentId: response.id,
+		apiVersion: response.apiVersion,
+		livemode: response.livemode,
+		status: response.status,
+		amountMinor: response.amountMinor,
+		amountReceivedMinor: response.amountReceivedMinor,
+		amountCapturableMinor: response.amountCapturableMinor,
+		currency: response.currency.toUpperCase(),
+		...(response.incrementalAuthorizationSupported === undefined
+			? {}
+			: { incrementalAuthorizationSupported: response.incrementalAuthorizationSupported }),
+	};
+}
+
+function validMetadata(metadata: Record<string, string> | undefined): boolean {
+	if (!metadata) return true;
+	const entries = Object.entries(metadata);
+	return (
+		entries.length <= 50 &&
+		entries.every(
+			([key, value]) => key.length > 0 && key.length <= 40 && value.length > 0 && value.length <= 500,
+		)
+	);
+}
+
+function readIncrementalAuthorizationSupported(
+	paymentIntent: Stripe.PaymentIntent,
+): boolean | null | undefined {
+	const latestCharge = paymentIntent.latest_charge;
+	if (!latestCharge || typeof latestCharge !== "object") return undefined;
+	return latestCharge.payment_method_details?.card_present?.incremental_authorization_supported;
+}

package/src/stripe/errors.ts

@@ -0,0 +1,28 @@
+import Stripe from "stripe";
+
+import type { StripeProviderFailure } from "../types.js";
+
+export function stripeProviderFailure(error: unknown): StripeProviderFailure {
+	if (error instanceof Stripe.errors.StripeAuthenticationError) {
+		return { ok: false, errorCode: "authentication_failed", retryable: false };
+	}
+	if (error instanceof Stripe.errors.StripePermissionError) {
+		return { ok: false, errorCode: "permission_denied", retryable: false };
+	}
+	if (error instanceof Stripe.errors.StripeRateLimitError) {
+		return { ok: false, errorCode: "rate_limited", retryable: true };
+	}
+	if (error instanceof Stripe.errors.StripeConnectionError) {
+		return { ok: false, errorCode: "connection_error", retryable: true };
+	}
+	if (
+		error instanceof Stripe.errors.StripeInvalidRequestError ||
+		error instanceof Stripe.errors.StripeIdempotencyError
+	) {
+		return { ok: false, errorCode: "invalid_request", retryable: false };
+	}
+	if (error instanceof Stripe.errors.StripeAPIError) {
+		return { ok: false, errorCode: "provider_error", retryable: true };
+	}
+	return { ok: false, errorCode: "provider_error", retryable: false };
+}

package/src/stripe/index.ts

@@ -0,0 +1,5 @@
+export * from "./account-probe.js";
+export * from "./checkout-provider.js";
+export * from "./errors.js";
+export * from "./refund-provider.js";
+export * from "./webhook-verifier.js";