@voyant-travel/finance 0.171.0 → 0.171.2

package/dist/app-api-runtime.d.ts

@@ -1,2 +1,5 @@
+import type { VoyantRuntimeHostPrimitives } from "@voyant-travel/core";
 import type { FinanceAppApiRuntime } from "@voyant-travel/finance-contracts/app-api";
-export declare function createFinanceAppApiRuntime(): FinanceAppApiRuntime;
+type ArtifactRuntimePrimitives = Pick<VoyantRuntimeHostPrimitives, "storage">;
+export declare function createFinanceAppApiRuntime(primitives?: ArtifactRuntimePrimitives): FinanceAppApiRuntime;
+export {};

package/dist/app-api-runtime.js

@@ -1,11 +1,11 @@
 import { bookings } from "@voyant-travel/bookings/schema";
 import { FinanceAppApiNumberConflictError } from "@voyant-travel/finance-contracts/app-api";
-import { and, asc, eq, sql } from "drizzle-orm";
-import { invoiceExternalRefs, invoiceLineItems, invoiceNumberSeries, invoices, taxRegimes, } from "./schema.js";
+import { and, asc, desc, eq, inArray, sql } from "drizzle-orm";
+import { invoiceExternalLifecycleOperations, invoiceExternalPaymentIdentifiers, invoiceExternalRefs, invoiceExternalSettlementObservations, invoiceExternalSyncObservations, invoiceLineItems, invoiceNumberSeries, invoiceRenditions, invoices, taxRegimes, } from "./schema.js";
 import { financeService } from "./service.js";
 import { buildInvoiceIssuedEvent } from "./service-issue.js";
 import { InvoiceNumberConflictError, toRows } from "./service-shared.js";
-export function createFinanceAppApiRuntime() {
+export function createFinanceAppApiRuntime(primitives) {
     return {
         async getIssuanceDocument(db, documentId) {
             const [invoice] = await db.select().from(invoices).where(eq(invoices.id, documentId)).limit(1);
@@ -184,8 +184,363 @@ export function createFinanceAppApiRuntime() {
                 allocationOutcome,
             };
         },
+        async attachPdfArtifact(db, environment, documentId, provider, input) {
+            const checksum = await sha256(input.bytes);
+            const idempotencyDigest = await sha256(new TextEncoder().encode(input.idempotencyKey));
+            const existing = await findAppArtifact(db, documentId, provider, idempotencyDigest);
+            if (existing)
+                return replayArtifact(existing, checksum, input.fileName);
+            const storage = primitives?.storage.resolve(environment, "documents");
+            if (!storage)
+                return { status: "not_configured" };
+            const requestedStorageKey = await artifactStorageKey(documentId, provider, input.idempotencyKey, checksum);
+            let uploaded;
+            try {
+                uploaded = await storage.upload(input.bytes, {
+                    key: requestedStorageKey,
+                    contentType: input.contentType,
+                    metadata: {
+                        documentId,
+                        provider,
+                        checksum,
+                    },
+                });
+            }
+            catch (error) {
+                await bestEffortDelete(storage, requestedStorageKey);
+                throw error;
+            }
+            const storageKey = uploaded.key;
+            try {
+                const result = await financeService.bindInvoiceRendition(db, documentId, {
+                    format: "pdf",
+                    contentType: input.contentType,
+                    storageKey,
+                    fileSize: input.bytes.byteLength,
+                    checksum,
+                    generatedAt: new Date().toISOString(),
+                    appProvider: provider,
+                    appIdempotencyDigest: idempotencyDigest,
+                    appFileName: input.fileName,
+                    metadata: { source: "remote_app" },
+                });
+                if (result.status === "not_found") {
+                    await bestEffortDelete(storage, storageKey);
+                    return { status: "not_found" };
+                }
+                return {
+                    status: "ok",
+                    outcome: "created",
+                    artifact: mapPdfArtifact(result.rendition, provider),
+                };
+            }
+            catch (error) {
+                const raced = await findAppArtifact(db, documentId, provider, idempotencyDigest);
+                if (raced) {
+                    if (raced.storageKey !== storageKey)
+                        await bestEffortDelete(storage, storageKey);
+                    return replayArtifact(raced, checksum, input.fileName);
+                }
+                await bestEffortDelete(storage, storageKey);
+                throw error;
+            }
+        },
+        async updateExternalSyncState(db, documentId, provider, input) {
+            const locked = toRows(await db.execute(
+            // agent-quality: raw-sql reviewed -- identifiers are static and values are bound.
+            sql `SELECT id FROM invoices WHERE id = ${documentId} FOR UPDATE`))[0];
+            if (!locked)
+                return { status: "not_found" };
+            const [replay] = await db
+                .select()
+                .from(invoiceExternalSyncObservations)
+                .where(and(eq(invoiceExternalSyncObservations.invoiceId, documentId), eq(invoiceExternalSyncObservations.provider, provider), eq(invoiceExternalSyncObservations.operationId, input.operationId)))
+                .limit(1);
+            if (replay) {
+                const replayState = mapExternalSyncObservation(replay);
+                return syncStateMatches(replayState, input)
+                    ? { status: "ok", outcome: "unchanged", sync: replayState }
+                    : {
+                        status: "conflict",
+                        reason: "idempotency_key_reused",
+                        current: replayState,
+                    };
+            }
+            const [existing] = await db
+                .select()
+                .from(invoiceExternalRefs)
+                .where(and(eq(invoiceExternalRefs.invoiceId, documentId), eq(invoiceExternalRefs.provider, provider)))
+                .limit(1);
+            const current = existing ? mapExternalSyncState(existing) : null;
+            if (current &&
+                new Date(current.occurredAt).getTime() >= new Date(input.occurredAt).getTime()) {
+                return { status: "conflict", reason: "out_of_order", current };
+            }
+            await db.insert(invoiceExternalSyncObservations).values({
+                invoiceId: documentId,
+                provider,
+                operationId: input.operationId,
+                status: input.status,
+                occurredAt: new Date(input.occurredAt),
+                errorCode: input.error?.code ?? null,
+                errorMessage: input.error?.message ?? null,
+                metadata: input.metadata,
+            });
+            const values = syncStateValues(input);
+            const [row] = existing
+                ? await db
+                    .update(invoiceExternalRefs)
+                    .set({ ...values, updatedAt: new Date() })
+                    .where(eq(invoiceExternalRefs.id, existing.id))
+                    .returning()
+                : await db
+                    .insert(invoiceExternalRefs)
+                    .values({ invoiceId: documentId, provider, ...values })
+                    .returning();
+            if (!row)
+                return { status: "not_found" };
+            const sync = mapExternalSyncState(row);
+            if (!sync) {
+                throw new Error("Persisted external sync state is incomplete.");
+            }
+            return {
+                status: "ok",
+                outcome: existing ? "updated" : "created",
+                sync,
+            };
+        },
+        async updateExternalLifecycleState(db, documentId, provider, input) {
+            const document = toRows(await db.execute(
+            // agent-quality: raw-sql reviewed -- identifiers are static and values are bound.
+            sql `SELECT id, invoice_type, status FROM invoices WHERE id = ${documentId} FOR UPDATE`))[0];
+            if (!document || document.invoice_type === "credit_note")
+                return { status: "not_found" };
+            const [replay] = await db
+                .select()
+                .from(invoiceExternalLifecycleOperations)
+                .where(and(eq(invoiceExternalLifecycleOperations.invoiceId, documentId), eq(invoiceExternalLifecycleOperations.provider, provider), eq(invoiceExternalLifecycleOperations.operationId, input.operationId)))
+                .limit(1);
+            if (replay) {
+                const replayState = mapExternalLifecycleOperation(replay);
+                return lifecycleStateMatches(replayState, input)
+                    ? { status: "ok", outcome: "unchanged", lifecycle: replayState }
+                    : {
+                        status: "conflict",
+                        reason: "idempotency_key_reused",
+                        current: replayState,
+                    };
+            }
+            const nativeConflict = await validateNativeLifecycleState(db, document, documentId, input);
+            if (nativeConflict)
+                return nativeConflict;
+            const [latest] = await db
+                .select()
+                .from(invoiceExternalLifecycleOperations)
+                .where(and(eq(invoiceExternalLifecycleOperations.invoiceId, documentId), eq(invoiceExternalLifecycleOperations.provider, provider)))
+                .orderBy(desc(invoiceExternalLifecycleOperations.occurredAt))
+                .limit(1);
+            const current = latest ? mapExternalLifecycleOperation(latest) : null;
+            if (current) {
+                if (new Date(current.occurredAt).getTime() >= new Date(input.occurredAt).getTime()) {
+                    return { status: "conflict", reason: "out_of_order", current };
+                }
+                return { status: "conflict", reason: "terminal_transition", current };
+            }
+            await db.insert(invoiceExternalLifecycleOperations).values({
+                invoiceId: documentId,
+                provider,
+                operationId: input.operationId,
+                state: input.state,
+                occurredAt: new Date(input.occurredAt),
+                successorInvoiceId: input.lineage?.successorDocumentId ?? null,
+            });
+            return {
+                status: "ok",
+                outcome: "created",
+                lifecycle: {
+                    provider,
+                    documentId,
+                    ...input,
+                },
+            };
+        },
+        async recordSettlementObservation(db, documentId, provider, input) {
+            const document = toRows(await db.execute(
+            // agent-quality: raw-sql reviewed -- identifiers are static and values are bound.
+            sql `SELECT id, invoice_type, status, currency, total_cents FROM invoices WHERE id = ${documentId} FOR UPDATE`))[0];
+            if (!document || document.invoice_type === "credit_note")
+                return { status: "not_found" };
+            const [replay] = await db
+                .select()
+                .from(invoiceExternalSettlementObservations)
+                .where(and(eq(invoiceExternalSettlementObservations.invoiceId, documentId), eq(invoiceExternalSettlementObservations.provider, provider), eq(invoiceExternalSettlementObservations.operationId, input.operationId)))
+                .limit(1);
+            if (replay) {
+                const replayObservation = mapSettlementObservation(replay);
+                return settlementObservationMatches(replayObservation, input)
+                    ? { status: "ok", outcome: "unchanged", observation: replayObservation }
+                    : {
+                        status: "conflict",
+                        reason: "idempotency_key_reused",
+                        current: replayObservation,
+                    };
+            }
+            if (!["issued", "overdue", "partially_paid", "paid"].includes(document.status) ||
+                document.currency !== input.currency ||
+                document.total_cents !== input.totals.totalCents) {
+                return { status: "conflict", reason: "native_document_mismatch", current: null };
+            }
+            const [latest] = await db
+                .select()
+                .from(invoiceExternalSettlementObservations)
+                .where(and(eq(invoiceExternalSettlementObservations.invoiceId, documentId), eq(invoiceExternalSettlementObservations.provider, provider)))
+                .orderBy(desc(invoiceExternalSettlementObservations.occurredAt))
+                .limit(1);
+            const current = latest ? mapSettlementObservation(latest) : null;
+            if (current) {
+                if (new Date(current.occurredAt).getTime() >= new Date(input.occurredAt).getTime()) {
+                    return { status: "conflict", reason: "out_of_order", current };
+                }
+                if (current.status === "paid") {
+                    return { status: "conflict", reason: "terminal_transition", current };
+                }
+                if (input.totals.paidCents < current.totals.paidCents ||
+                    input.totals.balanceDueCents > current.totals.balanceDueCents ||
+                    current.paymentIdentifiers.some((paymentIdentifier) => !input.paymentIdentifiers.includes(paymentIdentifier))) {
+                    return { status: "conflict", reason: "settlement_regression", current };
+                }
+            }
+            const paymentIdentifiers = [...new Set(input.paymentIdentifiers)].sort();
+            for (const paymentIdentifier of paymentIdentifiers) {
+                const lockKey = `finance:external-payment:${provider}:${paymentIdentifier}`;
+                await db.execute(
+                // agent-quality: raw-sql reviewed -- identifiers are static and values are bound.
+                sql `SELECT pg_advisory_xact_lock(hashtextextended(${lockKey}, 0))`);
+            }
+            const identifierOwners = await db
+                .select()
+                .from(invoiceExternalPaymentIdentifiers)
+                .where(and(eq(invoiceExternalPaymentIdentifiers.provider, provider), inArray(invoiceExternalPaymentIdentifiers.paymentIdentifier, paymentIdentifiers)))
+                .limit(paymentIdentifiers.length);
+            const conflictingOwner = identifierOwners.find((owner) => owner.invoiceId !== documentId);
+            if (conflictingOwner) {
+                return {
+                    status: "conflict",
+                    reason: "payment_identifier_conflict",
+                    current,
+                    paymentIdentifier: conflictingOwner.paymentIdentifier,
+                };
+            }
+            const ownedIdentifiers = new Set(identifierOwners.map((owner) => owner.paymentIdentifier));
+            const identifiersToClaim = paymentIdentifiers.filter((paymentIdentifier) => !ownedIdentifiers.has(paymentIdentifier));
+            if (identifiersToClaim.length > 0) {
+                await db.insert(invoiceExternalPaymentIdentifiers).values(identifiersToClaim.map((paymentIdentifier) => ({
+                    provider,
+                    paymentIdentifier,
+                    invoiceId: documentId,
+                    firstOperationId: input.operationId,
+                })));
+            }
+            await db.insert(invoiceExternalSettlementObservations).values({
+                invoiceId: documentId,
+                provider,
+                operationId: input.operationId,
+                occurredAt: new Date(input.occurredAt),
+                status: input.status,
+                currency: input.currency,
+                totalCents: input.totals.totalCents,
+                paidCents: input.totals.paidCents,
+                balanceDueCents: input.totals.balanceDueCents,
+                paymentIdentifiers,
+            });
+            return {
+                status: "ok",
+                outcome: "created",
+                observation: {
+                    provider,
+                    documentId,
+                    ...input,
+                    paymentIdentifiers,
+                },
+            };
+        },
+    };
+}
+async function validateNativeLifecycleState(db, document, documentId, input) {
+    if (input.state === "converted") {
+        if (input.lineage?.sourceDocumentId !== documentId) {
+            return { status: "conflict", reason: "lineage_mismatch", current: null };
+        }
+        if (document.invoice_type !== "proforma" || document.status !== "void") {
+            return { status: "conflict", reason: "native_state_mismatch", current: null };
+        }
+        const successor = toRows(await db.execute(
+        // agent-quality: raw-sql reviewed -- identifiers are static and values are bound.
+        sql `SELECT id, invoice_type, converted_from_invoice_id FROM invoices WHERE id = ${input.lineage.successorDocumentId} FOR SHARE`))[0];
+        if (successor?.invoice_type !== "invoice" ||
+            successor.converted_from_invoice_id !== documentId) {
+            return { status: "conflict", reason: "lineage_mismatch", current: null };
+        }
+        return null;
+    }
+    if (input.lineage || document.status !== "void") {
+        return { status: "conflict", reason: "native_state_mismatch", current: null };
+    }
+    const successor = toRows(await db.execute(
+    // agent-quality: raw-sql reviewed -- identifiers are static and values are bound.
+    sql `SELECT id FROM invoices WHERE converted_from_invoice_id = ${documentId} LIMIT 1 FOR SHARE`))[0];
+    return successor ? { status: "conflict", reason: "native_state_mismatch", current: null } : null;
+}
+function mapExternalLifecycleOperation(row) {
+    if (row.state !== "converted" && row.state !== "voided") {
+        throw new Error("Persisted external lifecycle operation has an invalid state.");
+    }
+    return {
+        provider: row.provider,
+        documentId: row.invoiceId,
+        operationId: row.operationId,
+        state: row.state,
+        occurredAt: row.occurredAt.toISOString(),
+        lineage: row.state === "converted" && row.successorInvoiceId
+            ? {
+                sourceDocumentId: row.invoiceId,
+                successorDocumentId: row.successorInvoiceId,
+            }
+            : null,
     };
 }
+function lifecycleStateMatches(current, input) {
+    return (current.state === input.state &&
+        new Date(current.occurredAt).getTime() === new Date(input.occurredAt).getTime() &&
+        canonicalJson(current.lineage) === canonicalJson(input.lineage));
+}
+function mapSettlementObservation(row) {
+    if (row.status !== "partial" && row.status !== "paid") {
+        throw new Error("Persisted settlement observation has an invalid status.");
+    }
+    return {
+        provider: row.provider,
+        documentId: row.invoiceId,
+        operationId: row.operationId,
+        occurredAt: row.occurredAt.toISOString(),
+        status: row.status,
+        currency: row.currency,
+        totals: {
+            totalCents: row.totalCents,
+            paidCents: row.paidCents,
+            balanceDueCents: row.balanceDueCents,
+        },
+        paymentIdentifiers: [...row.paymentIdentifiers].sort(),
+    };
+}
+function settlementObservationMatches(current, input) {
+    return (current.status === input.status &&
+        current.currency === input.currency &&
+        new Date(current.occurredAt).getTime() === new Date(input.occurredAt).getTime() &&
+        canonicalJson(current.totals) === canonicalJson(input.totals) &&
+        canonicalJson(current.paymentIdentifiers) ===
+            canonicalJson([...new Set(input.paymentIdentifiers)].sort()));
+}
 function buildHydratedFx(invoice, issuedEvent) {
     if (!invoice.baseCurrency || invoice.baseCurrency === invoice.currency)
         return null;
@@ -224,19 +579,132 @@ function mapExternalReference(row) {
         metadata: isRecord(row.metadata) ? row.metadata : null,
         syncedAt: row.syncedAt?.toISOString() ?? null,
         syncError: row.syncError,
+        sync: mapExternalSyncState(row),
         createdAt: row.createdAt.toISOString(),
         updatedAt: row.updatedAt.toISOString(),
     };
 }
+function mapExternalSyncState(row) {
+    if (!isExternalSyncStatus(row.syncState) || !row.syncOperationId || !row.syncOccurredAt) {
+        return null;
+    }
+    return {
+        provider: row.provider,
+        documentId: row.invoiceId,
+        operationId: row.syncOperationId,
+        status: row.syncState,
+        occurredAt: row.syncOccurredAt.toISOString(),
+        error: row.syncErrorCode && row.syncErrorMessage
+            ? { code: row.syncErrorCode, message: row.syncErrorMessage }
+            : null,
+        metadata: isRecord(row.syncMetadata) ? row.syncMetadata : null,
+    };
+}
+function mapExternalSyncObservation(row) {
+    if (!isExternalSyncStatus(row.status)) {
+        throw new Error("Persisted external sync observation has an invalid status.");
+    }
+    return {
+        provider: row.provider,
+        documentId: row.invoiceId,
+        operationId: row.operationId,
+        status: row.status,
+        occurredAt: row.occurredAt.toISOString(),
+        error: row.errorCode && row.errorMessage ? { code: row.errorCode, message: row.errorMessage } : null,
+        metadata: isRecord(row.metadata) ? row.metadata : null,
+    };
+}
+function syncStateValues(input) {
+    return {
+        syncState: input.status,
+        syncOperationId: input.operationId,
+        syncOccurredAt: new Date(input.occurredAt),
+        syncErrorCode: input.error?.code ?? null,
+        syncErrorMessage: input.error?.message ?? null,
+        syncMetadata: input.metadata,
+        syncedAt: input.status === "succeeded" ? new Date(input.occurredAt) : null,
+    };
+}
+function syncStateMatches(current, input) {
+    return (current.status === input.status &&
+        new Date(current.occurredAt).getTime() === new Date(input.occurredAt).getTime() &&
+        current.error?.code === input.error?.code &&
+        current.error?.message === input.error?.message &&
+        canonicalJson(current.metadata) === canonicalJson(input.metadata));
+}
+function isExternalSyncStatus(value) {
+    return ["succeeded", "retryable_failure", "terminal_failure"].includes(value ?? "");
+}
+async function findAppArtifact(db, documentId, provider, idempotencyDigest) {
+    const [row] = await db
+        .select()
+        .from(invoiceRenditions)
+        .where(and(eq(invoiceRenditions.invoiceId, documentId), eq(invoiceRenditions.appProvider, provider), eq(invoiceRenditions.appIdempotencyDigest, idempotencyDigest)))
+        .limit(1);
+    return row ?? null;
+}
+function replayArtifact(row, checksum, fileName) {
+    if (row.checksum !== checksum || row.appFileName !== fileName) {
+        return { status: "conflict", reason: "idempotency_key_reused" };
+    }
+    return {
+        status: "ok",
+        outcome: "unchanged",
+        artifact: mapPdfArtifact(row, row.appProvider ?? ""),
+    };
+}
+function mapPdfArtifact(row, provider) {
+    return {
+        id: row.id,
+        documentId: row.invoiceId,
+        provider,
+        fileName: row.appFileName ?? "document.pdf",
+        byteSize: row.fileSize ?? 0,
+        checksum: row.checksum ?? "",
+        createdAt: row.createdAt.toISOString(),
+    };
+}
+async function artifactStorageKey(documentId, provider, idempotencyKey, checksum) {
+    const providerHash = (await sha256(new TextEncoder().encode(provider))).slice(0, 24);
+    const documentHash = (await sha256(new TextEncoder().encode(documentId))).slice(0, 24);
+    const replayHash = (await sha256(new TextEncoder().encode(idempotencyKey))).slice(0, 24);
+    return `finance/app-artifacts/${providerHash}/${documentHash}/${replayHash}-${crypto.randomUUID()}-${checksum}.pdf`;
+}
+async function sha256(bytes) {
+    const buffer = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(buffer).set(bytes);
+    const digest = await crypto.subtle.digest("SHA-256", buffer);
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+async function bestEffortDelete(storage, key) {
+    try {
+        await storage.delete(key);
+    }
+    catch {
+        // Compensation is best effort; an unbound key remains unreachable through
+        // every Voyant document route and must never replace the persistence error.
+    }
+}
 function referenceMatches(existing, input) {
     return (existing.externalId === (input.externalId ?? null) &&
         existing.externalNumber === (input.externalNumber ?? null) &&
         existing.externalUrl === (input.externalUrl ?? null) &&
         existing.status === (input.status ?? null) &&
-        JSON.stringify(existing.metadata) === JSON.stringify(input.metadata ?? null) &&
+        canonicalJson(existing.metadata) === canonicalJson(input.metadata ?? null) &&
         (existing.syncedAt?.toISOString() ?? null) === (input.syncedAt ?? null) &&
         existing.syncError === (input.syncError ?? null));
 }
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (isRecord(value)) {
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value) ?? "undefined";
+}

package/dist/routes-runtime.d.ts

@@ -12,7 +12,6 @@ export declare const routeIdempotencyKey: (scope: string, options?: {
         VOYANT_CHECKOUT_CAPABILITY_TTL_SECONDS: string;
         CHECKOUT_CAPABILITY_TTL_SECONDS: string;
         SESSION_CLAIMS_SECRET: string;
-        BETTER_AUTH_SECRET: string;
     }>;
     Variables: {
         db: import("drizzle-orm/postgres-js").PostgresJsDatabase;

package/dist/routes-shared.d.ts

@@ -8,7 +8,6 @@ export type Env = {
         VOYANT_CHECKOUT_CAPABILITY_TTL_SECONDS: string;
         CHECKOUT_CAPABILITY_TTL_SECONDS: string;
         SESSION_CLAIMS_SECRET: string;
-        BETTER_AUTH_SECRET: string;
     }>;
     Variables: {
         db: PostgresJsDatabase;

package/dist/runtime-contributor.js

@@ -8,7 +8,7 @@ import { createFinanceStaleBookingHoldsRuntime } from "./stale-booking-holds-run
 /** Provide Finance's generic host input and its narrow Bookings integration. */
 export function createFinanceRuntimePortContribution(host) {
     return {
-        [financeAppApiRuntimePort.id]: createFinanceAppApiRuntime(),
+        [financeAppApiRuntimePort.id]: createFinanceAppApiRuntime(host.primitives),
         [actionLedgerFinanceDriftRuntimePort.id]: {
             checkFinanceDrift: checkFinanceActionLedgerDrift,
         },