@voyant-travel/apps 0.7.0 → 0.8.0

package/dist/api-runtime.d.ts

@@ -1,18 +1,10 @@
 export declare const createAppsApiModule: import("@voyant-travel/core/project").VoyantGraphRuntimeFactory<{
-    module: {
-        name: string;
-    };
-    adminRoutes: import("@hono/zod-openapi").OpenAPIHono<{
-        Bindings: {
-            VOYANT_CLOUD_DEPLOYMENT_ID?: string;
-        };
-        Variables: {
-            db: import("drizzle-orm/postgres-js").PostgresJsDatabase;
-        };
-    }, {}, "/">;
     lazyRoutes: {
         paths: string[];
         load: () => Promise<import("hono").Hono<{
+            Bindings: {
+                API_BASE_URL?: string;
+            };
             Variables: {
                 db: import("drizzle-orm/postgres-js").PostgresJsDatabase;
                 appId?: string;
@@ -20,9 +12,29 @@ export declare const createAppsApiModule: import("@voyant-travel/core/project").
                 appReleaseId?: string;
                 appTokenMode?: "offline" | "online";
                 appViewerId?: string;
+                appContextConstraint?: import("@voyant-travel/core").VoyantAppContextConstraint;
                 callerType?: string;
                 scopes?: string[];
             };
         }, import("hono/types").BlankSchema, "/">>;
     };
+    clientAuthenticated?: readonly [{
+        readonly method: "POST";
+        readonly path: "/oauth/token";
+    }, {
+        readonly method: "POST";
+        readonly path: "/oauth/session-token/exchange";
+    }] | undefined;
+    authAugmentation?: {
+        resolveAppToken: ({ db, token }: import("@voyant-travel/hono").VoyantAuthAppTokenResolveArgs<import("@voyant-travel/hono").VoyantBindings>) => Promise<import("@voyant-travel/core").VoyantAuthContext | null>;
+    } | undefined;
+    module: {
+        name: string;
+    };
+    adminRoutes: import("@hono/zod-openapi").OpenAPIHono<{
+        Variables: {
+            db: import("drizzle-orm/postgres-js").PostgresJsDatabase;
+            scopes?: string[];
+        };
+    }, {}, "/">;
 }>;

package/dist/api-runtime.js

@@ -3,7 +3,9 @@ import { customFieldValueLifecycleRuntimePort, customFieldValueOperationsRuntime
 import { createCustomFieldTargetRegistry } from "@voyant-travel/custom-fields";
 import { financeAppApiRuntimePort } from "@voyant-travel/finance-contracts/app-api";
 import { createAppsAppApiRoutes } from "./app-api-routes.js";
+import { createAppOAuthService } from "./oauth-service.js";
 import { createAppsAdminRoutes } from "./routes.js";
+import { appsManagedAuthRuntimePort } from "./runtime-port.js";
 export const createAppsApiModule = defineGraphRuntimeFactory(async ({ getPort, getPorts, graph, hasPort }) => {
     const customFieldTargets = createCustomFieldTargetRegistry(graph.customFieldTargets ?? []);
     const customFieldValueLifecycles = await getPorts(customFieldValueLifecycleRuntimePort);
@@ -11,9 +13,44 @@ export const createAppsApiModule = defineGraphRuntimeFactory(async ({ getPort, g
     const finance = hasPort(financeAppApiRuntimePort)
         ? await getPort(financeAppApiRuntimePort)
         : undefined;
+    const managedAuth = hasPort(appsManagedAuthRuntimePort)
+        ? await getPort(appsManagedAuthRuntimePort)
+        : undefined;
+    const oauthOptions = managedAuth
+        ? {
+            accessCatalog: graph.accessCatalog,
+            deploymentId: managedAuth.runtimeAudience,
+            clientAuthentication: "required",
+        }
+        : undefined;
+    const oauth = oauthOptions ? createAppOAuthService(oauthOptions) : undefined;
     return {
         module: { name: "apps" },
-        adminRoutes: createAppsAdminRoutes({ eventCatalog: graph.eventCatalog }),
+        adminRoutes: createAppsAdminRoutes({
+            eventCatalog: graph.eventCatalog,
+            ...(oauthOptions ? { oauth: oauthOptions } : {}),
+            ...(managedAuth
+                ? {
+                    sessionToken: {
+                        secret: managedAuth.sessionTokenSigningSecret,
+                        ...(managedAuth.sessionTokenTtlSeconds === undefined
+                            ? {}
+                            : { ttlSeconds: managedAuth.sessionTokenTtlSeconds }),
+                    },
+                }
+                : {}),
+        }),
+        ...(oauth
+            ? {
+                clientAuthenticated: [
+                    { method: "POST", path: "/oauth/token" },
+                    { method: "POST", path: "/oauth/session-token/exchange" },
+                ],
+                authAugmentation: {
+                    resolveAppToken: ({ db, token }) => oauth.resolveAccessToken(db, token),
+                },
+            }
+            : {}),
         lazyRoutes: {
             paths: ["/v1/app", "/v1/app/*"],
             load: async () => createAppsAppApiRoutes({

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

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

package/dist/api-runtime.test.js

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { createAppsApiModule } from "./api-runtime.js";
+import { appsManagedAuthRuntimePort } from "./runtime-port.js";
+const graph = {
+    providerSelections: {},
+    customFieldTargets: [],
+    accessCatalog: { resources: [], presets: [] },
+    eventCatalog: { schemaVersion: "voyant.event-catalog.v1", events: [] },
+    tools: [],
+    references: [],
+    setupSteps: [],
+};
+function context(managedAuth) {
+    return {
+        unitId: "@voyant-travel/apps",
+        projectConfig: {},
+        getUnitProjectConfig: () => undefined,
+        api: [],
+        graph,
+        runtimePorts: managedAuth ? { [appsManagedAuthRuntimePort.id]: managedAuth } : {},
+        hasPort: (port) => port.id === appsManagedAuthRuntimePort.id && managedAuth !== undefined,
+        getPort: async (port) => {
+            if (port.id === appsManagedAuthRuntimePort.id && managedAuth)
+                return managedAuth;
+            throw new Error(`missing ${port.id}`);
+        },
+        getPorts: async () => [],
+    };
+}
+describe("createAppsApiModule", () => {
+    it("keeps managed auth and client-authenticated routes off without host inputs", async () => {
+        const module = await createAppsApiModule(context());
+        expect(module.clientAuthenticated).toBeUndefined();
+        expect(module.authAugmentation).toBeUndefined();
+    });
+    it("composes OAuth, session exchange, and token resolution from the host port", async () => {
+        const module = await createAppsApiModule(context({
+            runtimeAudience: "deployment-1",
+            sessionTokenSigningSecret: "s".repeat(32),
+            sessionTokenTtlSeconds: 180,
+        }));
+        expect(module.clientAuthenticated).toEqual([
+            { method: "POST", path: "/oauth/token" },
+            { method: "POST", path: "/oauth/session-token/exchange" },
+        ]);
+        expect(module.authAugmentation?.resolveAppToken).toBeTypeOf("function");
+        await expect(module.authAugmentation?.resolveAppToken({
+            request: new Request("http://test/v1/app"),
+            env: { DATABASE_URL: "postgres://test" },
+            db: {},
+            token: "test-token",
+        })).resolves.toBeNull();
+    });
+});

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

@@ -1,5 +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 type { FinanceAppApiExternalLifecycleObservation, FinanceAppApiExternalReference, FinanceAppApiExternalSyncState, FinanceAppApiIssuanceDocument, FinanceAppApiPdfArtifact, FinanceAppApiSettlementObservation } 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";
@@ -48,6 +48,53 @@ export declare const appApiFinanceExternalReferenceUpsertSchema: z.ZodObject<{
         invoiceNumber: z.ZodString;
     }, z.core.$strict>>;
 }, z.core.$strict>;
+export declare const appApiFinancePdfArtifactHeadersSchema: z.ZodObject<{
+    idempotencyKey: z.ZodString;
+    fileName: z.ZodString;
+}, z.core.$strict>;
+export declare const appApiFinanceExternalSyncStateSchema: z.ZodObject<{
+    operationId: z.ZodString;
+    status: z.ZodEnum<{
+        succeeded: "succeeded";
+        retryable_failure: "retryable_failure";
+        terminal_failure: "terminal_failure";
+    }>;
+    occurredAt: z.ZodString;
+    error: z.ZodDefault<z.ZodNullable<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strict>>>;
+    metadata: z.ZodDefault<z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+}, z.core.$strict>;
+export declare const appApiFinanceExternalLifecycleStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    operationId: z.ZodString;
+    state: z.ZodLiteral<"converted">;
+    occurredAt: z.ZodString;
+    lineage: z.ZodObject<{
+        sourceDocumentId: z.ZodString;
+        successorDocumentId: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>, z.ZodObject<{
+    operationId: z.ZodString;
+    state: z.ZodLiteral<"voided">;
+    occurredAt: z.ZodString;
+    lineage: z.ZodDefault<z.ZodNull>;
+}, z.core.$strict>], "state">;
+export declare const appApiFinanceSettlementObservationSchema: z.ZodObject<{
+    operationId: z.ZodString;
+    occurredAt: z.ZodString;
+    status: z.ZodEnum<{
+        partial: "partial";
+        paid: "paid";
+    }>;
+    currency: z.ZodString;
+    totals: z.ZodObject<{
+        totalCents: z.ZodNumber;
+        paidCents: z.ZodNumber;
+        balanceDueCents: z.ZodNumber;
+    }, z.core.$strict>;
+    paymentIdentifiers: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
 export declare const appApiWebhookReplaySchema: z.ZodObject<{
     deliveryId: z.ZodString;
     signingKeyId: z.ZodString;
@@ -57,13 +104,6 @@ export declare const appApiAuditQuerySchema: z.ZodObject<{
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
-export declare const appApiTokenExchangeSchema: z.ZodObject<{
-    client_id: z.ZodString;
-    client_secret: z.ZodOptional<z.ZodString>;
-    viewer_id: z.ZodString;
-    viewer_scopes: z.ZodArray<z.ZodString>;
-    contextual_scopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strict>;
 export declare const appApiDefinitionNamespaceSchema: z.ZodObject<{
     namespace: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
@@ -72,7 +112,17 @@ 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 AppApiFinancePdfArtifactHeaders = z.infer<typeof appApiFinancePdfArtifactHeadersSchema>;
+export type AppApiFinanceExternalSyncStateInput = z.infer<typeof appApiFinanceExternalSyncStateSchema>;
+export type AppApiFinanceExternalLifecycleStateInput = z.infer<typeof appApiFinanceExternalLifecycleStateSchema>;
+export type AppApiFinanceSettlementObservationInput = z.infer<typeof appApiFinanceSettlementObservationSchema>;
 export type AppApiWebhookReplayInput = z.infer<typeof appApiWebhookReplaySchema>;
 export type AppApiAuditQuery = z.infer<typeof appApiAuditQuerySchema>;
 export type AppApiFinanceIssuanceDocument = FinanceAppApiIssuanceDocument;
 export type AppApiFinanceExternalReference = FinanceAppApiExternalReference;
+export type AppApiFinancePdfArtifact = FinanceAppApiPdfArtifact & {
+    documentUrl: string;
+};
+export type AppApiFinanceExternalSyncState = FinanceAppApiExternalSyncState;
+export type AppApiFinanceExternalLifecycleObservation = FinanceAppApiExternalLifecycleObservation;
+export type AppApiFinanceSettlementObservation = FinanceAppApiSettlementObservation;

package/dist/app-api-contracts.js

@@ -50,6 +50,108 @@ export const appApiFinanceExternalReferenceUpsertSchema = z
         .optional(),
 })
     .strict();
+export const appApiFinancePdfArtifactHeadersSchema = z
+    .object({
+    idempotencyKey: z.string().trim().min(1).max(200),
+    fileName: z
+        .string()
+        .trim()
+        .min(1)
+        .max(200)
+        .refine((value) => [...value].every((character) => {
+        const code = character.charCodeAt(0);
+        return code >= 32 && code !== 127 && character !== "/" && character !== "\\";
+    }), "Invalid artifact file name."),
+})
+    .strict();
+const appApiFinanceExternalSyncErrorSchema = z
+    .object({
+    code: z.string().trim().min(1).max(100),
+    message: z.string().trim().min(1).max(2_000),
+})
+    .strict();
+export const appApiFinanceExternalSyncStateSchema = z
+    .object({
+    operationId: z.string().trim().min(1).max(200),
+    status: z.enum(["succeeded", "retryable_failure", "terminal_failure"]),
+    occurredAt: z.string().datetime(),
+    error: appApiFinanceExternalSyncErrorSchema.nullable().default(null),
+    metadata: z
+        .record(z.string().trim().min(1).max(100), z.unknown())
+        .refine((value) => JSON.stringify(value).length <= 16_384, "Metadata is too large.")
+        .nullable()
+        .default(null),
+})
+    .strict()
+    .superRefine((value, context) => {
+    if (value.status === "succeeded" && value.error) {
+        context.addIssue({
+            code: "custom",
+            message: "Successful sync state cannot include an error.",
+        });
+    }
+    if (value.status !== "succeeded" && !value.error) {
+        context.addIssue({ code: "custom", message: "Failed sync state requires an error." });
+    }
+});
+const appApiFinanceDocumentLineageSchema = z
+    .object({
+    sourceDocumentId: z.string().trim().min(1).max(200),
+    successorDocumentId: z.string().trim().min(1).max(200),
+})
+    .strict();
+export const appApiFinanceExternalLifecycleStateSchema = z.discriminatedUnion("state", [
+    z
+        .object({
+        operationId: z.string().trim().min(1).max(200),
+        state: z.literal("converted"),
+        occurredAt: z.string().datetime(),
+        lineage: appApiFinanceDocumentLineageSchema,
+    })
+        .strict(),
+    z
+        .object({
+        operationId: z.string().trim().min(1).max(200),
+        state: z.literal("voided"),
+        occurredAt: z.string().datetime(),
+        lineage: z.null().default(null),
+    })
+        .strict(),
+]);
+export const appApiFinanceSettlementObservationSchema = z
+    .object({
+    operationId: z.string().trim().min(1).max(200),
+    occurredAt: z.string().datetime(),
+    status: z.enum(["partial", "paid"]),
+    currency: z
+        .string()
+        .trim()
+        .regex(/^[A-Z]{3}$/),
+    totals: z
+        .object({
+        totalCents: z.number().int().nonnegative(),
+        paidCents: z.number().int().positive(),
+        balanceDueCents: z.number().int().nonnegative(),
+    })
+        .strict(),
+    paymentIdentifiers: z
+        .array(z.string().trim().min(1).max(200))
+        .min(1)
+        .max(100)
+        .refine((value) => new Set(value).size === value.length, "Payment identifiers must be unique."),
+})
+    .strict()
+    .superRefine((value, context) => {
+    if (value.totals.paidCents + value.totals.balanceDueCents !== value.totals.totalCents) {
+        context.addIssue({ code: "custom", message: "Settlement totals must balance." });
+    }
+    if (value.status === "partial" && value.totals.balanceDueCents === 0) {
+        context.addIssue({ code: "custom", message: "Partial settlement requires a balance." });
+    }
+    if (value.status === "paid" && value.totals.balanceDueCents !== 0) {
+        context.addIssue({ code: "custom", message: "Paid settlement cannot have a balance." });
+    }
+});
 export const appApiWebhookReplaySchema = z
     .object({
     deliveryId: z.string().min(1),
@@ -61,15 +163,6 @@ export const appApiAuditQuerySchema = z.object({
     limit: z.coerce.number().int().min(1).max(100).default(25),
     offset: z.coerce.number().int().min(0).default(0),
 });
-export const appApiTokenExchangeSchema = z
-    .object({
-    client_id: z.string().min(1),
-    client_secret: z.string().optional(),
-    viewer_id: z.string().min(1),
-    viewer_scopes: z.array(z.string().min(1)),
-    contextual_scopes: z.array(z.string().min(1)).optional(),
-})
-    .strict();
 export const appApiDefinitionNamespaceSchema = z
     .object({
     namespace: z.string().optional(),