@q1k-oss/btree-workflows 0.0.1

package/src/actions/http-request.ts

@@ -0,0 +1,228 @@
+/**
+ * HttpRequest Node
+ *
+ * Makes HTTP requests via a Temporal activity.
+ * This node requires the `fetchUrl` activity to be configured in the context -
+ * it does not support standalone/inline execution because HTTP I/O requires
+ * capabilities outside the workflow sandbox.
+ *
+ * Features:
+ * - Support for GET, POST, PUT, DELETE, PATCH methods
+ * - Variable resolution in URL, headers, and body
+ * - Configurable response parsing (JSON/text/binary)
+ * - Retry with exponential backoff support
+ * - Timeout configuration
+ * - Result stored in blackboard
+ */
+
+import { ActionNode } from "../base-node.js";
+import { ConfigurationError } from "../errors.js";
+import {
+  type TemporalContext,
+  type NodeConfiguration,
+  type HttpRequestActivity,
+  NodeStatus,
+} from "../types.js";
+import { resolveValue, type VariableContext } from "../utilities/variable-resolver.js";
+
+/**
+ * Configuration for HttpRequest node
+ */
+export interface HttpRequestConfig extends NodeConfiguration {
+  /** URL to request (supports ${input.x}, ${bb.x}) */
+  url: string;
+  /** HTTP method (default: GET) */
+  method?: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+  /** Request headers (supports variable resolution) */
+  headers?: Record<string, string>;
+  /** Request body (supports variable resolution) */
+  body?: unknown;
+  /** Expected response type for parsing */
+  responseType?: "json" | "text" | "binary";
+  /** Request timeout in milliseconds */
+  timeout?: number;
+  /** Retry configuration */
+  retry?: {
+    maxAttempts: number;
+    backoffMs: number;
+  };
+  /** Output key on blackboard for response */
+  outputKey: string;
+}
+
+/**
+ * HttpRequest Node
+ *
+ * Makes HTTP requests via a Temporal activity and stores the response in blackboard.
+ * Requires the `fetchUrl` activity to be configured.
+ *
+ * @example YAML
+ * ```yaml
+ * type: HttpRequest
+ * id: fetch-user
+ * props:
+ *   url: "https://api.example.com/users/${input.userId}"
+ *   method: GET
+ *   headers:
+ *     Authorization: "Bearer ${bb.accessToken}"
+ *   timeout: 5000
+ *   responseType: json
+ *   outputKey: "userData"
+ * ```
+ *
+ * @example YAML with POST
+ * ```yaml
+ * type: HttpRequest
+ * id: create-order
+ * props:
+ *   url: "https://api.example.com/orders"
+ *   method: POST
+ *   headers:
+ *     Content-Type: "application/json"
+ *     Authorization: "Bearer ${bb.token}"
+ *   body:
+ *     customerId: "${input.customerId}"
+ *     items: "${bb.cartItems}"
+ *   timeout: 10000
+ *   retry:
+ *     maxAttempts: 3
+ *     backoffMs: 1000
+ *   outputKey: "orderResponse"
+ * ```
+ */
+export class HttpRequest extends ActionNode {
+  private url: string;
+  private method: HttpRequestConfig["method"];
+  private headers?: Record<string, string>;
+  private body?: unknown;
+  private responseType: HttpRequestConfig["responseType"];
+  private timeout?: number;
+  private retry?: HttpRequestConfig["retry"];
+  private outputKey: string;
+
+  constructor(config: HttpRequestConfig) {
+    super(config);
+
+    if (!config.url) {
+      throw new ConfigurationError("HttpRequest requires url");
+    }
+
+    if (!config.outputKey) {
+      throw new ConfigurationError("HttpRequest requires outputKey");
+    }
+
+    this.url = config.url;
+    this.method = config.method || "GET";
+    this.headers = config.headers;
+    this.body = config.body;
+    this.responseType = config.responseType || "json";
+    this.timeout = config.timeout;
+    this.retry = config.retry;
+    this.outputKey = config.outputKey;
+  }
+
+  protected async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    // Validate activity is available
+    if (!context.activities?.fetchUrl) {
+      this._lastError =
+        "HttpRequest requires activities.fetchUrl to be configured. " +
+        "This activity handles HTTP I/O outside the workflow sandbox.";
+      this.log(`Error: ${this._lastError}`);
+      return NodeStatus.FAILURE;
+    }
+
+    try {
+      const varCtx: VariableContext = {
+        blackboard: context.blackboard,
+        input: context.input,
+        testData: context.testData,
+      };
+
+      // Resolve variables in URL, headers, and body
+      const resolvedUrl = resolveValue(this.url, varCtx) as string;
+      const resolvedHeaders = this.headers
+        ? (resolveValue(this.headers, varCtx) as Record<string, string>)
+        : undefined;
+      const resolvedBody = this.body !== undefined
+        ? resolveValue(this.body, varCtx)
+        : undefined;
+
+      const request: HttpRequestActivity = {
+        url: resolvedUrl,
+        method: this.method || "GET",
+        headers: resolvedHeaders,
+        body: resolvedBody,
+        timeout: this.timeout,
+      };
+
+      this.log(`HTTP ${request.method} ${resolvedUrl}`);
+
+      // Execute with retry logic if configured
+      let response;
+      let lastError: Error | undefined;
+      const maxAttempts = this.retry?.maxAttempts || 1;
+      const backoffMs = this.retry?.backoffMs || 1000;
+
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+          response = await context.activities.fetchUrl(request);
+          lastError = undefined;
+          break;
+        } catch (error) {
+          lastError = error instanceof Error ? error : new Error(String(error));
+          if (attempt < maxAttempts) {
+            const delay = backoffMs * Math.pow(2, attempt - 1);
+            this.log(`Request failed, retrying in ${delay}ms (attempt ${attempt}/${maxAttempts})`);
+            await this.sleep(delay);
+          }
+        }
+      }
+
+      if (lastError) {
+        throw lastError;
+      }
+
+      if (!response) {
+        throw new Error("No response received");
+      }
+
+      // Parse response based on responseType
+      let parsedData = response.data;
+      if (this.responseType === "json" && typeof response.data === "string") {
+        try {
+          parsedData = JSON.parse(response.data);
+        } catch {
+          // Keep as string if parsing fails
+          this.log("Response is not valid JSON, keeping as string");
+        }
+      }
+
+      // Store response in blackboard
+      context.blackboard.set(this.outputKey, {
+        status: response.status,
+        headers: response.headers,
+        data: parsedData,
+      });
+
+      this.log(
+        `HTTP ${request.method} ${resolvedUrl} -> ${response.status}`
+      );
+
+      // Consider 2xx status codes as success
+      return response.status >= 200 && response.status < 300
+        ? NodeStatus.SUCCESS
+        : NodeStatus.FAILURE;
+    } catch (error) {
+      this._lastError = error instanceof Error ? error.message : String(error);
+      this.log(`HTTP request failed: ${this._lastError}`);
+      return NodeStatus.FAILURE;
+    }
+  }
+
+  /**
+   * Sleep for the specified duration
+   */
+  private sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}

package/src/actions/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Activity-based Action Nodes
+ *
+ * These nodes require Temporal activities to be provided via context.activities.
+ * They do not support standalone/inline execution because they need capabilities
+ * outside the workflow sandbox (Python execution, file I/O, HTTP requests).
+ */
+
+// PythonScript node
+export { PythonScript, type PythonScriptConfig } from "./python-script.js";
+
+// File parsing and generation nodes
+export { ParseFile, type ParseFileConfig } from "./parse-file.js";
+export { GenerateFile, type GenerateFileConfig } from "./generate-file.js";
+
+// HTTP request node
+export { HttpRequest, type HttpRequestConfig } from "./http-request.js";
+
+// CodeExecution node (Microsandbox-based)
+export { CodeExecution, type CodeExecutionConfig } from "./code-execution.js";

package/src/actions/parse-file.test.ts

@@ -0,0 +1,448 @@
+/**
+ * ParseFile Node Tests
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { ScopedBlackboard } from "../blackboard.js";
+import { Registry } from "../registry.js";
+import { type TemporalContext, type BtreeActivities, NodeStatus } from "../types.js";
+import { ParseFile, type ParseFileConfig } from "./parse-file.js";
+
+describe("ParseFile Node", () => {
+  let blackboard: ScopedBlackboard;
+  let registry: Registry;
+
+  beforeEach(() => {
+    blackboard = new ScopedBlackboard();
+    registry = new Registry();
+    vi.clearAllMocks();
+  });
+
+  describe("Construction and validation", () => {
+    it("should create node with valid config", () => {
+      const node = new ParseFile({
+        id: "test",
+        file: "/path/to/file.csv",
+        outputKey: "parsedData",
+      });
+
+      expect(node).toBeDefined();
+      expect(node.id).toBe("test");
+    });
+
+    it("should require file", () => {
+      expect(() => {
+        new ParseFile({
+          id: "test",
+          outputKey: "data",
+        } as ParseFileConfig);
+      }).toThrow(/requires file/i);
+    });
+
+    it("should require outputKey", () => {
+      expect(() => {
+        new ParseFile({
+          id: "test",
+          file: "/path/to/file.csv",
+        } as ParseFileConfig);
+      }).toThrow(/requires outputKey/i);
+    });
+
+    it("should accept optional format, sheetName, and options", () => {
+      const node = new ParseFile({
+        id: "test",
+        file: "/path/to/file.xlsx",
+        format: "xlsx",
+        sheetName: "Orders",
+        outputKey: "data",
+        options: {
+          skipRows: 1,
+          trim: true,
+        },
+      });
+
+      expect(node).toBeDefined();
+    });
+  });
+
+  describe("Activity requirement", () => {
+    it("should fail without parseFile activity", async () => {
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: undefined,
+      };
+
+      const node = new ParseFile({
+        id: "test",
+        file: "/data/orders.csv",
+        outputKey: "orders",
+      });
+
+      const status = await node.tick(context);
+
+      expect(status).toBe(NodeStatus.FAILURE);
+      expect(node.lastError).toContain("requires activities.parseFile");
+    });
+
+    it("should fail when activities object exists but parseFile is missing", async () => {
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          // parseFile is not provided
+        } as BtreeActivities,
+      };
+
+      const node = new ParseFile({
+        id: "test",
+        file: "/data/orders.csv",
+        outputKey: "orders",
+      });
+
+      const status = await node.tick(context);
+
+      expect(status).toBe(NodeStatus.FAILURE);
+      expect(node.lastError).toContain("requires activities.parseFile");
+    });
+  });
+
+  describe("Execution with activity", () => {
+    it("should parse CSV file via activity", async () => {
+      const mockParseActivity = vi.fn().mockResolvedValue({
+        data: [
+          { orderId: "1", product: "Widget", quantity: 5 },
+          { orderId: "2", product: "Gadget", quantity: 3 },
+        ],
+        rowCount: 2,
+        columns: ["orderId", "product", "quantity"],
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          parseFile: mockParseActivity,
+        },
+      };
+
+      const node = new ParseFile({
+        id: "test",
+        file: "/data/orders.csv",
+        format: "csv",
+        outputKey: "orders",
+      });
+
+      const status = await node.tick(context);
+
+      expect(status).toBe(NodeStatus.SUCCESS);
+      expect(mockParseActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          file: "/data/orders.csv",
+          format: "csv",
+        })
+      );
+    });
+
+    it("should store parsed data in blackboard", async () => {
+      const parsedData = [
+        { id: "1", name: "Alice" },
+        { id: "2", name: "Bob" },
+      ];
+
+      const mockParseActivity = vi.fn().mockResolvedValue({
+        data: parsedData,
+        rowCount: 2,
+        columns: ["id", "name"],
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          parseFile: mockParseActivity,
+        },
+      };
+
+      const node = new ParseFile({
+        id: "test",
+        file: "/data/users.csv",
+        outputKey: "users",
+      });
+
+      await node.tick(context);
+
+      expect(blackboard.get("users")).toEqual(parsedData);
+    });
+
+    it("should resolve file path from input", async () => {
+      const mockParseActivity = vi.fn().mockResolvedValue({
+        data: [],
+        rowCount: 0,
+        columns: [],
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        input: { dataFile: "/uploads/report-2024.csv" },
+        activities: {
+          executePieceAction: vi.fn(),
+          parseFile: mockParseActivity,
+        },
+      };
+
+      const node = new ParseFile({
+        id: "test",
+        file: "${input.dataFile}",
+        outputKey: "report",
+      });
+
+      await node.tick(context);
+
+      expect(mockParseActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          file: "/uploads/report-2024.csv",
+        })
+      );
+    });
+
+    it("should resolve file path from blackboard", async () => {
+      blackboard.set("uploadedFile", "/tmp/data.xlsx");
+
+      const mockParseActivity = vi.fn().mockResolvedValue({
+        data: [],
+        rowCount: 0,
+        columns: [],
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          parseFile: mockParseActivity,
+        },
+      };
+
+      const node = new ParseFile({
+        id: "test",
+        file: "${bb.uploadedFile}",
+        outputKey: "data",
+      });
+
+      await node.tick(context);
+
+      expect(mockParseActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          file: "/tmp/data.xlsx",
+        })
+      );
+    });
+
+    it("should pass column mapping to activity", async () => {
+      const mockParseActivity = vi.fn().mockResolvedValue({
+        data: [],
+        rowCount: 0,
+        columns: [],
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          parseFile: mockParseActivity,
+        },
+      };
+
+      const node = new ParseFile({
+        id: "test",
+        file: "/data/orders.csv",
+        outputKey: "orders",
+        columnMapping: {
+          "Order ID": "orderId",
+          "Customer Name": "customerName",
+          "Total Amount": "amount",
+        },
+      });
+
+      await node.tick(context);
+
+      expect(mockParseActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          columnMapping: {
+            "Order ID": "orderId",
+            "Customer Name": "customerName",
+            "Total Amount": "amount",
+          },
+        })
+      );
+    });
+
+    it("should pass parse options to activity", async () => {
+      const mockParseActivity = vi.fn().mockResolvedValue({
+        data: [],
+        rowCount: 0,
+        columns: [],
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          parseFile: mockParseActivity,
+        },
+      };
+
+      const node = new ParseFile({
+        id: "test",
+        file: "/data/orders.csv",
+        outputKey: "orders",
+        options: {
+          skipRows: 2,
+          trim: true,
+          emptyAsNull: true,
+          dateColumns: ["orderDate", "shipDate"],
+          dateFormat: "YYYY-MM-DD",
+        },
+      });
+
+      await node.tick(context);
+
+      expect(mockParseActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          options: {
+            skipRows: 2,
+            trim: true,
+            emptyAsNull: true,
+            dateColumns: ["orderDate", "shipDate"],
+            dateFormat: "YYYY-MM-DD",
+          },
+        })
+      );
+    });
+
+    it("should pass sheet name for Excel files", async () => {
+      const mockParseActivity = vi.fn().mockResolvedValue({
+        data: [],
+        rowCount: 0,
+        columns: [],
+      });
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          parseFile: mockParseActivity,
+        },
+      };
+
+      const node = new ParseFile({
+        id: "test",
+        file: "/data/report.xlsx",
+        format: "xlsx",
+        sheetName: "Q4 Sales",
+        outputKey: "sales",
+      });
+
+      await node.tick(context);
+
+      expect(mockParseActivity).toHaveBeenCalledWith(
+        expect.objectContaining({
+          format: "xlsx",
+          sheetName: "Q4 Sales",
+        })
+      );
+    });
+
+    it("should handle activity errors", async () => {
+      const mockParseActivity = vi.fn().mockRejectedValue(
+        new Error("File not found: /data/missing.csv")
+      );
+
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        activities: {
+          executePieceAction: vi.fn(),
+          parseFile: mockParseActivity,
+        },
+      };
+
+      const node = new ParseFile({
+        id: "test",
+        file: "/data/missing.csv",
+        outputKey: "data",
+      });
+
+      const status = await node.tick(context);
+
+      expect(status).toBe(NodeStatus.FAILURE);
+      expect(node.lastError).toContain("File not found");
+    });
+  });
+
+  describe("Node lifecycle", () => {
+    it("should clone correctly", () => {
+      const node = new ParseFile({
+        id: "original",
+        file: "/data/file.csv",
+        format: "csv",
+        outputKey: "data",
+      });
+
+      const cloned = node.clone() as ParseFile;
+
+      expect(cloned.id).toBe("original");
+    });
+
+    it("should reset status correctly", async () => {
+      const context: TemporalContext = {
+        blackboard,
+        treeRegistry: registry,
+        timestamp: Date.now(),
+        deltaTime: 0,
+        // No activities - will fail
+      };
+
+      const node = new ParseFile({
+        id: "test",
+        file: "/data/file.csv",
+        outputKey: "data",
+      });
+
+      await node.tick(context);
+      expect(node.status()).toBe(NodeStatus.FAILURE);
+
+      node.reset();
+      expect(node.status()).toBe(NodeStatus.IDLE);
+      expect(node.lastError).toBeUndefined();
+    });
+  });
+});