@voyant-travel/apps 0.3.0 → 0.5.0

package/dist/extension-resolution.js

@@ -0,0 +1,159 @@
+/**
+ * Installation-backed admin extension resolution (RFC §6, Phase 3).
+ *
+ * Replaces the static self-hosted descriptor list as the source of activated
+ * admin extensions: descriptors come from `app_extension_installations` for
+ * `active` installations only, so pausing, degrading, or uninstalling an app
+ * immediately drops its pages and slots. Slot extensions are filtered by
+ * release-pinned `extensionApi` compatibility, and host-rendered labels (nav
+ * entries, extension titles) plus the resolved app locale + text direction come
+ * from the installed release's declared locales and `app_release_localizations`.
+ *
+ * The returned descriptors are the exact shape the admin host consumes; static
+ * deployment-graph descriptors remain supported alongside these.
+ */
+import { ADMIN_UI_EXTENSION_API_VERSION, isUiExtensionCompatible, } from "@voyant-travel/admin-extension-sdk";
+import { and, eq, inArray } from "drizzle-orm";
+import { createHostLabelResolver, resolveAppLocale, } from "./locale-resolution.js";
+import { appExtensionInstallations, appInstallations, appReleaseLocalizations, appReleases, } from "./schema.js";
+export async function resolveInstalledExtensions(db, input) {
+    const rows = await db
+        .select({
+        installationId: appInstallations.id,
+        appId: appInstallations.appId,
+        extensionKey: appExtensionInstallations.extensionKey,
+        descriptor: appExtensionInstallations.descriptor,
+        releaseId: appExtensionInstallations.releaseId,
+        defaultLocale: appReleases.defaultLocale,
+        supportedLocales: appReleases.supportedLocales,
+    })
+        .from(appExtensionInstallations)
+        .innerJoin(appInstallations, eq(appExtensionInstallations.installationId, appInstallations.id))
+        .innerJoin(appReleases, eq(appExtensionInstallations.releaseId, appReleases.id))
+        .where(and(eq(appInstallations.deploymentId, input.deploymentId), 
+    // Active installations only: paused/degraded/uninstalled apps unmount.
+    eq(appInstallations.status, "active"), eq(appExtensionInstallations.status, "active")));
+    const localizationsByRelease = await loadLocalizations(db, rows.map((row) => row.releaseId));
+    return assembleInstalledExtensions(rows, localizationsByRelease, {
+        activeLocale: input.activeLocale,
+        extensionApiVersion: input.extensionApiVersion,
+    });
+}
+/**
+ * Pure assembly of resolved descriptors from store rows and localization data.
+ * Applies compatibility filtering, locale resolution, and host-label lookup.
+ * The `rows` are assumed to already be scoped to active installations/extensions.
+ */
+export function assembleInstalledExtensions(rows, localizationsByRelease, options) {
+    const version = options.extensionApiVersion ?? ADMIN_UI_EXTENSION_API_VERSION;
+    const slots = [];
+    const pages = [];
+    for (const row of rows) {
+        const declaration = {
+            defaultLocale: row.defaultLocale,
+            supportedLocales: row.supportedLocales,
+        };
+        const locale = resolveAppLocale(options.activeLocale, declaration);
+        const labels = createHostLabelResolver(localizationsByRelease.get(row.releaseId) ?? [], locale.appLocale, declaration.defaultLocale);
+        if (row.extensionKey.startsWith("page:")) {
+            const page = parsePageDescriptor(row.descriptor);
+            if (!page)
+                continue;
+            const title = labels.resolve(page.titleKey, ["extension", "navigation"]) ?? page.key;
+            const navLabel = labels.resolve(page.titleKey, ["navigation", "extension"]) ?? title;
+            pages.push({
+                key: `${row.installationId}:${page.key}`,
+                installationId: row.installationId,
+                appId: row.appId,
+                path: page.path,
+                entryUrl: page.entryUrl,
+                title,
+                navLabel,
+                appLocale: locale.appLocale,
+                direction: locale.direction,
+            });
+            continue;
+        }
+        if (row.extensionKey.startsWith("slot:")) {
+            const slot = parseSlotDescriptor(row.descriptor);
+            if (!slot)
+                continue;
+            // Release-pinned compatibility filter: an incompatible extension is not
+            // mounted (the host's render-time check is defense-in-depth).
+            if (!isUiExtensionCompatible(slot.extensionApi, version))
+                continue;
+            const displayName = labels.resolve(slot.titleKey, ["extension", "navigation"]) ?? slot.key;
+            slots.push({
+                descriptor: {
+                    key: `${row.installationId}:${slot.key}`,
+                    version: slot.version,
+                    displayName,
+                    extensionApi: slot.extensionApi,
+                    entryUrl: slot.entryUrl,
+                    slots: slot.slots,
+                    ...(slot.config ? { config: slot.config } : {}),
+                },
+                installationId: row.installationId,
+                appId: row.appId,
+                appLocale: locale.appLocale,
+                direction: locale.direction,
+            });
+        }
+    }
+    return { slots, pages };
+}
+async function loadLocalizations(db, releaseIds) {
+    const unique = [...new Set(releaseIds)];
+    const grouped = new Map();
+    if (unique.length === 0)
+        return grouped;
+    const rows = await db
+        .select({
+        releaseId: appReleaseLocalizations.releaseId,
+        locale: appReleaseLocalizations.locale,
+        surface: appReleaseLocalizations.surface,
+        messageKey: appReleaseLocalizations.messageKey,
+        text: appReleaseLocalizations.text,
+    })
+        .from(appReleaseLocalizations)
+        .where(inArray(appReleaseLocalizations.releaseId, unique));
+    for (const row of rows) {
+        const list = grouped.get(row.releaseId) ?? [];
+        list.push({
+            locale: row.locale,
+            surface: row.surface,
+            messageKey: row.messageKey,
+            text: row.text,
+        });
+        grouped.set(row.releaseId, list);
+    }
+    return grouped;
+}
+function parsePageDescriptor(value) {
+    const key = stringField(value.key);
+    const titleKey = stringField(value.titleKey);
+    const path = stringField(value.path);
+    const entryUrl = stringField(value.entryUrl);
+    if (!key || !titleKey || !path || !entryUrl)
+        return null;
+    return { key, titleKey, path, entryUrl };
+}
+function parseSlotDescriptor(value) {
+    const key = stringField(value.key);
+    const titleKey = stringField(value.titleKey);
+    const version = stringField(value.version);
+    const extensionApi = stringField(value.extensionApi);
+    const entryUrl = stringField(value.entryUrl);
+    const slots = Array.isArray(value.slots)
+        ? value.slots.filter((slot) => typeof slot === "string")
+        : [];
+    if (!key || !titleKey || !version || !extensionApi || !entryUrl || slots.length === 0)
+        return null;
+    const config = value.config && typeof value.config === "object" && !Array.isArray(value.config)
+        ? value.config
+        : undefined;
+    return { key, titleKey, version, extensionApi, entryUrl, slots, config };
+}
+function stringField(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}

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

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

package/dist/extension-resolution.test.js

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import { assembleInstalledExtensions } from "./extension-resolution.js";
+function slotRow(overrides = {}) {
+    return {
+        installationId: "apin_1",
+        appId: "app_1",
+        extensionKey: "slot:reports",
+        releaseId: "aprl_1",
+        defaultLocale: "en",
+        supportedLocales: ["en", "pt"],
+        descriptor: {
+            key: "reports",
+            titleKey: "reports.title",
+            version: "1.0.0",
+            extensionApi: "^1",
+            entryUrl: "https://app.example.com/reports",
+            slots: ["dashboard.header"],
+        },
+        ...overrides,
+    };
+}
+function pageRow(overrides = {}) {
+    return {
+        installationId: "apin_1",
+        appId: "app_1",
+        extensionKey: "page:settings",
+        releaseId: "aprl_1",
+        defaultLocale: "en",
+        supportedLocales: ["en", "pt"],
+        descriptor: {
+            key: "settings",
+            titleKey: "settings.title",
+            path: "/settings",
+            entryUrl: "https://app.example.com/settings",
+        },
+        ...overrides,
+    };
+}
+const localizations = new Map([
+    [
+        "aprl_1",
+        [
+            { locale: "en", surface: "extension", messageKey: "reports.title", text: "Reports" },
+            { locale: "pt", surface: "extension", messageKey: "reports.title", text: "Relatórios" },
+            { locale: "en", surface: "navigation", messageKey: "settings.title", text: "Settings" },
+            { locale: "en", surface: "extension", messageKey: "settings.title", text: "App Settings" },
+        ],
+    ],
+]);
+describe("assembleInstalledExtensions", () => {
+    it("resolves slot descriptors with host labels and locale/direction", () => {
+        const result = assembleInstalledExtensions([slotRow()], localizations, { activeLocale: "pt" });
+        expect(result.slots).toHaveLength(1);
+        const slot = result.slots[0];
+        expect(slot?.descriptor.key).toBe("apin_1:reports");
+        expect(slot?.descriptor.displayName).toBe("Relatórios");
+        expect(slot?.descriptor.slots).toEqual(["dashboard.header"]);
+        expect(slot?.appLocale).toBe("pt");
+        expect(slot?.direction).toBe("ltr");
+    });
+    it("resolves full-page descriptors with title and nav label", () => {
+        const result = assembleInstalledExtensions([pageRow()], localizations, { activeLocale: "en" });
+        expect(result.pages).toHaveLength(1);
+        const page = result.pages[0];
+        expect(page?.key).toBe("apin_1:settings");
+        expect(page?.path).toBe("/settings");
+        expect(page?.title).toBe("App Settings");
+        expect(page?.navLabel).toBe("Settings");
+    });
+    it("filters out extensionApi-incompatible slot extensions", () => {
+        const incompatible = slotRow({
+            descriptor: {
+                key: "legacy",
+                titleKey: "reports.title",
+                version: "1.0.0",
+                extensionApi: "^0.9",
+                entryUrl: "https://app.example.com/legacy",
+                slots: ["dashboard.header"],
+            },
+        });
+        const result = assembleInstalledExtensions([incompatible], localizations, {
+            activeLocale: "en",
+            extensionApiVersion: "1.1.0",
+        });
+        expect(result.slots).toHaveLength(0);
+    });
+    it("falls back to the descriptor key when no host label exists", () => {
+        const result = assembleInstalledExtensions([slotRow({ releaseId: "aprl_none" })], new Map(), {
+            activeLocale: "en",
+        });
+        expect(result.slots[0]?.descriptor.displayName).toBe("reports");
+    });
+    it("falls back to the default locale for an unsupported active locale", () => {
+        const result = assembleInstalledExtensions([slotRow()], localizations, { activeLocale: "de" });
+        expect(result.slots[0]?.appLocale).toBe("en");
+        expect(result.slots[0]?.descriptor.displayName).toBe("Reports");
+    });
+    it("skips malformed descriptors (fail-soft)", () => {
+        const malformed = slotRow({ descriptor: { key: "broken" } });
+        const result = assembleInstalledExtensions([malformed], localizations, { activeLocale: "en" });
+        expect(result.slots).toHaveLength(0);
+        expect(result.pages).toHaveLength(0);
+    });
+    it("gives each installation a unique descriptor key", () => {
+        const result = assembleInstalledExtensions([slotRow(), slotRow({ installationId: "apin_2" })], localizations, { activeLocale: "en" });
+        expect(result.slots.map((slot) => slot.descriptor.key)).toEqual([
+            "apin_1:reports",
+            "apin_2:reports",
+        ]);
+    });
+});

package/dist/index.d.ts

@@ -1,13 +1,20 @@
 export * from "./access-boundary.js";
+export * from "./app-api-contracts.js";
+export * from "./app-api-routes.js";
+export * from "./app-api-service.js";
 export * from "./compiler.js";
 export * from "./consent.js";
 export * from "./contracts.js";
+export * from "./extension-resolution.js";
 export * from "./ingestion.js";
 export * from "./installation-service.js";
+export * from "./locale-resolution.js";
 export * from "./oauth-crypto.js";
 export * from "./oauth-service.js";
 export { createAppsAdminRoutes } from "./routes.js";
-export { appAccessCredentialStatusEnum, appAccessCredentials, appAccessTokenModeEnum, appAuditEventKindEnum, appAuditEvents, appCredentialKindEnum, appCredentials, appDistributionEnum, appExtensionInstallations, appGrantStatusEnum, appGrants, appInstallationRegistrationStatusEnum, appInstallationSettings, appInstallationStatusEnum, appInstallations, appInstallationUpdatePolicyEnum, appLifecycleStateEnum, appOAuthAuthorizationCodes, appOAuthRefreshTokens, appRedirectUris, appReleaseArtifactStateEnum, appReleaseArtifacts, appReleaseLocalizations, appReleaseStateEnum, appReleases, appSecretReferences, apps, appWebhookSubscriptionStatusEnum, appWebhookSubscriptions, } from "./schema.js";
+export { appAccessCredentialStatusEnum, appAccessCredentials, appAccessTokenModeEnum, appAuditEventKindEnum, appAuditEvents, appCredentialKindEnum, appCredentials, appDistributionEnum, appExtensionInstallations, appGrantStatusEnum, appGrants, appInstallationRegistrationStatusEnum, appInstallationSettings, appInstallationStatusEnum, appInstallations, appInstallationUpdatePolicyEnum, appLifecycleStateEnum, appOAuthAuthorizationCodes, appOAuthRefreshTokens, appRedirectUris, appReleaseArtifactStateEnum, appReleaseArtifacts, appReleaseLocalizations, appReleaseStateEnum, appReleases, appSecretReferences, appSessionTokens, apps, appWebhookSubscriptionStatusEnum, appWebhookSubscriptions, } from "./schema.js";
 export { createAppsService } from "./service.js";
+export * from "./session-token.js";
+export * from "./session-token-service.js";
 export type { AppWebhookDeliveryOptions } from "./webhook-delivery.js";
 export { createAppWebhookDeliveryStore, createAppWebhookEventQueue, enqueueAppWebhookEvent, listAppWebhookHealth, replayAppWebhookDelivery, } from "./webhook-delivery.js";

package/dist/index.js

@@ -1,12 +1,19 @@
 export * from "./access-boundary.js";
+export * from "./app-api-contracts.js";
+export * from "./app-api-routes.js";
+export * from "./app-api-service.js";
 export * from "./compiler.js";
 export * from "./consent.js";
 export * from "./contracts.js";
+export * from "./extension-resolution.js";
 export * from "./ingestion.js";
 export * from "./installation-service.js";
+export * from "./locale-resolution.js";
 export * from "./oauth-crypto.js";
 export * from "./oauth-service.js";
 export { createAppsAdminRoutes } from "./routes.js";
-export { appAccessCredentialStatusEnum, appAccessCredentials, appAccessTokenModeEnum, appAuditEventKindEnum, appAuditEvents, appCredentialKindEnum, appCredentials, appDistributionEnum, appExtensionInstallations, appGrantStatusEnum, appGrants, appInstallationRegistrationStatusEnum, appInstallationSettings, appInstallationStatusEnum, appInstallations, appInstallationUpdatePolicyEnum, appLifecycleStateEnum, appOAuthAuthorizationCodes, appOAuthRefreshTokens, appRedirectUris, appReleaseArtifactStateEnum, appReleaseArtifacts, appReleaseLocalizations, appReleaseStateEnum, appReleases, appSecretReferences, apps, appWebhookSubscriptionStatusEnum, appWebhookSubscriptions, } from "./schema.js";
+export { appAccessCredentialStatusEnum, appAccessCredentials, appAccessTokenModeEnum, appAuditEventKindEnum, appAuditEvents, appCredentialKindEnum, appCredentials, appDistributionEnum, appExtensionInstallations, appGrantStatusEnum, appGrants, appInstallationRegistrationStatusEnum, appInstallationSettings, appInstallationStatusEnum, appInstallations, appInstallationUpdatePolicyEnum, appLifecycleStateEnum, appOAuthAuthorizationCodes, appOAuthRefreshTokens, appRedirectUris, appReleaseArtifactStateEnum, appReleaseArtifacts, appReleaseLocalizations, appReleaseStateEnum, appReleases, appSecretReferences, appSessionTokens, apps, appWebhookSubscriptionStatusEnum, appWebhookSubscriptions, } from "./schema.js";
 export { createAppsService } from "./service.js";
+export * from "./session-token.js";
+export * from "./session-token-service.js";
 export { createAppWebhookDeliveryStore, createAppWebhookEventQueue, enqueueAppWebhookEvent, listAppWebhookHealth, replayAppWebhookDelivery, } from "./webhook-delivery.js";

package/dist/installation-service.d.ts

@@ -100,7 +100,7 @@ export declare function createAppInstallationService(options?: AppInstallationSe
             uninstalledAt: Date | null;
             purgedAt: Date | null;
         };
-        outcome: "created" | "reinstalled";
+        outcome: "reinstalled" | "created";
     }>;
     upgrade: (db: PostgresJsDatabase, input: UpgradeAppInput) => Promise<{
         installation: {

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

@@ -12,6 +12,15 @@ 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;
+    };
 }
 export declare function createAppsAdminRoutes(options?: AppsAdminRouteOptions): Hono<Env, import("hono/types").BlankSchema, "/">;
 export {};

package/dist/routes.js

@@ -1,9 +1,10 @@
-import { parseJsonBody, parseQuery, RequestValidationError } from "@voyant-travel/hono";
+import { parseJsonBody, parseQuery, RequestValidationError, requireUserId, } from "@voyant-travel/hono";
 import { Hono } from "hono";
 import { z } from "zod";
-import { appCredentialRevocationSchema, appListQuerySchema, appOAuthAuthorizeQuerySchema, appOAuthTokenSchema, appWebhookReplaySchema, createCustomAppRegistrationSchema, releaseManifestFetchSchema, releaseManifestUploadSchema, } from "./contracts.js";
+import { appCredentialRevocationSchema, appListQuerySchema, appOAuthAuthorizeQuerySchema, appOAuthTokenSchema, appSessionTokenExchangeSchema, appSessionTokenIssueSchema, appWebhookReplaySchema, createCustomAppRegistrationSchema, releaseManifestFetchSchema, releaseManifestUploadSchema, } from "./contracts.js";
 import { createAppOAuthService } from "./oauth-service.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) });
@@ -11,6 +12,14 @@ export function createAppsAdminRoutes(options = {}) {
     const routes = new Hono();
     const service = createAppsService(options);
     const oauth = options.oauth ? createAppOAuthService(options.oauth) : null;
+    const sessionTokens = oauth && options.oauth && options.sessionToken
+        ? createAppSessionTokenService({
+            secret: options.sessionToken.secret,
+            ttlSeconds: options.sessionToken.ttlSeconds,
+            deploymentId: options.oauth.deploymentId,
+            oauth,
+        })
+        : null;
     routes.get("/", async (c) => {
         const query = parseQuery(c, appListQuerySchema);
         return c.json(await service.list(c.get("db"), query), 200);
@@ -81,6 +90,38 @@ export function createAppsAdminRoutes(options = {}) {
         const result = await oauth.revokeInstallationCredentials(c.get("db"), body.installationId, body.actorId);
         return c.json(result, 200);
     });
+    // 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) => {
+        if (!sessionTokens)
+            return c.json({ error: "App session tokens are not configured" }, 501);
+        const { installationId } = parseInstallationParams(c.req.param());
+        const viewerId = requireUserId(c);
+        const body = await parseJsonBody(c, appSessionTokenIssueSchema);
+        const issued = await sessionTokens.issue(c.get("db"), {
+            installationId,
+            viewerId,
+            entity: body.entity ?? null,
+            slot: body.slot ?? null,
+        });
+        return c.json({ data: issued }, 201);
+    });
+    // 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) => {
+        if (!sessionTokens)
+            return c.json({ error: "App session tokens are not configured" }, 501);
+        const body = await parseJsonBody(c, appSessionTokenExchangeSchema);
+        const token = await sessionTokens.exchange(c.get("db"), {
+            token: body.session_token,
+            clientId: body.client_id,
+            clientSecret: body.client_secret,
+            viewerScopes: body.viewer_scopes,
+            contextualScopes: body.contextual_scopes,
+        });
+        return c.json(token, 200);
+    });
     routes.get("/:appId", async (c) => {
         const { appId } = parseParams(c.req.param());
         const app = await service.get(c.get("db"), appId);