@zerowidth/workbench-sdk 2.0.0-alpha.0

package/src/utilities/mcp.js

@@ -0,0 +1,165 @@
+import axios from 'axios';
+import { v4 as uuidv4 } from 'uuid';
+
+/**
+ * MCP client for the `remote-mcp-tool` node.
+ *
+ * Speaks JSON-RPC 2.0 over the Streamable HTTP transport defined by
+ * the Model Context Protocol spec:
+ *
+ *   https://modelcontextprotocol.io/specification
+ *
+ * Spec-relevant wire requirements (all enforced by reference servers
+ * like @modelcontextprotocol/sdk's StreamableHTTPServerTransport):
+ *
+ *   1. Every request body carries `jsonrpc: "2.0"` plus `id` /
+ *      `method` / `params` — the JSON-RPC envelope, not just the
+ *      params.
+ *   2. `Accept` header MUST list both `application/json` AND
+ *      `text/event-stream` — the server picks the response shape
+ *      based on whether it's streaming.
+ *   3. The response body is either:
+ *        - `Content-Type: application/json` — single JSON-RPC
+ *          response object, parse normally.
+ *        - `Content-Type: text/event-stream` — SSE wire shape;
+ *          last `data:` line carries the JSON-RPC response.
+ *      Both shapes are valid; this client handles either.
+ */
+
+/** Build the headers for an MCP request. Adds bearer auth when
+ *  provided; sets the Accept header to satisfy spec-compliant
+ *  servers that require both content types in the list. */
+function buildHeaders(token) {
+  const headers = {
+    'Content-Type': 'application/json',
+    Accept: 'application/json, text/event-stream',
+  };
+  if (token) {
+    headers['Authorization'] = `Bearer ${token}`;
+  }
+  return headers;
+}
+
+/** Parse an MCP HTTP response. Tolerates either content-type
+ *  variant (plain JSON or SSE-framed). Returns the JSON-RPC
+ *  response object's `.result` (or throws on `.error`). */
+function parseMcpResponse(response) {
+  const contentType = (response.headers?.['content-type'] || '').toLowerCase();
+
+  // Streamable HTTP servers default to SSE — body is one or more
+  // `event: ...\ndata: ...\n\n` blocks. Find the final `data:` line
+  // and JSON.parse it. We disabled axios' default JSON parse so
+  // `response.data` is the raw text either way.
+  if (contentType.includes('text/event-stream')) {
+    const raw = typeof response.data === 'string'
+      ? response.data
+      : String(response.data ?? '');
+    const dataLines = [];
+    for (const line of raw.split(/\r?\n/)) {
+      if (line.startsWith('data:')) dataLines.push(line.slice(5).trimStart());
+    }
+    if (dataLines.length === 0) {
+      throw new Error('MCP SSE response had no data lines');
+    }
+    const payload = JSON.parse(dataLines[dataLines.length - 1]);
+    if (payload.error) {
+      throw new Error(
+        `MCP error ${payload.error.code}: ${payload.error.message}`,
+      );
+    }
+    return payload.result;
+  }
+
+  // Plain JSON response — single JSON-RPC object. `response.data`
+  // is the raw text (we disabled axios' parse); JSON.parse here.
+  const raw = typeof response.data === 'string'
+    ? response.data
+    : JSON.stringify(response.data);
+  const payload = JSON.parse(raw);
+  if (payload?.error) {
+    throw new Error(
+      `MCP error ${payload.error.code}: ${payload.error.message}`,
+    );
+  }
+  return payload?.result;
+}
+
+/**
+ * Call an MCP tool.
+ * @param {Object} args - The arguments to pass to the tool (must include 'name')
+ * @param {Object} options - { url, token }
+ * @returns {Object} The result of the tool call
+ */
+export async function callMCPTool(args, { url, token } = {}) {
+  if (!url) throw new Error('No MCP URL provided');
+
+  const toolName = args.name;
+  if (!toolName) throw new Error('No tool name provided for MCP call');
+
+  const { name, ...toolArgs } = args;
+  const id = uuidv4();
+
+  try {
+    const response = await axios.post(
+      url,
+      {
+        jsonrpc: '2.0',
+        id,
+        method: 'tools/call',
+        params: {
+          name: toolName,
+          arguments: toolArgs,
+        },
+      },
+      {
+        headers: buildHeaders(token),
+        // SSE responses arrive as text; tell axios not to JSON.parse.
+        responseType: 'text',
+        transformResponse: [(d) => d],
+      },
+    );
+    return parseMcpResponse(response);
+  } catch (err) {
+    throw new Error(
+      `Failed to call MCP tool "${toolName}" at ${url}: ${err.message}`,
+    );
+  }
+}
+
+/**
+ * Fetch all tool schemas from an MCP endpoint.
+ * @param {string} url - The MCP server URL
+ * @param {string} [token] - Optional bearer token for authentication
+ * @returns {Array} Array of tool schemas (normalized to {name, description, parameters})
+ */
+export async function fetchMCPTools(url, token) {
+  if (!url) throw new Error('No MCP URL provided');
+
+  const id = uuidv4();
+
+  try {
+    const response = await axios.post(
+      url,
+      {
+        jsonrpc: '2.0',
+        id,
+        method: 'tools/list',
+        params: {},
+      },
+      {
+        headers: buildHeaders(token),
+        responseType: 'text',
+        transformResponse: [(d) => d],
+      },
+    );
+    const result = parseMcpResponse(response);
+    const tools = result?.tools || [];
+    return tools.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.inputSchema,
+    }));
+  } catch (err) {
+    throw new Error(`Failed to fetch MCP tools from ${url}: ${err.message}`);
+  }
+}

package/src/utilities/oauth.js

@@ -0,0 +1,280 @@
+/**
+ * OAuth 2.0 Token Refresh Utility
+ * 
+ * Handles OAuth token refresh with:
+ * - Expiry pre-checking (epoch or ISO timestamps)
+ * - Refresh coalescing (multiple nodes waiting for same provider refresh)
+ * - Retry logic with max retries
+ * - Automatic in-memory key updates
+ */
+
+/**
+ * Check if a key is an OAuth key (has accessToken and onRefresh)
+ * @param {any} key - The key value to check
+ * @returns {boolean} True if this is an OAuth key
+ */
+export function isOAuthKey(key) {
+  return (
+    key &&
+    typeof key === 'object' &&
+    (typeof key.accessToken === 'string' || typeof key.access_token === 'string') &&
+    typeof key.onRefresh === 'function'
+  );
+}
+
+/**
+ * Parse expiresAt value (supports epoch milliseconds or ISO string)
+ * @param {number|string|undefined} expiresAt - Expiry timestamp
+ * @returns {number|null} Milliseconds since epoch, or null if invalid/undefined
+ */
+export function parseExpiresAt(expiresAt) {
+  if (!expiresAt) return null;
+  
+  if (typeof expiresAt === 'number') {
+    return expiresAt;
+  }
+  
+  if (typeof expiresAt === 'string') {
+    // Try ISO string
+    const isoDate = new Date(expiresAt);
+    if (!isNaN(isoDate.getTime())) {
+      return isoDate.getTime();
+    }
+    
+    // Try epoch string
+    const epochNum = parseInt(expiresAt, 10);
+    if (!isNaN(epochNum)) {
+      return epochNum;
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Check if token is expired or will expire soon
+ * @param {Object} oauthKey - OAuth key object
+ * @param {number} expirySkewMs - Milliseconds before actual expiry to consider expired
+ * @returns {boolean} True if token needs refresh
+ */
+export function isTokenExpired(oauthKey, expirySkewMs = 0) {
+  const expiresAt = parseExpiresAt(oauthKey.expiresAt);
+  if (!expiresAt) {
+    // No expiry info - assume not expired (can't determine)
+    return false;
+  }
+  
+  const now = Date.now();
+  const expiryThreshold = expiresAt - expirySkewMs;
+  return now >= expiryThreshold;
+}
+
+/**
+ * OAuth Refresh Manager
+ * Handles token refresh with coalescing for concurrent requests
+ */
+export class OAuthRefreshManager {
+  constructor(config = {}) {
+    // Map of provider -> refresh promise (for coalescing)
+    this.refreshPromises = new Map();
+    
+    // Configuration
+    this.expirySkewMs = config.oauthExpirySkewMs || 60000; // Default: 1 minute
+    this.maxRefreshRetries = config.oauthMaxRefreshRetries || 3;
+    this.refreshTimeoutMs = config.oauthRefreshTimeoutMs || 20000; // Default: 20 seconds
+    this.onNodeUpdate = config.onNodeUpdate || null;
+    this.keys = config.keys || null; // Reference to keys object for updates
+  }
+
+  /**
+   * Ensure token is valid, refresh if needed
+   * @param {string} provider - Provider name (e.g., 'hubspot')
+   * @param {Object} oauthKey - OAuth key object
+   * @returns {Promise<Object>} Updated OAuth key object with valid token
+   * @throws {Error} If refresh fails after max retries
+   */
+  async ensureValidToken(provider, oauthKey) {
+    // Check if token is expired
+    if (!isTokenExpired(oauthKey, this.expirySkewMs)) {
+      return oauthKey;
+    }
+
+    // Token needs refresh
+    return await this.refreshToken(provider, oauthKey);
+  }
+
+  /**
+   * Refresh OAuth token with coalescing support
+   * @param {string} provider - Provider name
+   * @param {Object} oauthKey - OAuth key object
+   * @returns {Promise<Object>} Updated OAuth key object
+   * @throws {Error} If refresh fails after max retries
+   */
+  async refreshToken(provider, oauthKey) {
+    // Check if refresh is already in progress for this provider
+    const existingRefresh = this.refreshPromises.get(provider);
+    if (existingRefresh) {
+      // Wait for existing refresh to complete
+      try {
+        return await existingRefresh;
+      } catch (error) {
+        // If existing refresh failed, retry our own
+        // Fall through to start new refresh
+      }
+    }
+
+    // Start new refresh
+    const refreshPromise = this._performRefresh(provider, oauthKey);
+    this.refreshPromises.set(provider, refreshPromise);
+
+    try {
+      const updatedKey = await refreshPromise;
+      return updatedKey;
+    } finally {
+      // Clean up promise after completion
+      this.refreshPromises.delete(provider);
+    }
+  }
+
+  /**
+   * Perform the actual token refresh
+   * @private
+   * @param {string} provider - Provider name
+   * @param {Object} oauthKey - OAuth key object
+   * @returns {Promise<Object>} Updated OAuth key object
+   */
+  async _performRefresh(provider, oauthKey) {
+    let lastError = null;
+    let retries = 0;
+
+    // Emit refresh started event
+    if (this.onNodeUpdate) {
+      this.onNodeUpdate({
+        type: 'oauth_refresh_start',
+        provider,
+        timestamp: Date.now(),
+        data: {
+          status: 'started',
+          retryAttempt: retries
+        }
+      });
+    }
+
+    while (retries <= this.maxRefreshRetries) {
+      try {
+        // Create timeout promise
+        const timeoutPromise = new Promise((_, reject) => {
+          setTimeout(() => {
+            reject(new Error(`OAuth refresh timeout after ${this.refreshTimeoutMs}ms`));
+          }, this.refreshTimeoutMs);
+        });
+
+        // Call onRefresh with timeout
+        const refreshPromise = oauthKey.onRefresh({
+          provider,
+          currentToken: oauthKey.accessToken,
+          refreshToken: oauthKey.refreshToken,
+          expiresAt: oauthKey.expiresAt
+        });
+
+        const updatedKey = await Promise.race([refreshPromise, timeoutPromise]);
+
+        // Validate the returned key object
+        if (!updatedKey || typeof updatedKey !== 'object') {
+          throw new Error('onRefresh callback must return an OAuth key object');
+        }
+
+        if (!updatedKey.accessToken || typeof updatedKey.accessToken !== 'string') {
+          throw new Error('onRefresh callback must return an object with accessToken string');
+        }
+
+        // Update in-memory keys object
+        if (this.keys && this.keys[provider]) {
+          this.keys[provider] = { ...this.keys[provider], ...updatedKey };
+        }
+
+        // Emit refresh success event
+        if (this.onNodeUpdate) {
+          this.onNodeUpdate({
+            type: 'oauth_refresh_complete',
+            provider,
+            timestamp: Date.now(),
+            data: {
+              status: 'success',
+              retryAttempt: retries
+            }
+          });
+        }
+
+        return updatedKey;
+      } catch (error) {
+        lastError = error;
+        retries++;
+
+        // Emit refresh failure event (if not final attempt)
+        if (retries <= this.maxRefreshRetries && this.onNodeUpdate) {
+          this.onNodeUpdate({
+            type: 'oauth_refresh_failed',
+            provider,
+            timestamp: Date.now(),
+            data: {
+              status: 'failed',
+              retryAttempt: retries,
+              error: error.message
+            }
+          });
+        }
+
+        // If we've exhausted retries, break
+        if (retries > this.maxRefreshRetries) {
+          break;
+        }
+
+        // Wait before retry (exponential backoff: 100ms, 200ms, 400ms)
+        await new Promise(resolve => setTimeout(resolve, Math.min(100 * Math.pow(2, retries - 1), 1000)));
+      }
+    }
+
+    // Emit final failure event
+    if (this.onNodeUpdate) {
+      this.onNodeUpdate({
+        type: 'oauth_refresh_complete',
+        provider,
+        timestamp: Date.now(),
+        data: {
+          status: 'failed',
+          retryAttempt: retries - 1,
+          error: lastError?.message || 'Unknown error'
+        }
+      });
+    }
+
+    // All retries exhausted
+    throw new Error(
+      `OAuth refresh failed for provider '${provider}' after ${this.maxRefreshRetries} retries: ${lastError?.message || 'Unknown error'}`
+    );
+  }
+
+  /**
+   * Check if a response indicates token refresh is needed
+   * @param {Object} response - HTTP response object (from axios)
+   * @param {Function} providerSpecificCheck - Optional provider-specific check function
+   * @returns {boolean} True if refresh is needed
+   */
+  static needsRefresh(response, providerSpecificCheck = null) {
+    // Check HTTP status codes
+    if (response && response.status) {
+      if (response.status === 401 || response.status === 403) {
+        return true;
+      }
+    }
+
+    // Run provider-specific check if provided
+    if (providerSpecificCheck) {
+      return providerSpecificCheck(response);
+    }
+
+    return false;
+  }
+}
+

package/src/utilities/sanitizeAPICall.js

@@ -0,0 +1,63 @@
+/**
+ * Sanitize an API call event by stripping auth credentials from headers and URLs.
+ *
+ * @param {Object} event - Raw API call event
+ * @returns {Object} Sanitized event safe for user consumption
+ */
+export function sanitizeAPICallEvent(event) {
+    const sanitized = { ...event };
+
+    if (sanitized.request) {
+        sanitized.request = { ...sanitized.request };
+
+        // Sanitize headers - redact auth-related values
+        if (sanitized.request.headers) {
+            const authPattern = /^(authorization|x-api-key|api-key|apikey|cookie)$/i;
+            const cleanHeaders = {};
+            for (const [key, value] of Object.entries(sanitized.request.headers)) {
+                cleanHeaders[key] = authPattern.test(key) ? '[REDACTED]' : value;
+            }
+            sanitized.request.headers = cleanHeaders;
+        }
+
+        // Sanitize URL query params - redact sensitive values
+        if (sanitized.request.url) {
+            try {
+                const urlObj = new URL(sanitized.request.url);
+                const sensitiveParams = /^(key|apikey|api_key|token|secret|password|access_token)$/i;
+                for (const key of [...urlObj.searchParams.keys()]) {
+                    if (sensitiveParams.test(key)) {
+                        urlObj.searchParams.set(key, '[REDACTED]');
+                    }
+                }
+                sanitized.request.url = urlObj.toString();
+            } catch (e) {
+                // If URL parsing fails, leave as-is
+            }
+        }
+    }
+
+    return sanitized;
+}
+
+/**
+ * Emit an onAPICall event if the callback is configured.
+ * Handles both sync and async callbacks and swallows callback errors.
+ *
+ * @param {Object} engineConfig - Engine config (may contain onAPICall)
+ * @param {Object} rawEvent - Raw unsanitized event data
+ */
+export async function emitAPICallEvent(engineConfig, rawEvent) {
+    if (!engineConfig?.onAPICall) return;
+
+    const event = sanitizeAPICallEvent(rawEvent);
+
+    try {
+        const result = engineConfig.onAPICall(event);
+        if (result && typeof result.then === 'function') {
+            await result;
+        }
+    } catch (e) {
+        // Don't let callback errors break the integration
+    }
+}

package/src/utilities/typeConverters.js

@@ -0,0 +1,34 @@
+/**
+ * Type conversion utilities for custom types
+ * This module provides utilities for loading and using type converters
+ * from separate converter files (e.g., message.converters.js)
+ */
+
+/**
+ * Load type converters from a converters module if it exists
+ * This allows extending converters for custom types
+ * @param {string} typeName - The type name
+ * @returns {Promise<Object|null>} Converter object or null if not found
+ */
+export async function loadTypeConverter(typeName) {
+  try {
+    const { getDirname } = await import('./helpers.js');
+    const path = (await import('path')).default;
+    const fs = (await import('fs')).default;
+    
+    const typeDir = path.join(getDirname(import.meta.url), "../types");
+    const converterPath = path.join(typeDir, `${typeName}.converters.js`);
+    
+    if (fs.existsSync(converterPath)) {
+      const converterFileUrl = `file://${path.resolve(converterPath)}`;
+      const converterModule = await import(converterFileUrl);
+      return converterModule.default || converterModule;
+    }
+  } catch (err) {
+    // Converter file doesn't exist or failed to load - that's okay
+    return null;
+  }
+  
+  return null;
+}
+