@voyant-travel/finance 0.159.0 → 0.162.0

package/dist/mcp-runtime.js

@@ -1,16 +1,276 @@
-import { defineToolContextContribution } from "@voyant-travel/tools";
+import { buildActionLedgerApprovedExecutionFields, } from "@voyant-travel/action-ledger";
+import { defineToolContextContribution, ToolError } from "@voyant-travel/tools";
+import { authorizeFinanceInvoiceIssue, FINANCE_INVOICE_ISSUE_ACTION_NAME, FINANCE_INVOICE_ISSUE_CAPABILITY, FINANCE_INVOICE_ISSUE_TOOL_NAME, } from "./invoice-issue-authorization.js";
+import { authorizeFinanceRefund, FINANCE_REFUND_ACTION_NAME, FINANCE_REFUND_CAPABILITY, FINANCE_REFUND_ROUTE_OR_TOOL_NAME, } from "./refund-authorization.js";
+import { getActionLedgerRequestContext, getFinanceRouteRuntime } from "./routes-runtime.js";
 import { financeService } from "./service.js";
+import { createBooking } from "./service-booking-create.js";
+import { issueInvoiceFromBookingCommand } from "./service-issue.js";
 export * from "./tools.js";
 export const voyantToolContextContribution = defineToolContextContribution({
     context: ["finance"],
-    contribute: ({ context }) => {
+    contribute: ({ context, request }) => {
+        const c = request;
         const db = context.db;
         return {
             finance: {
                 listInvoices: (query) => financeService.listInvoices(db, query),
                 getInvoiceById: (id) => financeService.getInvoiceById(db, id),
+                getFinanceAggregates: (query) => financeService.getFinanceAggregates(db, query),
                 voidInvoice: (id, input) => financeService.voidInvoice(db, id, input),
+                createBooking: (input) => createBooking(db, input, {
+                    userId: c.get("userId") ?? undefined,
+                    runtime: {
+                        ...getFinanceRouteRuntime(c),
+                        actionLedgerContext: getActionLedgerRequestContext(c),
+                        actionLedgerAuthorizationSource: "finance.booking_create.tool",
+                    },
+                }),
+                async issueInvoiceFromBooking(input) {
+                    const { command, idempotencyKey, approvalId } = input;
+                    const requestContext = financeToolActionLedgerContext(c);
+                    const authorization = await authorizeFinanceInvoiceIssue({
+                        db,
+                        commandInput: command,
+                        actor: c.get("actor"),
+                        callerType: c.get("callerType"),
+                        scopes: c.get("scopes"),
+                        isInternalRequest: c.get("isInternalRequest"),
+                        requestContext,
+                        approvalId: approvalId ?? null,
+                        idempotencyKey,
+                    });
+                    if (authorization.status === "approval_required") {
+                        return pendingApprovalResult(authorization);
+                    }
+                    if (authorization.status === "already_executed") {
+                        const invoice = await financeService.getInvoiceById(db, authorization.invoiceId);
+                        if (!invoice) {
+                            throw new ToolError("The previously issued invoice was not found.", "NOT_FOUND", {
+                                invoiceId: authorization.invoiceId,
+                            });
+                        }
+                        return { status: "issued", invoice: toJsonValue(invoice), replayed: true };
+                    }
+                    if (authorization.status !== "authorized") {
+                        throw financeInvoiceIssueAuthorizationError(authorization);
+                    }
+                    const approved = buildActionLedgerApprovedExecutionFields(authorization.approvedAction);
+                    const outcome = await issueInvoiceFromBookingCommand(db, command, {
+                        ...getFinanceRouteRuntime(c),
+                        actionLedgerContext: requestContext,
+                        actionLedgerAuthorizationSource: authorization.access.authorizationSource,
+                        actionLedgerActionName: FINANCE_INVOICE_ISSUE_ACTION_NAME,
+                        actionLedgerRouteOrToolName: FINANCE_INVOICE_ISSUE_TOOL_NAME,
+                        actionLedgerCapabilityId: FINANCE_INVOICE_ISSUE_CAPABILITY.id,
+                        actionLedgerCapabilityVersion: FINANCE_INVOICE_ISSUE_CAPABILITY.version,
+                        actionLedgerEvaluatedRisk: FINANCE_INVOICE_ISSUE_CAPABILITY.risk,
+                        actionLedgerCausationActionId: approved.causationActionId,
+                        actionLedgerApprovalId: approved.approvalId,
+                        actionLedgerIdempotencyScope: approved.idempotencyScope,
+                        actionLedgerIdempotencyKey: approved.idempotencyKey,
+                        actionLedgerIdempotencyFingerprint: approved.idempotencyFingerprint,
+                    });
+                    if (outcome.status !== "issued") {
+                        const subject = outcome.status === "booking_not_found" ? "Booking" : "Booking payment schedule";
+                        throw new ToolError(`${subject} was not found.`, "NOT_FOUND", { outcome });
+                    }
+                    return {
+                        status: "issued",
+                        invoice: toJsonValue(outcome.invoice),
+                        replayed: false,
+                    };
+                },
+                async issueInvoiceRefund(input) {
+                    const command = {
+                        creditNoteNumber: input.creditNoteNumber,
+                        status: "issued",
+                        amountCents: input.amountCents,
+                        currency: input.currency,
+                        baseCurrency: input.baseCurrency,
+                        baseAmountCents: input.baseAmountCents,
+                        fxRateSetId: input.fxRateSetId,
+                        reason: input.reason,
+                        notes: input.notes,
+                    };
+                    const requestContext = financeToolActionLedgerContext(c);
+                    const authorization = await authorizeFinanceRefund({
+                        db,
+                        invoiceId: input.invoiceId,
+                        commandInput: command,
+                        actor: c.get("actor"),
+                        callerType: c.get("callerType"),
+                        scopes: c.get("scopes"),
+                        isInternalRequest: c.get("isInternalRequest"),
+                        requestContext,
+                        approvalId: input.approvalId ?? null,
+                        idempotencyKey: input.idempotencyKey,
+                    });
+                    if (authorization.status === "approval_required") {
+                        return {
+                            status: "approval_required",
+                            requestedAction: {
+                                id: authorization.requestedAction.id,
+                                status: authorization.requestedAction.status,
+                                actionName: authorization.requestedAction.actionName,
+                                targetType: authorization.requestedAction.targetType,
+                                targetId: authorization.requestedAction.targetId,
+                            },
+                            approval: {
+                                id: authorization.approval.id,
+                                status: authorization.approval.status,
+                                requestedActionId: authorization.approval.requestedActionId,
+                                policyName: authorization.approval.policyName,
+                                policyVersion: authorization.approval.policyVersion,
+                                riskSnapshot: authorization.approval.riskSnapshot,
+                                reasonCode: authorization.approval.reasonCode,
+                                expiresAt: toIsoString(authorization.approval.expiresAt),
+                                createdAt: toIsoString(authorization.approval.createdAt),
+                            },
+                            replayed: authorization.replayed,
+                        };
+                    }
+                    if (authorization.status === "already_executed") {
+                        const creditNote = await financeService.getCreditNoteById(db, authorization.creditNoteId);
+                        if (!creditNote) {
+                            throw new ToolError("The previously issued credit note was not found.", "NOT_FOUND", {
+                                creditNoteId: authorization.creditNoteId,
+                            });
+                        }
+                        if (creditNote.invoiceId !== input.invoiceId || creditNote.status !== "issued") {
+                            throw new ToolError("The previous refund result does not match this issued invoice credit note.", "INVALID_INPUT", { creditNoteId: authorization.creditNoteId, invoiceId: input.invoiceId });
+                        }
+                        return {
+                            status: "issued",
+                            creditNote: toJsonValue(creditNote),
+                            replayed: true,
+                        };
+                    }
+                    if (authorization.status !== "authorized") {
+                        throw financeRefundAuthorizationError(authorization);
+                    }
+                    const approved = buildActionLedgerApprovedExecutionFields(authorization.approvedAction);
+                    const creditNote = await financeService.createCreditNote(db, input.invoiceId, command, {
+                        eventBus: c.get("eventBus"),
+                        actionLedgerContext: requestContext,
+                        actionLedgerAuthorizationSource: authorization.access.authorizationSource,
+                        actionLedgerActionName: FINANCE_REFUND_ACTION_NAME,
+                        actionLedgerRouteOrToolName: FINANCE_REFUND_ROUTE_OR_TOOL_NAME,
+                        actionLedgerTargetType: "invoice",
+                        actionLedgerTargetId: input.invoiceId,
+                        actionLedgerCapabilityId: FINANCE_REFUND_CAPABILITY.id,
+                        actionLedgerCapabilityVersion: FINANCE_REFUND_CAPABILITY.version,
+                        actionLedgerEvaluatedRisk: FINANCE_REFUND_CAPABILITY.risk,
+                        actionLedgerCausationActionId: approved.causationActionId,
+                        actionLedgerApprovalId: approved.approvalId,
+                        actionLedgerIdempotencyScope: approved.idempotencyScope,
+                        actionLedgerIdempotencyKey: approved.idempotencyKey,
+                        actionLedgerIdempotencyFingerprint: approved.idempotencyFingerprint,
+                    });
+                    if (!creditNote) {
+                        throw new ToolError(`Invoice "${input.invoiceId}" was not found.`, "NOT_FOUND", {
+                            invoiceId: input.invoiceId,
+                        });
+                    }
+                    return {
+                        status: "issued",
+                        creditNote: toJsonValue(creditNote),
+                        replayed: false,
+                    };
+                },
             },
         };
     },
 });
+function financeToolActionLedgerContext(c) {
+    return {
+        userId: c.get("userId") ?? null,
+        agentId: c.get("agentId") ?? null,
+        workflowPrincipalId: c.get("workflowPrincipalId") ?? null,
+        principalSubtype: c.get("principalSubtype") ?? null,
+        sessionId: c.get("sessionId") ?? null,
+        apiTokenId: c.get("apiTokenId") ?? c.get("apiKeyId") ?? null,
+        callerType: c.get("callerType") ?? null,
+        actor: c.get("actor") ?? null,
+        isInternalRequest: c.get("isInternalRequest") ?? false,
+        organizationId: c.get("organizationId") ?? null,
+        workflowRunId: c.get("workflowRunId") ?? null,
+        workflowStepId: c.get("workflowStepId") ?? null,
+        correlationId: c.req.header("x-correlation-id") ?? c.req.header("x-request-id") ?? null,
+    };
+}
+function financeRefundAuthorizationError(result) {
+    switch (result.status) {
+        case "denied":
+            return new ToolError("Invoice refund is not authorized.", "AUTHORIZATION_DENIED", {
+                reason: result.access.reason,
+            });
+        case "missing_idempotency_key":
+            return new ToolError("Invoice refund requires an idempotency key.", "INVALID_INPUT");
+        case "idempotency_conflict":
+            return new ToolError(result.message, "INVALID_INPUT", {
+                existingActionId: result.existingActionId,
+            });
+        case "invalid_approval":
+            return new ToolError("The approval does not authorize this exact invoice credit-note refund.", "INVALID_INPUT", {
+                reason: result.validation.reason,
+                approvalId: result.validation.approval?.id,
+            });
+    }
+}
+function pendingApprovalResult(input) {
+    return {
+        status: "approval_required",
+        requestedAction: {
+            id: input.requestedAction.id,
+            status: input.requestedAction.status,
+            actionName: input.requestedAction.actionName,
+            targetType: input.requestedAction.targetType,
+            targetId: input.requestedAction.targetId,
+        },
+        approval: {
+            id: input.approval.id,
+            status: input.approval.status,
+            requestedActionId: input.approval.requestedActionId,
+            policyName: input.approval.policyName,
+            policyVersion: input.approval.policyVersion,
+            riskSnapshot: input.approval.riskSnapshot,
+            reasonCode: input.approval.reasonCode ?? "approval_required",
+            expiresAt: toIsoString(input.approval.expiresAt),
+            createdAt: toIsoString(input.approval.createdAt),
+        },
+        replayed: input.replayed,
+    };
+}
+function financeInvoiceIssueAuthorizationError(result) {
+    switch (result.status) {
+        case "denied":
+            return new ToolError("Invoice issue is not authorized.", "AUTHORIZATION_DENIED", {
+                reason: result.access.reason,
+            });
+        case "missing_idempotency_key":
+            return new ToolError("Invoice issue requires an idempotency key.", "INVALID_INPUT");
+        case "idempotency_conflict":
+            return new ToolError(result.message, "INVALID_INPUT", {
+                existingActionId: result.existingActionId,
+            });
+        case "invalid_approval":
+            return new ToolError("The approval does not authorize this exact invoice issue command.", "INVALID_INPUT", { reason: result.validation.reason, approvalId: result.validation.approval?.id });
+    }
+}
+function toIsoString(value) {
+    if (!value)
+        return null;
+    return value instanceof Date ? value.toISOString() : value;
+}
+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/payment-schedule/routes.d.ts

@@ -23,7 +23,7 @@
  * `booking-schedule.ts`.
  */
 import { OpenAPIHono } from "@hono/zod-openapi";
-import type { HonoExtension } from "@voyant-travel/hono/module";
+import type { ApiExtension } from "@voyant-travel/hono/module";
 import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import type { Context } from "hono";
 import { type PaymentPolicy, type PaymentPolicySource } from "../payment-policy.js";
@@ -155,5 +155,5 @@ export declare function createPaymentPolicyPublicRoutes(options: BookingSchedule
     };
 }, "/">;
 /** Package-owned extension descriptor; deployments inject the policy cascade readers. */
-export declare function createBookingScheduleHonoExtension(options: BookingScheduleRoutesOptions): HonoExtension;
-export declare const createBookingScheduleVoyantRuntime: import("@voyant-travel/core/project").VoyantGraphRuntimeFactory<HonoExtension>;
+export declare function createBookingScheduleApiExtension(options: BookingScheduleRoutesOptions): ApiExtension;
+export declare const createBookingScheduleVoyantRuntime: import("@voyant-travel/core/project").VoyantGraphRuntimeFactory<ApiExtension>;

package/dist/payment-schedule/routes.js

@@ -363,7 +363,7 @@ export function createPaymentPolicyPublicRoutes(options) {
     return new OpenAPIHono({ defaultHook: openApiValidationHook }).openapi(resolvePolicyRoute, (c) => asRouteResponse(handleResolvePolicy(c, options, c.req.valid("json"))));
 }
 /** Package-owned extension descriptor; deployments inject the policy cascade readers. */
-export function createBookingScheduleHonoExtension(options) {
+export function createBookingScheduleApiExtension(options) {
     return {
         extension: { name: "booking-schedule", module: "bookings" },
         lazyAdminRoutes: async () => createBookingScheduleAdminRoutes(options),
@@ -374,7 +374,7 @@ export function createBookingScheduleHonoExtension(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 configured = createBookingScheduleHonoExtension(provider.options);
+    const configured = createBookingScheduleApiExtension(provider.options);
     const selected = {
         extension: {
             ...configured.extension,

package/dist/refund-authorization.d.ts

@@ -0,0 +1,68 @@
+/** Approval orchestration for issuing an invoice credit note as a refund. */
+import { type ActionLedgerCapabilityAccessResult, type ActionLedgerRequestContextValues, actionLedgerService, type BuildActionLedgerApprovedExecutionFieldsInput, requestActionLedgerApproval } from "@voyant-travel/action-ledger";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+export declare const FINANCE_REFUND_CAPABILITY: {
+    readonly id: "finance:refund";
+    readonly version: "v1";
+    readonly resource: "invoice";
+    readonly action: "refund";
+    readonly risk: "critical";
+    readonly ledgerPolicy: "required";
+    readonly approvalPolicy: "required";
+    readonly reversible: false;
+    readonly allowedActorTypes: readonly ["staff", "system"];
+    readonly requiredGrants: readonly [{
+        readonly resource: "finance";
+        readonly action: "refund";
+    }];
+};
+export declare const FINANCE_REFUND_APPROVAL_POLICY = "finance-credit-note-refund-approval-v1";
+export declare const FINANCE_REFUND_ACTION_NAME = "finance.credit_note.issue_refund";
+export declare const FINANCE_REFUND_ROUTE_OR_TOOL_NAME = "finance.issue_invoice_refund";
+export interface FinanceRefundAuthorizationInput {
+    db: PostgresJsDatabase;
+    invoiceId: string;
+    commandInput: unknown;
+    actor?: string | null;
+    callerType?: string | null;
+    scopes?: readonly string[] | null;
+    isInternalRequest?: boolean | null;
+    requestContext: ActionLedgerRequestContextValues;
+    approvalId?: string | null;
+    idempotencyKey?: string | null;
+}
+export type FinanceRefundAuthorizationResult = {
+    status: "authorized";
+    access: ActionLedgerCapabilityAccessResult;
+    approvedAction: BuildActionLedgerApprovedExecutionFieldsInput;
+} | {
+    status: "approval_required";
+    access: ActionLedgerCapabilityAccessResult;
+    requestedAction: Awaited<ReturnType<typeof requestActionLedgerApproval>>["requestedAction"];
+    approval: Awaited<ReturnType<typeof requestActionLedgerApproval>>["approval"];
+    replayed: boolean;
+} | {
+    status: "already_executed";
+    access: ActionLedgerCapabilityAccessResult;
+    creditNoteId: string;
+} | {
+    status: "denied";
+    access: ActionLedgerCapabilityAccessResult;
+} | {
+    status: "missing_idempotency_key";
+    access: ActionLedgerCapabilityAccessResult;
+} | {
+    status: "idempotency_conflict";
+    access: ActionLedgerCapabilityAccessResult;
+    message: string;
+    existingActionId: string;
+} | {
+    status: "invalid_approval";
+    access: ActionLedgerCapabilityAccessResult;
+    validation: Exclude<Awaited<ReturnType<typeof actionLedgerService.validateApprovedAction>>, {
+        ok: true;
+    }>;
+};
+export declare function authorizeFinanceRefund(input: FinanceRefundAuthorizationInput): Promise<FinanceRefundAuthorizationResult>;
+export declare function parseCreditNoteCommandResultRef(resultRef: string | null): string | null;
+export declare function resolveExecutedRefundCreditNoteId(db: PostgresJsDatabase, existingActionId: string): Promise<string | null>;

package/dist/refund-authorization.js

@@ -0,0 +1,184 @@
+/** Approval orchestration for issuing an invoice credit note as a refund. */
+import { ActionLedgerIdempotencyConflictError, actionLedgerService, appendActionLedgerMutation, buildActionApprovalCommandFingerprint, evaluateActionLedgerApprovalRequirement, evaluateActionLedgerCapabilityAccess, mapActionLedgerRequestContext, requestActionLedgerApproval, } from "@voyant-travel/action-ledger";
+import { financeService } from "./service.js";
+export const FINANCE_REFUND_CAPABILITY = {
+    id: "finance:refund",
+    version: "v1",
+    resource: "invoice",
+    action: "refund",
+    risk: "critical",
+    ledgerPolicy: "required",
+    approvalPolicy: "required",
+    reversible: false,
+    allowedActorTypes: ["staff", "system"],
+    requiredGrants: [{ resource: "finance", action: "refund" }],
+};
+export const FINANCE_REFUND_APPROVAL_POLICY = "finance-credit-note-refund-approval-v1";
+export const FINANCE_REFUND_ACTION_NAME = "finance.credit_note.issue_refund";
+export const FINANCE_REFUND_ROUTE_OR_TOOL_NAME = "finance.issue_invoice_refund";
+export async function authorizeFinanceRefund(input) {
+    const access = evaluateActionLedgerCapabilityAccess({
+        definition: FINANCE_REFUND_CAPABILITY,
+        actor: input.actor,
+        callerType: input.callerType,
+        scopes: input.scopes,
+        isInternalRequest: input.isInternalRequest,
+    });
+    if (!access.allowed) {
+        await appendActionLedgerMutation(input.db, {
+            context: input.requestContext,
+            actionName: FINANCE_REFUND_ACTION_NAME,
+            actionVersion: FINANCE_REFUND_CAPABILITY.version,
+            actionKind: "create",
+            status: "denied",
+            evaluatedRisk: access.evaluatedRisk,
+            targetType: "invoice",
+            targetId: input.invoiceId,
+            routeOrToolName: FINANCE_REFUND_ROUTE_OR_TOOL_NAME,
+            capabilityId: access.capabilityId,
+            capabilityVersion: access.capabilityVersion,
+            authorizationSource: access.authorizationSource,
+            mutationDetail: {
+                summary: `Invoice refund denied: ${access.reason}`,
+                reversalKind: "none",
+            },
+        });
+        return { status: "denied", access };
+    }
+    const approvalRequirement = evaluateActionLedgerApprovalRequirement({
+        access,
+        conditionalApprovalRequired: true,
+        reasonCode: "invoice_credit_note_refund_requested_by_agent",
+    });
+    const targetState = await loadInvoiceRefundTargetState(input.db, input.invoiceId);
+    const fingerprint = await buildActionApprovalCommandFingerprint({
+        actionName: FINANCE_REFUND_ACTION_NAME,
+        actionVersion: FINANCE_REFUND_CAPABILITY.version,
+        targetType: "invoice",
+        targetId: input.invoiceId,
+        commandInput: { command: input.commandInput, targetState },
+        approvalPolicy: approvalRequirement.approvalPolicy,
+        capabilityId: access.capabilityId,
+        capabilityVersion: access.capabilityVersion,
+        evaluatedRisk: approvalRequirement.evaluatedRisk,
+        reasonCode: approvalRequirement.reasonCode,
+    });
+    if (input.approvalId) {
+        const principal = mapActionLedgerRequestContext(input.requestContext);
+        const validation = await actionLedgerService.validateApprovedAction(input.db, {
+            approvalId: input.approvalId,
+            actionName: FINANCE_REFUND_ACTION_NAME,
+            actionVersion: FINANCE_REFUND_CAPABILITY.version,
+            requestedActionKind: "create",
+            requestedActionStatus: "awaiting_approval",
+            targetType: "invoice",
+            targetId: input.invoiceId,
+            routeOrToolName: FINANCE_REFUND_ROUTE_OR_TOOL_NAME,
+            principalType: principal.principalType,
+            principalId: principal.principalId,
+            idempotencyFingerprint: fingerprint,
+            executionActionKind: "create",
+            executionStatus: "succeeded",
+        });
+        if (!validation.ok) {
+            const requestedAction = validation.requestedAction;
+            const isExactReplay = validation.reason === "already_executed" &&
+                requestedAction !== undefined &&
+                requestedAction.idempotencyFingerprint === fingerprint &&
+                (!principal.principalType ||
+                    !principal.principalId ||
+                    (requestedAction.principalType === principal.principalType &&
+                        requestedAction.principalId === principal.principalId));
+            if (isExactReplay && validation.existingActionId) {
+                const creditNoteId = await resolveExecutedRefundCreditNoteId(input.db, validation.existingActionId);
+                if (creditNoteId)
+                    return { status: "already_executed", access, creditNoteId };
+            }
+            return { status: "invalid_approval", access, validation };
+        }
+        return {
+            status: "authorized",
+            access,
+            approvedAction: {
+                requestedActionId: validation.requestedAction.id,
+                approvalId: validation.approval.id,
+                idempotencyFingerprint: validation.idempotencyFingerprint,
+            },
+        };
+    }
+    if (!input.idempotencyKey)
+        return { status: "missing_idempotency_key", access };
+    try {
+        const result = await requestActionLedgerApproval(input.db, {
+            context: input.requestContext,
+            actionName: FINANCE_REFUND_ACTION_NAME,
+            actionVersion: FINANCE_REFUND_CAPABILITY.version,
+            actionKind: "create",
+            evaluatedRisk: approvalRequirement.evaluatedRisk,
+            targetType: "invoice",
+            targetId: input.invoiceId,
+            routeOrToolName: FINANCE_REFUND_ROUTE_OR_TOOL_NAME,
+            capabilityId: access.capabilityId,
+            capabilityVersion: access.capabilityVersion,
+            authorizationSource: access.authorizationSource,
+            idempotencyScope: `${FINANCE_REFUND_ROUTE_OR_TOOL_NAME}:${input.invoiceId}`,
+            idempotencyKey: input.idempotencyKey,
+            idempotencyFingerprint: fingerprint,
+            mutationDetail: {
+                summary: "Invoice credit-note refund awaiting approval",
+                reversalKind: "none",
+            },
+            approval: {
+                policyName: FINANCE_REFUND_APPROVAL_POLICY,
+                policyVersion: FINANCE_REFUND_CAPABILITY.version,
+                riskSnapshot: approvalRequirement.evaluatedRisk,
+                reasonCode: approvalRequirement.reasonCode,
+            },
+        });
+        return {
+            status: "approval_required",
+            access,
+            requestedAction: result.requestedAction,
+            approval: result.approval,
+            replayed: result.replayed,
+        };
+    }
+    catch (error) {
+        if (error instanceof ActionLedgerIdempotencyConflictError) {
+            return {
+                status: "idempotency_conflict",
+                access,
+                message: error.message,
+                existingActionId: error.existingActionId,
+            };
+        }
+        throw error;
+    }
+}
+export function parseCreditNoteCommandResultRef(resultRef) {
+    const prefix = "credit_note:";
+    if (!resultRef?.startsWith(prefix))
+        return null;
+    const creditNoteId = resultRef.slice(prefix.length).trim();
+    return creditNoteId || null;
+}
+export async function resolveExecutedRefundCreditNoteId(db, existingActionId) {
+    const existing = await actionLedgerService.getEntry(db, existingActionId);
+    return parseCreditNoteCommandResultRef(existing?.mutationDetail?.commandResultRef ?? null);
+}
+async function loadInvoiceRefundTargetState(db, invoiceId) {
+    const invoice = await financeService.getInvoiceById(db, invoiceId);
+    if (!invoice)
+        return { exists: false };
+    return {
+        exists: true,
+        status: invoice.status,
+        invoiceType: invoice.invoiceType,
+        invoiceNumber: invoice.invoiceNumber,
+        currency: invoice.currency,
+        totalCents: invoice.totalCents,
+        paidCents: invoice.paidCents,
+        balanceDueCents: invoice.balanceDueCents,
+        updatedAt: invoice.updatedAt.toISOString(),
+    };
+}

package/dist/routes-booking-create.d.ts

@@ -1,2 +1,2 @@
-import type { HonoExtension } from "@voyant-travel/hono/module";
-export declare const bookingsCreateExtension: HonoExtension;
+import type { ApiExtension } from "@voyant-travel/hono/module";
+export declare const bookingsCreateExtension: ApiExtension;