@voyant-travel/finance 0.158.0 → 0.161.0

package/dist/tools.js

@@ -1,11 +1,24 @@
 /**
- * Finance agent tools on the framework tool contract. Thin, read-only wrappers
- * over the existing finance service; the service is injected on the tool context
+ * Finance agent tools on the framework tool contract. Thin wrappers over the
+ * existing finance service; the service is injected on the tool context
  * by intersection so this module stays deployment-agnostic.
+ * Refunds are issued through the credit-note service after action approval.
  */
-import { defineTool, READ_ONLY_RISK, requireService } from "@voyant-travel/tools";
+import { defineTool, READ_ONLY_RISK, requireService, ToolError, } from "@voyant-travel/tools";
+import { listResponseSchema } from "@voyant-travel/types";
 import { z } from "zod";
-import { invoiceListQuerySchema } from "./validation.js";
+import { creditNoteSchema, invoiceDetailSchema, invoiceListItemSchema, invoiceSchema, } from "./routes-invoice-schemas.js";
+import { bookingCreateSchema } from "./service-booking-create.js";
+import { insertCreditNoteSchema, invoiceFromBookingSchema, invoiceListQuerySchema, } from "./validation.js";
+const voidInvoiceResultSchema = z.discriminatedUnion("status", [
+    z.object({ status: z.literal("not_found") }),
+    z.object({ status: z.literal("already_void"), invoice: invoiceSchema }),
+    z.object({ status: z.literal("draft"), invoice: invoiceSchema }),
+    z.object({ status: z.literal("invalid_status"), invoice: invoiceSchema }),
+    z.object({ status: z.literal("has_payments"), invoice: invoiceSchema }),
+    z.object({ status: z.literal("has_credit_notes"), invoice: invoiceSchema }),
+    z.object({ status: z.literal("voided"), invoice: invoiceSchema }),
+]);
 function finance(ctx) {
     return requireService(ctx.finance, "finance");
 }
@@ -13,12 +26,12 @@ export const listInvoicesTool = defineTool({
     name: "list_invoices",
     description: "List invoices with filters and pagination. Read-only.",
     inputSchema: invoiceListQuerySchema,
-    outputSchema: z.custom(),
+    outputSchema: listResponseSchema(invoiceListItemSchema),
     requiredScopes: ["finance:read"],
     tier: "read",
     riskPolicy: READ_ONLY_RISK,
     async handler(query, ctx) {
-        return finance(ctx).listInvoices(query);
+        return parseJsonResult(listResponseSchema(invoiceListItemSchema), await finance(ctx).listInvoices(query));
     },
 });
 const getInvoiceArgs = z.object({ id: z.string().min(1).describe("The invoice id.") });
@@ -26,12 +39,12 @@ export const getInvoiceTool = defineTool({
     name: "get_invoice",
     description: "Read a single invoice by id. Read-only.",
     inputSchema: getInvoiceArgs,
-    outputSchema: z.custom(),
+    outputSchema: invoiceDetailSchema.nullable(),
     requiredScopes: ["finance:read"],
     tier: "read",
     riskPolicy: READ_ONLY_RISK,
     async handler({ id }, ctx) {
-        return finance(ctx).getInvoiceById(id);
+        return parseJsonResult(invoiceDetailSchema.nullable(), await finance(ctx).getInvoiceById(id));
     },
 });
 const voidInvoiceArgs = z.object({
@@ -42,7 +55,7 @@ export const voidInvoiceTool = defineTool({
     name: "void_invoice",
     description: "Void an invoice (irreversible). Returns a not-found status when the invoice does not exist.",
     inputSchema: voidInvoiceArgs,
-    outputSchema: z.custom(),
+    outputSchema: voidInvoiceResultSchema,
     requiredScopes: ["finance:void"],
     tier: "destructive",
     riskPolicy: {
@@ -52,7 +65,245 @@ export const voidInvoiceTool = defineTool({
         confirmationRequired: true,
     },
     async handler({ id, reason }, ctx) {
-        return finance(ctx).voidInvoice(id, { reason });
+        return parseJsonResult(voidInvoiceResultSchema, await finance(ctx).voidInvoice(id, { reason }));
     },
 });
-export const financeTools = [listInvoicesTool, getInvoiceTool, voidInvoiceTool];
+export const issueInvoiceRefundInputSchema = insertCreditNoteSchema.omit({ status: true }).extend({
+    invoiceId: z.string().min(1).describe("Invoice that receives the issued credit note."),
+    idempotencyKey: z
+        .string()
+        .trim()
+        .min(1)
+        .describe("Stable key used when requesting approval and replaying the command."),
+    approvalId: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Approval id returned after the prior request is approved."),
+});
+const pendingFinanceApprovalSchema = z.object({
+    status: z.literal("approval_required"),
+    requestedAction: z.object({
+        id: z.string(),
+        status: z.string(),
+        actionName: z.string(),
+        targetType: z.string(),
+        targetId: z.string(),
+    }),
+    approval: z.object({
+        id: z.string(),
+        status: z.string(),
+        requestedActionId: z.string(),
+        policyName: z.string(),
+        policyVersion: z.string(),
+        riskSnapshot: z.string(),
+        reasonCode: z.string(),
+        expiresAt: z.string().datetime().nullable(),
+        createdAt: z.string().datetime(),
+    }),
+    replayed: z.boolean(),
+});
+export const issueInvoiceRefundOutputSchema = z.union([
+    pendingFinanceApprovalSchema,
+    z.object({ status: z.literal("issued"), creditNote: creditNoteSchema, replayed: z.boolean() }),
+]);
+export const issueInvoiceRefundTool = defineTool({
+    owner: "@voyant-travel/finance",
+    capabilityId: "@voyant-travel/finance#tool.issue-invoice-refund",
+    capabilityVersion: "v1",
+    name: "issue_invoice_refund",
+    description: "Request approval to refund an invoice by issuing a credit note, or execute the exact approved request.",
+    inputSchema: issueInvoiceRefundInputSchema,
+    outputSchema: issueInvoiceRefundOutputSchema,
+    requiredScopes: ["finance:refund"],
+    audience: { source: "grant", allowed: ["staff"] },
+    tier: "destructive",
+    riskPolicy: {
+        destructive: true,
+        reversible: false,
+        dryRunSupported: false,
+        confirmationRequired: true,
+        sideEffects: ["refund", "data-write"],
+    },
+    annotations: { idempotentHint: true },
+    actionPolicyEnforcement: "handler",
+    async handler(input, ctx) {
+        return issueInvoiceRefundOutputSchema.parse(await finance(ctx).issueInvoiceRefund(input));
+    },
+});
+const bookingCreateSummarySchema = z.object({
+    status: z.literal("created"),
+    booking: z.object({
+        id: z.string(),
+        bookingNumber: z.string(),
+        status: z.string(),
+        currency: z.string(),
+        amountCents: z.number().int().nullable(),
+        pax: z.number().int().nullable(),
+    }),
+    travelerIds: z.array(z.string()),
+    paymentSchedules: z.array(z.object({
+        id: z.string(),
+        scheduleType: z.string(),
+        status: z.string(),
+        dueDate: z.string(),
+        currency: z.string(),
+        amountCents: z.number().int(),
+    })),
+    invoice: z
+        .object({
+        id: z.string(),
+        invoiceNumber: z.string(),
+        invoiceType: z.string(),
+        status: z.string(),
+    })
+        .nullable(),
+    invoiceDocument: z.discriminatedUnion("status", [
+        z.object({ status: z.literal("requested"), renditionId: z.string().nullable() }),
+        z.object({ status: z.literal("generated"), renditionId: z.string() }),
+        z.object({ status: z.enum(["not_requested", "not_available", "failed"]) }),
+    ]),
+    paymentIds: z.array(z.string()),
+    groupId: z.string().nullable(),
+    travelCreditRedemptionId: z.string().nullable(),
+});
+export const createBookingToolInputSchema = z.object({
+    booking: bookingCreateSchema.describe("The atomic product/slot booking command, including travelers, room/item lines, and schedules."),
+});
+export const createBookingTool = defineTool({
+    owner: "@voyant-travel/finance",
+    capabilityId: "@voyant-travel/finance#bookings-create-extension.tool.create-booking",
+    capabilityVersion: "v1",
+    name: "create_booking",
+    aliases: ["bookings_create"],
+    description: "Atomically create a booking from a product or slot with travelers, room/item lines, payment schedules, optional credit, group membership, and invoice documents.",
+    inputSchema: createBookingToolInputSchema,
+    outputSchema: bookingCreateSummarySchema,
+    requiredScopes: ["bookings:write", "finance:write"],
+    audience: { source: "grant", allowed: ["staff"] },
+    tier: "destructive",
+    riskPolicy: {
+        destructive: false,
+        reversible: true,
+        dryRunSupported: false,
+        confirmationRequired: true,
+        sideEffects: ["data-write", "external-booking", "payment"],
+    },
+    async handler({ booking }, ctx) {
+        const outcome = await finance(ctx).createBooking(booking);
+        if (outcome.status !== "ok") {
+            throw bookingCreateToolError(outcome);
+        }
+        const result = outcome.result;
+        return {
+            status: "created",
+            booking: {
+                id: result.booking.id,
+                bookingNumber: result.booking.bookingNumber,
+                status: result.booking.status,
+                currency: result.booking.sellCurrency,
+                amountCents: result.booking.sellAmountCents,
+                pax: result.booking.pax,
+            },
+            travelerIds: result.travelers.map((traveler) => traveler.id),
+            paymentSchedules: result.paymentSchedules.map((schedule) => ({
+                id: schedule.id,
+                scheduleType: schedule.scheduleType,
+                status: schedule.status,
+                dueDate: schedule.dueDate,
+                currency: schedule.currency,
+                amountCents: schedule.amountCents,
+            })),
+            invoice: result.invoice
+                ? {
+                    id: result.invoice.id,
+                    invoiceNumber: result.invoice.invoiceNumber,
+                    invoiceType: result.invoice.invoiceType,
+                    status: result.invoice.status,
+                }
+                : null,
+            invoiceDocument: result.invoiceDocument,
+            paymentIds: result.payments.map((payment) => payment.id),
+            groupId: result.groupMembership?.groupId ?? null,
+            travelCreditRedemptionId: result.travelCreditRedemption?.redemption.id ?? null,
+        };
+    },
+});
+export const financeBookingsCreateTools = [createBookingTool];
+export const issueInvoiceFromBookingToolInputSchema = z.object({
+    command: invoiceFromBookingSchema.describe("The exact invoice or proforma issue command."),
+    idempotencyKey: z
+        .string()
+        .trim()
+        .min(1)
+        .describe("Stable key used when requesting approval and replaying the exact command."),
+    approvalId: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Approval id returned after the exact prior command is approved."),
+});
+export const issueInvoiceFromBookingToolOutputSchema = z.union([
+    pendingFinanceApprovalSchema,
+    z.object({ status: z.literal("issued"), invoice: invoiceSchema, replayed: z.boolean() }),
+]);
+export const issueInvoiceFromBookingTool = defineTool({
+    owner: "@voyant-travel/finance",
+    capabilityId: "@voyant-travel/finance#tool.issue-invoice-from-booking",
+    capabilityVersion: "v1",
+    name: "issue_invoice_from_booking",
+    aliases: ["invoices_issue_from_booking"],
+    description: "Request approval to create and issue an invoice or proforma from a booking, or execute and idempotently replay the exact approved command.",
+    inputSchema: issueInvoiceFromBookingToolInputSchema,
+    outputSchema: issueInvoiceFromBookingToolOutputSchema,
+    requiredScopes: ["finance:write", "bookings:read"],
+    audience: { source: "grant", allowed: ["staff"] },
+    actionPolicyEnforcement: "handler",
+    tier: "destructive",
+    riskPolicy: {
+        destructive: false,
+        reversible: false,
+        dryRunSupported: false,
+        confirmationRequired: true,
+        sideEffects: ["data-write"],
+    },
+    annotations: { idempotentHint: true },
+    async handler(input, ctx) {
+        return issueInvoiceFromBookingToolOutputSchema.parse(await finance(ctx).issueInvoiceFromBooking(input));
+    },
+});
+export const financeTools = [
+    listInvoicesTool,
+    getInvoiceTool,
+    voidInvoiceTool,
+    issueInvoiceRefundTool,
+    issueInvoiceFromBookingTool,
+];
+function parseJsonResult(schema, value) {
+    return schema.parse(toJsonValue(value));
+}
+function bookingCreateToolError(outcome) {
+    switch (outcome.status) {
+        case "product_not_found":
+        case "travel_credit_not_found":
+        case "group_not_found":
+            return new ToolError(`Booking create failed: ${outcome.status}`, "NOT_FOUND", { outcome });
+        default:
+            return new ToolError(`Booking create rejected: ${outcome.status}`, "INVALID_INPUT", {
+                outcome,
+            });
+    }
+}
+function toJsonValue(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map(toJsonValue);
+    if (typeof value !== "object" || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .map(([key, nested]) => [key, toJsonValue(nested)])
+        .filter(([, nested]) => nested !== undefined));
+}

package/dist/voyant-admin.d.ts

@@ -1,6 +1,10 @@
 /** Static admin contribution metadata used by the Finance deployment manifest. */
 export declare const financeVoyantAdmin: {
     readonly compositionOrder: 40;
+    readonly setupSteps: readonly [{
+        readonly id: "@voyant-travel/finance#setup.fiscal-settings";
+        readonly skippable: true;
+    }];
     readonly runtime: {
         readonly entry: "@voyant-travel/finance-react/admin";
         readonly export: "createSelectedFinanceAdminExtension";

package/dist/voyant-admin.js

@@ -5,6 +5,7 @@ const financeAdminRuntime = {
 /** Static admin contribution metadata used by the Finance deployment manifest. */
 export const financeVoyantAdmin = {
     compositionOrder: 40,
+    setupSteps: [{ id: "@voyant-travel/finance#setup.fiscal-settings", skippable: true }],
     runtime: {
         entry: "@voyant-travel/finance-react/admin",
         export: "createSelectedFinanceAdminExtension",

package/dist/voyant.js

@@ -3,7 +3,7 @@ import { bookingsFinanceRuntimePort } from "@voyant-travel/bookings/runtime-port
 import { defineExtension, defineModule, providePort, requirePort, } from "@voyant-travel/core/project";
 import { financeAccommodationsPaymentPolicyRuntimePort, financeCheckoutPaymentStartersRuntimePort, financeCruisesPaymentPolicyRuntimePort, financeDistributionPaymentPolicyRuntimePort, financeHostRuntimePort, financeInventoryPaymentPolicyRuntimePort, financeInvoiceSettlementPollerRuntimePort, financeNotificationsRuntimePort, financeOperatorSettingsRuntimePort, } from "./runtime-port.js";
 import { financeVoyantAdmin } from "./voyant-admin.js";
-import { bookingConfirmedPayloadSchema, bookingContractDocumentRequestedPayloadSchema, bookingCreatedPayloadSchema, bookingCreateRejectedPayloadSchema, bookingDualCreatedPayloadSchema, bookingPaymentSchedulePaidPayloadSchema, invoiceDocumentGeneratedPayloadSchema, invoiceIssuedPayloadSchema, invoicePaymentRecordedPayloadSchema, invoiceProformaConvertedPayloadSchema, invoiceRenderedPayloadSchema, invoiceSettledPayloadSchema, invoiceVoidedPayloadSchema, paymentCompletedPayloadSchema, } from "./voyant-event-schemas.js";
+import { bookingContractDocumentRequestedPayloadSchema, bookingCreatedPayloadSchema, bookingCreateRejectedPayloadSchema, bookingDualCreatedPayloadSchema, bookingPaymentSchedulePaidPayloadSchema, invoiceDocumentGeneratedPayloadSchema, invoiceIssuedPayloadSchema, invoicePaymentRecordedPayloadSchema, invoiceProformaConvertedPayloadSchema, invoiceRenderedPayloadSchema, invoiceSettledPayloadSchema, invoiceVoidedPayloadSchema, paymentCompletedPayloadSchema, } from "./voyant-event-schemas.js";
 /** Import-cheap deployment declaration owned by the finance package. */
 export const financeVoyantModule = defineModule({
     id: "@voyant-travel/finance",
@@ -20,7 +20,7 @@ export const financeVoyantModule = defineModule({
         }),
     ],
     provides: {
-        capabilities: ["finance.payment-sessions"],
+        capabilities: ["finance.data-owner", "finance.payment-sessions"],
         ports: [
             providePort(actionLedgerFinanceDriftRuntimePort),
             providePort(bookingsFinanceRuntimePort),
@@ -173,14 +173,6 @@ export const financeVoyantModule = defineModule({
             visibility: "internal",
             audit: { sourceModule: "finance", category: "domain" },
         },
-        {
-            id: "@voyant-travel/finance#event.booking.confirmed",
-            eventType: "booking.confirmed",
-            version: "1.0.0",
-            payloadSchema: bookingConfirmedPayloadSchema,
-            visibility: "internal",
-            audit: { sourceModule: "finance", category: "domain" },
-        },
         {
             id: "@voyant-travel/finance#event.booking.dual-created",
             eventType: "booking.dual-created",
@@ -246,8 +238,8 @@ export const financeVoyantModule = defineModule({
                     },
                     {
                         action: "refund",
-                        label: "Refund payments",
-                        description: "Issue financial refunds against eligible payments.",
+                        label: "Issue invoice refunds",
+                        description: "Issue a credit note against an eligible invoice.",
                         sensitive: true,
                     },
                     {
@@ -285,6 +277,25 @@ export const financeVoyantModule = defineModule({
             context: ["finance"],
             risk: "critical",
         },
+        {
+            id: "@voyant-travel/finance#tool.issue-invoice-refund",
+            name: "issue_invoice_refund",
+            runtime: { entry: "@voyant-travel/finance/tools", export: "issueInvoiceRefundTool" },
+            requiredScopes: ["finance:refund"],
+            context: ["finance"],
+            risk: "critical",
+        },
+        {
+            id: "@voyant-travel/finance#tool.issue-invoice-from-booking",
+            name: "issue_invoice_from_booking",
+            runtime: {
+                entry: "@voyant-travel/finance/tools",
+                export: "issueInvoiceFromBookingTool",
+            },
+            requiredScopes: ["finance:write", "bookings:read"],
+            context: ["finance"],
+            risk: "high",
+        },
     ],
     actions: [
         {
@@ -301,6 +312,38 @@ export const financeVoyantModule = defineModule({
             reversible: false,
             from: { tools: ["@voyant-travel/finance#tool.void-invoice"] },
         },
+        {
+            id: "@voyant-travel/finance#action.issue-invoice-refund",
+            capabilityId: "finance:refund",
+            version: "v1",
+            kind: "execute",
+            targetType: "invoice",
+            resource: "finance",
+            action: "refund",
+            requiredScopes: ["finance:refund"],
+            risk: "critical",
+            ledger: "required",
+            approval: "required",
+            reversible: false,
+            allowedActorTypes: ["staff", "system"],
+            from: { tools: ["@voyant-travel/finance#tool.issue-invoice-refund"] },
+        },
+        {
+            id: "@voyant-travel/finance#action.issue-invoice-from-booking",
+            capabilityId: "finance:invoice-issue-from-booking",
+            version: "v1",
+            kind: "execute",
+            targetType: "booking",
+            resource: "finance",
+            action: "write",
+            requiredScopes: ["finance:write", "bookings:read"],
+            risk: "high",
+            ledger: "required",
+            approval: "required",
+            reversible: false,
+            allowedActorTypes: ["staff", "system"],
+            from: { tools: ["@voyant-travel/finance#tool.issue-invoice-from-booking"] },
+        },
     ],
     admin: financeVoyantAdmin,
     presentations: [
@@ -359,6 +402,35 @@ export const financeBookingsCreateVoyantPlugin = defineExtension({
             },
         },
     ],
+    tools: [
+        {
+            id: "@voyant-travel/finance#bookings-create-extension.tool.create-booking",
+            name: "create_booking",
+            runtime: { entry: "@voyant-travel/finance/tools", export: "createBookingTool" },
+            requiredScopes: ["bookings:write", "finance:write"],
+            context: ["finance"],
+            risk: "high",
+        },
+    ],
+    actions: [
+        {
+            id: "@voyant-travel/finance#bookings-create-extension.action.create-booking",
+            version: "v1",
+            kind: "execute",
+            targetType: "booking",
+            resource: "bookings",
+            action: "write",
+            requiredScopes: ["bookings:write", "finance:write"],
+            risk: "high",
+            ledger: "required",
+            approval: "never",
+            reversible: true,
+            allowedActorTypes: ["staff"],
+            from: {
+                tools: ["@voyant-travel/finance#bookings-create-extension.tool.create-booking"],
+            },
+        },
+    ],
     meta: {
         ownership: "package",
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyant-travel/finance",
-  "version": "0.158.0",
+  "version": "0.161.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -145,17 +145,17 @@
     "fflate": "^0.8.2",
     "hono": "^4.12.27",
     "zod": "^4.4.3",
-    "@voyant-travel/action-ledger": "^0.108.5",
-    "@voyant-travel/bookings": "^0.158.0",
-    "@voyant-travel/core": "^0.122.2",
-    "@voyant-travel/db": "^0.114.5",
-    "@voyant-travel/finance-contracts": "^0.106.1",
+    "@voyant-travel/action-ledger": "^0.109.1",
+    "@voyant-travel/bookings": "^0.161.0",
+    "@voyant-travel/core": "^0.124.0",
+    "@voyant-travel/db": "^0.114.7",
     "@voyant-travel/types": "^0.109.2",
-    "@voyant-travel/hono": "^0.126.3",
-    "@voyant-travel/storage": "^0.110.0",
+    "@voyant-travel/finance-contracts": "^0.106.1",
+    "@voyant-travel/hono": "^0.127.2",
+    "@voyant-travel/public-document-delivery": "^0.3.7",
+    "@voyant-travel/storage": "^0.110.2",
     "@voyant-travel/utils": "^0.107.1",
-    "@voyant-travel/public-document-delivery": "^0.3.5",
-    "@voyant-travel/tools": "^0.2.1"
+    "@voyant-travel/tools": "^0.3.0"
   },
   "devDependencies": {
     "drizzle-kit": "^0.31.10",