@openserv-labs/client 1.0.0

package/dist/workflows-api.d.ts

@@ -0,0 +1,142 @@
+import type { PlatformClient } from "./client";
+import type { WorkflowConfig, TriggerDefinition, TaskDefinition, EdgeDefinition, Edge } from "./types";
+import { Workflow } from "./workflow";
+/**
+ * API for managing workflows on the OpenServ platform.
+ *
+ * @example
+ * ```typescript
+ * const client = new PlatformClient({ apiKey: 'your-key' });
+ *
+ * // Create a workflow
+ * const workflow = await client.workflows.create({
+ *   name: 'My Workflow',
+ *   goal: 'Process data automatically',
+ *   agentIds: [123, 456]
+ * });
+ *
+ * // List all workflows
+ * const workflows = await client.workflows.list();
+ *
+ * // Get a specific workflow
+ * const workflow = await client.workflows.get({ id: 789 });
+ * ```
+ */
+export declare class WorkflowsAPI {
+    private client;
+    constructor(client: PlatformClient);
+    /**
+     * Create a new workflow.
+     *
+     * Can create an empty workflow or a fully configured one with triggers, tasks, and edges.
+     *
+     * @param config - Workflow configuration
+     * @param config.name - Name of the workflow
+     * @param config.goal - Goal/description of what the workflow does
+     * @param config.agentIds - Array of agent IDs to include in the workflow
+     * @param config.triggers - Optional array of trigger definitions
+     * @param config.tasks - Optional array of task definitions
+     * @param config.edges - Optional array of edge definitions connecting nodes
+     * @returns The created Workflow object
+     *
+     * @example
+     * ```typescript
+     * // Simple workflow
+     * const workflow = await client.workflows.create({
+     *   name: 'Data Pipeline',
+     *   goal: 'Process incoming data',
+     *   agentIds: [123]
+     * });
+     *
+     * // Workflow with tasks
+     * const workflow = await client.workflows.create({
+     *   name: 'Data Pipeline',
+     *   goal: 'Process incoming data',
+     *   agentIds: [123],
+     *   tasks: [{ name: 'process', agentId: 123, description: 'Process data' }]
+     * });
+     * ```
+     */
+    create(config: WorkflowConfig): Promise<Workflow>;
+    /**
+     * Get a workflow by ID.
+     * @param params - Parameters object
+     * @param params.id - The workflow ID
+     * @returns The Workflow object with full data including triggers, tasks, and edges
+     */
+    get(params: {
+        id: number | string;
+    }): Promise<Workflow>;
+    /**
+     * List all workflows owned by the authenticated user.
+     * @returns Array of Workflow objects
+     */
+    list(): Promise<Workflow[]>;
+    /**
+     * Update workflow metadata.
+     * @param params - Parameters object
+     * @param params.id - The workflow ID to update
+     * @param params.name - New name (optional)
+     * @param params.goal - New goal (optional)
+     * @returns The updated Workflow object
+     */
+    update(params: {
+        id: number | string;
+        name?: string;
+        goal?: string;
+    }): Promise<Workflow>;
+    /**
+     * Delete a workflow.
+     * @param params - Parameters object
+     * @param params.id - The workflow ID to delete
+     */
+    delete(params: {
+        id: number | string;
+    }): Promise<void>;
+    /**
+     * Set a workflow to running state.
+     *
+     * This activates the workflow so it can process triggers and execute tasks.
+     *
+     * @param params - Parameters object
+     * @param params.id - The workflow ID
+     */
+    setRunning(params: {
+        id: number | string;
+    }): Promise<void>;
+    /**
+     * Connect edges in the workflow graph.
+     * @param params - Parameters object
+     * @param params.id - The workflow ID
+     * @param params.edges - Array of edges to add
+     */
+    connect(params: {
+        id: number | string;
+        edges: Edge[];
+    }): Promise<void>;
+    /**
+     * Sync workflow with declarative configuration.
+     *
+     * This allows updating triggers, tasks, and edges in a single call.
+     * Note: For creating triggers, prefer using the triggers API directly
+     * as the sync endpoint has known limitations.
+     *
+     * @param params - Parameters object
+     * @param params.id - The workflow ID
+     * @param params.triggers - Array of trigger definitions (optional)
+     * @param params.tasks - Array of task definitions (optional)
+     * @param params.edges - Array of edge definitions (optional)
+     */
+    sync(params: {
+        id: number | string;
+        triggers?: TriggerDefinition[];
+        tasks?: TaskDefinition[];
+        edges?: EdgeDefinition[];
+    }): Promise<void>;
+    private syncInternal;
+    private getIntegrationConnectionId;
+    private getTriggerName;
+    private resolveEdgeRef;
+    private resolveNodeId;
+}
+//# sourceMappingURL=workflows-api.d.ts.map

package/dist/workflows-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows-api.d.ts","sourceRoot":"","sources":["../src/workflows-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EACV,cAAc,EAEd,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,IAAI,EAGL,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,cAAc;IAE1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACG,MAAM,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,QAAQ,CAAC;IA4BvD;;;;;OAKG;IACG,GAAG,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;IA8C7D;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAWjC;;;;;;;OAOG;IACG,MAAM,CAAC,MAAM,EAAE;QACnB,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;QACpB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,GAAG,OAAO,CAAC,QAAQ,CAAC;IAWrB;;;;OAIG;IACG,MAAM,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI5D;;;;;;;OAOG;IACG,UAAU,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAMhE;;;;;OAKG;IACG,OAAO,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;QAAC,KAAK,EAAE,IAAI,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB5E;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,MAAM,EAAE;QACjB,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,iBAAiB,EAAE,CAAC;QAC/B,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;QACzB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;KAC1B,GAAG,OAAO,CAAC,IAAI,CAAC;YAWH,YAAY;IA8H1B,OAAO,CAAC,0BAA0B;IAWlC,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,aAAa;CAQtB"}

package/dist/workflows-api.js

@@ -0,0 +1,357 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkflowsAPI = void 0;
+const workflow_1 = require("./workflow");
+/**
+ * API for managing workflows on the OpenServ platform.
+ *
+ * @example
+ * ```typescript
+ * const client = new PlatformClient({ apiKey: 'your-key' });
+ *
+ * // Create a workflow
+ * const workflow = await client.workflows.create({
+ *   name: 'My Workflow',
+ *   goal: 'Process data automatically',
+ *   agentIds: [123, 456]
+ * });
+ *
+ * // List all workflows
+ * const workflows = await client.workflows.list();
+ *
+ * // Get a specific workflow
+ * const workflow = await client.workflows.get({ id: 789 });
+ * ```
+ */
+class WorkflowsAPI {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * Create a new workflow.
+     *
+     * Can create an empty workflow or a fully configured one with triggers, tasks, and edges.
+     *
+     * @param config - Workflow configuration
+     * @param config.name - Name of the workflow
+     * @param config.goal - Goal/description of what the workflow does
+     * @param config.agentIds - Array of agent IDs to include in the workflow
+     * @param config.triggers - Optional array of trigger definitions
+     * @param config.tasks - Optional array of task definitions
+     * @param config.edges - Optional array of edge definitions connecting nodes
+     * @returns The created Workflow object
+     *
+     * @example
+     * ```typescript
+     * // Simple workflow
+     * const workflow = await client.workflows.create({
+     *   name: 'Data Pipeline',
+     *   goal: 'Process incoming data',
+     *   agentIds: [123]
+     * });
+     *
+     * // Workflow with tasks
+     * const workflow = await client.workflows.create({
+     *   name: 'Data Pipeline',
+     *   goal: 'Process incoming data',
+     *   agentIds: [123],
+     *   tasks: [{ name: 'process', agentId: 123, description: 'Process data' }]
+     * });
+     * ```
+     */
+    async create(config) {
+        // Convert agentIds to the format expected by the API
+        const agents = config.agentIds.map((id) => ({
+            id: typeof id === "string" ? parseInt(id) : id,
+        }));
+        // First create the workspace
+        const data = await this.client.post("/workspaces?isBlank=true", {
+            name: config.name,
+            goal: config.goal,
+            agents,
+            type: "node-ui",
+        });
+        const workflowId = data.id;
+        // If declarative config provided, sync it
+        if (config.triggers || config.tasks || config.edges) {
+            await this.syncInternal(workflowId, config);
+        }
+        // Fetch and return the complete workflow
+        return this.get({ id: workflowId });
+    }
+    /**
+     * Get a workflow by ID.
+     * @param params - Parameters object
+     * @param params.id - The workflow ID
+     * @returns The Workflow object with full data including triggers, tasks, and edges
+     */
+    async get(params) {
+        const [workspace, tasks] = await Promise.all([
+            this.client.get(`/workspaces/${params.id}`),
+            this.client
+                .get(`/workspaces/${params.id}/tasks`)
+                .catch(() => []),
+        ]);
+        // Extract triggers from workspace response (includes token in attributes.uiState)
+        // The separate /triggers endpoint returns integration types, not actual triggers
+        const workspaceTriggers = (workspace.triggers || []).map((t) => ({
+            id: t.id,
+            name: t.name,
+            description: t.description || undefined,
+            token: t.attributes?.uiState?.token,
+            integrationConnectionId: t.integrationConnection?.id || "",
+            props: t.props || {},
+            isActive: t.is_active,
+            state: t.state,
+        }));
+        const workflowData = {
+            id: workspace.id,
+            name: workspace.name,
+            goal: workspace.goal,
+            status: workspace.executionState || "draft",
+            triggers: workspaceTriggers,
+            tasks: tasks || [],
+            edges: workspace.workflow?.edges || [],
+            agents: workspace.agents || [],
+        };
+        return new workflow_1.Workflow(workflowData, this.client);
+    }
+    /**
+     * List all workflows owned by the authenticated user.
+     * @returns Array of Workflow objects
+     */
+    async list() {
+        const workspaces = await this.client.get("/workspaces");
+        const workflows = [];
+        for (const ws of workspaces) {
+            workflows.push(await this.get({ id: ws.id }));
+        }
+        return workflows;
+    }
+    /**
+     * Update workflow metadata.
+     * @param params - Parameters object
+     * @param params.id - The workflow ID to update
+     * @param params.name - New name (optional)
+     * @param params.goal - New goal (optional)
+     * @returns The updated Workflow object
+     */
+    async update(params) {
+        const { id, name, goal } = params;
+        // Get current workflow to preserve required fields
+        const current = await this.get({ id });
+        await this.client.put(`/workspaces/${id}`, {
+            name: name ?? current.name,
+            goal: goal ?? current.goal,
+        });
+        return this.get({ id });
+    }
+    /**
+     * Delete a workflow.
+     * @param params - Parameters object
+     * @param params.id - The workflow ID to delete
+     */
+    async delete(params) {
+        await this.client.delete(`/workspaces/${params.id}`);
+    }
+    /**
+     * Set a workflow to running state.
+     *
+     * This activates the workflow so it can process triggers and execute tasks.
+     *
+     * @param params - Parameters object
+     * @param params.id - The workflow ID
+     */
+    async setRunning(params) {
+        await this.client.put(`/workspaces/${params.id}/execution-state`, {
+            executionState: "running",
+        });
+    }
+    /**
+     * Connect edges in the workflow graph.
+     * @param params - Parameters object
+     * @param params.id - The workflow ID
+     * @param params.edges - Array of edges to add
+     */
+    async connect(params) {
+        // Get current workflow to merge edges
+        const currentWorkflow = await this.client.get(`/workspaces/${params.id}`);
+        const nodes = currentWorkflow.workflow?.nodes || [];
+        const newEdges = params.edges.map((edge) => ({
+            source: this.resolveNodeId(edge.from),
+            target: this.resolveNodeId(edge.to),
+        }));
+        await this.client.put(`/workspaces/${params.id}/workflow`, {
+            workflow: {
+                nodes,
+                edges: [...(currentWorkflow.workflow?.edges || []), ...newEdges],
+            },
+        });
+    }
+    /**
+     * Sync workflow with declarative configuration.
+     *
+     * This allows updating triggers, tasks, and edges in a single call.
+     * Note: For creating triggers, prefer using the triggers API directly
+     * as the sync endpoint has known limitations.
+     *
+     * @param params - Parameters object
+     * @param params.id - The workflow ID
+     * @param params.triggers - Array of trigger definitions (optional)
+     * @param params.tasks - Array of task definitions (optional)
+     * @param params.edges - Array of edge definitions (optional)
+     */
+    async sync(params) {
+        await this.syncInternal(params.id, {
+            name: "",
+            goal: "",
+            agentIds: [],
+            triggers: params.triggers,
+            tasks: params.tasks,
+            edges: params.edges,
+        });
+    }
+    async syncInternal(workflowId, config) {
+        // Build the sync payload
+        const syncPayload = {};
+        // Get current workflow state for ID mapping
+        const currentTriggers = await this.client
+            .get(`/workspaces/${workflowId}/triggers`)
+            .catch(() => []);
+        const currentTasks = await this.client
+            .get(`/workspaces/${workflowId}/tasks`)
+            .catch(() => []);
+        // Map names to IDs for existing resources
+        const triggerNameToId = new Map();
+        const taskNameToId = new Map();
+        for (const t of currentTriggers || []) {
+            triggerNameToId.set(t.name || t.description, t.id);
+        }
+        for (const t of currentTasks || []) {
+            taskNameToId.set(t.name || t.description, t.id);
+        }
+        // Build triggers array with IDs
+        if (config.triggers) {
+            syncPayload.triggers = config.triggers.map((t) => ({
+                id: t.id || triggerNameToId.get(t.name) || `new-${t.name}`,
+                name: t.name,
+                description: t.name,
+                // Use integrationConnectionId if provided, otherwise fall back to type-based lookup
+                integrationConnectionId: t.integrationConnectionId || this.getIntegrationConnectionId(t.type),
+                // trigger_name is required by the sync endpoint
+                // Different triggers use different names: manual uses "on_event", webhook uses "on_request"
+                trigger_name: this.getTriggerName(t.type),
+                props: t.props || {},
+                attributes: {},
+            }));
+        }
+        // Build tasks array with IDs
+        if (config.tasks) {
+            syncPayload.tasks = config.tasks.map((t) => {
+                const existingId = t.id || taskNameToId.get(t.name);
+                return {
+                    id: existingId || 0, // 0 means create new
+                    description: t.description,
+                    body: t.body || t.description,
+                    input: t.input || "",
+                    assigneeAgentId: typeof t.agentId === "string" ? parseInt(t.agentId) : t.agentId,
+                    status: "to-do",
+                    metadata: null,
+                    attributes: { name: t.name },
+                    outputOptions: {
+                        default: {
+                            name: "Task Output",
+                            type: "text",
+                            instructions: "Complete the task and provide output",
+                        },
+                    },
+                };
+            });
+        }
+        // Build workflow graph (nodes + edges)
+        if (config.edges || config.triggers || config.tasks) {
+            const nodes = [];
+            const edges = [];
+            // Add trigger nodes
+            if (config.triggers) {
+                for (const t of config.triggers) {
+                    const triggerId = t.id || triggerNameToId.get(t.name) || `new-${t.name}`;
+                    nodes.push({
+                        id: `trigger-${t.name}`,
+                        type: "trigger",
+                        triggerId,
+                        position: { x: 0, y: 0 },
+                        inputPorts: [],
+                        outputPorts: [{ id: "output", name: "Output" }],
+                    });
+                }
+            }
+            // Add task nodes
+            if (config.tasks) {
+                for (const t of config.tasks) {
+                    const taskId = t.id || taskNameToId.get(t.name) || 0;
+                    nodes.push({
+                        id: `task-${t.name}`,
+                        type: "task",
+                        taskId,
+                        position: { x: 200, y: 0 },
+                        inputPorts: [{ id: "input", name: "Input" }],
+                        outputPorts: [{ id: "output", name: "Output" }],
+                    });
+                }
+            }
+            // Add edges with required fields
+            if (config.edges) {
+                config.edges.forEach((e, i) => {
+                    const sourceNode = this.resolveEdgeRef(e.from);
+                    const targetNode = this.resolveEdgeRef(e.to);
+                    edges.push({
+                        id: `edge-${i}`,
+                        source: sourceNode,
+                        target: targetNode,
+                        sourcePort: "output",
+                        targetPort: "input",
+                    });
+                });
+            }
+            syncPayload.workflow = { nodes, edges };
+        }
+        // Call the sync endpoint
+        await this.client.put(`/workspaces/${workflowId}/sync`, syncPayload);
+    }
+    getIntegrationConnectionId(type) {
+        if (!type)
+            return "";
+        const mapping = {
+            x402: "x402-trigger",
+            webhook: "webhook-trigger",
+            cron: "cron-trigger",
+            manual: "manual-trigger",
+        };
+        return mapping[type] || type;
+    }
+    getTriggerName(type) {
+        if (!type)
+            return "on_request";
+        const mapping = {
+            x402: "on_payment",
+            webhook: "on_request",
+            cron: "periodically",
+            manual: "on_event",
+        };
+        return mapping[type] || "on_request";
+    }
+    resolveEdgeRef(ref) {
+        // Convert 'trigger:name' or 'task:name' to node ID
+        const [type, name] = ref.split(":");
+        return `${type}-${name}`;
+    }
+    resolveNodeId(ref) {
+        if (typeof ref === "string") {
+            return this.resolveEdgeRef(ref);
+        }
+        return `${ref.type}-${ref.id}`;
+    }
+}
+exports.WorkflowsAPI = WorkflowsAPI;

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@openserv-labs/client",
+  "version": "1.0.0",
+  "description": "OpenServ Platform Client - Manage agents, workflows, tasks, and triggers via the OpenServ API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "check-types": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run lint && npm run check-types",
+    "prepare": "npm run build",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write \"**/*.{ts,json,md}\"",
+    "format:check": "prettier --check \"**/*.{ts,json,md}\"",
+    "test": "node --import tsx --test test/**/*.test.ts",
+    "test:unit": "node --import tsx --test test/unit/**/*.test.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openserv-labs/client.git"
+  },
+  "bugs": {
+    "url": "https://github.com/openserv-labs/client/issues"
+  },
+  "homepage": "https://github.com/openserv-labs/client#readme",
+  "keywords": [
+    "openserv",
+    "api",
+    "client",
+    "platform",
+    "workflows",
+    "agents",
+    "typescript"
+  ],
+  "author": "OpenServ Labs",
+  "license": "MIT",
+  "dependencies": {
+    "axios": "^1.6.8",
+    "ethers": "^6.16.0",
+    "viem": "^2.45.1",
+    "x402-fetch": "^1.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@tsconfig/strictest": "^2.0.3",
+    "@types/node": "^22.10.2",
+    "dotenv": "^16.4.5",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "prettier": "^3.2.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.4.2",
+    "typescript-eslint": "^8.33.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}