@voyant-travel/finance 0.119.5

package/dist/service-payment-sessions.js

@@ -0,0 +1,280 @@
+import { and, appendActionLedgerMutation, buildPaymentSessionCancelledActionLedgerInput, buildPaymentSessionCreateActionLedgerInput, buildPaymentSessionExpiredActionLedgerInput, buildPaymentSessionFailedActionLedgerInput, buildPaymentSessionRequiresRedirectActionLedgerInput, buildPaymentSessionUpdateActionLedgerInput, derivePaymentSessionTarget, desc, eq, paginate, paymentSessions, sql, toTimestamp, } from "./service-shared.js";
+function derivePaymentSessionTargetColumns(data) {
+    const explicitTarget = "target" in data ? data.target : undefined;
+    if (!explicitTarget)
+        return {};
+    switch (explicitTarget.type) {
+        case "booking":
+            return { bookingId: explicitTarget.bookingId };
+        case "invoice":
+            return { invoiceId: explicitTarget.invoiceId };
+        case "booking_payment_schedule":
+            return { bookingPaymentScheduleId: explicitTarget.bookingPaymentScheduleId };
+        case "booking_guarantee":
+            return { bookingGuaranteeId: explicitTarget.bookingGuaranteeId };
+        case "legacy_order":
+            return { orderId: explicitTarget.legacyOrderId };
+        default:
+            return {};
+    }
+}
+export const financePaymentSessionService = {
+    async listPaymentSessions(db, query) {
+        const conditions = [];
+        if (query.bookingId)
+            conditions.push(eq(paymentSessions.bookingId, query.bookingId));
+        if (query.legacyOrderId)
+            conditions.push(eq(paymentSessions.orderId, query.legacyOrderId));
+        if (query.invoiceId)
+            conditions.push(eq(paymentSessions.invoiceId, query.invoiceId));
+        if (query.bookingPaymentScheduleId) {
+            conditions.push(eq(paymentSessions.bookingPaymentScheduleId, query.bookingPaymentScheduleId));
+        }
+        if (query.bookingGuaranteeId) {
+            conditions.push(eq(paymentSessions.bookingGuaranteeId, query.bookingGuaranteeId));
+        }
+        if (query.targetType)
+            conditions.push(eq(paymentSessions.targetType, query.targetType));
+        if (query.status)
+            conditions.push(eq(paymentSessions.status, query.status));
+        if (query.provider)
+            conditions.push(eq(paymentSessions.provider, query.provider));
+        if (query.providerSessionId) {
+            conditions.push(eq(paymentSessions.providerSessionId, query.providerSessionId));
+        }
+        if (query.providerPaymentId) {
+            conditions.push(eq(paymentSessions.providerPaymentId, query.providerPaymentId));
+        }
+        if (query.externalReference) {
+            conditions.push(eq(paymentSessions.externalReference, query.externalReference));
+        }
+        if (query.clientReference) {
+            conditions.push(eq(paymentSessions.clientReference, query.clientReference));
+        }
+        if (query.idempotencyKey) {
+            conditions.push(eq(paymentSessions.idempotencyKey, query.idempotencyKey));
+        }
+        const where = conditions.length ? and(...conditions) : undefined;
+        return paginate(db
+            .select()
+            .from(paymentSessions)
+            .where(where)
+            .limit(query.limit)
+            .offset(query.offset)
+            .orderBy(desc(paymentSessions.createdAt)), db.select({ total: sql `count(*)::int` }).from(paymentSessions).where(where), query.limit, query.offset);
+    },
+    async getPaymentSessionById(db, id) {
+        const [row] = await db.select().from(paymentSessions).where(eq(paymentSessions.id, id)).limit(1);
+        return row ?? null;
+    },
+    async createPaymentSession(db, data, runtime = {}) {
+        if (data.idempotencyKey) {
+            const [existing] = await db
+                .select()
+                .from(paymentSessions)
+                .where(eq(paymentSessions.idempotencyKey, data.idempotencyKey))
+                .limit(1);
+            if (existing) {
+                return existing;
+            }
+        }
+        const target = derivePaymentSessionTarget(data);
+        const targetColumns = derivePaymentSessionTargetColumns(data);
+        const { legacyOrderId, target: _explicitTarget, provenance: _provenance, ...sessionData } = data;
+        const resolvedLegacyOrderId = legacyOrderId ?? null;
+        const createSession = (writer) => writer
+            .insert(paymentSessions)
+            .values({
+            ...sessionData,
+            ...targetColumns,
+            ...target,
+            orderId: targetColumns.orderId ?? resolvedLegacyOrderId,
+            paymentInstrumentId: data.paymentInstrumentId ?? null,
+            paymentAuthorizationId: data.paymentAuthorizationId ?? null,
+            paymentCaptureId: data.paymentCaptureId ?? null,
+            paymentId: data.paymentId ?? null,
+            completedAt: toTimestamp(data.completedAt),
+            failedAt: toTimestamp(data.failedAt),
+            cancelledAt: toTimestamp(data.cancelledAt),
+            expiredAt: toTimestamp(data.expiredAt),
+            expiresAt: toTimestamp(data.expiresAt),
+        })
+            .returning();
+        const actionLedgerContext = runtime.actionLedgerContext;
+        if (actionLedgerContext) {
+            const [row] = await db.transaction(async (tx) => {
+                const created = await createSession(tx);
+                if (created[0]) {
+                    await appendActionLedgerMutation(tx, await buildPaymentSessionCreateActionLedgerInput(actionLedgerContext, { session: created[0] }, { authorizationSource: runtime.actionLedgerAuthorizationSource }));
+                }
+                return created;
+            });
+            return row ?? null;
+        }
+        const [row] = await createSession(db);
+        return row ?? null;
+    },
+    async updatePaymentSession(db, id, data, runtime = {}) {
+        const target = derivePaymentSessionTarget(data);
+        const targetColumns = derivePaymentSessionTargetColumns(data);
+        const { legacyOrderId, target: _explicitTarget, provenance: _provenance, ...sessionData } = data;
+        const resolvedLegacyOrderId = legacyOrderId;
+        const updateSession = (writer) => writer
+            .update(paymentSessions)
+            .set({
+            ...sessionData,
+            ...targetColumns,
+            ...target,
+            orderId: targetColumns.orderId ??
+                (resolvedLegacyOrderId === undefined ? undefined : (resolvedLegacyOrderId ?? null)),
+            paymentInstrumentId: data.paymentInstrumentId === undefined ? undefined : (data.paymentInstrumentId ?? null),
+            paymentAuthorizationId: data.paymentAuthorizationId === undefined
+                ? undefined
+                : (data.paymentAuthorizationId ?? null),
+            paymentCaptureId: data.paymentCaptureId === undefined ? undefined : (data.paymentCaptureId ?? null),
+            paymentId: data.paymentId === undefined ? undefined : (data.paymentId ?? null),
+            completedAt: data.completedAt === undefined ? undefined : toTimestamp(data.completedAt),
+            failedAt: data.failedAt === undefined ? undefined : toTimestamp(data.failedAt),
+            cancelledAt: data.cancelledAt === undefined ? undefined : toTimestamp(data.cancelledAt),
+            expiredAt: data.expiredAt === undefined ? undefined : toTimestamp(data.expiredAt),
+            expiresAt: data.expiresAt === undefined ? undefined : toTimestamp(data.expiresAt),
+            updatedAt: new Date(),
+        })
+            .where(eq(paymentSessions.id, id))
+            .returning();
+        const actionLedgerContext = runtime.actionLedgerContext;
+        if (actionLedgerContext) {
+            const [row] = await db.transaction(async (tx) => {
+                const updated = await updateSession(tx);
+                if (updated[0]) {
+                    await appendActionLedgerMutation(tx, buildPaymentSessionUpdateActionLedgerInput(actionLedgerContext, { session: updated[0], changes: data }, { authorizationSource: runtime.actionLedgerAuthorizationSource }));
+                }
+                return updated;
+            });
+            return row ?? null;
+        }
+        const [row] = await updateSession(db);
+        return row ?? null;
+    },
+    async markPaymentSessionRequiresRedirect(db, id, data, runtime = {}) {
+        const markRequiresRedirect = (writer) => writer
+            .update(paymentSessions)
+            .set({
+            status: "requires_redirect",
+            provider: data.provider ?? undefined,
+            providerSessionId: data.providerSessionId ?? undefined,
+            providerPaymentId: data.providerPaymentId ?? undefined,
+            externalReference: data.externalReference ?? undefined,
+            redirectUrl: data.redirectUrl,
+            returnUrl: data.returnUrl ?? undefined,
+            cancelUrl: data.cancelUrl ?? undefined,
+            callbackUrl: data.callbackUrl ?? undefined,
+            expiresAt: data.expiresAt === undefined ? undefined : toTimestamp(data.expiresAt),
+            providerPayload: data.providerPayload ?? undefined,
+            metadata: data.metadata ?? undefined,
+            notes: data.notes ?? undefined,
+            updatedAt: new Date(),
+        })
+            .where(eq(paymentSessions.id, id))
+            .returning();
+        const actionLedgerContext = runtime.actionLedgerContext;
+        if (actionLedgerContext) {
+            const [row] = await db.transaction(async (tx) => {
+                const updated = await markRequiresRedirect(tx);
+                if (updated[0]) {
+                    await appendActionLedgerMutation(tx, buildPaymentSessionRequiresRedirectActionLedgerInput(actionLedgerContext, { session: updated[0], changes: data }, { authorizationSource: runtime.actionLedgerAuthorizationSource }));
+                }
+                return updated;
+            });
+            return row ?? null;
+        }
+        const [row] = await markRequiresRedirect(db);
+        return row ?? null;
+    },
+    async failPaymentSession(db, id, data, runtime = {}) {
+        const failSession = (writer) => writer
+            .update(paymentSessions)
+            .set({
+            status: "failed",
+            providerSessionId: data.providerSessionId ?? undefined,
+            providerPaymentId: data.providerPaymentId ?? undefined,
+            externalReference: data.externalReference ?? undefined,
+            failureCode: data.failureCode ?? undefined,
+            failureMessage: data.failureMessage ?? undefined,
+            failedAt: new Date(),
+            providerPayload: data.providerPayload ?? undefined,
+            metadata: data.metadata ?? undefined,
+            notes: data.notes ?? undefined,
+            updatedAt: new Date(),
+        })
+            .where(eq(paymentSessions.id, id))
+            .returning();
+        const actionLedgerContext = runtime.actionLedgerContext;
+        if (actionLedgerContext) {
+            const [row] = await db.transaction(async (tx) => {
+                const updated = await failSession(tx);
+                if (updated[0]) {
+                    await appendActionLedgerMutation(tx, buildPaymentSessionFailedActionLedgerInput(actionLedgerContext, { session: updated[0], changes: data }, { authorizationSource: runtime.actionLedgerAuthorizationSource }));
+                }
+                return updated;
+            });
+            return row ?? null;
+        }
+        const [row] = await failSession(db);
+        return row ?? null;
+    },
+    async cancelPaymentSession(db, id, data, runtime = {}) {
+        const cancelSession = (writer) => writer
+            .update(paymentSessions)
+            .set({
+            status: "cancelled",
+            cancelledAt: data.cancelledAt ? toTimestamp(data.cancelledAt) : new Date(),
+            providerPayload: data.providerPayload ?? undefined,
+            metadata: data.metadata ?? undefined,
+            notes: data.notes ?? undefined,
+            updatedAt: new Date(),
+        })
+            .where(eq(paymentSessions.id, id))
+            .returning();
+        const actionLedgerContext = runtime.actionLedgerContext;
+        if (actionLedgerContext) {
+            const [row] = await db.transaction(async (tx) => {
+                const updated = await cancelSession(tx);
+                if (updated[0]) {
+                    await appendActionLedgerMutation(tx, buildPaymentSessionCancelledActionLedgerInput(actionLedgerContext, { session: updated[0], changes: data }, { authorizationSource: runtime.actionLedgerAuthorizationSource }));
+                }
+                return updated;
+            });
+            return row ?? null;
+        }
+        const [row] = await cancelSession(db);
+        return row ?? null;
+    },
+    async expirePaymentSession(db, id, data, runtime = {}) {
+        const expireSession = (writer) => writer
+            .update(paymentSessions)
+            .set({
+            status: "expired",
+            expiredAt: data.expiredAt ? toTimestamp(data.expiredAt) : new Date(),
+            providerPayload: data.providerPayload ?? undefined,
+            metadata: data.metadata ?? undefined,
+            notes: data.notes ?? undefined,
+            updatedAt: new Date(),
+        })
+            .where(eq(paymentSessions.id, id))
+            .returning();
+        const actionLedgerContext = runtime.actionLedgerContext;
+        if (actionLedgerContext) {
+            const [row] = await db.transaction(async (tx) => {
+                const updated = await expireSession(tx);
+                if (updated[0]) {
+                    await appendActionLedgerMutation(tx, buildPaymentSessionExpiredActionLedgerInput(actionLedgerContext, { session: updated[0], changes: data }, { authorizationSource: runtime.actionLedgerAuthorizationSource }));
+                }
+                return updated;
+            });
+            return row ?? null;
+        }
+        const [row] = await expireSession(db);
+        return row ?? null;
+    },
+};

package/dist/service-profitability.d.ts

@@ -0,0 +1,114 @@
+import type { DepartureProfitabilityQuery, ProductProfitabilityQuery, TravelerProfitabilityQuery } from "@voyant-travel/finance-contracts";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import { type InvoiceFxOptions } from "./invoice-fx.js";
+/**
+ * FX runtime for the profitability read model. Carries the operator FX settings
+ * (which name the accounting base currency, default "RON") and the exchange-rate
+ * resolver used to convert legacy, un-snapshotted rows. Threaded from the finance
+ * route runtime so the rollup matches how invoices were snapshotted at write time.
+ */
+export type ProfitabilityFxRuntime = InvoiceFxOptions;
+/**
+ * Profitability read model (RFC §8). Computed on read, never stored. Amounts are
+ * grouped **per currency** and never summed across currencies (no FX in v1).
+ *
+ * - Revenue  = issued customer invoices (AR), attributed to a departure by
+ *   splitting each booking's invoiced total across its departures in proportion
+ *   to the departures' booked sell amounts (`booking_items`). Credit notes net
+ *   the revenue down.
+ * - Actual cost = `supplier_cost_allocations` targeted at the departure/product.
+ * - Planned cost = `booking_items.totalCostAmountCents` (what we expected to pay).
+ * - Profit = revenue − actual cost. Variance = planned − actual cost.
+ */
+export interface ProfitabilityCostByServiceType {
+    serviceType: string;
+    currency: string;
+    amountCents: number;
+}
+export interface ProfitabilityUnattributed {
+    currency: string;
+    amountCents: number;
+}
+export interface DepartureProfitabilityRow {
+    departureId: string;
+    departureLabel: string | null;
+    productId: string | null;
+    productName: string | null;
+    departureDate: string | null;
+    currency: string;
+    revenueCents: number;
+    actualCostCents: number;
+    plannedCostCents: number;
+    profitCents: number;
+    marginPercent: number | null;
+    varianceCents: number;
+}
+export interface DepartureProfitabilityBaseRollup {
+    currency: string;
+    rows: DepartureProfitabilityRow[];
+    costByServiceType: ProfitabilityCostByServiceType[];
+    unattributedCents: number;
+    /** Source currencies with no resolvable FX rate — excluded from the rollup. */
+    unconvertibleCurrencies: string[];
+}
+export interface DepartureProfitabilityReport {
+    rows: DepartureProfitabilityRow[];
+    costByServiceType: ProfitabilityCostByServiceType[];
+    unattributed: ProfitabilityUnattributed[];
+    base?: DepartureProfitabilityBaseRollup;
+}
+export interface ProductProfitabilityRow {
+    productId: string;
+    productName: string | null;
+    currency: string;
+    departureCount: number;
+    revenueCents: number;
+    actualCostCents: number;
+    plannedCostCents: number;
+    profitCents: number;
+    marginPercent: number | null;
+    varianceCents: number;
+}
+export interface ProductProfitabilityBaseRollup {
+    currency: string;
+    rows: ProductProfitabilityRow[];
+    costByServiceType: ProfitabilityCostByServiceType[];
+    unattributedCents: number;
+    unconvertibleCurrencies: string[];
+}
+export interface ProductProfitabilityReport {
+    rows: ProductProfitabilityRow[];
+    costByServiceType: ProfitabilityCostByServiceType[];
+    unattributed: ProfitabilityUnattributed[];
+    base?: ProductProfitabilityBaseRollup;
+}
+export declare function getDepartureProfitability(db: PostgresJsDatabase, query: DepartureProfitabilityQuery, options?: ProfitabilityFxRuntime): Promise<DepartureProfitabilityReport>;
+export declare function getProductProfitability(db: PostgresJsDatabase, query: ProductProfitabilityQuery, options?: ProfitabilityFxRuntime): Promise<ProductProfitabilityReport>;
+export interface TravelerProfitabilityRow {
+    travelerId: string;
+    travelerName: string;
+    bookingId: string;
+    currency: string;
+    revenueCents: number;
+    actualCostCents: number;
+    plannedCostCents: number;
+    profitCents: number;
+    marginPercent: number | null;
+    varianceCents: number;
+}
+export interface TravelerProfitabilityReport {
+    departureId: string;
+    currency: string;
+    travelerCount: number;
+    rows: TravelerProfitabilityRow[];
+}
+/**
+ * Derive per-traveller P&L for one departure in a single currency. Revenue is a
+ * booking's departure-attributed invoiced AR split equally across that booking's
+ * travellers; planned cost likewise; actual departure cost is split equally
+ * across all the departure's travellers (`equal` method — `per_pax` parity).
+ */
+export declare function getTravelerProfitability(db: PostgresJsDatabase, query: TravelerProfitabilityQuery): Promise<TravelerProfitabilityReport>;
+export declare function buildDepartureProfitabilityCsv(report: DepartureProfitabilityReport): string;
+export declare function buildProductProfitabilityCsv(report: ProductProfitabilityReport): string;
+//# sourceMappingURL=service-profitability.d.ts.map

package/dist/service-profitability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-profitability.d.ts","sourceRoot":"","sources":["../src/service-profitability.ts"],"names":[],"mappings":"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"}