@voyant-travel/finance 0.158.0 → 0.161.0

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-invoice-issue.js

@@ -155,83 +155,11 @@ financeInvoiceIssueRoutes
     .openapi(issueInvoiceFromBookingRoute, async (c) => {
     const input = c.req.valid("json");
     const db = c.get("db");
-    const [{ bookingItems, bookings }, { bookingPaymentSchedules }, { and, asc, eq }, { issueInvoiceFromBooking, issueProformaFromBooking },] = await Promise.all([
-        import("@voyant-travel/bookings/schema"),
-        import("./schema.js"),
-        import("drizzle-orm"),
-        import("./service-issue.js"),
-    ]);
-    const [booking] = await db
-        .select()
-        .from(bookings)
-        .where(eq(bookings.id, input.bookingId))
-        .limit(1);
-    if (!booking) {
-        return c.json({ error: "Booking not found" }, 404);
-    }
-    const items = await db
-        .select()
-        .from(bookingItems)
-        .where(eq(bookingItems.bookingId, booking.id))
-        .orderBy(asc(bookingItems.createdAt), asc(bookingItems.id));
-    const [paymentSchedule] = input.bookingPaymentScheduleId
-        ? await db
-            .select()
-            .from(bookingPaymentSchedules)
-            .where(and(eq(bookingPaymentSchedules.id, input.bookingPaymentScheduleId), eq(bookingPaymentSchedules.bookingId, booking.id)))
-            .limit(1)
-        : [];
-    if (input.bookingPaymentScheduleId && !paymentSchedule) {
-        return c.json({ error: "Booking payment schedule not found" }, 404);
-    }
     const runtime = getFinanceRouteRuntime(c);
-    const issuer = input.invoiceType === "proforma" ? issueProformaFromBooking : issueInvoiceFromBooking;
-    let row;
+    const { issueInvoiceFromBookingCommand } = await import("./service-issue.js");
+    let outcome;
     try {
-        row = await issuer(db, input, {
-            booking: {
-                id: booking.id,
-                bookingNumber: booking.bookingNumber,
-                personId: booking.personId,
-                organizationId: booking.organizationId,
-                startDate: booking.startDate,
-                endDate: booking.endDate,
-                sellCurrency: booking.sellCurrency,
-                baseCurrency: booking.baseCurrency,
-                fxRateSetId: booking.fxRateSetId,
-                sellAmountCents: booking.sellAmountCents,
-                baseSellAmountCents: booking.baseSellAmountCents,
-            },
-            paymentSchedule: paymentSchedule
-                ? {
-                    id: paymentSchedule.id,
-                    bookingId: paymentSchedule.bookingId,
-                    bookingItemId: paymentSchedule.bookingItemId,
-                    scheduleType: paymentSchedule.scheduleType,
-                    dueDate: paymentSchedule.dueDate,
-                    currency: paymentSchedule.currency,
-                    amountCents: paymentSchedule.amountCents,
-                }
-                : null,
-            items: items.map((item) => ({
-                id: item.id,
-                title: item.title,
-                productId: item.productId,
-                productName: item.productNameSnapshot,
-                productNameSnapshot: item.productNameSnapshot,
-                optionNameSnapshot: item.optionNameSnapshot,
-                unitNameSnapshot: item.unitNameSnapshot,
-                departureLabelSnapshot: item.departureLabelSnapshot,
-                startDate: item.serviceDate ?? item.startsAt,
-                serviceDate: item.serviceDate,
-                startsAt: item.startsAt,
-                endDate: item.endsAt ?? item.serviceDate,
-                endsAt: item.endsAt,
-                quantity: item.quantity,
-                unitSellAmountCents: item.unitSellAmountCents,
-                totalSellAmountCents: item.totalSellAmountCents,
-            })),
-        }, {
+        outcome = await issueInvoiceFromBookingCommand(db, input, {
             ...(runtime ?? {}),
             actionLedgerContext: getActionLedgerRequestContext(c),
             actionLedgerAuthorizationSource: "finance.invoice.from_booking.route",
@@ -253,7 +181,13 @@ financeInvoiceIssueRoutes
         }
         throw error;
     }
-    return c.json({ data: row }, 201);
+    if (outcome.status === "booking_not_found") {
+        return c.json({ error: "Booking not found" }, 404);
+    }
+    if (outcome.status === "payment_schedule_not_found") {
+        return c.json({ error: "Booking payment schedule not found" }, 404);
+    }
+    return c.json({ data: outcome.invoice }, 201);
 })
     .openapi(convertProformaToInvoiceRoute, async (c) => {
     const { convertProformaToInvoice } = await import("./service-issue.js");

package/dist/routes-runtime.d.ts

@@ -24,6 +24,7 @@ export declare const routeIdempotencyKey: (scope: string, options?: {
         organizationId?: string | null;
         callerType?: "session" | "api_key" | "internal" | "agent" | "workflow";
         actor?: string;
+        scopes?: string[] | null;
         apiTokenId?: string;
         apiKeyId?: string;
         workflowRunId?: string;

package/dist/routes-shared.d.ts

@@ -20,6 +20,7 @@ export type Env = {
         organizationId?: string | null;
         callerType?: "session" | "api_key" | "internal" | "agent" | "workflow";
         actor?: string;
+        scopes?: string[] | null;
         apiTokenId?: string;
         apiKeyId?: string;
         workflowRunId?: string;

package/dist/service-action-ledger-accounting.d.ts

@@ -75,6 +75,16 @@ export declare function buildPaymentDeleteActionLedgerInput(context: ActionLedge
 }): BuildActionLedgerMutationInput;
 export declare function buildInvoiceIssuedActionLedgerInput(context: ActionLedgerRequestContextValues, input: InvoiceIssuedLedgerInput, options?: {
     authorizationSource?: string | null;
+    actionName?: string | null;
+    routeOrToolName?: string | null;
+    capabilityId?: string | null;
+    capabilityVersion?: string | null;
+    evaluatedRisk?: "low" | "medium" | "high" | "critical" | null;
+    causationActionId?: string | null;
+    approvalId?: string | null;
+    idempotencyScope?: string | null;
+    idempotencyKey?: string | null;
+    idempotencyFingerprint?: string | null;
 }): Promise<BuildActionLedgerMutationInput>;
 export declare function buildInvoiceUpdateActionLedgerInput(context: ActionLedgerRequestContextValues, input: InvoiceUpdateLedgerInput, options?: {
     authorizationSource?: string | null;
@@ -93,6 +103,18 @@ export declare function buildInvoiceLineItemDeleteActionLedgerInput(context: Act
 }): BuildActionLedgerMutationInput;
 export declare function buildCreditNoteCreationActionLedgerInput(context: ActionLedgerRequestContextValues, input: CreateCreditNoteLedgerInput, options?: {
     authorizationSource?: string | null;
+    actionName?: string | null;
+    routeOrToolName?: string | null;
+    targetType?: string | null;
+    targetId?: string | null;
+    capabilityId?: string | null;
+    capabilityVersion?: string | null;
+    evaluatedRisk?: BuildActionLedgerMutationInput["evaluatedRisk"] | null;
+    causationActionId?: string | null;
+    approvalId?: string | null;
+    idempotencyScope?: string | null;
+    idempotencyKey?: string | null;
+    idempotencyFingerprint?: string | null;
 }): Promise<BuildActionLedgerMutationInput>;
 export declare function buildCreditNoteUpdateActionLedgerInput(context: ActionLedgerRequestContextValues, input: CreditNoteUpdateLedgerInput, options?: {
     authorizationSource?: string | null;

package/dist/service-action-ledger-accounting.js

@@ -133,36 +133,42 @@ function getInvoiceLedgerTarget(invoice) {
 export async function buildInvoiceIssuedActionLedgerInput(context, input, options = {}) {
     const target = getInvoiceLedgerTarget(input.invoice);
     const invoiceTypeLabel = input.invoice.invoiceType === "proforma" ? "Proforma" : "Invoice";
+    const actionName = options.actionName ?? "finance.invoice.issue_from_booking";
     return {
         context,
-        actionName: "finance.invoice.issue_from_booking",
+        actionName,
         actionVersion: "v1",
         actionKind: "create",
         status: "succeeded",
-        evaluatedRisk: "high",
+        evaluatedRisk: options.evaluatedRisk ?? "high",
         targetType: target.type,
         targetId: target.id,
-        routeOrToolName: "finance.invoice.issue_from_booking",
+        routeOrToolName: options.routeOrToolName ?? "finance.invoice.issue_from_booking",
+        capabilityId: options.capabilityId,
+        capabilityVersion: options.capabilityVersion,
         authorizationSource: options.authorizationSource ?? "finance.invoice.from_booking.route",
-        idempotencyScope: `finance.booking:${input.invoice.bookingId}:invoice_issue`,
-        idempotencyKey: input.invoice.invoiceNumber,
-        idempotencyFingerprint: await buildIdempotencyFingerprint({
-            actionName: "finance.invoice.issue_from_booking",
-            actionVersion: "v1",
-            targetType: target.type,
-            targetId: target.id,
-            commandInput: {
-                invoiceId: input.invoice.id,
-                invoiceNumber: input.invoice.invoiceNumber,
-                invoiceType: input.invoice.invoiceType,
-                bookingId: input.invoice.bookingId,
-                totalCents: input.invoice.totalCents,
-                currency: input.invoice.currency,
-                status: input.invoice.status,
-                issueDate: input.invoice.issueDate,
-                dueDate: input.invoice.dueDate,
-            },
-        }),
+        causationActionId: options.causationActionId,
+        approvalId: options.approvalId,
+        idempotencyScope: options.idempotencyScope ?? `finance.booking:${input.invoice.bookingId}:invoice_issue`,
+        idempotencyKey: options.idempotencyKey ?? input.invoice.invoiceNumber,
+        idempotencyFingerprint: options.idempotencyFingerprint ??
+            (await buildIdempotencyFingerprint({
+                actionName,
+                actionVersion: "v1",
+                targetType: target.type,
+                targetId: target.id,
+                commandInput: {
+                    invoiceId: input.invoice.id,
+                    invoiceNumber: input.invoice.invoiceNumber,
+                    invoiceType: input.invoice.invoiceType,
+                    bookingId: input.invoice.bookingId,
+                    totalCents: input.invoice.totalCents,
+                    currency: input.invoice.currency,
+                    status: input.invoice.status,
+                    issueDate: input.invoice.issueDate,
+                    dueDate: input.invoice.dueDate,
+                },
+            })),
         mutationDetail: {
             commandInputRef: `booking:${input.invoice.bookingId}:invoice_issue`,
             commandResultRef: `invoice:${input.invoice.id}`,
@@ -297,35 +303,43 @@ export function buildInvoiceLineItemDeleteActionLedgerInput(context, input, opti
 }
 export async function buildCreditNoteCreationActionLedgerInput(context, input, options = {}) {
     const target = getInvoiceLedgerTarget(input.invoice);
-    const idempotencyKey = input.creditNote.creditNoteNumber;
+    const targetType = options.targetType ?? target.type;
+    const targetId = options.targetId ?? target.id;
+    const actionName = options.actionName ?? "finance.credit_note.create";
+    const idempotencyKey = options.idempotencyKey ?? input.creditNote.creditNoteNumber;
     return {
         context,
-        actionName: "finance.credit_note.create",
-        actionVersion: "v1",
+        actionName,
+        actionVersion: options.capabilityVersion ?? "v1",
         actionKind: "create",
         status: "succeeded",
-        evaluatedRisk: "high",
-        targetType: target.type,
-        targetId: target.id,
-        routeOrToolName: "finance.credit_note.create",
+        evaluatedRisk: options.evaluatedRisk ?? "high",
+        targetType,
+        targetId,
+        routeOrToolName: options.routeOrToolName ?? "finance.credit_note.create",
+        capabilityId: options.capabilityId ?? null,
+        capabilityVersion: options.capabilityVersion ?? null,
         authorizationSource: options.authorizationSource ?? "finance.credit_note.route",
-        idempotencyScope: `finance.invoice:${input.invoice.id}:credit_note`,
+        causationActionId: options.causationActionId ?? null,
+        approvalId: options.approvalId ?? null,
+        idempotencyScope: options.idempotencyScope ?? `finance.invoice:${input.invoice.id}:credit_note`,
         idempotencyKey,
-        idempotencyFingerprint: await buildIdempotencyFingerprint({
-            actionName: "finance.credit_note.create",
-            actionVersion: "v1",
-            targetType: target.type,
-            targetId: target.id,
-            commandInput: {
-                invoiceId: input.invoice.id,
-                creditNoteId: input.creditNote.id,
-                creditNoteNumber: input.creditNote.creditNoteNumber,
-                amountCents: input.creditNote.amountCents,
-                currency: input.creditNote.currency,
-                status: input.creditNote.status,
-                reason: input.creditNote.reason,
-            },
-        }),
+        idempotencyFingerprint: options.idempotencyFingerprint ??
+            (await buildIdempotencyFingerprint({
+                actionName,
+                actionVersion: options.capabilityVersion ?? "v1",
+                targetType,
+                targetId,
+                commandInput: {
+                    invoiceId: input.invoice.id,
+                    creditNoteId: input.creditNote.id,
+                    creditNoteNumber: input.creditNote.creditNoteNumber,
+                    amountCents: input.creditNote.amountCents,
+                    currency: input.creditNote.currency,
+                    status: input.creditNote.status,
+                    reason: input.creditNote.reason,
+                },
+            })),
         mutationDetail: {
             commandInputRef: `invoice:${input.invoice.id}:credit_note`,
             commandResultRef: `credit_note:${input.creditNote.id}`,

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

@@ -34,6 +34,7 @@ export declare const bookingCreateSchema: z.ZodObject<{
     productId: z.ZodString;
     optionId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
     slotId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    availabilityHoldToken: z.ZodOptional<z.ZodString>;
     bookingNumber: z.ZodString;
     personId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
     organizationId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
@@ -240,6 +241,7 @@ export declare const bookingCreateSubSchema: z.ZodObject<{
         travelerIndexes: z.ZodNullable<z.ZodOptional<z.ZodArray<z.ZodNumber>>>;
     }, z.core.$strip>>>;
     slotId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+    availabilityHoldToken: z.ZodOptional<z.ZodString>;
     sellAmountCentsOverride: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
     catalogSellAmountCents: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
     confirmedSellAmountCents: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;

package/dist/service-booking-create.js

@@ -256,6 +256,8 @@ const bookingCreateBaseSchema = z.object({
     productId: z.string().min(1),
     optionId: z.string().optional().nullable(),
     slotId: z.string().optional().nullable(),
+    /** Pre-booking availability hold converted inside the create transaction. */
+    availabilityHoldToken: z.string().min(1).optional(),
     bookingNumber: z.string().min(1),
     personId: z.string().optional().nullable(),
     organizationId: z.string().optional().nullable(),
@@ -924,7 +926,7 @@ export async function createBooking(db, rawInput, options = {}) {
                 contactAddressLine2: input.contactAddressLine2 ?? null,
                 contactPostalCode: input.contactPostalCode ?? null,
                 itemLines: normalizedItemLines,
-            });
+            }, userId, { availabilityHoldToken: input.availabilityHoldToken });
             if (!booking) {
                 // Caller gave us a product that doesn't resolve. Throw so drizzle
                 // rolls back any writes the convert helper may have made.

package/dist/service-bookings-dual-create.d.ts

@@ -76,6 +76,7 @@ export declare const dualCreateBookingSchema: z.ZodObject<{
             travelerIndexes: z.ZodNullable<z.ZodOptional<z.ZodArray<z.ZodNumber>>>;
         }, z.core.$strip>>>;
         slotId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        availabilityHoldToken: z.ZodOptional<z.ZodString>;
         sellAmountCentsOverride: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
         catalogSellAmountCents: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
         confirmedSellAmountCents: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
@@ -197,6 +198,7 @@ export declare const dualCreateBookingSchema: z.ZodObject<{
             travelerIndexes: z.ZodNullable<z.ZodOptional<z.ZodArray<z.ZodNumber>>>;
         }, z.core.$strip>>>;
         slotId: z.ZodNullable<z.ZodOptional<z.ZodString>>;
+        availabilityHoldToken: z.ZodOptional<z.ZodString>;
         sellAmountCentsOverride: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
         catalogSellAmountCents: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;
         confirmedSellAmountCents: z.ZodNullable<z.ZodOptional<z.ZodNumber>>;

package/dist/service-invoice-credit-notes.d.ts

@@ -459,6 +459,21 @@ export declare const financeInvoiceCreditNoteService: {
             generated: undefined;
         }, {}, {}>;
     }>, "where" | "orderBy">;
+    getCreditNoteById(db: PostgresJsDatabase, creditNoteId: string): Promise<{
+        id: string;
+        creditNoteNumber: string;
+        invoiceId: string;
+        status: "draft" | "issued" | "applied";
+        amountCents: number;
+        currency: string;
+        baseCurrency: string | null;
+        baseAmountCents: number | null;
+        fxRateSetId: string | null;
+        reason: string;
+        notes: string | null;
+        createdAt: Date;
+        updatedAt: Date;
+    } | null>;
     createCreditNote(db: PostgresJsDatabase, invoiceId: string, data: CreateCreditNoteInput, runtime?: FinanceServiceRuntime): Promise<{
         id: string;
         status: "draft" | "issued" | "applied";

package/dist/service-invoice-credit-notes.js

@@ -48,6 +48,14 @@ export const financeInvoiceCreditNoteService = {
             .where(eq(creditNotes.invoiceId, invoiceId))
             .orderBy(desc(creditNotes.createdAt));
     },
+    async getCreditNoteById(db, creditNoteId) {
+        const [row] = await db
+            .select()
+            .from(creditNotes)
+            .where(eq(creditNotes.id, creditNoteId))
+            .limit(1);
+        return row ?? null;
+    },
     async createCreditNote(db, invoiceId, data, runtime = {}) {
         const [invoice] = await db.select().from(invoices).where(eq(invoices.id, invoiceId)).limit(1);
         if (!invoice) {
@@ -73,6 +81,18 @@ export const financeInvoiceCreditNoteService = {
                     creditNote: row,
                 }, {
                     authorizationSource: runtime.actionLedgerAuthorizationSource,
+                    actionName: runtime.actionLedgerActionName,
+                    routeOrToolName: runtime.actionLedgerRouteOrToolName,
+                    targetType: runtime.actionLedgerTargetType,
+                    targetId: runtime.actionLedgerTargetId,
+                    capabilityId: runtime.actionLedgerCapabilityId,
+                    capabilityVersion: runtime.actionLedgerCapabilityVersion,
+                    evaluatedRisk: runtime.actionLedgerEvaluatedRisk,
+                    causationActionId: runtime.actionLedgerCausationActionId,
+                    approvalId: runtime.actionLedgerApprovalId,
+                    idempotencyScope: runtime.actionLedgerIdempotencyScope,
+                    idempotencyKey: runtime.actionLedgerIdempotencyKey,
+                    idempotencyFingerprint: runtime.actionLedgerIdempotencyFingerprint,
                 }));
             }
             return row;

package/dist/service-invoices.d.ts

@@ -458,6 +458,21 @@ export declare const financeInvoiceService: {
             generated: undefined;
         }, {}, {}>;
     }>, "where" | "orderBy">;
+    getCreditNoteById(db: import("drizzle-orm/postgres-js").PostgresJsDatabase, creditNoteId: string): Promise<{
+        id: string;
+        creditNoteNumber: string;
+        invoiceId: string;
+        status: "draft" | "issued" | "applied";
+        amountCents: number;
+        currency: string;
+        baseCurrency: string | null;
+        baseAmountCents: number | null;
+        fxRateSetId: string | null;
+        reason: string;
+        notes: string | null;
+        createdAt: Date;
+        updatedAt: Date;
+    } | null>;
     createCreditNote(db: import("drizzle-orm/postgres-js").PostgresJsDatabase, invoiceId: string, data: import("./service-shared.js").CreateCreditNoteInput, runtime?: import("./service-shared.js").FinanceServiceRuntime): Promise<{
         id: string;
         status: "draft" | "issued" | "applied";

package/dist/service-issue.d.ts

@@ -12,6 +12,14 @@ import { type CreateInvoiceFromBookingInput, type FinanceServiceRuntime, type In
  */
 export interface InvoiceIssueRuntime extends FinanceServiceRuntime {
 }
+export type InvoiceFromBookingCommandOutcome = {
+    status: "issued";
+    invoice: typeof invoices.$inferSelect;
+} | {
+    status: "booking_not_found";
+} | {
+    status: "payment_schedule_not_found";
+};
 interface ExistingConvertedInvoicePointer {
     id: string;
     invoiceNumber: string;
@@ -87,6 +95,12 @@ export interface InvoiceProformaConvertedEvent extends InvoiceIssuedEvent {
     proformaId: string;
     proformaInvoiceNumber: string;
 }
+/**
+ * Package-owned invoice-from-booking composer shared by HTTP routes and Tools.
+ * It owns the cross-module projection read so transport adapters never reach
+ * into booking or finance tables themselves.
+ */
+export declare function issueInvoiceFromBookingCommand(db: PostgresJsDatabase, input: CreateInvoiceFromBookingInput, runtime?: InvoiceIssueRuntime): Promise<InvoiceFromBookingCommandOutcome>;
 /**
  * Create + emit an invoice from a booking. Returns the persisted row
  * after flipping the status from `draft` to `issued`. Drafts shouldn't