@voyant-travel/apps 0.5.0 → 0.6.1

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,15 @@
+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 = {
+    Bindings: {
+        /** Deployment identity; the install lifecycle is scoped to it. */
+        VOYANT_CLOUD_DEPLOYMENT_ID?: string;
+    };
     Variables: {
         db: PostgresJsDatabase;
     };
@@ -21,6 +28,15 @@ export interface AppsAdminRouteOptions extends AppsServiceOptions {
         secret: string;
         ttlSeconds?: number;
     };
+    /**
+     * Deployment identity used when installing over HTTP. Falls back to
+     * {@link oauth}'s deployment id when omitted.
+     */
+    deploymentId?: string;
+    /** Platform API version used to gate release compatibility. */
+    platformApiVersion?: string;
+    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,16 +1,25 @@
-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 { appCredentialRevocationSchema, appListQuerySchema, appOAuthAuthorizeQuerySchema, appOAuthTokenSchema, appSessionTokenExchangeSchema, appSessionTokenIssueSchema, appWebhookReplaySchema, createCustomAppRegistrationSchema, releaseManifestFetchSchema, releaseManifestUploadSchema, } from "./contracts.js";
+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,
+        platformApiVersion: options.platformApiVersion,
+        eventBus: options.eventBus,
+        customFields: options.customFields,
+    });
     const oauth = options.oauth ? createAppOAuthService(options.oauth) : null;
     const sessionTokens = oauth && options.oauth && options.sessionToken
         ? createAppSessionTokenService({
@@ -20,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);
@@ -32,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);
@@ -52,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);
@@ -83,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);
@@ -93,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());
@@ -109,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);
@@ -122,28 +131,112 @@ export function createAppsAdminRoutes(options = {}) {
         });
         return c.json(token, 200);
     });
-    routes.get("/:appId", 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 →
+        // construction option. Without this the standard runtime mounts these
+        // routes with no deployment id and every install 400s (app_deployment_required).
+        const deploymentId = body.deploymentId ?? c.env?.VOYANT_CLOUD_DEPLOYMENT_ID?.trim() ?? options.deploymentId;
+        const result = await installations.install(c.get("db"), {
+            appId: body.appId,
+            releaseId: body.releaseId,
+            actorId: body.actorId,
+            grantedOptionalScopes: body.grantedOptionalScopes,
+            updatePolicy: body.updatePolicy,
+            deploymentId,
+        });
+        return c.json({ data: result }, 201);
+    });
+    routes.openapi(listAppInstallationsRoute, async (c) => {
+        const query = parseQuery(c, appInstallationListQuerySchema);
+        return c.json(await listInstallationSummaries(c.get("db"), query), 200);
+    });
+    routes.openapi(getAppInstallationRoute, async (c) => {
+        const { installationId } = parseInstallationParams(c.req.param());
+        const detail = await loadInstallationDetail(c.get("db"), installationId, {
+            platformApiVersion: options.platformApiVersion,
+        });
+        return detail
+            ? c.json({ data: detail }, 200)
+            : c.json({ error: "App installation not found" }, 404);
+    });
+    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.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.openapi(resumeAppInstallationRoute, async (c) => {
+        const { installationId } = parseInstallationParams(c.req.param());
+        const body = await parseJsonBody(c, lifecycleActionBodySchema);
+        const result = await installations.resume(c.get("db"), {
+            installationId,
+            actorId: body.actorId,
+        });
+        return c.json({ data: result }, 200);
+    });
+    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"), {
+            installationId,
+            actorId: body.actorId,
+        });
+        return c.json({ data: result }, 200);
+    });
+    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"), {
+            installationId,
+            releaseId: body.releaseId,
+            actorId: body.actorId,
+        });
+        return c.json({ data: result }, 200);
+    });
+    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"), {
+            installationId,
+            actorId: body.actorId,
+        });
+        return c.json({ data: result }, 200);
+    });
+    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.post("/: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.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

@@ -1,5 +1,9 @@
 import { defineModule, requirePort } from "@voyant-travel/core/project";
 import { customFieldValueLifecycleRuntimePort, customFieldValueOperationsRuntimePort, } from "@voyant-travel/core/runtime-port";
+const appsAdminRuntime = {
+    entry: "@voyant-travel/apps-react/admin",
+    export: "createSelectedAppsAdminExtension",
+};
 const appInstallationLifecyclePayloadSchema = {
     type: "object",
     additionalProperties: false,
@@ -29,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: {
@@ -107,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",
             },
             {
@@ -116,17 +132,55 @@ 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",
             },
             {
-                id: "@voyant-travel/apps#access.webhooks",
-                resource: "webhooks",
+                id: "@voyant-travel/apps#access.app-webhooks",
+                // Namespaced `app-webhooks` (not `webhooks`) to avoid a duplicate
+                // access-resource authority with @voyant-travel/workflow-runs, which
+                // owns the deployment `webhooks` resource.
+                resource: "app-webhooks",
                 label: "App webhooks",
                 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." },
                 ],
             },
@@ -136,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",
@@ -144,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",
@@ -152,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",
             },
             {
@@ -162,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",
             },
@@ -189,6 +280,49 @@ export const appsVoyantModule = defineModule({
             },
         ],
     },
+    admin: {
+        compositionOrder: 170,
+        runtime: appsAdminRuntime,
+        copy: [
+            {
+                id: "@voyant-travel/apps#admin.copy",
+                namespace: "apps.admin",
+                fallbackLocale: "en",
+                runtime: {
+                    entry: "@voyant-travel/apps-react/i18n",
+                    export: "appsUiMessageDefinitions",
+                },
+            },
+        ],
+        routes: [
+            {
+                id: "@voyant-travel/apps#admin.route.installed",
+                path: "/apps",
+                requiredScopes: ["apps:read"],
+                runtime: appsAdminRuntime,
+            },
+            {
+                id: "@voyant-travel/apps#admin.route.developer",
+                path: "/apps/developer",
+                requiredScopes: ["apps:write"],
+                runtime: appsAdminRuntime,
+            },
+        ],
+        nav: [
+            {
+                id: "@voyant-travel/apps#admin.nav.installed",
+                routeId: "@voyant-travel/apps#admin.route.installed",
+                label: { namespace: "apps.admin", key: "navigation.title" },
+                order: 170,
+            },
+            {
+                id: "@voyant-travel/apps#admin.nav.developer",
+                routeId: "@voyant-travel/apps#admin.route.developer",
+                label: { namespace: "apps.admin", key: "navigation.developerTitle" },
+                order: 171,
+            },
+        ],
+    },
     lifecycle: { uninstall: { default: "retain-data", purge: "not-supported" } },
     meta: {
         ownership: "package",