@voyant-travel/apps 0.5.0 → 0.6.1

package/dist/api-runtime.d.ts

@@ -2,11 +2,14 @@ export declare const createAppsApiModule: import("@voyant-travel/core/project").
     module: {
         name: string;
     };
-    adminRoutes: import("hono").Hono<{
+    adminRoutes: import("@hono/zod-openapi").OpenAPIHono<{
+        Bindings: {
+            VOYANT_CLOUD_DEPLOYMENT_ID?: string;
+        };
         Variables: {
             db: import("drizzle-orm/postgres-js").PostgresJsDatabase;
         };
-    }, import("hono/types").BlankSchema, "/">;
+    }, {}, "/">;
     lazyRoutes: {
         paths: string[];
         load: () => Promise<import("hono").Hono<{

package/dist/app-api-routes.js

@@ -72,7 +72,7 @@ export function createAppsAppApiRoutes(options = {}) {
     });
     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"]);
+        await service.requireAccess(c.get("db"), appContext(c), ["app-webhooks:replay"]);
         const body = await parseJsonBody(c, appApiWebhookReplaySchema);
         return run(c, replayAppWebhookDelivery(c.get("db"), {
             deliveryId: body.deliveryId,

package/dist/app-api-service.js

@@ -99,7 +99,7 @@ export function createAppApiService(options = {}) {
         };
     }
     async function listWebhookHealth(db, context) {
-        await requireAccess(db, context, ["webhooks:read"]);
+        await requireAccess(db, context, ["app-webhooks:read"]);
         const data = await db
             .select()
             .from(appWebhookSubscriptions)

package/dist/contracts.d.ts

@@ -170,6 +170,44 @@ export declare const appListQuerySchema: z.ZodObject<{
     limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
 }, z.core.$strip>;
+export declare const appInstallationListQuerySchema: z.ZodObject<{
+    appId: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        pending: "pending";
+        authorizing: "authorizing";
+        paused: "paused";
+        degraded: "degraded";
+        revoked: "revoked";
+        uninstalled: "uninstalled";
+    }>>;
+    deploymentId: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    offset: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const appInstallationAuditQuerySchema: z.ZodObject<{
+    limit: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export declare const installAppSchema: z.ZodObject<{
+    appId: z.ZodString;
+    releaseId: z.ZodString;
+    actorId: z.ZodString;
+    grantedOptionalScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    updatePolicy: z.ZodOptional<z.ZodEnum<{
+        manual: "manual";
+        compatible: "compatible";
+        patch: "patch";
+        pinned: "pinned";
+    }>>;
+    deploymentId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const lifecycleActionBodySchema: z.ZodObject<{
+    actorId: z.ZodString;
+}, z.core.$strict>;
+export declare const activateInstallationBodySchema: z.ZodObject<{
+    releaseId: z.ZodString;
+    actorId: z.ZodString;
+}, z.core.$strict>;
 export declare const appWebhookReplaySchema: z.ZodObject<{
     deliveryId: z.ZodString;
     actorId: z.ZodString;
@@ -284,6 +322,11 @@ export type CreateCustomAppRegistrationInput = z.infer<typeof createCustomAppReg
 export type ReleaseManifestUploadInput = z.infer<typeof releaseManifestUploadSchema>;
 export type ReleaseManifestFetchInput = z.infer<typeof releaseManifestFetchSchema>;
 export type AppListQuery = z.infer<typeof appListQuerySchema>;
+export type AppInstallationListQuery = z.infer<typeof appInstallationListQuerySchema>;
+export type AppInstallationAuditQuery = z.infer<typeof appInstallationAuditQuerySchema>;
+export type InstallAppRequest = z.infer<typeof installAppSchema>;
+export type LifecycleActionBody = z.infer<typeof lifecycleActionBodySchema>;
+export type ActivateInstallationBody = z.infer<typeof activateInstallationBodySchema>;
 export type AppWebhookReplayInput = z.infer<typeof appWebhookReplaySchema>;
 export type AppOAuthAuthorizeQuery = z.infer<typeof appOAuthAuthorizeQuerySchema>;
 export type AppOAuthTokenInput = z.infer<typeof appOAuthTokenSchema>;

package/dist/contracts.js

@@ -213,6 +213,47 @@ export const appListQuerySchema = z.object({
     limit: z.coerce.number().int().positive().max(100).default(25),
     offset: z.coerce.number().int().nonnegative().default(0),
 });
+const appInstallationStatusValues = [
+    "pending",
+    "authorizing",
+    "active",
+    "paused",
+    "degraded",
+    "revoked",
+    "uninstalled",
+];
+const appInstallationUpdatePolicyValues = ["manual", "compatible", "patch", "pinned"];
+export const appInstallationListQuerySchema = z.object({
+    appId: z.string().trim().min(1).optional(),
+    status: z.enum(appInstallationStatusValues).optional(),
+    deploymentId: z.string().trim().min(1).optional(),
+    limit: z.coerce.number().int().positive().max(100).default(25),
+    offset: z.coerce.number().int().nonnegative().default(0),
+});
+export const appInstallationAuditQuerySchema = z.object({
+    limit: z.coerce.number().int().positive().max(200).default(50),
+});
+export const installAppSchema = z
+    .object({
+    appId: z.string().trim().min(1),
+    releaseId: z.string().trim().min(1),
+    actorId: z.string().trim().min(1).max(160),
+    grantedOptionalScopes: z.array(scopeSchema).optional(),
+    updatePolicy: z.enum(appInstallationUpdatePolicyValues).optional(),
+    deploymentId: z.string().trim().min(1).optional(),
+})
+    .strict();
+export const lifecycleActionBodySchema = z
+    .object({
+    actorId: z.string().trim().min(1).max(160),
+})
+    .strict();
+export const activateInstallationBodySchema = z
+    .object({
+    releaseId: z.string().trim().min(1),
+    actorId: z.string().trim().min(1).max(160),
+})
+    .strict();
 export const appWebhookReplaySchema = z
     .object({
     deliveryId: z.string().trim().min(1),

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from "./consent.js";
 export * from "./contracts.js";
 export * from "./extension-resolution.js";
 export * from "./ingestion.js";
+export * from "./installation-read-model.js";
 export * from "./installation-service.js";
 export * from "./locale-resolution.js";
 export * from "./oauth-crypto.js";

package/dist/index.js

@@ -7,6 +7,7 @@ export * from "./consent.js";
 export * from "./contracts.js";
 export * from "./extension-resolution.js";
 export * from "./ingestion.js";
+export * from "./installation-read-model.js";
 export * from "./installation-service.js";
 export * from "./locale-resolution.js";
 export * from "./oauth-crypto.js";

package/dist/installation-read-model.d.ts

@@ -0,0 +1,64 @@
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import type { AppInstallationListQuery } from "./contracts.js";
+import { type AppInstallation, type AppRegistration, type AppRelease, appAuditEvents, appExtensionInstallations, appGrants } from "./schema.js";
+import { listAppWebhookHealth } from "./webhook-delivery.js";
+export type AppGrantRow = typeof appGrants.$inferSelect;
+export type AppExtensionInstallationRow = typeof appExtensionInstallations.$inferSelect;
+export type AppAuditEventRow = typeof appAuditEvents.$inferSelect;
+export type AppWebhookHealth = Awaited<ReturnType<typeof listAppWebhookHealth>>;
+/**
+ * A single installation as shown in a governance list: the installation row
+ * plus the joined app and active-release descriptors the UI renders per row.
+ */
+export interface InstallationSummary extends AppInstallation {
+    appDisplayName: string;
+    appSlug: string;
+    distribution: AppRegistration["distribution"];
+    releaseVersion: string;
+}
+export interface InstallationListResult {
+    data: InstallationSummary[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/**
+ * A release the installation could move to, with whether governance can apply
+ * it without new consent and why it is blocked when it cannot.
+ */
+export interface AppAvailableUpdate {
+    release: AppRelease;
+    blocked: boolean;
+    blockedReason: string | null;
+}
+export interface InstallationDetail {
+    installation: AppInstallation;
+    app: AppRegistration;
+    activeRelease: AppRelease;
+    pendingRelease: AppRelease | null;
+    pendingReason: string | null;
+    grants: AppGrantRow[];
+    extensions: AppExtensionInstallationRow[];
+    webhooks: AppWebhookHealth;
+    recentAudit: AppAuditEventRow[];
+    availableUpdates: AppAvailableUpdate[];
+}
+export interface AvailableUpdateOptions {
+    platformApiVersion?: string;
+}
+export declare function listInstallationSummaries(db: PostgresJsDatabase, query: AppInstallationListQuery): Promise<InstallationListResult>;
+export declare function listAppReleases(db: PostgresJsDatabase, appId: string): Promise<AppRelease[]>;
+export declare function listInstallationAudit(db: PostgresJsDatabase, installationId: string, limit: number): Promise<AppAuditEventRow[]>;
+export declare function loadInstallationDetail(db: PostgresJsDatabase, installationId: string, options?: AvailableUpdateOptions): Promise<InstallationDetail | null>;
+/**
+ * Pure evaluation of which other available releases a governance operator can
+ * roll to. A candidate is blocked when it requires scopes the installation has
+ * not already granted, or when it falls outside the platform API range (only
+ * checked when a platform API version is known).
+ */
+export declare function computeAvailableUpdates(input: {
+    installation: Pick<AppInstallation, "releaseId">;
+    candidateReleases: readonly AppRelease[];
+    grantedScopes: ReadonlySet<string>;
+    platformApiVersion?: string;
+}): AppAvailableUpdate[];

package/dist/installation-read-model.js

@@ -0,0 +1,148 @@
+import { and, desc, eq, getTableColumns, sql } from "drizzle-orm";
+import { appAuditEvents, appExtensionInstallations, appGrants, appInstallations, appReleases, apps, } from "./schema.js";
+import { listAppWebhookHealth } from "./webhook-delivery.js";
+export async function listInstallationSummaries(db, query) {
+    const where = and(query.appId ? eq(appInstallations.appId, query.appId) : undefined, query.status ? eq(appInstallations.status, query.status) : undefined, query.deploymentId ? eq(appInstallations.deploymentId, query.deploymentId) : undefined);
+    const [data, count] = await Promise.all([
+        db
+            .select({
+            ...getTableColumns(appInstallations),
+            appDisplayName: apps.displayName,
+            appSlug: apps.slug,
+            distribution: apps.distribution,
+            releaseVersion: appReleases.releaseVersion,
+        })
+            .from(appInstallations)
+            .innerJoin(apps, eq(apps.id, appInstallations.appId))
+            .innerJoin(appReleases, eq(appReleases.id, appInstallations.releaseId))
+            .where(where)
+            .orderBy(desc(appInstallations.installedAt))
+            .limit(query.limit)
+            .offset(query.offset),
+        db.select({ count: sql `count(*)::int` }).from(appInstallations).where(where),
+    ]);
+    return { data, total: count[0]?.count ?? 0, limit: query.limit, offset: query.offset };
+}
+export async function listAppReleases(db, appId) {
+    return db
+        .select()
+        .from(appReleases)
+        .where(eq(appReleases.appId, appId))
+        .orderBy(desc(appReleases.createdAt));
+}
+export async function listInstallationAudit(db, installationId, limit) {
+    return db
+        .select()
+        .from(appAuditEvents)
+        .where(eq(appAuditEvents.installationId, installationId))
+        .orderBy(desc(appAuditEvents.createdAt))
+        .limit(limit);
+}
+export async function loadInstallationDetail(db, installationId, options = {}) {
+    const [installation] = await db
+        .select()
+        .from(appInstallations)
+        .where(eq(appInstallations.id, installationId))
+        .limit(1);
+    if (!installation)
+        return null;
+    const [app] = await db.select().from(apps).where(eq(apps.id, installation.appId)).limit(1);
+    if (!app)
+        return null;
+    const [activeRelease] = await db
+        .select()
+        .from(appReleases)
+        .where(eq(appReleases.id, installation.releaseId))
+        .limit(1);
+    if (!activeRelease)
+        return null;
+    const [grants, extensions, webhooks, recentAudit, candidateReleases, pendingRelease] = await Promise.all([
+        db
+            .select()
+            .from(appGrants)
+            .where(eq(appGrants.installationId, installation.id))
+            .orderBy(appGrants.scope),
+        db
+            .select()
+            .from(appExtensionInstallations)
+            .where(eq(appExtensionInstallations.installationId, installation.id))
+            .orderBy(appExtensionInstallations.extensionKey),
+        listAppWebhookHealth(db, installation.id),
+        listInstallationAudit(db, installation.id, 20),
+        db
+            .select()
+            .from(appReleases)
+            .where(and(eq(appReleases.appId, installation.appId), eq(appReleases.state, "available"))),
+        loadPendingRelease(db, installation.pendingReleaseId),
+    ]);
+    const grantedScopes = new Set(grants.filter((grant) => grant.status === "granted").map((grant) => grant.scope));
+    const availableUpdates = computeAvailableUpdates({
+        installation,
+        candidateReleases,
+        grantedScopes,
+        platformApiVersion: options.platformApiVersion,
+    });
+    return {
+        installation,
+        app,
+        activeRelease,
+        pendingRelease,
+        pendingReason: installation.pendingReason ?? null,
+        grants,
+        extensions,
+        webhooks,
+        recentAudit,
+        availableUpdates,
+    };
+}
+/**
+ * Pure evaluation of which other available releases a governance operator can
+ * roll to. A candidate is blocked when it requires scopes the installation has
+ * not already granted, or when it falls outside the platform API range (only
+ * checked when a platform API version is known).
+ */
+export function computeAvailableUpdates(input) {
+    const updates = [];
+    for (const release of input.candidateReleases) {
+        if (release.id === input.installation.releaseId)
+            continue;
+        updates.push({
+            release,
+            ...evaluateUpdateBlock(release, input.grantedScopes, input.platformApiVersion),
+        });
+    }
+    return updates;
+}
+function evaluateUpdateBlock(release, grantedScopes, platformApiVersion) {
+    const required = readRequestedScopes(release.normalizedRecord);
+    const missing = required.filter((scope) => !grantedScopes.has(scope));
+    if (missing.length > 0) {
+        return {
+            blocked: true,
+            blockedReason: `New required scopes need consent: ${missing.join(", ")}`,
+        };
+    }
+    if (platformApiVersion && !isApiCompatible(release.apiCompatibility, platformApiVersion)) {
+        return { blocked: true, blockedReason: "Release is not API-compatible with this platform" };
+    }
+    return { blocked: false, blockedReason: null };
+}
+function isApiCompatible(range, platformApiVersion) {
+    return platformApiVersion >= range.min && platformApiVersion <= range.max;
+}
+async function loadPendingRelease(db, pendingReleaseId) {
+    if (!pendingReleaseId)
+        return null;
+    const [row] = await db
+        .select()
+        .from(appReleases)
+        .where(eq(appReleases.id, pendingReleaseId))
+        .limit(1);
+    return row ?? null;
+}
+function readRequestedScopes(normalizedRecord) {
+    const value = normalizedRecord.requestedScopes;
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((item) => typeof item === "string");
+}

package/dist/installation-routes.test.d.ts

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

package/dist/installation-routes.test.js

@@ -0,0 +1,161 @@
+import { handleApiError } from "@voyant-travel/hono";
+import { Hono } from "hono";
+import { beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { createAppsAdminRoutes } from "./routes.js";
+import { createAppsService } from "./service.js";
+import { validManifest } from "./test-fixtures.js";
+const DB_AVAILABLE = !!process.env.TEST_DATABASE_URL;
+const DEPLOYMENT_ID = "deployment_test";
+const json = (body) => ({
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+});
+describe.skipIf(!DB_AVAILABLE)("apps installation admin routes", () => {
+    let app;
+    let db;
+    beforeAll(async () => {
+        const { createTestDb } = await import("@voyant-travel/db/test-utils");
+        db = createTestDb();
+        app = new Hono();
+        app.onError((err, c) => handleApiError(err, c));
+        app.use("*", async (c, next) => {
+            c.set("db", db);
+            await next();
+        });
+        app.route("/", createAppsAdminRoutes({ deploymentId: DEPLOYMENT_ID }));
+    });
+    beforeEach(async () => {
+        const { cleanupTestDb } = await import("@voyant-travel/db/test-utils");
+        await cleanupTestDb(db);
+    });
+    async function seedAppWithReleases() {
+        const service = createAppsService();
+        const registration = await service.createCustomApp(db, {
+            ownerId: "owner_1",
+            displayName: "Acme Sync",
+            slug: "acme-sync",
+            redirectUris: [],
+            createdBy: "user_1",
+        });
+        const v1 = await service.releaseFromUpload(db, registration.id, {
+            manifest: validManifest,
+            createdBy: "user_1",
+            provenance: { source: "test" },
+        });
+        const v2 = await service.releaseFromUpload(db, registration.id, {
+            manifest: {
+                ...validManifest,
+                releaseVersion: "2.0.0",
+                scopes: { requested: ["bookings:read", "customers:read"], optional: ["invoices:read"] },
+            },
+            createdBy: "user_1",
+            provenance: { source: "test" },
+        });
+        return { appId: registration.id, releaseV1: v1.release, releaseV2: v2.release };
+    }
+    async function installV1(appId, releaseId) {
+        const response = await app.request("/install", json({ appId, releaseId, actorId: "actor_1" }));
+        expect(response.status).toBe(201);
+        const payload = (await response.json());
+        return payload.data.installation;
+    }
+    it("lists installation summaries with joined app + release descriptors", async () => {
+        const { appId, releaseV1 } = await seedAppWithReleases();
+        await installV1(appId, releaseV1.id);
+        const response = await app.request("/installations");
+        expect(response.status).toBe(200);
+        const body = (await response.json());
+        expect(body.total).toBe(1);
+        expect(body.limit).toBe(25);
+        expect(body.offset).toBe(0);
+        const [summary] = body.data;
+        expect(summary).toMatchObject({
+            appId,
+            status: "active",
+            appDisplayName: "Acme Sync",
+            appSlug: "acme-sync",
+            distribution: "custom",
+            releaseVersion: "1.0.0",
+        });
+    });
+    it("aggregates installation detail with grants, extensions, webhooks, audit and blocked updates", async () => {
+        const { appId, releaseV1, releaseV2 } = await seedAppWithReleases();
+        const installation = await installV1(appId, releaseV1.id);
+        const response = await app.request(`/installations/${installation.id}`);
+        expect(response.status).toBe(200);
+        const body = (await response.json());
+        const detail = body.data;
+        expect(detail.installation.id).toBe(installation.id);
+        expect(detail.app.id).toBe(appId);
+        expect(detail.activeRelease.id).toBe(releaseV1.id);
+        expect(detail.pendingRelease).toBeNull();
+        expect(detail.pendingReason).toBeNull();
+        // grants are ordered by scope; bookings:read granted, invoices:read optional
+        expect(detail.grants.map((g) => g.scope)).toEqual(["bookings:read", "invoices:read"]);
+        const bookings = detail.grants.find((g) => g.scope === "bookings:read");
+        expect(bookings?.status).toBe("granted");
+        expect(detail.extensions.length).toBeGreaterThan(0);
+        expect(detail.webhooks.data.map((w) => w.eventType)).toContain("booking.created");
+        expect(detail.recentAudit.length).toBeGreaterThan(0);
+        // v2 introduces customers:read which was never granted -> blocked
+        const v2Update = detail.availableUpdates.find((u) => u.release.id === releaseV2.id);
+        expect(v2Update).toBeDefined();
+        expect(v2Update?.blocked).toBe(true);
+        expect(v2Update?.blockedReason).toBe("New required scopes need consent: customers:read");
+        // the active release is never offered as an update
+        expect(detail.availableUpdates.some((u) => u.release.id === releaseV1.id)).toBe(false);
+    });
+    it("returns 404 for an unknown installation", async () => {
+        const response = await app.request("/installations/app_installations_missing");
+        expect(response.status).toBe(404);
+        const body = (await response.json());
+        expect(body.error).toBe("App installation not found");
+    });
+    it("exposes the installation audit trail newest-first", async () => {
+        const { appId, releaseV1 } = await seedAppWithReleases();
+        const installation = await installV1(appId, releaseV1.id);
+        const response = await app.request(`/installations/${installation.id}/audit?limit=5`);
+        expect(response.status).toBe(200);
+        const body = (await response.json());
+        expect(body.data.length).toBeGreaterThan(0);
+        const timestamps = body.data.map((row) => row.createdAt);
+        const sorted = [...timestamps].sort((a, b) => (a < b ? 1 : -1));
+        expect(timestamps).toEqual(sorted);
+    });
+    it("lists all releases for an app newest-first", async () => {
+        const { appId, releaseV2 } = await seedAppWithReleases();
+        const response = await app.request(`/${appId}/releases`);
+        expect(response.status).toBe(200);
+        const body = (await response.json());
+        expect(body.data).toHaveLength(2);
+        expect(body.data[0]?.id).toBe(releaseV2.id);
+    });
+    it("drives pause -> resume -> uninstall then purge-preview", async () => {
+        const { appId, releaseV1 } = await seedAppWithReleases();
+        const installation = await installV1(appId, releaseV1.id);
+        const paused = await app.request(`/installations/${installation.id}/pause`, json({ actorId: "actor_1" }));
+        expect(paused.status).toBe(200);
+        expect((await paused.json()).data.installation.status).toBe("paused");
+        const resumed = await app.request(`/installations/${installation.id}/resume`, json({ actorId: "actor_1" }));
+        expect(resumed.status).toBe(200);
+        expect((await resumed.json()).data.installation.status).toBe("active");
+        const uninstalled = await app.request(`/installations/${installation.id}/uninstall`, json({ actorId: "actor_1" }));
+        expect(uninstalled.status).toBe(200);
+        expect((await uninstalled.json()).data.installation.status).toBe("uninstalled");
+        const purge = await app.request(`/installations/${installation.id}/purge-preview`, json({ actorId: "actor_1" }));
+        expect(purge.status).toBe(200);
+        const purgeBody = (await purge.json());
+        expect(purgeBody.data.grants).toBeGreaterThan(0);
+        expect(purgeBody.data.extensions).toBeGreaterThan(0);
+        expect(purgeBody.data.webhooks).toBeGreaterThan(0);
+    });
+    it("creates an active installation via /install", async () => {
+        const { appId, releaseV1 } = await seedAppWithReleases();
+        const response = await app.request("/install", json({ appId, releaseId: releaseV1.id, actorId: "actor_1" }));
+        expect(response.status).toBe(201);
+        const body = (await response.json());
+        expect(body.data.installation.status).toBe("active");
+        expect(body.data.outcome).toBe("created");
+    });
+});