@happyvertical/payments 0.105.4 → 0.105.5

package/dist/adapters/stripe.js

@@ -1,5 +1,5 @@
-import { a as PaymentVerificationError, r as PaymentProviderError, t as PaymentConfigurationError } from "../chunks/errors-feZrwnTy.js";
-import { _ as normalizeUrlString, a as formEncode, b as rememberPaymentOption, f as normalizeMaxStoredPaymentOptions, g as normalizePositivePaymentAmount, h as normalizePositiveMinorUnitAmount, m as normalizeNonEmptyString, o as getFetch, p as normalizeMinorUnitAmount, t as applyExpiryToPendingStatus, u as normalizeDate, v as pollPaymentStatus, y as readJsonResponse } from "../chunks/shared-DVl6UzD9.js";
+import { i as PaymentProviderError, o as PaymentVerificationError, r as PaymentNotOwnedError, t as PaymentConfigurationError } from "../chunks/errors-zSmk_AYY.js";
+import { _ as normalizeUrlString, a as formEncode, b as rememberPaymentOption, f as normalizeMaxStoredPaymentOptions, g as normalizePositivePaymentAmount, h as normalizePositiveMinorUnitAmount, m as normalizeNonEmptyString, o as getFetch, p as normalizeMinorUnitAmount, t as applyExpiryToPendingStatus, u as normalizeDate, v as pollPaymentStatus, y as readJsonResponse } from "../chunks/shared-oBgOhLsa.js";
 import { createHmac, timingSafeEqual } from "node:crypto";
 //#region src/adapters/stripe.ts
 var STRIPE_BACKEND_ID = "stripe";
@@ -18,6 +18,7 @@ var StripeAdapter = class {
 	supportedCurrencies;
 	checkoutMode;
 	webhookSecret;
+	connectWebhookSecret;
 	stripeAccount;
 	maxStoredPaymentOptions;
 	maxStoredWebhookEventIds;
@@ -26,10 +27,8 @@ var StripeAdapter = class {
 	constructor(options) {
 		this.options = options;
 		if (typeof options.secretKey !== "string" || !options.secretKey.trim()) throw new PaymentConfigurationError("StripeAdapter requires secretKey.");
-		if (options.webhookSecret !== void 0) {
-			if (typeof options.webhookSecret !== "string") throw new PaymentConfigurationError("StripeAdapter webhookSecret must be a string when configured.");
-			if (!options.webhookSecret.trim()) throw new PaymentConfigurationError("StripeAdapter webhookSecret must not be empty when configured.");
-		}
+		assertOptionalSecret(options.webhookSecret, "webhookSecret");
+		assertOptionalSecret(options.connectWebhookSecret, "connectWebhookSecret");
 		if (options.apiBaseUrl !== void 0) {
 			if (typeof options.apiBaseUrl !== "string") throw new PaymentConfigurationError("StripeAdapter apiBaseUrl must be a string when configured.");
 			if (!options.apiBaseUrl.trim()) throw new PaymentConfigurationError("StripeAdapter apiBaseUrl must not be empty when configured.");
@@ -45,6 +44,7 @@ var StripeAdapter = class {
 		this.checkoutMode = options.checkoutMode ?? "payment";
 		if (this.checkoutMode !== "payment") throw new PaymentConfigurationError("StripeAdapter only supports payment Checkout mode.");
 		this.webhookSecret = options.webhookSecret?.trim();
+		this.connectWebhookSecret = options.connectWebhookSecret?.trim();
 		this.stripeAccount = normalizeOptionalStripeAccount(options.stripeAccount, "StripeAdapter stripeAccount");
 		this.capabilities = {
 			id: STRIPE_BACKEND_ID,
@@ -382,33 +382,165 @@ var StripeAdapter = class {
 			raw: session
 		};
 	}
+	/**
+	* Verify and parse a delivery to the platform webhook endpoint. Events that
+	* carry a connected `account` are rejected: they belong to the Connect
+	* endpoint and must never be processed as platform-account events.
+	*/
 	parseWebhookEvent(payload, signature) {
-		if (!this.webhookSecret) throw new PaymentConfigurationError("StripeAdapter parseWebhookEvent requires webhookSecret.");
+		const event = this.verifyWebhookEvent(payload, signature, "platform");
+		this.recordWebhookEvent(event);
+		return event;
+	}
+	/**
+	* Verify a Stripe Connect endpoint delivery with `connectWebhookSecret`,
+	* then parse it. The signature is checked before the payload is parsed, and
+	* an event without a connected `account` is rejected. When this adapter is
+	* scoped to a `stripeAccount`, events for any other account are rejected.
+	* The payload, including `quoteId`, is controlled by the connected account:
+	* bind `quoteId` to `account` before acting on it.
+	*/
+	parseConnectWebhookEvent(payload, signature) {
+		const event = this.verifyWebhookEvent(payload, signature, "connect");
+		this.recordWebhookEvent(event);
+		return event;
+	}
+	/**
+	* Verify a webhook delivery, then map its connected account to an owner
+	* (for example a tenant) with the host's resolver. An account the resolver
+	* does not recognize is rejected with {@link PaymentNotOwnedError}; there is
+	* no fallback to the platform account. The event is recorded for duplicate
+	* detection only after it resolves, so a retried delivery that failed to
+	* resolve is not reported as a duplicate.
+	*
+	* Security: a connected account controls the objects it creates, so a
+	* Connect event's `quoteId` (and every other payload field) is chosen by
+	* that account. Resolving the account proves only who sent the event. The
+	* host must check that `event.quoteId` belongs to the resolved owner (for
+	* example inside `resolveAccount`, which receives the event, or before
+	* settling) and must never settle another owner's quote from it.
+	*/
+	async resolveConnectWebhookEvent(payload, signature, options) {
+		if (typeof options?.resolveAccount !== "function") throw new PaymentConfigurationError("Stripe resolveConnectWebhookEvent requires a resolveAccount function.");
+		const endpoint = options.endpoint ?? "connect";
+		if (endpoint !== "connect" && endpoint !== "platform") throw new PaymentConfigurationError("Stripe resolveConnectWebhookEvent endpoint must be connect or platform.");
+		const event = this.verifyWebhookEvent(payload, signature, endpoint);
+		const account = endpoint === "connect" ? event.account : event.connect?.type === "application_fee.created" || event.connect?.type === "application_fee.refunded" ? event.connect.applicationFee.account : void 0;
+		if (account === void 0) throw new PaymentNotOwnedError(`Stripe webhook event ${event.id} (${event.type}) has no connected account to route by.`);
+		this.assertAdapterAccount(account);
+		const owner = await options.resolveAccount(account, event);
+		if (owner === void 0 || owner === null) throw new PaymentNotOwnedError(`Stripe connected account ${account} is not mapped to an owner.`);
+		this.recordWebhookEvent(event);
+		return {
+			event,
+			account,
+			owner
+		};
+	}
+	/**
+	* Create a Stripe Connect **Standard** account. The account holder owns the
+	* Stripe relationship and dashboard; the platform only connects to it.
+	* Always issued on the platform account, never on a connected account.
+	*/
+	async createStandardAccount(input = {}) {
+		const country = input.country === void 0 ? void 0 : normalizeStripeCountry(input.country);
+		const email = input.email === void 0 ? void 0 : normalizeNonEmptyString(input.email, "Stripe account email");
+		return mapStripeConnectAccount(await this.stripeRequest("/accounts", {
+			method: "POST",
+			idempotencyKey: input.idempotencyKey,
+			body: formEncode({
+				type: "standard",
+				country,
+				email,
+				...Object.fromEntries([["business_type", input.businessType]]),
+				...flattenStripeMetadata(input.metadata)
+			})
+		}), "Stripe account response");
+	}
+	/**
+	* Create a single-use Account Link that sends the account holder through
+	* Stripe-hosted onboarding. `refreshUrl` is visited when the link expires or
+	* is reused, and should mint a new link; `returnUrl` does not mean
+	* onboarding finished, so read {@link getAccountCapabilities} afterwards.
+	*/
+	async createOnboardingLink(accountId, returnUrl, refreshUrl, options = {}) {
+		const account = normalizeStripeConnectedAccountId(accountId);
+		const link = await this.stripeRequest("/account_links", {
+			method: "POST",
+			idempotencyKey: options.idempotencyKey,
+			body: formEncode({
+				account,
+				type: "account_onboarding",
+				collect: options.collect,
+				...Object.fromEntries([["return_url", normalizeUrlString(returnUrl, "Stripe returnUrl")], ["refresh_url", normalizeUrlString(refreshUrl, "Stripe refreshUrl")]])
+			})
+		});
+		const url = normalizeOptionalProviderString(readProviderString(link, "url"));
+		if (!url) throw new PaymentProviderError("Stripe Account Link response did not include a url.");
+		const expiresAtSeconds = readSafeInteger(link, "expires_at");
+		return {
+			url,
+			expiresAt: expiresAtSeconds === void 0 ? void 0 : /* @__PURE__ */ new Date(expiresAtSeconds * 1e3),
+			raw: link
+		};
+	}
+	/**
+	* Read a connected account's onboarding and capability state
+	* (`charges_enabled`, `details_submitted`, `payouts_enabled`, per-capability
+	* status, and outstanding requirements).
+	*/
+	async getAccountCapabilities(accountId) {
+		const account = normalizeStripeConnectedAccountId(accountId);
+		const status = mapStripeConnectAccount(await this.stripeRequest(`/accounts/${encodeURIComponent(account)}`), "Stripe account response");
+		if (status.accountId !== account) throw new PaymentVerificationError(`Stripe account response ${status.accountId} did not match ${account}.`);
+		return status;
+	}
+	verifyWebhookEvent(payload, signature, endpoint) {
+		const secret = endpoint === "connect" ? this.connectWebhookSecret : this.webhookSecret;
+		if (!secret) throw new PaymentConfigurationError(endpoint === "connect" ? "StripeAdapter parseConnectWebhookEvent requires connectWebhookSecret." : "StripeAdapter parseWebhookEvent requires webhookSecret.");
 		if (!signature) throw new PaymentProviderError("Missing Stripe webhook signature.");
-		verifyStripeWebhookSignature(payload, signature, this.webhookSecret);
+		verifyStripeWebhookSignature(payload, signature, secret);
 		const event = parseStripeWebhookPayload(payload);
 		const id = readRequiredWebhookString(event, "id", "Stripe webhook event id");
 		const type = readRequiredWebhookString(event, "type", "Stripe webhook event type");
-		const duplicate = this.seenWebhookEventIds.has(id);
-		if (!duplicate) {
-			this.seenWebhookEventIds.add(id);
-			while (this.seenWebhookEventIds.size > this.maxStoredWebhookEventIds) {
-				const oldest = this.seenWebhookEventIds.values().next().value;
-				if (oldest === void 0) break;
-				this.seenWebhookEventIds.delete(oldest);
-			}
-		}
+		const rawAccount = event.account;
+		let account;
+		if (endpoint === "connect") {
+			account = typeof rawAccount === "string" ? rawAccount.trim() : void 0;
+			if (!account || !STRIPE_CONNECTED_ACCOUNT_ID.test(account)) throw new PaymentVerificationError("Stripe Connect webhook event did not include a valid connected account.");
+			this.assertAdapterAccount(account);
+		} else if (rawAccount !== void 0 && rawAccount !== null) throw new PaymentVerificationError("Stripe connected-account event received on the platform webhook endpoint; verify it with parseConnectWebhookEvent.");
 		const data = event.data?.object;
+		const connect = mapStripeConnectEventDetail(type, data);
+		if (account !== void 0 && connect?.type === "account.updated" && connect.account.accountId !== account) throw new PaymentVerificationError("Stripe account.updated webhook object did not match the event account.");
 		return {
 			id,
 			type,
 			status: mapStripeWebhookStatus(type, data),
 			quoteId: normalizeOptionalWebhookString((type.startsWith("checkout.session.") ? readString(data, "client_reference_id") : void 0) ?? readString(data?.metadata ?? {}, "quoteId")),
 			providerPaymentId: normalizeOptionalWebhookString(readString(data, "id")),
-			duplicate,
+			duplicate: this.seenWebhookEventIds.has(id),
+			...account === void 0 ? {} : { account },
+			...connect === void 0 ? {} : { connect },
 			raw: event
 		};
 	}
+	recordWebhookEvent(event) {
+		if (this.seenWebhookEventIds.has(event.id)) {
+			event.duplicate = true;
+			return;
+		}
+		event.duplicate = false;
+		this.seenWebhookEventIds.add(event.id);
+		while (this.seenWebhookEventIds.size > this.maxStoredWebhookEventIds) {
+			const oldest = this.seenWebhookEventIds.values().next().value;
+			if (oldest === void 0) break;
+			this.seenWebhookEventIds.delete(oldest);
+		}
+	}
+	assertAdapterAccount(account) {
+		if (this.stripeAccount !== void 0 && account !== this.stripeAccount) throw new PaymentNotOwnedError(`Stripe connected account ${account} does not match this adapter's account scope.`);
+	}
 	async stripeRequest(path, init = {}) {
 		const headers = new Headers(init.headers);
 		headers.set("Authorization", `Bearer ${this.secretKey}`);
@@ -442,6 +574,80 @@ var StripeAdapter = class {
 		for (const option of this.optionsByQuote.values()) if (option.providerPaymentId === sessionId) return option;
 	}
 };
+function assertOptionalSecret(value, name) {
+	if (value === void 0) return;
+	if (typeof value !== "string") throw new PaymentConfigurationError(`StripeAdapter ${name} must be a string when configured.`);
+	if (!value.trim()) throw new PaymentConfigurationError(`StripeAdapter ${name} must not be empty when configured.`);
+}
+var STRIPE_CONNECTED_ACCOUNT_ID = /^acct_[A-Za-z0-9]+$/;
+function normalizeStripeConnectedAccountId(value) {
+	const account = typeof value === "string" ? value.trim() : void 0;
+	if (!account || !STRIPE_CONNECTED_ACCOUNT_ID.test(account)) throw new PaymentConfigurationError("Stripe connected account id must look like acct_...");
+	return account;
+}
+function normalizeStripeCountry(value) {
+	const country = typeof value === "string" ? value.trim().toUpperCase() : "";
+	if (!/^[A-Z]{2}$/.test(country)) throw new PaymentConfigurationError("Stripe account country must be a two-letter ISO country code.");
+	return country;
+}
+function readStringArray(value, key) {
+	const item = value?.[key];
+	return Array.isArray(item) ? item.filter((entry) => typeof entry === "string") : [];
+}
+function mapStripeConnectAccount(account, context) {
+	const accountId = readProviderString(account, "id")?.trim();
+	if (!account || !accountId || !STRIPE_CONNECTED_ACCOUNT_ID.test(accountId)) throw new PaymentProviderError(`${context} did not include an account id.`);
+	const capabilities = {};
+	for (const [name, state] of Object.entries(readObject(account, "capabilities") ?? {})) if (typeof state === "string") capabilities[name] = state;
+	const requirements = readObject(account, "requirements");
+	const disabledReason = normalizeOptionalProviderString(readProviderString(requirements, "disabled_reason"));
+	const defaultCurrency = readProviderString(account, "default_currency");
+	return {
+		accountId,
+		type: normalizeOptionalProviderString(readProviderString(account, "type")),
+		chargesEnabled: account.charges_enabled === true,
+		detailsSubmitted: account.details_submitted === true,
+		payoutsEnabled: account.payouts_enabled === true,
+		capabilities,
+		requirements: {
+			currentlyDue: readStringArray(requirements, "currently_due"),
+			eventuallyDue: readStringArray(requirements, "eventually_due"),
+			pastDue: readStringArray(requirements, "past_due"),
+			...disabledReason === void 0 ? {} : { disabledReason }
+		},
+		country: normalizeOptionalProviderString(readProviderString(account, "country")),
+		defaultCurrency: defaultCurrency?.toUpperCase(),
+		raw: account
+	};
+}
+function mapStripeApplicationFee(fee) {
+	const id = normalizeOptionalProviderString(readProviderString(fee, "id"));
+	if (!fee || !id) throw new PaymentProviderError("Stripe application_fee webhook object did not include an id.");
+	const account = normalizeOptionalProviderString(readProviderString(fee, "account"));
+	if (account !== void 0 && !STRIPE_CONNECTED_ACCOUNT_ID.test(account)) throw new PaymentProviderError("Stripe application_fee webhook object has an invalid account id.");
+	const livemode = fee.livemode;
+	return {
+		id,
+		account,
+		amount: readSafeInteger(fee, "amount"),
+		amountRefunded: readSafeInteger(fee, "amount_refunded"),
+		currency: readStripeResultCurrency(fee),
+		refunded: fee.refunded === true,
+		charge: normalizeOptionalProviderString(readProviderString(fee, "charge") ?? readProviderString(readObject(fee, "charge"), "id")),
+		livemode: typeof livemode === "boolean" ? livemode : void 0,
+		raw: fee
+	};
+}
+function mapStripeConnectEventDetail(type, object) {
+	if (type === "account.updated") return {
+		type,
+		account: mapStripeConnectAccount(object, "Stripe account.updated webhook object")
+	};
+	if (type === "application_fee.created" || type === "application_fee.refunded") return {
+		type,
+		applicationFee: mapStripeApplicationFee(object)
+	};
+}
 function readStripeOptionAccount(option) {
 	const value = option?.metadata?.stripeAccount;
 	return typeof value === "string" ? value : void 0;