@voyant-travel/apps 0.3.0 → 0.4.0

package/dist/api-runtime.d.ts

@@ -7,4 +7,19 @@ export declare const createAppsApiModule: import("@voyant-travel/core/project").
             db: import("drizzle-orm/postgres-js").PostgresJsDatabase;
         };
     }, import("hono/types").BlankSchema, "/">;
+    lazyRoutes: {
+        paths: string[];
+        load: () => Promise<import("hono").Hono<{
+            Variables: {
+                db: import("drizzle-orm/postgres-js").PostgresJsDatabase;
+                appId?: string;
+                appInstallationId?: string;
+                appReleaseId?: string;
+                appTokenMode?: "offline" | "online";
+                appViewerId?: string;
+                callerType?: string;
+                scopes?: string[];
+            };
+        }, import("hono/types").BlankSchema, "/">>;
+    };
 }>;

package/dist/api-runtime.js

@@ -1,8 +1,22 @@
 import { defineGraphRuntimeFactory } from "@voyant-travel/core/project";
+import { customFieldValueLifecycleRuntimePort, customFieldValueOperationsRuntimePort, } from "@voyant-travel/core/runtime-port";
+import { createCustomFieldTargetRegistry } from "@voyant-travel/custom-fields";
+import { createAppsAppApiRoutes } from "./app-api-routes.js";
 import { createAppsAdminRoutes } from "./routes.js";
-export const createAppsApiModule = defineGraphRuntimeFactory(async ({ graph }) => {
+export const createAppsApiModule = defineGraphRuntimeFactory(async ({ getPorts, graph }) => {
+    const customFieldTargets = createCustomFieldTargetRegistry(graph.customFieldTargets ?? []);
+    const customFieldValueLifecycles = await getPorts(customFieldValueLifecycleRuntimePort);
+    const customFieldValueOperations = await getPorts(customFieldValueOperationsRuntimePort);
     return {
         module: { name: "apps" },
         adminRoutes: createAppsAdminRoutes({ eventCatalog: graph.eventCatalog }),
+        lazyRoutes: {
+            paths: ["/v1/app", "/v1/app/*"],
+            load: async () => createAppsAppApiRoutes({
+                customFieldTargets,
+                customFieldValueLifecycles,
+                customFieldValueOperations,
+            }),
+        },
     };
 });

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

@@ -0,0 +1,51 @@
+import { customFieldDefinitionInputSchema, customFieldDefinitionListQuerySchema, customFieldValueListQuerySchema, updateCustomFieldDefinitionSchema, upsertCustomFieldValueSchema } from "@voyant-travel/custom-fields";
+import { z } from "zod";
+export declare const APP_API_VERSION = "2026-07-01";
+export declare const appApiVersionHeader = "voyant-app-api-version";
+export declare const appApiEntityReadQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const appApiFinanceDocumentQuerySchema: z.ZodObject<{
+    invoiceId: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const appApiFinanceActionSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        issue: "issue";
+        retry: "retry";
+        reconcile: "reconcile";
+    }>;
+    invoiceId: z.ZodOptional<z.ZodString>;
+    bookingId: z.ZodOptional<z.ZodString>;
+    approvalId: z.ZodOptional<z.ZodString>;
+    idempotencyKey: z.ZodString;
+    payload: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const appApiWebhookReplaySchema: z.ZodObject<{
+    deliveryId: z.ZodString;
+    signingKeyId: z.ZodString;
+    signingSecret: z.ZodString;
+}, z.core.$strict>;
+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>;
+export { customFieldDefinitionInputSchema as appApiCustomFieldDefinitionCreateSchema, customFieldDefinitionListQuerySchema as appApiCustomFieldDefinitionListQuerySchema, customFieldValueListQuerySchema as appApiCustomFieldValueListQuerySchema, updateCustomFieldDefinitionSchema as appApiCustomFieldDefinitionUpdateSchema, upsertCustomFieldValueSchema as appApiCustomFieldValueUpsertSchema, };
+export type AppApiEntityReadQuery = z.infer<typeof appApiEntityReadQuerySchema>;
+export type AppApiFinanceDocumentQuery = z.infer<typeof appApiFinanceDocumentQuerySchema>;
+export type AppApiFinanceActionInput = z.infer<typeof appApiFinanceActionSchema>;
+export type AppApiWebhookReplayInput = z.infer<typeof appApiWebhookReplaySchema>;
+export type AppApiAuditQuery = z.infer<typeof appApiAuditQuerySchema>;

package/dist/app-api-contracts.js

@@ -0,0 +1,50 @@
+import { customFieldDefinitionInputSchema, customFieldDefinitionListQuerySchema, customFieldValueListQuerySchema, updateCustomFieldDefinitionSchema, upsertCustomFieldValueSchema, } from "@voyant-travel/custom-fields";
+import { z } from "zod";
+export const APP_API_VERSION = "2026-07-01";
+export const appApiVersionHeader = "voyant-app-api-version";
+export const appApiEntityReadQuerySchema = z.object({
+    limit: z.coerce.number().int().min(1).max(100).default(25),
+    offset: z.coerce.number().int().min(0).default(0),
+});
+export const appApiFinanceDocumentQuerySchema = z.object({
+    invoiceId: z.string().min(1).optional(),
+    provider: z.string().min(1).optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(25),
+    offset: z.coerce.number().int().min(0).default(0),
+});
+export const appApiFinanceActionSchema = z
+    .object({
+    action: z.enum(["issue", "retry", "reconcile"]),
+    invoiceId: z.string().min(1).optional(),
+    bookingId: z.string().min(1).optional(),
+    approvalId: z.string().min(1).optional(),
+    idempotencyKey: z.string().min(1),
+    payload: z.record(z.string(), z.unknown()).default({}),
+})
+    .strict();
+export const appApiWebhookReplaySchema = z
+    .object({
+    deliveryId: z.string().min(1),
+    signingKeyId: z.string().min(1),
+    signingSecret: z.string().min(1),
+})
+    .strict();
+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(),
+})
+    .strict();
+export { customFieldDefinitionInputSchema as appApiCustomFieldDefinitionCreateSchema, customFieldDefinitionListQuerySchema as appApiCustomFieldDefinitionListQuerySchema, customFieldValueListQuerySchema as appApiCustomFieldValueListQuerySchema, updateCustomFieldDefinitionSchema as appApiCustomFieldDefinitionUpdateSchema, upsertCustomFieldValueSchema as appApiCustomFieldValueUpsertSchema, };

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

@@ -0,0 +1,28 @@
+import type { AccessCatalog } from "@voyant-travel/types/api-keys";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import { Hono } from "hono";
+import { type AppApiServiceOptions } from "./app-api-service.js";
+type Env = {
+    Variables: {
+        db: PostgresJsDatabase;
+        appId?: string;
+        appInstallationId?: string;
+        appReleaseId?: string;
+        appTokenMode?: "offline" | "online";
+        appViewerId?: string;
+        callerType?: string;
+        scopes?: string[];
+    };
+};
+/** Absolute mount prefix for the versioned App API surface. */
+export declare const APP_API_BASE_PATH = "/v1/app";
+export interface AppsAppApiRouteOptions extends AppApiServiceOptions {
+    oauth?: {
+        accessCatalog: AccessCatalog;
+        deploymentId: string;
+    };
+    deadlineMs?: number;
+    maxPayloadBytes?: number;
+}
+export declare function createAppsAppApiRoutes(options?: AppsAppApiRouteOptions): Hono<Env, import("hono/types").BlankSchema, "/">;
+export {};

package/dist/app-api-routes.js

@@ -0,0 +1,141 @@
+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 { 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";
+const idParamSchema = z.object({ id: z.string().min(1) });
+const entityParamSchema = z.object({ entity: z.string().min(1) });
+const definitionBodySchema = z
+    .object({
+    namespace: z.string().optional(),
+    definition: appApiCustomFieldDefinitionCreateSchema,
+})
+    .strict();
+const definitionUpdateBodySchema = z
+    .object({
+    namespace: z.string().optional(),
+    definition: appApiCustomFieldDefinitionUpdateSchema,
+})
+    .strict();
+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;
+    routes.use("*", async (c, next) => {
+        if (c.get("callerType") !== "app") {
+            throw new ApiHttpError("App API requires an app access token.", {
+                status: 401,
+                code: "app_api_token_required",
+            });
+        }
+        const length = Number(c.req.header("content-length") ?? "0");
+        if (Number.isFinite(length) && length > maxPayloadBytes) {
+            throw new ApiHttpError("App API payload is too large.", {
+                status: 413,
+                code: "app_api_payload_too_large",
+                details: { maxPayloadBytes },
+            });
+        }
+        return next();
+    });
+    routes.get("/self", (c) => run(c, service.introspect(c.get("db"), appContext(c)), options.deadlineMs));
+    routes.get("/entities/:entity", (c) => {
+        const { entity } = parseEntityParams(c.req.param());
+        const query = parseQuery(c, appApiEntityReadQuerySchema);
+        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.post("/finance/actions", async (c) => {
+        const body = await parseJsonBody(c, appApiFinanceActionSchema);
+        return run(c, service.executeFinanceAction(c.get("db"), appContext(c), body), options.deadlineMs);
+    });
+    routes.get("/custom-fields/definitions", (c) => run(c, service.listCustomFieldDefinitions(c.get("db"), appContext(c), parseQuery(c, appApiCustomFieldDefinitionListQuerySchema)), options.deadlineMs));
+    routes.post("/custom-fields/definitions", async (c) => {
+        const body = await parseJsonBody(c, definitionBodySchema);
+        return run(c, service.createCustomFieldDefinition(c.get("db"), appContext(c), body.namespace, body.definition), options.deadlineMs);
+    });
+    routes.patch("/custom-fields/definitions/:id", async (c) => {
+        const { id } = parseIdParams(c.req.param());
+        const body = await parseJsonBody(c, definitionUpdateBodySchema);
+        return run(c, service.updateCustomFieldDefinition(c.get("db"), appContext(c), id, body.namespace, body.definition), options.deadlineMs);
+    });
+    routes.get("/custom-fields/values", (c) => run(c, service.listCustomFieldValues(c.get("db"), appContext(c), parseQuery(c, appApiCustomFieldValueListQuerySchema)), options.deadlineMs));
+    routes.put("/custom-fields/definitions/:id/value", async (c) => {
+        const { id } = parseIdParams(c.req.param());
+        const body = await parseJsonBody(c, appApiCustomFieldValueUpsertSchema);
+        return run(c, service.upsertCustomFieldValue(c.get("db"), appContext(c), id, body), options.deadlineMs);
+    });
+    routes.get("/webhooks", (c) => run(c, service.listWebhookHealth(c.get("db"), appContext(c)), options.deadlineMs));
+    routes.post("/webhooks/replay", async (c) => {
+        await service.requireAccess(c.get("db"), appContext(c), ["webhooks:replay"]);
+        const body = await parseJsonBody(c, appApiWebhookReplaySchema);
+        return run(c, replayAppWebhookDelivery(c.get("db"), {
+            deliveryId: body.deliveryId,
+            actorId: appContext(c).appId,
+            signingKey: { id: body.signingKeyId, secret: body.signingSecret },
+        }), 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
+    // `/v1/app/*` up front.
+    const app = new Hono();
+    app.route(APP_API_BASE_PATH, routes);
+    return app;
+}
+function appContext(c) {
+    const appId = c.get("appId");
+    const installationId = c.get("appInstallationId");
+    const releaseId = c.get("appReleaseId");
+    const tokenMode = c.get("appTokenMode");
+    if (!appId || !installationId || !releaseId || !tokenMode) {
+        throw new RequestValidationError("App token context is missing.");
+    }
+    return {
+        appId,
+        installationId,
+        releaseId,
+        tokenMode,
+        viewerId: c.get("appViewerId"),
+        scopes: c.get("scopes") ?? [],
+        apiVersion: c.req.header(appApiVersionHeader) ?? undefined,
+    };
+}
+function parseIdParams(input) {
+    const parsed = idParamSchema.safeParse(input);
+    if (!parsed.success)
+        throw new RequestValidationError("Invalid route parameters");
+    return parsed.data;
+}
+function parseEntityParams(input) {
+    const parsed = entityParamSchema.safeParse(input);
+    if (!parsed.success)
+        throw new RequestValidationError("Invalid route parameters");
+    return parsed.data;
+}
+async function run(c, promise, deadlineMs, status = 200) {
+    const data = await withAppApiDeadline(promise, deadlineMs);
+    return c.json(data, status);
+}