@opengeni/db 0.28.9 → 0.36.0

package/dist/capability-integrations.d.ts

@@ -0,0 +1,194 @@
+import { type McpServerConnectionRef } from "@opengeni/contracts";
+import { type Database } from "./database.js";
+export type ApiIntegrationProtocol = "openapi" | "graphql";
+export type ApiIntegrationToolSafety = "read" | "write" | "destructive";
+export type ApiIntegrationApprovalMode = "never" | "ask";
+export type ApiIntegrationFacetDefinition = {
+    readonly facetKey: string;
+    readonly kind: "knowledge_source" | "inbound_trigger" | "delivery_destination" | "identity_link";
+    readonly configSchema: Readonly<Record<string, unknown>>;
+    readonly capabilities: Readonly<Record<string, unknown>>;
+};
+export type ApiIntegrationToolDefinition = {
+    readonly id: string;
+    readonly operationKey: string;
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Readonly<Record<string, unknown>>;
+    readonly outputSchema?: Readonly<Record<string, unknown>>;
+    readonly safety: ApiIntegrationToolSafety;
+    readonly approvalMode: ApiIntegrationApprovalMode;
+    readonly deprecated: boolean;
+};
+type StoredApiIntegrationRevisionBase = {
+    readonly id: string;
+    readonly definitionId: string;
+    readonly contentSha256: string;
+    readonly source: {
+        readonly url?: string;
+        readonly provider?: string;
+        readonly fetchedAt?: string;
+    };
+    readonly title: string;
+    readonly description?: string;
+    readonly version?: string;
+    readonly tools: readonly ApiIntegrationToolDefinition[];
+};
+export type StoredOpenApiOperationBinding = {
+    readonly method: "get" | "put" | "post" | "delete" | "patch" | "head" | "options" | "trace";
+    readonly pathTemplate: string;
+    readonly serverUrl: string;
+    readonly parameters: readonly {
+        readonly name: string;
+        readonly location: "path" | "query" | "header" | "cookie";
+        readonly required: boolean;
+        readonly schema: Readonly<Record<string, unknown>>;
+        readonly description?: string;
+    }[];
+    readonly requestBody?: {
+        readonly required: boolean;
+        readonly contentTypes: readonly string[];
+        readonly schemas: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+    };
+    readonly requiredScopeAlternatives?: readonly (readonly string[])[];
+};
+export type StoredGraphqlOperationBinding = {
+    readonly kind: "query" | "mutation";
+    readonly fieldName: string;
+    readonly operationName: string;
+    readonly variableDefinitions: readonly string[];
+    readonly variableNames: readonly string[];
+    readonly defaultSelection?: string;
+    readonly selectionAllowed: boolean;
+};
+/** Protocol-normalized immutable revision persisted in integration_spec_revisions.spec. */
+export type StoredApiIntegrationRevision = (StoredApiIntegrationRevisionBase & {
+    readonly protocol: "openapi";
+    readonly bindings: Readonly<Record<string, StoredOpenApiOperationBinding>>;
+}) | (StoredApiIntegrationRevisionBase & {
+    readonly protocol: "graphql";
+    readonly bindings: Readonly<Record<string, StoredGraphqlOperationBinding>>;
+});
+export type InstallApiIntegrationInput = {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    capabilityId: string;
+    pluginKey: string;
+    serverId: string;
+    name: string;
+    description?: string | null;
+    category?: string;
+    tags?: string[];
+    definitionId: string;
+    definitionProvenance: "curated" | "workspace";
+    provider?: string;
+    providerDomain: string;
+    protocol: ApiIntegrationProtocol;
+    baseUrl: string;
+    sourceUrl?: string | null;
+    authScheme?: Record<string, unknown>;
+    connectionId?: string | null;
+    instanceKey?: string;
+    displayName?: string;
+    expectedInstanceVersion?: number;
+    requiredScopes?: string[];
+    ownership?: "workspace" | "subject" | "either";
+    allowedTools?: string[];
+    facetDefinitions?: readonly ApiIntegrationFacetDefinition[];
+    revision: StoredApiIntegrationRevision;
+    owner?: ApiIntegrationOwner;
+};
+export type InstalledApiIntegration = {
+    capabilityId: string;
+    pluginId: string;
+    pluginVersionId: string;
+    integrationFacetId: string;
+    apiFacetId: string;
+    pluginInstallationId: string;
+    integrationFacetInstallationId: string;
+    apiFacetInstallationId: string;
+    installationVersion: number;
+    instanceId: string;
+    instanceKey: string;
+    displayName: string;
+    instanceVersion: number;
+    revisionId: string;
+    serverId: string;
+    status: "installed";
+};
+export type ApiIntegrationRuntime = {
+    capabilityId: string;
+    pluginKey: string;
+    pluginInstallationId: string;
+    installationVersion: number;
+    instanceId: string;
+    instanceKey: string;
+    displayName: string;
+    instanceVersion: number;
+    serverId: string;
+    name: string;
+    description: string | null;
+    protocol: ApiIntegrationProtocol;
+    definitionId: string;
+    definitionProvenance: "curated" | "workspace";
+    baseUrl: string;
+    sourceUrl: string | null;
+    providerDomain: string;
+    authScheme: Record<string, unknown>;
+    connectionRef: McpServerConnectionRef | null;
+    allowedTools: string[];
+    requireApproval: true | string[];
+    revision: StoredApiIntegrationRevision;
+};
+export type ApiIntegrationOwner = {
+    kind: "direct" | "plugin" | "pack" | "migration";
+    id: string;
+    removable: boolean;
+};
+export type ApiIntegrationUninstallPreview = {
+    capabilityId: string;
+    instanceKey: string;
+    displayName: string | null;
+    installed: boolean;
+    installationVersion: number | null;
+    instanceVersion: number | null;
+    directOwner: ApiIntegrationOwner | null;
+    remainingOwners: ApiIntegrationOwner[];
+    removesRuntimeIntegration: boolean;
+    removesDefinition: boolean;
+};
+export type UninstallApiIntegrationResult = {
+    capabilityId: string;
+    instanceKey: string;
+    status: "not_installed" | "uninstalled" | "retained_by_other_owners";
+    remainingOwners: ApiIntegrationOwner[];
+    definitionStatus: "retained" | "disabled";
+};
+export declare class ApiIntegrationInstallationVersionConflictError extends Error {
+    readonly capabilityId: string;
+    readonly expectedVersion: number;
+    readonly actualVersion: number;
+    readonly name = "ApiIntegrationInstallationVersionConflictError";
+    constructor(capabilityId: string, expectedVersion: number, actualVersion: number);
+}
+export declare function installApiIntegration(db: Database, input: InstallApiIntegrationInput): Promise<InstalledApiIntegration>;
+export declare function listInstalledApiIntegrations(db: Database, workspaceId: string, subjectId?: string): Promise<ApiIntegrationRuntime[]>;
+/**
+ * Read installed API Integrations from a transaction that already carries the
+ * workspace RLS context. This is intentionally separate from the public
+ * wrapper so compound Plugin/Pack lifecycle transactions never open a nested
+ * transaction or lose their advisory locks.
+ */
+export declare function listInstalledApiIntegrationsInRlsContext(scopedDb: Database, workspaceId: string, subjectId?: string): Promise<ApiIntegrationRuntime[]>;
+export declare function getApiIntegrationUninstallPreview(db: Database, workspaceId: string, subjectId: string, capabilityId: string, instanceKey: string): Promise<ApiIntegrationUninstallPreview>;
+export declare function uninstallApiIntegration(db: Database, input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    capabilityId: string;
+    instanceKey: string;
+    expectedInstallationVersion: number;
+    expectedInstanceVersion: number;
+}): Promise<UninstallApiIntegrationResult>;
+export {};