Skip to content

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

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

import {createHash} from 'node:crypto';
import {alertSupport} from '@app/api/billing/BillingSupportAlert';
import {
	billingDocumentLanguage,
	buildCreditContent,
	buildSaleContent,
	type CreditOriginal,
	chargedTax,
	creditOriginalFromContent,
	creditSeries,
	layoutOf,
	type SaleData,
	type SaleLine,
	saleSeries,
	sekMinor,
	swedishTaxMinor,
	vatTreatmentOf,
} from '@app/api/billing_documents/BillingDocumentBuilder';
import {BillingDocumentRepository} from '@app/api/billing_documents/BillingDocumentRepository';
import {EcbReferenceRates} from '@app/api/billing_documents/EcbReferenceRates';
import {Config} from '@app/api/Config';
import type {BillingDocumentRow} from '@app/api/database/types/BillingDocumentTypes';
import {Logger} from '@app/api/Logger';
import {getKVClient, getSnowflakeService} from '@app/api/middleware/ServiceRegistry';
import {getBillingBranding} from '@app/api/stripe/BillingBranding';
import {ProductType} from '@app/api/stripe/ProductRegistry';
import {extractId} from '@app/api/stripe/StripeUtils';
import {
	type BillingDocumentAddress,
	type BillingDocumentBuyer,
	type BillingDocumentContent,
	type BillingDocumentCreditReason,
	type BillingDocumentFlow,
	type BillingDocumentLanguage,
	type BillingDocumentSekTax,
	type BillingDocumentSeries,
	type BillingDocumentTaxLine,
	type BillingDocumentVatIdVerification,
	billingDocumentFilename,
	formatBillingDocumentNumber,
	stockholmDate,
} from '@pkgs/email/src/billing_documents/BillingDocumentContent';
import {renderBillingDocumentPdf} from '@pkgs/email/src/billing_documents/BillingDocumentPdf';
import type {BillingDocumentAttachment, BillingTotals} from '@pkgs/email/src/IEmailService';
import type Stripe from 'stripe';

const LINE_ITEM_LIMIT = 100;
const YEARLY_PERIOD_MIN_SECONDS = 60 * 24 * 60 * 60;

export interface IssueContext {
	userId: bigint | null;
	locale: string | null;
	donorEmail?: string | null;
}

interface Descriptions {
	operatorPass: string;
	plan: (name: string, yearly: boolean) => string;
	proration: (name: string) => string;
	gift: (name: string, yearly: boolean) => string;
	donation: (interval: 'once' | 'month' | 'year') => string;
}

const DESCRIPTIONS: Record<BillingDocumentLanguage, Descriptions> = {
	en: {
		operatorPass: 'Operator Pass: printable numbered Operator certificate (PDF), delivered digitally',
		plan: (name, yearly) => `${name}, ${yearly ? 'yearly' : 'monthly'} subscription`,
		proration: (name) => `${name}, adjustment for a plan change`,
		gift: (name, yearly) => `${name} gift code, ${yearly ? '1 year' : '1 month'}`,
		donation: (interval) =>
			({month: 'Monthly donation to Fluxer', year: 'Yearly donation to Fluxer', once: 'Donation to Fluxer'})[interval],
	},
	'sv-SE': {
		operatorPass: 'Operator Pass: utskrivbart numrerat Operator-certifikat (PDF), levereras digitalt',
		plan: (name, yearly) => `${name}, ${yearly ? 'årsabonnemang' : 'månadsabonnemang'}`,
		proration: (name) => `${name}, justering vid byte av plan`,
		gift: (name, yearly) => `${name}-presentkod, ${yearly ? '1 år' : '1 månad'}`,
		donation: (interval) =>
			({month: 'Månatlig gåva till Fluxer', year: 'Årlig gåva till Fluxer', once: 'Gåva till Fluxer'})[interval],
	},
	'pt-BR': {
		operatorPass: 'Operator Pass: certificado de Operator numerado para impressão (PDF), entregue digitalmente',
		plan: (name, yearly) => `${name}, assinatura ${yearly ? 'anual' : 'mensal'}`,
		proration: (name) => `${name}, ajuste por mudança de plano`,
		gift: (name, yearly) => `Código de presente ${name}, ${yearly ? '1 ano' : '1 mês'}`,
		donation: (interval) =>
			({month: 'Doação mensal ao Fluxer', year: 'Doação anual ao Fluxer', once: 'Doação ao Fluxer'})[interval],
	},
};

function isoFromUnix(value: number | null | undefined): string | null {
	return value ? new Date(value * 1000).toISOString() : null;
}

function address(value: Stripe.Address | null | undefined): BillingDocumentAddress | null {
	if (!value || !(value.line1 || value.city || value.postal_code)) {
		return null;
	}
	return {
		line1: value.line1 ?? null,
		line2: value.line2 ?? null,
		postalCode: value.postal_code ?? null,
		city: value.city ?? null,
		state: value.state ?? null,
		country: value.country ?? null,
	};
}

function describeCharge(charge: Stripe.Charge | null): string | null {
	const details = charge?.payment_method_details;
	if (!details) {
		return null;
	}
	if (details.type === 'card' && details.card) {
		const brand = details.card.brand
			? details.card.brand.charAt(0).toUpperCase() + details.card.brand.slice(1)
			: 'Card';
		return details.card.last4 ? `${brand} ···· ${details.card.last4}` : brand;
	}
	return details.type === 'pix'
		? 'Pix'
		: details.type.charAt(0).toUpperCase() + details.type.slice(1).replaceAll('_', ' ');
}

function taxRatePercent(rate: Stripe.TaxRate | null | undefined): number | null {
	return rate?.percentage ?? null;
}

function sha256(value: string | Uint8Array): string {
	return createHash('sha256').update(value).digest('hex');
}

export function billingDocumentContent(row: BillingDocumentRow): BillingDocumentContent {
	return JSON.parse(row.content) as BillingDocumentContent;
}

export function billingDocumentAttachment(row: BillingDocumentRow): BillingDocumentAttachment {
	return {
		number: row.display_number,
		issuedAt: row.issued_at,
		pdf: {
			filename: billingDocumentFilename(row.display_number),
			content: new Uint8Array(row.pdf),
			contentType: 'application/pdf',
		},
	};
}

export function billingDocumentTotals(row: BillingDocumentRow): BillingTotals {
	const content = billingDocumentContent(row);
	return {
		totalMinor: content.totalMinor,
		paidMinor: content.totalMinor,
		currency: content.currency.toLowerCase(),
		tax: content.taxMinor !== 0 ? {amountMinor: content.taxMinor, behavior: 'inclusive'} : null,
		reverseCharge: content.vatTreatment === 'reverse_charge_eu',
	};
}

const FRAUD_DISPUTE_REASONS = new Set<string>(['fraudulent', 'unrecognized']);

type CreditSource = Pick<Stripe.Refund, 'id' | 'created' | 'amount' | 'currency'>;

function creditReason(refund: Stripe.Refund): BillingDocumentCreditReason {
	if (refund.reason === 'fraudulent') return 'fraud';
	if (refund.reason === 'duplicate') return 'duplicate';
	return (refund.metadata?.rejection_reason ?? '').startsWith('operator_pass_withdrawal:') ? 'withdrawal' : 'refund';
}

export class BillingDocumentSourceError extends Error {
	constructor(message: string) {
		super(message);
		this.name = 'BillingDocumentSourceError';
	}
}

export function createBillingDocumentService(stripe: Stripe | null): BillingDocumentService | null {
	if (!stripe || Config.instance.selfHosted) {
		return null;
	}
	return new BillingDocumentService(stripe, new BillingDocumentRepository(), new EcbReferenceRates(getKVClient()), () =>
		getSnowflakeService().generate(),
	);
}

export class BillingDocumentService {
	private readonly taxRates = new Map<string, Promise<Stripe.TaxRate>>();
	private readonly seriesStarts = new Map<string, Date | null>();

	constructor(
		private readonly stripe: Stripe,
		readonly repository: BillingDocumentRepository,
		private readonly ecb: EcbReferenceRates,
		private readonly nextId: () => Promise<bigint>,
		private readonly now: () => Date = () => new Date(),
	) {}

	async findDocument(documentId: bigint): Promise<BillingDocumentRow | null> {
		return this.repository.findDocument(documentId);
	}

	async issueForCheckoutSession(sessionId: string, context: IssueContext): Promise<BillingDocumentRow> {
		const existing = await this.repository.findDocumentBySource(`cs:${sessionId}`);
		if (existing) {
			return existing;
		}
		const session = await this.stripe.checkout.sessions.retrieve(sessionId);
		const invoiceId = extractId(session.invoice);
		if (session.mode !== 'payment' || invoiceId) {
			throw new BillingDocumentSourceError(
				invoiceId
					? `Checkout session ${sessionId} has Stripe invoice ${invoiceId}; its sale is documented under in:${invoiceId} or before the cutover, not under cs:`
					: `Checkout session ${sessionId} is a ${session.mode} session; its payments are documented under their in: invoices`,
			);
		}
		const language = billingDocumentLanguage(context.locale);
		const sale = await this.loadCheckoutSale(sessionId, language);
		return this.issueSale(`cs:${sessionId}`, sale, language, context);
	}

	async issueForInvoice(invoiceId: string, context: IssueContext): Promise<BillingDocumentRow | null> {
		const existing = await this.repository.findDocumentBySource(`in:${invoiceId}`);
		if (existing) {
			return existing;
		}
		const language = billingDocumentLanguage(context.locale);
		const sale = await this.loadInvoiceSale(invoiceId, language);
		return sale ? this.issueSale(`in:${invoiceId}`, sale, language, context) : null;
	}

	async issueForRefund(refundOrId: Stripe.Refund | string, context: IssueContext): Promise<BillingDocumentRow | null> {
		const refund = typeof refundOrId === 'string' ? await this.stripe.refunds.retrieve(refundOrId) : refundOrId;
		const own = await this.repository.findDocumentBySource(`re:${refund.id}`);
		if (own) {
			return own;
		}
		const retryOf = refund.metadata?.retry_of;
		if (retryOf) {
			const retried = await this.repository.findDocumentBySource(`re:${retryOf}`);
			if (retried) {
				await this.repository.aliasSource(`re:${refund.id}`, retried.document_id);
				return retried;
			}
		}
		if (refund.status !== 'succeeded' || refund.amount <= 0) {
			return null;
		}
		const paymentIntentId = extractId(refund.payment_intent ?? null);
		if (!paymentIntentId) {
			return null;
		}
		const original = await this.resolveOriginal(paymentIntentId, context);
		if (!original) {
			Logger.warn({refundId: refund.id, paymentIntentId}, 'No original sale found for a refund; no credit note issued');
			return null;
		}
		const chargeId = extractId(refund.charge ?? null) ?? original.sale.references.chargeId;
		const charge = chargeId ? await this.stripe.charges.retrieve(chargeId) : null;
		const creditedBefore = await this.creditedBefore(paymentIntentId, refund, charge, original);
		const amountMinor = refundCreditMinor(refund, charge, original, creditedBefore);
		return this.issueCredit(`re:${refund.id}`, original, context, {
			amountMinor,
			creditedBeforeMinor: creditedBefore,
			creditedQuantity: withdrawnPassCount(refund),
			reason: creditReason(refund),
			at: new Date(refund.created * 1000).toISOString(),
			references: {
				...original.sale.references,
				refundId: refund.id,
				disputeId: null,
				chargeId: extractId(refund.charge ?? null) ?? original.sale.references.chargeId,
			},
		});
	}

	async issueForDispute(disputeId: string, context: IssueContext): Promise<BillingDocumentRow | null> {
		const own = await this.repository.findDocumentBySource(`du:${disputeId}`);
		if (own) {
			return own;
		}
		const dispute = await this.stripe.disputes.retrieve(disputeId);
		if (dispute.status !== 'lost') {
			throw new BillingDocumentSourceError(`Dispute ${disputeId} is ${dispute.status}, not lost`);
		}
		if (FRAUD_DISPUTE_REASONS.has(dispute.reason)) {
			throw new BillingDocumentSourceError(
				`Dispute ${disputeId} is a ${dispute.reason} dispute, which the books treat as a bad debt without a credit note`,
			);
		}
		const paymentIntentId = extractId(dispute.payment_intent ?? null);
		if (!paymentIntentId) {
			return null;
		}
		const original = await this.resolveOriginal(paymentIntentId, context);
		if (!original) {
			Logger.warn({disputeId, paymentIntentId}, 'No original sale found for a lost dispute; no credit note issued');
			return null;
		}
		const chargeId = extractId(dispute.charge ?? null) ?? original.sale.references.chargeId;
		const charge = chargeId ? await this.stripe.charges.retrieve(chargeId) : null;
		const current = {id: dispute.id, created: dispute.created, amount: dispute.amount, currency: dispute.currency};
		const creditedBefore = await this.creditedBefore(paymentIntentId, current, charge, original);
		return this.issueCredit(`du:${dispute.id}`, original, context, {
			amountMinor: refundCreditMinor(current, charge, original, creditedBefore),
			creditedBeforeMinor: creditedBefore,
			creditedQuantity: null,
			reason: 'dispute',
			at: new Date().toISOString(),
			references: {
				...original.sale.references,
				refundId: null,
				disputeId: dispute.id,
				chargeId: chargeId ?? null,
			},
		});
	}

	async reissue(sourceKey: string, context: IssueContext): Promise<BillingDocumentRow | null> {
		const separator = sourceKey.indexOf(':');
		const id = sourceKey.slice(separator + 1);
		switch (separator > 0 && id ? sourceKey.slice(0, separator) : null) {
			case 'cs':
				return this.issueForCheckoutSession(id, context);
			case 'in':
				return this.issueForInvoice(id, context);
			case 're':
				return this.issueForRefund(id, context);
			case 'du':
				return this.issueForDispute(id, context);
			default:
				throw new BillingDocumentSourceError(
					`Billing document source ${sourceKey} is not a cs:, in:, re: or du: source`,
				);
		}
	}

	async reissueContext(sourceKey: string): Promise<IssueContext> {
		const id = sourceKey.slice(sourceKey.indexOf(':') + 1);
		const userId = (value: string | null | undefined) => (value && /^\d+$/.test(value) ? BigInt(value) : null);
		if (sourceKey.startsWith('cs:')) {
			const session = await this.stripe.checkout.sessions.retrieve(id);
			const metadata = session.metadata ?? {};
			return {
				userId: userId(session.client_reference_id ?? metadata.user_id),
				locale: metadata.operator_pass_locale ?? metadata.donation_locale ?? null,
				donorEmail:
					metadata.is_donation === 'true' ? (metadata.donation_email ?? session.customer_details?.email ?? null) : null,
			};
		}
		if (sourceKey.startsWith('in:')) {
			const invoice = await this.stripe.invoices.retrieve(id);
			const metadata = {...invoice.metadata, ...invoice.parent?.subscription_details?.metadata};
			return {
				userId: userId(metadata.user_id),
				locale: metadata.donation_locale ?? null,
				donorEmail:
					metadata.is_donation === 'true' ? (metadata.donation_email ?? invoice.customer_email ?? null) : null,
			};
		}
		if (!sourceKey.startsWith('re:') && !sourceKey.startsWith('du:')) {
			throw new BillingDocumentSourceError(`Billing document source ${sourceKey} is not a cs:, in:, re: or du: source`);
		}
		const source = sourceKey.startsWith('re:')
			? await this.stripe.refunds.retrieve(id)
			: await this.stripe.disputes.retrieve(id);
		const paymentIntentId = extractId(source.payment_intent ?? null);
		const original = paymentIntentId ? await this.repository.findDocumentBySource(`pi:${paymentIntentId}`) : null;
		return {userId: original?.user_id ?? null, locale: original?.language ?? null};
	}

	private async issueSale(
		sourceKey: string,
		sale: SaleData,
		language: BillingDocumentLanguage,
		context: IssueContext,
	): Promise<BillingDocumentRow> {
		const sekTax = await this.sekTax(sale);
		const series = saleSeries(sale.flow);
		const missingAddress = layoutOf(sale.buyer) === 'full' && !sale.buyer.address;
		if (missingAddress) {
			Logger.error(
				{billingDocumentAlert: true, sourceKey, series, country: sale.buyer.country},
				'A full invoice goes to a business buyer without an address; add the address with a corrected invoice',
			);
		}
		const row = await this.issue(sourceKey, series, context, (documentId, number, issuedAt) =>
			buildSaleContent(sale, {documentId, number, issuedAt, language}, sekTax),
		);
		if (missingAddress) {
			await alertSupport({
				dedupeKey: `missing-address:${sourceKey}`,
				subject: `Invoice ${row.display_number} has no buyer address`,
				summary:
					'A full invoice was issued to a business buyer without the buyer address. A full invoice must name the buyer and their address, so send the buyer a corrected invoice.',
				facts: {
					invoiceId: sale.references.stripeInvoiceId,
					paymentIntentId: sale.references.paymentIntentId,
					checkoutSessionId: sale.references.checkoutSessionId,
					userId: context.userId,
					documentNumber: row.display_number,
					series,
					amountMinor: sale.totalMinor,
					currency: sale.currency,
					country: sale.buyer.country,
				},
			});
		}
		if (sale.references.paymentIntentId) {
			await this.repository.aliasSource(`pi:${sale.references.paymentIntentId}`, row.document_id);
		}
		return row;
	}

	private async issueCredit(
		sourceKey: string,
		original: CreditOriginal,
		context: IssueContext,
		request: Parameters<typeof buildCreditContent>[1],
	): Promise<BillingDocumentRow> {
		const language = original.language ?? billingDocumentLanguage(context.locale);
		return this.issue(sourceKey, creditSeries(original), context, (documentId, number, issuedAt) =>
			buildCreditContent(original, request, {documentId, number, issuedAt, language}),
		);
	}

	private async issue(
		sourceKey: string,
		series: BillingDocumentSeries,
		context: IssueContext,
		build: (documentId: string, number: string, issuedAt: string) => BillingDocumentContent,
	): Promise<BillingDocumentRow> {
		const source = await this.repository.claimSource(sourceKey, await this.nextId());
		const documentId = source.document_id;
		const done = await this.repository.findDocument(documentId);
		if (done) {
			return done;
		}
		const claimed = await this.repository.claimNumber(series, sourceKey, documentId);
		const issuedAt = this.now();
		const content = build(
			documentId.toString(),
			formatBillingDocumentNumber(series, claimed.number),
			issuedAt.toISOString(),
		);
		const json = JSON.stringify(content);
		const pdf = await renderBillingDocumentPdf(content);
		const original = content.original?.documentId ? BigInt(content.original.documentId) : null;
		const row = await this.repository.createDocument({
			document_id: documentId,
			series,
			number: claimed.number,
			display_number: content.number,
			kind: content.kind,
			flow: content.flow,
			layout: content.layout,
			issued_at: issuedAt,
			supply_date: content.supplyDate,
			period_start: content.periodStart ? new Date(content.periodStart) : null,
			period_end: content.periodEnd ? new Date(content.periodEnd) : null,
			currency: content.currency,
			total_minor: BigInt(content.totalMinor),
			tax_minor: BigInt(content.taxMinor),
			tax_lines: JSON.stringify(content.taxLines),
			sek_tax_minor: content.sekTax ? BigInt(content.sekTax.amountMinor) : null,
			fx_rate: content.sekTax?.rate ?? null,
			fx_date: content.sekTax?.rateDate ?? null,
			buyer: JSON.stringify(content.buyer),
			seller: JSON.stringify(content.seller),
			language: content.language,
			original_document_id: original,
			original_number: content.original?.number ?? null,
			reason: content.reason,
			source_key: sourceKey,
			stripe_refs: JSON.stringify(content.references),
			user_id: context.userId,
			donor_email_hash: context.donorEmail ? sha256(context.donorEmail.trim().toLowerCase()) : null,
			content: json,
			content_sha256: sha256(json),
			pdf: Buffer.from(pdf),
			pdf_sha256: sha256(pdf),
			render_version: content.renderVersion,
			emailed_at: null,
			archived_at: null,
		});
		Logger.info({documentId: row.document_id, number: row.display_number, sourceKey}, 'Issued a billing document');
		return row;
	}

	private async sekTax(sale: SaleData): Promise<BillingDocumentSekTax | null> {
		const seTax = swedishTaxMinor(sale.taxLines);
		if (seTax === 0 || sale.currency.toUpperCase() === 'SEK' || sale.flow === 'gift' || sale.flow === 'donation') {
			return null;
		}
		const rate = await this.ecb.sekRate(sale.currency, sale.payment ? new Date(sale.payment.at) : this.now());
		return {
			amountMinor: sekMinor(seTax, sale.currency, rate.rate),
			rate: rate.rate,
			rateDate: rate.rateDate,
			source: 'ECB',
		};
	}

	private async buyerVerification(
		customerId: string | null,
		vatId: string | null,
	): Promise<BillingDocumentVatIdVerification | null> {
		if (!vatId) {
			return null;
		}
		if (!customerId) {
			return 'unavailable';
		}
		const ids = await this.stripe.customers.listTaxIds(customerId, {limit: 20});
		const match = ids.data.find((id) => id.value === vatId);
		switch (match?.verification?.status) {
			case 'verified':
				return 'verified';
			case 'unverified':
				return 'unverified';
			case 'pending':
				return 'pending';
			default:
				return 'unavailable';
		}
	}

	private async taxRate(id: string): Promise<Stripe.TaxRate> {
		let rate = this.taxRates.get(id);
		if (!rate) {
			rate = this.stripe.taxRates.retrieve(id);
			this.taxRates.set(id, rate);
		}
		return rate;
	}

	async loadCheckoutSale(sessionId: string, language: BillingDocumentLanguage): Promise<SaleData> {
		const session = await this.stripe.checkout.sessions.retrieve(sessionId, {
			expand: ['total_details.breakdown', 'payment_intent.latest_charge'],
		});
		if (session.payment_status !== 'paid' && session.payment_status !== 'no_payment_required') {
			throw new Error(`Checkout session ${sessionId} is not paid yet`);
		}
		const items = await this.stripe.checkout.sessions.listLineItems(sessionId, {
			limit: LINE_ITEM_LIMIT,
			expand: ['data.taxes'],
		});
		const flow = checkoutFlow(session);
		const descriptions = DESCRIPTIONS[language];
		const branding = await getBillingBranding();
		const premium = `${branding.productName} ${branding.premiumName}`;
		const intent = typeof session.payment_intent === 'object' ? session.payment_intent : null;
		const charge = intent && typeof intent.latest_charge === 'object' ? intent.latest_charge : null;
		const paidAt = charge ? new Date(charge.created * 1000) : new Date(session.created * 1000);
		const description = (item: Stripe.LineItem): string => {
			switch (flow) {
				case 'operator_pass':
					return descriptions.operatorPass;
				case 'gift':
					return descriptions.gift(premium, session.metadata?.product_type === ProductType.GIFT_1_YEAR);
				case 'donation':
					return descriptions.donation('once');
				default:
					return item.description ?? premium;
			}
		};
		const lines: Array<SaleLine> = items.data.map((item) => ({
			description: description(item),
			quantity: item.quantity ?? 1,
			amountMinor: item.amount_total,
			taxMinor: item.amount_tax,
			ratePercent: taxRatePercent(item.taxes?.find((tax) => tax.amount > 0)?.rate),
			periodStart: null,
			periodEnd: null,
		}));
		const taxLines = untaxedAtNet(
			(session.total_details?.breakdown?.taxes ?? []).map((tax) => ({
				country: tax.rate.country ?? null,
				jurisdiction: tax.rate.jurisdiction ?? null,
				ratePercent: tax.rate.percentage ?? null,
				taxType: tax.rate.tax_type ?? null,
				taxabilityReason: tax.taxability_reason ?? null,
				taxableMinor: tax.taxable_amount ?? 0,
				taxMinor: tax.amount,
			})),
			lines,
		);
		const details = session.customer_details;
		const vatId = details?.tax_ids?.[0]?.value ?? null;
		const customerId = extractId(session.customer);
		const business = (details?.tax_ids?.length ?? 0) > 0 || Boolean(details?.business_name);
		const buyer: BillingDocumentBuyer = {
			business,
			name: business ? (details?.name ?? null) : null,
			businessName: details?.business_name ?? null,
			email: details?.email ?? session.customer_email ?? null,
			address: business ? address(details?.address) : null,
			country: details?.address?.country ?? taxLines[0]?.country ?? null,
			vatId,
			vatIdVerification: await this.buyerVerification(customerId, vatId),
		};
		return {
			flow,
			currency: session.currency ?? charge?.currency ?? 'usd',
			totalMinor: session.amount_total ?? 0,
			lines,
			taxLines,
			buyer,
			supplyDate: stockholmDate(paidAt.toISOString()),
			periodStart: null,
			periodEnd: null,
			payment: {at: paidAt.toISOString(), method: describeCharge(charge)},
			references: {
				checkoutSessionId: session.id,
				paymentIntentId: intent?.id ?? extractId(session.payment_intent),
				chargeId: charge?.id ?? null,
				stripeInvoiceId: null,
				refundId: null,
				disputeId: null,
			},
		};
	}

	async loadInvoiceSale(invoiceId: string, language: BillingDocumentLanguage): Promise<SaleData | null> {
		const invoice = await this.stripe.invoices.retrieve(invoiceId, {
			expand: ['payments.data.payment.payment_intent'],
		});
		if (invoice.status !== 'paid' || invoice.total <= 0) {
			return null;
		}
		const donation = invoice.parent?.subscription_details?.metadata?.is_donation === 'true';
		const descriptions = DESCRIPTIONS[language];
		const branding = await getBillingBranding();
		const premium = `${branding.productName} ${branding.premiumName}`;
		const payment = (invoice.payments?.data ?? []).find((entry) => entry.status === 'paid')?.payment;
		const intent = typeof payment?.payment_intent === 'object' ? payment.payment_intent : null;
		const latestCharge = intent?.latest_charge ?? null;
		const charge =
			typeof latestCharge === 'string' ? await this.stripe.charges.retrieve(latestCharge) : (latestCharge ?? null);
		const taxLinesById = new Map<string, BillingDocumentTaxLine>();
		for (const tax of invoice.total_taxes ?? []) {
			const id = tax.tax_rate_details?.tax_rate;
			const rate = id ? await this.taxRate(id) : null;
			const key = id ?? `${tax.taxability_reason}`;
			const current = taxLinesById.get(key);
			taxLinesById.set(key, {
				country: rate?.country ?? null,
				jurisdiction: rate?.jurisdiction ?? null,
				ratePercent: rate?.percentage ?? null,
				taxType: rate?.tax_type ?? null,
				taxabilityReason: tax.taxability_reason ?? null,
				taxableMinor: (current?.taxableMinor ?? 0) + (tax.taxable_amount ?? 0),
				taxMinor: (current?.taxMinor ?? 0) + tax.amount,
			});
		}
		const lines: Array<SaleLine> = [];
		for (const line of invoice.lines?.data ?? []) {
			const taxes = line.taxes ?? [];
			const taxMinor = taxes.reduce((sum, tax) => sum + tax.amount, 0);
			const discounts = (line.discount_amounts ?? []).reduce((sum, discount) => sum + discount.amount, 0);
			const exclusive = taxes.some((tax) => tax.tax_behavior === 'exclusive');
			const rateId = taxes.find((tax) => tax.amount > 0)?.tax_rate_details?.tax_rate;
			const proration = Boolean(
				line.parent?.subscription_item_details?.proration || line.parent?.invoice_item_details?.proration,
			);
			const yearly = line.period ? line.period.end - line.period.start > YEARLY_PERIOD_MIN_SECONDS : false;
			const planDescription = proration ? descriptions.proration(premium) : descriptions.plan(premium, yearly);
			lines.push({
				description: donation ? descriptions.donation(yearly ? 'year' : 'month') : planDescription,
				quantity: line.quantity ?? 1,
				amountMinor: line.amount - discounts + (exclusive ? taxMinor : 0),
				taxMinor,
				ratePercent: rateId ? ((await this.taxRate(rateId)).percentage ?? null) : null,
				periodStart: isoFromUnix(line.period?.start),
				periodEnd: isoFromUnix(line.period?.end),
			});
		}
		const linesTotal = lines.reduce((sum, line) => sum + line.amountMinor, 0);
		const last = lines.at(-1);
		if (last && linesTotal !== invoice.total) {
			Logger.warn(
				{invoiceId, linesTotal, total: invoice.total},
				'Invoice lines do not add up to the total; the last line takes the difference',
			);
			last.amountMinor += invoice.total - linesTotal;
		}
		const taxLines = untaxedAtNet([...taxLinesById.values()], lines);
		const vatId = invoice.customer_tax_ids?.[0]?.value ?? null;
		const customerId = extractId(invoice.customer);
		const primary = lines.find((line) => line.periodStart && line.amountMinor > 0) ?? lines[0];
		const paidAt = isoFromUnix(invoice.status_transitions?.paid_at) ?? new Date(invoice.created * 1000).toISOString();
		const business = (invoice.customer_tax_ids?.length ?? 0) > 0;
		const buyer: BillingDocumentBuyer = {
			business,
			name: business ? (invoice.customer_name ?? null) : null,
			businessName: business ? (invoice.customer_name ?? null) : null,
			email: invoice.customer_email ?? null,
			address: business ? address(invoice.customer_address) : null,
			country: invoice.customer_address?.country ?? taxLines[0]?.country ?? null,
			vatId,
			vatIdVerification: await this.buyerVerification(customerId, vatId),
		};
		return {
			flow: donation ? 'donation' : 'plutonium',
			currency: invoice.currency,
			totalMinor: invoice.total,
			lines,
			taxLines,
			buyer,
			supplyDate: null,
			periodStart: primary?.periodStart ?? null,
			periodEnd: primary?.periodEnd ?? null,
			payment: {at: paidAt, method: describeCharge(charge)},
			references: {
				checkoutSessionId: null,
				paymentIntentId: intent?.id ?? null,
				chargeId: charge?.id ?? null,
				stripeInvoiceId: invoice.id ?? null,
				refundId: null,
				disputeId: null,
			},
		};
	}

	private async seriesStartedAt(series: BillingDocumentSeries): Promise<Date | null> {
		if (this.seriesStarts.has(series)) {
			return this.seriesStarts.get(series) ?? null;
		}
		const first = await this.repository.findNumber(series, 1n);
		const document = first?.document_id ? await this.repository.findDocument(first.document_id) : null;
		const startedAt = document?.issued_at ?? null;
		if (startedAt) {
			this.seriesStarts.set(series, startedAt);
		}
		return startedAt;
	}

	private async issuedAfterCutover(flow: BillingDocumentFlow, paidAt: Date): Promise<boolean> {
		const startedAt = await this.seriesStartedAt(saleSeries(flow));
		return startedAt != null && paidAt.getTime() >= startedAt.getTime();
	}

	private async resolveOriginal(paymentIntentId: string, context: IssueContext): Promise<CreditOriginal | null> {
		const known = await this.repository.findDocumentBySource(`pi:${paymentIntentId}`);
		if (known) {
			return creditOriginalFromContent(billingDocumentContent(known));
		}
		const language = billingDocumentLanguage(context.locale);
		const sessions = await this.stripe.checkout.sessions.list({payment_intent: paymentIntentId, limit: 1});
		const session = sessions.data[0];
		if (session && session.mode === 'payment') {
			const flow = checkoutFlow(session);
			const legacyInvoiceId = extractId(session.invoice);
			if (!legacyInvoiceId && (await this.issuedAfterCutover(flow, new Date(session.created * 1000)))) {
				const issued = await this.issueForCheckoutSession(session.id, context);
				return creditOriginalFromContent(billingDocumentContent(issued));
			}
			const sale = await this.loadCheckoutSale(session.id, language);
			const legacy = legacyInvoiceId ? await this.stripe.invoices.retrieve(legacyInvoiceId) : null;
			return this.legacyOriginal(sale, legacy, paymentIntentId);
		}
		const invoice = await this.findSubscriptionInvoice(paymentIntentId);
		if (!invoice?.id) {
			return null;
		}
		const issuedDocument = await this.repository.findDocumentBySource(`in:${invoice.id}`);
		if (issuedDocument) {
			return creditOriginalFromContent(billingDocumentContent(issuedDocument));
		}
		const donation = invoice.parent?.subscription_details?.metadata?.is_donation === 'true';
		const paidAt = new Date((invoice.status_transitions?.paid_at ?? invoice.created) * 1000);
		if (await this.issuedAfterCutover(donation ? 'donation' : 'plutonium', paidAt)) {
			const issued = await this.issueForInvoice(invoice.id, context);
			if (issued) {
				return creditOriginalFromContent(billingDocumentContent(issued));
			}
		}
		const sale = await this.loadInvoiceSale(invoice.id, language);
		return sale ? this.legacyOriginal(sale, invoice, paymentIntentId) : null;
	}

	private legacyOriginal(sale: SaleData, invoice: Stripe.Invoice | null, paymentIntentId: string): CreditOriginal {
		const reference = invoice?.number
			? {
					number: invoice.number,
					issuedAt:
						isoFromUnix(invoice.status_transitions?.finalized_at) ?? new Date(invoice.created * 1000).toISOString(),
					documentId: null,
				}
			: {
					number: sale.references.chargeId ?? paymentIntentId,
					issuedAt: sale.payment?.at ?? this.now().toISOString(),
					documentId: null,
				};
		return {
			sale,
			language: null,
			reference,
			layout: invoice ? layoutOf(sale.buyer) : 'simplified',
			vatTreatment: sale.flow === 'gift' && invoice && chargedTax(sale) > 0 ? 'charged' : vatTreatmentOf(sale),
			sekRate: null,
		};
	}

	private async findSubscriptionInvoice(paymentIntentId: string): Promise<Stripe.Invoice | null> {
		const payments = await this.stripe.invoicePayments.list({
			payment: {type: 'payment_intent', payment_intent: paymentIntentId},
			status: 'paid',
			limit: 1,
		});
		const invoiceId = extractId(payments.data[0]?.invoice ?? null);
		return invoiceId ? this.stripe.invoices.retrieve(invoiceId) : null;
	}

	private async creditedBefore(
		paymentIntentId: string,
		current: CreditSource,
		charge: Stripe.Charge | null,
		original: CreditOriginal,
	): Promise<number> {
		const refunds = await this.stripe.refunds.list({payment_intent: paymentIntentId, limit: 100});
		let total = 0;
		for (const refund of refunds.data) {
			const earlier =
				refund.created < current.created || (refund.created === current.created && refund.id < current.id);
			if (refund.id === current.id || !earlier) {
				continue;
			}
			const credited = await this.repository.findSource(`re:${refund.id}`);
			const retried = refund.metadata?.retry_of
				? await this.repository.findSource(`re:${refund.metadata.retry_of}`)
				: null;
			if (credited && !retried) {
				const document = await this.repository.findDocument(credited.document_id);
				total += document ? -Number(document.total_minor) : 0;
			} else if (!credited && !retried && refund.status === 'succeeded') {
				total += refundCreditMinor(refund, charge, original, total);
			}
		}
		return total;
	}
}

function remainingMinor(original: CreditOriginal, creditedBefore: number): number {
	return Math.max(0, original.sale.totalMinor - creditedBefore);
}

function convertedCharge(refund: CreditSource, charge: Stripe.Charge, original: CreditOriginal): boolean {
	const presentment = charge.presentment_details?.presentment_currency?.toLowerCase();
	return (
		charge.currency !== original.sale.currency.toLowerCase() ||
		(refund.currency != null && refund.currency !== charge.currency) ||
		(presentment != null && presentment !== charge.currency)
	);
}

function refundCreditMinor(
	refund: CreditSource,
	charge: Stripe.Charge | null,
	original: CreditOriginal,
	creditedBefore: number,
): number {
	const remaining = remainingMinor(original, creditedBefore);
	if (!charge || !convertedCharge(refund, charge, original)) {
		return Math.min(refund.amount, remaining);
	}
	if (refund.currency && refund.currency !== charge.currency) {
		Logger.error(
			{
				billingDocumentAlert: true,
				refundId: refund.id,
				refundCurrency: refund.currency,
				chargeCurrency: charge.currency,
			},
			'A refund is in another currency than its charge; check the credit note amount',
		);
		void alertSupport({
			dedupeKey: `credit-currency:${refund.id}`,
			subject: `Check the credit note amount for ${refund.id}`,
			summary: `A refund or dispute is in ${refund.currency.toUpperCase()} but its charge was in ${charge.currency.toUpperCase()}. Check that the credit note amount is right.`,
			facts: {
				...(refund.id.startsWith('re_') ? {refundId: refund.id} : {disputeId: refund.id}),
				paymentIntentId: original.sale.references.paymentIntentId,
				documentNumber: original.reference.number,
				amountMinor: refund.amount,
				currency: refund.currency,
			},
		});
	}
	if (refund.amount >= charge.amount || charge.amount <= 0) {
		return remaining;
	}
	return Math.min(Math.round((refund.amount * original.sale.totalMinor) / charge.amount), remaining);
}

function withdrawnPassCount(refund: Stripe.Refund): number | null {
	const scope = (refund.metadata?.rejection_reason ?? '').match(/^operator_pass_withdrawal:(.+)$/)?.[1];
	return scope && !scope.startsWith('all:') ? 1 : null;
}

function untaxedAtNet(
	taxLines: ReadonlyArray<BillingDocumentTaxLine>,
	lines: ReadonlyArray<SaleLine>,
): Array<BillingDocumentTaxLine> {
	const untaxedMinor = lines.filter((line) => line.taxMinor === 0).reduce((sum, line) => sum + line.amountMinor, 0);
	return taxLines.map((line) =>
		line.taxMinor === 0
			? {...line, ratePercent: null, taxableMinor: line.taxableMinor > 0 ? line.taxableMinor : untaxedMinor}
			: line,
	);
}

function checkoutFlow(session: Stripe.Checkout.Session): BillingDocumentFlow {
	if (session.metadata?.operator_pass === 'true') return 'operator_pass';
	if (session.metadata?.is_donation === 'true') return 'donation';
	if (session.metadata?.is_gift === 'true') return 'gift';
	return 'plutonium';
}