@graph-compose/client 1.0.0

package/dist/core/builder.d.ts

@@ -0,0 +1,313 @@
+import { Node, ToolNode, WorkflowConfig, WorkflowGraph } from "@graph-compose/core";
+import { ApiResponse, ValidationResult as ClientValidationResult, ExecuteOptions, GetWorkflowResponse, TerminateWorkflowResponse, WorkflowResponse } from "../types";
+import { NodeBuilder } from "./node-builder";
+import { ToolBuilder } from "./tool-builder";
+interface ApiValidationError {
+    name: string;
+    message: string;
+}
+interface ApiValidationResult {
+    isValid: boolean;
+    errors: ApiValidationError[];
+}
+export interface GraphComposeOptions {
+    /** API token for authentication. Can also be set via GRAPH_COMPOSE_TOKEN environment variable */
+    token?: string;
+}
+/**
+ * GraphCompose is the main builder class for creating workflow graphs.
+ * It provides a fluent API for building and executing workflows composed of HTTP nodes, agents, and error boundaries.
+ * You configure each node or tool using chained methods and **must** call `.end()` to finalize its definition.
+ *
+ * @example
+ * ```typescript
+ * const graph = new GraphCompose({ token: "your-token" });
+ *
+ * // Create and finalize a simple HTTP node
+ * graph.node("fetch_data")
+ *   .get("https://api.example.com/data")
+ *   .withHeaders({ "Authorization": "Bearer token" })
+ *   .end(); // Required!
+ *
+ * // Define and end a tool (example)
+ * graph.tool("analyze")
+ *   .post("https://api.example.com/analyze")
+ *   .end();
+ *
+ * // Create and finalize an agent node that uses the tool
+ * graph.agent("process_data")
+ *   .withMaxIterations(5)
+ *   .withTools(["analyze"])
+ *   .post("https://api.example.com/agent")
+ *   .withDependencies(["fetch_data"])
+ *   .end(); // Required!
+ *
+ * // Validate the complete workflow (requires all nodes/tools ended)
+ * const validationResult = graph.validate();
+ * if (!validationResult.isValid) { console.error("Validation failed:", validationResult.errors); }
+ *
+ * // Execute the workflow (requires all nodes/tools ended)
+ * try {
+ *   const result = await graph.execute({});
+ *   console.log("Execution started:", result);
+ * } catch (error) { console.error("Execution failed:", error); }
+ *
+ * // Get the raw workflow definition (requires all nodes/tools ended)
+ * const definition = graph.toJSON();
+ * console.log("Workflow JSON:", JSON.stringify(definition, null, 2));
+ *
+ * // Interact with existing workflows via API
+ * // const statusResult = await graph.getWorkflowStatus('some-workflow-id');
+ * // const terminateResult = await graph.terminateWorkflow('some-workflow-id');
+ * ```
+ */
+export declare class GraphCompose {
+    private nodes;
+    private _tools;
+    private currentNodeBuilder?;
+    private currentToolBuilder?;
+    private webhookUrl?;
+    private context?;
+    private workflowConfig?;
+    private token;
+    private baseUrl;
+    /**
+     * Creates a new GraphCompose instance.
+     *
+     * @param options Configuration options for the graph builder
+     * @throws {Error} If no API token is provided via options or environment variable
+     */
+    constructor(options?: GraphComposeOptions);
+    /** Internal method for ToolBuilder to add its definition */
+    _addToolDefinition(tool: ToolNode): void;
+    /** Internal method for NodeBuilder to add its definition */
+    _addNodeDefinition(node: Node): void;
+    /**
+     * Checks if there's an unfinalized builder and throws an error.
+     * Call this before operations that require a complete workflow definition.
+     */
+    private ensureBuildersFinalized;
+    /**
+     * Start building a new HTTP node.
+     * HTTP nodes are the basic building blocks of workflows, used to make HTTP requests.
+     * **Note:** You must call `.end()` on the returned `NodeBuilder` before starting another node or finishing the graph.
+     *
+     * @param id Unique identifier for the node (must be alphanumeric with underscores)
+     * @returns NodeBuilder instance for method chaining
+     * @throws {Error} If another node or tool is currently being built.
+     * @example
+     * ```typescript
+     * graph.node("fetch_data")
+     *   .get("https://api.example.com/data")
+     *   .withHeaders({ "Authorization": "Bearer token" })
+     *   .end(); // Required!
+     * ```
+     */
+    node(id: string): NodeBuilder;
+    /**
+     * Start building a new error boundary node.
+     * Error boundaries catch and handle errors from their protected nodes.
+     * **Note:** You must call `.end()` on the returned `NodeBuilder` before starting another node or finishing the graph.
+     *
+     * @param id Unique identifier for the node (must be alphanumeric with underscores)
+     * @param protectedNodes Array of node IDs that this error boundary protects
+     * @returns NodeBuilder instance for method chaining
+     * @throws {Error} If another node or tool is currently being built.
+     * @example
+     * ```typescript
+     * graph.errorBoundary("data_error_handler", ["fetch_data"])
+     *   .post("https://api.example.com/error-handler")
+     *   .withBody(({ context, results }) => ({
+     *     error: results.error,
+     *     nodeId: results.nodeId
+     *   }))
+     *   .end(); // Required!
+     * ```
+     */
+    errorBoundary(id: string, protectedNodes: string[]): NodeBuilder;
+    /**
+     * Start building a new agent node.
+     * Agent nodes are special nodes that can execute multiple iterations and use tools.
+     * **Note:** You must call `.end()` on the returned `NodeBuilder` before starting another node or finishing the graph.
+     *
+     * @param id Unique identifier for the node (must be alphanumeric with underscores)
+     * @returns NodeBuilder instance for method chaining
+     * @throws {Error} If another node or tool is currently being built.
+     * @example
+     * ```typescript
+     * graph.agent("research_agent")
+     *   .withMaxIterations(10)
+     *   .withTools(["search", "analyze"])
+     *   .post("https://api.example.com/agent")
+     *   .end(); // Required!
+     * ```
+     */
+    agent(id: string): NodeBuilder;
+    /**
+     * Start building a new tool definition.
+     * Tools are reusable components (HTTP calls or sub-graphs) usable by agent nodes.
+     * **Note:** You must call `.end()` on the returned `ToolBuilder` before starting another tool/node or finishing the graph.
+     *
+     * @param id Unique identifier for the tool (must be alphanumeric with underscores)
+     * @returns ToolBuilder instance for method chaining
+     * @throws {Error} If another node or tool is currently being built.
+     * @example
+     * ```typescript
+     * graph.tool("search")
+     *   .get("https://api.search.com")
+     *   .withHeaders({ "Authorization": "Bearer token" })
+     *   .end(); // Required!
+     * ```
+     */
+    tool(id: string): ToolBuilder;
+    /**
+     * Add a pre-configured node to the workflow.
+     * Ensures no other builder is active before adding.
+     *
+     * @param node The node configuration to add
+     * @returns this GraphCompose instance for method chaining
+     * @throws {Error} If another node or tool is currently being built.
+     */
+    addNode(node: Node): GraphCompose;
+    /**
+     * Add a pre-configured tool definition to the workflow.
+     * Ensures no other builder is active before adding.
+     *
+     * @param tool The tool configuration to add
+     * @returns this GraphCompose instance for method chaining
+     * @throws {Error} If another node or tool is currently being built.
+     */
+    addTool(tool: ToolNode): GraphCompose;
+    /**
+     * Get the complete workflow definition object.
+     * This includes all nodes, tools, webhook URL, context, and workflow configuration.
+     * **Note:** Requires all active builders to be finalized using `.end()`.
+     *
+     * @returns The complete workflow graph definition object.
+     * @throws {Error} If a node or tool is currently being built (missing `.end()`).
+     */
+    getWorkflow(): WorkflowGraph;
+    /**
+     * Returns the complete workflow definition as a plain JavaScript object.
+     * This is the raw representation suitable for serialization (e.g., to JSON).
+     * **Note:** Requires all active builders to be finalized using `.end()`.
+     *
+     * @returns The complete workflow graph definition object.
+     * @throws {Error} If a node or tool is currently being built (missing `.end()`).
+     * @alias getWorkflow
+     */
+    toJSON(): WorkflowGraph;
+    /**
+     * Validate the current workflow locally.
+     * Checks for:
+     * - Valid node IDs
+     * - Valid URLs
+     * - Valid dependencies
+     * - Valid tool configurations
+     * - No circular dependencies
+     * - Agent-specific requirements (e.g., `max_iterations` presence and value)
+     *
+     * Note: This performs client-side validation only. Use `validateApi()` for server-side checks including tier limits.
+     *
+     * @returns Validation result indicating if the workflow is valid and any errors.
+     * @throws {Error} If a node or tool is currently being built (missing `.end()`).
+     */
+    validate(): ClientValidationResult;
+    /**
+     * Validates the current workflow definition against the API endpoint.
+     * Performs server-side checks including tier limits.
+     * **Note:** Requires all active builders to be finalized using `.end()`.
+     *
+     * @returns {Promise<ApiResponse<ApiValidationResult | null>>} The validation result from the API, wrapped in an ApiResponse.
+     * @throws {Error} If the API call fails or returns an unexpected format.
+     */
+    validateApi(): Promise<ApiResponse<ApiValidationResult | null>>;
+    /**
+     * Retrieves the details and status of a specific workflow instance by its ID.
+     *
+     * @param workflowId The unique identifier of the workflow instance.
+     * @returns Promise resolving to the full API response containing the workflow details.
+     * @throws {Error} If the API request fails (e.g., 404 Not Found).
+     */
+    getWorkflowStatus(workflowId: string): Promise<ApiResponse<GetWorkflowResponse | null>>;
+    /**
+     * Requests the termination of a running workflow instance.
+     *
+     * @param workflowId The unique identifier of the workflow instance to terminate.
+     * @param options Optional parameters including the specific run ID and a reason for termination.
+     * @returns Promise resolving to the full API response confirming the termination request.
+     * @throws {Error} If the API request fails.
+     */
+    terminateWorkflow(workflowId: string, options?: {
+        runId?: string;
+        reason?: string;
+    }): Promise<ApiResponse<TerminateWorkflowResponse | null>>;
+    /**
+     * Set the execution context for the workflow.
+     * The context is available to all nodes via JSONata expressions.
+     * **Note:** Requires all active builders to be finalized using `.end()`.
+     *
+     * @param context Key-value pairs that will be available to nodes
+     * @returns this GraphCompose instance for method chaining
+     * @throws {Error} If a node or tool is currently being built.
+     * @example
+     * ```typescript
+     * graph.withContext({
+     *   api_key: process.env.API_KEY,
+     *   user_id: "123",
+     * });
+     * ```
+     */
+    withContext(context: Record<string, any>): GraphCompose;
+    /**
+     * Execute the workflow asynchronously without waiting for completion.
+     * **Note:** Requires all active builders to be finalized using `.end()`.
+     *
+     * @param options Execution options including webhook URL and context
+     * @returns Promise resolving to the full API response containing the initial workflow details (like workflow ID and run ID). The status will likely be RUNNING.
+     * @throws {Error} If a node or tool is currently being built.
+     * @throws {Error} If validation fails or if the execution fails
+     * @example
+     * ```typescript
+     * const apiResponse = await graph.execute({ ... });
+     * if (apiResponse.success && apiResponse.data) {
+     *   console.log("Workflow started:", apiResponse.data.workflowId);
+     *   // apiResponse.data will contain workflowId, runId, etc.
+     * }
+     * ```
+     */
+    execute(options?: Omit<ExecuteOptions, "token" | "baseUrl">): Promise<ApiResponse<WorkflowResponse | null>>;
+    /**
+     * Execute the workflow synchronously and wait for completion.
+     * **Note:** Requires all active builders to be finalized using `.end()`.
+     *
+     * @param options Execution options including webhook URL and context
+     * @returns Promise resolving to the full API response containing the final workflow details (status, results, error) upon completion or failure.
+     * @throws {Error} If a node or tool is currently being built (missing `.end()`).
+     */
+    executeSync(options?: Omit<ExecuteOptions, "token" | "baseUrl">): Promise<ApiResponse<WorkflowResponse | null>>;
+    /**
+     * Set the webhook URL for workflow notifications.
+     * **Note:** Requires all active builders to be finalized using `.end()`.
+     *
+     * @param url The URL that will receive webhook notifications
+     * @returns this GraphCompose instance for method chaining
+     * @throws {Error} If a node or tool is currently being built.
+     */
+    withWebhookUrl(url: string): GraphCompose;
+    /**
+     * Sets the workflow-level configuration.
+     * **Note:** Requires all active builders to be finalized using `.end()`.
+     *
+     * @param config The workflow configuration object
+     * @returns this GraphCompose instance for method chaining
+     * @throws {Error} If a node or tool is currently being built.
+     * @example
+     * ```typescript
+     * graph.withWorkflowConfig({ workflowExecutionTimeout: '5 minutes' });
+     * ```
+     */
+    withWorkflowConfig(config: WorkflowConfig): GraphCompose;
+}
+export {};
+//# sourceMappingURL=builder.d.ts.map

package/dist/core/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/core/builder.ts"],"names":[],"mappings":"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"}