@voyant-travel/finance 0.165.0 → 0.167.0

package/dist/booking-tax.d.ts

@@ -13,15 +13,27 @@ export type ResolvedBookingSellTaxRate = {
     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`.
+     * Operator invoicing mode for the deferred bank-transfer path.
+     * `proforma-first` issues a proforma at order placement and converts it
+     * to a fiscal invoice on full settlement; `direct` issues the fiscal
+     * invoice at order placement. Card payments always invoice directly and
+     * never consult this. Absent/null → `proforma-first`.
      */
     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>;
@@ -47,12 +59,6 @@ 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;
@@ -78,6 +84,7 @@ export declare function createBookingTaxRoutes(options?: BookingTaxRouteOptions)
                     taxPriceMode: "inclusive" | "exclusive";
                     taxPolicyProfileId: string | null;
                     invoicingMode: "direct" | "proforma-first";
+                    fxReferenceSource: "ecb" | "bnr";
                 };
             };
             outputFormat: "json";
@@ -92,6 +99,7 @@ export declare function createBookingTaxRoutes(options?: BookingTaxRouteOptions)
                     taxPriceMode?: "inclusive" | "exclusive" | undefined;
                     taxPolicyProfileId?: string | null | undefined;
                     invoicingMode?: "direct" | "proforma-first" | undefined;
+                    fxReferenceSource?: "ecb" | "bnr" | undefined;
                 };
             };
             output: {};
@@ -103,6 +111,7 @@ export declare function createBookingTaxRoutes(options?: BookingTaxRouteOptions)
                     taxPriceMode?: "inclusive" | "exclusive" | undefined;
                     taxPolicyProfileId?: string | null | undefined;
                     invoicingMode?: "direct" | "proforma-first" | undefined;
+                    fxReferenceSource?: "ecb" | "bnr" | undefined;
                 };
             };
             output: {
@@ -110,6 +119,7 @@ export declare function createBookingTaxRoutes(options?: BookingTaxRouteOptions)
                     taxPriceMode: "inclusive" | "exclusive";
                     taxPolicyProfileId: string | null;
                     invoicingMode: "direct" | "proforma-first";
+                    fxReferenceSource: "ecb" | "bnr";
                 };
             };
             outputFormat: "json";

package/dist/booking-tax.js

@@ -15,12 +15,14 @@ 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({
@@ -115,18 +117,10 @@ async function resolveBookingTaxSettingsOrDefault(db, options = {}) {
     return {
         taxPriceMode: settings?.taxPriceMode === "exclusive" ? "exclusive" : "inclusive",
         taxPolicyProfileId: settings?.taxPolicyProfileId ?? null,
-        invoicingMode: settings?.invoicingMode === "proforma-first" ? "proforma-first" : "direct",
+        invoicingMode: settings?.invoicingMode === "direct" ? "direct" : "proforma-first",
+        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;
@@ -288,6 +282,7 @@ export function createBookingTaxRoutes(options = {}) {
                 ? 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 { 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

@@ -385,11 +385,9 @@ export const createBookingScheduleVoyantRuntime = defineGraphRuntimeFactory(asyn
                     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.
+                // Same host wiring powers the proforma-conversion subscriber:
+                // when a fully-paid proforma settles it mints the fiscal invoice.
                 container.register(PROFORMA_CONVERSION_SUBSCRIBER_RUNTIME_KEY, {
-                    resolveInvoicingMode: operatorSettings.resolveInvoicingMode,
                     withDb: provider.withDb,
                     eventBus,
                 });

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

@@ -1,26 +1,29 @@
 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).
+ * A proforma is issued for deferred (bank-transfer) checkouts when the
+ * operator runs the `proforma-first` invoicing mode, or by the manual
+ * `POST /invoices/{id}/convert-to-invoice` flow. This subscriber watches
+ * settlement signals (`invoice.settled` from the settlement poller and
+ * `invoice.payment.recorded` from manual/processed payments) and 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).
+ *
+ * The conversion is not gated on the invoicing mode: any fully-paid
+ * proforma should mint its fiscal invoice, and the `invoiceType ===
+ * "proforma"` guard already scopes it to proformas. Gating on the current
+ * mode would strand a proforma that is still outstanding when an operator
+ * switches from `proforma-first` to `direct`. When no proforma exists
+ * (card checkouts, or bank transfer in `direct` mode) the subscriber
+ * simply never fires. 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. */

package/dist/proforma-conversion-runtime.js

@@ -3,17 +3,23 @@ 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).
+ * A proforma is issued for deferred (bank-transfer) checkouts when the
+ * operator runs the `proforma-first` invoicing mode, or by the manual
+ * `POST /invoices/{id}/convert-to-invoice` flow. This subscriber watches
+ * settlement signals (`invoice.settled` from the settlement poller and
+ * `invoice.payment.recorded` from manual/processed payments) and 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).
+ *
+ * The conversion is not gated on the invoicing mode: any fully-paid
+ * proforma should mint its fiscal invoice, and the `invoiceType ===
+ * "proforma"` guard already scopes it to proformas. Gating on the current
+ * mode would strand a proforma that is still outstanding when an operator
+ * switches from `proforma-first` to `direct`. When no proforma exists
+ * (card checkouts, or bank transfer in `direct` mode) the subscriber
+ * simply never fires. 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";
@@ -26,15 +32,13 @@ export function createProformaConversionSubscriberRuntime(dependencies = {}) {
         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.
+                // Runtime is registered by the finance booking-schedule host wiring.
+                // Absent → the deployment did not mount finance settlement → 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;

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";
@@ -24,11 +24,50 @@ export interface FinanceOperatorSettingsRuntime {
      * 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>;
@@ -67,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

@@ -20,8 +20,38 @@ export const financeOperatorSettingsRuntimePort = objectPort("finance.operator-s
     "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/openapi/admin/booking-tax.json

@@ -36,7 +36,8 @@
                 "properties": {
                   "taxPriceMode": { "type": "string", "enum": ["inclusive", "exclusive"] },
                   "taxPolicyProfileId": { "type": ["string", "null"] },
-                  "invoicingMode": { "type": "string", "enum": ["direct", "proforma-first"] }
+                  "invoicingMode": { "type": "string", "enum": ["direct", "proforma-first"] },
+                  "fxReferenceSource": { "type": "string", "enum": ["ecb", "bnr"] }
                 }
               }
             }
@@ -76,11 +77,12 @@
     "schemas": {
       "BookingTaxSettings": {
         "type": "object",
-        "required": ["taxPriceMode", "taxPolicyProfileId", "invoicingMode"],
+        "required": ["taxPriceMode", "taxPolicyProfileId", "invoicingMode", "fxReferenceSource"],
         "properties": {
           "taxPriceMode": { "type": "string", "enum": ["inclusive", "exclusive"] },
           "taxPolicyProfileId": { "type": ["string", "null"] },
-          "invoicingMode": { "type": "string", "enum": ["direct", "proforma-first"] }
+          "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.165.0",
+  "version": "0.167.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -151,12 +151,13 @@
     "hono": "^4.12.27",
     "zod": "^4.4.3",
     "@voyant-travel/action-ledger": "^0.111.1",
-    "@voyant-travel/bookings": "^0.165.0",
+    "@voyant-travel/bookings": "^0.167.0",
     "@voyant-travel/core": "^0.125.0",
     "@voyant-travel/db": "^0.114.10",
     "@voyant-travel/types": "^0.109.3",
     "@voyant-travel/finance-contracts": "^0.106.2",
     "@voyant-travel/hono": "^0.128.1",
+    "@voyant-travel/payments": "^0.2.1",
     "@voyant-travel/public-document-delivery": "^0.4.1",
     "@voyant-travel/storage": "^0.111.1",
     "@voyant-travel/utils": "^0.107.1",