Skip to content

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

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

import type {AdminRepository} from '@app/api/admin/AdminRepository';
import {AdminAuditService} from '@app/api/admin/services/AdminAuditService';
import {alertSupport} from '@app/api/billing/BillingSupportAlert';
import type {BillingRepository} from '@app/api/billing/repositories/BillingRepository';
import type {DonationRepository} from '@app/api/donation/DonationRepository';
import type {EnforcementDecisionService} from '@app/api/enforcement/EnforcementDecisionService';
import type {IGatewayService} from '@app/api/infrastructure/IGatewayService';
import type {ISnowflakeService} from '@app/api/infrastructure/ISnowflakeService';
import type {KVAccountDeletionQueueService} from '@app/api/infrastructure/KVAccountDeletionQueueService';
import type {PremiumStateReconciliationQueueService} from '@app/api/infrastructure/PremiumStateReconciliationQueueService';
import type {UserCacheService} from '@app/api/infrastructure/UserCacheService';
import {Logger} from '@app/api/Logger';
import {getWorkerService} from '@app/api/middleware/ServiceRegistry';
import {OAuth2TokenRepository} from '@app/api/oauth/repositories/OAuth2TokenRepository';
import type {OperatorPassFulfilmentService} from '@app/api/operator_pass/OperatorPassFulfilmentService';
import {PaymentDisputeEnforcementService} from '@app/api/payment_disputes/PaymentDisputeEnforcement';
import {PaymentDisputeRepository} from '@app/api/payment_disputes/PaymentDisputeRepository';
import {PaymentDisputeReviewService} from '@app/api/payment_disputes/PaymentDisputeReviews';
import type {StoreEntitlementService} from '@app/api/store_billing/StoreEntitlementService';
import {getAcceptedWebhookSecrets} from '@app/api/stripe/BillingConfigCache';
import {tagChargeDistribution, tagInvoiceDistribution} from '@app/api/stripe/DistributionStripeMetadata';
import type {ProductRegistry} from '@app/api/stripe/ProductRegistry';
import {mirrorBestEffort} from '@app/api/stripe/StripeMirror';
import {extractId} from '@app/api/stripe/StripeUtils';
import {type BillingEmailJob, enqueueBillingEmail, isRecentRefund} from '@app/api/stripe/services/BillingEmailService';
import {isDonationSubscription, subscriptionBillingProduct} from '@app/api/stripe/services/BillingInvoiceDetails';
import {
	CLEARED_CANCEL_METADATA,
	freshCancelSource,
	subscriptionCancelling,
} from '@app/api/stripe/services/BillingSubscriptionDetails';
import {StripeCheckoutWebhookHandler} from '@app/api/stripe/services/StripeCheckoutWebhookHandler';
import {StripeDisputeWebhookHandler} from '@app/api/stripe/services/StripeDisputeWebhookHandler';
import {StripeGiftReversalHandler} from '@app/api/stripe/services/StripeGiftReversalHandler';
import type {StripeGiftService} from '@app/api/stripe/services/StripeGiftService';
import {StripePaymentFraudService} from '@app/api/stripe/services/StripePaymentFraudService';
import type {StripePremiumService} from '@app/api/stripe/services/StripePremiumService';
import type {StripeRefundService} from '@app/api/stripe/services/StripeRefundService';
import {StripeSubscriptionReconciler} from '@app/api/stripe/services/StripeSubscriptionReconciler';
import type {StripeSubscriptionService} from '@app/api/stripe/services/StripeSubscriptionService';
import {StripeSubscriptionWebhookHandler} from '@app/api/stripe/services/StripeSubscriptionWebhookHandler';
import type {UserRepository} from '@app/api/user/repositories/UserRepository';
import {StripeError} from '@fluxer/errors/src/domains/payment/StripeError';
import {StripeWebhookNotAvailableError} from '@fluxer/errors/src/domains/payment/StripeWebhookNotAvailableError';
import {StripeWebhookSignatureInvalidError} from '@fluxer/errors/src/domains/payment/StripeWebhookSignatureInvalidError';
import type {ICacheService} from '@pkgs/cache/src/ICacheService';
import type {IEmailService} from '@pkgs/email/src/IEmailService';
import type Stripe from 'stripe';

interface HandleWebhookParams {
	body: string;
	signature: string;
}

export class StripeWebhookService {
	readonly checkoutHandler: StripeCheckoutWebhookHandler;
	private subscriptionHandler: StripeSubscriptionWebhookHandler;
	private disputeHandler: StripeDisputeWebhookHandler;
	private paymentFraudService: StripePaymentFraudService;

	constructor(
		private stripe: Stripe | null,
		userRepository: UserRepository,
		userCacheService: UserCacheService,
		subscriptionService: StripeSubscriptionService,
		emailService: IEmailService,
		gatewayService: IGatewayService,
		private productRegistry: ProductRegistry,
		cacheService: ICacheService,
		giftService: StripeGiftService,
		premiumService: StripePremiumService,
		private donationRepository: DonationRepository,
		kvDeletionQueue: KVAccountDeletionQueueService,
		premiumStateReconciliationQueueService: PremiumStateReconciliationQueueService,
		adminRepository: AdminRepository,
		snowflakeService: ISnowflakeService,
		private billingRepository: BillingRepository,
		private refundService: StripeRefundService,
		enforcementService: EnforcementDecisionService,
		storeEntitlementService: StoreEntitlementService | null = null,
		private operatorPassFulfilment: OperatorPassFulfilmentService | null = null,
	) {
		const auditService = new AdminAuditService(adminRepository, snowflakeService);
		const oauth2Tokens = new OAuth2TokenRepository();
		const disputeRepository = new PaymentDisputeRepository();
		const disputeEnforcement = new PaymentDisputeEnforcementService({
			repository: disputeRepository,
			userRepository,
			userCacheService,
			emailService,
			cacheService,
			gatewayService,
			auditService,
			kvDeletionQueue,
			oauth2Tokens,
			systemDm: null,
			enforcement: enforcementService,
			operatorPass: operatorPassFulfilment,
		});
		this.checkoutHandler = new StripeCheckoutWebhookHandler(
			stripe,
			userRepository,
			emailService,
			gatewayService,
			productRegistry,
			cacheService,
			giftService,
			premiumService,
			donationRepository,
			operatorPassFulfilment,
		);
		const reconciler = new StripeSubscriptionReconciler(stripe, userRepository, productRegistry);
		const giftReversalHandler = new StripeGiftReversalHandler(
			userRepository,
			gatewayService,
			premiumStateReconciliationQueueService,
			storeEntitlementService,
		);
		this.paymentFraudService = new StripePaymentFraudService({
			stripe,
			userRepository,
			donationRepository,
			cacheService,
			auditService,
			enforcement: enforcementService,
			operatorPassFulfilment,
		});
		this.subscriptionHandler = new StripeSubscriptionWebhookHandler(
			userRepository,
			gatewayService,
			premiumService,
			donationRepository,
			premiumStateReconciliationQueueService,
			reconciler,
			billingRepository,
			storeEntitlementService,
		);
		this.disputeHandler = new StripeDisputeWebhookHandler(
			userRepository,
			userCacheService,
			emailService,
			donationRepository,
			kvDeletionQueue,
			giftReversalHandler,
			this.paymentFraudService,
			enforcementService,
			subscriptionService,
			new PaymentDisputeReviewService(disputeRepository, auditService, emailService),
			disputeEnforcement,
			operatorPassFulfilment,
		);
	}

	private constructVerifiedEvent(
		stripe: Stripe,
		body: string,
		signature: string,
		webhookSecrets: Array<string>,
	): Stripe.Event {
		const SEVEN_DAYS_SECONDS = 7 * 24 * 60 * 60;
		let lastError: unknown = null;
		for (const webhookSecret of webhookSecrets) {
			try {
				return stripe.webhooks.constructEvent(body, signature, webhookSecret, SEVEN_DAYS_SECONDS);
			} catch (error: unknown) {
				lastError = error;
			}
		}
		Logger.error({error: lastError}, 'Invalid webhook signature');
		throw new StripeWebhookSignatureInvalidError();
	}

	async handleWebhook({body, signature}: HandleWebhookParams): Promise<void> {
		const webhookSecrets = getAcceptedWebhookSecrets();
		if (!this.stripe || webhookSecrets.length === 0) {
			throw new StripeWebhookNotAvailableError();
		}
		const event = this.constructVerifiedEvent(this.stripe, body, signature, webhookSecrets);
		Logger.debug({eventType: event.type, eventId: event.id}, 'Processing Stripe webhook');
		const claim = await this.billingRepository.webhookEvents.tryClaim(event.id);
		if (claim === 'already_processed') {
			Logger.debug({eventId: event.id, eventType: event.type}, 'Stripe webhook already processed (durable claim)');
			return;
		}
		if (claim === 'in_flight') {
			Logger.warn({eventId: event.id, eventType: event.type}, 'Stripe webhook in-flight; will retry via worker queue');
			throw new StripeError('Stripe webhook event in-flight, retry');
		}
		try {
			await this.dispatchWebhookEvent(event);
			await this.billingRepository.webhookEvents.markProcessed(event.id);
		} catch (err) {
			await this.billingRepository.webhookEvents.releaseClaim(event.id);
			throw err;
		}
	}

	private async dispatchWebhookEvent(event: Stripe.Event): Promise<void> {
		switch (event.type) {
			case 'checkout.session.completed': {
				const checkoutSession = event.data.object as Stripe.Checkout.Session;
				await this.checkoutHandler.handleCheckoutSessionCompleted(checkoutSession);
				break;
			}
			case 'checkout.session.async_payment_succeeded': {
				const cs = event.data.object as Stripe.Checkout.Session;
				await this.checkoutHandler.handleAsyncPaymentSucceeded(cs, new Date(event.created * 1000));
				break;
			}
			case 'checkout.session.expired': {
				await this.checkoutHandler.handleCheckoutSessionExpired(event.data.object as Stripe.Checkout.Session);
				break;
			}
			case 'checkout.session.async_payment_failed': {
				const cs = event.data.object as Stripe.Checkout.Session;
				await this.checkoutHandler.handleAsyncPaymentFailed(cs);
				break;
			}
			case 'invoice.paid':
			case 'invoice.payment_succeeded': {
				const inv = event.data.object as Stripe.Invoice;
				await this.mirrorInvoice(event, inv);
				await this.subscriptionHandler.handleInvoicePaymentSucceeded(event.id, inv);
				await this.queueBillingEmail(inv.id ? {kind: 'invoice_paid', id: inv.id} : null);
				if (event.type === 'invoice.paid' && this.stripe) await tagInvoiceDistribution(this.stripe, inv);
				break;
			}
			case 'invoice.payment_failed': {
				const inv = event.data.object as Stripe.Invoice;
				await this.mirrorInvoice(event, inv);
				await this.subscriptionHandler.handleInvoicePaymentFailed(inv);
				await this.queueInvoicePaymentProblem(inv, false);
				break;
			}
			case 'invoice.payment_action_required': {
				const inv = event.data.object as Stripe.Invoice;
				await this.mirrorInvoice(event, inv);
				await this.subscriptionHandler.handleInvoicePaymentActionRequired(inv);
				await this.queueInvoicePaymentProblem(inv, true);
				break;
			}
			case 'invoice.finalization_failed': {
				const inv = event.data.object as Stripe.Invoice;
				await this.mirrorInvoice(event, inv);
				await this.subscriptionHandler.handleInvoiceFinalizationFailed(inv);
				break;
			}
			case 'invoice.updated': {
				const inv = event.data.object as Stripe.Invoice;
				await this.mirrorInvoice(event, inv);
				await this.subscriptionHandler.handleInvoiceUpdated(inv);
				break;
			}
			case 'customer.subscription.created':
			case 'customer.subscription.updated':
			case 'customer.subscription.pending_update_applied':
			case 'customer.subscription.pending_update_expired': {
				const sub = event.data.object as Stripe.Subscription;
				const subKnownUserId = await this.resolveKnownUserIdForSubscription(sub);
				const snapshotCapturedAt = new Date(event.created * 1000);
				await this.safeMirrorUpsert(event, () =>
					this.billingRepository.subscriptions.upsertFromStripe(sub, {
						knownUserId: subKnownUserId ?? undefined,
						snapshotCapturedAt,
					}),
				);
				await this.subscriptionHandler.handleSubscriptionUpdated(sub, snapshotCapturedAt);
				if (event.type === 'customer.subscription.updated') {
					await this.handleCancellationScheduled(event, sub);
					await this.clearWithdrawnCancelSource(event, sub);
				}
				break;
			}
			case 'customer.subscription.deleted': {
				const sub = event.data.object as Stripe.Subscription;
				const subKnownUserId = await this.resolveKnownUserIdForSubscription(sub);
				await this.safeMirrorUpsert(event, () =>
					this.billingRepository.subscriptions.upsertFromStripe(sub, {
						knownUserId: subKnownUserId ?? undefined,
						snapshotCapturedAt: new Date(event.created * 1000),
					}),
				);
				await this.subscriptionHandler.handleSubscriptionDeleted(sub);
				await this.voidUnpaidDonationInvoices(sub);
				await this.queueEndedUnpaid(sub);
				break;
			}
			case 'charge.dispute.created': {
				const d = event.data.object as Stripe.Dispute;
				await this.disputeHandler.handleChargebackCreated(d);
				break;
			}
			case 'charge.dispute.closed': {
				const d = event.data.object as Stripe.Dispute;
				await this.disputeHandler.handleChargebackClosed(d);
				break;
			}
			case 'radar.early_fraud_warning.created':
			case 'radar.early_fraud_warning.updated':
				await this.paymentFraudService.handleEarlyFraudWarning(event.data.object as Stripe.Radar.EarlyFraudWarning);
				break;
			case 'charge.refunded': {
				const c = event.data.object as Stripe.Charge;
				await this.safeMirrorUpsert(event, () => this.billingRepository.charges.upsertFromStripe(c));
				const refunds = await this.listChargeRefunds(c);
				for (const r of refunds) {
					await this.safeMirrorUpsert(event, () =>
						this.billingRepository.refunds.upsertFromStripe(r, {
							customerId: typeof c.customer === 'string' ? c.customer : (c.customer?.id ?? undefined),
							livemode: event.livemode,
						}),
					);
				}
				await this.disputeHandler.handleRefund(c);
				for (const r of refunds.filter((refund) => isRecentRefund(refund, event.created))) {
					await this.queueBillingEmail({kind: 'refund', id: r.id});
				}
				break;
			}
			case 'customer.created':
			case 'customer.updated': {
				const cust = event.data.object as Stripe.Customer;
				await this.safeMirrorUpsert(event, () => this.billingRepository.customers.upsertFromStripe(cust));
				break;
			}
			case 'customer.deleted': {
				const cust = event.data.object as Stripe.Customer | Stripe.DeletedCustomer;
				await this.safeMirrorUpsert(event, () => this.billingRepository.customers.upsertFromStripe(cust));
				await this.safeMirrorUpsert(event, () => this.billingRepository.customers.markDeleted(cust.id, new Date()));
				await this.donationRepository.clearDonorStripeCustomer(cust.id);
				break;
			}
			case 'price.created':
			case 'price.updated':
			case 'price.deleted': {
				const p = event.data.object as Stripe.Price;
				await this.safeMirrorUpsert(event, () => this.billingRepository.prices.upsertFromStripe(p));
				break;
			}
			case 'payment_method.attached':
			case 'payment_method.updated':
			case 'payment_method.automatically_updated': {
				const pm = event.data.object as Stripe.PaymentMethod;
				await this.safeMirrorUpsert(event, () => this.billingRepository.paymentMethods.upsertFromStripe(pm));
				break;
			}
			case 'payment_method.detached': {
				const pm = event.data.object as Stripe.PaymentMethod;
				await this.safeMirrorUpsert(event, () => this.billingRepository.paymentMethods.markDetached(pm.id, new Date()));
				break;
			}
			case 'mandate.updated': {
				await this.handleMandateUpdated(event.data.object as Stripe.Mandate);
				break;
			}
			case 'payment_intent.created':
			case 'payment_intent.processing':
			case 'payment_intent.succeeded':
			case 'payment_intent.payment_failed':
			case 'payment_intent.canceled':
			case 'payment_intent.requires_action': {
				const pi = event.data.object as Stripe.PaymentIntent;
				await this.safeMirrorUpsert(event, () => this.billingRepository.paymentIntents.upsertFromStripe(pi));
				break;
			}
			case 'charge.succeeded':
			case 'charge.updated':
			case 'charge.failed':
			case 'charge.captured': {
				const c = event.data.object as Stripe.Charge;
				await this.safeMirrorUpsert(event, () => this.billingRepository.charges.upsertFromStripe(c));
				if (event.type === 'charge.succeeded' && this.stripe) await tagChargeDistribution(this.stripe, c);
				break;
			}
			case 'refund.created':
			case 'refund.updated':
			case 'refund.failed': {
				const r = event.data.object as Stripe.Refund;
				const customerId = await this.resolveRefundCustomerId(r);
				await this.safeMirrorUpsert(event, () =>
					this.billingRepository.refunds.upsertFromStripe(r, {
						customerId: customerId ?? undefined,
						livemode: event.livemode,
					}),
				);
				await this.refundService.handleRefundWebhookEvent(r, event.type);
				await this.queueBillingEmail({kind: 'refund', id: r.id});
				await this.operatorPassFulfilment?.handleRefundFailed(r, event.type);
				break;
			}
			case 'invoice.created':
			case 'invoice.finalized':
			case 'invoice.voided':
			case 'invoice.marked_uncollectible': {
				const inv = event.data.object as Stripe.Invoice;
				await this.mirrorInvoice(event, inv);
				break;
			}
			case 'credit_note.created': {
				const note = event.data.object as Stripe.CreditNote;
				Logger.error(
					{billingDocumentAlert: true, creditNoteId: note.id, invoiceId: note.invoice, amount: note.total},
					'A Stripe credit note was created outside Fluxer; issue the Fluxer credit note for the refund with POST /admin/billing-documents/reissue (re:); a lost dispute needs no credit note',
				);
				await alertSupport({
					dedupeKey: `stripe-credit-note:${note.id}`,
					subject: `Stripe credit note ${note.id} created outside Fluxer`,
					summary:
						'Someone created a credit note in the Stripe Dashboard. If it is for a refund, issue the Fluxer credit note with POST /admin/billing-documents/reissue and the re: source. A lost dispute needs no credit note.',
					facts: {
						creditNoteId: note.id,
						invoiceId: extractId(note.invoice),
						refundId: extractId(note.refunds[0]?.refund ?? null),
						amountMinor: note.total,
						currency: note.currency,
					},
				});
				break;
			}
			case 'charge.dispute.updated': {
				const d = event.data.object as Stripe.Dispute;
				await this.disputeHandler.handleDisputeUpdated(d);
				break;
			}
			default: {
				Logger.debug({eventType: event.type, eventId: event.id}, 'Stripe webhook event type not handled');
			}
		}
	}

	private async queueBillingEmail(job: BillingEmailJob | null): Promise<void> {
		if (job) {
			await enqueueBillingEmail(getWorkerService(), job);
		}
	}

	private async handleCancellationScheduled(event: Stripe.Event, subscription: Stripe.Subscription): Promise<void> {
		const previous = (event.data.previous_attributes ?? {}) as Partial<Stripe.Subscription>;
		const scheduled =
			(previous.cancel_at_period_end === false && subscription.cancel_at_period_end) ||
			('cancel_at' in previous && previous.cancel_at === null && subscription.cancel_at != null);
		if (!scheduled || !subscriptionBillingProduct(subscription, this.productRegistry)) {
			return;
		}
		await this.voidUnpaidDonationInvoices(subscription);
		if (freshCancelSource(subscription, event.created)) {
			return;
		}
		await this.queueBillingEmail({
			kind: 'subscription_cancel_scheduled',
			id: subscription.id,
			requestedAt: event.created,
		});
	}

	private async voidUnpaidDonationInvoices(subscription: Stripe.Subscription): Promise<void> {
		if (!this.stripe || !isDonationSubscription(subscription)) {
			return;
		}
		for (const status of ['draft', 'open'] as const) {
			const invoices = await this.stripe.invoices.list({subscription: subscription.id, status, limit: 100});
			for (const invoice of invoices.data) {
				if (!invoice.id || invoice.amount_due <= 0) {
					continue;
				}
				if (status === 'draft') {
					await this.stripe.invoices.finalizeInvoice(invoice.id, {auto_advance: false});
				}
				await this.stripe.invoices.voidInvoice(invoice.id);
				Logger.info(
					{subscriptionId: subscription.id, invoiceId: invoice.id, status},
					'Voided an unpaid invoice of a canceled recurring donation',
				);
			}
		}
	}

	private async clearWithdrawnCancelSource(event: Stripe.Event, subscription: Stripe.Subscription): Promise<void> {
		const previous = (event.data.previous_attributes ?? {}) as Partial<Stripe.Subscription>;
		const withdrawn =
			(previous.cancel_at_period_end === true && !subscription.cancel_at_period_end) ||
			(previous.cancel_at != null && subscription.cancel_at == null);
		if (
			!withdrawn ||
			subscriptionCancelling(subscription, null) ||
			!this.stripe ||
			!subscription.metadata?.fluxer_cancel_source
		) {
			return;
		}
		try {
			await this.stripe.subscriptions.update(subscription.id, {metadata: CLEARED_CANCEL_METADATA});
		} catch (error) {
			Logger.warn({error, subscriptionId: subscription.id}, 'Could not clear the cancellation source after a resume');
		}
	}

	private async queueEndedUnpaid(subscription: Stripe.Subscription): Promise<void> {
		const reason = subscription.cancellation_details?.reason;
		if (reason === 'canceled_by_retention_policy') {
			Logger.info({subscriptionId: subscription.id}, 'Subscription ended by the retention policy; no email sent');
			return;
		}
		if (reason === 'payment_failed' && subscriptionBillingProduct(subscription, this.productRegistry) === 'plutonium') {
			await this.queueBillingEmail({kind: 'subscription_ended_unpaid', id: subscription.id});
		}
	}

	private async queueInvoicePaymentProblem(invoice: Stripe.Invoice, actionRequired: boolean): Promise<void> {
		await this.queueBillingEmail(
			invoice.id
				? {kind: 'invoice_payment_problem', id: invoice.id, paymentAttempt: invoice.attempt_count, actionRequired}
				: null,
		);
	}

	private async handleMandateUpdated(mandate: Stripe.Mandate): Promise<void> {
		if (mandate.status !== 'inactive') {
			return;
		}
		const paymentMethodId =
			typeof mandate.payment_method === 'string' ? mandate.payment_method : (mandate.payment_method?.id ?? null);
		Logger.warn(
			{mandateId: mandate.id, paymentMethodId, status: mandate.status},
			'Stripe mandate is no longer active; recurring payments on this payment method will fail',
		);
	}

	private async resolveRefundCustomerId(refund: Stripe.Refund): Promise<string | null> {
		const chargeId = typeof refund.charge === 'string' ? refund.charge : (refund.charge?.id ?? null);
		if (chargeId !== null) {
			const chargeRow = await this.billingRepository.charges.findById(chargeId);
			if (chargeRow?.customer_id != null) {
				return chargeRow.customer_id;
			}
		}
		const paymentIntentId =
			typeof refund.payment_intent === 'string' ? refund.payment_intent : (refund.payment_intent?.id ?? null);
		if (paymentIntentId !== null) {
			const paymentIntentRow = await this.billingRepository.paymentIntents.findById(paymentIntentId);
			if (paymentIntentRow?.customer_id != null) {
				return paymentIntentRow.customer_id;
			}
		}
		return null;
	}

	private async listChargeRefunds(charge: Stripe.Charge): Promise<Array<Stripe.Refund>> {
		const inlined = charge.refunds?.data ?? [];
		if (inlined.length > 0 || charge.id == null || this.stripe == null) {
			return inlined;
		}
		try {
			const listed = await this.stripe.refunds.list({charge: charge.id, limit: 100});
			return listed.data;
		} catch (listErr) {
			Logger.warn({listErr, chargeId: charge.id}, 'Failed to list refunds for charge; skipping refund mirror');
			return [];
		}
	}

	private async mirrorInvoice(event: Stripe.Event, inv: Stripe.Invoice): Promise<void> {
		let hydrated = inv;
		if (inv.payments === undefined && inv.id != null && this.stripe != null) {
			try {
				hydrated = await this.stripe.invoices.retrieve(inv.id, {expand: ['payments.data.payment']});
			} catch (hydrateErr) {
				Logger.warn(
					{hydrateErr, eventId: event.id, invoiceId: inv.id},
					'Failed to hydrate invoice payments; mirroring invoice without payment rows',
				);
			}
		}
		await this.safeMirrorUpsert(event, () => this.billingRepository.invoices.upsertFromStripe(hydrated));
	}

	private async safeMirrorUpsert(event: Stripe.Event, fn: () => Promise<unknown>): Promise<void> {
		await mirrorBestEffort(
			() => fn(),
			{eventId: event.id, eventType: event.type},
			'Mirror upsert failed; continuing with downstream handler',
		);
	}

	private async resolveKnownUserIdForSubscription(sub: Stripe.Subscription): Promise<bigint | null> {
		const metadataUserId = sub.metadata?.user_id ?? sub.metadata?.userId;
		if (typeof metadataUserId === 'string' && metadataUserId.length > 0) {
			try {
				return BigInt(metadataUserId);
			} catch {}
		}
		const customerId = typeof sub.customer === 'string' ? sub.customer : (sub.customer?.id ?? null);
		if (!customerId) {
			return null;
		}
		try {
			const customerRow = await this.billingRepository.customers.findById(customerId);
			return customerRow?.user_id ?? null;
		} catch (err) {
			Logger.warn({err, subscriptionId: sub.id, customerId}, 'Customer reverse-lookup failed for subscription mirror');
			return null;
		}
	}
}