@kognitivedev/cloud-platforms 0.2.29

package/src/__tests__/client.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it, vi } from "vitest";
+import { CloudPlatforms } from "../client";
+
+function jsonResponse(value: unknown, status = 200): Response {
+    return new Response(JSON.stringify(value), {
+        status,
+        headers: { "Content-Type": "application/json" },
+    });
+}
+
+function makeFetch() {
+    const calls: Array<{ url: string; init: RequestInit | undefined }> = [];
+    const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
+        const url = String(input);
+        calls.push({ url, init });
+
+        if (url.endsWith("/api/cloud/platforms/catalog")) {
+            return jsonResponse({
+                toolkits: [],
+                actions: [],
+                lastSyncedAt: null,
+            });
+        }
+
+        if (url.includes("/api/cloud/platforms/tools")) {
+            return jsonResponse({
+                tools: [
+                    {
+                        id: "platform_slack_send_message",
+                        actionSlug: "SEND_MESSAGE",
+                        toolkitSlug: "slack",
+                        name: "Send message",
+                        description: "Send a Slack message\n\nAvailable connections: Acme Slack (conn-1).",
+                        inputSchema: {
+                            type: "object",
+                            properties: {
+                                connectionId: { type: "string", enum: ["conn-1"] },
+                                text: { type: "string" },
+                            },
+                            required: ["connectionId", "text"],
+                        },
+                        outputSchema: { type: "object" },
+                        requireApproval: true,
+                        connections: [{ id: "conn-1", label: "Acme Slack", toolkitSlug: "slack" }],
+                    },
+                ],
+            });
+        }
+
+        if (url.endsWith("/api/cloud/platforms/actions/SEND_MESSAGE/execute")) {
+            return jsonResponse({
+                actionSlug: "SEND_MESSAGE",
+                toolkitSlug: "slack",
+                connectionId: "conn-1",
+                version: "20260424",
+                result: { ok: true },
+            });
+        }
+
+        return jsonResponse({ error: "not found" }, 404);
+    });
+
+    return { fetchMock, calls };
+}
+
+describe("CloudPlatforms", () => {
+    it("requires explicit apiKey and baseUrl", () => {
+        expect(() => new CloudPlatforms({ apiKey: "", baseUrl: "https://api.example.com" })).toThrow("apiKey");
+        expect(() => new CloudPlatforms({ apiKey: "key", baseUrl: "" })).toThrow("baseUrl");
+    });
+
+    it("sends API-key scoped requests", async () => {
+        const { fetchMock, calls } = makeFetch();
+        const platforms = new CloudPlatforms({
+            apiKey: "kog_test",
+            baseUrl: "https://api.example.com",
+            fetch: fetchMock,
+        });
+
+        await platforms.catalog();
+
+        expect(calls[0].url).toBe("https://api.example.com/api/cloud/platforms/catalog");
+        expect(new Headers(calls[0].init?.headers).get("Authorization")).toBe("Bearer kog_test");
+    });
+
+    it("creates one executable model tool per backend action", async () => {
+        const { fetchMock, calls } = makeFetch();
+        const platforms = new CloudPlatforms({
+            apiKey: "kog_test",
+            baseUrl: "https://api.example.com",
+            fetch: fetchMock,
+        });
+
+        const tools = await platforms.tools({ selectedConnectionIds: ["conn-1"] });
+        const result = await tools[0].execute(
+            { connectionId: "conn-1", text: "hello" },
+            {
+                abortSignal: new AbortController().signal,
+                resourceId: {},
+                emit: () => undefined,
+                metadata: {
+                    platforms: {
+                        approval: { approved: true, toolCallId: "call-1" },
+                    },
+                },
+            },
+        );
+
+        expect(tools[0]).toMatchObject({
+            id: "platform_slack_send_message",
+            requireApproval: true,
+        });
+        expect(result.result).toEqual({ ok: true });
+        const executeCall = calls.find((call) => call.url.endsWith("/api/cloud/platforms/actions/SEND_MESSAGE/execute"));
+        expect(JSON.parse(String(executeCall?.init?.body))).toEqual({
+            connectionId: "conn-1",
+            arguments: { text: "hello" },
+            approval: { approved: true, toolCallId: "call-1" },
+        });
+    });
+
+    it("context adapter reads selected connection ids from metadata", async () => {
+        const { fetchMock, calls } = makeFetch();
+        const platforms = new CloudPlatforms({
+            apiKey: "kog_test",
+            baseUrl: "https://api.example.com",
+            fetch: fetchMock,
+        });
+
+        const result = await platforms.contextAdapter().resolve({
+            resourceId: {},
+            messages: [],
+            abortSignal: new AbortController().signal,
+            metadata: {
+                platforms: {
+                    selectedConnectionIds: ["conn-1"],
+                },
+            },
+        });
+
+        expect(result.tools).toHaveLength(1);
+        expect(calls.some((call) => call.url.includes("selectedConnectionIds=conn-1"))).toBe(true);
+    });
+});

package/src/client.ts

@@ -0,0 +1,211 @@
+import { HttpTransport, withQuery } from "@kognitivedev/client-core";
+import type { AgentContextAdapter } from "@kognitivedev/agents";
+import type { ToolContext } from "@kognitivedev/tools";
+import type {
+    CloudPlatformsClient,
+    CloudPlatformsConfig,
+    CloudPlatformsContextAdapterOptions,
+    CloudPlatformToolsInput,
+    ConnectLinkInput,
+    ConnectLinkResult,
+    ExecutePlatformActionInput,
+    ListPlatformActionsInput,
+    PlatformAction,
+    PlatformActionResult,
+    PlatformCatalog,
+    PlatformConnection,
+    PlatformTool,
+    PlatformToolDefinition,
+    SyncConnectionsInput,
+} from "./types";
+import {
+    cloneUnknown,
+    decodeActionResult,
+    decodeActionsEnvelope,
+    decodeCatalog,
+    decodeConnectLink,
+    decodeConnectionsEnvelope,
+    decodeToolsEnvelope,
+    isPlainObject,
+    validateOptionalStringArray,
+} from "./validation";
+
+const CLOUD_PLATFORMS_PATH = "/api/cloud/platforms";
+
+function requireNonEmptyConfigValue(value: string | undefined, name: string): string {
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`CloudPlatforms requires ${name}`);
+    }
+    return value.trim();
+}
+
+function normalizeSelectedConnectionIds(input?: CloudPlatformToolsInput): string[] | undefined {
+    return validateOptionalStringArray(input?.selectedConnectionIds, "selectedConnectionIds");
+}
+
+function getPlatformsMetadata(metadata: unknown): Record<string, unknown> | null {
+    if (!isPlainObject(metadata)) {
+        return null;
+    }
+    const platforms = metadata.platforms;
+    return isPlainObject(platforms) ? platforms : null;
+}
+
+function getSelectedConnectionIdsFromMetadata(metadata: unknown): string[] | undefined {
+    const platforms = getPlatformsMetadata(metadata);
+    if (!platforms) {
+        return undefined;
+    }
+    return validateOptionalStringArray(platforms.selectedConnectionIds, "metadata.platforms.selectedConnectionIds");
+}
+
+function getApprovalFromMetadata(metadata: unknown): ExecutePlatformActionInput["approval"] | undefined {
+    const platforms = getPlatformsMetadata(metadata);
+    if (!platforms) {
+        return undefined;
+    }
+
+    const approval = platforms.approval;
+    if (!isPlainObject(approval)) {
+        return undefined;
+    }
+
+    return {
+        approved: approval.approved === true,
+        ...(typeof approval.toolCallId === "string" ? { toolCallId: approval.toolCallId } : {}),
+        ...(typeof approval.approvedBy === "string" ? { approvedBy: approval.approvedBy } : {}),
+        ...(typeof approval.approvedAt === "string" ? { approvedAt: approval.approvedAt } : {}),
+    };
+}
+
+function parseToolInput(value: unknown): { connectionId: string; arguments: Record<string, unknown> } {
+    if (!isPlainObject(value)) {
+        throw new Error("Platform tool input must be an object");
+    }
+    if (typeof value.connectionId !== "string" || !value.connectionId.trim()) {
+        throw new Error("Platform tool input requires connectionId");
+    }
+
+    const args: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (key !== "connectionId") {
+            args[key] = cloneUnknown(entry);
+        }
+    }
+
+    return {
+        connectionId: value.connectionId.trim(),
+        arguments: args,
+    };
+}
+
+function createPlatformTool(client: CloudPlatforms, definition: PlatformToolDefinition): PlatformTool {
+    return {
+        id: definition.id,
+        description: definition.description,
+        inputSchema: cloneUnknown(definition.inputSchema),
+        outputSchema: cloneUnknown(definition.outputSchema),
+        requireApproval: definition.requireApproval,
+        execute: async (input: Record<string, unknown>, context: ToolContext) => {
+            const parsed = parseToolInput(input);
+            return client.execute({
+                actionSlug: definition.actionSlug,
+                connectionId: parsed.connectionId,
+                arguments: parsed.arguments,
+                approval: getApprovalFromMetadata(context.metadata),
+            });
+        },
+        toModelOutput: (output: PlatformActionResult) => JSON.stringify(output.result),
+    };
+}
+
+export class CloudPlatforms implements CloudPlatformsClient {
+    private readonly transport: HttpTransport;
+
+    constructor(config: CloudPlatformsConfig) {
+        const apiKey = requireNonEmptyConfigValue(config.apiKey, "apiKey");
+        const baseUrl = requireNonEmptyConfigValue(config.baseUrl, "baseUrl");
+        this.transport = new HttpTransport({
+            apiKey,
+            baseUrl,
+            fetch: config.fetch,
+            timeout: config.timeout,
+            logLevel: config.logLevel,
+        });
+    }
+
+    async catalog(): Promise<PlatformCatalog> {
+        const response = await this.transport.json<unknown>(`${CLOUD_PLATFORMS_PATH}/catalog`);
+        return decodeCatalog(response);
+    }
+
+    async connections(): Promise<PlatformConnection[]> {
+        const response = await this.transport.json<unknown>(`${CLOUD_PLATFORMS_PATH}/connections`);
+        return decodeConnectionsEnvelope(response);
+    }
+
+    async connectLink(input: ConnectLinkInput): Promise<ConnectLinkResult> {
+        const response = await this.transport.json<unknown>(`${CLOUD_PLATFORMS_PATH}/connect-link`, {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+        return decodeConnectLink(response);
+    }
+
+    async syncConnections(input: SyncConnectionsInput = {}): Promise<PlatformConnection[]> {
+        const response = await this.transport.json<unknown>(`${CLOUD_PLATFORMS_PATH}/connections/sync`, {
+            method: "POST",
+            body: JSON.stringify(input),
+        });
+        return decodeConnectionsEnvelope(response);
+    }
+
+    async actions(input: ListPlatformActionsInput = {}): Promise<PlatformAction[]> {
+        const response = await this.transport.json<unknown>(`${CLOUD_PLATFORMS_PATH}/actions`);
+        const actions = decodeActionsEnvelope(response);
+        if (!input.toolkitSlug) {
+            return actions;
+        }
+        return actions.filter((action) => action.toolkitSlug === input.toolkitSlug);
+    }
+
+    async toolDefinitions(input: CloudPlatformToolsInput = {}): Promise<PlatformToolDefinition[]> {
+        const selectedConnectionIds = normalizeSelectedConnectionIds(input);
+        const path = selectedConnectionIds
+            ? withQuery(`${CLOUD_PLATFORMS_PATH}/tools`, { selectedConnectionIds: selectedConnectionIds.join(",") })
+            : `${CLOUD_PLATFORMS_PATH}/tools`;
+        const response = await this.transport.json<unknown>(path);
+        return decodeToolsEnvelope(response);
+    }
+
+    async tools(input: CloudPlatformToolsInput = {}): Promise<PlatformTool[]> {
+        const definitions = await this.toolDefinitions(input);
+        return definitions.map((definition) => createPlatformTool(this, definition));
+    }
+
+    async execute(input: ExecutePlatformActionInput): Promise<PlatformActionResult> {
+        const response = await this.transport.json<unknown>(
+            `${CLOUD_PLATFORMS_PATH}/actions/${encodeURIComponent(input.actionSlug)}/execute`,
+            {
+                method: "POST",
+                body: JSON.stringify({
+                    connectionId: input.connectionId,
+                    arguments: input.arguments,
+                    ...(input.approval ? { approval: input.approval } : {}),
+                }),
+            },
+        );
+        return decodeActionResult(response);
+    }
+
+    contextAdapter(options: CloudPlatformsContextAdapterOptions = {}): AgentContextAdapter {
+        return {
+            resolve: async (input) => {
+                const metadataSelectedConnectionIds = getSelectedConnectionIdsFromMetadata(input.metadata);
+                const selectedConnectionIds = metadataSelectedConnectionIds ?? options.selectedConnectionIds;
+                const tools = await this.tools({ selectedConnectionIds });
+                return { tools };
+            },
+        };
+    }
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+export { CloudPlatforms } from "./client";
+export { CloudPlatformsValidationError } from "./validation";
+export type {
+    CloudPlatformsClient,
+    CloudPlatformsConfig,
+    CloudPlatformsContextAdapterOptions,
+    CloudPlatformToolsInput,
+    ConnectLinkInput,
+    ConnectLinkResult,
+    ExecutePlatformActionInput,
+    ListPlatformActionsInput,
+    PlatformAction,
+    PlatformActionResult,
+    PlatformApprovalMetadata,
+    PlatformCatalog,
+    PlatformConnection,
+    PlatformTool,
+    PlatformToolConnection,
+    PlatformToolDefinition,
+    PlatformToolkit,
+    SyncConnectionsInput,
+} from "./types";

package/src/types.ts

@@ -0,0 +1,135 @@
+import type { AgentContextAdapter } from "@kognitivedev/agents";
+import type { LogLevel } from "@kognitivedev/client-core";
+import type { Tool } from "@kognitivedev/tools";
+
+export interface CloudPlatformsConfig {
+    apiKey: string;
+    baseUrl: string;
+    fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+    timeout?: number;
+    logLevel?: LogLevel;
+}
+
+export interface PlatformToolkit {
+    id: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    iconUrl: string | null;
+    categories: string[];
+    managedAuthSchemes: string[];
+}
+
+export interface PlatformAction {
+    id: string;
+    slug: string;
+    toolkitSlug: string;
+    name: string;
+    description: string | null;
+    version: string | null;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    tags: string[];
+    isDangerous: boolean;
+    requireApproval: boolean;
+}
+
+export interface PlatformConnection {
+    id: string;
+    toolkitSlug: string;
+    alias: string | null;
+    displayName: string | null;
+    status: string;
+    externalAccountLabel: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+    lastSyncedAt: string;
+    lastVerifiedAt: string | null;
+}
+
+export interface PlatformCatalog {
+    toolkits: PlatformToolkit[];
+    actions: PlatformAction[];
+    lastSyncedAt: string | null;
+}
+
+export interface ConnectLinkInput {
+    toolkitSlug: string;
+    alias?: string | null;
+}
+
+export interface ConnectLinkResult {
+    toolkitSlug: string;
+    connectionRequestId: string;
+    redirectUrl: string;
+}
+
+export interface SyncConnectionsInput {
+    toolkitSlugs?: string[];
+}
+
+export interface ListPlatformActionsInput {
+    toolkitSlug?: string;
+}
+
+export interface CloudPlatformToolsInput {
+    selectedConnectionIds?: string[];
+}
+
+export interface PlatformToolConnection {
+    id: string;
+    label: string;
+    toolkitSlug: string;
+}
+
+export interface PlatformToolDefinition {
+    id: string;
+    actionSlug: string;
+    toolkitSlug: string;
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    requireApproval: boolean;
+    connections: PlatformToolConnection[];
+}
+
+export interface PlatformApprovalMetadata {
+    approved: boolean;
+    toolCallId?: string;
+    approvedBy?: string;
+    approvedAt?: string;
+}
+
+export interface ExecutePlatformActionInput {
+    actionSlug: string;
+    connectionId: string;
+    arguments: Record<string, unknown>;
+    approval?: PlatformApprovalMetadata;
+}
+
+export interface PlatformActionResult {
+    actionSlug: string;
+    toolkitSlug: string;
+    connectionId: string;
+    version: string | null;
+    result: unknown;
+}
+
+export interface CloudPlatformsContextAdapterOptions {
+    selectedConnectionIds?: string[];
+}
+
+export type PlatformTool = Tool<Record<string, unknown>, PlatformActionResult>;
+
+export interface CloudPlatformsClient {
+    catalog(): Promise<PlatformCatalog>;
+    connections(): Promise<PlatformConnection[]>;
+    connectLink(input: ConnectLinkInput): Promise<ConnectLinkResult>;
+    syncConnections(input?: SyncConnectionsInput): Promise<PlatformConnection[]>;
+    actions(input?: ListPlatformActionsInput): Promise<PlatformAction[]>;
+    tools(input?: CloudPlatformToolsInput): Promise<PlatformTool[]>;
+    execute(input: ExecutePlatformActionInput): Promise<PlatformActionResult>;
+    contextAdapter(options?: CloudPlatformsContextAdapterOptions): AgentContextAdapter;
+}