@voyant-travel/apps 0.4.0 → 0.6.0

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");
+    });
+});

package/dist/locale-resolution.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Deterministic app-locale resolution for the extension host (RFC §6.1).
+ *
+ * The host always passes the staff member's active locale to the frame. It also
+ * resolves an "app locale" against the installed release's declared locales so
+ * host-rendered labels (nav entries, extension titles) and the frame's initial
+ * direction are chosen consistently:
+ *
+ *   1. exact active-locale match;
+ *   2. progressively less specific language match (`pt-BR` → `pt`);
+ *   3. the app's declared default locale.
+ *
+ * Everything here is pure and BCP 47 aware only to the extent of splitting on
+ * the primary subtag — the app remains authoritative for its in-frame
+ * translations and may choose a more sophisticated fallback itself.
+ */
+export type AppTextDirection = "ltr" | "rtl";
+/** Text direction for a locale, from its primary language subtag. */
+export declare function resolveTextDirection(locale: string): AppTextDirection;
+export interface AppLocaleDeclaration {
+    defaultLocale: string;
+    supportedLocales: readonly string[];
+}
+export interface ResolvedAppLocale {
+    /** The active admin locale the host requested resolution for. */
+    requestedLocale: string;
+    /** The declared locale the host resolved to (exact → language → default). */
+    appLocale: string;
+    /** Text direction for {@link appLocale}. */
+    direction: AppTextDirection;
+}
+/**
+ * Resolve the app locale for an active admin locale against a release's
+ * declared locales. The returned `appLocale` is always one of the declared
+ * tags (falling back to `defaultLocale`), preserving the declared casing.
+ */
+export declare function resolveAppLocale(activeLocale: string, declaration: AppLocaleDeclaration): ResolvedAppLocale;
+/** One flattened host-rendered localization row (matches `app_release_localizations`). */
+export interface HostLabelRow {
+    locale: string;
+    surface: string;
+    messageKey: string;
+    text: string;
+}
+export interface HostLabelResolver {
+    /**
+     * Resolve a host-rendered label for a message key, trying the resolved app
+     * locale first and then the default locale (host labels use the platform
+     * algorithm, never the app's in-frame fallback). Returns null when no
+     * declared surface carries the key.
+     */
+    resolve(messageKey: string, surfaces?: readonly string[]): string | null;
+}
+/**
+ * Build a resolver over a release's localization rows for a resolved app locale
+ * with default-locale fallback. Missing translations fall back deterministically
+ * rather than throwing, so an incomplete non-default locale never blocks mount.
+ */
+export declare function createHostLabelResolver(rows: readonly HostLabelRow[], appLocale: string, defaultLocale: string): HostLabelResolver;

package/dist/locale-resolution.js

@@ -0,0 +1,113 @@
+/**
+ * Deterministic app-locale resolution for the extension host (RFC §6.1).
+ *
+ * The host always passes the staff member's active locale to the frame. It also
+ * resolves an "app locale" against the installed release's declared locales so
+ * host-rendered labels (nav entries, extension titles) and the frame's initial
+ * direction are chosen consistently:
+ *
+ *   1. exact active-locale match;
+ *   2. progressively less specific language match (`pt-BR` → `pt`);
+ *   3. the app's declared default locale.
+ *
+ * Everything here is pure and BCP 47 aware only to the extent of splitting on
+ * the primary subtag — the app remains authoritative for its in-frame
+ * translations and may choose a more sophisticated fallback itself.
+ */
+/**
+ * Primary language subtags written right-to-left. Kept small and explicit; the
+ * frame receives the resolved direction so it never has to infer it from an
+ * incomplete language list.
+ */
+const RTL_LANGUAGES = new Set([
+    "ar", // Arabic
+    "arc", // Aramaic
+    "ckb", // Central Kurdish (Sorani)
+    "dv", // Divehi
+    "fa", // Persian
+    "he", // Hebrew
+    "ku", // Kurdish
+    "ps", // Pashto
+    "sd", // Sindhi
+    "syr", // Syriac
+    "ur", // Urdu
+    "yi", // Yiddish
+]);
+/** The primary language subtag of a BCP 47 tag, lowercased. */
+function primaryLanguage(locale) {
+    return locale.trim().toLowerCase().split(/[-_]/)[0] ?? "";
+}
+/** Text direction for a locale, from its primary language subtag. */
+export function resolveTextDirection(locale) {
+    return RTL_LANGUAGES.has(primaryLanguage(locale)) ? "rtl" : "ltr";
+}
+/**
+ * Resolve the app locale for an active admin locale against a release's
+ * declared locales. The returned `appLocale` is always one of the declared
+ * tags (falling back to `defaultLocale`), preserving the declared casing.
+ */
+export function resolveAppLocale(activeLocale, declaration) {
+    const requested = activeLocale.trim();
+    const normalized = requested.toLowerCase();
+    const supported = declaration.supportedLocales;
+    const exact = supported.find((candidate) => candidate.toLowerCase() === normalized);
+    if (exact) {
+        return { requestedLocale: requested, appLocale: exact, direction: resolveTextDirection(exact) };
+    }
+    const requestedLanguage = primaryLanguage(requested);
+    if (requestedLanguage) {
+        const languageMatch = supported.find((candidate) => primaryLanguage(candidate) === requestedLanguage);
+        if (languageMatch) {
+            return {
+                requestedLocale: requested,
+                appLocale: languageMatch,
+                direction: resolveTextDirection(languageMatch),
+            };
+        }
+    }
+    return {
+        requestedLocale: requested,
+        appLocale: declaration.defaultLocale,
+        direction: resolveTextDirection(declaration.defaultLocale),
+    };
+}
+const DEFAULT_LABEL_SURFACES = ["extension", "navigation", "setup", "app"];
+/**
+ * Build a resolver over a release's localization rows for a resolved app locale
+ * with default-locale fallback. Missing translations fall back deterministically
+ * rather than throwing, so an incomplete non-default locale never blocks mount.
+ */
+export function createHostLabelResolver(rows, appLocale, defaultLocale) {
+    // locale → surface → messageKey → text
+    const byLocale = new Map();
+    for (const row of rows) {
+        const locale = row.locale.toLowerCase();
+        let surfaces = byLocale.get(locale);
+        if (!surfaces) {
+            surfaces = new Map();
+            byLocale.set(locale, surfaces);
+        }
+        let keys = surfaces.get(row.surface);
+        if (!keys) {
+            keys = new Map();
+            surfaces.set(row.surface, keys);
+        }
+        keys.set(row.messageKey, row.text);
+    }
+    const localePreference = [appLocale.toLowerCase(), defaultLocale.toLowerCase()];
+    return {
+        resolve(messageKey, surfaces = DEFAULT_LABEL_SURFACES) {
+            for (const locale of localePreference) {
+                const surfaceMap = byLocale.get(locale);
+                if (!surfaceMap)
+                    continue;
+                for (const surface of surfaces) {
+                    const text = surfaceMap.get(surface)?.get(messageKey);
+                    if (text !== undefined)
+                        return text;
+                }
+            }
+            return null;
+        },
+    };
+}

package/dist/locale-resolution.test.d.ts

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

package/dist/locale-resolution.test.js

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { createHostLabelResolver, resolveAppLocale, resolveTextDirection, } from "./locale-resolution.js";
+describe("resolveAppLocale", () => {
+    const declaration = { defaultLocale: "en", supportedLocales: ["en", "pt", "pt-BR", "ar"] };
+    it("prefers an exact match", () => {
+        expect(resolveAppLocale("pt-BR", declaration).appLocale).toBe("pt-BR");
+    });
+    it("falls back to a language match when the exact tag is absent", () => {
+        expect(resolveAppLocale("pt-PT", declaration).appLocale).toBe("pt");
+    });
+    it("is case-insensitive on the requested tag", () => {
+        expect(resolveAppLocale("PT-br", declaration).appLocale).toBe("pt-BR");
+    });
+    it("falls back to the declared default when nothing matches", () => {
+        expect(resolveAppLocale("de-DE", declaration).appLocale).toBe("en");
+    });
+    it("resolves text direction from the resolved locale", () => {
+        expect(resolveAppLocale("ar", declaration).direction).toBe("rtl");
+        expect(resolveAppLocale("en", declaration).direction).toBe("ltr");
+    });
+});
+describe("resolveTextDirection", () => {
+    it("marks RTL languages", () => {
+        expect(resolveTextDirection("he-IL")).toBe("rtl");
+        expect(resolveTextDirection("fa")).toBe("rtl");
+        expect(resolveTextDirection("en-US")).toBe("ltr");
+    });
+});
+describe("createHostLabelResolver", () => {
+    const rows = [
+        { locale: "en", surface: "extension", messageKey: "title", text: "Reports" },
+        { locale: "en", surface: "navigation", messageKey: "nav", text: "Reports" },
+        { locale: "pt", surface: "extension", messageKey: "title", text: "Relatórios" },
+    ];
+    it("resolves in the app locale first", () => {
+        const resolver = createHostLabelResolver(rows, "pt", "en");
+        expect(resolver.resolve("title")).toBe("Relatórios");
+    });
+    it("falls back to the default locale deterministically", () => {
+        const resolver = createHostLabelResolver(rows, "pt", "en");
+        // "nav" is missing in pt; falls back to en.
+        expect(resolver.resolve("nav", ["navigation"])).toBe("Reports");
+    });
+    it("returns null when no surface carries the key", () => {
+        const resolver = createHostLabelResolver(rows, "en", "en");
+        expect(resolver.resolve("missing")).toBeNull();
+    });
+});

package/dist/routes.d.ts

@@ -1,8 +1,15 @@
+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;
     };
@@ -12,6 +19,24 @@ export interface AppsAdminRouteOptions extends AppsServiceOptions {
         accessCatalog: AccessCatalog;
         deploymentId: string;
     };
+    /**
+     * Enables the iframe session-token broker. Requires {@link oauth} for the
+     * deployment audience and the actor-token-exchange primitive. `secret` is the
+     * root secret the signing key is HKDF-derived from.
+     */
+    sessionToken?: {
+        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 {};