@voyant-travel/apps 0.6.0 → 0.6.2

package/dist/routes-openapi.js

@@ -0,0 +1,195 @@
+import { createRoute, z } from "@hono/zod-openapi";
+import { activateInstallationBodySchema, appCredentialRevocationSchema, appInstallationAuditQuerySchema, appInstallationListQuerySchema, appListQuerySchema, appOAuthAuthorizeQuerySchema, appOAuthTokenSchema, appSessionTokenExchangeSchema, appSessionTokenIssueSchema, appWebhookReplaySchema, createCustomAppRegistrationSchema, installAppSchema, lifecycleActionBodySchema, releaseManifestFetchSchema, releaseManifestUploadSchema, } from "./contracts.js";
+const appIdParamSchema = z.object({ appId: z.string().min(1) });
+const installationIdParamSchema = z.object({ installationId: z.string().min(1) });
+const errorSchema = z.object({ error: z.string() });
+const dataEnvelopeSchema = z.object({ data: z.unknown() });
+const listEnvelopeSchema = z.object({
+    data: z.array(z.unknown()),
+    total: z.number(),
+    limit: z.number(),
+    offset: z.number(),
+});
+const releaseCreateResponseSchema = z.object({
+    data: z.unknown(),
+    digest: z.string(),
+    created: z.boolean(),
+});
+const oauthRedirectResponseSchema = z.object({
+    data: z.object({ redirectUrl: z.string().url(), state: z.string() }),
+});
+const tokenResponseSchema = z.record(z.string(), z.unknown());
+const credentialRevocationResponseSchema = z.object({
+    installationId: z.string(),
+    generation: z.number(),
+});
+const jsonContent = (schema, description) => ({
+    description,
+    content: { "application/json": { schema } },
+});
+const requiredJsonBody = (schema) => ({
+    required: true,
+    content: { "application/json": { schema } },
+});
+export const listAppsRoute = createRoute({
+    method: "get",
+    path: "/",
+    request: { query: appListQuerySchema },
+    responses: { 200: jsonContent(listEnvelopeSchema, "Paginated app registrations") },
+});
+export const createCustomAppRoute = createRoute({
+    method: "post",
+    path: "/",
+    request: { body: requiredJsonBody(createCustomAppRegistrationSchema) },
+    responses: {
+        201: jsonContent(dataEnvelopeSchema, "Created custom app registration"),
+        409: jsonContent(errorSchema, "Duplicate app registration"),
+    },
+});
+export const authorizeAppOAuthRoute = createRoute({
+    method: "post",
+    path: "/oauth/authorize",
+    request: { body: requiredJsonBody(appOAuthAuthorizeQuerySchema) },
+    responses: {
+        200: jsonContent(oauthRedirectResponseSchema, "OAuth authorization redirect target"),
+        501: jsonContent(errorSchema, "App OAuth is not configured"),
+    },
+});
+export const issueAppOAuthTokenRoute = createRoute({
+    method: "post",
+    path: "/oauth/token",
+    request: { body: requiredJsonBody(appOAuthTokenSchema) },
+    responses: {
+        200: jsonContent(tokenResponseSchema, "OAuth token response"),
+        501: jsonContent(errorSchema, "App OAuth is not configured"),
+    },
+});
+export const revokeAppInstallationCredentialsRoute = createRoute({
+    method: "post",
+    path: "/oauth/revoke-installation",
+    request: { body: requiredJsonBody(appCredentialRevocationSchema) },
+    responses: {
+        200: jsonContent(credentialRevocationResponseSchema, "Revoked installation credential generation"),
+        501: jsonContent(errorSchema, "App OAuth is not configured"),
+    },
+});
+export const issueAppSessionTokenRoute = createRoute({
+    method: "post",
+    path: "/installations/{installationId}/session-token",
+    request: {
+        params: installationIdParamSchema,
+        body: requiredJsonBody(appSessionTokenIssueSchema),
+    },
+    responses: {
+        201: jsonContent(dataEnvelopeSchema, "Issued app session token"),
+        501: jsonContent(errorSchema, "App session tokens are not configured"),
+    },
+});
+export const exchangeAppSessionTokenRoute = createRoute({
+    method: "post",
+    path: "/oauth/session-token/exchange",
+    request: { body: requiredJsonBody(appSessionTokenExchangeSchema) },
+    responses: {
+        200: jsonContent(tokenResponseSchema, "Online app token response"),
+        501: jsonContent(errorSchema, "App session tokens are not configured"),
+    },
+});
+export const installAppRoute = createRoute({
+    method: "post",
+    path: "/install",
+    request: { body: requiredJsonBody(installAppSchema) },
+    responses: { 201: jsonContent(dataEnvelopeSchema, "Installed app") },
+});
+export const listAppInstallationsRoute = createRoute({
+    method: "get",
+    path: "/installations",
+    request: { query: appInstallationListQuerySchema },
+    responses: { 200: jsonContent(listEnvelopeSchema, "Paginated app installations") },
+});
+export const getAppInstallationRoute = createRoute({
+    method: "get",
+    path: "/installations/{installationId}",
+    request: { params: installationIdParamSchema },
+    responses: {
+        200: jsonContent(dataEnvelopeSchema, "App installation detail"),
+        404: jsonContent(errorSchema, "App installation not found"),
+    },
+});
+export const listAppInstallationAuditRoute = createRoute({
+    method: "get",
+    path: "/installations/{installationId}/audit",
+    request: { params: installationIdParamSchema, query: appInstallationAuditQuerySchema },
+    responses: { 200: jsonContent(dataEnvelopeSchema, "App installation audit events") },
+});
+export const pauseAppInstallationRoute = createRoute({
+    method: "post",
+    path: "/installations/{installationId}/pause",
+    request: { params: installationIdParamSchema, body: requiredJsonBody(lifecycleActionBodySchema) },
+    responses: { 200: jsonContent(dataEnvelopeSchema, "Paused app installation") },
+});
+export const resumeAppInstallationRoute = createRoute({
+    method: "post",
+    path: "/installations/{installationId}/resume",
+    request: { params: installationIdParamSchema, body: requiredJsonBody(lifecycleActionBodySchema) },
+    responses: { 200: jsonContent(dataEnvelopeSchema, "Resumed app installation") },
+});
+export const uninstallAppInstallationRoute = createRoute({
+    method: "post",
+    path: "/installations/{installationId}/uninstall",
+    request: { params: installationIdParamSchema, body: requiredJsonBody(lifecycleActionBodySchema) },
+    responses: { 200: jsonContent(dataEnvelopeSchema, "Uninstalled app installation") },
+});
+export const activateAppInstallationRoute = createRoute({
+    method: "post",
+    path: "/installations/{installationId}/activate",
+    request: {
+        params: installationIdParamSchema,
+        body: requiredJsonBody(activateInstallationBodySchema),
+    },
+    responses: { 200: jsonContent(dataEnvelopeSchema, "Activated app installation release") },
+});
+export const previewAppInstallationPurgeRoute = createRoute({
+    method: "post",
+    path: "/installations/{installationId}/purge-preview",
+    request: { params: installationIdParamSchema, body: requiredJsonBody(lifecycleActionBodySchema) },
+    responses: { 200: jsonContent(dataEnvelopeSchema, "App installation purge preview") },
+});
+export const getAppRoute = createRoute({
+    method: "get",
+    path: "/{appId}",
+    request: { params: appIdParamSchema },
+    responses: {
+        200: jsonContent(dataEnvelopeSchema, "App registration"),
+        404: jsonContent(errorSchema, "App not found"),
+    },
+});
+export const listAppReleasesRoute = createRoute({
+    method: "get",
+    path: "/{appId}/releases",
+    request: { params: appIdParamSchema },
+    responses: { 200: jsonContent(dataEnvelopeSchema, "App releases") },
+});
+export const createAppReleaseRoute = createRoute({
+    method: "post",
+    path: "/{appId}/releases",
+    request: { params: appIdParamSchema, body: requiredJsonBody(releaseManifestUploadSchema) },
+    responses: { 201: jsonContent(releaseCreateResponseSchema, "Created app release") },
+});
+export const fetchAppReleaseRoute = createRoute({
+    method: "post",
+    path: "/{appId}/releases/fetch",
+    request: { params: appIdParamSchema, body: requiredJsonBody(releaseManifestFetchSchema) },
+    responses: { 201: jsonContent(releaseCreateResponseSchema, "Fetched app release") },
+});
+export const listAppWebhooksRoute = createRoute({
+    method: "get",
+    path: "/installations/{installationId}/webhooks",
+    request: { params: installationIdParamSchema },
+    responses: { 200: jsonContent(dataEnvelopeSchema, "App webhook delivery health") },
+});
+export const replayAppWebhookRoute = createRoute({
+    method: "post",
+    path: "/installations/{installationId}/webhooks/replay",
+    request: { params: installationIdParamSchema, body: requiredJsonBody(appWebhookReplaySchema) },
+    responses: { 202: jsonContent(dataEnvelopeSchema, "Replayed app webhook delivery") },
+});

package/dist/routes.d.ts

@@ -1,8 +1,8 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
 import type { EventBus } from "@voyant-travel/core/events";
 import type { createCustomFieldsService } from "@voyant-travel/custom-fields";
 import type { AccessCatalog } from "@voyant-travel/types/api-keys";
 import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
-import { Hono } from "hono";
 import { type AppsServiceOptions } from "./service.js";
 type CustomFieldsService = ReturnType<typeof createCustomFieldsService>;
 type Env = {
@@ -38,5 +38,5 @@ export interface AppsAdminRouteOptions extends AppsServiceOptions {
     eventBus?: EventBus;
     customFields?: CustomFieldsService;
 }
-export declare function createAppsAdminRoutes(options?: AppsAdminRouteOptions): Hono<Env, import("hono/types").BlankSchema, "/">;
+export declare function createAppsAdminRoutes(options?: AppsAdminRouteOptions): OpenAPIHono<Env, {}, "/">;
 export {};

package/dist/routes.js

@@ -1,17 +1,18 @@
-import { parseJsonBody, parseQuery, RequestValidationError, requireUserId, } from "@voyant-travel/hono";
-import { Hono } from "hono";
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { openApiValidationHook, parseJsonBody, parseQuery, RequestValidationError, requireUserId, } from "@voyant-travel/hono";
 import { z } from "zod";
 import { activateInstallationBodySchema, appCredentialRevocationSchema, appInstallationAuditQuerySchema, appInstallationListQuerySchema, appListQuerySchema, appOAuthAuthorizeQuerySchema, appOAuthTokenSchema, appSessionTokenExchangeSchema, appSessionTokenIssueSchema, appWebhookReplaySchema, createCustomAppRegistrationSchema, installAppSchema, lifecycleActionBodySchema, releaseManifestFetchSchema, releaseManifestUploadSchema, } from "./contracts.js";
 import { listAppReleases, listInstallationAudit, listInstallationSummaries, loadInstallationDetail, } from "./installation-read-model.js";
 import { createAppInstallationService } from "./installation-service.js";
 import { createAppOAuthService } from "./oauth-service.js";
+import { activateAppInstallationRoute, authorizeAppOAuthRoute, createAppReleaseRoute, createCustomAppRoute, exchangeAppSessionTokenRoute, fetchAppReleaseRoute, getAppInstallationRoute, getAppRoute, installAppRoute, issueAppOAuthTokenRoute, issueAppSessionTokenRoute, listAppInstallationAuditRoute, listAppInstallationsRoute, listAppReleasesRoute, listAppsRoute, listAppWebhooksRoute, pauseAppInstallationRoute, previewAppInstallationPurgeRoute, replayAppWebhookRoute, resumeAppInstallationRoute, revokeAppInstallationCredentialsRoute, uninstallAppInstallationRoute, } from "./routes-openapi.js";
 import { createAppsService } from "./service.js";
 import { createAppSessionTokenService } from "./session-token-service.js";
 import { listAppWebhookHealth, replayAppWebhookDelivery } from "./webhook-delivery.js";
 const appIdParamSchema = z.object({ appId: z.string().min(1) });
 const installationIdParamSchema = z.object({ installationId: z.string().min(1) });
 export function createAppsAdminRoutes(options = {}) {
-    const routes = new Hono();
+    const routes = new OpenAPIHono({ defaultHook: openApiValidationHook });
     const service = createAppsService(options);
     const installations = createAppInstallationService({
         deploymentId: options.oauth?.deploymentId ?? options.deploymentId,
@@ -28,11 +29,11 @@ export function createAppsAdminRoutes(options = {}) {
             oauth,
         })
         : null;
-    routes.get("/", async (c) => {
+    routes.openapi(listAppsRoute, async (c) => {
         const query = parseQuery(c, appListQuerySchema);
         return c.json(await service.list(c.get("db"), query), 200);
     });
-    routes.post("/", async (c) => {
+    routes.openapi(createCustomAppRoute, async (c) => {
         const body = await parseJsonBody(c, createCustomAppRegistrationSchema);
         const app = await service.createCustomApp(c.get("db"), body);
         return c.json({ data: app }, 201);
@@ -40,7 +41,7 @@ export function createAppsAdminRoutes(options = {}) {
     // Consent approval mutates state (installation, grants, authorization code),
     // so it must never be reachable through read-scoped GET requests. The admin
     // consent UI submits the approval and performs the redirect itself.
-    routes.post("/oauth/authorize", async (c) => {
+    routes.openapi(authorizeAppOAuthRoute, async (c) => {
         if (!oauth)
             return c.json({ error: "App OAuth is not configured" }, 501);
         const body = await parseJsonBody(c, appOAuthAuthorizeQuerySchema);
@@ -60,7 +61,7 @@ export function createAppsAdminRoutes(options = {}) {
         redirectUrl.searchParams.set("state", result.state);
         return c.json({ data: { redirectUrl: redirectUrl.toString(), state: result.state } }, 200);
     });
-    routes.post("/oauth/token", async (c) => {
+    routes.openapi(issueAppOAuthTokenRoute, async (c) => {
         if (!oauth)
             return c.json({ error: "App OAuth is not configured" }, 501);
         const body = await parseJsonBody(c, appOAuthTokenSchema);
@@ -91,7 +92,7 @@ export function createAppsAdminRoutes(options = {}) {
                 });
         return c.json(token, 200);
     });
-    routes.post("/oauth/revoke-installation", async (c) => {
+    routes.openapi(revokeAppInstallationCredentialsRoute, async (c) => {
         if (!oauth)
             return c.json({ error: "App OAuth is not configured" }, 501);
         const body = await parseJsonBody(c, appCredentialRevocationSchema);
@@ -101,7 +102,7 @@ export function createAppsAdminRoutes(options = {}) {
     // Staff-authenticated: the admin host requests a short-lived session token for
     // the current viewer + entity/slot context. The viewer is taken from the
     // authenticated session, never from the frame.
-    routes.post("/installations/:installationId/session-token", async (c) => {
+    routes.openapi(issueAppSessionTokenRoute, async (c) => {
         if (!sessionTokens)
             return c.json({ error: "App session tokens are not configured" }, 501);
         const { installationId } = parseInstallationParams(c.req.param());
@@ -117,7 +118,7 @@ export function createAppsAdminRoutes(options = {}) {
     });
     // App-backend-facing: exchange a presented session token for online actor
     // access. Client-authenticated; bounded by viewer ∩ app grants.
-    routes.post("/oauth/session-token/exchange", async (c) => {
+    routes.openapi(exchangeAppSessionTokenRoute, async (c) => {
         if (!sessionTokens)
             return c.json({ error: "App session tokens are not configured" }, 501);
         const body = await parseJsonBody(c, appSessionTokenExchangeSchema);
@@ -130,7 +131,7 @@ export function createAppsAdminRoutes(options = {}) {
         });
         return c.json(token, 200);
     });
-    routes.post("/install", async (c) => {
+    routes.openapi(installAppRoute, async (c) => {
         const body = await parseJsonBody(c, installAppSchema);
         // The deployment id is a runtime value (not known at graph-composition
         // time), so resolve it per request: explicit body → runtime env →
@@ -147,11 +148,11 @@ export function createAppsAdminRoutes(options = {}) {
         });
         return c.json({ data: result }, 201);
     });
-    routes.get("/installations", async (c) => {
+    routes.openapi(listAppInstallationsRoute, async (c) => {
         const query = parseQuery(c, appInstallationListQuerySchema);
         return c.json(await listInstallationSummaries(c.get("db"), query), 200);
     });
-    routes.get("/installations/:installationId", async (c) => {
+    routes.openapi(getAppInstallationRoute, async (c) => {
         const { installationId } = parseInstallationParams(c.req.param());
         const detail = await loadInstallationDetail(c.get("db"), installationId, {
             platformApiVersion: options.platformApiVersion,
@@ -160,19 +161,19 @@ export function createAppsAdminRoutes(options = {}) {
             ? c.json({ data: detail }, 200)
             : c.json({ error: "App installation not found" }, 404);
     });
-    routes.get("/installations/:installationId/audit", async (c) => {
+    routes.openapi(listAppInstallationAuditRoute, async (c) => {
         const { installationId } = parseInstallationParams(c.req.param());
         const query = parseQuery(c, appInstallationAuditQuerySchema);
         const data = await listInstallationAudit(c.get("db"), installationId, query.limit);
         return c.json({ data }, 200);
     });
-    routes.post("/installations/:installationId/pause", async (c) => {
+    routes.openapi(pauseAppInstallationRoute, async (c) => {
         const { installationId } = parseInstallationParams(c.req.param());
         const body = await parseJsonBody(c, lifecycleActionBodySchema);
         const result = await installations.pause(c.get("db"), { installationId, actorId: body.actorId });
         return c.json({ data: result }, 200);
     });
-    routes.post("/installations/:installationId/resume", async (c) => {
+    routes.openapi(resumeAppInstallationRoute, async (c) => {
         const { installationId } = parseInstallationParams(c.req.param());
         const body = await parseJsonBody(c, lifecycleActionBodySchema);
         const result = await installations.resume(c.get("db"), {
@@ -181,7 +182,7 @@ export function createAppsAdminRoutes(options = {}) {
         });
         return c.json({ data: result }, 200);
     });
-    routes.post("/installations/:installationId/uninstall", async (c) => {
+    routes.openapi(uninstallAppInstallationRoute, async (c) => {
         const { installationId } = parseInstallationParams(c.req.param());
         const body = await parseJsonBody(c, lifecycleActionBodySchema);
         const result = await installations.uninstall(c.get("db"), {
@@ -190,7 +191,7 @@ export function createAppsAdminRoutes(options = {}) {
         });
         return c.json({ data: result }, 200);
     });
-    routes.post("/installations/:installationId/activate", async (c) => {
+    routes.openapi(activateAppInstallationRoute, async (c) => {
         const { installationId } = parseInstallationParams(c.req.param());
         const body = await parseJsonBody(c, activateInstallationBodySchema);
         const result = await installations.upgrade(c.get("db"), {
@@ -200,7 +201,7 @@ export function createAppsAdminRoutes(options = {}) {
         });
         return c.json({ data: result }, 200);
     });
-    routes.post("/installations/:installationId/purge-preview", async (c) => {
+    routes.openapi(previewAppInstallationPurgeRoute, async (c) => {
         const { installationId } = parseInstallationParams(c.req.param());
         const body = await parseJsonBody(c, lifecycleActionBodySchema);
         const result = await installations.purgePreview(c.get("db"), {
@@ -209,33 +210,33 @@ export function createAppsAdminRoutes(options = {}) {
         });
         return c.json({ data: result }, 200);
     });
-    routes.get("/:appId", async (c) => {
+    routes.openapi(getAppRoute, async (c) => {
         const { appId } = parseParams(c.req.param());
         const app = await service.get(c.get("db"), appId);
         return app ? c.json({ data: app }, 200) : c.json({ error: "App not found" }, 404);
     });
-    routes.get("/:appId/releases", async (c) => {
+    routes.openapi(listAppReleasesRoute, async (c) => {
         const { appId } = parseParams(c.req.param());
         const data = await listAppReleases(c.get("db"), appId);
         return c.json({ data }, 200);
     });
-    routes.post("/:appId/releases", async (c) => {
+    routes.openapi(createAppReleaseRoute, async (c) => {
         const { appId } = parseParams(c.req.param());
         const body = await parseJsonBody(c, releaseManifestUploadSchema);
         const result = await service.releaseFromUpload(c.get("db"), appId, body);
         return c.json({ data: result.release, digest: result.digest, created: result.created }, 201);
     });
-    routes.post("/:appId/releases/fetch", async (c) => {
+    routes.openapi(fetchAppReleaseRoute, async (c) => {
         const { appId } = parseParams(c.req.param());
         const body = await parseJsonBody(c, releaseManifestFetchSchema);
         const result = await service.releaseFromFetch(c.get("db"), appId, body);
         return c.json({ data: result.release, digest: result.digest, created: result.created }, 201);
     });
-    routes.get("/installations/:installationId/webhooks", async (c) => {
+    routes.openapi(listAppWebhooksRoute, async (c) => {
         const { installationId } = parseInstallationParams(c.req.param());
         return c.json(await listAppWebhookHealth(c.get("db"), installationId), 200);
     });
-    routes.post("/installations/:installationId/webhooks/replay", async (c) => {
+    routes.openapi(replayAppWebhookRoute, async (c) => {
         parseInstallationParams(c.req.param());
         const body = await parseJsonBody(c, appWebhookReplaySchema);
         const delivery = await replayAppWebhookDelivery(c.get("db"), {

package/dist/runtime-contributor.d.ts

@@ -0,0 +1 @@
+export declare function createAppsRuntimePortContribution(): Readonly<Record<string, unknown>>;

package/dist/runtime-contributor.js

@@ -0,0 +1,3 @@
+export function createAppsRuntimePortContribution() {
+    return {};
+}

package/dist/voyant.js

@@ -33,6 +33,7 @@ export const appsVoyantModule = defineModule({
             id: "@voyant-travel/apps#api.admin",
             surface: "admin",
             mount: "apps",
+            openapi: { document: "apps" },
             resource: "apps",
             transactional: true,
             runtime: {
@@ -111,7 +112,18 @@ export const appsVoyantModule = defineModule({
                 label: "Own custom-field definitions",
                 description: "Read and write custom-field definitions owned by the app.",
                 remoteSafe: true,
-                actions: ["read", "write"],
+                actions: [
+                    {
+                        action: "read",
+                        label: "Read custom-field definitions",
+                        description: "Read definitions owned by the app.",
+                    },
+                    {
+                        action: "write",
+                        label: "Write custom-field definitions",
+                        description: "Create and update definitions owned by the app.",
+                    },
+                ],
                 wildcard: "explicit-resource",
             },
             {
@@ -120,7 +132,38 @@ export const appsVoyantModule = defineModule({
                 label: "Own custom-field values",
                 description: "Read and write app-owned custom-field values by target.",
                 remoteSafe: true,
-                actions: ["read", "write", "booking", "person", "organization", "invoice"],
+                actions: [
+                    {
+                        action: "read",
+                        label: "Read custom-field values",
+                        description: "Read custom-field values owned by the app.",
+                    },
+                    {
+                        action: "write",
+                        label: "Write custom-field values",
+                        description: "Write custom-field values owned by the app.",
+                    },
+                    {
+                        action: "booking",
+                        label: "Booking custom fields",
+                        description: "Access app-owned custom-field values on bookings.",
+                    },
+                    {
+                        action: "person",
+                        label: "Person custom fields",
+                        description: "Access app-owned custom-field values on people.",
+                    },
+                    {
+                        action: "organization",
+                        label: "Organization custom fields",
+                        description: "Access app-owned custom-field values on organizations.",
+                    },
+                    {
+                        action: "invoice",
+                        label: "Invoice custom fields",
+                        description: "Access app-owned custom-field values on invoices.",
+                    },
+                ],
                 wildcard: "explicit-resource",
             },
             {
@@ -133,7 +176,11 @@ export const appsVoyantModule = defineModule({
                 description: "Read webhook health and request replay.",
                 remoteSafe: true,
                 actions: [
-                    "read",
+                    {
+                        action: "read",
+                        label: "Read app webhooks",
+                        description: "Read app webhook subscription and delivery health.",
+                    },
                     { action: "replay", label: "Replay webhooks", description: "Replay deliveries." },
                 ],
             },
@@ -143,7 +190,13 @@ export const appsVoyantModule = defineModule({
                 label: "App audit history",
                 description: "Read audit history owned by the app.",
                 remoteSafe: true,
-                actions: ["read"],
+                actions: [
+                    {
+                        action: "read",
+                        label: "Read app audit history",
+                        description: "Read audit events owned by the app.",
+                    },
+                ],
             },
             {
                 id: "@voyant-travel/apps#access.online-token",
@@ -151,7 +204,14 @@ export const appsVoyantModule = defineModule({
                 label: "Online token exchange",
                 description: "Exchange admin session context for online app access.",
                 remoteSafe: true,
-                actions: [{ action: "exchange", wildcard: "explicit" }],
+                actions: [
+                    {
+                        action: "exchange",
+                        label: "Exchange online token",
+                        description: "Exchange admin session context for online app access.",
+                        wildcard: "explicit",
+                    },
+                ],
             },
             {
                 id: "@voyant-travel/apps#access.finance-documents",
@@ -159,7 +219,13 @@ export const appsVoyantModule = defineModule({
                 label: "Finance documents",
                 description: "Read finance documents visible to remote accounting apps.",
                 remoteSafe: true,
-                actions: ["read"],
+                actions: [
+                    {
+                        action: "read",
+                        label: "Read finance documents",
+                        description: "Read finance documents visible to the app.",
+                    },
+                ],
                 wildcard: "explicit-resource",
             },
             {
@@ -169,9 +235,27 @@ export const appsVoyantModule = defineModule({
                 description: "Request approved finance document actions.",
                 remoteSafe: true,
                 actions: [
-                    { action: "issue", sensitive: true, wildcard: "explicit" },
-                    { action: "retry", sensitive: true, wildcard: "explicit" },
-                    { action: "reconcile", sensitive: true, wildcard: "explicit" },
+                    {
+                        action: "issue",
+                        label: "Issue finance documents",
+                        description: "Request approved finance document issuance.",
+                        sensitive: true,
+                        wildcard: "explicit",
+                    },
+                    {
+                        action: "retry",
+                        label: "Retry finance actions",
+                        description: "Request approved finance action retry.",
+                        sensitive: true,
+                        wildcard: "explicit",
+                    },
+                    {
+                        action: "reconcile",
+                        label: "Reconcile finance documents",
+                        description: "Request approved finance document reconciliation.",
+                        sensitive: true,
+                        wildcard: "explicit",
+                    },
                 ],
                 wildcard: "explicit-resource",
             },

package/openapi/admin/apps.json

@@ -0,0 +1,72 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "Voyant Apps API",
+    "version": "1.0.0",
+    "description": "Operator app registration, release, installation, consent, token, and webhook governance routes."
+  },
+  "paths": {
+    "/v1/admin/apps": {
+      "get": { "summary": "List app registrations" },
+      "post": { "summary": "Create a custom app registration" }
+    },
+    "/v1/admin/apps/oauth/authorize": {
+      "post": { "summary": "Approve app OAuth consent" }
+    },
+    "/v1/admin/apps/oauth/token": {
+      "post": { "summary": "Issue an app OAuth token" }
+    },
+    "/v1/admin/apps/oauth/revoke-installation": {
+      "post": { "summary": "Revoke installation credentials" }
+    },
+    "/v1/admin/apps/oauth/session-token/exchange": {
+      "post": { "summary": "Exchange an app session token" }
+    },
+    "/v1/admin/apps/install": {
+      "post": { "summary": "Install an app release" }
+    },
+    "/v1/admin/apps/installations": {
+      "get": { "summary": "List app installations" }
+    },
+    "/v1/admin/apps/installations/{installationId}": {
+      "get": { "summary": "Get app installation detail" }
+    },
+    "/v1/admin/apps/installations/{installationId}/audit": {
+      "get": { "summary": "List app installation audit events" }
+    },
+    "/v1/admin/apps/installations/{installationId}/pause": {
+      "post": { "summary": "Pause an app installation" }
+    },
+    "/v1/admin/apps/installations/{installationId}/resume": {
+      "post": { "summary": "Resume an app installation" }
+    },
+    "/v1/admin/apps/installations/{installationId}/uninstall": {
+      "post": { "summary": "Uninstall an app installation" }
+    },
+    "/v1/admin/apps/installations/{installationId}/activate": {
+      "post": { "summary": "Activate an app installation release" }
+    },
+    "/v1/admin/apps/installations/{installationId}/purge-preview": {
+      "post": { "summary": "Preview app installation purge impact" }
+    },
+    "/v1/admin/apps/installations/{installationId}/session-token": {
+      "post": { "summary": "Issue an app extension session token" }
+    },
+    "/v1/admin/apps/installations/{installationId}/webhooks": {
+      "get": { "summary": "List app webhook delivery health" }
+    },
+    "/v1/admin/apps/installations/{installationId}/webhooks/replay": {
+      "post": { "summary": "Replay an app webhook delivery" }
+    },
+    "/v1/admin/apps/{appId}": {
+      "get": { "summary": "Get an app registration" }
+    },
+    "/v1/admin/apps/{appId}/releases": {
+      "get": { "summary": "List app releases" },
+      "post": { "summary": "Create an app release from an uploaded manifest" }
+    },
+    "/v1/admin/apps/{appId}/releases/fetch": {
+      "post": { "summary": "Create an app release from a fetched manifest" }
+    }
+  }
+}