@q1k-oss/btree-workflows 0.0.1

package/src/integrations/integration-action.ts

@@ -0,0 +1,233 @@
+/**
+ * Integration Action Node
+ * Execute third-party service actions via Active Pieces packages
+ *
+ * Features:
+ * - Variable resolution: ${input.key}, ${bb.key}, ${env.KEY}, ${param.key}
+ * - Pluggable token provider for OAuth/API key authentication
+ * - Dynamic Active Pieces action execution
+ * - Result storage in blackboard
+ */
+
+import { ActionNode } from "../base-node.js";
+import { ConfigurationError } from "../errors.js";
+import {
+  type TemporalContext,
+  type NodeConfiguration,
+  type PieceActivityRequest,
+  type PieceAuth,
+  type TokenProvider,
+  NodeStatus,
+} from "../types.js";
+import { executePieceAction } from "./piece-executor.js";
+import { resolveValue, type VariableContext } from "../utilities/variable-resolver.js";
+
+// Re-export TokenProvider for backward compatibility
+export type { TokenProvider } from "../types.js";
+
+/**
+ * Configuration for IntegrationAction node
+ */
+export interface IntegrationActionConfig extends NodeConfiguration {
+  /** Provider name: 'google-sheets', 'slack', 'openai', etc. */
+  provider: string;
+  /** Action name from Active Pieces: 'append_row', 'send_message', etc. */
+  action: string;
+  /** Action inputs (supports ${input.key}, ${bb.key}, ${env.KEY}, ${param.key}) */
+  inputs?: Record<string, unknown>;
+  /** Connection ID to use (optional, defaults to user's primary connection) */
+  connectionId?: string;
+  /** Whether to store the result in blackboard (default: true) */
+  storeResult?: boolean;
+  /** Custom blackboard key for result (default: ${nodeId}.result) */
+  resultKey?: string;
+}
+
+/**
+ * Extended context with token provider
+ */
+export interface IntegrationContext extends TemporalContext {
+  /** Token provider function for fetching OAuth tokens */
+  tokenProvider?: TokenProvider;
+  /** Tenant ID for multi-tenant token lookup */
+  tenantId?: string;
+  /** User ID for user-scoped token lookup */
+  userId?: string;
+}
+
+/**
+ * Integration Action Node
+ *
+ * Executes actions on third-party services using Active Pieces packages.
+ * Requires a token provider to be set in context for authentication.
+ *
+ * Supports variable resolution:
+ * - ${input.key} - Workflow input parameters
+ * - ${bb.key} - Blackboard values
+ * - ${env.KEY} - Environment variables
+ * - ${param.key} - Test data parameters
+ *
+ * @example
+ * ```yaml
+ * type: IntegrationAction
+ * id: add-to-sheet
+ * props:
+ *   provider: google-sheets
+ *   action: append_row
+ *   inputs:
+ *     spreadsheetId: "${input.spreadsheetId}"
+ *     sheetName: "Orders"
+ *     values:
+ *       - "${input.orderId}"
+ *       - "${bb.customerName}"
+ *       - "${bb.total}"
+ * ```
+ */
+export class IntegrationAction extends ActionNode {
+  private provider: string;
+  private action: string;
+  private inputs: Record<string, unknown>;
+  private connectionId?: string;
+  private storeResult: boolean;
+  private resultKey: string;
+
+  constructor(config: IntegrationActionConfig) {
+    super(config);
+
+    if (!config.provider) {
+      throw new ConfigurationError("IntegrationAction requires provider");
+    }
+
+    if (!config.action) {
+      throw new ConfigurationError("IntegrationAction requires action");
+    }
+
+    this.provider = config.provider;
+    this.action = config.action;
+    this.inputs = config.inputs || {};
+    this.connectionId = config.connectionId;
+    this.storeResult = config.storeResult !== false; // Default true
+    this.resultKey = config.resultKey || `${this.id}.result`;
+  }
+
+  protected async executeTick(context: TemporalContext): Promise<NodeStatus> {
+    const integrationContext = context as IntegrationContext;
+
+    // Validate token provider is available
+    if (!integrationContext.tokenProvider) {
+      this._lastError =
+        "No token provider configured in context. " +
+        "Set context.tokenProvider to fetch OAuth tokens.";
+      this.log(`Error: ${this._lastError}`);
+      return NodeStatus.FAILURE;
+    }
+
+    try {
+      // 1. Resolve inputs from blackboard
+      const resolvedInputs = this.resolveInputs(context);
+      this.log(`Resolved inputs: ${JSON.stringify(resolvedInputs)}`);
+
+      // 2. Get authentication via token provider
+      const auth = await integrationContext.tokenProvider(
+        context,
+        this.provider,
+        this.connectionId
+      );
+      this.log(`Got authentication for provider: ${this.provider}`);
+
+      // 3. Execute via activity (if available) or inline (standalone mode)
+      const result = await this.executeAction(context, resolvedInputs, auth);
+
+      // 4. Store result in blackboard if enabled
+      if (this.storeResult) {
+        context.blackboard.set(this.resultKey, result);
+        this.log(`Stored result in blackboard: ${this.resultKey}`);
+      }
+
+      this.log(
+        `Integration action completed: ${this.provider}/${this.action}`
+      );
+      return NodeStatus.SUCCESS;
+    } catch (error) {
+      this._lastError =
+        error instanceof Error ? error.message : String(error);
+      this.log(`Integration action failed: ${this._lastError}`);
+      return NodeStatus.FAILURE;
+    }
+  }
+
+  /**
+   * Dual-mode execution:
+   * - Activity mode: Use context.activities (deterministic for Temporal)
+   * - Standalone mode: Inline executePieceAction (for testing)
+   */
+  private async executeAction(
+    context: TemporalContext,
+    inputs: Record<string, unknown>,
+    auth: PieceAuth
+  ): Promise<unknown> {
+    const request: PieceActivityRequest = {
+      provider: this.provider,
+      action: this.action,
+      inputs,
+      auth,
+    };
+
+    // Activity mode: deterministic execution
+    if (context.activities?.executePieceAction) {
+      this.log(`Executing via activity: ${this.provider}/${this.action}`);
+      return context.activities.executePieceAction(request);
+    }
+
+    // Standalone mode: inline execution (for testing without Temporal)
+    this.log(`Executing inline (standalone): ${this.provider}/${this.action}`);
+    return executePieceAction(request);
+  }
+
+  /**
+   * Resolve variable references in inputs
+   * Supports ${input.key}, ${bb.key}, ${env.KEY}, ${param.key}
+   */
+  private resolveInputs(context: TemporalContext): Record<string, unknown> {
+    const varCtx: VariableContext = {
+      blackboard: context.blackboard,
+      input: context.input,
+      testData: context.testData,
+    };
+    // Use preserveUndefined: false to return empty string/undefined for missing values
+    // This matches the original behavior
+    return resolveValue(this.inputs, varCtx, { preserveUndefined: false }) as Record<string, unknown>;
+  }
+}
+
+/**
+ * Default token provider that reads from environment variables
+ * Useful for testing and simple deployments
+ *
+ * Looks for:
+ * - {PROVIDER}_ACCESS_TOKEN (e.g., GOOGLE_ACCESS_TOKEN)
+ * - {PROVIDER}_API_KEY (e.g., OPENAI_API_KEY)
+ */
+export const envTokenProvider: TokenProvider = async (
+  _context,
+  provider
+): Promise<PieceAuth> => {
+  const normalizedProvider = provider.toUpperCase().replace(/-/g, "_");
+
+  // Try access token first
+  const accessToken = process.env[`${normalizedProvider}_ACCESS_TOKEN`];
+  if (accessToken) {
+    return { access_token: accessToken };
+  }
+
+  // Try API key
+  const apiKey = process.env[`${normalizedProvider}_API_KEY`];
+  if (apiKey) {
+    return { api_key: apiKey };
+  }
+
+  throw new Error(
+    `No token found for provider ${provider}. ` +
+    `Set ${normalizedProvider}_ACCESS_TOKEN or ${normalizedProvider}_API_KEY environment variable.`
+  );
+};

package/src/integrations/piece-executor.ts

@@ -0,0 +1,320 @@
+/**
+ * Piece Executor
+ * Dynamically executes Active Pieces actions
+ *
+ * Active Pieces is an open-source automation platform with 440+ connectors.
+ * This module wraps their npm packages for use in btree workflows.
+ *
+ * @see https://activepieces.com/docs
+ */
+
+import type { PieceActivityRequest, PieceAuth } from "../types.js";
+
+// Re-export types for backward compatibility
+export type { PieceAuth, PieceActivityRequest as PieceActionRequest } from "../types.js";
+
+/**
+ * Mapping from provider names to Active Pieces package names
+ * Add entries as needed when integrating new providers
+ */
+const PROVIDER_TO_PIECE: Record<string, string> = {
+  // Google services
+  "google": "google-sheets",
+  "google-sheets": "google-sheets",
+  "google-drive": "google-drive",
+  "google-calendar": "google-calendar",
+  "gmail": "gmail",
+
+  // Communication
+  "slack": "slack",
+  "discord": "discord",
+  "telegram": "telegram-bot",
+  "twilio": "twilio",
+
+  // AI/ML
+  "openai": "openai",
+  "anthropic": "anthropic",
+
+  // CRM & Sales
+  "hubspot": "hubspot",
+  "salesforce": "salesforce",
+
+  // Productivity
+  "notion": "notion",
+  "airtable": "airtable",
+  "asana": "asana",
+  "trello": "trello",
+
+  // Development
+  "github": "github",
+  "gitlab": "gitlab",
+
+  // E-commerce
+  "shopify": "shopify",
+  "stripe": "stripe",
+
+  // Other
+  "http": "http",
+  "webhook": "http",
+};
+
+/**
+ * Cache for loaded pieces to avoid repeated dynamic imports
+ */
+const pieceCache: Map<string, unknown> = new Map();
+
+/**
+ * Get the Active Pieces package name for a provider
+ */
+function getPiecePackageName(provider: string): string {
+  const pieceName = PROVIDER_TO_PIECE[provider.toLowerCase()];
+  if (pieceName) {
+    return `@activepieces/piece-${pieceName}`;
+  }
+  // Default: assume package name matches provider name
+  return `@activepieces/piece-${provider.toLowerCase()}`;
+}
+
+/**
+ * Mapping from package name to piece export name
+ * Active Pieces packages export the piece with a specific name (e.g., googleSheets, slack)
+ */
+const PIECE_EXPORT_NAMES: Record<string, string> = {
+  "@activepieces/piece-google-sheets": "googleSheets",
+  "@activepieces/piece-slack": "slack",
+  "@activepieces/piece-openai": "openai",
+  "@activepieces/piece-discord": "discord",
+  "@activepieces/piece-notion": "notion",
+  "@activepieces/piece-github": "github",
+  "@activepieces/piece-http": "http",
+};
+
+/**
+ * Dynamically load an Active Pieces package
+ */
+async function loadPiece(packageName: string): Promise<unknown> {
+  // Check cache first
+  if (pieceCache.has(packageName)) {
+    return pieceCache.get(packageName);
+  }
+
+  try {
+    // Dynamic import of the piece package
+    const pieceModule = await import(packageName);
+
+    // Active Pieces exports vary - try to find the piece object
+    // Format 1: { googleSheets: { _actions: {...} } }
+    // Format 2: { default: { actions: {...} } }
+    let piece: unknown = pieceModule;
+
+    // Check for known export names
+    const exportName = PIECE_EXPORT_NAMES[packageName];
+    if (exportName && pieceModule[exportName]) {
+      piece = pieceModule[exportName];
+    } else {
+      // Try to find the piece by looking for an object with _actions
+      for (const key of Object.keys(pieceModule)) {
+        const exported = pieceModule[key];
+        if (exported && typeof exported === "object" && "_actions" in exported) {
+          piece = exported;
+          break;
+        }
+      }
+    }
+
+    pieceCache.set(packageName, piece);
+    return piece;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+
+    // Provide helpful error message
+    if (message.includes("Cannot find module")) {
+      throw new Error(
+        `Active Pieces package '${packageName}' is not installed. ` +
+        `Run: npm install ${packageName}`
+      );
+    }
+
+    throw new Error(`Failed to load piece package '${packageName}': ${message}`);
+  }
+}
+
+/**
+ * Execute an Active Pieces action
+ *
+ * @param request - Action request with provider, action, inputs, and auth
+ * @returns The result from the Active Pieces action
+ *
+ * @example
+ * ```typescript
+ * const result = await executePieceAction({
+ *   provider: 'google-sheets',
+ *   action: 'append_row',
+ *   inputs: {
+ *     spreadsheetId: 'xxx',
+ *     sheetName: 'Sheet1',
+ *     values: ['A', 'B', 'C']
+ *   },
+ *   auth: { access_token: 'ya29.xxx' }
+ * });
+ * ```
+ */
+export async function executePieceAction(
+  request: PieceActivityRequest
+): Promise<unknown> {
+  const { provider, action, inputs, auth } = request;
+
+  // Get package name and load piece
+  const packageName = getPiecePackageName(provider);
+  const piece = (await loadPiece(packageName)) as Record<string, unknown>;
+
+  // Find the actions object
+  // Active Pieces uses _actions internally, but some may use actions
+  let actions: Record<string, unknown> | undefined;
+
+  // Try _actions first (Active Pieces internal format)
+  if (piece._actions && typeof piece._actions === "object") {
+    actions = piece._actions as Record<string, unknown>;
+  }
+  // Then try actions (public API format)
+  else if (piece.actions && typeof piece.actions === "object") {
+    actions = piece.actions as Record<string, unknown>;
+  }
+  // Try default export
+  else if (piece.default && typeof piece.default === "object") {
+    const defaultExport = piece.default as Record<string, unknown>;
+    actions = (defaultExport._actions || defaultExport.actions) as Record<string, unknown> | undefined;
+  }
+
+  if (!actions) {
+    throw new Error(
+      `Piece '${packageName}' does not export actions. ` +
+      `This may not be a valid Active Pieces package.`
+    );
+  }
+
+  // Find the specific action
+  const actionDef = actions[action] as Record<string, unknown> | undefined;
+
+  if (!actionDef) {
+    const availableActions = Object.keys(actions).join(", ");
+    throw new Error(
+      `Action '${action}' not found in piece '${packageName}'. ` +
+      `Available actions: ${availableActions}`
+    );
+  }
+
+  // Verify action has a run method
+  if (typeof actionDef.run !== "function") {
+    throw new Error(
+      `Action '${action}' in piece '${packageName}' does not have a run method`
+    );
+  }
+
+  // Execute the action
+  // Active Pieces actions expect: { auth, propsValue, ... }
+  const runFn = actionDef.run as (context: Record<string, unknown>) => Promise<unknown>;
+
+  const result = await runFn({
+    auth,
+    propsValue: inputs,
+    // Additional context that some pieces might need
+    store: createMockStore(),
+    files: createMockFiles(),
+  });
+
+  return result;
+}
+
+/**
+ * Create a mock store for pieces that use state storage
+ * In a real implementation, this could be backed by Redis or the blackboard
+ */
+function createMockStore(): Record<string, unknown> {
+  const storage: Record<string, unknown> = {};
+
+  return {
+    async get(key: string): Promise<unknown> {
+      return storage[key];
+    },
+    async put(key: string, value: unknown): Promise<void> {
+      storage[key] = value;
+    },
+    async delete(key: string): Promise<void> {
+      delete storage[key];
+    },
+  };
+}
+
+/**
+ * Create a mock files helper for pieces that handle file uploads
+ */
+function createMockFiles(): Record<string, unknown> {
+  return {
+    async write(params: { fileName: string; data: Buffer }): Promise<string> {
+      // In a real implementation, this would upload to a file storage
+      console.log(`[PieceExecutor] Mock file write: ${params.fileName}`);
+      return `mock://files/${params.fileName}`;
+    },
+  };
+}
+
+/**
+ * List available actions for a provider
+ * Useful for UI builders and documentation
+ */
+export async function listPieceActions(
+  provider: string
+): Promise<{ name: string; displayName?: string; description?: string }[]> {
+  const packageName = getPiecePackageName(provider);
+  const piece = (await loadPiece(packageName)) as Record<string, unknown>;
+
+  let actions: Record<string, unknown> | undefined;
+
+  // Try _actions first (Active Pieces internal format)
+  if (piece._actions && typeof piece._actions === "object") {
+    actions = piece._actions as Record<string, unknown>;
+  }
+  // Then try actions (public API format)
+  else if (piece.actions && typeof piece.actions === "object") {
+    actions = piece.actions as Record<string, unknown>;
+  }
+  // Try default export
+  else if (piece.default && typeof piece.default === "object") {
+    const defaultExport = piece.default as Record<string, unknown>;
+    actions = (defaultExport._actions || defaultExport.actions) as Record<string, unknown> | undefined;
+  }
+
+  if (!actions) {
+    return [];
+  }
+
+  return Object.entries(actions).map(([name, def]) => {
+    const actionDef = def as Record<string, unknown>;
+    return {
+      name,
+      displayName: actionDef.displayName as string | undefined,
+      description: actionDef.description as string | undefined,
+    };
+  });
+}
+
+/**
+ * Check if a piece is installed
+ */
+export async function isPieceInstalled(provider: string): Promise<boolean> {
+  const packageName = getPiecePackageName(provider);
+  try {
+    await loadPiece(packageName);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Clear the piece cache (useful for testing)
+ */
+export function clearPieceCache(): void {
+  pieceCache.clear();
+}