@voyant-travel/apps 0.1.0 → 0.3.0

package/dist/app-api-service.js

@@ -1,231 +0,0 @@
-import { createAppCustomFieldDefinitionOwner, createCustomFieldsService, } from "@voyant-travel/custom-fields";
-import { ApiHttpError } from "@voyant-travel/hono";
-import { and, asc, eq, sql } from "drizzle-orm";
-import { assertActiveAppInstallationAccess } from "./access-boundary.js";
-import { APP_API_VERSION } from "./app-api-contracts.js";
-import { appAuditEvents, appGrants, appReleases, appWebhookSubscriptions } from "./schema.js";
-const DEFAULT_RATE_LIMIT = { installationLimit: 120, appLimit: 600, windowMs: 60_000 };
-const REMOTE_APP_NAMESPACE = /^\$app(?::[a-z][a-z0-9-]*)?$/;
-const PHYSICAL_APP_NAMESPACE = /^app--/;
-const buckets = new Map();
-export function createAppApiService(options = {}) {
-    const now = () => options.now?.() ?? new Date();
-    const customFields = options.customFieldTargets &&
-        createCustomFieldsService(options.customFieldTargets, options.customFieldValueLifecycles ?? [], options.customFieldValueOperations ?? []);
-    async function introspect(db, context) {
-        const access = await requireAccess(db, context, ["app-installation:read"]);
-        const grants = await db
-            .select({
-            scope: appGrants.scope,
-            status: appGrants.status,
-            optional: appGrants.optional,
-        })
-            .from(appGrants)
-            .where(eq(appGrants.installationId, context.installationId))
-            .orderBy(appGrants.scope);
-        return {
-            data: {
-                installation: {
-                    id: access.installation.id,
-                    appId: access.installation.appId,
-                    status: access.installation.status,
-                    namespace: access.installation.namespace,
-                    deploymentId: access.installation.deploymentId,
-                },
-                release: {
-                    id: access.release.id,
-                    version: access.release.releaseVersion,
-                    apiCompatibility: access.release.apiCompatibility,
-                },
-                grants,
-            },
-        };
-    }
-    async function listEntities(db, context, entity, query) {
-        await requireAccess(db, context, [`${entity}:read`]);
-        const reader = options.entityReaders?.[entity];
-        if (!reader)
-            throw notSupported(`Entity "${entity}" is not supported by the App API.`);
-        return { data: await reader.list(db, query) };
-    }
-    async function listFinanceDocuments(db, context, query) {
-        await requireAccess(db, context, ["finance-documents:read"]);
-        if (!options.finance)
-            throw notSupported("Finance App API runtime is not configured.");
-        return { data: await options.finance.listDocuments(db, query) };
-    }
-    async function executeFinanceAction(db, context, input) {
-        await requireAccess(db, context, [`finance-actions:${input.action}`]);
-        if (!options.finance)
-            throw notSupported("Finance App API runtime is not configured.");
-        if (!input.approvalId) {
-            throw new ApiHttpError("Finance action requires action-ledger approval.", {
-                status: 403,
-                code: "app_api_finance_approval_required",
-            });
-        }
-        return { data: await options.finance.executeAction(db, input) };
-    }
-    async function listCustomFieldDefinitions(db, context, query) {
-        const access = await requireAccess(db, context, ["custom-field-definitions:read"]);
-        return customFieldsRequired().listForOwner(db, owner(access), query);
-    }
-    async function createCustomFieldDefinition(db, context, namespace, input) {
-        assertAppNamespaceAlias(namespace);
-        const access = await requireAccess(db, context, ["custom-field-definitions:write"]);
-        return { data: await customFieldsRequired().createForOwner(db, owner(access), input) };
-    }
-    async function updateCustomFieldDefinition(db, context, id, namespace, input) {
-        assertAppNamespaceAlias(namespace);
-        const access = await requireAccess(db, context, ["custom-field-definitions:write"]);
-        const data = await customFieldsRequired().updateForOwner(db, owner(access), id, input);
-        if (!data)
-            throw notFound("Custom-field definition not found.");
-        return { data };
-    }
-    async function listCustomFieldValues(db, context, query) {
-        await requireAccess(db, context, [`custom-field-values:${query.entityType ?? "read"}`]);
-        const access = await requireAccess(db, context, ["custom-field-values:read"]);
-        return customFieldsRequired().values.listForOwner(db, owner(access), query);
-    }
-    async function upsertCustomFieldValue(db, context, definitionId, input) {
-        await requireAccess(db, context, [
-            "custom-field-values:write",
-            `custom-field-values:${input.entityType}`,
-        ]);
-        const access = await requireAccess(db, context, []);
-        return {
-            data: await customFieldsRequired().values.upsertForOwner(db, owner(access), definitionId, input),
-        };
-    }
-    async function listWebhookHealth(db, context) {
-        await requireAccess(db, context, ["webhooks:read"]);
-        const data = await db
-            .select()
-            .from(appWebhookSubscriptions)
-            .where(eq(appWebhookSubscriptions.installationId, context.installationId))
-            .orderBy(asc(appWebhookSubscriptions.eventType));
-        return { data };
-    }
-    async function listAuditHistory(db, context, query) {
-        await requireAccess(db, context, ["app-audit:read"]);
-        const where = and(eq(appAuditEvents.appId, context.appId), eq(appAuditEvents.installationId, context.installationId));
-        const [data, count] = await Promise.all([
-            db.select().from(appAuditEvents).where(where).limit(query.limit).offset(query.offset),
-            db.select({ count: sql `count(*)::int` }).from(appAuditEvents).where(where),
-        ]);
-        return { data, total: count[0]?.count ?? 0, limit: query.limit, offset: query.offset };
-    }
-    return {
-        introspect,
-        listEntities,
-        listFinanceDocuments,
-        executeFinanceAction,
-        listCustomFieldDefinitions,
-        createCustomFieldDefinition,
-        updateCustomFieldDefinition,
-        listCustomFieldValues,
-        upsertCustomFieldValue,
-        listWebhookHealth,
-        listAuditHistory,
-        requireAccess,
-        enforceRateLimit,
-    };
-    async function requireAccess(db, context, requiredScopes) {
-        enforceRateLimit(context);
-        const installation = await assertActiveAppInstallationAccess(db, {
-            installationId: context.installationId,
-            requiredScopes,
-        });
-        if (installation.appId !== context.appId || installation.releaseId !== context.releaseId) {
-            throw new ApiHttpError("App token does not match the active installation.", {
-                status: 403,
-                code: "app_api_token_installation_mismatch",
-            });
-        }
-        const [release] = await db
-            .select()
-            .from(appReleases)
-            .where(eq(appReleases.id, installation.releaseId))
-            .limit(1);
-        if (!release)
-            throw notFound("Installed app release not found.");
-        assertCompatibleVersion(context.apiVersion ?? APP_API_VERSION, release.apiCompatibility);
-        return { installation, release };
-    }
-    function enforceRateLimit(context) {
-        const policy = options.rateLimit ?? DEFAULT_RATE_LIMIT;
-        hit(`installation:${context.installationId}`, policy.installationLimit, policy.windowMs);
-        hit(`app:${context.appId}`, policy.appLimit, policy.windowMs);
-    }
-    function hit(key, limit, windowMs) {
-        const timestamp = now().getTime();
-        const bucket = buckets.get(key);
-        if (!bucket || bucket.resetAt <= timestamp) {
-            buckets.set(key, { count: 1, resetAt: timestamp + windowMs });
-            return;
-        }
-        if (bucket.count >= limit) {
-            throw new ApiHttpError("App API rate limit exceeded.", {
-                status: 429,
-                code: "app_api_rate_limited",
-                details: { key, resetAt: new Date(bucket.resetAt).toISOString() },
-            });
-        }
-        bucket.count += 1;
-    }
-    function owner(access) {
-        return createAppCustomFieldDefinitionOwner({
-            appId: access.installation.appId,
-            namespace: access.installation.namespace,
-        });
-    }
-    function customFieldsRequired() {
-        if (!customFields)
-            throw notSupported("Custom fields App API runtime is not configured.");
-        return customFields;
-    }
-}
-export function assertAppNamespaceAlias(namespace) {
-    if (!namespace || namespace === "$app")
-        return;
-    if (PHYSICAL_APP_NAMESPACE.test(namespace) || !REMOTE_APP_NAMESPACE.test(namespace)) {
-        throw new ApiHttpError("App APIs accept only the server-resolved $app namespace alias.", {
-            status: 400,
-            code: "app_api_invalid_custom_field_namespace",
-        });
-    }
-}
-export function assertCompatibleVersion(requested, range) {
-    if (requested < range.min || requested > range.max) {
-        throw new ApiHttpError("Requested App API version is outside the installed release range.", {
-            status: 426,
-            code: "app_api_version_out_of_range",
-            details: { requested, supported: range },
-        });
-    }
-}
-export async function withAppApiDeadline(promise, timeoutMs = 5_000) {
-    let timeout;
-    try {
-        return await Promise.race([
-            promise,
-            new Promise((_, reject) => {
-                timeout = setTimeout(() => reject(new ApiHttpError("App API request deadline exceeded.", {
-                    status: 504,
-                    code: "app_api_deadline_exceeded",
-                })), timeoutMs);
-            }),
-        ]);
-    }
-    finally {
-        if (timeout)
-            clearTimeout(timeout);
-    }
-}
-function notSupported(message) {
-    return new ApiHttpError(message, { status: 501, code: "app_api_not_configured" });
-}
-function notFound(message) {
-    return new ApiHttpError(message, { status: 404, code: "not_found" });
-}

package/dist/app-api-service.test.d.ts

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

package/dist/app-api-service.test.js

@@ -1,105 +0,0 @@
-import { ApiHttpError } from "@voyant-travel/hono";
-import { describe, expect, it, vi } from "vitest";
-import { assertAppNamespaceAlias, assertCompatibleVersion, createAppApiService, } from "./app-api-service.js";
-import { appGrants, appInstallations, appReleases } from "./schema.js";
-function postgresStub(implementation) {
-    const db = Object.create(null);
-    Object.assign(db, implementation);
-    return db;
-}
-function createAccessDb(options) {
-    const installation = {
-        id: "inst_1",
-        appId: "app_1",
-        deploymentId: "dep_1",
-        releaseId: "rel_1",
-        status: options.status ?? "active",
-        namespace: "app--one",
-    };
-    const release = {
-        id: "rel_1",
-        appId: "app_1",
-        releaseVersion: "1.0.0",
-        apiCompatibility: options.releaseRange ?? { min: "2026-07-01", max: "2026-12-31" },
-    };
-    return postgresStub({
-        select: () => ({
-            from: (table) => ({
-                where: () => {
-                    const rows = () => {
-                        if (table === appInstallations)
-                            return [installation];
-                        if (table === appReleases)
-                            return [release];
-                        if (table === appGrants)
-                            return (options.scopes ?? []).map((scope) => ({ scope }));
-                        return [];
-                    };
-                    return {
-                        // biome-ignore lint/suspicious/noThenProperty: test stub models Drizzle's awaitable query builder -- owner: apps.
-                        then: (resolve) => Promise.resolve(rows()).then(resolve),
-                        orderBy: async () => rows(),
-                        limit: async () => rows(),
-                    };
-                },
-            }),
-        }),
-    });
-}
-const context = {
-    appId: "app_1",
-    installationId: "inst_1",
-    releaseId: "rel_1",
-    tokenMode: "offline",
-    scopes: [],
-    apiVersion: "2026-07-01",
-};
-describe("App API service boundary", () => {
-    it("rejects direct service calls when the installation is inactive", async () => {
-        const service = createAppApiService();
-        await expect(service.requireAccess(createAccessDb({ status: "paused", scopes: ["app-installation:read"] }), context, ["app-installation:read"])).rejects.toMatchObject({ status: 403, code: "app_installation_not_active" });
-    });
-    it("rejects direct service calls when required scopes are not granted", async () => {
-        const service = createAppApiService();
-        await expect(service.requireAccess(createAccessDb({ scopes: [] }), context, ["app-installation:read"])).rejects.toMatchObject({ status: 403, code: "app_installation_scope_missing" });
-    });
-    it("fails closed when the requested API version is outside the installed release range", async () => {
-        const service = createAppApiService();
-        await expect(service.requireAccess(createAccessDb({
-            scopes: ["app-installation:read"],
-            releaseRange: { min: "2026-08-01", max: "2026-12-31" },
-        }), context, ["app-installation:read"])).rejects.toMatchObject({ status: 426, code: "app_api_version_out_of_range" });
-    });
-    it("requires action-ledger approval for finance actions even when OAuth scope is granted", async () => {
-        const executeAction = vi.fn();
-        const service = createAppApiService({
-            finance: { listDocuments: vi.fn(), executeAction },
-        });
-        await expect(service.executeFinanceAction(createAccessDb({ scopes: ["finance-actions:issue"] }), context, {
-            action: "issue",
-            idempotencyKey: "idem_1",
-            payload: {},
-        })).rejects.toMatchObject({ status: 403, code: "app_api_finance_approval_required" });
-        expect(executeAction).not.toHaveBeenCalled();
-    });
-    it("isolates rate limits per installation", async () => {
-        const service = createAppApiService({
-            rateLimit: { installationLimit: 1, appLimit: 10, windowMs: 60_000 },
-        });
-        const rateContext = { ...context, appId: "rate_app", installationId: "rate_inst_1" };
-        service.enforceRateLimit(rateContext);
-        expect(() => service.enforceRateLimit(rateContext)).toThrow(ApiHttpError);
-        expect(() => service.enforceRateLimit({ ...rateContext, installationId: "rate_inst_2" })).not.toThrow();
-    });
-    it("accepts only the $app custom-field namespace alias from request data", () => {
-        expect(() => assertAppNamespaceAlias(undefined)).not.toThrow();
-        expect(() => assertAppNamespaceAlias("$app")).not.toThrow();
-        expect(() => assertAppNamespaceAlias("$app:sync")).not.toThrow();
-        expect(() => assertAppNamespaceAlias("app--foreign")).toThrow(ApiHttpError);
-        expect(() => assertAppNamespaceAlias("custom")).toThrow(ApiHttpError);
-    });
-    it("compares App API compatibility ranges inclusively", () => {
-        expect(() => assertCompatibleVersion("2026-07-01", { min: "2026-07-01", max: "2026-12-31" })).not.toThrow();
-        expect(() => assertCompatibleVersion("2027-01-01", { min: "2026-07-01", max: "2026-12-31" })).toThrow(ApiHttpError);
-    });
-});