@voyant-travel/apps 0.1.0

package/dist/service.test.js

@@ -0,0 +1,178 @@
+import { describe, expect, it, vi } from "vitest";
+import { appRedirectUris, appReleaseArtifacts, appReleaseLocalizations, appReleases, apps, } from "./schema.js";
+import { createAppsService } from "./service.js";
+import { validManifest } from "./test-fixtures.js";
+function postgresStub(implementation) {
+    const db = Object.create(null);
+    Object.assign(db, implementation);
+    if (!("transaction" in db)) {
+        Object.assign(db, {
+            transaction: async (callback) => callback(db),
+        });
+    }
+    return db;
+}
+function createRegistryDb() {
+    const rows = {
+        apps: [],
+        releases: [],
+        artifacts: [],
+        localizations: [],
+        redirectUris: [],
+    };
+    let appSequence = 0;
+    let releaseSequence = 0;
+    const db = postgresStub({
+        insert: (table) => ({
+            values: (value) => {
+                const values = Array.isArray(value) ? value : [value];
+                const insertRows = () => {
+                    if (table === apps) {
+                        const row = { id: `app_${++appSequence}`, ...values[0] };
+                        if (rows.apps.some((existing) => existing.platformNamespace === row.platformNamespace)) {
+                            return [];
+                        }
+                        rows.apps.push(row);
+                        return [row];
+                    }
+                    if (table === appReleases) {
+                        const row = { id: `release_${++releaseSequence}`, ...values[0] };
+                        const duplicate = rows.releases.find((existing) => existing.appId === row.appId &&
+                            existing.manifestDigest === row.manifestDigest);
+                        if (duplicate)
+                            return [];
+                        rows.releases.push(row);
+                        return [row];
+                    }
+                    if (table === appReleaseArtifacts)
+                        rows.artifacts.push(...values);
+                    if (table === appReleaseLocalizations)
+                        rows.localizations.push(...values);
+                    if (table === appRedirectUris)
+                        rows.redirectUris.push(...values);
+                    return values;
+                };
+                return {
+                    onConflictDoNothing: () => ({ returning: async () => insertRows() }),
+                    returning: async () => insertRows(),
+                };
+            },
+        }),
+        select: () => ({
+            from: (table) => ({
+                where: () => ({
+                    for: () => ({
+                        limit: async () => (table === apps ? rows.apps.slice(0, 1) : []),
+                    }),
+                    limit: async () => (table === appReleases ? rows.releases.slice(0, 1) : []),
+                }),
+            }),
+        }),
+    });
+    return { db, rows };
+}
+describe("apps service", () => {
+    it("assigns immutable platform app ids and reserved namespaces independent of names", async () => {
+        const { db, rows } = createRegistryDb();
+        const service = createAppsService();
+        const first = await service.createCustomApp(db, {
+            ownerId: "owner_1",
+            displayName: "Acme Sync",
+            slug: "acme-sync",
+            redirectUris: [],
+            createdBy: "user_1",
+        });
+        const second = await service.createCustomApp(db, {
+            ownerId: "owner_1",
+            displayName: "Acme Sync",
+            slug: "acme-sync",
+            redirectUris: [],
+            createdBy: "user_1",
+        });
+        expect(first.id).not.toBe(second.id);
+        expect(first.platformNamespace).toMatch(/^app--[a-f0-9]+$/);
+        expect(second.platformNamespace).toMatch(/^app--[a-f0-9]+$/);
+        expect(first.platformNamespace).not.toBe(second.platformNamespace);
+        expect(rows.apps).toHaveLength(2);
+    });
+    it("creates immutable releases and treats the same digest as idempotent", async () => {
+        const { db, rows } = createRegistryDb();
+        const service = createAppsService();
+        const app = await service.createCustomApp(db, {
+            ownerId: "owner_1",
+            displayName: "Acme Sync",
+            slug: "acme-sync",
+            redirectUris: [],
+            createdBy: "user_1",
+        });
+        const first = await service.releaseFromUpload(db, app.id, {
+            manifest: validManifest,
+            createdBy: "user_1",
+            provenance: { source: "test" },
+        });
+        const second = await service.releaseFromUpload(db, app.id, {
+            manifest: validManifest,
+            createdBy: "user_1",
+            provenance: { source: "test" },
+        });
+        expect(first.created).toBe(true);
+        expect(second.created).toBe(false);
+        expect(first.release.id).toBe(second.release.id);
+        expect(rows.releases).toHaveLength(1);
+        expect(rows.artifacts).toHaveLength(1);
+        expect(rows.localizations.length).toBeGreaterThan(0);
+        expect(Object.keys(service)).not.toContain("updateRelease");
+    });
+    it("rejects reusing a release version with different content", async () => {
+        const { db, rows } = createRegistryDb();
+        const service = createAppsService();
+        const app = await service.createCustomApp(db, {
+            ownerId: "owner_1",
+            displayName: "Acme Sync",
+            slug: "acme-sync",
+            redirectUris: [],
+            createdBy: "user_1",
+        });
+        await service.releaseFromUpload(db, app.id, {
+            manifest: validManifest,
+            createdBy: "user_1",
+            provenance: { source: "test" },
+        });
+        await expect(service.releaseFromUpload(db, app.id, {
+            manifest: {
+                ...validManifest,
+                scopes: { requested: ["bookings:read", "invoices:read"], optional: [] },
+            },
+            createdBy: "user_1",
+            provenance: { source: "test" },
+        })).rejects.toMatchObject({ status: 409 });
+        expect(rows.releases).toHaveLength(1);
+    });
+    it("fetch ingestion stores only the validated snapshot", async () => {
+        const { db, rows } = createRegistryDb();
+        const fetcher = vi.fn(async () => new Response(JSON.stringify(validManifest), {
+            headers: { "content-type": "application/json" },
+        }));
+        const service = createAppsService({
+            fetch: fetcher,
+            resolveHost: async () => ["203.0.113.10"],
+        });
+        const app = await service.createCustomApp(db, {
+            ownerId: "owner_1",
+            displayName: "Acme Sync",
+            slug: "acme-sync",
+            redirectUris: [],
+            createdBy: "user_1",
+        });
+        await service.releaseFromFetch(db, app.id, {
+            manifestUrl: "https://app.example.com/manifest.json",
+            createdBy: "user_1",
+        });
+        expect(rows.releases[0]).toMatchObject({
+            appId: app.id,
+            manifestSchemaVersion: "voyant.app-manifest.v1",
+        });
+        expect(rows.releases[0]?.manifestSnapshot).not.toHaveProperty("scripts");
+        expect(rows.artifacts[0]?.provenance).toMatchObject({ source: "https-manifest" });
+    });
+});

package/dist/test-fixtures.d.ts

@@ -0,0 +1,80 @@
+export declare const validManifest: {
+    schemaVersion: "voyant.app-manifest.v1";
+    releaseVersion: string;
+    apiCompatibility: {
+        min: string;
+        max: string;
+    };
+    scopes: {
+        requested: string[];
+        optional: string[];
+    };
+    admin: {
+        pages: {
+            key: string;
+            titleKey: string;
+            path: string;
+            entryUrl: string;
+        }[];
+        slotExtensions: {
+            key: string;
+            titleKey: string;
+            version: string;
+            extensionApi: string;
+            entryUrl: string;
+            slots: "booking.details.header"[];
+        }[];
+    };
+    webhooks: {
+        eventType: string;
+        eventVersion: string;
+        endpointUrl: string;
+    }[];
+    customFields: {
+        entityType: string;
+        key: string;
+        label: string;
+        fieldType: "text";
+        isRequired: false;
+        isSearchable: false;
+        isExportable: true;
+        isInvoiceable: false;
+        options: null;
+        dataClassification: "internal";
+    }[];
+    locales: {
+        default: string;
+        supported: string[];
+        host: {
+            "en-US": {
+                name: string;
+                summary: string;
+                navigation: {
+                    settings: string;
+                };
+                extensions: {
+                    "booking-panel": string;
+                };
+                setup: {};
+            };
+            "ro-RO": {
+                name: string;
+                summary: string;
+                navigation: {};
+                extensions: {};
+                setup: {};
+            };
+        };
+    };
+    urls: {
+        health: string;
+        launch: string;
+        privacy: string;
+        support: string;
+    };
+    data: {
+        classifications: "internal"[];
+        retention: string;
+        storesSecrets: false;
+    };
+};

package/dist/test-fixtures.js

@@ -0,0 +1,78 @@
+export const validManifest = {
+    schemaVersion: "voyant.app-manifest.v1",
+    releaseVersion: "1.0.0",
+    apiCompatibility: { min: "2026-07-01", max: "2026-12-31" },
+    scopes: { requested: ["bookings:read"], optional: ["invoices:read"] },
+    admin: {
+        pages: [
+            {
+                key: "settings",
+                titleKey: "settings.title",
+                path: "/settings",
+                entryUrl: "https://app.example.com/admin/settings",
+            },
+        ],
+        slotExtensions: [
+            {
+                key: "booking-panel",
+                titleKey: "booking.panel.title",
+                version: "1.0.0",
+                extensionApi: "^1",
+                entryUrl: "https://app.example.com/admin/booking-panel",
+                slots: ["booking.details.header"],
+            },
+        ],
+    },
+    webhooks: [
+        {
+            eventType: "booking.created",
+            eventVersion: "1.0.0",
+            endpointUrl: "https://app.example.com/webhooks/voyant",
+        },
+    ],
+    customFields: [
+        {
+            entityType: "booking",
+            key: "external_id",
+            label: "External ID",
+            fieldType: "text",
+            isRequired: false,
+            isSearchable: false,
+            isExportable: true,
+            isInvoiceable: false,
+            options: null,
+            dataClassification: "internal",
+        },
+    ],
+    locales: {
+        default: "en-US",
+        supported: ["en-US", "ro-RO"],
+        host: {
+            "en-US": {
+                name: "Example App",
+                summary: "Synchronizes example records.",
+                navigation: { settings: "Example" },
+                extensions: { "booking-panel": "Example panel" },
+                setup: {},
+            },
+            "ro-RO": {
+                name: "Aplicatie Exemplu",
+                summary: "Sincronizeaza inregistrari exemplu.",
+                navigation: {},
+                extensions: {},
+                setup: {},
+            },
+        },
+    },
+    urls: {
+        health: "https://app.example.com/health",
+        launch: "https://app.example.com/launch",
+        privacy: "https://app.example.com/privacy",
+        support: "https://app.example.com/support",
+    },
+    data: {
+        classifications: ["internal"],
+        retention: "Retained until the operator removes the app-owned records.",
+        storesSecrets: false,
+    },
+};

package/dist/voyant.d.ts

@@ -0,0 +1,2 @@
+export declare const appsVoyantModule: import("@voyant-travel/core").VoyantGraphUnitManifest;
+export default appsVoyantModule;

package/dist/voyant.js

@@ -0,0 +1,115 @@
+import { defineModule } from "@voyant-travel/core/project";
+const appInstallationLifecyclePayloadSchema = {
+    type: "object",
+    additionalProperties: false,
+    required: ["appId", "installationId", "deploymentId"],
+    properties: {
+        appId: { type: "string" },
+        installationId: { type: "string" },
+        deploymentId: { type: "string" },
+    },
+};
+export const appsVoyantModule = defineModule({
+    id: "@voyant-travel/apps",
+    packageName: "@voyant-travel/apps",
+    localId: "apps",
+    api: [
+        {
+            id: "@voyant-travel/apps#api.admin",
+            surface: "admin",
+            mount: "apps",
+            resource: "apps",
+            transactional: true,
+            runtime: {
+                entry: "@voyant-travel/apps/api-runtime",
+                export: "createAppsApiModule",
+            },
+        },
+    ],
+    schema: [
+        {
+            id: "@voyant-travel/apps#schema",
+            source: "@voyant-travel/apps/schema",
+        },
+    ],
+    migrations: [
+        {
+            id: "@voyant-travel/apps#migrations",
+            source: "./migrations",
+        },
+    ],
+    events: [
+        {
+            id: "@voyant-travel/apps#event.installation-active",
+            eventType: "app.installation.active",
+            version: "1.0.0",
+            payloadSchema: appInstallationLifecyclePayloadSchema,
+            visibility: "internal",
+            audit: { sourceModule: "apps", category: "internal" },
+        },
+        {
+            id: "@voyant-travel/apps#event.installation-upgraded",
+            eventType: "app.installation.upgraded",
+            version: "1.0.0",
+            payloadSchema: appInstallationLifecyclePayloadSchema,
+            visibility: "internal",
+            audit: { sourceModule: "apps", category: "internal" },
+        },
+        {
+            id: "@voyant-travel/apps#event.installation-upgrade-pending",
+            eventType: "app.installation.upgrade_pending",
+            version: "1.0.0",
+            payloadSchema: appInstallationLifecyclePayloadSchema,
+            visibility: "internal",
+            audit: { sourceModule: "apps", category: "internal" },
+        },
+        {
+            id: "@voyant-travel/apps#event.installation-paused",
+            eventType: "app.installation.paused",
+            version: "1.0.0",
+            payloadSchema: appInstallationLifecyclePayloadSchema,
+            visibility: "internal",
+            audit: { sourceModule: "apps", category: "internal" },
+        },
+        {
+            id: "@voyant-travel/apps#event.installation-uninstalled",
+            eventType: "app.installation.uninstalled",
+            version: "1.0.0",
+            payloadSchema: appInstallationLifecyclePayloadSchema,
+            visibility: "internal",
+            audit: { sourceModule: "apps", category: "internal" },
+        },
+    ],
+    access: {
+        resources: [
+            {
+                id: "@voyant-travel/apps#access.apps",
+                resource: "apps",
+                label: "Apps",
+                description: "Administer app registrations and immutable app releases.",
+                actions: [
+                    {
+                        action: "read",
+                        label: "View apps",
+                        description: "View app registrations and releases.",
+                    },
+                    {
+                        action: "write",
+                        label: "Administer apps",
+                        description: "Create custom app registrations and immutable app releases.",
+                        sensitive: true,
+                    },
+                ],
+            },
+        ],
+    },
+    lifecycle: { uninstall: { default: "retain-data", purge: "not-supported" } },
+    meta: {
+        ownership: "package",
+        agentTools: {
+            posture: "not-applicable",
+            rationale: "The app registry is an authenticated admin API surface; this module does not expose agent Tools.",
+        },
+    },
+});
+export default appsVoyantModule;

package/dist/webhook-delivery.d.ts

@@ -0,0 +1,69 @@
+import type { EventEnvelope } from "@voyant-travel/core";
+import { type ExternalWebhookEventContract, type WebhookDeliveryStore, type WebhookEnqueueOutcome, type WebhookSigningKey } from "@voyant-travel/webhook-delivery";
+import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+export interface AppWebhookDeliveryOptions {
+    contracts: readonly ExternalWebhookEventContract[];
+    resolveSigningKey(input: {
+        appId: string;
+        installationId: string;
+    }): Promise<WebhookSigningKey>;
+    terminalFailureThreshold?: number;
+    now?: () => Date;
+}
+export declare function createAppWebhookDeliveryStore(db: PostgresJsDatabase, options: Omit<AppWebhookDeliveryOptions, "contracts">): WebhookDeliveryStore;
+export declare function createAppWebhookEventQueue(db: PostgresJsDatabase, options: AppWebhookDeliveryOptions): import("@voyant-travel/webhook-delivery").SelectedExternalWebhookQueue;
+export declare function enqueueAppWebhookEvent(db: PostgresJsDatabase, event: EventEnvelope, options: AppWebhookDeliveryOptions): Promise<WebhookEnqueueOutcome[]>;
+export declare function listAppWebhookHealth(db: PostgresJsDatabase, installationId: string): Promise<{
+    data: {
+        id: string;
+        installationId: string;
+        releaseId: string;
+        eventType: string;
+        eventVersion: string;
+        endpointUrl: string;
+        status: "active" | "inactive" | "failed";
+        externalSubscriptionId: string | null;
+        signingKeyId: string | null;
+        lastDeliveryAt: Date | null;
+        failureCount: number;
+        pausedAt: Date | null;
+        installedAt: Date;
+        deactivatedAt: Date | null;
+    }[];
+}>;
+export declare function replayAppWebhookDelivery(db: PostgresJsDatabase, input: {
+    deliveryId: string;
+    actorId: string;
+    signingKey: WebhookSigningKey;
+}): Promise<{
+    id: string;
+    sourceModule: string;
+    sourceEvent: string;
+    sourceEntityModule: string | null;
+    sourceEntityId: string | null;
+    subscriptionId: string | null;
+    targetUrl: string;
+    targetKind: string | null;
+    targetRef: string | null;
+    requestMethod: string;
+    requestHeaders: Record<string, string> | null;
+    requestBodyHash: string | null;
+    requestBodyExcerpt: string | null;
+    requestPayload: Record<string, unknown> | null;
+    deliveryContract: Record<string, unknown> | null;
+    responseStatus: number | null;
+    responseHeaders: Record<string, string> | null;
+    responseBodyExcerpt: string | null;
+    attemptNumber: number;
+    parentDeliveryId: string | null;
+    idempotencyKey: string | null;
+    status: "pending" | "failed" | "succeeded" | "in_flight" | "abandoned";
+    scheduledFor: Date | null;
+    startedAt: Date | null;
+    finishedAt: Date | null;
+    durationMs: number | null;
+    errorClass: "timeout" | "network" | "4xx" | "5xx" | "adapter_error" | "rate_limited" | null;
+    errorMessage: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+}>;