@zerowidth/workbench-sdk 2.0.0-alpha.0

package/src/integrations/twilio.js

@@ -0,0 +1,66 @@
+import axios from 'axios';
+import { emitAPICallEvent } from '../utilities/sanitizeAPICall.js';
+
+export default class TwilioIntegration {
+    constructor(config, options = {}) {
+        if (typeof config === 'object') {
+            this.accountSid = config.account_sid;
+            this.authToken = config.auth_token;
+        } else {
+            throw new Error('Twilio integration requires an object with account_sid and auth_token');
+        }
+        this.options = {
+            baseURL: `https://api.twilio.com/2010-04-01/Accounts/${this.accountSid}`,
+            timeout: 30000,
+            ...options
+        };
+    }
+
+    async _request(config) {
+        const requestHeaders = { 'Content-Type': 'application/x-www-form-urlencoded', ...config.headers };
+        const startTime = Date.now();
+
+        try {
+            const response = await axios({
+                ...config,
+                headers: requestHeaders,
+                auth: { username: this.accountSid, password: this.authToken },
+                timeout: this.options.timeout
+            });
+
+            await emitAPICallEvent(this._engineConfig, {
+                timestamp: startTime, integration: 'twilio', nodeId: null, nodeType: null,
+                request: { method: config.method, url: config.url, headers: requestHeaders, body: config.data || null },
+                response: { status: response.status, statusText: response.statusText },
+                duration: Date.now() - startTime, error: null
+            });
+
+            return response.data;
+        } catch (error) {
+            await emitAPICallEvent(this._engineConfig, {
+                timestamp: startTime, integration: 'twilio', nodeId: null, nodeType: null,
+                request: { method: config.method, url: config.url, headers: requestHeaders, body: config.data || null },
+                response: { status: error.response?.status || 0, statusText: error.response?.statusText || 'Error' },
+                duration: Date.now() - startTime, error: error.message
+            });
+            if (error.response) {
+                const msg = error.response.data?.message || error.response.statusText;
+                throw new Error(`Twilio API error (${error.response.status}): ${msg}`);
+            }
+            throw new Error(`Twilio API error: ${error.message}`);
+        }
+    }
+
+    async sendSMS(to, from, body) {
+        const params = new URLSearchParams();
+        params.append('To', to);
+        params.append('From', from);
+        params.append('Body', body);
+
+        return await this._request({
+            method: 'POST',
+            url: `${this.options.baseURL}/Messages.json`,
+            data: params.toString()
+        });
+    }
+}

package/src/types/README.md

@@ -0,0 +1,181 @@
+# Custom Type Conversions
+
+This directory contains type definitions (`.json` files) and optional type converters (`.converters.js` files) for custom types in the Workbench SDK.
+
+## Type Definitions
+
+Each type is defined by a JSON schema file (e.g., `message.json`, `conversation.json`). These schemas are used to validate values at runtime.
+
+## Type Converters
+
+Type converters allow you to define conversion operations for custom types, such as converting a `message` object to a string.
+
+### Default Converters
+
+The SDK includes default converter files for common types in this directory:
+
+- **`message.converters.js`**: Converts to string by extracting all text from `message.content` array
+- **`conversation.converters.js`**: Converts array of messages to string, joining with separator
+- **`content.converters.js`**: Extracts text from content objects/arrays
+- **`tool.converters.js`**: Converts tool objects to string representation
+- **`plugin.converters.js`**: Converts plugin objects to string representation
+
+You can override any of these by modifying the corresponding `.converters.js` file.
+
+### Using Converters
+
+You can use type converters in your code:
+
+```javascript
+import Workbench from '@zerowidth/workbench-sdk';
+
+const engine = await Workbench.create('./myflow.zwf', config);
+
+// Convert a message to string
+const message = {
+  role: 'user',
+  content: [
+    { type: 'text', text: 'Hello' },
+    { type: 'text', text: ' World' }
+  ]
+};
+
+const text = engine.convertType(message, 'message');
+// Result: "Hello World"
+```
+
+### Creating Custom Converters
+
+To define converters for a type, create a `<typeName>.converters.js` file in this directory. Each type should have its own converter file.
+
+**Example: `message.converters.js`**
+
+```javascript
+/**
+ * Type converters for the 'message' type
+ * Converts message objects to strings by extracting all text content
+ */
+
+/**
+ * Extract text content from a message's content field
+ */
+function extractTextFromContent(content) {
+  if (typeof content === 'string') {
+    return content;
+  }
+  
+  if (content === null || content === undefined) {
+    return '';
+  }
+  
+  if (Array.isArray(content)) {
+    let text = '';
+    for (const item of content) {
+      if (item && typeof item === 'object' && item.type === 'text' && item.text) {
+        text += item.text;
+      }
+    }
+    return text;
+  }
+  
+  return String(content || '');
+}
+
+/**
+ * Convert a message object to a string
+ */
+export function toString(message, separator) {
+  if (!message || typeof message !== 'object') {
+    return String(message || '');
+  }
+  
+  return extractTextFromContent(message.content);
+}
+
+export default {
+  toString
+};
+```
+
+### Converter Functions
+
+Each converter file should export an object with conversion functions. Common conversions:
+
+- **`toString(value, options)`**: Converts the value to a string
+  - `value`: The value to convert
+  - `options`: Optional object with conversion options (e.g., `{ separator: '\n' }`)
+
+
+- **`toBoolean(value)`**: (Message only) Converts message to boolean
+  - `value`: The message to convert
+  - Returns true if message has content
+
+### How It Works
+
+1. When you call `engine.convertType(value, 'message')`, the engine:
+   - Checks if a custom converter file exists (`message.converters.js`)
+   - Falls back to built-in converters if available
+   - Falls back to default `String()` conversion
+
+2. The converter system is extensible - you can override built-in converters or add converters for new types.
+
+### Examples
+
+**Converting a message:**
+```javascript
+const message = {
+  role: 'assistant',
+  content: [
+    { type: 'text', text: 'Hello, ' },
+    { type: 'text', text: 'how can I help?' }
+  ]
+};
+
+const text = engine.convertType(message, 'message');
+// Returns: "Hello, how can I help?"
+```
+
+**Converting a conversation to string (YAML-like chat log format):**
+```javascript
+const conversation = [
+  { 
+    role: 'user', 
+    content: [
+      { type: 'text', text: 'Hello' },
+      { type: 'image_url', image_url: { url: 'https://example.com/image.png' } }
+    ]
+  },
+  { 
+    role: 'assistant', 
+    content: 'Hi there! Here is the image you requested.' 
+  },
+  {
+    role: 'tool',
+    tool_call_id: 'call_123',
+    content: [{ type: 'tool_result', result: 'Success' }]
+  }
+];
+
+const chatLog = engine.convertType(conversation, 'conversation');
+// Returns:
+// user:
+//   Hello [image_url: https://example.com/image.png]
+//
+// assistant:
+//   Hi there! Here is the image you requested.
+//
+// tool:
+//   [tool_result: Success] [tool_call_id: call_123]
+```
+
+**Converting content:**
+```javascript
+const content = [
+  { type: 'text', text: 'First paragraph' },
+  { type: 'text', text: 'Second paragraph' }
+];
+
+const text = engine.convertType(content, 'content');
+// Returns: "First paragraphSecond paragraph"
+```
+

package/src/types/content.converters.js

@@ -0,0 +1,21 @@
+/**
+ * Type converters for the 'content' type
+ * Extracts text from content objects/arrays
+ */
+
+import { extractTextFromContent } from '../utilities/helpers.js';
+
+/**
+ * Convert a content object to a string
+ * Extracts text from content items with type 'text'
+ * @param {Object|Array|string} content - Content object, array, or string
+ * @returns {string} Extracted text content
+ */
+export function toString(content) {
+  return extractTextFromContent(content);
+}
+
+export default {
+  toString
+};
+

package/src/types/content.json

@@ -0,0 +1,31 @@
+{
+  "type": "object",
+  "properties": {
+    "type": { "type": "string" },
+    "text": { "type": "string" },
+    "name": { "type": "string" },
+    "arguments": { "type": "object" },
+    "image_url": { "type": "object", "properties": { "url": { "type": "string" } } },
+    "result": {
+      "anyOf": [
+        { "type": "string" },
+        { "type": "number" },
+        { "type": "object" },
+        { "type": "array" },
+        { "type": "boolean" },
+        { "type": "null" }
+      ]
+    },
+    "source": {
+      "type": "object",
+      "properties": {
+        "url": { "type": "string" },
+        "data": { "type": "string" },
+        "media_type": { "type": "string" }
+      },
+      "additionalProperties": true
+    }
+  },
+  "required": ["type"],
+  "additionalProperties": true
+}

package/src/types/conversation.converters.js

@@ -0,0 +1,148 @@
+/**
+ * Type converters for the 'conversation' type
+ * Converts an array of messages to a string
+ */
+
+import { extractTextFromContent } from '../utilities/helpers.js';
+
+/**
+ * Convert a conversation to a YAML-like chat log format
+ * This is the default toString behavior for conversations
+ * Format: {role}:\n  {content}\n
+ * @param {Array} conversation - Array of message objects
+ * @param {string} separator - Ignored (kept for API compatibility)
+ * @returns {string} YAML-like formatted chat log
+ */
+export function toString(conversation, separator) {
+  if (!Array.isArray(conversation)) {
+    return String(conversation || '');
+  }
+  
+  const lines = [];
+  
+  for (const message of conversation) {
+    if (typeof message === 'string') {
+      // Simple string message - no role
+      lines.push(message);
+      lines.push(''); // Empty line separator
+      continue;
+    }
+    
+    if (!message || typeof message !== 'object') {
+      continue;
+    }
+    
+    // Get role (default to 'unknown' if not specified)
+    const role = message.role || 'unknown';
+    
+    // Format the content
+    let contentStr = '';
+    
+    if (message.content === undefined || message.content === null) {
+      // No content
+      contentStr = '';
+    } else if (typeof message.content === 'string') {
+      // Simple string content
+      contentStr = message.content;
+    } else if (Array.isArray(message.content)) {
+      // Array of content items
+      const contentParts = message.content
+        .map(item => formatContentItem(item))
+        .filter(part => part.trim().length > 0);
+      contentStr = contentParts.join(' ');
+    } else {
+      // Fallback
+      contentStr = String(message.content);
+    }
+    
+    // Handle tool_call_id
+    if (message.tool_call_id) {
+      if (contentStr) {
+        contentStr += ` [tool_call_id: ${message.tool_call_id}]`;
+      } else {
+        contentStr = `[tool_call_id: ${message.tool_call_id}]`;
+      }
+    }
+    
+    // Format as role: content
+    if (contentStr.trim()) {
+      lines.push(`${role}:`);
+      // Indent content (2 spaces for YAML-like style)
+      const indentedContent = contentStr.split('\n').map(line => `  ${line}`).join('\n');
+      lines.push(indentedContent);
+    } else {
+      // Empty content - just show role
+      lines.push(`${role}:`);
+    }
+    
+    // Add empty line separator between messages
+    lines.push('');
+  }
+  
+  return lines.join('\n').trim();
+}
+
+/**
+ * Format a single content item for the chat log
+ * @param {Object} item - Content item object
+ * @returns {string} Formatted string representation
+ */
+function formatContentItem(item) {
+  if (!item || typeof item !== 'object') {
+    return '';
+  }
+  
+  const parts = [];
+  
+  // Handle text content
+  if (item.type === 'text' && item.text) {
+    parts.push(item.text);
+  }
+  
+  // Handle image URLs
+  if (item.image_url && item.image_url.url) {
+    parts.push(`[image_url: ${item.image_url.url}]`);
+  }
+  
+  // Handle tool calls
+  if (item.type === 'tool_call' || item.name) {
+    const toolParts = [];
+    if (item.name) toolParts.push(`tool: ${item.name}`);
+    if (item.arguments) {
+      toolParts.push(`arguments: ${JSON.stringify(item.arguments)}`);
+    }
+    if (toolParts.length > 0) {
+      parts.push(`[${toolParts.join(', ')}]`);
+    }
+  }
+  
+  // Handle tool results
+  if (item.type === 'tool_result' || item.result !== undefined) {
+    const resultStr = typeof item.result === 'string' 
+      ? item.result 
+      : JSON.stringify(item.result);
+    parts.push(`[tool_result: ${resultStr}]`);
+  }
+  
+  // Handle source references
+  if (item.source) {
+    const sourceParts = [];
+    if (item.source.url) sourceParts.push(`url: ${item.source.url}`);
+    if (item.source.media_type) sourceParts.push(`media_type: ${item.source.media_type}`);
+    if (sourceParts.length > 0) {
+      parts.push(`[source: ${sourceParts.join(', ')}]`);
+    }
+  }
+  
+  // Handle other types
+  if (parts.length === 0 && item.type) {
+    parts.push(`[${item.type}]`);
+  }
+  
+  return parts.join(' ');
+}
+
+export default {
+  toString
+};
+

package/src/types/conversation.json

@@ -0,0 +1,51 @@
+{
+  "type": "array",
+  "items": {
+    "type": "object",
+    "properties": {
+      "content": {
+        "oneOf": [
+          { "type": "string" },
+          { "type": "null" },
+          {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "type": { "type": "string" },
+                "text": { "type": "string" },
+                "image_url": { "type": "object", "properties": { "url": { "type": "string" } } },
+                "name": { "type": "string" },
+                "arguments": { "type": "object" },
+                "result": {
+                  "anyOf": [
+                    { "type": "string" },
+                    { "type": "number" },
+                    { "type": "object" },
+                    { "type": "array" },
+                    { "type": "boolean" },
+                    { "type": "null" }
+                  ]
+                },
+                "source": {
+                  "type": "object",
+                  "properties": {
+                    "url": { "type": "string" },
+                    "data": { "type": "string" },
+                    "media_type": { "type": "string" }
+                  }
+                }
+              },
+              "required": ["type"],
+              "additionalProperties": true
+            }
+          }
+        ]
+      },
+      "tool_call_id": { "type": "string", "nullable": true },
+      "role": { "type": "string", "enum": ["user", "assistant", "system", "tool", "developer"] }
+    },
+    "additionalProperties": true
+  }
+}
+

package/src/types/message.converters.js

@@ -0,0 +1,45 @@
+/**
+ * Type converters for the 'message' type
+ * Converts message objects to strings by extracting all text content
+ */
+
+import { extractTextFromContent } from '../utilities/helpers.js';
+
+/**
+ * Convert a message object to a string
+ * Joins all text content from the message's content array
+ * @param {Object} message - Message object with content field
+ * @param {string} separator - Optional separator (not used for single messages)
+ * @returns {string} All text content joined together
+ */
+export function toString(message, separator) {
+  if (!message || typeof message !== 'object') {
+    return String(message || '');
+  }
+  
+  return extractTextFromContent(message.content);
+}
+
+/**
+ * Convert a message object to a boolean
+ * @param {Object} message - Message object with content field
+ * @returns {boolean} True if the message is not undefined or null 
+ */
+export function toBoolean(message) {
+  if (!message || typeof message !== 'object') {
+    return false;
+  }
+  
+  return message.content !== undefined && message.content !== null;
+}
+
+
+/**
+ * Export the converters object
+ * Each key corresponds to a conversion operation (e.g., 'toString')
+ */
+export default {
+  toString,
+  toBoolean
+};
+

package/src/types/message.json

@@ -0,0 +1,47 @@
+{
+  "type": "object",
+  "properties": {
+    "content": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "null" },
+        {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "type": { "type": "string" },
+              "text": { "type": "string" },
+              "image_url": { "type": "object", "properties": { "url": { "type": "string" } } },
+              "name": { "type": "string" },
+              "arguments": { "type": "object" },
+              "result": {
+                "anyOf": [
+                  { "type": "string" },
+                  { "type": "number" },
+                  { "type": "object" },
+                  { "type": "array" },
+                  { "type": "boolean" },
+                  { "type": "null" }
+                ]
+              },
+              "source": {
+                "type": "object",
+                "properties": {
+                  "url": { "type": "string" },
+                  "data": { "type": "string" },
+                  "media_type": { "type": "string" }
+                }
+              }
+            },
+            "required": ["type"],
+            "additionalProperties": true
+          }
+        }
+      ]
+    },
+    "tool_call_id": { "type": "string", "nullable": true },
+    "role": { "type": "string", "enum": ["user", "assistant", "system", "tool", "developer"] }
+  },
+  "additionalProperties": true
+}

package/src/types/plugin.converters.js

@@ -0,0 +1,28 @@
+/**
+ * Type converters for the 'plugin' type
+ * Converts plugin objects to string representation
+ */
+
+/**
+ * Convert a plugin object to a string representation
+ * @param {Object} plugin - Plugin object
+ * @returns {string} String representation of the plugin
+ */
+export function toString(plugin) {
+  if (!plugin || typeof plugin !== 'object') {
+    return String(plugin || '');
+  }
+  
+  const parts = [];
+  if (plugin.name) parts.push(`name: ${plugin.name}`);
+  if (plugin.description) parts.push(`description: ${plugin.description}`);
+  if (plugin.type) parts.push(`type: ${plugin.type}`);
+  
+  return parts.length > 0 ? parts.join(', ') : JSON.stringify(plugin);
+}
+
+export default {
+  toString
+};
+
+

package/src/types/plugin.json

@@ -0,0 +1,10 @@
+{
+  "type": "object",
+  "properties": {
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "schema": { "type": "object" }
+  },
+  "required": ["name", "description", "schema"],
+  "additionalProperties": true
+}

package/src/types/tool.converters.js

@@ -0,0 +1,28 @@
+/**
+ * Type converters for the 'tool' type
+ * Converts tool objects to string representation
+ */
+
+/**
+ * Convert a tool object to a string representation
+ * @param {Object} tool - Tool object
+ * @returns {string} String representation of the tool
+ */
+export function toString(tool) {
+  if (!tool || typeof tool !== 'object') {
+    return String(tool || '');
+  }
+  
+  const parts = [];
+  if (tool.name) parts.push(`name: ${tool.name}`);
+  if (tool.description) parts.push(`description: ${tool.description}`);
+  if (tool.type) parts.push(`type: ${tool.type}`);
+  
+  return parts.length > 0 ? parts.join(', ') : JSON.stringify(tool);
+}
+
+export default {
+  toString
+};
+
+

package/src/types/tool.json

@@ -0,0 +1,18 @@
+{
+  "type": "object",
+  "properties": {
+    "type": { "type": "string", "enum": ["function"] },
+    "function": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "parameters": { "type": "object" },
+        "strict": { "type": "boolean", "default": false }
+      },
+      "required": ["name"]
+    }
+  },
+  "required": ["type", "function"],
+  "additionalProperties": true
+}