@voyant-travel/finance 0.164.0 → 0.165.0

package/dist/booking-tax.d.ts

@@ -12,9 +12,16 @@ export type ResolvedBookingSellTaxRate = {
     rate: number;
     priceMode: "inclusive" | "exclusive";
 };
+export type InvoicingMode = "direct" | "proforma-first";
 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;
 };
 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 +47,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 +77,7 @@ export declare function createBookingTaxRoutes(options?: BookingTaxRouteOptions)
                 data: {
                     taxPriceMode: "inclusive" | "exclusive";
                     taxPolicyProfileId: string | null;
+                    invoicingMode: "direct" | "proforma-first";
                 };
             };
             outputFormat: "json";
@@ -77,6 +91,7 @@ export declare function createBookingTaxRoutes(options?: BookingTaxRouteOptions)
                 json: {
                     taxPriceMode?: "inclusive" | "exclusive" | undefined;
                     taxPolicyProfileId?: string | null | undefined;
+                    invoicingMode?: "direct" | "proforma-first" | undefined;
                 };
             };
             output: {};
@@ -87,12 +102,14 @@ export declare function createBookingTaxRoutes(options?: BookingTaxRouteOptions)
                 json: {
                     taxPriceMode?: "inclusive" | "exclusive" | undefined;
                     taxPolicyProfileId?: string | null | undefined;
+                    invoicingMode?: "direct" | "proforma-first" | undefined;
                 };
             };
             output: {
                 data: {
                     taxPriceMode: "inclusive" | "exclusive";
                     taxPolicyProfileId: string | null;
+                    invoicingMode: "direct" | "proforma-first";
                 };
             };
             outputFormat: "json";

package/dist/booking-tax.js

@@ -14,11 +14,13 @@ 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(),
 });
 const bookingTaxSettingsResponseSchema = z.object({
     data: z.object({
         taxPriceMode: z.enum(["inclusive", "exclusive"]),
         taxPolicyProfileId: z.string().nullable(),
+        invoicingMode: z.enum(["direct", "proforma-first"]),
     }),
 });
 const bookingTaxPreviewResponseSchema = z.object({
@@ -113,8 +115,18 @@ async function resolveBookingTaxSettingsOrDefault(db, options = {}) {
     return {
         taxPriceMode: settings?.taxPriceMode === "exclusive" ? "exclusive" : "inclusive",
         taxPolicyProfileId: settings?.taxPolicyProfileId ?? null,
+        invoicingMode: settings?.invoicingMode === "proforma-first" ? "proforma-first" : "direct",
     };
 }
+/**
+ * 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 +287,7 @@ export function createBookingTaxRoutes(options = {}) {
             taxPolicyProfileId: patch.taxPolicyProfileId === undefined
                 ? current.taxPolicyProfileId
                 : patch.taxPolicyProfileId,
+            invoicingMode: patch.invoicingMode ?? current.invoicingMode,
         });
         return c.json({
             data: await resolveBookingTaxSettingsOrDefault(c.get("db"), { settings: next }),

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

@@ -17,6 +17,13 @@ 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">;
 }
 export interface FinanceNotificationsRuntime {
     resolveNotificationDispatcher: NonNullable<CheckoutRoutesOptions["resolveNotificationDispatcher"]>;

package/dist/runtime-port.js

@@ -15,7 +15,12 @@ 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",
+]);
 export const financeNotificationsRuntimePort = objectPort("finance.notifications.runtime", ["resolveNotificationDispatcher", "listBookingReminderRuns"]);
 export const financeDistributionPaymentPolicyRuntimePort = objectPort("finance.distribution-payment-policy.runtime", ["resolveSupplierPolicy", "resolveSupplierPolicyById"]);
 export const financeAccommodationsPaymentPolicyRuntimePort = objectPort("finance.accommodations-payment-policy.runtime", ["resolveBookingPolicy", "resolveEntityPolicy"]);

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,8 @@
                 "type": "object",
                 "properties": {
                   "taxPriceMode": { "type": "string", "enum": ["inclusive", "exclusive"] },
-                  "taxPolicyProfileId": { "type": ["string", "null"] }
+                  "taxPolicyProfileId": { "type": ["string", "null"] },
+                  "invoicingMode": { "type": "string", "enum": ["direct", "proforma-first"] }
                 }
               }
             }
@@ -75,10 +76,11 @@
     "schemas": {
       "BookingTaxSettings": {
         "type": "object",
-        "required": ["taxPriceMode", "taxPolicyProfileId"],
+        "required": ["taxPriceMode", "taxPolicyProfileId", "invoicingMode"],
         "properties": {
           "taxPriceMode": { "type": "string", "enum": ["inclusive", "exclusive"] },
-          "taxPolicyProfileId": { "type": ["string", "null"] }
+          "taxPolicyProfileId": { "type": ["string", "null"] },
+          "invoicingMode": { "type": "string", "enum": ["direct", "proforma-first"] }
         }
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyant-travel/finance",
-  "version": "0.164.0",
+  "version": "0.165.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,16 @@
     "hono": "^4.12.27",
     "zod": "^4.4.3",
     "@voyant-travel/action-ledger": "^0.111.1",
-    "@voyant-travel/bookings": "^0.164.0",
+    "@voyant-travel/bookings": "^0.165.0",
     "@voyant-travel/core": "^0.125.0",
-    "@voyant-travel/db": "^0.114.9",
-    "@voyant-travel/types": "^0.109.2",
+    "@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/utils": "^0.107.1",
-    "@voyant-travel/tools": "^0.3.0",
     "@voyant-travel/public-document-delivery": "^0.4.1",
-    "@voyant-travel/storage": "^0.111.1"
+    "@voyant-travel/storage": "^0.111.1",
+    "@voyant-travel/utils": "^0.107.1",
+    "@voyant-travel/tools": "^0.3.0"
   },
   "devDependencies": {
     "drizzle-kit": "^0.31.10",