@dineway-ai/plugin-payment 0.2.1

package/src/stripe/refund-provider.ts

@@ -0,0 +1,144 @@
+import Stripe from "stripe";
+
+import type {
+	StripeRefundInput,
+	StripeRefundProvider,
+	StripeRefundResult,
+	StripeRefundStatus,
+} from "../types.js";
+import { stripeProviderFailure } from "./errors.js";
+
+const SAFE_FAILURE_REASON = /^[a-z][a-z0-9_]{0,63}$/;
+const CURRENCY_PATTERN = /^[A-Z]{3}$/i;
+
+export interface StripeRefundResponse {
+	id: string;
+	apiVersion: string;
+	paymentIntentId: string | null;
+	status: string | null;
+	amountMinor: number;
+	currency: string;
+	failureReason: string | null;
+}
+
+export interface StripeRefundClient {
+	createRefund(
+		params: Stripe.RefundCreateParams,
+		options: Pick<Stripe.RequestOptions, "idempotencyKey">,
+	): Promise<StripeRefundResponse>;
+}
+
+export type StripeRefundClientFactory = (secretKey: string) => StripeRefundClient;
+
+export class StripeNodeRefundProvider implements StripeRefundProvider {
+	constructor(
+		private readonly createClient: StripeRefundClientFactory = createStripeRefundClient,
+	) {}
+
+	async createRefund(input: StripeRefundInput): Promise<StripeRefundResult> {
+		try {
+			assertRefundInput(input);
+			const response = await this.createClient(input.secretKey).createRefund(
+				{
+					payment_intent: input.paymentIntentId,
+					amount: input.amountMinor,
+					reason: input.reason,
+					...(input.metadata ? { metadata: input.metadata } : {}),
+				},
+				{ idempotencyKey: input.idempotencyKey },
+			);
+			const status = refundStatus(response.status);
+			if (
+				!response.id ||
+				!response.apiVersion ||
+				response.paymentIntentId !== input.paymentIntentId ||
+				response.amountMinor !== input.amountMinor ||
+				response.currency.toUpperCase() !== input.currency.toUpperCase()
+			) {
+				throw new Error("Stripe Refund response does not match the request");
+			}
+			return {
+				ok: true,
+				refundId: response.id,
+				paymentIntentId: response.paymentIntentId,
+				apiVersion: response.apiVersion,
+				livemode: input.secretKey.startsWith("sk_live_"),
+				status,
+				amountMinor: response.amountMinor,
+				currency: response.currency.toUpperCase(),
+				failureReason:
+					response.failureReason && SAFE_FAILURE_REASON.test(response.failureReason)
+						? response.failureReason
+						: response.failureReason
+							? "provider_error"
+							: null,
+			};
+		} catch (error) {
+			return stripeProviderFailure(error);
+		}
+	}
+}
+
+function createStripeRefundClient(secretKey: string): StripeRefundClient {
+	const stripe = new Stripe(secretKey, {
+		appInfo: { name: "Dineway Payments" },
+		maxNetworkRetries: 1,
+		timeout: 15_000,
+		typescript: true,
+	});
+	return {
+		async createRefund(params, options) {
+			const refund = await stripe.refunds.create(params, options);
+			return {
+				id: refund.id,
+				apiVersion: refund.lastResponse.apiVersion ?? Stripe.API_VERSION,
+				paymentIntentId:
+					typeof refund.payment_intent === "string"
+						? refund.payment_intent
+						: (refund.payment_intent?.id ?? null),
+				status: refund.status,
+				amountMinor: refund.amount,
+				currency: refund.currency,
+				failureReason: refund.failure_reason ?? null,
+			};
+		},
+	};
+}
+
+function assertRefundInput(input: StripeRefundInput): void {
+	if (
+		(!input.secretKey.startsWith("sk_test_") && !input.secretKey.startsWith("sk_live_")) ||
+		!input.idempotencyKey.trim() ||
+		!input.paymentIntentId.startsWith("pi_") ||
+		!Number.isSafeInteger(input.amountMinor) ||
+		input.amountMinor <= 0 ||
+		!CURRENCY_PATTERN.test(input.currency) ||
+		!validMetadata(input.metadata)
+	) {
+		throw new Error("Stripe Refund input is invalid");
+	}
+}
+
+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 refundStatus(value: string | null): StripeRefundStatus {
+	if (
+		value === "pending" ||
+		value === "requires_action" ||
+		value === "succeeded" ||
+		value === "failed" ||
+		value === "canceled"
+	) {
+		return value;
+	}
+	throw new Error("Stripe Refund status is invalid");
+}

package/src/stripe/webhook-verifier.ts

@@ -0,0 +1,223 @@
+import { createHash } from "node:crypto";
+
+import Stripe from "stripe";
+
+import type {
+	StripePaymentIntentStatus,
+	StripeRefundStatus,
+	StripeWebhookEvent,
+	StripeWebhookPaymentIntent,
+	StripeWebhookRefund,
+	StripeWebhookVerificationInput,
+	StripeWebhookVerificationResult,
+	StripeWebhookVerifier,
+} from "../types.js";
+
+export const STRIPE_WEBHOOK_MAX_BYTES = 256 * 1024;
+const WEBHOOK_TOLERANCE_SECONDS = 300;
+const CURRENCY_PATTERN = /^[A-Za-z]{3}$/;
+const PAYMENT_INTENT_STATUSES = new Set<StripePaymentIntentStatus>([
+	"requires_payment_method",
+	"requires_confirmation",
+	"requires_action",
+	"processing",
+	"requires_capture",
+	"canceled",
+	"succeeded",
+]);
+const REFUND_STATUSES = new Set<StripeRefundStatus>([
+	"pending",
+	"requires_action",
+	"succeeded",
+	"failed",
+	"canceled",
+]);
+const SAFE_FAILURE_REASON = /^[a-z][a-z0-9_]{0,63}$/;
+
+export class StripeNodeWebhookVerifier implements StripeWebhookVerifier {
+	verify(input: StripeWebhookVerificationInput): StripeWebhookVerificationResult {
+		if (input.rawBody.byteLength === 0 || input.rawBody.byteLength > STRIPE_WEBHOOK_MAX_BYTES) {
+			return { ok: false, errorCode: "payload_invalid" };
+		}
+		if (!input.signature?.trim()) return { ok: false, errorCode: "signature_missing" };
+
+		let event: Stripe.Event;
+		try {
+			const stripe = new Stripe(input.secretKey, {
+				appInfo: { name: "Dineway Payments" },
+				maxNetworkRetries: 0,
+				timeout: 15_000,
+				typescript: true,
+			});
+			event = stripe.webhooks.constructEvent(
+				input.rawBody,
+				input.signature,
+				input.webhookSecret,
+				WEBHOOK_TOLERANCE_SECONDS,
+				undefined,
+				input.receivedAt,
+			);
+		} catch (error) {
+			return {
+				ok: false,
+				errorCode:
+					error instanceof Stripe.errors.StripeSignatureVerificationError
+						? "signature_invalid"
+						: "payload_invalid",
+			};
+		}
+
+		try {
+			return { ok: true, event: projectEvent(event, input.rawBody) };
+		} catch {
+			return { ok: false, errorCode: "event_invalid" };
+		}
+	}
+}
+
+function projectEvent(event: Stripe.Event, rawBody: Uint8Array): StripeWebhookEvent {
+	assertSafeString(event.id, 255);
+	assertSafeString(event.type, 255);
+	assertSafeInteger(event.created);
+	if (typeof event.livemode !== "boolean") throw new Error("Invalid Stripe event mode");
+	if (event.api_version !== null) assertSafeString(event.api_version, 64);
+
+	const objectRecord = asRecord(event.data.object as unknown);
+	const objectType = optionalSafeString(objectRecord?.object, 128);
+	const objectId = optionalSafeString(objectRecord?.id, 255);
+	if ((objectType === null) !== (objectId === null)) throw new Error("Incomplete Stripe object");
+
+	return {
+		eventId: event.id,
+		eventType: event.type,
+		eventCreated: event.created,
+		livemode: event.livemode,
+		apiVersion: event.api_version,
+		payloadSha256: `sha256:${createHash("sha256").update(rawBody).digest("hex")}`,
+		objectType,
+		objectId,
+		paymentIntent:
+			objectType === "payment_intent" ? projectPaymentIntent(objectRecord) : null,
+		refund: objectType === "refund" ? projectRefund(objectRecord) : null,
+	};
+}
+
+function projectPaymentIntent(value: Record<string, unknown> | null): StripeWebhookPaymentIntent {
+	if (!value) throw new Error("Stripe PaymentIntent is missing");
+	const status = requiredSafeString(value.status, 64);
+	if (!PAYMENT_INTENT_STATUSES.has(status as StripePaymentIntentStatus)) {
+		throw new Error("Stripe PaymentIntent status is invalid");
+	}
+	const incrementalAuthorizationSupported = readIncrementalAuthorizationSupported(value);
+	return {
+		id: requiredSafeString(value.id, 255),
+		status: status as StripePaymentIntentStatus,
+		amountMinor: requiredSafeInteger(value.amount),
+		amountReceivedMinor: requiredSafeInteger(value.amount_received),
+		amountCapturableMinor: requiredSafeInteger(value.amount_capturable),
+		currency: requiredCurrency(value.currency),
+		...(incrementalAuthorizationSupported === undefined
+			? {}
+			: { incrementalAuthorizationSupported }),
+		metadata: projectMetadata(value.metadata),
+	};
+}
+
+function projectRefund(value: Record<string, unknown> | null): StripeWebhookRefund {
+	if (!value) throw new Error("Stripe Refund is missing");
+	const status = requiredSafeString(value.status, 64);
+	if (!REFUND_STATUSES.has(status as StripeRefundStatus)) {
+		throw new Error("Stripe Refund status is invalid");
+	}
+	const failureReason = optionalSafeString(value.failure_reason, 64);
+	return {
+		id: requiredSafeString(value.id, 255),
+		status: status as StripeRefundStatus,
+		paymentIntentId: requiredRelationId(value.payment_intent, "pi_"),
+		amountMinor: requiredSafeInteger(value.amount),
+		currency: requiredCurrency(value.currency),
+		failureReason:
+			failureReason && SAFE_FAILURE_REASON.test(failureReason)
+				? failureReason
+				: failureReason
+					? "provider_error"
+					: null,
+		metadata: projectMetadata(value.metadata),
+	};
+}
+
+function projectMetadata(value: unknown): Record<string, string> {
+	const record = asRecord(value);
+	if (!record) return {};
+	const entries = Object.entries(record);
+	if (entries.length > 50) throw new Error("Stripe metadata exceeds the supported limit");
+	return Object.fromEntries(
+		entries.map(([key, item]) => {
+			assertSafeString(key, 40);
+			assertSafeString(item, 500);
+			return [key, item];
+		}),
+	);
+}
+
+function readIncrementalAuthorizationSupported(
+	value: Record<string, unknown>,
+): boolean | undefined {
+	const latestCharge = asRecord(value.latest_charge);
+	const paymentMethodDetails = asRecord(latestCharge?.payment_method_details);
+	const cardPresent = asRecord(paymentMethodDetails?.card_present);
+	if (!cardPresent || !("incremental_authorization_supported" in cardPresent)) return undefined;
+	const supported = cardPresent.incremental_authorization_supported;
+	if (typeof supported !== "boolean") {
+		throw new Error("Invalid Stripe incremental authorization capability");
+	}
+	return supported;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+	return typeof value === "object" && value !== null && !Array.isArray(value)
+		? (value as Record<string, unknown>)
+		: null;
+}
+
+function requiredSafeString(value: unknown, maxLength: number): string {
+	assertSafeString(value, maxLength);
+	return value;
+}
+
+function optionalSafeString(value: unknown, maxLength: number): string | null {
+	if (value === undefined || value === null || value === "") return null;
+	assertSafeString(value, maxLength);
+	return value;
+}
+
+function assertSafeString(value: unknown, maxLength: number): asserts value is string {
+	if (typeof value !== "string" || value.length === 0 || value.length > maxLength) {
+		throw new Error("Invalid Stripe string");
+	}
+}
+
+function requiredSafeInteger(value: unknown): number {
+	assertSafeInteger(value);
+	return value;
+}
+
+function assertSafeInteger(value: unknown): asserts value is number {
+	if (!Number.isSafeInteger(value) || (value as number) < 0) {
+		throw new Error("Invalid Stripe integer");
+	}
+}
+
+function requiredCurrency(value: unknown): string {
+	const currency = requiredSafeString(value, 3);
+	if (!CURRENCY_PATTERN.test(currency)) throw new Error("Invalid Stripe currency");
+	return currency.toUpperCase();
+}
+
+function requiredRelationId(value: unknown, prefix: string): string {
+	const record = asRecord(value);
+	const id = typeof value === "string" ? value : record?.id;
+	const normalized = requiredSafeString(id, 255);
+	if (!normalized.startsWith(prefix)) throw new Error("Invalid Stripe relation");
+	return normalized;
+}

package/src/types.ts

@@ -0,0 +1,290 @@
+export type StripeMode = "test" | "live";
+export type StripeTaxStatus = "unknown" | "active" | "pending" | "unavailable";
+
+export type StripeProviderErrorCode =
+	| "authentication_failed"
+	| "permission_denied"
+	| "rate_limited"
+	| "connection_error"
+	| "invalid_request"
+	| "provider_error";
+
+export interface StripeProviderFailure {
+	ok: false;
+	errorCode: StripeProviderErrorCode;
+	retryable: boolean;
+}
+
+export interface StripeAccountProbeInput {
+	mode: StripeMode;
+	secretKey: string;
+}
+
+export type StripeAccountProbeResult =
+	| {
+			ok: true;
+			accountId: string;
+			livemode: boolean;
+			chargesEnabled: boolean;
+			detailsSubmitted: boolean;
+			taxStatus: Exclude<StripeTaxStatus, "unknown">;
+	  }
+	| {
+			ok: false;
+			errorCode: string;
+	  };
+
+export interface StripeAccountProbe {
+	probe(input: StripeAccountProbeInput): Promise<StripeAccountProbeResult>;
+}
+
+export type StripePaymentIntentStatus =
+	| "requires_payment_method"
+	| "requires_confirmation"
+	| "requires_action"
+	| "processing"
+	| "requires_capture"
+	| "canceled"
+	| "succeeded";
+
+export type StripeRefundStatus =
+	| "pending"
+	| "requires_action"
+	| "succeeded"
+	| "failed"
+	| "canceled";
+
+export type StripeRefundReason = "duplicate" | "fraudulent" | "requested_by_customer";
+
+export interface StripeRefundInput {
+	secretKey: string;
+	idempotencyKey: string;
+	paymentIntentId: string;
+	amountMinor: number;
+	currency: string;
+	reason: StripeRefundReason;
+	metadata?: Record<string, string>;
+}
+
+export interface StripeRefundSuccess {
+	ok: true;
+	refundId: string;
+	paymentIntentId: string;
+	apiVersion: string;
+	livemode: boolean;
+	status: StripeRefundStatus;
+	amountMinor: number;
+	currency: string;
+	failureReason: string | null;
+}
+
+export type StripeRefundResult = StripeRefundSuccess | StripeProviderFailure;
+
+export interface StripeRefundProvider {
+	createRefund(input: StripeRefundInput): Promise<StripeRefundResult>;
+}
+
+export interface StripeAddress {
+	countryCode: string;
+	line1?: string;
+	line2?: string;
+	city?: string;
+	region?: string;
+	postalCode?: string;
+}
+
+export interface StripeTaxLineInput {
+	reference: string;
+	amountMinor: number;
+	quantity: number;
+	taxCode: string | null;
+	taxBehavior: "exclusive" | "inclusive";
+}
+
+export interface StripeTaxCalculationInput {
+	secretKey: string;
+	idempotencyKey: string;
+	currency: string;
+	customerAddress: StripeAddress;
+	customerAddressSource: "billing" | "shipping";
+	shipFromAddress: StripeAddress;
+	lines: StripeTaxLineInput[];
+	taxDate?: number;
+}
+
+export interface StripeTaxLineBreakdown {
+	amountMinor: number;
+	taxableAmountMinor: number;
+	taxabilityReason: string;
+	sourcing: "destination" | "origin";
+	jurisdiction: {
+		countryCode: string;
+		regionCode: string | null;
+		displayName: string;
+		level: "city" | "country" | "county" | "district" | "state";
+	};
+	rate: {
+		displayName: string;
+		percentage: string;
+		taxType: string;
+	} | null;
+}
+
+export interface StripeTaxCalculationSuccess {
+	ok: true;
+	calculationId: string;
+	apiVersion: string;
+	livemode: boolean;
+	currency: string;
+	expiresAt: number | null;
+	amountTotalMinor: number;
+	taxAmountExclusiveMinor: number;
+	taxAmountInclusiveMinor: number;
+	lines: Array<{
+		reference: string;
+		amountMinor: number;
+		taxMinor: number;
+		quantity: number;
+		taxBehavior: "exclusive" | "inclusive";
+		taxCode: string;
+		breakdown: StripeTaxLineBreakdown[];
+	}>;
+}
+
+export type StripeTaxCalculationResult = StripeTaxCalculationSuccess | StripeProviderFailure;
+
+export interface StripePaymentIntentInput {
+	secretKey: string;
+	idempotencyKey: string;
+	amountMinor: number;
+	currency: string;
+	description: string;
+	metadata?: Record<string, string>;
+	receiptEmail?: string | null;
+	captureMethod?: "automatic" | "manual";
+	requestIncrementalAuthorizationSupport?: boolean;
+	requestOvercapture?: boolean;
+}
+
+export interface StripePaymentIntentSuccess {
+	ok: true;
+	paymentIntentId: string;
+	apiVersion: string;
+	clientSecret: string;
+	livemode: boolean;
+	status: StripePaymentIntentStatus;
+	amountMinor: number;
+	amountReceivedMinor: number;
+	amountCapturableMinor: number;
+	currency: string;
+	incrementalAuthorizationSupported?: boolean | null;
+}
+
+export type StripePaymentIntentResult = StripePaymentIntentSuccess | StripeProviderFailure;
+
+export interface StripePaymentIntentOperationInput {
+	secretKey: string;
+	idempotencyKey: string;
+	paymentIntentId: string;
+	currency: string;
+	metadata?: Record<string, string>;
+}
+
+export interface StripeCapturePaymentIntentInput extends StripePaymentIntentOperationInput {
+	amountMinor: number;
+}
+
+export interface StripeIncrementAuthorizationInput extends StripePaymentIntentOperationInput {
+	amountMinor: number;
+}
+
+export interface StripeCancelPaymentIntentInput extends StripePaymentIntentOperationInput {
+	reason?: "duplicate" | "fraudulent" | "requested_by_customer" | "abandoned";
+}
+
+export interface StripePaymentIntentOperationSuccess {
+	ok: true;
+	paymentIntentId: string;
+	apiVersion: string;
+	livemode: boolean;
+	status: StripePaymentIntentStatus;
+	amountMinor: number;
+	amountReceivedMinor: number;
+	amountCapturableMinor: number;
+	currency: string;
+	incrementalAuthorizationSupported?: boolean | null;
+}
+
+export type StripePaymentIntentOperationResult =
+	| StripePaymentIntentOperationSuccess
+	| StripeProviderFailure;
+
+export interface StripeCheckoutProvider {
+	calculateTax(input: StripeTaxCalculationInput): Promise<StripeTaxCalculationResult>;
+	createPaymentIntent(input: StripePaymentIntentInput): Promise<StripePaymentIntentResult>;
+	capturePaymentIntent(
+		input: StripeCapturePaymentIntentInput,
+	): Promise<StripePaymentIntentOperationResult>;
+	incrementAuthorization(
+		input: StripeIncrementAuthorizationInput,
+	): Promise<StripePaymentIntentOperationResult>;
+	cancelPaymentIntent(
+		input: StripeCancelPaymentIntentInput,
+	): Promise<StripePaymentIntentOperationResult>;
+}
+
+export type StripeWebhookErrorCode =
+	| "signature_missing"
+	| "signature_invalid"
+	| "payload_invalid"
+	| "event_invalid";
+
+export interface StripeWebhookPaymentIntent {
+	id: string;
+	status: StripePaymentIntentStatus;
+	amountMinor: number;
+	amountReceivedMinor: number;
+	amountCapturableMinor: number;
+	currency: string;
+	incrementalAuthorizationSupported?: boolean | null;
+	metadata: Record<string, string>;
+}
+
+export interface StripeWebhookRefund {
+	id: string;
+	status: StripeRefundStatus;
+	paymentIntentId: string;
+	amountMinor: number;
+	currency: string;
+	failureReason: string | null;
+	metadata: Record<string, string>;
+}
+
+export interface StripeWebhookEvent {
+	eventId: string;
+	eventType: string;
+	eventCreated: number;
+	livemode: boolean;
+	apiVersion: string | null;
+	payloadSha256: string;
+	objectType: string | null;
+	objectId: string | null;
+	paymentIntent: StripeWebhookPaymentIntent | null;
+	refund: StripeWebhookRefund | null;
+}
+
+export type StripeWebhookVerificationResult =
+	| { ok: true; event: StripeWebhookEvent }
+	| { ok: false; errorCode: StripeWebhookErrorCode };
+
+export interface StripeWebhookVerificationInput {
+	secretKey: string;
+	webhookSecret: string;
+	signature: string | null;
+	rawBody: Uint8Array;
+	receivedAt?: number;
+}
+
+export interface StripeWebhookVerifier {
+	verify(input: StripeWebhookVerificationInput): StripeWebhookVerificationResult;
+}