@voyant-travel/apps 0.6.3 → 0.8.0

package/dist/app-api-routes.js

@@ -1,9 +1,8 @@
 import { ApiHttpError, parseJsonBody, parseQuery, RequestValidationError, } from "@voyant-travel/hono";
 import { Hono } from "hono";
 import { z } from "zod";
-import { appApiAuditQuerySchema, appApiCustomFieldDefinitionCreateSchema, appApiCustomFieldDefinitionListQuerySchema, appApiCustomFieldDefinitionUpdateSchema, appApiCustomFieldValueListQuerySchema, appApiCustomFieldValueUpsertSchema, appApiEntityReadQuerySchema, appApiFinanceActionSchema, appApiFinanceDocumentQuerySchema, appApiTokenExchangeSchema, appApiVersionHeader, appApiWebhookReplaySchema, } from "./app-api-contracts.js";
+import { appApiAuditQuerySchema, appApiCustomFieldDefinitionCreateSchema, appApiCustomFieldDefinitionListQuerySchema, appApiCustomFieldDefinitionUpdateSchema, appApiCustomFieldValueListQuerySchema, appApiCustomFieldValueUpsertSchema, appApiEntityReadQuerySchema, appApiFinanceActionSchema, appApiFinanceDocumentQuerySchema, appApiFinanceExternalLifecycleStateSchema, appApiFinanceExternalReferenceUpsertSchema, appApiFinanceExternalSyncStateSchema, appApiFinancePdfArtifactHeadersSchema, appApiFinanceSettlementObservationSchema, appApiVersionHeader, appApiWebhookReplaySchema, } from "./app-api-contracts.js";
 import { createAppApiService, withAppApiDeadline, } from "./app-api-service.js";
-import { createAppOAuthService } from "./oauth-service.js";
 import { replayAppWebhookDelivery } from "./webhook-delivery.js";
 /** Absolute mount prefix for the versioned App API surface. */
 export const APP_API_BASE_PATH = "/v1/app";
@@ -24,8 +23,8 @@ const definitionUpdateBodySchema = z
 export function createAppsAppApiRoutes(options = {}) {
     const routes = new Hono();
     const service = createAppApiService(options);
-    const oauth = options.oauth ? createAppOAuthService(options.oauth) : null;
     const maxPayloadBytes = options.maxPayloadBytes ?? 256 * 1024;
+    const maxFinanceArtifactBytes = options.maxFinanceArtifactBytes ?? 10 * 1024 * 1024;
     routes.use("*", async (c, next) => {
         if (c.get("callerType") !== "app") {
             throw new ApiHttpError("App API requires an app access token.", {
@@ -33,12 +32,26 @@ export function createAppsAppApiRoutes(options = {}) {
                 code: "app_api_token_required",
             });
         }
-        const length = Number(c.req.header("content-length") ?? "0");
-        if (Number.isFinite(length) && length > maxPayloadBytes) {
+        const requestLimit = isFinancePdfArtifactRequest(c) ? maxFinanceArtifactBytes : maxPayloadBytes;
+        const declaredLength = c.req.header("content-length");
+        if (declaredLength !== undefined && !/^(0|[1-9][0-9]*)$/.test(declaredLength)) {
+            throw new ApiHttpError("App API Content-Length is invalid.", {
+                status: 400,
+                code: "app_api_content_length_invalid",
+            });
+        }
+        const length = Number(declaredLength ?? "0");
+        if (!Number.isSafeInteger(length)) {
+            throw new ApiHttpError("App API Content-Length is invalid.", {
+                status: 400,
+                code: "app_api_content_length_invalid",
+            });
+        }
+        if (length > requestLimit) {
             throw new ApiHttpError("App API payload is too large.", {
                 status: 413,
                 code: "app_api_payload_too_large",
-                details: { maxPayloadBytes },
+                details: { maxPayloadBytes: requestLimit },
             });
         }
         return next();
@@ -50,6 +63,67 @@ export function createAppsAppApiRoutes(options = {}) {
         return run(c, service.listEntities(c.get("db"), appContext(c), entity, query), options.deadlineMs);
     });
     routes.get("/finance/documents", (c) => run(c, service.listFinanceDocuments(c.get("db"), appContext(c), parseQuery(c, appApiFinanceDocumentQuerySchema)), options.deadlineMs));
+    routes.get("/finance/documents/:id", (c) => {
+        const { id } = parseIdParams(c.req.param());
+        return run(c, service.getFinanceIssuanceDocument(c.get("db"), appContext(c), id), options.deadlineMs);
+    });
+    routes.get("/finance/documents/:id/external-reference", (c) => {
+        const { id } = parseIdParams(c.req.param());
+        return run(c, service.getFinanceExternalReference(c.get("db"), appContext(c), id), options.deadlineMs);
+    });
+    routes.put("/finance/documents/:id/external-reference", async (c) => {
+        const { id } = parseIdParams(c.req.param());
+        const body = await parseJsonBody(c, appApiFinanceExternalReferenceUpsertSchema);
+        return run(c, service.upsertFinanceExternalReference(c.get("db"), appContext(c), id, body), options.deadlineMs);
+    });
+    routes.put("/finance/documents/:id/artifacts/provider-pdf", async (c) => {
+        const { id } = parseIdParams(c.req.param());
+        if (c.req.header("content-type")?.toLowerCase() !== "application/pdf") {
+            throw new ApiHttpError("Finance document artifact must be an application/pdf body.", {
+                status: 415,
+                code: "app_api_finance_artifact_media_type_unsupported",
+            });
+        }
+        const headers = parseArtifactHeaders(c);
+        const bytes = await readBoundedArtifactBody(c, maxFinanceArtifactBytes);
+        if (!hasPdfSignature(bytes)) {
+            throw new ApiHttpError("Finance document artifact is not a PDF.", {
+                status: 415,
+                code: "app_api_finance_artifact_invalid_pdf",
+            });
+        }
+        const result = await withAppApiDeadline(service.attachFinancePdfArtifact(c.get("db"), appContext(c), id, c.env, headers, bytes), options.deadlineMs);
+        return c.json({
+            data: {
+                outcome: result.data.outcome,
+                artifact: {
+                    id: result.data.artifact.id,
+                    documentId: result.data.artifact.documentId,
+                    provider: result.data.artifact.provider,
+                    fileName: result.data.artifact.fileName,
+                    byteSize: result.data.artifact.byteSize,
+                    checksum: result.data.artifact.checksum,
+                    createdAt: result.data.artifact.createdAt,
+                    documentUrl: financeArtifactDocumentUrl(c, result.data.artifact.id),
+                },
+            },
+        });
+    });
+    routes.put("/finance/documents/:id/external-sync-state", async (c) => {
+        const { id } = parseIdParams(c.req.param());
+        const body = await parseJsonBody(c, appApiFinanceExternalSyncStateSchema);
+        return run(c, service.updateFinanceExternalSyncState(c.get("db"), appContext(c), id, body), options.deadlineMs);
+    });
+    routes.put("/finance/documents/:id/external-lifecycle-state", async (c) => {
+        const { id } = parseIdParams(c.req.param());
+        const body = await parseJsonBody(c, appApiFinanceExternalLifecycleStateSchema);
+        return run(c, service.updateFinanceExternalLifecycleState(c.get("db"), appContext(c), id, body), options.deadlineMs);
+    });
+    routes.post("/finance/documents/:id/settlement-observations", async (c) => {
+        const { id } = parseIdParams(c.req.param());
+        const body = await parseJsonBody(c, appApiFinanceSettlementObservationSchema);
+        return run(c, service.recordFinanceSettlementObservation(c.get("db"), appContext(c), id, body), options.deadlineMs, 201);
+    });
     routes.post("/finance/actions", async (c) => {
         const body = await parseJsonBody(c, appApiFinanceActionSchema);
         return run(c, service.executeFinanceAction(c.get("db"), appContext(c), body), options.deadlineMs);
@@ -81,22 +155,6 @@ export function createAppsAppApiRoutes(options = {}) {
         }), options.deadlineMs, 202);
     });
     routes.get("/audit", (c) => run(c, service.listAuditHistory(c.get("db"), appContext(c), parseQuery(c, appApiAuditQuerySchema)), options.deadlineMs));
-    routes.post("/oauth/token-exchange", async (c) => {
-        if (!oauth)
-            return c.json({ error: "App OAuth is not configured" }, 501);
-        const context = appContext(c);
-        await service.requireAccess(c.get("db"), context, ["online-token:exchange"]);
-        const body = await parseJsonBody(c, appApiTokenExchangeSchema);
-        return run(c, oauth.token(c.get("db"), {
-            grantType: "urn:voyant:params:oauth:grant-type:actor-token-exchange",
-            installationId: context.installationId,
-            viewerId: body.viewer_id,
-            viewerScopes: body.viewer_scopes,
-            contextualScopes: body.contextual_scopes,
-            clientId: body.client_id,
-            clientSecret: body.client_secret,
-        }), options.deadlineMs);
-    });
     // Lazy route families forward the original absolute URL, so the loaded
     // sub-app must expose absolute paths. Mount the relative handlers under the
     // App API prefix; the matchers in api-runtime install `/v1/app` and
@@ -119,6 +177,7 @@ function appContext(c) {
         releaseId,
         tokenMode,
         viewerId: c.get("appViewerId"),
+        contextConstraint: c.get("appContextConstraint"),
         scopes: c.get("scopes") ?? [],
         apiVersion: c.req.header(appApiVersionHeader) ?? undefined,
     };
@@ -135,6 +194,69 @@ function parseEntityParams(input) {
         throw new RequestValidationError("Invalid route parameters");
     return parsed.data;
 }
+function parseArtifactHeaders(c) {
+    const parsed = appApiFinancePdfArtifactHeadersSchema.safeParse({
+        idempotencyKey: c.req.header("idempotency-key"),
+        fileName: c.req.header("x-voyant-artifact-name"),
+    });
+    if (!parsed.success)
+        throw new RequestValidationError("Invalid artifact request headers");
+    return parsed.data;
+}
+function isFinancePdfArtifactRequest(c) {
+    return (c.req.method === "PUT" &&
+        /^\/v1\/app\/finance\/documents\/[^/]+\/artifacts\/provider-pdf$/.test(c.req.path));
+}
+function hasPdfSignature(bytes) {
+    return (bytes.byteLength >= 5 &&
+        bytes[0] === 0x25 &&
+        bytes[1] === 0x50 &&
+        bytes[2] === 0x44 &&
+        bytes[3] === 0x46 &&
+        bytes[4] === 0x2d);
+}
+async function readBoundedArtifactBody(c, maxBytes) {
+    const body = c.req.raw.body;
+    if (!body)
+        return new Uint8Array();
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        while (true) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            total += next.value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel("Finance document artifact exceeded limit");
+                throw new ApiHttpError("Finance document artifact is too large.", {
+                    status: 413,
+                    code: "app_api_payload_too_large",
+                    details: { maxPayloadBytes: maxBytes },
+                });
+            }
+            chunks.push(next.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return bytes;
+}
+function financeArtifactDocumentUrl(c, artifactId) {
+    const path = `/v1/admin/finance/invoice-renditions/${encodeURIComponent(artifactId)}/download`;
+    const configuredApiBaseUrl = c.env.API_BASE_URL?.trim().replace(/\/+$/, "");
+    return configuredApiBaseUrl
+        ? `${configuredApiBaseUrl}${path}`
+        : new URL(path, c.req.url).toString();
+}
 async function run(c, promise, deadlineMs, status = 200) {
     const data = await withAppApiDeadline(promise, deadlineMs);
     return c.json(data, status);

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

@@ -1,22 +1,25 @@
+import type { VoyantAppContextConstraint } from "@voyant-travel/core";
 import type { CustomFieldValueLifecycleRuntime, CustomFieldValueOperationsRuntime } from "@voyant-travel/core/runtime-port";
 import { type CustomFieldDefinitionOwner, createCustomFieldsService } from "@voyant-travel/custom-fields";
+import { type FinanceAppApiRuntime } from "@voyant-travel/finance-contracts/app-api";
 import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
-import type { AppApiAuditQuery, AppApiEntityReadQuery, AppApiFinanceActionInput, AppApiFinanceDocumentQuery } from "./app-api-contracts.js";
+import type { AppApiAuditQuery, AppApiEntityReadQuery, AppApiFinanceActionInput, AppApiFinanceDocumentQuery, AppApiFinanceExternalLifecycleStateInput, AppApiFinanceExternalReferenceUpsertInput, AppApiFinanceExternalSyncStateInput, AppApiFinancePdfArtifactHeaders, AppApiFinanceSettlementObservationInput } from "./app-api-contracts.js";
 export interface AppApiAccessContext {
     appId: string;
     installationId: string;
     releaseId: string;
     tokenMode: "offline" | "online";
     viewerId?: string;
+    contextConstraint?: VoyantAppContextConstraint;
     scopes: readonly string[];
     apiVersion?: string;
 }
 export interface AppApiEntityReader {
     list(db: PostgresJsDatabase, query: AppApiEntityReadQuery): Promise<unknown>;
 }
-export interface AppApiFinanceRuntime {
-    listDocuments(db: PostgresJsDatabase, query: AppApiFinanceDocumentQuery): Promise<unknown>;
-    executeAction(db: PostgresJsDatabase, input: AppApiFinanceActionInput): Promise<unknown>;
+export interface AppApiFinanceRuntime extends Partial<FinanceAppApiRuntime> {
+    listDocuments?(db: PostgresJsDatabase, query: AppApiFinanceDocumentQuery): Promise<unknown>;
+    executeAction?(db: PostgresJsDatabase, input: AppApiFinanceActionInput): Promise<unknown>;
 }
 export interface AppApiRateLimitPolicy {
     installationLimit: number;
@@ -63,9 +66,51 @@ export declare function createAppApiService(options?: AppApiServiceOptions): {
     listFinanceDocuments: (db: PostgresJsDatabase, context: AppApiAccessContext, query: AppApiFinanceDocumentQuery) => Promise<{
         data: unknown;
     }>;
+    getFinanceIssuanceDocument: (db: PostgresJsDatabase, context: AppApiAccessContext, documentId: string) => Promise<{
+        data: import("@voyant-travel/finance-contracts/app-api").FinanceAppApiIssuanceDocument;
+    }>;
     executeFinanceAction: (db: PostgresJsDatabase, context: AppApiAccessContext, input: AppApiFinanceActionInput) => Promise<{
         data: unknown;
     }>;
+    getFinanceExternalReference: (db: PostgresJsDatabase, context: AppApiAccessContext, documentId: string) => Promise<{
+        data: import("@voyant-travel/finance-contracts/app-api").FinanceAppApiExternalReference;
+    }>;
+    upsertFinanceExternalReference: (db: PostgresJsDatabase, context: AppApiAccessContext, documentId: string, input: AppApiFinanceExternalReferenceUpsertInput) => Promise<{
+        data: {
+            status: "ok";
+            reference: import("@voyant-travel/finance-contracts/app-api").FinanceAppApiExternalReference;
+            referenceOutcome: "created" | "updated" | "unchanged";
+            allocationOutcome: "not_requested" | "applied" | "already_applied";
+        };
+    }>;
+    attachFinancePdfArtifact: (db: PostgresJsDatabase, context: AppApiAccessContext, documentId: string, environment: unknown, headers: AppApiFinancePdfArtifactHeaders, bytes: Uint8Array) => Promise<{
+        data: {
+            status: "ok";
+            outcome: "created" | "unchanged";
+            artifact: import("@voyant-travel/finance-contracts/app-api").FinanceAppApiPdfArtifact;
+        };
+    }>;
+    updateFinanceExternalSyncState: (db: PostgresJsDatabase, context: AppApiAccessContext, documentId: string, input: AppApiFinanceExternalSyncStateInput) => Promise<{
+        data: {
+            status: "ok";
+            outcome: "created" | "updated" | "unchanged";
+            sync: import("@voyant-travel/finance-contracts/app-api").FinanceAppApiExternalSyncState;
+        };
+    }>;
+    updateFinanceExternalLifecycleState: (db: PostgresJsDatabase, context: AppApiAccessContext, documentId: string, input: AppApiFinanceExternalLifecycleStateInput) => Promise<{
+        data: {
+            status: "ok";
+            outcome: "created" | "unchanged";
+            lifecycle: import("@voyant-travel/finance-contracts/app-api").FinanceAppApiExternalLifecycleObservation;
+        };
+    }>;
+    recordFinanceSettlementObservation: (db: PostgresJsDatabase, context: AppApiAccessContext, documentId: string, input: AppApiFinanceSettlementObservationInput) => Promise<{
+        data: {
+            status: "ok";
+            outcome: "created" | "unchanged";
+            observation: import("@voyant-travel/finance-contracts/app-api").FinanceAppApiSettlementObservation;
+        };
+    }>;
     listCustomFieldDefinitions: (db: PostgresJsDatabase, context: AppApiAccessContext, query: Parameters<NonNullable<{
         list(db: PostgresJsDatabase, query: import("@voyant-travel/custom-fields").CustomFieldDefinitionListQuery): Promise<{
             data: {

package/dist/app-api-service.js

@@ -1,8 +1,10 @@
 import { createAppCustomFieldDefinitionOwner, createCustomFieldsService, } from "@voyant-travel/custom-fields";
+import { FinanceAppApiNumberConflictError, } from "@voyant-travel/finance-contracts/app-api";
 import { ApiHttpError } from "@voyant-travel/hono";
 import { and, asc, eq, sql } from "drizzle-orm";
 import { assertActiveAppInstallationAccess } from "./access-boundary.js";
 import { APP_API_VERSION } from "./app-api-contracts.js";
+import { audit } from "./installation-reconciliation.js";
 import { appAuditEvents, appGrants, appReleases, appWebhookSubscriptions } from "./schema.js";
 const DEFAULT_RATE_LIMIT = { installationLimit: 120, appLimit: 600, windowMs: 60_000 };
 const REMOTE_APP_NAMESPACE = /^\$app(?::[a-z][a-z0-9-]*)?$/;
@@ -49,15 +51,32 @@ export function createAppApiService(options = {}) {
         return { data: await reader.list(db, query) };
     }
     async function listFinanceDocuments(db, context, query) {
+        assertUnconstrainedFinanceContext(context);
         await requireAccess(db, context, ["finance-documents:read"]);
         if (!options.finance)
             throw notSupported("Finance App API runtime is not configured.");
+        if (!options.finance.listDocuments)
+            throw notSupported("Finance document listing is unavailable.");
         return { data: await options.finance.listDocuments(db, query) };
     }
+    async function getFinanceIssuanceDocument(db, context, documentId) {
+        assertFinanceDocumentContext(context, documentId);
+        await requireAccess(db, context, ["finance-documents:read"]);
+        const getDocument = options.finance?.getIssuanceDocument;
+        if (!getDocument)
+            throw notSupported("Finance document hydration is unavailable.");
+        const data = await getDocument(db, documentId);
+        if (!data)
+            throw notFound("Finance document not found.");
+        return { data };
+    }
     async function executeFinanceAction(db, context, input) {
+        assertFinanceDocumentContext(context, input.invoiceId);
         await requireAccess(db, context, [`finance-actions:${input.action}`]);
         if (!options.finance)
             throw notSupported("Finance App API runtime is not configured.");
+        if (!options.finance.executeAction)
+            throw notSupported("Finance actions are unavailable.");
         if (!input.approvalId) {
             throw new ApiHttpError("Finance action requires action-ledger approval.", {
                 status: 403,
@@ -66,6 +85,198 @@ export function createAppApiService(options = {}) {
         }
         return { data: await options.finance.executeAction(db, input) };
     }
+    async function getFinanceExternalReference(db, context, documentId) {
+        assertFinanceDocumentContext(context, documentId);
+        await requireAccess(db, context, ["finance-external-references:read"]);
+        const getReference = options.finance?.getExternalReference;
+        if (!getReference)
+            throw notSupported("Finance external references are unavailable.");
+        const data = await getReference(db, documentId, context.appId);
+        if (!data)
+            throw notFound("Finance external reference not found.");
+        return { data };
+    }
+    async function upsertFinanceExternalReference(db, context, documentId, input) {
+        assertFinanceDocumentContext(context, documentId);
+        const scopes = ["finance-external-references:write"];
+        if (input.allocation)
+            scopes.push("finance-external-allocation:write");
+        const access = await requireAccess(db, context, scopes);
+        const upsertReference = options.finance?.upsertExternalReference;
+        if (!upsertReference)
+            throw notSupported("Finance external reference writes are unavailable.");
+        let result;
+        try {
+            result = await db.transaction(async (tx) => {
+                const mutation = await upsertReference(tx, documentId, context.appId, input);
+                if (mutation.status === "ok") {
+                    await audit(tx, access.installation, `app:${context.appId}`, "reconciliation", "finance.external-reference.upserted", {
+                        documentId,
+                        provider: context.appId,
+                        referenceOutcome: mutation.referenceOutcome,
+                        allocationOutcome: mutation.allocationOutcome,
+                        releaseId: context.releaseId,
+                        tokenMode: context.tokenMode,
+                    });
+                }
+                return mutation;
+            });
+        }
+        catch (error) {
+            if (error instanceof FinanceAppApiNumberConflictError) {
+                throw new ApiHttpError("Finance document number is already in use.", {
+                    status: 409,
+                    code: "app_api_finance_number_conflict",
+                    details: { invoiceNumber: error.invoiceNumber },
+                });
+            }
+            throw error;
+        }
+        if (result.status === "not_found")
+            throw notFound("Finance document not found.");
+        if (result.status === "allocation_conflict") {
+            throw new ApiHttpError("Finance document has already received a different allocation.", {
+                status: 409,
+                code: "app_api_finance_allocation_conflict",
+                details: result,
+            });
+        }
+        return { data: result };
+    }
+    async function attachFinancePdfArtifact(db, context, documentId, environment, headers, bytes) {
+        assertFinanceDocumentContext(context, documentId);
+        const access = await requireAccess(db, context, ["finance-document-artifacts:write"]);
+        const attachArtifact = options.finance?.attachPdfArtifact;
+        if (!attachArtifact)
+            throw notSupported("Finance document artifact writes are unavailable.");
+        const result = await attachArtifact(db, environment, documentId, context.appId, {
+            bytes,
+            contentType: "application/pdf",
+            fileName: headers.fileName,
+            idempotencyKey: headers.idempotencyKey,
+        });
+        if (result.status === "not_found")
+            throw notFound("Finance document not found.");
+        if (result.status === "not_configured") {
+            throw new ApiHttpError("Finance document storage is unavailable.", {
+                status: 503,
+                code: "app_api_finance_artifact_storage_unavailable",
+            });
+        }
+        if (result.status === "conflict") {
+            throw new ApiHttpError("Artifact idempotency key was reused with different content.", {
+                status: 409,
+                code: "app_api_finance_artifact_idempotency_conflict",
+            });
+        }
+        await audit(db, access.installation, `app:${context.appId}`, "reconciliation", "finance.document-artifact.attached", {
+            documentId,
+            provider: context.appId,
+            artifactId: result.artifact.id,
+            outcome: result.outcome,
+            releaseId: context.releaseId,
+            tokenMode: context.tokenMode,
+        });
+        return { data: result };
+    }
+    async function updateFinanceExternalSyncState(db, context, documentId, input) {
+        assertFinanceDocumentContext(context, documentId);
+        const access = await requireAccess(db, context, ["finance-external-sync:write"]);
+        const updateSyncState = options.finance?.updateExternalSyncState;
+        if (!updateSyncState)
+            throw notSupported("Finance external sync writes are unavailable.");
+        const result = await db.transaction(async (tx) => {
+            const mutation = await updateSyncState(tx, documentId, context.appId, input);
+            if (mutation.status === "ok") {
+                await audit(tx, access.installation, `app:${context.appId}`, "reconciliation", "finance.external-sync.updated", {
+                    documentId,
+                    provider: context.appId,
+                    operationId: input.operationId,
+                    syncStatus: input.status,
+                    outcome: mutation.outcome,
+                    releaseId: context.releaseId,
+                    tokenMode: context.tokenMode,
+                });
+            }
+            return mutation;
+        });
+        if (result.status === "not_found")
+            throw notFound("Finance document not found.");
+        if (result.status === "conflict") {
+            throw new ApiHttpError("External sync state conflicts with the current observation.", {
+                status: 409,
+                code: `app_api_finance_external_sync_${result.reason}`,
+                details: result,
+            });
+        }
+        return { data: result };
+    }
+    async function updateFinanceExternalLifecycleState(db, context, documentId, input) {
+        assertFinanceDocumentContext(context, documentId);
+        const access = await requireAccess(db, context, ["finance-external-lifecycle:write"]);
+        const updateLifecycleState = options.finance?.updateExternalLifecycleState;
+        if (!updateLifecycleState) {
+            throw notSupported("Finance external lifecycle writes are unavailable.");
+        }
+        const result = await db.transaction(async (tx) => {
+            const mutation = await updateLifecycleState(tx, documentId, context.appId, input);
+            if (mutation.status === "ok") {
+                await audit(tx, access.installation, `app:${context.appId}`, "reconciliation", "finance.external-lifecycle.updated", {
+                    documentId,
+                    provider: context.appId,
+                    operationId: input.operationId,
+                    lifecycleState: input.state,
+                    outcome: mutation.outcome,
+                    releaseId: context.releaseId,
+                    tokenMode: context.tokenMode,
+                });
+            }
+            return mutation;
+        });
+        if (result.status === "not_found")
+            throw notFound("Finance document not found.");
+        if (result.status === "conflict") {
+            throw new ApiHttpError("External lifecycle state conflicts with the current document.", {
+                status: 409,
+                code: `app_api_finance_external_lifecycle_${result.reason}`,
+                details: result,
+            });
+        }
+        return { data: result };
+    }
+    async function recordFinanceSettlementObservation(db, context, documentId, input) {
+        assertFinanceDocumentContext(context, documentId);
+        const access = await requireAccess(db, context, ["finance-settlement-observations:write"]);
+        const recordObservation = options.finance?.recordSettlementObservation;
+        if (!recordObservation) {
+            throw notSupported("Finance settlement observations are unavailable.");
+        }
+        const result = await db.transaction(async (tx) => {
+            const mutation = await recordObservation(tx, documentId, context.appId, input);
+            if (mutation.status === "ok") {
+                await audit(tx, access.installation, `app:${context.appId}`, "reconciliation", "finance.settlement-observation.recorded", {
+                    documentId,
+                    provider: context.appId,
+                    operationId: input.operationId,
+                    settlementStatus: input.status,
+                    outcome: mutation.outcome,
+                    releaseId: context.releaseId,
+                    tokenMode: context.tokenMode,
+                });
+            }
+            return mutation;
+        });
+        if (result.status === "not_found")
+            throw notFound("Finance document not found.");
+        if (result.status === "conflict") {
+            throw new ApiHttpError("Settlement observation conflicts with the current document.", {
+                status: 409,
+                code: `app_api_finance_settlement_observation_${result.reason}`,
+                details: result,
+            });
+        }
+        return { data: result };
+    }
     async function listCustomFieldDefinitions(db, context, query) {
         const access = await requireAccess(db, context, ["custom-field-definitions:read"]);
         return customFieldsRequired().listForOwner(db, owner(access), query);
@@ -120,7 +331,14 @@ export function createAppApiService(options = {}) {
         introspect,
         listEntities,
         listFinanceDocuments,
+        getFinanceIssuanceDocument,
         executeFinanceAction,
+        getFinanceExternalReference,
+        upsertFinanceExternalReference,
+        attachFinancePdfArtifact,
+        updateFinanceExternalSyncState,
+        updateFinanceExternalLifecycleState,
+        recordFinanceSettlementObservation,
         listCustomFieldDefinitions,
         createCustomFieldDefinition,
         updateCustomFieldDefinition,
@@ -218,6 +436,25 @@ export function assertCompatibleVersion(requested, range) {
         });
     }
 }
+function assertFinanceDocumentContext(context, documentId) {
+    const constraint = context.contextConstraint;
+    if (!constraint)
+        return;
+    if (constraint.entity?.type !== "invoice" || !documentId || constraint.entity.id !== documentId) {
+        throw new ApiHttpError("Online app token is not bound to this finance document.", {
+            status: 403,
+            code: "app_api_entity_context_mismatch",
+        });
+    }
+}
+function assertUnconstrainedFinanceContext(context) {
+    if (!context.contextConstraint)
+        return;
+    throw new ApiHttpError("Entity-bound online app tokens cannot list finance documents.", {
+        status: 403,
+        code: "app_api_entity_context_mismatch",
+    });
+}
 export async function withAppApiDeadline(promise, timeoutMs = 5_000) {
     let timeout;
     try {

package/dist/app-api-service.test.js

@@ -1,5 +1,7 @@
+import { FinanceAppApiNumberConflictError } from "@voyant-travel/finance-contracts/app-api";
 import { ApiHttpError } from "@voyant-travel/hono";
 import { describe, expect, it, vi } from "vitest";
+import { appApiFinanceExternalReferenceUpsertSchema } from "./app-api-contracts.js";
 import { assertAppNamespaceAlias, assertCompatibleVersion, createAppApiService, } from "./app-api-service.js";
 import { appGrants, appInstallations, appReleases } from "./schema.js";
 function postgresStub(implementation) {
@@ -86,6 +88,42 @@ describe("App API service boundary", () => {
         })).rejects.toMatchObject({ status: 403, code: "app_api_finance_approval_required" });
         expect(executeAction).not.toHaveBeenCalled();
     });
+    it("hydrates one finance document through the stable App API identifier", async () => {
+        const getIssuanceDocument = vi.fn().mockResolvedValue({ id: "inv_1" });
+        const service = createAppApiService({
+            finance: { listDocuments: vi.fn(), executeAction: vi.fn(), getIssuanceDocument },
+        });
+        await expect(service.getFinanceIssuanceDocument(createAccessDb({ scopes: ["finance-documents:read"] }), { ...context, scopes: ["finance-documents:read"] }, "inv_1")).resolves.toEqual({ data: { id: "inv_1" } });
+        expect(getIssuanceDocument).toHaveBeenCalledWith(expect.anything(), "inv_1");
+    });
+    it("maps a provider-owned invoice number conflict to a stable App API conflict", async () => {
+        const upsertExternalReference = vi
+            .fn()
+            .mockRejectedValue(new FinanceAppApiNumberConflictError("SB-42"));
+        const service = createAppApiService({ finance: { upsertExternalReference } });
+        const db = createAccessDb({
+            scopes: ["finance-external-references:write", "finance-external-allocation:write"],
+        });
+        Object.assign(db, {
+            transaction: (callback) => callback(db),
+        });
+        await expect(service.upsertFinanceExternalReference(db, {
+            ...context,
+            scopes: ["finance-external-references:write", "finance-external-allocation:write"],
+        }, "inv_1", {
+            reference: {
+                externalId: null,
+                externalNumber: null,
+                externalUrl: null,
+                status: null,
+                metadata: null,
+                syncedAt: null,
+                syncError: null,
+            },
+            allocation: { invoiceNumber: "SB-42" },
+        })).rejects.toMatchObject({ status: 409, code: "app_api_finance_number_conflict" });
+        expect(upsertExternalReference).toHaveBeenCalledWith(expect.anything(), "inv_1", "app_1", expect.anything());
+    });
     it("isolates rate limits per installation", async () => {
         const service = createAppApiService({
             rateLimit: { installationLimit: 1, appLimit: 10, windowMs: 60_000 },
@@ -106,4 +144,18 @@ describe("App API service boundary", () => {
         expect(() => assertCompatibleVersion("2026-07-01", { min: "2026-07-01", max: "2026-12-31" })).not.toThrow();
         expect(() => assertCompatibleVersion("2027-01-01", { min: "2026-07-01", max: "2026-12-31" })).toThrow(ApiHttpError);
     });
+    it("requires a complete bounded external-reference replacement", () => {
+        expect(appApiFinanceExternalReferenceUpsertSchema.safeParse({ reference: {} }).success).toBe(false);
+        expect(appApiFinanceExternalReferenceUpsertSchema.safeParse({
+            reference: {
+                externalId: null,
+                externalNumber: null,
+                externalUrl: null,
+                status: null,
+                metadata: { payload: "x".repeat(17_000) },
+                syncedAt: null,
+                syncError: null,
+            },
+        }).success).toBe(false);
+    });
 });

package/dist/consent.d.ts

@@ -13,3 +13,4 @@ export interface ComputedConsent {
     deniedOptionalScopes: string[];
 }
 export declare function computeAppConsent(input: ConsentComputationInput): ComputedConsent;
+export declare function grantableRemoteAppScopes(catalog: AccessCatalog): Set<string>;