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

package/dist/packages/server/src/service.d.ts

@@ -0,0 +1,760 @@
+import { type Connector, type Provider } from "../../connector-kit/src/connector.js";
+import { type CredentialKey } from "./secrets.js";
+import type { AgentRow, ConnectionRow, Limits, ProviderRow, PublicConnection, Store } from "./store.js";
+import { type ToolContext, type Toolset } from "../../connector-kit/src/common.js";
+import type { TeamsAccess } from "./teams/runtime.js";
+import type { BotRow } from "./teams/store.js";
+import { type ProviderClient, type Vendor, type VendorRequest } from "../../connector-kit/src/types.js";
+export type App = {
+    connector: Connector;
+    vendor: Vendor;
+    toolset: Toolset;
+};
+export type ProviderApp = {
+    provider: Provider;
+    client: ProviderClient;
+};
+type CertificateInfo = {
+    thumbprint: string;
+    expiresAt: string;
+};
+export type PublicProvider = Omit<ProviderRow, "credential" | "credentialKeyId" | "credentialScope"> & {
+    certificate: CertificateInfo | null;
+    nextCertificate: CertificateInfo | null;
+    apps: string[];
+};
+export type CheckResult = {
+    label: string;
+    values: string[];
+    warning?: string;
+};
+export declare class InvalidInput extends Error {
+}
+export declare function validateCapabilities(connector: Connector, raw: unknown): string[];
+export declare function publicConnection(row: ConnectionRow): PublicConnection;
+export declare function publicProvider(row: ProviderRow, connections: ConnectionRow[], sharedClientId?: string | null): PublicProvider;
+export declare function sameSignIn(provider: Provider, before: Record<string, string>, after: Record<string, string>): boolean;
+export declare function assertToolsImplemented(apps: App[]): void;
+export declare function validateLimits(connector: Connector, raw: unknown): Limits;
+export declare function validateChoices(connector: Connector, fields: Record<string, string>): Record<string, string>;
+export declare function createService(deps: {
+    apps: App[];
+    providers?: ProviderApp[];
+    store: Store;
+    key: CredentialKey;
+    bots?: {
+        botForAgent(org: string, agentId: string): Promise<BotRow | null>;
+        access(bot: BotRow): TeamsAccess;
+    };
+}): {
+    connectors: () => {
+        id: string;
+        name: string;
+        description: string;
+        logo: string;
+        identity: string;
+        connectionKind: "guided";
+        accountKey: string;
+        setup: {
+            title: string;
+            body: string;
+            link?: {
+                label: string;
+                href: string;
+            } | undefined;
+            copy?: string[] | undefined;
+            shell?: "bash" | "powershell" | undefined;
+            permissions?: boolean | undefined;
+            certificate?: boolean | undefined;
+            click?: string[] | undefined;
+            clickUnavailable?: true | undefined;
+            siteRole?: "write" | "read" | undefined;
+            agentCheck?: boolean | undefined;
+            confirm?: string | undefined;
+            live?: string | undefined;
+            settings?: {
+                id: string;
+                label: string;
+                pattern: string;
+                help?: string | undefined;
+                placeholder?: string | undefined;
+            }[] | undefined;
+            option?: {
+                field: string;
+                value: string;
+            } | undefined;
+        }[];
+        afterConnect: {
+            title: string;
+            body: string;
+            link?: {
+                label: string;
+                href: string;
+            } | undefined;
+            copy?: string[] | undefined;
+            shell?: "bash" | "powershell" | undefined;
+            permissions?: boolean | undefined;
+            certificate?: boolean | undefined;
+            click?: string[] | undefined;
+            clickUnavailable?: true | undefined;
+            siteRole?: "write" | "read" | undefined;
+            agentCheck?: boolean | undefined;
+            confirm?: string | undefined;
+            live?: string | undefined;
+            settings?: {
+                id: string;
+                label: string;
+                pattern: string;
+                help?: string | undefined;
+                placeholder?: string | undefined;
+            }[] | undefined;
+            option?: {
+                field: string;
+                value: string;
+            } | undefined;
+        }[];
+        fields: {
+            id: string;
+            label: string;
+            secret: boolean;
+            help?: string | undefined;
+            placeholder?: string | undefined;
+            options?: {
+                value: string;
+                label: string;
+                description: string;
+                scopes?: string[] | undefined;
+            }[] | undefined;
+            requires?: {
+                field: string;
+                value: string;
+            } | undefined;
+        }[];
+        capabilities: {
+            id: string;
+            label: string;
+            description: string;
+            required: boolean;
+            destructive: boolean;
+            scopes: string[];
+            permissions: string[];
+            tools: string[];
+            costs?: boolean | undefined;
+            roles?: string[] | undefined;
+            fill?: Record<string, string> | undefined;
+            note?: string | undefined;
+            forbidden?: string | undefined;
+            claudeKey?: boolean | undefined;
+        }[];
+        limits: {
+            id: string;
+            label: string;
+            help: string;
+            kind: "text" | "map" | "list";
+            required: boolean;
+            pattern?: string | undefined;
+            keys?: string | undefined;
+        }[];
+        verify: {
+            method: "GET" | "POST";
+            path: string;
+            label: string;
+            show: string;
+            match?: Record<string, string | number | boolean> | undefined;
+            body?: Record<string, unknown> | undefined;
+            ifEmpty?: string | undefined;
+        } | {
+            label: string;
+            check: string;
+            ifEmpty?: string | undefined;
+        };
+        revoke: string;
+        signsInAs?: "agentBot" | undefined;
+        provider?: string | undefined;
+        order?: number | undefined;
+        scopes?: string[] | undefined;
+        siteAccess?: {
+            grant: {
+                title: string;
+                body: string;
+                link?: {
+                    label: string;
+                    href: string;
+                } | undefined;
+                copy?: string[] | undefined;
+                shell?: "bash" | "powershell" | undefined;
+                permissions?: boolean | undefined;
+                certificate?: boolean | undefined;
+                click?: string[] | undefined;
+                clickUnavailable?: true | undefined;
+                siteRole?: "write" | "read" | undefined;
+                agentCheck?: boolean | undefined;
+                confirm?: string | undefined;
+                live?: string | undefined;
+                settings?: {
+                    id: string;
+                    label: string;
+                    pattern: string;
+                    help?: string | undefined;
+                    placeholder?: string | undefined;
+                }[] | undefined;
+                option?: {
+                    field: string;
+                    value: string;
+                } | undefined;
+            }[];
+            request: string;
+            write: string[];
+        } | undefined;
+        agentAccess?: {
+            limit: string;
+            label: string;
+            path: string;
+            granted: string;
+            notGranted: string;
+            notFound: string;
+            probes: Record<string, {
+                method: "GET" | "POST" | "PATCH";
+                path: string;
+                allowed: number[];
+                body?: unknown;
+            }>;
+            missing?: string | undefined;
+        } | undefined;
+        discover?: {
+            method: "GET" | "POST";
+            path: string;
+            label: string;
+            show: string;
+            match?: Record<string, string | number | boolean> | undefined;
+            body?: Record<string, unknown> | undefined;
+            ifEmpty?: string | undefined;
+        } | {
+            label: string;
+            check: string;
+            ifEmpty?: string | undefined;
+        } | undefined;
+        http?: {
+            baseUrl: string;
+            auth: {
+                type: "header";
+                header: string;
+                value: string;
+                prefix?: string | undefined;
+            } | {
+                type: "bearer";
+                token: string;
+            } | {
+                type: "basic";
+                username: string;
+                password: string;
+            } | {
+                type: "oauth2";
+                tokenUrl: string;
+                clientId: string;
+                clientSecret: string;
+                scope?: string | undefined;
+            } | {
+                type: "query";
+                param: string;
+                value: string;
+            };
+            headers: Record<string, string>;
+            tools: {
+                name: string;
+                description: string;
+                method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+                path: string;
+                params: Record<string, {
+                    type: "string" | "number" | "boolean" | "array" | "integer";
+                    description: string;
+                    in: "path" | "body" | "query";
+                    required: boolean;
+                    name?: string | undefined;
+                    default?: string | number | boolean | (string | number | boolean)[] | undefined;
+                    enum?: (string | number | boolean)[] | undefined;
+                    items?: "string" | "number" | "boolean" | "integer" | undefined;
+                    join?: string | undefined;
+                    limit?: string | undefined;
+                }>;
+                destructive: boolean;
+                answerLimits: {
+                    field: string;
+                    limit: string;
+                }[];
+                result?: {
+                    items?: string | undefined;
+                    fields?: string[] | undefined;
+                } | undefined;
+                paging?: {
+                    param: string;
+                    body: string;
+                } | {
+                    param: string;
+                    header: string;
+                } | {
+                    param: string;
+                    link: true;
+                } | undefined;
+            }[];
+            allowInsecureHttp: boolean;
+        } | undefined;
+        soap?: {
+            endpoint: string;
+            version: "1.1" | "1.2";
+            namespaces: Record<string, string>;
+            tools: {
+                name: string;
+                description: string;
+                operation: string;
+                body: string;
+                params: Record<string, {
+                    type: "string" | "number" | "boolean" | "integer";
+                    description: string;
+                    required: boolean;
+                    limit?: string | undefined;
+                }>;
+                readOnly: boolean;
+                destructive: boolean;
+                answerLimits: {
+                    field: string;
+                    limit: string;
+                }[];
+                soapAction?: string | undefined;
+                result?: string | undefined;
+                fields?: string[] | undefined;
+            }[];
+            allowInsecureHttp: boolean;
+            auth?: {
+                type: "header";
+                header: string;
+                value: string;
+                prefix?: string | undefined;
+            } | {
+                type: "bearer";
+                token: string;
+            } | {
+                type: "basic";
+                username: string;
+                password: string;
+            } | undefined;
+            wsSecurity?: {
+                username: string;
+                password: string;
+                digest: boolean;
+            } | undefined;
+            verify?: {
+                tool: string;
+                args: Record<string, string | number | boolean>;
+                show: string;
+            } | undefined;
+        } | undefined;
+        odata?: {
+            serviceRoot: string;
+            version: "2" | "4";
+            auth: {
+                type: "header";
+                header: string;
+                value: string;
+                prefix?: string | undefined;
+            } | {
+                type: "bearer";
+                token: string;
+            } | {
+                type: "basic";
+                username: string;
+                password: string;
+            } | {
+                type: "oauth2";
+                tokenUrl: string;
+                clientId: string;
+                clientSecret: string;
+                scope?: string | undefined;
+            } | {
+                type: "query";
+                param: string;
+                value: string;
+            };
+            headers: Record<string, string>;
+            csrf: boolean;
+            paging: "skip" | "server";
+            tools: {
+                name: string;
+                description: string;
+                kind: "function" | "list" | "get" | "create" | "update" | "action";
+                key: Record<string, {
+                    type: "string" | "number" | "boolean" | "integer" | "decimal" | "guid" | "datetime" | "datetimeoffset";
+                    description: string;
+                    property?: string | undefined;
+                    required?: boolean | undefined;
+                    limit?: string | undefined;
+                }>;
+                filters: Record<string, {
+                    type: "string" | "number" | "boolean" | "integer" | "decimal" | "guid" | "datetime" | "datetimeoffset";
+                    description: string;
+                    op: "eq" | "ne" | "gt" | "ge" | "lt" | "le" | "contains" | "startswith";
+                    property?: string | undefined;
+                    required?: boolean | undefined;
+                    limit?: string | undefined;
+                }>;
+                fields: Record<string, {
+                    type: "string" | "number" | "boolean" | "integer" | "decimal" | "guid" | "datetime" | "datetimeoffset";
+                    description: string;
+                    property?: string | undefined;
+                    required?: boolean | undefined;
+                    limit?: string | undefined;
+                }>;
+                params: Record<string, {
+                    type: "string" | "number" | "boolean" | "integer" | "decimal" | "guid" | "datetime" | "datetimeoffset";
+                    description: string;
+                    property?: string | undefined;
+                    required?: boolean | undefined;
+                    limit?: string | undefined;
+                }>;
+                select: string[];
+                top: number;
+                destructive: boolean;
+                answerLimits: {
+                    field: string;
+                    limit: string;
+                }[];
+                entitySet?: string | undefined;
+                function?: string | undefined;
+                orderBy?: string | undefined;
+            }[];
+            allowInsecureHttp: boolean;
+        } | undefined;
+        sql?: {
+            engine: "postgres" | "sqlserver" | "mysql" | "oracle";
+            host: string;
+            database: string;
+            auth: {
+                user: string;
+                password: string;
+            };
+            tls: "verify" | "insecure" | "off";
+            timeoutSeconds: number;
+            maxRows: number;
+            tools: {
+                name: string;
+                description: string;
+                sql: string;
+                params: Record<string, {
+                    type: "string" | "number" | "boolean" | "integer";
+                    description: string;
+                    required: boolean;
+                    limit?: string | undefined;
+                }>;
+                write: boolean;
+                destructive: boolean;
+                answerLimits: {
+                    column: string;
+                    limit: string;
+                }[];
+            }[];
+            port?: number | undefined;
+        } | undefined;
+        events?: {
+            types: {
+                id: string;
+                label: string;
+            }[];
+            fields: Record<string, string>;
+            limits: Record<string, string>;
+            webhook?: {
+                verify: {
+                    type: "hmac-sha256";
+                    header: string;
+                    prefix: string;
+                } | {
+                    type: "token";
+                    header: string;
+                } | {
+                    type: "none";
+                };
+                allowInsecure: boolean;
+                type: {
+                    field: string;
+                } | {
+                    header: string;
+                };
+                setup: {
+                    title: string;
+                    body: string;
+                    link?: {
+                        label: string;
+                        href: string;
+                    } | undefined;
+                    copy?: string[] | undefined;
+                    shell?: "bash" | "powershell" | undefined;
+                    permissions?: boolean | undefined;
+                    certificate?: boolean | undefined;
+                    click?: string[] | undefined;
+                    clickUnavailable?: true | undefined;
+                    siteRole?: "write" | "read" | undefined;
+                    agentCheck?: boolean | undefined;
+                    confirm?: string | undefined;
+                    live?: string | undefined;
+                    settings?: {
+                        id: string;
+                        label: string;
+                        pattern: string;
+                        help?: string | undefined;
+                        placeholder?: string | undefined;
+                    }[] | undefined;
+                    option?: {
+                        field: string;
+                        value: string;
+                    } | undefined;
+                }[];
+                deliveryId?: {
+                    field: string;
+                } | {
+                    header: string;
+                } | undefined;
+                timestamp?: {
+                    at: {
+                        field: string;
+                    } | {
+                        header: string;
+                    };
+                    unit: "s" | "ms" | "iso";
+                    toleranceSeconds: number;
+                } | undefined;
+                register?: {
+                    method: "GET" | "POST" | "PUT";
+                    path: string;
+                    location: string;
+                    body?: unknown;
+                } | undefined;
+            } | undefined;
+            self?: {
+                request: {
+                    method: "GET" | "POST" | "PUT";
+                    path: string;
+                    body?: unknown;
+                };
+                id: string;
+                fields: string[];
+            } | undefined;
+            poll?: {
+                request: {
+                    method: "GET" | "POST" | "PUT";
+                    path: string;
+                    body?: unknown;
+                };
+                items: string;
+                cursor: string;
+                deliveryId: string[];
+                types: {
+                    type: string;
+                    same?: [string, string] | undefined;
+                }[];
+                filter?: string | undefined;
+                wrap?: string | undefined;
+            } | undefined;
+        } | undefined;
+    }[];
+    providers: () => {
+        approval: boolean;
+        id: string;
+        name: string;
+        logo: string;
+        identity: string;
+        accountKey: string;
+        principalKeys: string[];
+        certificate: boolean;
+        setup: {
+            title: string;
+            body: string;
+            link?: {
+                label: string;
+                href: string;
+            } | undefined;
+            copy?: string[] | undefined;
+            shell?: "bash" | "powershell" | undefined;
+            permissions?: boolean | undefined;
+            certificate?: boolean | undefined;
+            click?: string[] | undefined;
+            clickUnavailable?: true | undefined;
+            siteRole?: "write" | "read" | undefined;
+            agentCheck?: boolean | undefined;
+            confirm?: string | undefined;
+            live?: string | undefined;
+            settings?: {
+                id: string;
+                label: string;
+                pattern: string;
+                help?: string | undefined;
+                placeholder?: string | undefined;
+            }[] | undefined;
+            option?: {
+                field: string;
+                value: string;
+            } | undefined;
+        }[];
+        fields: {
+            id: string;
+            label: string;
+            secret: boolean;
+            optional: boolean;
+            help?: string | undefined;
+            placeholder?: string | undefined;
+            options?: {
+                value: string;
+                label: string;
+                description: string;
+                scopes?: string[] | undefined;
+            }[] | undefined;
+            requires?: {
+                field: string;
+                value: string;
+            } | undefined;
+        }[];
+        addAgent: {
+            title: string;
+            body: string;
+            apps: string[];
+            link?: {
+                label: string;
+                href: string;
+            } | undefined;
+            copy?: string[] | undefined;
+            shell?: "bash" | "powershell" | undefined;
+            permissions?: boolean | undefined;
+            certificate?: boolean | undefined;
+            click?: string[] | undefined;
+            clickUnavailable?: true | undefined;
+            siteRole?: "write" | "read" | undefined;
+            agentCheck?: boolean | undefined;
+            confirm?: string | undefined;
+            live?: string | undefined;
+            settings?: {
+                id: string;
+                label: string;
+                pattern: string;
+                help?: string | undefined;
+                placeholder?: string | undefined;
+            }[] | undefined;
+            option?: {
+                field: string;
+                value: string;
+            } | undefined;
+        }[];
+        revoke: string;
+        sharedIdentity?: string | undefined;
+    }[];
+    listConnections(org: string): Promise<PublicConnection[]>;
+    listProviders(org: string): Promise<PublicProvider[]>;
+    listConfirmed(org: string): Promise<{
+        step: string;
+        by: string;
+        at: string;
+    }[]>;
+    setConfirmed(org: string, step: string, by: string, on: boolean): Promise<void>;
+    connect(input: {
+        organizationId: string;
+        connectorId: string;
+        capabilities: unknown;
+        fields: Record<string, string>;
+        connectedBy: string;
+    }): Promise<{
+        connection: PublicConnection;
+        checks: CheckResult[];
+    }>;
+    connectProvider(input: {
+        organizationId: string;
+        provider: string;
+        fields: Record<string, string>;
+        connectedBy: string;
+    }): Promise<PublicProvider>;
+    newCertificate(org: string, id: string, by: string): Promise<PublicProvider>;
+    activateCertificate(org: string, id: string, by: string): Promise<PublicProvider>;
+    checkProvider(org: string, id: string): Promise<{
+        ok: false;
+        error: string;
+    } | {
+        ok: true;
+        error?: undefined;
+    } | null>;
+    setProviderSettings(org: string, id: string, values: Record<string, string>, by: string): Promise<{
+        settings: Record<string, string>;
+    }>;
+    disconnectProvider(org: string, id: string, by: string): Promise<boolean>;
+    startConsent(input: {
+        organizationId: string;
+        connectorId: string;
+        capabilities: unknown;
+        redirectUri: string;
+    }): {
+        url: string;
+        nonce: string;
+    };
+    finishConsent(input: {
+        organizationId: string;
+        connectorId: string;
+        state: string;
+        nonce: string;
+        params: Record<string, string>;
+        connectedBy: string;
+    }): Promise<{
+        redirect: string;
+    } | {
+        provider: PublicProvider;
+    } | Awaited<ReturnType<(target: App, input: {
+        organizationId: string;
+        connectorId: string;
+        capabilities: unknown;
+        fields: Record<string, string>;
+        connectedBy: string;
+    }) => Promise<{
+        connection: PublicConnection;
+        checks: CheckResult[];
+    }>>>>;
+    check(org: string, connectorId: string, { record, by }?: {
+        record?: boolean;
+        by?: string;
+    }): Promise<{
+        ok: true;
+        checks: CheckResult[];
+        error?: undefined;
+    } | {
+        ok: false;
+        error: string;
+        checks?: undefined;
+    } | null>;
+    setSites(org: string, connectorId: string, raw: string[]): Promise<{
+        sites: string[];
+    } | null>;
+    siteAccess(org: string, connectorId: string, only?: string): Promise<{
+        sites: import("../../connector-kit/src/types.js").SiteAccess[];
+    } | null>;
+    agentAccess(org: string, connectorId: string, value: string, by: string): Promise<{
+        value: string;
+        status: "not_granted" | "not_found" | "failed";
+        message: string;
+    } | {
+        value: string;
+        status: "granted";
+        message: string;
+    } | null>;
+    setCeiling(org: string, connectorId: string, ceiling: unknown): Promise<string[] | null>;
+    setGrant(org: string, agentId: string, connectorId: string, capabilities: unknown, limits: unknown): Promise<{
+        capabilities: string[];
+        limits: Limits;
+    } | null>;
+    /** A call with the organization's own connection, no agent's (an event poll or a webhook
+     *  registration). Null when the app is not connected. */
+    appCall(org: string, connectorId: string, request: VendorRequest): Promise<import("../../connector-kit/src/types.js").VendorResponse | null>;
+    agentSession(rawKey: string): Promise<{
+        agent: AgentRow;
+        toolsets: {
+            toolset: Toolset;
+            ctx: ToolContext;
+            allowed: Set<string>;
+        }[];
+        refuseUngranted(tool: string, args: unknown): Promise<void>;
+    } | null>;
+};
+export type Service = ReturnType<typeof createService>;
+export {};