@arbium/enterprise-agent-connect-client 0.0.0-stage → 0.1.2-dev.cba5f68

package/lib/index.js

@@ -0,0 +1,235 @@
+import { chosenSteps } from "./steps.js";
+export * from "./steps.js";
+/** A refusal the admin should read (4xx with an `error`): bad input, a failed connection
+ *  check, a name in use. A 5xx or an answer without an `error` throws a plain Error. */
+export class AgentConnectError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/** The admin API (v1), server to server: the token must never reach a browser. */
+export function createClient(options) {
+    const base = `${options.baseUrl.replace(/\/+$/, "")}/agent-connect/admin/v1`;
+    async function send(method, path, body) {
+        return (options.fetch ?? globalThis.fetch)(`${base}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${options.token}`,
+                ...(body === undefined ? {} : { "content-type": "application/json" }),
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+            cache: "no-store",
+            signal: AbortSignal.timeout(options.timeoutMs ?? 45_000),
+        });
+    }
+    async function refusal(res, method, path) {
+        const data = await res.json().catch(() => null);
+        const message = data?.error;
+        if (res.status < 500 && typeof message === "string")
+            throw new AgentConnectError(message, res.status);
+        throw new Error(`agent-connect ${method} ${path} answered ${res.status}`);
+    }
+    async function call(method, path, body) {
+        const res = await send(method, path, body);
+        if (res.status === 204)
+            return undefined;
+        if (res.ok)
+            return (await res.json());
+        return refusal(res, method, path);
+    }
+    /** A row that may not exist yet: 404 is null, not an error. */
+    async function maybe(path) {
+        const res = await send("GET", path);
+        if (res.status === 404)
+            return null;
+        if (res.ok)
+            return (await res.json());
+        return refusal(res, "GET", path);
+    }
+    const seg = encodeURIComponent;
+    const org = (id) => `/orgs/${seg(id)}`;
+    const app = (o, a) => `${org(o)}/connections/${seg(a)}`;
+    const provider = (o, p) => `${org(o)}/providers/${seg(p)}`;
+    const agent = (o, id) => `${org(o)}/agents/${seg(id)}`;
+    const bot = (o, id) => `${agent(o, id)}/teams-bot`;
+    const client = {
+        organizations: {
+            list: () => call("GET", "/orgs"),
+            get: (id) => maybe(org(id)),
+            /** Makes the organization with this id if missing; `name` replaces the kept one. */
+            ensure: (id, name) => call("PUT", org(id), name === undefined ? {} : { name }),
+            create: (name) => call("POST", "/orgs", { name }),
+        },
+        branding: () => call("GET", "/branding"),
+        connectors: () => call("GET", "/connectors"),
+        providers: () => call("GET", "/providers"),
+        providerConnections: (o) => call("GET", `${org(o)}/providers`),
+        connectProvider: (o, p, body) => call("PUT", provider(o, p), body),
+        checkProvider: (o, p) => call("POST", `${provider(o, p)}/check`),
+        // `by`: the admin, recorded in the service's audit log with each change.
+        /** Before connecting, the certificate to upload; after, one to rotate to. */
+        newCertificate: (o, p, by) => call("POST", `${provider(o, p)}/certificate`, { by }),
+        /** Signs in with the new certificate and, if that works, switches to it. */
+        activateCertificate: (o, p, by) => call("POST", `${provider(o, p)}/certificate/activate`, {
+            by,
+        }),
+        /** Disconnects the provider and every app signing in through it. */
+        disconnectProvider: (o, p, by) => call("DELETE", provider(o, p), { by }),
+        /** Values an app's steps ask for, kept on the provider connection. */
+        setProviderSettings: (o, p, values, by) => call("PUT", `${provider(o, p)}/settings`, { values, by }),
+        connections: (o) => call("GET", `${org(o)}/connections`),
+        connect: (o, a, body) => call("PUT", app(o, a), body),
+        startConsent: (o, a, body) => call("POST", `${app(o, a)}/consent`, body),
+        /** `redirect`: the approval came back; the admin signs in to that organization next.
+         *  `provider`: the approval connected the provider; the app still needs its own settings. */
+        finishConsent: (o, a, body) => call("POST", `${app(o, a)}/consent/callback`, body),
+        setCeiling: (o, a, capabilities, by) => call("PATCH", app(o, a), { capabilities, by }),
+        /** Recorded: a failure marks the app as needing reconnecting, so it names the admin. */
+        check: (o, a, by) => call("POST", `${app(o, a)}/check`, { by }),
+        /** The same checks, read only: a failure here does not mark the app. */
+        peek: (o, a) => call("POST", `${app(o, a)}/check?record=false`),
+        /** The sites added to an app, the whole list at once. */
+        setSites: (o, a, sites, by) => call("PUT", `${app(o, a)}/sites`, { sites, by }),
+        /** Whether the app can open each added site, or just `site`. */
+        checkSites: (o, a, site) => call("POST", `${app(o, a)}/sites/check`, site === undefined ? {} : { site }),
+        /** Whether the app can reach one agent's own address (its mailbox) yet. */
+        agentAccess: (o, a, value, by) => call("POST", `${app(o, a)}/agent-access`, { value, by }),
+        disconnect: (o, a, by) => call("DELETE", app(o, a), { by }),
+        agents: (o) => call("GET", `${org(o)}/agents`),
+        createAgent: (o, body) => call("POST", `${org(o)}/agents`, body),
+        setAgentStatus: (o, id, status, by) => call("PATCH", agent(o, id), { status, by }),
+        newKey: (o, id, by) => call("POST", `${agent(o, id)}/key`, { by }),
+        deleteAgent: (o, id, by) => call("DELETE", agent(o, id), { by }),
+        setGrant: (o, id, a, capabilities, limits, by) => call("PUT", `${agent(o, id)}/grants/${seg(a)}`, { capabilities, limits, by }),
+        removeGrant: (o, id, a, by) => call("DELETE", `${agent(o, id)}/grants/${seg(a)}`, { by }),
+        /** Recent requests, newest first, of one key (`agent`), one app, or both. */
+        audit: (o, filter, limit = 50) => call("GET", `${org(o)}/audit?${new URLSearchParams({ limit: String(limit), ...filter })}`),
+        // Setup steps an admin marked done (they cannot be checked), shared by every admin.
+        confirmed: async (o) => (await call("GET", `${org(o)}/confirmed`)).map((c) => c.step),
+        setConfirmed: (o, step, on, by) => call(on ? "PUT" : "DELETE", `${org(o)}/confirmed/${seg(step)}`, { by }),
+        // ---- Teams: each agent's own bot ----
+        teamsBots: (o) => call("GET", `${org(o)}/teams/bots`),
+        createTeamsBot: (o, id, displayName, by) => call("POST", bot(o, id), { displayName, by }),
+        /** Proves the application ID the setup script printed by signing in as it. */
+        connectTeamsBot: (o, id, botAppId, by) => call("PUT", bot(o, id), { botAppId, by }),
+        checkTeamsBot: (o, id) => call("POST", `${bot(o, id)}/check`),
+        teamsTest: (o, id, conversationId, by) => call("POST", `${bot(o, id)}/test`, { conversationId, by }),
+        /** Forgets the bot. What Add to Teams made is deleted (`failed`: what could not be);
+         *  `removal` is the commands for the rest. */
+        removeTeamsBot: (o, id, by) => call("DELETE", bot(o, id), { by }),
+        newTeamsCertificate: (o, id, by) => call("POST", `${bot(o, id)}/certificate`, { by }),
+        activateTeamsCertificate: (o, id, by) => call("POST", `${bot(o, id)}/certificate/activate`, {
+            by,
+        }),
+        /** The Teams page's set-up-once steps, checked live. */
+        teamsSetupState: (o) => call("GET", `${org(o)}/teams/setup`),
+        /** Makes the agent's bot in the tenant, each part only if missing. */
+        addToTeams: (o, id, displayName, by) => call("POST", `${bot(o, id)}/add`, { displayName, by }),
+        startTeamsPublish: (o, id, redirectUri) => call("POST", `${bot(o, id)}/publish`, { redirectUri }),
+        finishTeamsPublish: (o, body) => call("POST", `${org(o)}/teams/publish/callback`, body),
+        teamsTargets: (o, id, kind, q) => call("GET", `${bot(o, id)}/targets?${new URLSearchParams({ kind, q })}`),
+        installTeamsBot: (o, id, kind, target, by) => call("POST", `${bot(o, id)}/install`, { kind, id: target, by }),
+        /** A file the service makes (the setup script, certificate or Teams app package), as is. */
+        teamsFile: async (o, id, file) => {
+            const path = `${bot(o, id)}/${file}`;
+            const res = await send("GET", path);
+            return res.ok ? res : refusal(res, "GET", path);
+        },
+        teamsTrigger: (o, id) => maybe(`${agent(o, id)}/teams-trigger`),
+        setTeamsTrigger: (o, id, body) => call("PUT", `${agent(o, id)}/teams-trigger`, body),
+        teamsRuns: (o, id, limit = 20) => call("GET", `${agent(o, id)}/teams-runs?limit=${limit}`),
+        // App events that start agents (docs/triggers.md). A webhook's secret is in the answer to
+        // subscribeEvents and rotateEventSecret only.
+        eventSubscriptions: (o) => call("GET", `${org(o)}/event-subscriptions`),
+        subscribeEvents: (o, body) => call("POST", `${org(o)}/event-subscriptions`, body),
+        rotateEventSecret: (o, id, by) => call("POST", `${org(o)}/event-subscriptions/${seg(id)}/secret`, {
+            by,
+        }),
+        unsubscribeEvents: (o, id, by) => call("DELETE", `${org(o)}/event-subscriptions/${seg(id)}`, { by }),
+        eventTriggers: (o, id) => call("GET", `${agent(o, id)}/event-triggers`),
+        setEventTrigger: (o, id, a, body) => call("PUT", `${agent(o, id)}/event-triggers/${seg(a)}`, body),
+        removeEventTrigger: (o, id, a, by) => call("DELETE", `${agent(o, id)}/event-triggers/${seg(a)}`, { by }),
+        eventRuns: (o, id, limit = 20) => call("GET", `${agent(o, id)}/event-runs?limit=${limit}`),
+        // The organization's Claude API key: write-only, shown by its last four characters.
+        claudeKey: (o) => call("GET", `${org(o)}/claude-key`),
+        setClaudeKey: (o, apiKey, by) => call("PUT", `${org(o)}/claude-key`, { apiKey, by }),
+        removeClaudeKey: (o, by) => call("DELETE", `${org(o)}/claude-key`, { by }),
+        claudeAgents: (o) => call("GET", `${org(o)}/claude-key/agents`),
+    };
+    /** One app's live site check, or null when the app cannot run it (e.g. the vendor refuses
+     *  the sign-in): the page then shows the app as needing attention instead of failing. */
+    async function checkedSites(o, a) {
+        try {
+            return (await client.checkSites(o, a)).sites;
+        }
+        catch (error) {
+            if (!(error instanceof AgentConnectError))
+                throw error;
+            console.error(`[agent-connect] site check for ${a}`, error.message);
+            return null;
+        }
+    }
+    const peeked = (o, a) => client.peek(o, a).catch((error) => {
+        if (!(error instanceof AgentConnectError))
+            throw error;
+        console.error(`[agent-connect] check for ${a}`, error.message);
+        return null;
+    });
+    return {
+        ...client,
+        checkedSites,
+        /** The read-only live check of each app of its own that is on, for warnings no stored
+         *  status holds (e.g. an app can see nothing yet). Null for an app whose check could not
+         *  run. */
+        async appChecks(o, connectors, connections) {
+            const apps = connectors.filter((c) => !c.provider &&
+                connections.some((x) => x.connectorId === c.id && x.status === "connected"));
+            const results = await Promise.all(apps.map((c) => peeked(o, c.id)));
+            return Object.fromEntries(apps.map((c, i) => [c.id, results[i]]));
+        },
+        /** Each provider app's live state for its steps (`appState`), read only: its own check
+         *  and its sites while on, the organization's Claude key where a capability needs one,
+         *  and its chosen steps' own live checks (none while those steps are not chosen, so no
+         *  vendor call). An app's page, its provider's page and the Integrations tab all read it
+         *  here, so they agree. The Claude key and the step checks are read once for all apps. */
+        async appStates(o, connectors, connections) {
+            const apps = connectors.map((connector) => {
+                const connection = connections.find((c) => c.connectorId === connector.id) ?? null;
+                const liveSteps = chosenSteps(connector, [...connector.setup, ...connector.afterConnect], connection?.config ?? {}, connection?.capabilities ?? []).filter((s) => s.live);
+                return { connector, connection, liveSteps };
+            });
+            const liveSteps = apps.flatMap((a) => a.liveSteps);
+            const [claudeKey, live, perApp] = await Promise.all([
+                apps.some((a) => a.connector.capabilities.some((c) => c.claudeKey))
+                    ? client.claudeKey(o)
+                    : null,
+                liveSteps.length
+                    ? client.teamsSetupState(o).catch((error) => {
+                        if (!(error instanceof AgentConnectError)) {
+                            console.error("[agent-connect] step checks", error);
+                            return null;
+                        }
+                        // The service's own answer (e.g. what the connection lacks) goes on each step.
+                        const failing = { state: "failing", message: error.message };
+                        return Object.fromEntries(liveSteps.map((s) => [s.live, failing]));
+                    })
+                    : null,
+                Promise.all(apps.map(({ connector, connection }) => Promise.all([
+                    connection ? peeked(o, connector.id) : null,
+                    connection && connector.siteAccess ? checkedSites(o, connector.id) : null,
+                ]))),
+            ]);
+            return Object.fromEntries(apps.map((a, i) => [
+                a.connector.id,
+                {
+                    health: perApp[i][0],
+                    sites: perApp[i][1],
+                    claudeKey: claudeKey?.set === true,
+                    live: a.liveSteps.length ? live : null,
+                },
+            ]));
+        },
+    };
+}