@voyant-travel/finance 0.119.5

package/dist/service-shared.js

@@ -0,0 +1,764 @@
+// agent-quality: file-size exception -- owner: finance; compatibility exports and shared service helpers stay co-located while the domain-operation service modules are split out.
+export { appendActionLedgerMutation, } from "@voyant-travel/action-ledger";
+export { actionMutationDetails } from "@voyant-travel/action-ledger/schema";
+export { bookingItems, bookings } from "@voyant-travel/bookings/schema";
+export { newId } from "@voyant-travel/db/lib/typeid";
+export { renderStructuredTemplate } from "@voyant-travel/utils/template-renderer";
+export { and, asc, desc, eq, gt, gte, ilike, inArray, isNotNull, lte, ne, or, sql, } from "drizzle-orm";
+export { resolveFxMoneyBaseAmount } from "./fx-money.js";
+export { isInvoiceNumberUniqueConstraintError } from "./invoice-number-errors.js";
+export { bookingGuarantees, bookingItemCommissions, bookingItemTaxLines, bookingPaymentSchedules, creditNoteLineItems, creditNotes, financeNotes, invoiceAttachments, invoiceExternalRefs, invoiceLineItems, invoiceNumberSeries, invoiceRenditions, invoices, invoiceTemplates, paymentAuthorizations, paymentCaptures, paymentInstruments, paymentSessions, payments, supplierInvoices, supplierPayments, taxClasses, taxPolicyProfiles, taxPolicyRules, taxRegimes, } from "./schema.js";
+export { recomputeSupplierInvoiceBalance } from "./service-supplier-invoices.js";
+import { actionMutationDetails } from "@voyant-travel/action-ledger/schema";
+import { bookings } from "@voyant-travel/bookings/schema";
+import { renderStructuredTemplate } from "@voyant-travel/utils/template-renderer";
+import { and, desc, eq, gt, ne, sql } from "drizzle-orm";
+import { resolveFxMoneyBaseAmount } from "./fx-money.js";
+import { bookingPaymentSchedules, creditNotes, invoices, payments, supplierInvoices, supplierPayments, } from "./schema.js";
+export { buildBookingCreateRejectedActionLedgerInput, buildBookingCreateSucceededActionLedgerInput, buildBookingGuaranteeCreateActionLedgerInput, buildBookingGuaranteeDeleteActionLedgerInput, buildBookingGuaranteeUpdateActionLedgerInput, buildBookingPaymentScheduleCreateActionLedgerInput, buildBookingPaymentScheduleDeleteActionLedgerInput, buildBookingPaymentScheduleUpdateActionLedgerInput, buildCreditNoteCreationActionLedgerInput, buildCreditNoteLineItemCreateActionLedgerInput, buildCreditNoteUpdateActionLedgerInput, buildInvoiceDeleteActionLedgerInput, buildInvoiceIssuedActionLedgerInput, buildInvoiceLineItemCreateActionLedgerInput, buildInvoiceLineItemDeleteActionLedgerInput, buildInvoiceLineItemUpdateActionLedgerInput, buildInvoiceUpdateActionLedgerInput, buildPaymentAuthorizationCreateActionLedgerInput, buildPaymentAuthorizationDeleteActionLedgerInput, buildPaymentAuthorizationUpdateActionLedgerInput, buildPaymentCaptureCreateActionLedgerInput, buildPaymentCaptureDeleteActionLedgerInput, buildPaymentCaptureUpdateActionLedgerInput, buildPaymentDeleteActionLedgerInput, buildPaymentInstrumentCreateActionLedgerInput, buildPaymentInstrumentDeleteActionLedgerInput, buildPaymentInstrumentUpdateActionLedgerInput, buildPaymentSessionCancelledActionLedgerInput, buildPaymentSessionCompletionActionLedgerInput, buildPaymentSessionCreateActionLedgerInput, buildPaymentSessionExpiredActionLedgerInput, buildPaymentSessionFailedActionLedgerInput, buildPaymentSessionRequiresRedirectActionLedgerInput, buildPaymentSessionUpdateActionLedgerInput, buildPaymentUpdateActionLedgerInput, buildRecordPaymentActionLedgerInput, buildSupplierPaymentCreateActionLedgerInput, buildSupplierPaymentUpdateActionLedgerInput, } from "./service-action-ledger.js";
+export class PaymentValidationError extends Error {
+    status;
+    code;
+    details;
+    constructor(message, details, options = {}) {
+        super(message);
+        this.name = "PaymentValidationError";
+        this.status = options.status ?? 400;
+        this.code = options.code ?? "invalid_request";
+        this.details = details;
+    }
+}
+export class InvoiceNumberAllocationError extends Error {
+    code;
+    scope;
+    seriesId;
+    constructor(code, details) {
+        super(code);
+        this.name = "InvoiceNumberAllocationError";
+        this.code = code;
+        this.scope = details.scope;
+        this.seriesId = details.seriesId;
+    }
+}
+export class ExternalInvoiceNumberSeriesCollisionError extends Error {
+    code = "external_invoice_number_series_code_conflict";
+    seriesCode;
+    provider;
+    scope;
+    existingProvider;
+    existingScope;
+    constructor(details) {
+        super(`Invoice number series code "${details.seriesCode}" already belongs to ${details.existingProvider ?? "a local series"} in scope "${details.existingScope}"`);
+        this.name = "ExternalInvoiceNumberSeriesCollisionError";
+        this.seriesCode = details.seriesCode;
+        this.provider = details.provider;
+        this.scope = details.scope;
+        this.existingProvider = details.existingProvider;
+        this.existingScope = details.existingScope;
+    }
+}
+export class InvoiceNumberConflictError extends Error {
+    code = "invoice_number_conflict";
+    invoiceNumber;
+    constructor(invoiceNumber) {
+        super("Invoice number already exists");
+        this.name = "InvoiceNumberConflictError";
+        this.invoiceNumber = invoiceNumber;
+    }
+}
+export class InvoiceFromBookingValidationError extends Error {
+    status = 400;
+    code = "invalid_invoice_from_booking";
+    details;
+    constructor(message, details) {
+        super(message);
+        this.name = "InvoiceFromBookingValidationError";
+        this.details = details;
+    }
+}
+export class InvoiceLineItemsPersistenceError extends Error {
+    code = "invoice_line_items_not_persisted";
+    invoiceId;
+    expectedCount;
+    actualCount;
+    constructor(invoiceId, expectedCount, actualCount) {
+        super("Invoice line items were not persisted");
+        this.name = "InvoiceLineItemsPersistenceError";
+        this.invoiceId = invoiceId;
+        this.expectedCount = expectedCount;
+        this.actualCount = actualCount;
+    }
+}
+export const PAYMENT_SCHEDULE_LINE_LABELS = {
+    deposit: "Deposit",
+    installment: "Installment",
+    balance: "Balance",
+    hold: "Hold",
+    other: "Payment schedule",
+};
+export function bookingItemToInvoiceLine(item, taxes, sortOrder) {
+    const quantity = Math.max(item.quantity, 1);
+    const totalCents = item.totalSellAmountCents ?? (item.unitSellAmountCents ?? 0) * Math.max(item.quantity, 1);
+    const firstTaxWithRate = taxes.find((tax) => tax.scope !== "withheld" && tax.rateBasisPoints != null);
+    return {
+        bookingItemId: item.id,
+        bookingPaymentScheduleId: null,
+        description: renderBookingItemInvoiceLineDescription(item),
+        quantity: item.quantity,
+        unitPriceCents: item.unitSellAmountCents ??
+            (item.totalSellAmountCents !== null && item.totalSellAmountCents !== undefined
+                ? Math.floor(item.totalSellAmountCents / quantity)
+                : 0),
+        totalCents,
+        taxAmountCents: 0,
+        taxRate: firstTaxWithRate?.rateBasisPoints != null
+            ? Math.round(firstTaxWithRate.rateBasisPoints / 100)
+            : null,
+        sortOrder,
+    };
+}
+export function renderBookingItemInvoiceLineDescription(item) {
+    const base = resolveBookingItemDisplayName(item) ?? item.title;
+    const dates = formatInvoiceLineDateRange(resolveBookingItemStartDate(item), resolveBookingItemEndDate(item));
+    return dates ? `${base} | ${dates}` : base;
+}
+export function bookingPaymentScheduleToInvoiceLine(booking, schedule, item, descriptionFormat = "schedule_first") {
+    const label = PAYMENT_SCHEDULE_LINE_LABELS[schedule.scheduleType];
+    const percent = getPaymentSchedulePercent(booking, schedule);
+    const head = percent != null && percent < 100 ? `${label} ${percent}%` : label;
+    const base = resolveBookingItemDisplayName(item) ?? `booking ${booking.bookingNumber}`;
+    const dates = formatInvoiceLineDateRange(item ? (resolveBookingItemStartDate(item) ?? booking.startDate) : booking.startDate, item ? (resolveBookingItemEndDate(item) ?? booking.endDate) : booking.endDate);
+    return {
+        bookingItemId: schedule.bookingItemId ?? null,
+        bookingPaymentScheduleId: schedule.id,
+        description: renderPaymentScheduleLineDescription({ base, dates, head, descriptionFormat }),
+        quantity: 1,
+        unitPriceCents: schedule.amountCents,
+        totalCents: schedule.amountCents,
+        taxAmountCents: 0,
+        taxRate: null,
+        sortOrder: 0,
+    };
+}
+export function renderPaymentScheduleLineDescription(input) {
+    switch (input.descriptionFormat) {
+        case "product_only":
+            return input.dates ? `${input.base} | ${input.dates}` : input.base;
+        case "product_first":
+            return input.dates
+                ? `${input.base} - ${input.head} | ${input.dates}`
+                : `${input.base} - ${input.head}`;
+        case "schedule_first":
+            return input.dates
+                ? `${input.head} ${input.base} | ${input.dates}`
+                : `${input.head} ${input.base}`;
+    }
+}
+export function resolvePaymentScheduleDisplayItem(schedule, items) {
+    if (schedule.bookingItemId) {
+        return items.find((item) => item.id === schedule.bookingItemId);
+    }
+    const namedItems = items.filter((item) => resolveBookingItemDisplayName(item));
+    return [...(namedItems.length > 0 ? namedItems : items)].sort(compareBookingItemsForScheduleDisplay)[0];
+}
+export function resolveBookingItemDisplayName(item) {
+    return (item?.productNameSnapshot?.trim() || item?.productName?.trim() || item?.title?.trim() || null);
+}
+export function resolveBookingItemStartDate(item) {
+    return item.startDate ?? item.serviceDate ?? item.startsAt;
+}
+export function resolveBookingItemEndDate(item) {
+    return item.endDate ?? item.endsAt ?? item.serviceDate ?? resolveBookingItemStartDate(item);
+}
+export function compareBookingItemsForScheduleDisplay(left, right) {
+    return (compareNullableStrings(resolveBookingItemDateSortKey(left), resolveBookingItemDateSortKey(right)) ||
+        compareNullableStrings(resolveBookingItemDisplayName(left), resolveBookingItemDisplayName(right)) ||
+        left.id.localeCompare(right.id));
+}
+export function resolveBookingItemDateSortKey(item) {
+    return (toDateOnly(resolveBookingItemStartDate(item)) ?? toDateOnly(resolveBookingItemEndDate(item)));
+}
+export function compareNullableStrings(left, right) {
+    if (left && right)
+        return left.localeCompare(right);
+    if (left)
+        return -1;
+    if (right)
+        return 1;
+    return 0;
+}
+export function getPaymentSchedulePercent(booking, schedule) {
+    if (!booking.sellAmountCents || booking.sellAmountCents <= 0)
+        return null;
+    return Math.round((schedule.amountCents / booking.sellAmountCents) * 100);
+}
+export function formatInvoiceLineDateRange(startDate, endDate) {
+    const start = toDateOnly(startDate);
+    const end = toDateOnly(endDate);
+    if (!start)
+        return null;
+    if (!end || end === start)
+        return start;
+    return `${start} - ${end}`;
+}
+export function toDateOnly(value) {
+    if (!value)
+        return null;
+    if (value instanceof Date)
+        return value.toISOString().slice(0, 10);
+    return value.slice(0, 10);
+}
+export function invoiceFromBookingOverrideLineItems(lineItems) {
+    return lineItems.map((line, sortOrder) => {
+        const lineSubtotalCents = line.quantity * line.unitAmountCents;
+        const taxAmountCents = line.taxAmountCents ??
+            (line.taxRateBps != null ? Math.round((lineSubtotalCents * line.taxRateBps) / 10_000) : 0);
+        return {
+            bookingItemId: null,
+            bookingPaymentScheduleId: null,
+            description: line.description,
+            quantity: line.quantity,
+            unitPriceCents: line.unitAmountCents,
+            totalCents: lineSubtotalCents,
+            taxAmountCents,
+            taxRate: line.taxRateBps != null ? Math.round(line.taxRateBps / 100) : null,
+            sortOrder,
+        };
+    });
+}
+export async function resolveInvoiceLineDescriptions(lineItems, context) {
+    if (!context.descriptionResolver)
+        return lineItems;
+    const scheduleItem = context.paymentSchedule
+        ? resolvePaymentScheduleDisplayItem(context.paymentSchedule, context.items)
+        : undefined;
+    return Promise.all(lineItems.map(async (line) => ({
+        ...line,
+        description: (await context.descriptionResolver?.({
+            booking: context.booking,
+            schedule: context.paymentSchedule ?? undefined,
+            item: context.paymentSchedule
+                ? scheduleItem
+                : context.items.find((item) => item.id === line.bookingItemId),
+            line,
+        })) ?? line.description,
+    })));
+}
+export async function resolveInvoiceFromBookingDueDate(data, bookingData, runtime) {
+    if (!runtime.invoiceDueDateResolver)
+        return data.dueDate;
+    const dueDate = await runtime.invoiceDueDateResolver({
+        issueDate: data.issueDate,
+        dueDate: data.dueDate,
+        invoiceType: data.invoiceType ?? "invoice",
+        booking: bookingData.booking,
+        bookingPaymentSchedule: bookingData.paymentSchedule ?? bookingData.dueDatePaymentSchedule ?? undefined,
+    });
+    if (!dueDate) {
+        throw new InvoiceFromBookingValidationError("Invoice due date resolver returned an empty date", {
+            issueDate: data.issueDate,
+            dueDate: data.dueDate,
+        });
+    }
+    return dueDate;
+}
+export function assertInvoiceFromBookingOverrideTotals(data, totals) {
+    if (data.subtotalCents !== undefined && data.subtotalCents !== totals.subtotalCents) {
+        throw new InvoiceFromBookingValidationError("Invoice subtotal does not match line items", {
+            expectedSubtotalCents: totals.subtotalCents,
+            subtotalCents: data.subtotalCents,
+        });
+    }
+    if (data.taxCents !== undefined && data.taxCents !== totals.taxCents) {
+        throw new InvoiceFromBookingValidationError("Invoice tax does not match line items", {
+            expectedTaxCents: totals.taxCents,
+            taxCents: data.taxCents,
+        });
+    }
+    if (data.totalCents !== undefined && data.totalCents !== totals.totalCents) {
+        throw new InvoiceFromBookingValidationError("Invoice total does not match subtotal plus tax", {
+            expectedTotalCents: totals.totalCents,
+            totalCents: data.totalCents,
+        });
+    }
+}
+export function normalizeCurrencyCode(value) {
+    return value?.trim().toUpperCase() ?? null;
+}
+export function invoiceFromBookingExternalRefValues(invoiceId, refs) {
+    return refs.map((ref) => ({
+        invoiceId,
+        provider: ref.provider,
+        externalId: ref.externalId ?? null,
+        externalNumber: ref.externalNumber ?? null,
+        externalUrl: ref.externalUrl ?? null,
+        status: ref.status ?? null,
+        metadata: ref.metadata ?? null,
+        syncedAt: toTimestamp(ref.syncedAt),
+        syncError: ref.syncError ?? null,
+    }));
+}
+export function resolveBookingInvoiceBaseAmount(booking, invoiceCurrency, amountCents) {
+    if (!booking.baseCurrency)
+        return null;
+    if (invoiceCurrency === booking.baseCurrency)
+        return amountCents;
+    if (invoiceCurrency !== booking.sellCurrency || booking.baseSellAmountCents == null)
+        return null;
+    if (!booking.sellAmountCents || booking.sellAmountCents <= 0)
+        return booking.baseSellAmountCents;
+    return Math.round((amountCents / booking.sellAmountCents) * booking.baseSellAmountCents);
+}
+export function toTimestamp(value) {
+    return value ? new Date(value) : null;
+}
+export function toDateString(value) {
+    return value.toISOString().slice(0, 10);
+}
+export function readStringMetadata(value, key) {
+    if (value == null || typeof value !== "object")
+        return null;
+    const candidate = value[key];
+    return typeof candidate === "string" && candidate.trim() ? candidate : null;
+}
+export function startOfUtcDay(value) {
+    return new Date(Date.UTC(value.getUTCFullYear(), value.getUTCMonth(), value.getUTCDate()));
+}
+export function parseDateString(value) {
+    return new Date(`${value}T00:00:00.000Z`);
+}
+export function derivePaymentSessionTarget(input) {
+    const explicitTarget = "target" in input ? input.target : undefined;
+    if (explicitTarget) {
+        switch (explicitTarget.type) {
+            case "booking":
+                return { targetType: "booking", targetId: explicitTarget.bookingId };
+            case "invoice":
+                return { targetType: "invoice", targetId: explicitTarget.invoiceId };
+            case "booking_payment_schedule":
+                return {
+                    targetType: "booking_payment_schedule",
+                    targetId: explicitTarget.bookingPaymentScheduleId,
+                };
+            case "booking_guarantee":
+                return {
+                    targetType: "booking_guarantee",
+                    targetId: explicitTarget.bookingGuaranteeId,
+                };
+            case "flight_order":
+                return { targetType: "flight_order", targetId: explicitTarget.flightOrderId };
+            case "legacy_order":
+                return { targetType: "order", targetId: explicitTarget.legacyOrderId };
+            case "program":
+                return { targetType: "other", targetId: explicitTarget.programId };
+            case "supplier_settlement":
+                return { targetType: "other", targetId: explicitTarget.supplierSettlementId };
+            case "channel_settlement":
+                return { targetType: "other", targetId: explicitTarget.channelSettlementId };
+            case "provider_reference":
+                return { targetType: "other", targetId: explicitTarget.reference };
+        }
+    }
+    const legacyOrderId = input.legacyOrderId ?? null;
+    if (input.targetType && input.targetType !== "other") {
+        return {
+            targetType: input.targetType,
+            targetId: input.targetId ??
+                (input.targetType === "booking"
+                    ? input.bookingId
+                    : input.targetType === "order"
+                        ? legacyOrderId
+                        : input.targetType === "invoice"
+                            ? input.invoiceId
+                            : input.targetType === "booking_payment_schedule"
+                                ? input.bookingPaymentScheduleId
+                                : input.targetType === "booking_guarantee"
+                                    ? input.bookingGuaranteeId
+                                    : input.targetId),
+        };
+    }
+    if (input.bookingPaymentScheduleId) {
+        return {
+            targetType: "booking_payment_schedule",
+            targetId: input.bookingPaymentScheduleId,
+        };
+    }
+    if (input.bookingGuaranteeId) {
+        return { targetType: "booking_guarantee", targetId: input.bookingGuaranteeId };
+    }
+    if (input.invoiceId) {
+        return { targetType: "invoice", targetId: input.invoiceId };
+    }
+    if (legacyOrderId) {
+        return { targetType: "order", targetId: legacyOrderId };
+    }
+    if (input.bookingId) {
+        return { targetType: "booking", targetId: input.bookingId };
+    }
+    return {
+        targetType: (input.targetType ?? "other"),
+        targetId: input.targetId ?? null,
+    };
+}
+// ============================================================================
+// Invoice number allocation (transactional)
+// ============================================================================
+export function currentPeriodBoundary(strategy, now) {
+    if (strategy === "never")
+        return null;
+    if (strategy === "annual") {
+        return new Date(Date.UTC(now.getUTCFullYear(), 0, 1));
+    }
+    // monthly
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+}
+export function formatNumber(prefix, separator, padLength, sequence) {
+    const padded = String(sequence).padStart(padLength, "0");
+    return `${prefix}${separator}${padded}`;
+}
+export function invoiceScopeForType(invoiceType) {
+    return invoiceType === "proforma" ? "proforma" : "invoice";
+}
+export function pendingExternalInvoiceNumber(scope) {
+    const uuid = globalThis.crypto?.randomUUID?.().replace(/-/g, "") ?? randomId();
+    return `PENDING-${scope.toUpperCase()}-${uuid.slice(0, 32)}`;
+}
+export function randomId() {
+    return `${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`.padEnd(32, "0");
+}
+export function renderInvoiceBody(body, bodyFormat, variables) {
+    return renderStructuredTemplate(body, bodyFormat, variables);
+}
+export async function paginate(rowsQuery, countQuery, limit, offset) {
+    const [data, countResult] = await Promise.all([rowsQuery, countQuery]);
+    return { data, total: countResult[0]?.total ?? 0, limit, offset };
+}
+export function buildBookingPaymentSchedulePaidEvent(schedule, session, paymentId) {
+    return {
+        bookingId: schedule.bookingId,
+        bookingPaymentScheduleId: schedule.id,
+        paymentSessionId: session.id,
+        paymentId,
+        scheduleType: schedule.scheduleType,
+        amountCents: schedule.amountCents,
+        currency: schedule.currency,
+        provider: session.provider,
+    };
+}
+export function buildPaymentCompletedEvent(session) {
+    return {
+        paymentSessionId: session.id,
+        targetType: session.targetType,
+        targetId: session.targetId,
+        bookingId: session.bookingId,
+        legacyOrderId: session.orderId,
+        invoiceId: session.invoiceId,
+        bookingPaymentScheduleId: session.bookingPaymentScheduleId,
+        bookingGuaranteeId: session.bookingGuaranteeId,
+        amountCents: session.amountCents,
+        currency: session.currency,
+        provider: session.provider,
+    };
+}
+/**
+ * Normalize `db.execute(sql)` results across drizzle drivers.
+ * `drizzle-orm/postgres-js` returns rows directly (an array), while
+ * `drizzle-orm/node-postgres` (used by the operator starter against a
+ * local pg server) and `drizzle-orm/neon-serverless` return pg's
+ * `QueryResult<T>` wrapper with `.rows`. Casting to `Array<T>` and
+ * calling `.map` blows up under the wrapper shape — surface the rows
+ * regardless of which driver is bound.
+ */
+export function toRows(result) {
+    if (Array.isArray(result))
+        return result;
+    if (result && typeof result === "object" && "rows" in result) {
+        const rows = result.rows;
+        return Array.isArray(rows) ? rows : [];
+    }
+    return [];
+}
+export function mapRawPayment(row) {
+    // Person display name: "First Last", trimmed. Falls back to null when both
+    // halves are missing so the UI can swap to organization or hide the field.
+    const personName = row.person_first_name || row.person_last_name
+        ? `${row.person_first_name ?? ""} ${row.person_last_name ?? ""}`.trim() || null
+        : null;
+    return {
+        kind: row.kind,
+        id: row.id,
+        invoiceId: row.invoice_id,
+        invoiceNumber: row.invoice_number,
+        bookingId: row.booking_id,
+        bookingNumber: row.booking_number,
+        supplierId: row.supplier_id,
+        supplierName: row.supplier_name,
+        personId: row.person_id,
+        personName,
+        organizationId: row.organization_id,
+        organizationName: row.organization_name,
+        amountCents: row.amount_cents,
+        currency: row.currency,
+        baseCurrency: row.base_currency,
+        baseAmountCents: row.base_amount_cents,
+        paymentMethod: row.payment_method,
+        status: row.status,
+        referenceNumber: row.reference_number,
+        paymentDate: row.payment_date,
+        notes: row.notes,
+        createdAt: row.created_at instanceof Date ? row.created_at : new Date(row.created_at),
+        updatedAt: row.updated_at instanceof Date ? row.updated_at : new Date(row.updated_at),
+    };
+}
+export function paymentSettlementAmountSql(invoiceCurrency) {
+    return sql `
+    coalesce(
+      sum(
+        case
+          when ${payments.currency} = ${invoiceCurrency} then ${payments.amountCents}
+          when ${payments.baseCurrency} = ${invoiceCurrency} then coalesce(${payments.baseAmountCents}, 0)
+          else 0
+        end
+      ),
+      0
+    )::int
+  `;
+}
+export async function recomputeInvoiceTotalsAfterPaymentChange(tx, invoice) {
+    const [sumResult] = await tx
+        .select({ total: paymentSettlementAmountSql(invoice.currency) })
+        .from(payments)
+        .where(and(eq(payments.invoiceId, invoice.id), eq(payments.status, "completed")));
+    const paidCents = sumResult?.total ?? 0;
+    const balanceDueCents = Math.max(0, invoice.totalCents - paidCents);
+    let nextStatus = invoice.status;
+    if (invoice.status !== "void" && invoice.status !== "draft") {
+        if (paidCents >= invoice.totalCents && invoice.totalCents > 0) {
+            nextStatus = "paid";
+        }
+        else if (paidCents > 0) {
+            nextStatus = "partially_paid";
+        }
+        else if (invoice.status === "paid" || invoice.status === "partially_paid") {
+            nextStatus = "issued";
+        }
+    }
+    await tx
+        .update(invoices)
+        .set({ paidCents, balanceDueCents, status: nextStatus, updatedAt: new Date() })
+        .where(eq(invoices.id, invoice.id));
+}
+export async function assertInvoiceAcceptsNewPayment(db, invoice) {
+    if (invoice.status !== "void")
+        return;
+    let redirectInvoiceId = null;
+    let redirectInvoiceNumber = null;
+    if (invoice.invoiceType === "proforma") {
+        const [successor] = await db
+            .select({ id: invoices.id, invoiceNumber: invoices.invoiceNumber })
+            .from(invoices)
+            .where(eq(invoices.convertedFromInvoiceId, invoice.id))
+            .limit(1);
+        redirectInvoiceId = successor?.id ?? null;
+        redirectInvoiceNumber = successor?.invoiceNumber ?? null;
+    }
+    throw new PaymentValidationError(redirectInvoiceId
+        ? `This proforma was converted to invoice ${redirectInvoiceNumber ?? redirectInvoiceId}; record the payment there instead.`
+        : `Cannot record payment against voided invoice ${invoice.id}.`, {
+        invoiceId: invoice.id,
+        ...(redirectInvoiceId ? { redirectInvoiceId, redirectInvoiceNumber } : {}),
+    }, { status: 409, code: "invoice_void" });
+}
+export function assertPaymentCanSettleInvoice(invoiceCurrency, data) {
+    if (data.status !== "completed" || data.currency === invoiceCurrency) {
+        return;
+    }
+    if (data.baseCurrency === invoiceCurrency && data.baseAmountCents && data.baseAmountCents > 0) {
+        return;
+    }
+    throw new PaymentValidationError("Completed cross-currency payments require a base amount in the invoice currency", {
+        invoiceCurrency,
+        paymentCurrency: data.currency,
+        fields: ["baseCurrency", "baseAmountCents"],
+    });
+}
+export async function getPaymentFromReplayedLedgerEntry(db, actionId) {
+    const [detail] = await db
+        .select({ commandResultRef: actionMutationDetails.commandResultRef })
+        .from(actionMutationDetails)
+        .where(eq(actionMutationDetails.actionId, actionId))
+        .limit(1);
+    const paymentId = parsePaymentCommandResultRef(detail?.commandResultRef ?? null);
+    if (!paymentId) {
+        throw new Error(`Replayed payment ledger entry ${actionId} did not reference a payment`);
+    }
+    const [payment] = await db.select().from(payments).where(eq(payments.id, paymentId)).limit(1);
+    if (!payment) {
+        throw new Error(`Replayed payment ledger entry ${actionId} referenced missing payment ${paymentId}`);
+    }
+    return payment;
+}
+export function parsePaymentCommandResultRef(commandResultRef) {
+    const prefix = "payment:";
+    if (!commandResultRef?.startsWith(prefix))
+        return null;
+    const paymentId = commandResultRef.slice(prefix.length).trim();
+    return paymentId ? paymentId : null;
+}
+export function shouldNormalizeBaseAmount(data) {
+    return (data.amountCents !== undefined ||
+        data.currency !== undefined ||
+        data.baseCurrency !== undefined ||
+        data.baseAmountCents !== undefined ||
+        data.fxRateSetId !== undefined ||
+        data.paymentDate !== undefined);
+}
+export async function resolveSupplierPaymentUpdateData(db, id, data, runtime) {
+    const [existing] = await db
+        .select()
+        .from(supplierPayments)
+        .where(eq(supplierPayments.id, id))
+        .limit(1);
+    if (!existing)
+        return null;
+    if (!shouldNormalizeBaseAmount(data))
+        return data;
+    const bookingId = data.bookingId ?? existing.bookingId;
+    const supplierInvoiceId = data.supplierInvoiceId ?? existing.supplierInvoiceId;
+    let targetBaseCurrency = null;
+    let fallbackFxRateSetId = null;
+    if (bookingId) {
+        const [booking] = await db.select().from(bookings).where(eq(bookings.id, bookingId)).limit(1);
+        targetBaseCurrency = booking?.baseCurrency ?? null;
+        fallbackFxRateSetId = booking?.fxRateSetId ?? null;
+    }
+    else if (supplierInvoiceId) {
+        const [invoice] = await db
+            .select()
+            .from(supplierInvoices)
+            .where(eq(supplierInvoices.id, supplierInvoiceId))
+            .limit(1);
+        targetBaseCurrency = invoice?.baseCurrency ?? null;
+        fallbackFxRateSetId = invoice?.fxRateSetId ?? null;
+    }
+    const normalized = await resolveFxMoneyBaseAmount(db, {
+        amountCents: data.amountCents ?? existing.amountCents,
+        currency: data.currency ?? existing.currency,
+        baseCurrency: data.baseCurrency ?? existing.baseCurrency,
+        baseAmountCents: data.baseAmountCents ?? null,
+        fxRateSetId: data.fxRateSetId ?? existing.fxRateSetId,
+    }, {
+        ...runtime,
+        targetBaseCurrency,
+        fallbackFxRateSetId,
+        date: data.paymentDate ?? existing.paymentDate,
+    });
+    return {
+        ...data,
+        baseCurrency: normalized.baseCurrency ?? null,
+        baseAmountCents: normalized.baseAmountCents ?? null,
+        fxRateSetId: normalized.fxRateSetId ?? null,
+    };
+}
+export async function resolveCreditNoteUpdateData(db, id, data, runtime) {
+    const [existing] = await db.select().from(creditNotes).where(eq(creditNotes.id, id)).limit(1);
+    if (!existing)
+        return null;
+    if (!shouldNormalizeBaseAmount(data))
+        return data;
+    const [invoice] = await db
+        .select()
+        .from(invoices)
+        .where(eq(invoices.id, existing.invoiceId))
+        .limit(1);
+    if (!invoice)
+        return null;
+    const normalized = await resolveFxMoneyBaseAmount(db, {
+        amountCents: data.amountCents ?? existing.amountCents,
+        currency: data.currency ?? existing.currency,
+        baseCurrency: data.baseCurrency ?? existing.baseCurrency,
+        baseAmountCents: data.baseAmountCents ?? null,
+        fxRateSetId: data.fxRateSetId ?? existing.fxRateSetId,
+    }, {
+        ...runtime,
+        targetBaseCurrency: invoice.currency,
+        fallbackFxRateSetId: invoice.fxRateSetId ?? null,
+        date: new Date(),
+    });
+    return {
+        ...data,
+        baseCurrency: normalized.baseCurrency ?? null,
+        baseAmountCents: normalized.baseAmountCents ?? null,
+        fxRateSetId: normalized.fxRateSetId ?? null,
+    };
+}
+export async function resolveInvoiceForPaymentSession(db, session) {
+    if (session.invoiceId) {
+        const [invoice] = await db.select().from(invoices).where(eq(invoices.id, session.invoiceId));
+        return invoice ?? null;
+    }
+    if (!session.bookingPaymentScheduleId) {
+        return null;
+    }
+    const [schedule] = await db
+        .select()
+        .from(bookingPaymentSchedules)
+        .where(eq(bookingPaymentSchedules.id, session.bookingPaymentScheduleId))
+        .limit(1);
+    if (!schedule) {
+        return null;
+    }
+    const [invoice] = await db
+        .select()
+        .from(invoices)
+        .where(and(eq(invoices.bookingId, schedule.bookingId), eq(invoices.currency, schedule.currency), ne(invoices.status, "void"), gt(invoices.balanceDueCents, 0)))
+        .orderBy(desc(invoices.createdAt))
+        .limit(1);
+    return invoice ?? null;
+}
+export async function assertBookingPaymentScheduleHasPaymentCoverage(db, schedule) {
+    // Sum every completed payment recorded against this booking's invoices
+    // and convert to the schedule's currency:
+    //   - same-currency payments contribute their `amountCents`
+    //   - cross-currency payments contribute their `baseAmountCents` when
+    //     `baseCurrency` matches the schedule (the BookingPaymentsSummary
+    //     "FX equivalent" column already exposes this conversion to the
+    //     operator, so reusing it here keeps the math consistent)
+    // We then subtract any *other* schedules already flagged paid in the
+    // same currency, so the operator can't double-count payments by
+    // marking multiple schedules paid when only one schedule's worth of
+    // money actually came in.
+    const paymentRows = await db
+        .select({
+        amountCents: payments.amountCents,
+        currency: payments.currency,
+        baseCurrency: payments.baseCurrency,
+        baseAmountCents: payments.baseAmountCents,
+    })
+        .from(payments)
+        .innerJoin(invoices, eq(payments.invoiceId, invoices.id))
+        .where(and(eq(invoices.bookingId, schedule.bookingId), eq(payments.status, "completed")));
+    const totalPaidInScheduleCurrency = paymentRows.reduce((sum, payment) => {
+        if (payment.currency === schedule.currency)
+            return sum + payment.amountCents;
+        if (payment.baseCurrency === schedule.currency && typeof payment.baseAmountCents === "number") {
+            return sum + payment.baseAmountCents;
+        }
+        return sum;
+    }, 0);
+    const otherPaidSchedules = await db
+        .select({ amountCents: bookingPaymentSchedules.amountCents })
+        .from(bookingPaymentSchedules)
+        .where(and(eq(bookingPaymentSchedules.bookingId, schedule.bookingId), eq(bookingPaymentSchedules.status, "paid"), eq(bookingPaymentSchedules.currency, schedule.currency), ne(bookingPaymentSchedules.id, schedule.id)));
+    const alreadyClaimed = otherPaidSchedules.reduce((sum, row) => sum + row.amountCents, 0);
+    const availableCoverage = totalPaidInScheduleCurrency - alreadyClaimed;
+    if (availableCoverage < schedule.amountCents) {
+        throw new PaymentValidationError("Cannot mark booking payment schedule as paid without linked completed payment coverage", {
+            scheduleId: schedule.id,
+            bookingId: schedule.bookingId,
+            requiredCents: schedule.amountCents,
+            coveredCents: availableCoverage,
+            currency: schedule.currency,
+        });
+    }
+}