@voyant-travel/apps 0.6.2 → 0.7.0

package/dist/api-runtime.js

@@ -1,12 +1,16 @@
 import { defineGraphRuntimeFactory } from "@voyant-travel/core/project";
 import { customFieldValueLifecycleRuntimePort, customFieldValueOperationsRuntimePort, } from "@voyant-travel/core/runtime-port";
 import { createCustomFieldTargetRegistry } from "@voyant-travel/custom-fields";
+import { financeAppApiRuntimePort } from "@voyant-travel/finance-contracts/app-api";
 import { createAppsAppApiRoutes } from "./app-api-routes.js";
 import { createAppsAdminRoutes } from "./routes.js";
-export const createAppsApiModule = defineGraphRuntimeFactory(async ({ getPorts, graph }) => {
+export const createAppsApiModule = defineGraphRuntimeFactory(async ({ getPort, getPorts, graph, hasPort }) => {
     const customFieldTargets = createCustomFieldTargetRegistry(graph.customFieldTargets ?? []);
     const customFieldValueLifecycles = await getPorts(customFieldValueLifecycleRuntimePort);
     const customFieldValueOperations = await getPorts(customFieldValueOperationsRuntimePort);
+    const finance = hasPort(financeAppApiRuntimePort)
+        ? await getPort(financeAppApiRuntimePort)
+        : undefined;
     return {
         module: { name: "apps" },
         adminRoutes: createAppsAdminRoutes({ eventCatalog: graph.eventCatalog }),
@@ -16,6 +20,7 @@ export const createAppsApiModule = defineGraphRuntimeFactory(async ({ getPorts,
                 customFieldTargets,
                 customFieldValueLifecycles,
                 customFieldValueOperations,
+                finance,
             }),
         },
     };

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

@@ -1,4 +1,5 @@
 import { customFieldDefinitionInputSchema, customFieldDefinitionListQuerySchema, customFieldValueListQuerySchema, updateCustomFieldDefinitionSchema, upsertCustomFieldValueSchema } from "@voyant-travel/custom-fields";
+import type { FinanceAppApiExternalReference, FinanceAppApiIssuanceDocument } from "@voyant-travel/finance-contracts/app-api";
 import { z } from "zod";
 export declare const APP_API_VERSION = "2026-07-01";
 export declare const appApiVersionHeader = "voyant-app-api-version";
@@ -24,6 +25,29 @@ export declare const appApiFinanceActionSchema: z.ZodObject<{
     idempotencyKey: z.ZodString;
     payload: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strict>;
+export declare const appApiFinanceExternalReferenceSchema: z.ZodObject<{
+    externalId: z.ZodNullable<z.ZodString>;
+    externalNumber: z.ZodNullable<z.ZodString>;
+    externalUrl: z.ZodNullable<z.ZodString>;
+    status: z.ZodNullable<z.ZodString>;
+    metadata: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    syncedAt: z.ZodNullable<z.ZodString>;
+    syncError: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const appApiFinanceExternalReferenceUpsertSchema: z.ZodObject<{
+    reference: z.ZodObject<{
+        externalId: z.ZodNullable<z.ZodString>;
+        externalNumber: z.ZodNullable<z.ZodString>;
+        externalUrl: z.ZodNullable<z.ZodString>;
+        status: z.ZodNullable<z.ZodString>;
+        metadata: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        syncedAt: z.ZodNullable<z.ZodString>;
+        syncError: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    allocation: z.ZodOptional<z.ZodObject<{
+        invoiceNumber: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
 export declare const appApiWebhookReplaySchema: z.ZodObject<{
     deliveryId: z.ZodString;
     signingKeyId: z.ZodString;
@@ -47,5 +71,8 @@ export { customFieldDefinitionInputSchema as appApiCustomFieldDefinitionCreateSc
 export type AppApiEntityReadQuery = z.infer<typeof appApiEntityReadQuerySchema>;
 export type AppApiFinanceDocumentQuery = z.infer<typeof appApiFinanceDocumentQuerySchema>;
 export type AppApiFinanceActionInput = z.infer<typeof appApiFinanceActionSchema>;
+export type AppApiFinanceExternalReferenceUpsertInput = z.infer<typeof appApiFinanceExternalReferenceUpsertSchema>;
 export type AppApiWebhookReplayInput = z.infer<typeof appApiWebhookReplaySchema>;
 export type AppApiAuditQuery = z.infer<typeof appApiAuditQuerySchema>;
+export type AppApiFinanceIssuanceDocument = FinanceAppApiIssuanceDocument;
+export type AppApiFinanceExternalReference = FinanceAppApiExternalReference;

package/dist/app-api-contracts.js

@@ -22,6 +22,34 @@ export const appApiFinanceActionSchema = z
     payload: z.record(z.string(), z.unknown()).default({}),
 })
     .strict();
+export const appApiFinanceExternalReferenceSchema = z
+    .object({
+    externalId: z.string().min(1).max(500).nullable(),
+    externalNumber: z.string().min(1).max(500).nullable(),
+    externalUrl: z
+        .string()
+        .url()
+        .max(2_048)
+        .refine((value) => new URL(value).protocol === "https:", "External URL must use HTTPS.")
+        .nullable(),
+    status: z.string().min(1).max(100).nullable(),
+    metadata: z
+        .record(z.string().min(1).max(100), z.unknown())
+        .refine((value) => JSON.stringify(value).length <= 16_384, "Metadata is too large.")
+        .nullable(),
+    syncedAt: z.string().datetime().nullable(),
+    syncError: z.string().max(4_000).nullable(),
+})
+    .strict();
+export const appApiFinanceExternalReferenceUpsertSchema = z
+    .object({
+    reference: appApiFinanceExternalReferenceSchema,
+    allocation: z
+        .object({ invoiceNumber: z.string().trim().min(1).max(500) })
+        .strict()
+        .optional(),
+})
+    .strict();
 export const appApiWebhookReplaySchema = z
     .object({
     deliveryId: z.string().min(1),

package/dist/app-api-finance-routes.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/app-api-finance-routes.test.js

@@ -0,0 +1,153 @@
+import { Hono } from "hono";
+import { describe, expect, it, vi } from "vitest";
+import { createAppsAppApiRoutes } from "./app-api-routes.js";
+import { appGrants, appInstallations, appReleases } from "./schema.js";
+function accessDb(scopes = ["finance-documents:read"]) {
+    const db = Object.create(null);
+    Object.assign(db, {
+        select: () => ({
+            from: (table) => ({
+                where: () => {
+                    const rows = () => {
+                        if (table === appInstallations) {
+                            return [
+                                {
+                                    id: "inst_1",
+                                    appId: "app_1",
+                                    deploymentId: "dep_1",
+                                    releaseId: "rel_1",
+                                    status: "active",
+                                    namespace: "app--one",
+                                },
+                            ];
+                        }
+                        if (table === appReleases) {
+                            return [
+                                {
+                                    id: "rel_1",
+                                    appId: "app_1",
+                                    releaseVersion: "1.0.0",
+                                    apiCompatibility: { min: "2026-07-01", max: "2026-12-31" },
+                                },
+                            ];
+                        }
+                        if (table === appGrants)
+                            return scopes.map((scope) => ({ scope }));
+                        return [];
+                    };
+                    return {
+                        // biome-ignore lint/suspicious/noThenProperty: models Drizzle's awaitable query builder.
+                        then: (resolve) => Promise.resolve(rows()).then(resolve),
+                        limit: async () => rows(),
+                    };
+                },
+            }),
+        }),
+    });
+    return db;
+}
+describe("finance App API routes", () => {
+    it("hydrates a finance issuance document by stable id", async () => {
+        const getIssuanceDocument = vi.fn().mockResolvedValue({ id: "inv_1" });
+        const app = new Hono();
+        app.use("*", async (c, next) => {
+            c.set("db", accessDb());
+            c.set("callerType", "app");
+            c.set("appId", "app_1");
+            c.set("appInstallationId", "inst_1");
+            c.set("appReleaseId", "rel_1");
+            c.set("appTokenMode", "offline");
+            c.set("scopes", ["finance-documents:read"]);
+            await next();
+        });
+        app.route("/", createAppsAppApiRoutes({ finance: { getIssuanceDocument } }));
+        const response = await app.request("/v1/app/finance/documents/inv_1");
+        expect(response.status).toBe(200);
+        await expect(response.json()).resolves.toEqual({ data: { id: "inv_1" } });
+    });
+    it("does not expose a caller-selected provider reference route", async () => {
+        const getExternalReference = vi.fn().mockResolvedValue({ id: "ref_1" });
+        const upsertExternalReference = vi.fn();
+        const app = new Hono();
+        app.use("*", async (c, next) => {
+            c.set("db", accessDb(["finance-external-references:read"]));
+            c.set("callerType", "app");
+            c.set("appId", "app_1");
+            c.set("appInstallationId", "inst_1");
+            c.set("appReleaseId", "rel_1");
+            c.set("appTokenMode", "offline");
+            c.set("scopes", ["finance-external-references:read"]);
+            await next();
+        });
+        app.route("/", createAppsAppApiRoutes({ finance: { getExternalReference, upsertExternalReference } }));
+        const ownedResponse = await app.request("/v1/app/finance/documents/inv_1/external-reference");
+        expect(ownedResponse.status).toBe(200);
+        expect(getExternalReference).toHaveBeenCalledWith(expect.anything(), "inv_1", "app_1");
+        const response = await app.request("/v1/app/finance/documents/inv_1/external-references/another-provider", {
+            method: "PUT",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                reference: {
+                    externalId: null,
+                    externalNumber: null,
+                    externalUrl: null,
+                    status: null,
+                    metadata: null,
+                    syncedAt: null,
+                    syncError: null,
+                },
+            }),
+        });
+        expect(response.status).toBe(404);
+        expect(upsertExternalReference).not.toHaveBeenCalled();
+    });
+    it("atomically writes the owned reference, allocation, and audit through HTTP", async () => {
+        const scopes = ["finance-external-references:write", "finance-external-allocation:write"];
+        const db = accessDb(scopes);
+        const auditValues = vi.fn().mockResolvedValue(undefined);
+        Object.assign(db, {
+            transaction: (callback) => callback(db),
+            insert: () => ({ values: auditValues }),
+        });
+        const upsertExternalReference = vi.fn().mockResolvedValue({
+            status: "ok",
+            reference: { id: "ref_1" },
+            referenceOutcome: "created",
+            allocationOutcome: "applied",
+        });
+        const app = new Hono();
+        app.use("*", async (c, next) => {
+            c.set("db", db);
+            c.set("callerType", "app");
+            c.set("appId", "app_1");
+            c.set("appInstallationId", "inst_1");
+            c.set("appReleaseId", "rel_1");
+            c.set("appTokenMode", "offline");
+            c.set("scopes", scopes);
+            await next();
+        });
+        app.route("/", createAppsAppApiRoutes({ finance: { upsertExternalReference } }));
+        const response = await app.request("/v1/app/finance/documents/inv_1/external-reference", {
+            method: "PUT",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                reference: {
+                    externalId: "remote_1",
+                    externalNumber: "SB-42",
+                    externalUrl: null,
+                    status: "issued",
+                    metadata: null,
+                    syncedAt: null,
+                    syncError: null,
+                },
+                allocation: { invoiceNumber: "SB-42" },
+            }),
+        });
+        expect(response.status).toBe(200);
+        expect(upsertExternalReference).toHaveBeenCalledWith(db, "inv_1", "app_1", expect.anything());
+        expect(auditValues).toHaveBeenCalledWith(expect.objectContaining({
+            appId: "app_1",
+            action: "finance.external-reference.upserted",
+        }));
+    });
+});

package/dist/app-api-routes.js

@@ -1,7 +1,7 @@
 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, appApiFinanceExternalReferenceUpsertSchema, appApiTokenExchangeSchema, 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";
@@ -50,6 +50,19 @@ 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.post("/finance/actions", async (c) => {
         const body = await parseJsonBody(c, appApiFinanceActionSchema);
         return run(c, service.executeFinanceAction(c.get("db"), appContext(c), body), options.deadlineMs);

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

@@ -1,7 +1,8 @@
 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, AppApiFinanceExternalReferenceUpsertInput } from "./app-api-contracts.js";
 export interface AppApiAccessContext {
     appId: string;
     installationId: string;
@@ -14,9 +15,9 @@ export interface AppApiAccessContext {
 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 +64,23 @@ 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";
+        };
+    }>;
     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-]*)?$/;
@@ -52,12 +54,26 @@ export function createAppApiService(options = {}) {
         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) {
+        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) {
         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 +82,62 @@ export function createAppApiService(options = {}) {
         }
         return { data: await options.finance.executeAction(db, input) };
     }
+    async function getFinanceExternalReference(db, 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) {
+        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 listCustomFieldDefinitions(db, context, query) {
         const access = await requireAccess(db, context, ["custom-field-definitions:read"]);
         return customFieldsRequired().listForOwner(db, owner(access), query);
@@ -120,7 +192,10 @@ export function createAppApiService(options = {}) {
         introspect,
         listEntities,
         listFinanceDocuments,
+        getFinanceIssuanceDocument,
         executeFinanceAction,
+        getFinanceExternalReference,
+        upsertFinanceExternalReference,
         listCustomFieldDefinitions,
         createCustomFieldDefinition,
         updateCustomFieldDefinition,

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/contracts.d.ts

@@ -29,8 +29,8 @@ export declare const appOwnedCustomFieldDeclarationSchema: z.ZodObject<{
     }, z.core.$strip>>>>;
     logicalNamespace: z.ZodOptional<z.ZodString>;
     dataClassification: z.ZodDefault<z.ZodEnum<{
-        internal: "internal";
         public: "public";
+        internal: "internal";
         confidential: "confidential";
         restricted: "restricted";
         personal: "personal";
@@ -106,8 +106,8 @@ export declare const appManifestSchema: z.ZodPipe<z.ZodRecord<z.ZodString, z.Zod
         }, z.core.$strip>>>>;
         logicalNamespace: z.ZodOptional<z.ZodString>;
         dataClassification: z.ZodDefault<z.ZodEnum<{
-            internal: "internal";
             public: "public";
+            internal: "internal";
             confidential: "confidential";
             restricted: "restricted";
             personal: "personal";
@@ -134,8 +134,8 @@ export declare const appManifestSchema: z.ZodPipe<z.ZodRecord<z.ZodString, z.Zod
     }, z.core.$strict>;
     data: z.ZodObject<{
         classifications: z.ZodArray<z.ZodEnum<{
-            internal: "internal";
             public: "public";
+            internal: "internal";
             confidential: "confidential";
             restricted: "restricted";
             personal: "personal";

package/dist/voyant.js

@@ -1,5 +1,6 @@
 import { defineModule, requirePort } from "@voyant-travel/core/project";
 import { customFieldValueLifecycleRuntimePort, customFieldValueOperationsRuntimePort, } from "@voyant-travel/core/runtime-port";
+import { financeAppApiRuntimePort } from "@voyant-travel/finance-contracts/runtime-port";
 const appsAdminRuntime = {
     entry: "@voyant-travel/apps-react/admin",
     export: "createSelectedAppsAdminExtension",
@@ -27,6 +28,7 @@ export const appsVoyantModule = defineModule({
             optional: true,
             cardinality: "many",
         }),
+        requirePort(financeAppApiRuntimePort, { optional: true }),
     ],
     api: [
         {
@@ -259,6 +261,45 @@ export const appsVoyantModule = defineModule({
                 ],
                 wildcard: "explicit-resource",
             },
+            {
+                id: "@voyant-travel/apps#access.finance-external-references",
+                resource: "finance-external-references",
+                label: "Finance external references",
+                description: "Read and record provider-owned finance document references.",
+                remoteSafe: true,
+                actions: [
+                    {
+                        action: "read",
+                        label: "Read external references",
+                        description: "Read the app provider's reference for a finance document.",
+                    },
+                    {
+                        action: "write",
+                        label: "Write external references",
+                        description: "Idempotently record the app provider's finance document reference.",
+                        sensitive: true,
+                        wildcard: "explicit",
+                    },
+                ],
+                wildcard: "explicit-resource",
+            },
+            {
+                id: "@voyant-travel/apps#access.finance-external-allocation",
+                resource: "finance-external-allocation",
+                label: "External finance number allocation",
+                description: "Write a provider-owned number to a pending finance document.",
+                remoteSafe: true,
+                actions: [
+                    {
+                        action: "write",
+                        label: "Allocate external finance number",
+                        description: "Atomically finalize a pending provider-owned document number.",
+                        sensitive: true,
+                        wildcard: "explicit",
+                    },
+                ],
+                wildcard: "explicit-resource",
+            },
             {
                 id: "@voyant-travel/apps#access.apps",
                 resource: "apps",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyant-travel/apps",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -123,12 +123,13 @@
     "zod": "^4.4.3",
     "@voyant-travel/admin": "^0.127.0",
     "@voyant-travel/admin-extension-sdk": "^0.2.0",
-    "@voyant-travel/core": "^0.126.0",
-    "@voyant-travel/custom-fields": "^0.2.2",
-    "@voyant-travel/db": "^0.114.11",
-    "@voyant-travel/hono": "^0.128.4",
+    "@voyant-travel/core": "^0.127.0",
+    "@voyant-travel/custom-fields": "^0.2.3",
+    "@voyant-travel/finance-contracts": "^0.107.0",
+    "@voyant-travel/db": "^0.114.13",
+    "@voyant-travel/hono": "^0.128.6",
     "@voyant-travel/types": "^0.109.4",
-    "@voyant-travel/webhook-delivery": "^0.4.1"
+    "@voyant-travel/webhook-delivery": "^0.4.2"
   },
   "devDependencies": {
     "@types/node": "^25.5.2",