Skip to content

A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.

TypeScript fluxerfluxerapp
29.8 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-or-later

import {createUserID, type UserID} from '@app/api/BrandedTypes';
import type {BillingSubscriptionRow} from '@app/api/database/types/BillingTypes';
import type {UserRow} from '@app/api/database/types/UserTypes';
import type {DonationRepository} from '@app/api/donation/DonationRepository';
import type {IGatewayService} from '@app/api/infrastructure/IGatewayService';
import {Logger} from '@app/api/Logger';
import {getBillingRepository, getWorkerService} from '@app/api/middleware/ServiceRegistry';
import {getPaymentDisputeRepository} from '@app/api/middleware/ServiceSingletons';
import type {Payment} from '@app/api/models/Payment';
import type {User} from '@app/api/models/User';
import {
	isOperatorPassCheckoutSession,
	type OperatorPassFulfilmentService,
} from '@app/api/operator_pass/OperatorPassFulfilmentService';
import {flagPurchaseDuringDispute} from '@app/api/payment_disputes/PaymentDisputeReviews';
import {distributionPaymentFields, distributionSaleFromMetadata} from '@app/api/stripe/DistributionPricing';
import {distributionRefundMetadata} from '@app/api/stripe/DistributionStripeMetadata';
import type {ProductInfo, ProductRegistry} from '@app/api/stripe/ProductRegistry';
import {mirrorBestEffort} from '@app/api/stripe/StripeMirror';
import {
	getFirstInvoicePaymentIntentId,
	getSubscriptionCurrentPeriodStart,
	getSubscriptionPremiumPeriodEnd,
} from '@app/api/stripe/StripeSubscriptionPeriod';
import {extractId, isMissingOrCancelledSubscriptionError} from '@app/api/stripe/StripeUtils';
import {enqueueBillingEmail} from '@app/api/stripe/services/BillingEmailService';
import {EU_WITHDRAWAL_WAIVER_TEXT_VERSION} from '@app/api/stripe/services/StripeCheckoutService';
import {StripeDonationCheckoutFulfilment} from '@app/api/stripe/services/StripeDonationCheckoutFulfilment';
import type {StripeGiftService} from '@app/api/stripe/services/StripeGiftService';
import type {StripePremiumService} from '@app/api/stripe/services/StripePremiumService';
import type {UserRepository} from '@app/api/user/repositories/UserRepository';
import {dispatchUserUpdate} from '@app/api/user/UserMappers';
import {UserPremiumTypes} from '@fluxer/constants/src/UserConstants';
import {DAYS_PER_MONTH, MS_PER_DAY} from '@fluxer/date_utils/src/DateConstants';
import {StripeError} from '@fluxer/errors/src/domains/payment/StripeError';
import type {ICacheService} from '@pkgs/cache/src/ICacheService';
import type {IEmailService} from '@pkgs/email/src/IEmailService';
import {seconds} from 'itty-time';
import type Stripe from 'stripe';

type CheckoutPremiumApplyResult = 'granted' | 'refunded_duplicate_subscription';
type CheckoutSideEffectResult = 'continue' | 'stop';

interface CheckoutPremiumGrantRecovery {
	expectedPremiumUntil?: Date | null;
}

interface CheckoutFulfilmentContext {
	session: Stripe.Checkout.Session;
	payment: Payment;
	user: User;
	productInfo: ProductInfo;
	subscriptionId: string | null;
	customerId: string | null;
	isRecurring: boolean;
	amountTotal: number;
	currency: string;
}

interface CheckoutPremiumGrantContext extends CheckoutFulfilmentContext {
	recovery: CheckoutPremiumGrantRecovery;
}

export class StripeCheckoutWebhookHandler {
	private static readonly CHECKOUT_EFFECTS_APPLIED_TTL_SECONDS = seconds('365 days');
	private donationFulfilment: StripeDonationCheckoutFulfilment;

	constructor(
		private stripe: Stripe | null,
		private userRepository: UserRepository,
		emailService: IEmailService,
		private gatewayService: IGatewayService,
		private productRegistry: ProductRegistry,
		private cacheService: ICacheService,
		private giftService: StripeGiftService,
		private premiumService: StripePremiumService,
		donationRepository: DonationRepository,
		private operatorPassFulfilment: OperatorPassFulfilmentService | null = null,
	) {
		this.donationFulfilment = new StripeDonationCheckoutFulfilment(
			stripe,
			donationRepository,
			emailService,
			cacheService,
		);
	}

	async handleCheckoutSessionCompleted(session: Stripe.Checkout.Session): Promise<void> {
		if (this.operatorPassFulfilment && isOperatorPassCheckoutSession(session)) {
			await this.operatorPassFulfilment.handleCheckoutSessionCompleted(session);
			if (session.payment_status !== 'unpaid') {
				await this.flagOpenDisputes(session);
			}
			return;
		}
		if (session.metadata?.is_donation === 'true') {
			await this.handleDonationCheckoutCompleted(session);
			return;
		}
		if (session.payment_status === 'unpaid') {
			const payment = await this.userRepository.getPaymentByCheckoutSession(session.id);
			if (payment && payment.status === 'pending') {
				await this.userRepository.updatePayment({
					...payment.toRow(),
					status: 'awaiting_settlement',
				});
			}
			Logger.info(
				{sessionId: session.id, paymentStatus: session.payment_status},
				'Checkout session completed with unpaid status; deferring fulfilment until settlement',
			);
			return;
		}
		await this.fulfilCheckoutSession(session);
	}

	async handleAsyncPaymentSucceeded(session: Stripe.Checkout.Session, paidAt: Date): Promise<void> {
		if (this.operatorPassFulfilment && isOperatorPassCheckoutSession(session)) {
			await this.operatorPassFulfilment.handleAsyncPaymentSucceeded(session, paidAt);
			await this.flagOpenDisputes(session);
			return;
		}
		if (session.metadata?.is_donation === 'true') {
			Logger.info({sessionId: session.id}, 'Processing async payment succeeded for donation checkout session');
			await this.handleDonationCheckoutCompleted(session);
			return;
		}
		Logger.info({sessionId: session.id}, 'Processing async payment succeeded for checkout session');
		await this.fulfilCheckoutSession(session);
	}

	async handleCheckoutSessionExpired(session: Stripe.Checkout.Session): Promise<void> {
		if (this.operatorPassFulfilment && isOperatorPassCheckoutSession(session)) {
			await this.operatorPassFulfilment.handleCheckoutSessionExpired(session);
		}
	}

	async handleAsyncPaymentFailed(session: Stripe.Checkout.Session): Promise<void> {
		if (this.operatorPassFulfilment && isOperatorPassCheckoutSession(session)) {
			await this.operatorPassFulfilment.handleAsyncPaymentFailed(session);
			return;
		}
		if (session.metadata?.is_donation === 'true') {
			Logger.warn(
				{
					sessionId: session.id,
					email: session.metadata?.donation_email,
					paymentStatus: session.payment_status,
				},
				'Async payment failed for donation checkout session; no confirmation sent',
			);
			return;
		}
		const payment = await this.userRepository.getPaymentByCheckoutSession(session.id);
		if (payment && (payment.status === 'pending' || payment.status === 'awaiting_settlement')) {
			await this.userRepository.updatePayment({
				...payment.toRow(),
				status: 'failed',
			});
		}
		Logger.warn(
			{sessionId: session.id, paymentStatus: session.payment_status},
			'Async payment failed for checkout session',
		);
	}

	private async flagOpenDisputes(session: Stripe.Checkout.Session, userId?: UserID): Promise<void> {
		const reference = session.client_reference_id;
		const purchaserId = userId ?? (reference && /^\d+$/.test(reference) ? createUserID(BigInt(reference)) : null);
		if (purchaserId === null) {
			return;
		}
		try {
			await flagPurchaseDuringDispute(getPaymentDisputeRepository(), purchaserId, `stripe_checkout:${session.id}`);
		} catch (error) {
			Logger.error({error, sessionId: session.id}, 'Could not flag open payment dispute reviews for a checkout');
		}
	}

	private async fulfilCheckoutSession(session: Stripe.Checkout.Session): Promise<void> {
		let payment = await this.userRepository.getPaymentByCheckoutSession(session.id);
		if (!payment) {
			payment = await this.tryRecoverPaymentFromSessionMetadata(session);
		}
		if (!payment) {
			Logger.error(
				{
					sessionId: session.id,
					paymentLinkId: extractId(session.payment_link),
					mode: session.mode,
					submitType: session.submit_type,
					paymentStatus: session.payment_status,
					clientReferenceId: session.client_reference_id,
				},
				'No payment record found for checkout session and recovery failed, skipping event',
			);
			return;
		}
		if (payment.status === 'completed') {
			Logger.debug({sessionId: session.id, status: payment.status}, 'Payment already processed');
			return;
		}
		if (payment.status !== 'pending' && payment.status !== 'awaiting_settlement') {
			Logger.debug({sessionId: session.id, status: payment.status}, 'Payment already processed');
			return;
		}
		const productInfo = payment.priceId === null ? null : this.productRegistry.getProduct(payment.priceId);
		if (!productInfo) {
			Logger.error({sessionId: session.id, priceId: payment.priceId}, 'Unknown price ID');
			throw new StripeError('Unknown price ID for checkout session');
		}
		const user = await this.userRepository.findUnique(payment.userId);
		if (!user) {
			Logger.error({userId: payment.userId, sessionId: session.id}, 'User not found');
			throw new StripeError('User not found for checkout session');
		}
		await this.flagOpenDisputes(session, user.id);
		if (session.amount_total == null || !session.currency) {
			Logger.error(
				{sessionId: session.id, amountTotal: session.amount_total, currency: session.currency},
				'Checkout session missing amount or currency',
			);
			throw new StripeError('Checkout session missing amount or currency');
		}
		const customerId = extractId(session.customer);
		const subscriptionId = extractId(session.subscription);
		const isRecurring = this.productRegistry.isRecurringSubscription(productInfo);
		let giftCode: string | null = payment.giftCode;
		if (payment.isGift && !giftCode) {
			const paymentIntentId = extractId(session.payment_intent);
			giftCode = await this.giftService.prepareGiftCode(session.id, user, productInfo, paymentIntentId);
		}
		const sideEffectResult = await this.applyCheckoutSideEffects({
			session,
			payment,
			user,
			productInfo,
			subscriptionId,
			customerId,
			isRecurring,
			amountTotal: session.amount_total,
			currency: session.currency,
		});
		if (sideEffectResult === 'stop') {
			return;
		}
		const metadataWaiverAccepted = session.metadata?.eu_withdrawal_waiver_accepted === 'true';
		const stripeTermsAccepted = session.consent?.terms_of_service === 'accepted';
		const metadataWaiverAcceptedAt = session.metadata?.eu_withdrawal_waiver_accepted_at
			? new Date(session.metadata.eu_withdrawal_waiver_accepted_at)
			: null;
		const resolvedWaiverAccepted = payment.euWithdrawalWaiverAccepted || metadataWaiverAccepted || stripeTermsAccepted;
		const resolvedWaiverAcceptedAt =
			payment.euWithdrawalWaiverAcceptedAt ??
			(Number.isNaN(metadataWaiverAcceptedAt?.getTime() ?? Number.NaN) ? null : metadataWaiverAcceptedAt) ??
			(stripeTermsAccepted ? new Date() : null);
		if (payment.isGift) {
			await enqueueBillingEmail(getWorkerService(), {kind: 'gift_paid', id: session.id});
		}
		await this.userRepository.updatePayment({
			...payment.toRow(),
			stripe_customer_id: customerId,
			payment_intent_id: extractId(session.payment_intent) ?? (await this.firstInvoicePaymentIntentId(session)),
			subscription_id: subscriptionId,
			invoice_id: typeof session.invoice === 'string' ? session.invoice : null,
			amount_cents: session.amount_total,
			currency: session.currency,
			status: 'completed',
			completed_at: payment.completedAt ?? new Date(),
			gift_code: giftCode,
			eu_withdrawal_waiver_accepted: resolvedWaiverAccepted,
			eu_withdrawal_waiver_accepted_at: resolvedWaiverAcceptedAt,
			eu_withdrawal_waiver_text_version:
				payment.euWithdrawalWaiverTextVersion ??
				session.metadata?.eu_withdrawal_waiver_text_version ??
				EU_WITHDRAWAL_WAIVER_TEXT_VERSION,
			tax_amount_minor: session.total_details?.amount_tax ?? null,
			tax_country: session.customer_details?.address?.country ?? null,
		});
		Logger.debug(
			{
				userId: payment.userId,
				sessionId: session.id,
				productType: productInfo.type,
				isGift: payment.isGift,
			},
			'Checkout session completed and processed',
		);
	}

	private async applyCheckoutSideEffects(context: CheckoutFulfilmentContext): Promise<CheckoutSideEffectResult> {
		const checkoutEffectsAppliedKey = this.getCheckoutEffectsAppliedKey(context.session.id);
		if (await this.cacheService.get<boolean>(checkoutEffectsAppliedKey)) {
			Logger.debug({sessionId: context.session.id}, 'Checkout side effects already applied, finishing payment commit');
			return 'continue';
		}
		if (!context.payment.isGift && context.isRecurring && (await this.hasSubscriptionEnded(context.subscriptionId))) {
			Logger.warn(
				{sessionId: context.session.id, subscriptionId: context.subscriptionId, userId: context.payment.userId},
				'Checkout subscription ended before fulfilment, so no premium is granted',
			);
			return 'continue';
		}
		await this.syncCheckoutUserFields(context);
		const result = context.payment.isGift
			? await this.applyGiftCheckoutEffects(context)
			: await this.applyPremiumCheckoutEffects(context);
		if (result === 'stop') {
			return 'stop';
		}
		await this.cacheService.set(
			checkoutEffectsAppliedKey,
			true,
			StripeCheckoutWebhookHandler.CHECKOUT_EFFECTS_APPLIED_TTL_SECONDS,
		);
		return 'continue';
	}

	private async hasSubscriptionEnded(subscriptionId: string | null): Promise<boolean> {
		if (!subscriptionId || !this.stripe) return false;
		try {
			const subscription = await this.stripe.subscriptions.retrieve(subscriptionId);
			return subscription.status === 'canceled' || subscription.status === 'incomplete_expired';
		} catch (error) {
			Logger.warn({error, subscriptionId}, 'Failed to read the checkout subscription status before fulfilment');
			return false;
		}
	}

	private async syncCheckoutUserFields(context: CheckoutFulfilmentContext): Promise<void> {
		const {payment, user, customerId, subscriptionId, isRecurring, productInfo} = context;
		const userUpdates: Partial<UserRow> = {};
		if (customerId && !user.stripeCustomerId) {
			userUpdates.stripe_customer_id = customerId;
		}
		if (subscriptionId && isRecurring) {
			userUpdates.stripe_subscription_id = subscriptionId;
			userUpdates.premium_billing_cycle = productInfo.billingCycle || null;
		}
		if (payment.isGift) {
			userUpdates.has_ever_purchased = true;
		}
		if (Object.keys(userUpdates).length > 0) {
			await this.userRepository.patchUpsert(payment.userId, userUpdates, user.toRow());
		}
	}

	private async applyGiftCheckoutEffects(context: CheckoutFulfilmentContext): Promise<CheckoutSideEffectResult> {
		const {session, payment, user} = context;
		const giftFinalisedKey = this.getCheckoutGiftFinalisedKey(session.id);
		if (await this.cacheService.get<boolean>(giftFinalisedKey)) {
			return 'continue';
		}
		try {
			await this.giftService.finaliseGiftCode(payment.userId);
			await this.cacheService.set(
				giftFinalisedKey,
				true,
				StripeCheckoutWebhookHandler.CHECKOUT_EFFECTS_APPLIED_TTL_SECONDS,
			);
		} catch (error) {
			const latestUser = await this.userRepository.findUnique(payment.userId);
			if (this.didGiftFinalisationApply(user, latestUser)) {
				await this.cacheService.set(
					giftFinalisedKey,
					true,
					StripeCheckoutWebhookHandler.CHECKOUT_EFFECTS_APPLIED_TTL_SECONDS,
				);
				Logger.warn(
					{sessionId: session.id, userId: payment.userId},
					'Gift finalisation threw after state update; marking as applied for idempotency',
				);
			}
			throw error;
		}
		return 'continue';
	}

	private async applyPremiumCheckoutEffects(context: CheckoutFulfilmentContext): Promise<CheckoutSideEffectResult> {
		const premiumAppliedKey = this.getCheckoutPremiumAppliedKey(context.session.id);
		if (await this.cacheService.get<boolean>(premiumAppliedKey)) {
			return 'continue';
		}
		const recovery: CheckoutPremiumGrantRecovery = {};
		try {
			const result = await this.applyCheckoutPremiumGrant({...context, recovery});
			await this.cacheService.set(
				premiumAppliedKey,
				true,
				StripeCheckoutWebhookHandler.CHECKOUT_EFFECTS_APPLIED_TTL_SECONDS,
			);
			return result === 'refunded_duplicate_subscription' ? 'stop' : 'continue';
		} catch (error) {
			const latestUser = await this.userRepository.findUnique(context.payment.userId);
			if (this.didCheckoutPremiumGrantApply(context.user, latestUser, context.productInfo, recovery)) {
				await this.cacheService.set(
					premiumAppliedKey,
					true,
					StripeCheckoutWebhookHandler.CHECKOUT_EFFECTS_APPLIED_TTL_SECONDS,
				);
				Logger.warn(
					{sessionId: context.session.id, userId: context.payment.userId},
					'Premium grant threw after state update; marking as applied for idempotency',
				);
			}
			throw error;
		}
	}

	private async applyCheckoutPremiumGrant(context: CheckoutPremiumGrantContext): Promise<CheckoutPremiumApplyResult> {
		const {session, payment, productInfo, subscriptionId, recovery} = context;
		if (this.productRegistry.isRecurringSubscription(productInfo) && subscriptionId) {
			const duplicate = await this.detectDuplicateRecurringSubscription(payment.userId, subscriptionId, productInfo);
			if (duplicate) {
				await this.refundDuplicateRecurringSubscriptionCheckout(context, duplicate.existingSubscriptionId);
				return 'refunded_duplicate_subscription';
			}
		}
		if (this.productRegistry.isRecurringSubscription(productInfo)) {
			const period = await this.resolveCheckoutSubscriptionPeriod(session, productInfo);
			recovery.expectedPremiumUntil = period.end;
			await this.premiumService.setPremiumFromSubscriptionPeriod(
				payment.userId,
				period.end,
				productInfo.billingCycle || null,
				true,
				null,
				period.start,
			);
			return 'granted';
		}
		await this.premiumService.extendPremiumByGift(
			payment.userId,
			UserPremiumTypes.SUBSCRIPTION,
			'months',
			productInfo.durationMonths,
			true,
		);
		return 'granted';
	}

	private async detectDuplicateRecurringSubscription(
		userId: UserID,
		newSubscriptionId: string,
		productInfo: ProductInfo,
	): Promise<{existingSubscriptionId: string} | null> {
		const billingRepo = getBillingRepository();
		const customers = await billingRepo.customers.findByUserId(userId).catch((error) => {
			Logger.warn(
				{error, userId, newSubscriptionId},
				'Failed to load billing customers for duplicate checkout detection',
			);
			return [];
		});
		for (const customer of customers) {
			const subs = await billingRepo.subscriptions.listByCustomer(customer.provider_id).catch((error) => {
				Logger.warn(
					{error, userId, customerId: customer.provider_id, newSubscriptionId},
					'Failed to load billing subscriptions for duplicate checkout detection',
				);
				return [];
			});
			const duplicate = subs.find((sub) =>
				this.isDuplicateRecurringSubscriptionCandidate(sub, newSubscriptionId, productInfo),
			);
			if (duplicate) {
				return {existingSubscriptionId: duplicate.provider_id};
			}
		}
		return null;
	}

	private isDuplicateRecurringSubscriptionCandidate(
		subscription: BillingSubscriptionRow,
		newSubscriptionId: string,
		productInfo: ProductInfo,
	): boolean {
		if (subscription.provider_id === newSubscriptionId) {
			return false;
		}
		if (!this.isActiveDuplicateSubscriptionStatus(subscription.status)) {
			return false;
		}
		return this.isSameProductRecurring(subscription.primary_price_id, productInfo);
	}

	private isActiveDuplicateSubscriptionStatus(status: BillingSubscriptionRow['status']): boolean {
		return status === 'active' || status === 'trialing' || status === 'past_due';
	}

	private isSameProductRecurring(existingPriceId: string | null, productInfo: ProductInfo): boolean {
		if (!existingPriceId) {
			return false;
		}
		const existingProduct = this.productRegistry.getProduct(existingPriceId);
		if (!existingProduct) {
			return false;
		}
		return existingProduct.type === productInfo.type;
	}

	private async refundDuplicateRecurringSubscriptionCheckout(
		context: CheckoutPremiumGrantContext,
		existingSubscriptionId: string,
	): Promise<void> {
		const {session, payment, productInfo, subscriptionId, customerId, amountTotal, currency} = context;
		if (!subscriptionId) {
			throw new StripeError('Duplicate subscription checkout missing subscription id');
		}
		Logger.warn(
			{
				sessionId: session.id,
				userId: payment.userId,
				newSubscriptionId: subscriptionId,
				existingSubscriptionId,
				productType: productInfo.type,
			},
			'Refusing duplicate recurring subscription checkout; cancelling new Stripe subscription and refunding',
		);
		await this.cancelStripeSubscriptionById(subscriptionId, session.id, payment.userId.toString());
		const chargeId = await this.tryGetLatestChargeForSubscription(subscriptionId);
		if (chargeId) {
			await this.refundChargeForDuplicateSubscription(chargeId, session.id);
		}
		const latestUser = await this.userRepository.findUnique(payment.userId);
		if (latestUser && latestUser.stripeSubscriptionId === subscriptionId) {
			const restoredUser = await this.userRepository.patchUpsert(
				payment.userId,
				{stripe_subscription_id: existingSubscriptionId},
				latestUser.toRow(),
			);
			await dispatchUserUpdate(this.gatewayService, restoredUser);
		}
		await this.userRepository.updatePayment({
			...payment.toRow(),
			stripe_customer_id: customerId,
			payment_intent_id: extractId(session.payment_intent),
			subscription_id: subscriptionId,
			invoice_id: typeof session.invoice === 'string' ? session.invoice : null,
			amount_cents: amountTotal,
			currency,
			status: 'refunded_duplicate_subscription',
			completed_at: payment.completedAt ?? new Date(),
		});
	}

	private async firstInvoicePaymentIntentId(session: Stripe.Checkout.Session): Promise<string | null> {
		const invoiceId = extractId(session.invoice);
		if (!invoiceId || !this.stripe) {
			return null;
		}
		try {
			return getFirstInvoicePaymentIntentId(await this.stripe.invoices.retrieve(invoiceId, {expand: ['payments']}));
		} catch (err) {
			Logger.warn({err, sessionId: session.id, invoiceId}, 'Failed to read the payment intent of a checkout invoice');
			return null;
		}
	}

	private async tryGetLatestChargeForSubscription(subscriptionId: string): Promise<string | null> {
		if (!this.stripe) {
			return null;
		}
		try {
			const subscription = await this.stripe.subscriptions.retrieve(subscriptionId, {
				expand: ['latest_invoice.payments.data.payment'],
			});
			const latestInvoice =
				typeof subscription.latest_invoice === 'string' ? null : (subscription.latest_invoice ?? null);
			const paymentIntentId = getFirstInvoicePaymentIntentId(latestInvoice);
			if (!paymentIntentId) {
				return null;
			}
			const paymentIntent = await this.stripe.paymentIntents.retrieve(paymentIntentId);
			return extractId(paymentIntent.latest_charge);
		} catch (err) {
			Logger.warn({err, subscriptionId}, 'Failed to resolve latest charge for duplicate-subscription refund');
			return null;
		}
	}

	private async refundChargeForDuplicateSubscription(chargeId: string, checkoutSessionId: string): Promise<void> {
		if (!this.stripe) {
			return;
		}
		const refund = await this.stripe.refunds.create(
			{
				charge: chargeId,
				metadata: {
					checkout_session_id: checkoutSessionId,
					rejection_reason: 'duplicate_active_subscription',
					...(await distributionRefundMetadata(this.stripe, {charge: chargeId})),
				},
			},
			{idempotencyKey: `duplicate-sub-refund:${checkoutSessionId}`},
		);
		await mirrorBestEffort(
			() => getBillingRepository().refunds.upsertFromStripe(refund),
			{refundId: refund.id},
			'Mirror upsert failed for duplicate-sub refund; reconciler will heal',
		);
	}

	private async resolveCheckoutSubscriptionPeriod(
		session: Stripe.Checkout.Session,
		productInfo: ProductInfo,
	): Promise<{start: Date | null; end: Date}> {
		const subscriptionId = extractId(session.subscription);
		if (subscriptionId && this.stripe) {
			try {
				const subscription = await this.stripe.subscriptions.retrieve(subscriptionId);
				const candidate = getSubscriptionPremiumPeriodEnd(subscription);
				if (candidate) {
					return {start: getSubscriptionCurrentPeriodStart(subscription), end: candidate};
				}
			} catch (error) {
				Logger.warn(
					{error, sessionId: session.id, subscriptionId},
					'Failed to retrieve Stripe subscription for checkout period_end; falling back to product duration',
				);
			}
		}
		const fallback = new Date(Date.now() + productInfo.durationMonths * DAYS_PER_MONTH * MS_PER_DAY);
		Logger.warn(
			{sessionId: session.id, subscriptionId, durationMonths: productInfo.durationMonths},
			'Using product duration fallback for subscription period_end on checkout fulfilment',
		);
		return {start: null, end: fallback};
	}

	private didCheckoutPremiumGrantApply(
		initialUser: User,
		latestUser: User | null,
		productInfo: ProductInfo,
		recovery: CheckoutPremiumGrantRecovery,
	): boolean {
		if (!latestUser) {
			return false;
		}
		if (latestUser.premiumType !== UserPremiumTypes.SUBSCRIPTION) {
			return false;
		}
		if (this.productRegistry.isRecurringSubscription(productInfo)) {
			const targetPremiumUntil = recovery.expectedPremiumUntil?.getTime() ?? null;
			const latestPremiumUntil = latestUser.premiumUntil?.getTime() ?? null;
			return targetPremiumUntil !== null && latestPremiumUntil !== null && latestPremiumUntil >= targetPremiumUntil;
		}
		const initialGiftEnd = initialUser.premiumGiftExtensionEndsAt?.getTime() ?? 0;
		const latestGiftEnd = latestUser.premiumGiftExtensionEndsAt?.getTime() ?? 0;
		return productInfo.durationMonths > 0 && latestGiftEnd > initialGiftEnd;
	}

	private didGiftFinalisationApply(initialUser: User, latestUser: User | null): boolean {
		if (!latestUser) {
			return false;
		}
		const initialServerSeq = initialUser.giftInventoryServerSeq ?? 0;
		const latestServerSeq = latestUser.giftInventoryServerSeq ?? 0;
		return latestServerSeq > initialServerSeq;
	}

	private async handleDonationCheckoutCompleted(session: Stripe.Checkout.Session): Promise<void> {
		const email = session.metadata?.donation_email?.trim().toLowerCase();
		if (!email) {
			Logger.error({sessionId: session.id}, 'Donation checkout missing email in metadata');
			throw new StripeError('Donation checkout missing email');
		}
		await this.donationFulfilment.registerDonation(session, {
			email,
			locale: session.metadata?.donation_locale ?? null,
			isBusiness: session.metadata?.is_business === 'true',
		});
	}

	private async cancelStripeSubscriptionById(
		subscriptionId: string,
		checkoutSessionId: string,
		userId: string,
	): Promise<void> {
		if (!this.stripe) {
			throw new StripeError('Stripe client not available for subscription cancellation');
		}
		try {
			const canceledSubscription = await this.stripe.subscriptions.cancel(
				subscriptionId,
				{invoice_now: false, prorate: false},
				{idempotencyKey: `localized-card-country-cancel:${checkoutSessionId}`},
			);
			await mirrorBestEffort(
				() =>
					getBillingRepository().subscriptions.upsertFromStripe(canceledSubscription, {
						snapshotCapturedAt: new Date(),
					}),
				{subId: canceledSubscription.id},
				'Mirror upsert failed after Stripe write; reconciler will heal',
			);
		} catch (error) {
			if (isMissingOrCancelledSubscriptionError(error)) {
				Logger.warn(
					{subscriptionId, checkoutSessionId, userId},
					'Stripe subscription was already unavailable while rejecting localized card payment',
				);
				return;
			}
			Logger.error(
				{error, subscriptionId, checkoutSessionId, userId},
				'Failed to cancel localized card payment subscription',
			);
			throw error;
		}
	}

	private async tryRecoverPaymentFromSessionMetadata(session: Stripe.Checkout.Session): Promise<Payment | null> {
		const userIdStr = session.client_reference_id ?? session.metadata?.user_id;
		const priceId = session.metadata?.price_id;
		const productType = session.metadata?.product_type;
		const isGift = session.metadata?.is_gift === 'true';
		const euWithdrawalWaiverRequired = session.metadata?.eu_withdrawal_waiver_required === 'true';
		const euWithdrawalWaiverAccepted =
			session.metadata?.eu_withdrawal_waiver_accepted === 'true' || session.consent?.terms_of_service === 'accepted';
		const euWithdrawalWaiverAcceptedAt = session.metadata?.eu_withdrawal_waiver_accepted_at
			? new Date(session.metadata.eu_withdrawal_waiver_accepted_at)
			: null;
		if (!userIdStr || !priceId || !productType) {
			return null;
		}
		let userId: UserID;
		try {
			userId = createUserID(BigInt(userIdStr));
		} catch {
			Logger.error({sessionId: session.id, userIdStr}, 'Invalid user ID in checkout session metadata');
			return null;
		}
		try {
			const payment = {
				checkout_session_id: session.id,
				user_id: userId,
				price_id: priceId,
				product_type: productType,
				status: 'pending',
				is_gift: isGift,
				created_at: new Date(),
				purchase_geoip_country_code: session.metadata?.purchase_geoip_country_code ?? null,
				purchase_client_country_code: session.metadata?.purchase_client_country_code ?? null,
				eu_withdrawal_waiver_required: euWithdrawalWaiverRequired,
				eu_withdrawal_waiver_accepted: euWithdrawalWaiverAccepted,
			};
			let waiverAcceptedAt = euWithdrawalWaiverAcceptedAt;
			if (Number.isNaN(waiverAcceptedAt?.getTime() ?? Number.NaN)) {
				waiverAcceptedAt = session.consent?.terms_of_service === 'accepted' ? new Date() : null;
			}
			await this.userRepository.createPayment({
				...payment,
				eu_withdrawal_waiver_accepted_at: waiverAcceptedAt,
				eu_withdrawal_waiver_text_version:
					session.metadata?.eu_withdrawal_waiver_text_version ?? EU_WITHDRAWAL_WAIVER_TEXT_VERSION,
				...distributionPaymentFields(distributionSaleFromMetadata(session.metadata)),
			});
			Logger.warn(
				{sessionId: session.id, userId: userId.toString(), priceId, productType},
				'Recovered missing payment record from checkout session metadata',
			);
			return await this.userRepository.getPaymentByCheckoutSession(session.id);
		} catch (error) {
			Logger.error(
				{sessionId: session.id, userId: userId.toString(), error},
				'Failed to recover payment record from checkout session metadata',
			);
			return null;
		}
	}

	private getCheckoutEffectsAppliedKey(checkoutSessionId: string): string {
		return `stripe:checkout:effects:applied:${checkoutSessionId}`;
	}

	private getCheckoutPremiumAppliedKey(checkoutSessionId: string): string {
		return `stripe:checkout:premium:applied:${checkoutSessionId}`;
	}

	private getCheckoutGiftFinalisedKey(checkoutSessionId: string): string {
		return `stripe:checkout:gift:finalised:${checkoutSessionId}`;
	}
}