@voyant-travel/finance 0.164.0 → 0.166.0

package/dist/booking-tax.d.ts

@@ -12,9 +12,26 @@ export type ResolvedBookingSellTaxRate = {
     rate: number;
     priceMode: "inclusive" | "exclusive";
 };
+export type InvoicingMode = "direct" | "proforma-first";
+/**
+ * Official FX reference-rate source. `ecb` (default) covers most EU
+ * operators; `bnr` is the National Bank of Romania. A setting, not
+ * per-country code — new jurisdictions add values here, not modules.
+ */
+export type FxReferenceSource = "ecb" | "bnr";
 export type BookingTaxSettings = {
     taxPriceMode?: "inclusive" | "exclusive" | null;
     taxPolicyProfileId?: string | null;
+    /**
+     * Operator invoicing mode. `direct` bills the fiscal invoice
+     * straight away; `proforma-first` issues a proforma and converts it
+     * to a fiscal invoice on full settlement. Absent/null → `direct`.
+     */
+    invoicingMode?: InvoicingMode | null;
+    /**
+     * Operator's official FX reference-rate source. Absent/null → `ecb`.
+     */
+    fxReferenceSource?: FxReferenceSource | null;
 };
 export type ResolveBookingTaxSettings = (db: PostgresJsDatabase) => BookingTaxSettings | null | undefined | Promise<BookingTaxSettings | null | undefined>;
 export type UpdateBookingTaxSettings = (db: PostgresJsDatabase, settings: BookingTaxSettings) => BookingTaxSettings | null | undefined | Promise<BookingTaxSettings | null | undefined>;
@@ -40,6 +57,12 @@ export declare function resolveBookingSellTaxRate(db: PostgresJsDatabase, args:
     productId?: string | null;
     facts?: Partial<ProductTaxFacts>;
 }, options?: ResolveBookingSellTaxRateOptions): Promise<ResolvedBookingSellTaxRate | null>;
+/**
+ * Resolve just the operator invoicing mode, defaulting to `direct`
+ * when no settings row exists. Shared by the proforma-conversion
+ * subscriber so it never converts unless the operator opted in.
+ */
+export declare function resolveInvoicingModeOrDefault(db: PostgresJsDatabase, options?: ResolveBookingSellTaxRateOptions): Promise<InvoicingMode>;
 export declare function computeBookingItemTaxLine(taxRate: ResolvedBookingSellTaxRate | null, amountCents: number, currency: string, sortOrder?: number): {
     code: string;
     name: string;
@@ -64,6 +87,8 @@ export declare function createBookingTaxRoutes(options?: BookingTaxRouteOptions)
                 data: {
                     taxPriceMode: "inclusive" | "exclusive";
                     taxPolicyProfileId: string | null;
+                    invoicingMode: "direct" | "proforma-first";
+                    fxReferenceSource: "ecb" | "bnr";
                 };
             };
             outputFormat: "json";
@@ -77,6 +102,8 @@ export declare function createBookingTaxRoutes(options?: BookingTaxRouteOptions)
                 json: {
                     taxPriceMode?: "inclusive" | "exclusive" | undefined;
                     taxPolicyProfileId?: string | null | undefined;
+                    invoicingMode?: "direct" | "proforma-first" | undefined;
+                    fxReferenceSource?: "ecb" | "bnr" | undefined;
                 };
             };
             output: {};
@@ -87,12 +114,16 @@ export declare function createBookingTaxRoutes(options?: BookingTaxRouteOptions)
                 json: {
                     taxPriceMode?: "inclusive" | "exclusive" | undefined;
                     taxPolicyProfileId?: string | null | undefined;
+                    invoicingMode?: "direct" | "proforma-first" | undefined;
+                    fxReferenceSource?: "ecb" | "bnr" | undefined;
                 };
             };
             output: {
                 data: {
                     taxPriceMode: "inclusive" | "exclusive";
                     taxPolicyProfileId: string | null;
+                    invoicingMode: "direct" | "proforma-first";
+                    fxReferenceSource: "ecb" | "bnr";
                 };
             };
             outputFormat: "json";

package/dist/booking-tax.js

@@ -14,11 +14,15 @@ const taxPreviewBodySchema = z.object({
 const bookingTaxSettingsPatchSchema = z.object({
     taxPriceMode: z.enum(["inclusive", "exclusive"]).optional(),
     taxPolicyProfileId: z.string().min(1).nullable().optional(),
+    invoicingMode: z.enum(["direct", "proforma-first"]).optional(),
+    fxReferenceSource: z.enum(["ecb", "bnr"]).optional(),
 });
 const bookingTaxSettingsResponseSchema = z.object({
     data: z.object({
         taxPriceMode: z.enum(["inclusive", "exclusive"]),
         taxPolicyProfileId: z.string().nullable(),
+        invoicingMode: z.enum(["direct", "proforma-first"]),
+        fxReferenceSource: z.enum(["ecb", "bnr"]),
     }),
 });
 const bookingTaxPreviewResponseSchema = z.object({
@@ -113,8 +117,19 @@ async function resolveBookingTaxSettingsOrDefault(db, options = {}) {
     return {
         taxPriceMode: settings?.taxPriceMode === "exclusive" ? "exclusive" : "inclusive",
         taxPolicyProfileId: settings?.taxPolicyProfileId ?? null,
+        invoicingMode: settings?.invoicingMode === "proforma-first" ? "proforma-first" : "direct",
+        fxReferenceSource: settings?.fxReferenceSource === "bnr" ? "bnr" : "ecb",
     };
 }
+/**
+ * Resolve just the operator invoicing mode, defaulting to `direct`
+ * when no settings row exists. Shared by the proforma-conversion
+ * subscriber so it never converts unless the operator opted in.
+ */
+export async function resolveInvoicingModeOrDefault(db, options = {}) {
+    const settings = await resolveBookingTaxSettingsOrDefault(db, options);
+    return settings.invoicingMode;
+}
 export function computeBookingItemTaxLine(taxRate, amountCents, currency, sortOrder = 0) {
     if (!taxRate || taxRate.rate <= 0 || amountCents <= 0)
         return null;
@@ -275,6 +290,8 @@ export function createBookingTaxRoutes(options = {}) {
             taxPolicyProfileId: patch.taxPolicyProfileId === undefined
                 ? current.taxPolicyProfileId
                 : patch.taxPolicyProfileId,
+            invoicingMode: patch.invoicingMode ?? current.invoicingMode,
+            fxReferenceSource: patch.fxReferenceSource ?? current.fxReferenceSource,
         });
         return c.json({
             data: await resolveBookingTaxSettingsOrDefault(c.get("db"), { settings: next }),

package/dist/card-payment.d.ts

@@ -11,8 +11,10 @@
  * Returning `null` from a starter means "this processor isn't configured" so
  * callers fall back gracefully (bank-transfer paths still work).
  */
+import type { PaymentAdapter, PaymentAdapterRuntimeContext } from "@voyant-travel/payments";
 import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import type { Context } from "hono";
+import type { FinanceServiceRuntime } from "./service-shared.js";
 /**
  * Billing details a card processor needs to start a hosted payment.
  *
@@ -54,3 +56,9 @@ export interface CardPaymentStartResult {
  * configured" — callers fall back (bank transfer still works).
  */
 export type CardPaymentStarter = (c: Context, args: CardPaymentStartArgs) => Promise<CardPaymentStartResult | null>;
+export interface PaymentAdapterCardPaymentStarterOptions {
+    resolveContext?(c: Context): PaymentAdapterRuntimeContext;
+    resolveRuntime?(c: Context): FinanceServiceRuntime;
+    idempotencyKey?(sessionId: string): string;
+}
+export declare function createPaymentAdapterCardPaymentStarter(adapter: PaymentAdapter, options?: PaymentAdapterCardPaymentStarterOptions): CardPaymentStarter;

package/dist/card-payment.js

@@ -1 +1,57 @@
-export {};
+import { eq } from "drizzle-orm";
+import { paymentSessions } from "./schema/payment-sessions.js";
+import { financePaymentSessionCompletionService } from "./service-payment-session-completion.js";
+import { financePaymentSessionService } from "./service-payment-sessions.js";
+export function createPaymentAdapterCardPaymentStarter(adapter, options = {}) {
+    return async (c, args) => {
+        const [session] = await args.db
+            .select()
+            .from(paymentSessions)
+            .where(eq(paymentSessions.id, args.sessionId))
+            .limit(1);
+        if (!session)
+            return null;
+        const idempotencyKey = session.idempotencyKey ?? options.idempotencyKey?.(session.id) ?? `payment:${session.id}`;
+        const result = await adapter.initiate(options.resolveContext?.(c) ?? { env: c.env }, {
+            paymentSessionId: session.id,
+            money: { amountMinor: session.amountCents, currency: session.currency },
+            description: args.description ?? session.notes ?? undefined,
+            returnUrl: args.returnUrl ?? session.returnUrl ?? undefined,
+            idempotencyKey,
+            customer: {
+                email: args.billing.email,
+                phone: args.billing.phone ?? null,
+                firstName: args.billing.firstName,
+                lastName: args.billing.lastName ?? null,
+            },
+        });
+        const providerData = {
+            providerSessionId: result.processorSessionId ?? undefined,
+            providerPaymentId: result.processorPaymentId ?? undefined,
+            providerPayload: result.raw === undefined ? undefined : { initiation: result.raw },
+            metadata: { paymentAdapterInitiationIdempotencyKey: result.idempotencyKey },
+        };
+        if (result.nextState === "paid" || result.nextState === "authorized") {
+            await financePaymentSessionService.updatePaymentSession(args.db, session.id, {
+                provider: adapter.id,
+                redirectUrl: result.checkout?.url ?? undefined,
+                idempotencyKey,
+            });
+            await financePaymentSessionCompletionService.completePaymentSession(args.db, session.id, {
+                status: result.nextState,
+                captureMode: "automatic",
+                ...providerData,
+            }, options.resolveRuntime?.(c));
+        }
+        else {
+            await financePaymentSessionService.updatePaymentSession(args.db, session.id, {
+                provider: adapter.id,
+                status: result.nextState,
+                redirectUrl: result.checkout?.url ?? undefined,
+                idempotencyKey,
+                ...providerData,
+            });
+        }
+        return { redirectUrl: result.checkout?.url ?? null };
+    };
+}

package/dist/index.d.ts

@@ -23,12 +23,16 @@ export interface FinanceApiModuleOptions extends FinanceRuntimeOptions, PublicFi
 export declare function createFinanceApiModule(options?: FinanceApiModuleOptions): ApiModule;
 export declare const financeApiModule: ApiModule;
 export declare const createFinanceVoyantRuntime: import("@voyant-travel/core/project").VoyantGraphRuntimeFactory<ApiModule>;
+export type { PaymentAdapter, PaymentAdapterCapabilities, PaymentAdapterConformanceHarness, PaymentAdapterConformanceResult, PaymentAdapterDiagnostics, PaymentAdapterRuntimeContext, PaymentCallbackEvent, PaymentCallbackRequest, PaymentCallbackVerificationResult, PaymentInitiationInput, PaymentInitiationResult, PaymentMoney, PaymentOperationInput, PaymentOperationResult, PaymentStatusInput, PaymentStatusResult, } from "@voyant-travel/payments";
+export { PAYMENT_ADAPTER_CONTRACT_VERSION, PAYMENT_ADAPTER_RUNTIME_PORT_ID, paymentAdapterRuntimePort, runPaymentAdapterConformance, } from "@voyant-travel/payments";
 export { type BookingCancellationSettlementInput, buildPaidBookingCancellationSettlementNote, closeTerminalBookingPaymentSchedules, financeBookingLifecycle, recordPaidBookingCancellationSettlement, } from "./booking-lifecycle.js";
-export { type BookingTaxRouteOptions, type BookingTaxSettings, computeBookingItemTaxLine, createBookingTaxApiExtension, createBookingTaxRoutes, createBookingTaxVoyantRuntime, loadProductTaxFacts, matchesTaxPolicyCondition, mountBookingTaxRoutes, type ProductTaxFacts, type ResolveBookingSellTaxRateOptions, type ResolveBookingTaxSettings, type ResolvedBookingSellTaxRate, resolveBookingSellTaxRate, type TaxPolicyCondition, type UpdateBookingTaxSettings, } from "./booking-tax.js";
-export type { CardPaymentBilling, CardPaymentStartArgs, CardPaymentStarter, CardPaymentStartResult, } from "./card-payment.js";
+export { type BookingTaxRouteOptions, type BookingTaxSettings, computeBookingItemTaxLine, createBookingTaxApiExtension, createBookingTaxRoutes, createBookingTaxVoyantRuntime, type InvoicingMode, loadProductTaxFacts, matchesTaxPolicyCondition, mountBookingTaxRoutes, type ProductTaxFacts, type ResolveBookingSellTaxRateOptions, type ResolveBookingTaxSettings, type ResolvedBookingSellTaxRate, resolveBookingSellTaxRate, type TaxPolicyCondition, type UpdateBookingTaxSettings, } from "./booking-tax.js";
+export type { CardPaymentBilling, CardPaymentStartArgs, CardPaymentStarter, CardPaymentStartResult, PaymentAdapterCardPaymentStarterOptions, } from "./card-payment.js";
+export { createPaymentAdapterCardPaymentStarter } from "./card-payment.js";
 export { type DocumentDownloadEnvelope, type DocumentDownloadResolution, type DocumentDownloadResolver, resolveStoredDocumentDownload, type StoredDocumentReference, } from "./document-download.js";
 export { createInvoiceFxApiExtension, createInvoiceFxRoutes, createVoyantDataFxExchangeRateResolver, type InvoiceExchangeRateResolution, type InvoiceFxContext, type InvoiceFxOptions, type InvoiceFxRouteOptions, type InvoiceFxSettings, mountInvoiceFxRoutes, type ResolvedInvoiceFxSettings, type ResolveInvoiceExchangeRate, type ResolveInvoiceExchangeRateInput, type ResolveInvoiceFxSettings, resolveInvoiceFxContext, resolveInvoiceFxSettingsOrDefault, type UpdateInvoiceFxSettings, type VoyantDataFxResolverOptions, } from "./invoice-fx.js";
 export { type CreateOrderPaymentSessionsOptions, createOrderPaymentSessions, type EnsureOrderSessionParams, type OrderPaymentSessionSummary, type OrderPaymentSessions, type OrderPaymentSessionTargetType, type StartOrderPaymentProvider, } from "./order-payment-sessions.js";
+export { applyPaymentAdapterCallbackEvent } from "./payment-adapter-events.js";
 export type { ComputedScheduleEntry, ComputeScheduleInput, DepositKind, DepositRule, PaymentPolicy, PaymentPolicyCascadeLayers, PaymentPolicySource, PaymentScheduleEntryType, ResolvedPaymentPolicy, } from "./payment-policy.js";
 export { computePaymentSchedule, isPaymentPolicyEmpty, noDepositPolicy, normalizePaymentPolicy, policyShouldRequireFullPayment, resolveEffectivePaymentPolicy, } from "./payment-policy.js";
 export { createPaymentPolicyCascade, type PaymentPolicyCascade, type PaymentPolicyCascadeOptions, type PaymentPolicyCascadeReaders, readPolicySourceFromInternalNotes, stampPolicySourceOnBooking, } from "./payment-policy-cascade.js";

package/dist/index.js

@@ -87,11 +87,14 @@ export const createFinanceVoyantRuntime = defineGraphRuntimeFactory(async ({ api
     }
     return selected;
 });
+export { PAYMENT_ADAPTER_CONTRACT_VERSION, PAYMENT_ADAPTER_RUNTIME_PORT_ID, paymentAdapterRuntimePort, runPaymentAdapterConformance, } from "@voyant-travel/payments";
 export { buildPaidBookingCancellationSettlementNote, closeTerminalBookingPaymentSchedules, financeBookingLifecycle, recordPaidBookingCancellationSettlement, } from "./booking-lifecycle.js";
 export { computeBookingItemTaxLine, createBookingTaxApiExtension, createBookingTaxRoutes, createBookingTaxVoyantRuntime, loadProductTaxFacts, matchesTaxPolicyCondition, mountBookingTaxRoutes, resolveBookingSellTaxRate, } from "./booking-tax.js";
+export { createPaymentAdapterCardPaymentStarter } from "./card-payment.js";
 export { resolveStoredDocumentDownload, } from "./document-download.js";
 export { createInvoiceFxApiExtension, createInvoiceFxRoutes, createVoyantDataFxExchangeRateResolver, mountInvoiceFxRoutes, resolveInvoiceFxContext, resolveInvoiceFxSettingsOrDefault, } from "./invoice-fx.js";
 export { createOrderPaymentSessions, } from "./order-payment-sessions.js";
+export { applyPaymentAdapterCallbackEvent } from "./payment-adapter-events.js";
 export { computePaymentSchedule, isPaymentPolicyEmpty, noDepositPolicy, normalizePaymentPolicy, policyShouldRequireFullPayment, resolveEffectivePaymentPolicy, } from "./payment-policy.js";
 export { createPaymentPolicyCascade, readPolicySourceFromInternalNotes, stampPolicySourceOnBooking, } from "./payment-policy-cascade.js";
 export { createBookingScheduleAdminRoutes, createBookingScheduleApiExtension, createBookingScheduleVoyantRuntime, createPaymentPolicyPublicRoutes, generatePaymentScheduleForBooking, } from "./payment-schedule/routes.js";

package/dist/payment-adapter-events.d.ts

@@ -0,0 +1,47 @@
+import type { PaymentCallbackEvent } from "@voyant-travel/payments";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { FinanceServiceRuntime } from "./service-shared.js";
+export declare function applyPaymentAdapterCallbackEvent(db: PostgresJsDatabase, event: PaymentCallbackEvent, runtime?: FinanceServiceRuntime): Promise<{
+    id: string;
+    targetType: "other" | "booking" | "order" | "invoice" | "booking_payment_schedule" | "booking_guarantee" | "flight_order";
+    targetId: string | null;
+    bookingId: string | null;
+    orderId: string | null;
+    invoiceId: string | null;
+    bookingPaymentScheduleId: string | null;
+    bookingGuaranteeId: string | null;
+    paymentInstrumentId: string | null;
+    paymentAuthorizationId: string | null;
+    paymentCaptureId: string | null;
+    paymentId: string | null;
+    status: "paid" | "pending" | "failed" | "requires_redirect" | "processing" | "authorized" | "cancelled" | "expired";
+    provider: string | null;
+    providerSessionId: string | null;
+    providerPaymentId: string | null;
+    externalReference: string | null;
+    idempotencyKey: string | null;
+    clientReference: string | null;
+    currency: string;
+    amountCents: number;
+    paymentMethod: "bank_transfer" | "credit_card" | "debit_card" | "cash" | "cheque" | "wallet" | "direct_bill" | "travel_credit" | "other" | null;
+    payerPersonId: string | null;
+    payerOrganizationId: string | null;
+    payerEmail: string | null;
+    payerName: string | null;
+    redirectUrl: string | null;
+    returnUrl: string | null;
+    cancelUrl: string | null;
+    callbackUrl: string | null;
+    expiresAt: Date | null;
+    completedAt: Date | null;
+    failedAt: Date | null;
+    cancelledAt: Date | null;
+    expiredAt: Date | null;
+    failureCode: string | null;
+    failureMessage: string | null;
+    notes: string | null;
+    providerPayload: Record<string, unknown> | null;
+    metadata: Record<string, unknown> | null;
+    createdAt: Date;
+    updatedAt: Date;
+} | null>;

package/dist/payment-adapter-events.js

@@ -0,0 +1,34 @@
+import { financePaymentSessionCompletionService } from "./service-payment-session-completion.js";
+import { financePaymentSessionService } from "./service-payment-sessions.js";
+export async function applyPaymentAdapterCallbackEvent(db, event, runtime = {}) {
+    const providerData = {
+        providerSessionId: event.processorSessionId ?? undefined,
+        providerPaymentId: event.processorPaymentId ?? undefined,
+        providerPayload: event.raw === undefined ? undefined : { callback: event.raw },
+        metadata: { paymentAdapterEventId: event.eventId, paymentAdapterOccurredAt: event.occurredAt },
+    };
+    if (event.nextState === "paid" || event.nextState === "authorized") {
+        return financePaymentSessionCompletionService.completePaymentSession(db, event.paymentSessionId, {
+            status: event.nextState,
+            captureMode: "automatic",
+            ...providerData,
+        }, runtime);
+    }
+    if (event.nextState === "failed") {
+        return financePaymentSessionService.failPaymentSession(db, event.paymentSessionId, {
+            ...providerData,
+            failureCode: "payment_adapter_callback",
+            failureMessage: "Payment adapter callback mapped this session to failed.",
+        }, runtime);
+    }
+    if (event.nextState === "cancelled") {
+        return financePaymentSessionService.cancelPaymentSession(db, event.paymentSessionId, providerData, runtime);
+    }
+    if (event.nextState === "expired") {
+        return financePaymentSessionService.expirePaymentSession(db, event.paymentSessionId, providerData, runtime);
+    }
+    return financePaymentSessionService.updatePaymentSession(db, event.paymentSessionId, {
+        status: event.nextState,
+        ...providerData,
+    }, runtime);
+}

package/dist/payment-schedule/routes.js

@@ -30,6 +30,7 @@ import { openApiValidationHook, parseJsonBody } from "@voyant-travel/hono";
 import { asc, eq } from "drizzle-orm";
 import { BOOKING_SCHEDULE_SUBSCRIBER_RUNTIME_KEY } from "../booking-schedule/subscriber-runtime.js";
 import { computePaymentSchedule, noDepositPolicy, resolveEffectivePaymentPolicy, } from "../payment-policy.js";
+import { PROFORMA_CONVERSION_SUBSCRIBER_RUNTIME_KEY } from "../proforma-conversion-runtime.js";
 import { createFinanceBookingScheduleRuntime } from "../runtime.js";
 import { financeAccommodationsPaymentPolicyRuntimePort, financeCruisesPaymentPolicyRuntimePort, financeDistributionPaymentPolicyRuntimePort, financeHostRuntimePort, financeInventoryPaymentPolicyRuntimePort, financeOperatorSettingsRuntimePort, } from "../runtime-port.js";
 import { bookingPaymentSchedules } from "../schema/booking-billing.js";
@@ -373,16 +374,25 @@ export function createBookingScheduleApiExtension(options) {
     };
 }
 export const createBookingScheduleVoyantRuntime = defineGraphRuntimeFactory(async ({ api, getPort }) => {
-    const provider = createFinanceBookingScheduleRuntime(await getPort(financeHostRuntimePort), await getPort(financeOperatorSettingsRuntimePort), await getPort(financeDistributionPaymentPolicyRuntimePort), await getPort(financeAccommodationsPaymentPolicyRuntimePort), await getPort(financeCruisesPaymentPolicyRuntimePort), await getPort(financeInventoryPaymentPolicyRuntimePort));
+    const operatorSettings = await getPort(financeOperatorSettingsRuntimePort);
+    const provider = createFinanceBookingScheduleRuntime(await getPort(financeHostRuntimePort), operatorSettings, await getPort(financeDistributionPaymentPolicyRuntimePort), await getPort(financeAccommodationsPaymentPolicyRuntimePort), await getPort(financeCruisesPaymentPolicyRuntimePort), await getPort(financeInventoryPaymentPolicyRuntimePort));
     const configured = createBookingScheduleApiExtension(provider.options);
     const selected = {
         extension: {
             ...configured.extension,
-            bootstrap: async ({ container }) => {
+            bootstrap: async ({ container, eventBus }) => {
                 container.register(BOOKING_SCHEDULE_SUBSCRIBER_RUNTIME_KEY, {
                     resolveRoutesOptions: () => provider.options,
                     withDb: provider.withDb,
                 });
+                // Same host/settings wiring powers the proforma-conversion
+                // subscriber: it reads the operator invoicing mode and, in
+                // proforma-first mode, mints the fiscal invoice on settlement.
+                container.register(PROFORMA_CONVERSION_SUBSCRIBER_RUNTIME_KEY, {
+                    resolveInvoicingMode: operatorSettings.resolveInvoicingMode,
+                    withDb: provider.withDb,
+                    eventBus,
+                });
             },
         },
     };

package/dist/proforma-conversion-runtime.d.ts

@@ -0,0 +1,34 @@
+import type { EventBus, SubscriberRuntimeDescriptor } from "@voyant-travel/core";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { InvoicingMode } from "./booking-tax.js";
+/**
+ * Standard proforma → fiscal invoice conversion.
+ *
+ * When the operator runs `invoicing.mode: "proforma-first"`, a proforma
+ * is issued at checkout and the fiscal invoice is minted once the
+ * proforma is fully settled. This subscriber watches settlement signals
+ * (`invoice.settled` from the settlement poller and
+ * `invoice.payment.recorded` from manual/processed payments) and, in
+ * proforma-first mode only, converts a fully-paid proforma to its fiscal
+ * invoice via {@link convertProformaToInvoice} (which copies lines,
+ * assigns the fiscal number, links both documents, and voids the
+ * proforma). `direct` mode is a no-op — zero behaviour change for
+ * existing deployments — and the conversion is idempotent (the service
+ * guards against double-conversion under an advisory lock).
+ */
+export declare const FINANCE_PROFORMA_CONVERSION_SUBSCRIBER_ID = "@voyant-travel/finance#subscriber.proforma-conversion";
+export declare const PROFORMA_CONVERSION_SUBSCRIBER_RUNTIME_KEY = "finance.proformaConversionSubscriberRuntime";
+export interface ProformaConversionSubscriberRuntime {
+    /** Operator invoicing mode; defaults to `direct` when unconfigured. */
+    resolveInvoicingMode(db: PostgresJsDatabase): Promise<InvoicingMode>;
+    /** Resolve the deployment database and retain ownership of its lifecycle. */
+    withDb<T>(bindings: unknown, operation: (db: PostgresJsDatabase) => Promise<T>): Promise<T>;
+    /** Event bus used to re-emit conversion events for downstream plugins. */
+    eventBus?: EventBus;
+}
+export interface ProformaConversionSubscriberDependencies {
+    logger?: Pick<Console, "error" | "info">;
+}
+/** Build the package-owned descriptor resolved by selected-graph lowering. */
+export declare function createProformaConversionSubscriberRuntime(dependencies?: ProformaConversionSubscriberDependencies): SubscriberRuntimeDescriptor;
+export declare const proformaConversionSubscriber: SubscriberRuntimeDescriptor;

package/dist/proforma-conversion-runtime.js

@@ -0,0 +1,73 @@
+import { financeService } from "./service.js";
+import { convertProformaToInvoice } from "./service-issue.js";
+/**
+ * Standard proforma → fiscal invoice conversion.
+ *
+ * When the operator runs `invoicing.mode: "proforma-first"`, a proforma
+ * is issued at checkout and the fiscal invoice is minted once the
+ * proforma is fully settled. This subscriber watches settlement signals
+ * (`invoice.settled` from the settlement poller and
+ * `invoice.payment.recorded` from manual/processed payments) and, in
+ * proforma-first mode only, converts a fully-paid proforma to its fiscal
+ * invoice via {@link convertProformaToInvoice} (which copies lines,
+ * assigns the fiscal number, links both documents, and voids the
+ * proforma). `direct` mode is a no-op — zero behaviour change for
+ * existing deployments — and the conversion is idempotent (the service
+ * guards against double-conversion under an advisory lock).
+ */
+export const FINANCE_PROFORMA_CONVERSION_SUBSCRIBER_ID = "@voyant-travel/finance#subscriber.proforma-conversion";
+export const PROFORMA_CONVERSION_SUBSCRIBER_RUNTIME_KEY = "finance.proformaConversionSubscriberRuntime";
+const SETTLEMENT_EVENTS = ["invoice.settled", "invoice.payment.recorded"];
+/** Build the package-owned descriptor resolved by selected-graph lowering. */
+export function createProformaConversionSubscriberRuntime(dependencies = {}) {
+    const logger = dependencies.logger ?? console;
+    return {
+        id: FINANCE_PROFORMA_CONVERSION_SUBSCRIBER_ID,
+        eventType: "invoice.settled",
+        register: ({ bindings, container, eventBus }) => {
+            const handler = async ({ data }) => {
+                // Runtime is only registered when the operator-settings port is
+                // available. Absent → treat as `direct` mode → no-op.
+                if (!container.has(PROFORMA_CONVERSION_SUBSCRIBER_RUNTIME_KEY))
+                    return;
+                const runtime = resolveProformaConversionSubscriberRuntime(container);
+                try {
+                    await runtime.withDb(bindings, async (db) => {
+                        if ((await runtime.resolveInvoicingMode(db)) !== "proforma-first")
+                            return;
+                        const invoice = await financeService.getInvoiceById(db, data.invoiceId);
+                        if (!invoice)
+                            return;
+                        // Only fully-settled proformas convert. Partial payments leave
+                        // the proforma outstanding until the balance is cleared.
+                        if (invoice.invoiceType !== "proforma" || invoice.balanceDueCents !== 0)
+                            return;
+                        const result = await convertProformaToInvoice(db, invoice.id, {}, { eventBus: runtime.eventBus ?? eventBus });
+                        if (result.status !== "ok" && result.status !== "already_converted") {
+                            logger.error("[proforma-conversion] conversion did not complete", {
+                                invoiceId: invoice.id,
+                                status: result.status,
+                            });
+                        }
+                    });
+                }
+                catch (error) {
+                    logger.error("[proforma-conversion] failed to convert settled proforma", {
+                        invoiceId: data.invoiceId,
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            };
+            for (const eventType of SETTLEMENT_EVENTS) {
+                eventBus.subscribe(eventType, handler);
+            }
+        },
+    };
+}
+function resolveProformaConversionSubscriberRuntime(container) {
+    if (!container.has(PROFORMA_CONVERSION_SUBSCRIBER_RUNTIME_KEY)) {
+        throw new Error(`Proforma-conversion subscriber runtime is not registered at "${PROFORMA_CONVERSION_SUBSCRIBER_RUNTIME_KEY}".`);
+    }
+    return container.resolve(PROFORMA_CONVERSION_SUBSCRIBER_RUNTIME_KEY);
+}
+export const proformaConversionSubscriber = createProformaConversionSubscriberRuntime();

package/dist/runtime-port.d.ts

@@ -1,7 +1,7 @@
 import type { VoyantRuntimeHostPrimitives } from "@voyant-travel/core";
 import type { AnyDrizzleDb } from "@voyant-travel/db";
 import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
-import type { BookingTaxRouteOptions } from "./booking-tax.js";
+import type { BookingTaxRouteOptions, FxReferenceSource } from "./booking-tax.js";
 import type { CheckoutRoutesOptions } from "./checkout-routes.js";
 import type { CheckoutPaymentStarter } from "./checkout-service.js";
 import type { PaymentPolicy } from "./payment-policy.js";
@@ -17,11 +17,57 @@ export interface FinanceOperatorSettingsRuntime {
     resolveOperatorDefaultPaymentPolicy: BookingScheduleRoutesOptions["resolveOperatorDefaultPaymentPolicy"];
     resolveBookingTaxSettings: NonNullable<BookingTaxRouteOptions["resolveBookingTaxSettings"]>;
     updateBookingTaxSettings: NonNullable<BookingTaxRouteOptions["updateBookingTaxSettings"]>;
+    /**
+     * Resolve the operator's invoicing mode (`direct` | `proforma-first`).
+     * Defaults to `direct` when unconfigured. The finance
+     * proforma-conversion subscriber reads this to decide whether a
+     * settled proforma should be auto-converted to a fiscal invoice.
+     */
+    resolveInvoicingMode: (db: PostgresJsDatabase) => Promise<"direct" | "proforma-first">;
+    /**
+     * Resolve the operator's official FX reference-rate source
+     * (`ecb` | `bnr`, default `ecb`). Read by the finance fx-reference
+     * helper to pick the host-provided rate source for the operator.
+     */
+    resolveFxReferenceSource: (db: PostgresJsDatabase) => Promise<FxReferenceSource>;
 }
 export interface FinanceNotificationsRuntime {
     resolveNotificationDispatcher: NonNullable<CheckoutRoutesOptions["resolveNotificationDispatcher"]>;
     listBookingReminderRuns: NonNullable<CheckoutRoutesOptions["listBookingReminderRuns"]>;
 }
+/** Request for one official FX reference rate on a given date. */
+export interface FxReferenceRateRequest {
+    /** Currency to convert from, e.g. `EUR` (ISO 4217). */
+    base: string;
+    /** Currency to convert into, e.g. `RON` (ISO 4217). */
+    quote: string;
+    /** Reference date in `YYYY-MM-DD`. Defaults to the host's latest published rate. */
+    date?: string;
+}
+/** One resolved official FX reference rate. */
+export interface FxReferenceRate {
+    /** Units of `quote` per one unit of `base`. */
+    rate: number;
+    /** The reference source that published the rate, e.g. `ecb` or `bnr`. */
+    source: FxReferenceSource;
+    /** Date the returned rate was published (`YYYY-MM-DD`). */
+    asOf: string;
+}
+/**
+ * Host-provided official FX reference-rate source. Finance defines the
+ * seam only; hosts/deployments wire it to their own FX data source. No
+ * HTTP client or API key lives inside finance.
+ */
+export interface FinanceFxReferenceRuntime {
+    /**
+     * Resolve one official reference rate. `source` is the operator's
+     * configured reference source (e.g. `ecb`, `bnr`); the host uses it
+     * to pick the correct published series.
+     */
+    resolveReferenceRate(request: FxReferenceRateRequest & {
+        source: FxReferenceSource;
+    }): Promise<FxReferenceRate>;
+}
 export interface FinanceDistributionPaymentPolicyRuntime {
     resolveSupplierPolicy: PolicyReader;
     resolveSupplierPolicyById(db: PostgresJsDatabase, supplierId: string): Promise<PaymentPolicy | null>;
@@ -60,6 +106,35 @@ export interface FinanceBookingScheduleRuntime {
 export declare const financeHostRuntimePort: import("@voyant-travel/core/project").VoyantPort<FinanceHostRuntime>;
 export declare const financeOperatorSettingsRuntimePort: import("@voyant-travel/core/project").VoyantPort<FinanceOperatorSettingsRuntime>;
 export declare const financeNotificationsRuntimePort: import("@voyant-travel/core/project").VoyantPort<FinanceNotificationsRuntime>;
+export declare const financeFxReferenceRuntimePort: import("@voyant-travel/core/project").VoyantPort<FinanceFxReferenceRuntime>;
+/**
+ * Raised when a caller explicitly requests an official FX reference
+ * rate but no `finance.fx-reference.runtime` provider is wired. Callers
+ * that never request a reference rate are unaffected — the seam is
+ * inert until used.
+ */
+export declare class FinanceFxReferenceSourceUnavailableError extends Error {
+    readonly code = "finance_fx_reference_source_unavailable";
+    constructor(source: FxReferenceSource);
+}
+export interface ResolveReferenceRateHelperInput {
+    base: string;
+    quote: string;
+    date?: string;
+    /** The operator's configured reference source (e.g. `ecb`, `bnr`). */
+    source: FxReferenceSource;
+    /** Host-provided implementation. Absent → typed unavailable error. */
+    provider?: FinanceFxReferenceRuntime | null;
+}
+/**
+ * Typed helper that resolves an official FX reference rate for an
+ * operator's configured source by delegating to the host-provided
+ * `finance.fx-reference.runtime` implementation. When no provider is
+ * wired, throws {@link FinanceFxReferenceSourceUnavailableError} — a
+ * clear, typed signal rather than a silent fallback. Finance holds no
+ * FX data itself.
+ */
+export declare function resolveReferenceRate(input: ResolveReferenceRateHelperInput): Promise<FxReferenceRate>;
 export declare const financeDistributionPaymentPolicyRuntimePort: import("@voyant-travel/core/project").VoyantPort<FinanceDistributionPaymentPolicyRuntime>;
 export declare const financeAccommodationsPaymentPolicyRuntimePort: import("@voyant-travel/core/project").VoyantPort<FinanceAccommodationsPaymentPolicyRuntime>;
 export declare const financeCruisesPaymentPolicyRuntimePort: import("@voyant-travel/core/project").VoyantPort<FinanceCruisesPaymentPolicyRuntime>;

package/dist/runtime-port.js

@@ -15,8 +15,43 @@ function objectPort(id, methods = []) {
     });
 }
 export const financeHostRuntimePort = objectPort("finance.host.runtime");
-export const financeOperatorSettingsRuntimePort = objectPort("finance.operator-settings.runtime", ["resolveOperatorDefaultPaymentPolicy", "resolveBookingTaxSettings", "updateBookingTaxSettings"]);
+export const financeOperatorSettingsRuntimePort = objectPort("finance.operator-settings.runtime", [
+    "resolveOperatorDefaultPaymentPolicy",
+    "resolveBookingTaxSettings",
+    "updateBookingTaxSettings",
+    "resolveInvoicingMode",
+    "resolveFxReferenceSource",
+]);
 export const financeNotificationsRuntimePort = objectPort("finance.notifications.runtime", ["resolveNotificationDispatcher", "listBookingReminderRuns"]);
+export const financeFxReferenceRuntimePort = objectPort("finance.fx-reference.runtime", ["resolveReferenceRate"]);
+/**
+ * Raised when a caller explicitly requests an official FX reference
+ * rate but no `finance.fx-reference.runtime` provider is wired. Callers
+ * that never request a reference rate are unaffected — the seam is
+ * inert until used.
+ */
+export class FinanceFxReferenceSourceUnavailableError extends Error {
+    code = "finance_fx_reference_source_unavailable";
+    constructor(source) {
+        super(`No FX reference-rate source is configured for "${source}". A host must provide the finance.fx-reference.runtime port.`);
+        this.name = "FinanceFxReferenceSourceUnavailableError";
+    }
+}
+/**
+ * Typed helper that resolves an official FX reference rate for an
+ * operator's configured source by delegating to the host-provided
+ * `finance.fx-reference.runtime` implementation. When no provider is
+ * wired, throws {@link FinanceFxReferenceSourceUnavailableError} — a
+ * clear, typed signal rather than a silent fallback. Finance holds no
+ * FX data itself.
+ */
+export function resolveReferenceRate(input) {
+    const { provider, source, base, quote, date } = input;
+    if (!provider) {
+        throw new FinanceFxReferenceSourceUnavailableError(source);
+    }
+    return provider.resolveReferenceRate({ base, quote, date, source });
+}
 export const financeDistributionPaymentPolicyRuntimePort = objectPort("finance.distribution-payment-policy.runtime", ["resolveSupplierPolicy", "resolveSupplierPolicyById"]);
 export const financeAccommodationsPaymentPolicyRuntimePort = objectPort("finance.accommodations-payment-policy.runtime", ["resolveBookingPolicy", "resolveEntityPolicy"]);
 export const financeCruisesPaymentPolicyRuntimePort = objectPort("finance.cruises-payment-policy.runtime", [

package/dist/service-payment-session-completion.js

@@ -9,6 +9,7 @@ export const financePaymentSessionCompletionService = {
         if (!session) {
             return null;
         }
+        const shouldEmitPaymentCompleted = data.status === "paid" && session.status !== "paid";
         const txResult = await db.transaction(async (tx) => {
             let authorizationId = session.paymentAuthorizationId;
             let captureId = session.paymentCaptureId;
@@ -257,7 +258,7 @@ export const financePaymentSessionCompletionService = {
         // Some aggregate flows, such as composed trips, intentionally use a
         // generic target instead of booking/order/invoice columns; those still
         // need the completion event keyed by targetType/targetId.
-        if (data.status === "paid" && txResult.updated) {
+        if (shouldEmitPaymentCompleted && txResult.updated) {
             await runtime.eventBus?.emit("payment.completed", buildPaymentCompletedEvent(txResult.updated), {
                 category: "domain",
                 source: "service",

package/dist/voyant.js

@@ -487,6 +487,15 @@ export const financeBookingScheduleVoyantPlugin = defineExtension({
                 export: "bookingScheduleConfirmedSubscriber",
             },
         },
+        {
+            id: "@voyant-travel/finance#subscriber.proforma-conversion",
+            eventType: "invoice.settled",
+            source: "@voyant-travel/finance/proforma-conversion-subscriber",
+            runtime: {
+                entry: "@voyant-travel/finance/proforma-conversion-subscriber",
+                export: "proformaConversionSubscriber",
+            },
+        },
     ],
     meta: {
         ownership: "package",

package/openapi/admin/booking-tax.json

@@ -35,7 +35,9 @@
                 "type": "object",
                 "properties": {
                   "taxPriceMode": { "type": "string", "enum": ["inclusive", "exclusive"] },
-                  "taxPolicyProfileId": { "type": ["string", "null"] }
+                  "taxPolicyProfileId": { "type": ["string", "null"] },
+                  "invoicingMode": { "type": "string", "enum": ["direct", "proforma-first"] },
+                  "fxReferenceSource": { "type": "string", "enum": ["ecb", "bnr"] }
                 }
               }
             }
@@ -75,10 +77,12 @@
     "schemas": {
       "BookingTaxSettings": {
         "type": "object",
-        "required": ["taxPriceMode", "taxPolicyProfileId"],
+        "required": ["taxPriceMode", "taxPolicyProfileId", "invoicingMode", "fxReferenceSource"],
         "properties": {
           "taxPriceMode": { "type": "string", "enum": ["inclusive", "exclusive"] },
-          "taxPolicyProfileId": { "type": ["string", "null"] }
+          "taxPolicyProfileId": { "type": ["string", "null"] },
+          "invoicingMode": { "type": "string", "enum": ["direct", "proforma-first"] },
+          "fxReferenceSource": { "type": "string", "enum": ["ecb", "bnr"] }
         }
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyant-travel/finance",
-  "version": "0.164.0",
+  "version": "0.166.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -104,6 +104,11 @@
       "import": "./dist/booking-schedule/subscriber-runtime.js",
       "default": "./dist/booking-schedule/subscriber-runtime.js"
     },
+    "./proforma-conversion-subscriber": {
+      "types": "./dist/proforma-conversion-runtime.d.ts",
+      "import": "./dist/proforma-conversion-runtime.js",
+      "default": "./dist/proforma-conversion-runtime.js"
+    },
     "./routes": {
       "types": "./dist/routes.d.ts",
       "import": "./dist/routes.js",
@@ -146,16 +151,17 @@
     "hono": "^4.12.27",
     "zod": "^4.4.3",
     "@voyant-travel/action-ledger": "^0.111.1",
-    "@voyant-travel/bookings": "^0.164.0",
-    "@voyant-travel/core": "^0.125.0",
-    "@voyant-travel/db": "^0.114.9",
-    "@voyant-travel/types": "^0.109.2",
-    "@voyant-travel/finance-contracts": "^0.106.2",
+    "@voyant-travel/db": "^0.114.10",
+    "@voyant-travel/types": "^0.109.3",
+    "@voyant-travel/bookings": "^0.166.0",
     "@voyant-travel/hono": "^0.128.1",
-    "@voyant-travel/utils": "^0.107.1",
+    "@voyant-travel/core": "^0.125.0",
+    "@voyant-travel/storage": "^0.111.1",
+    "@voyant-travel/payments": "^0.2.0",
     "@voyant-travel/tools": "^0.3.0",
     "@voyant-travel/public-document-delivery": "^0.4.1",
-    "@voyant-travel/storage": "^0.111.1"
+    "@voyant-travel/finance-contracts": "^0.106.2",
+    "@voyant-travel/utils": "^0.107.1"
   },
   "devDependencies": {
     "drizzle-kit": "^0.31.10",