@voyant-travel/finance 0.159.0 → 0.161.0

package/README.md

@@ -2,6 +2,29 @@
 
 Finance module for Voyant. Invoices, payments, credit notes, supplier payments, and finance notes.
 
+## Composed agent commands
+
+`create_booking` is owned by the Finance booking-create extension because that package
+already owns the atomic composer spanning product conversion, travelers, room/item
+lines, payment schedules, optional credits and group membership, invoices, ledger
+records, and post-commit events. The Tool is a structural adapter over that service.
+
+`issue_invoice_from_booking` creates and issues either an invoice or proforma through
+the same package-owned composer used by the HTTP route. Agent execution requires an
+idempotency key and exact approval. Approved execution records approval and causation
+in the action ledger; replaying an already executed approval returns the original
+invoice rather than issuing a duplicate.
+
+## Agent Tools
+
+`issue_invoice_refund` defines a refund as issuing an `issued` credit note
+against an invoice through the existing credit-note domain service. Agent
+callers cannot issue it directly: the first call creates a pending action-ledger
+approval, and execution requires the approved id plus an exact match on the
+principal, command, current invoice snapshot, and fingerprint. Successful
+execution is recorded as `finance.credit_note.issue_refund`, linked to the
+requested action and approval, and requires `finance:refund`.
+
 ## Install
 
 ```bash

package/dist/invoice-issue-authorization.d.ts

@@ -0,0 +1,69 @@
+/** Exact approval and idempotency orchestration for invoice issue Tools. */
+import { type ActionLedgerCapabilityAccessResult, type ActionLedgerRequestContextValues, actionLedgerService, type BuildActionLedgerApprovedExecutionFieldsInput, requestActionLedgerApproval } from "@voyant-travel/action-ledger";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { CreateInvoiceFromBookingInput } from "./service.js";
+export declare const FINANCE_INVOICE_ISSUE_CAPABILITY: {
+    readonly id: "finance:invoice-issue-from-booking";
+    readonly version: "v1";
+    readonly resource: "finance";
+    readonly action: "write";
+    readonly risk: "high";
+    readonly ledgerPolicy: "required";
+    readonly approvalPolicy: "required";
+    readonly reversible: false;
+    readonly allowedActorTypes: readonly ["staff", "system"];
+    readonly requiredGrants: readonly [{
+        readonly resource: "finance";
+        readonly action: "write";
+    }, {
+        readonly resource: "bookings";
+        readonly action: "read";
+    }];
+};
+export declare const FINANCE_INVOICE_ISSUE_APPROVAL_POLICY = "finance-invoice-issue-approval-v1";
+export declare const FINANCE_INVOICE_ISSUE_ACTION_NAME = "finance.invoice.issue_from_booking";
+export declare const FINANCE_INVOICE_ISSUE_TOOL_NAME = "finance.issue_invoice_from_booking";
+export interface FinanceInvoiceIssueAuthorizationInput {
+    db: PostgresJsDatabase;
+    commandInput: CreateInvoiceFromBookingInput;
+    actor?: string | null;
+    callerType?: string | null;
+    scopes?: readonly string[] | null;
+    isInternalRequest?: boolean | null;
+    requestContext: ActionLedgerRequestContextValues;
+    approvalId?: string | null;
+    idempotencyKey?: string | null;
+}
+export type FinanceInvoiceIssueAuthorizationResult = {
+    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;
+    invoiceId: 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 authorizeFinanceInvoiceIssue(input: FinanceInvoiceIssueAuthorizationInput): Promise<FinanceInvoiceIssueAuthorizationResult>;

package/dist/invoice-issue-authorization.js

@@ -0,0 +1,156 @@
+/** Exact approval and idempotency orchestration for invoice issue Tools. */
+import { ActionLedgerIdempotencyConflictError, actionLedgerService, appendActionLedgerMutation, buildActionApprovalCommandFingerprint, evaluateActionLedgerApprovalRequirement, evaluateActionLedgerCapabilityAccess, mapActionLedgerRequestContext, requestActionLedgerApproval, } from "@voyant-travel/action-ledger";
+export const FINANCE_INVOICE_ISSUE_CAPABILITY = {
+    id: "finance:invoice-issue-from-booking",
+    version: "v1",
+    resource: "finance",
+    action: "write",
+    risk: "high",
+    ledgerPolicy: "required",
+    approvalPolicy: "required",
+    reversible: false,
+    allowedActorTypes: ["staff", "system"],
+    requiredGrants: [
+        { resource: "finance", action: "write" },
+        { resource: "bookings", action: "read" },
+    ],
+};
+export const FINANCE_INVOICE_ISSUE_APPROVAL_POLICY = "finance-invoice-issue-approval-v1";
+export const FINANCE_INVOICE_ISSUE_ACTION_NAME = "finance.invoice.issue_from_booking";
+export const FINANCE_INVOICE_ISSUE_TOOL_NAME = "finance.issue_invoice_from_booking";
+export async function authorizeFinanceInvoiceIssue(input) {
+    const access = evaluateActionLedgerCapabilityAccess({
+        definition: FINANCE_INVOICE_ISSUE_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_INVOICE_ISSUE_ACTION_NAME,
+            actionVersion: FINANCE_INVOICE_ISSUE_CAPABILITY.version,
+            actionKind: "create",
+            status: "denied",
+            evaluatedRisk: access.evaluatedRisk,
+            targetType: "booking",
+            targetId: input.commandInput.bookingId,
+            routeOrToolName: FINANCE_INVOICE_ISSUE_TOOL_NAME,
+            capabilityId: access.capabilityId,
+            capabilityVersion: access.capabilityVersion,
+            authorizationSource: access.authorizationSource,
+            mutationDetail: {
+                summary: `Invoice issue denied: ${access.reason}`,
+                reversalKind: "none",
+            },
+        });
+        return { status: "denied", access };
+    }
+    const approvalRequirement = evaluateActionLedgerApprovalRequirement({
+        access,
+        conditionalApprovalRequired: true,
+        reasonCode: "invoice_issue_from_booking_requested_by_agent",
+    });
+    const fingerprint = await buildActionApprovalCommandFingerprint({
+        actionName: FINANCE_INVOICE_ISSUE_ACTION_NAME,
+        actionVersion: FINANCE_INVOICE_ISSUE_CAPABILITY.version,
+        targetType: "booking",
+        targetId: input.commandInput.bookingId,
+        commandInput: input.commandInput,
+        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_INVOICE_ISSUE_ACTION_NAME,
+            actionVersion: FINANCE_INVOICE_ISSUE_CAPABILITY.version,
+            requestedActionKind: "create",
+            requestedActionStatus: "awaiting_approval",
+            targetType: "booking",
+            targetId: input.commandInput.bookingId,
+            routeOrToolName: FINANCE_INVOICE_ISSUE_TOOL_NAME,
+            principalType: principal.principalType,
+            principalId: principal.principalId,
+            idempotencyFingerprint: fingerprint,
+            executionActionKind: "create",
+            executionStatus: "succeeded",
+        });
+        if (!validation.ok) {
+            if (validation.reason === "already_executed" && validation.existingActionId) {
+                const existing = await actionLedgerService.getEntry(input.db, validation.existingActionId);
+                const resultRef = existing?.mutationDetail?.commandResultRef;
+                if (resultRef?.startsWith("invoice:")) {
+                    return {
+                        status: "already_executed",
+                        access,
+                        invoiceId: resultRef.slice("invoice:".length),
+                    };
+                }
+            }
+            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_INVOICE_ISSUE_ACTION_NAME,
+            actionVersion: FINANCE_INVOICE_ISSUE_CAPABILITY.version,
+            actionKind: "create",
+            evaluatedRisk: approvalRequirement.evaluatedRisk,
+            targetType: "booking",
+            targetId: input.commandInput.bookingId,
+            routeOrToolName: FINANCE_INVOICE_ISSUE_TOOL_NAME,
+            capabilityId: access.capabilityId,
+            capabilityVersion: access.capabilityVersion,
+            authorizationSource: access.authorizationSource,
+            idempotencyScope: `${FINANCE_INVOICE_ISSUE_TOOL_NAME}:${input.commandInput.bookingId}`,
+            idempotencyKey: input.idempotencyKey,
+            idempotencyFingerprint: fingerprint,
+            mutationDetail: {
+                summary: "Invoice issue from booking awaiting approval",
+                reversalKind: "none",
+            },
+            approval: {
+                policyName: FINANCE_INVOICE_ISSUE_APPROVAL_POLICY,
+                policyVersion: FINANCE_INVOICE_ISSUE_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;
+    }
+}

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/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>;