@zerowidth/workbench-sdk 2.0.0-alpha.0

package/src/integrations/airtable.js

@@ -0,0 +1,192 @@
+import axios from 'axios';
+import { emitAPICallEvent } from '../utilities/sanitizeAPICall.js';
+
+export default class AirtableIntegration {
+    constructor(apiKey, options = {}) {
+        this.apiKey = apiKey;
+        this.options = {
+            baseURL: 'https://api.airtable.com/v0',
+            timeout: 30000,
+            ...options
+        };
+    }
+
+    /**
+     * Build the API URL for a table or record
+     * @param {string} baseId - The Airtable base ID
+     * @param {string} tableName - The table name or ID
+     * @param {string} [recordId] - Optional record ID
+     * @returns {string} The full API URL
+     */
+    _buildUrl(baseId, tableName, recordId = null) {
+        const encodedTable = encodeURIComponent(tableName);
+        let url = `${this.options.baseURL}/${baseId}/${encodedTable}`;
+        if (recordId) {
+            url = `${url}/${recordId}`;
+        }
+        return url;
+    }
+
+    /**
+     * Make an API request with error handling
+     * @param {Object} config - Axios request config
+     * @returns {Promise<Object>} Response data
+     */
+    async _request(config) {
+        const requestHeaders = { 'Authorization': `Bearer ${this.apiKey}`, 'Content-Type': 'application/json', ...config.headers };
+        const startTime = Date.now();
+
+        try {
+            const response = await axios({
+                ...config,
+                headers: requestHeaders,
+                timeout: this.options.timeout
+            });
+
+            await emitAPICallEvent(this._engineConfig, {
+                timestamp: startTime, integration: 'airtable', 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: 'airtable', 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 status = error.response.status;
+                const errorData = error.response.data?.error || {};
+                const errorType = errorData.type || 'UNKNOWN_ERROR';
+                const errorMessage = errorData.message || error.response.statusText;
+                throw new Error(`Airtable API error (${status}): ${errorType} - ${errorMessage}`);
+            } else if (error.request) {
+                throw new Error('Airtable API error: No response received');
+            } else {
+                throw new Error(`Airtable API error: ${error.message}`);
+            }
+        }
+    }
+
+    /**
+     * List records from a table
+     * @param {string} baseId - The Airtable base ID
+     * @param {string} tableName - The table name or ID
+     * @param {Object} [params] - Query parameters
+     * @returns {Promise<Object>} Response with records and optional offset
+     */
+    async listRecords(baseId, tableName, params = {}) {
+        const url = this._buildUrl(baseId, tableName);
+        const queryParams = {};
+
+        if (params.filterFormula) {
+            queryParams.filterByFormula = params.filterFormula;
+        }
+        if (params.sortField) {
+            queryParams['sort[0][field]'] = params.sortField;
+            queryParams['sort[0][direction]'] = params.sortDirection || 'asc';
+        }
+        if (params.maxRecords) {
+            queryParams.maxRecords = params.maxRecords;
+        }
+        if (params.pageSize) {
+            queryParams.pageSize = Math.min(params.pageSize, 100);
+        }
+        if (params.offset) {
+            queryParams.offset = params.offset;
+        }
+        if (params.view) {
+            queryParams.view = params.view;
+        }
+        if (params.fields && Array.isArray(params.fields)) {
+            params.fields.forEach((field, i) => {
+                queryParams[`fields[${i}]`] = field;
+            });
+        }
+
+        return await this._request({
+            method: 'GET',
+            url,
+            params: queryParams
+        });
+    }
+
+    /**
+     * Get a single record by ID
+     * @param {string} baseId - The Airtable base ID
+     * @param {string} tableName - The table name or ID
+     * @param {string} recordId - The record ID
+     * @returns {Promise<Object>} The record
+     */
+    async getRecord(baseId, tableName, recordId) {
+        const url = this._buildUrl(baseId, tableName, recordId);
+        return await this._request({
+            method: 'GET',
+            url
+        });
+    }
+
+    /**
+     * Create a new record
+     * @param {string} baseId - The Airtable base ID
+     * @param {string} tableName - The table name or ID
+     * @param {Object} fields - Field name/value pairs
+     * @param {Object} [options] - Additional options
+     * @returns {Promise<Object>} The created record
+     */
+    async createRecord(baseId, tableName, fields, options = {}) {
+        const url = this._buildUrl(baseId, tableName);
+        const data = { fields };
+        if (options.typecast) {
+            data.typecast = true;
+        }
+
+        return await this._request({
+            method: 'POST',
+            url,
+            data
+        });
+    }
+
+    /**
+     * Update an existing record
+     * @param {string} baseId - The Airtable base ID
+     * @param {string} tableName - The table name or ID
+     * @param {string} recordId - The record ID
+     * @param {Object} fields - Field name/value pairs to update
+     * @param {Object} [options] - Additional options
+     * @returns {Promise<Object>} The updated record
+     */
+    async updateRecord(baseId, tableName, recordId, fields, options = {}) {
+        const url = this._buildUrl(baseId, tableName, recordId);
+        const data = { fields };
+        if (options.typecast) {
+            data.typecast = true;
+        }
+
+        return await this._request({
+            method: 'PATCH',
+            url,
+            data
+        });
+    }
+
+    /**
+     * Delete a record
+     * @param {string} baseId - The Airtable base ID
+     * @param {string} tableName - The table name or ID
+     * @param {string} recordId - The record ID
+     * @returns {Promise<Object>} Deletion confirmation
+     */
+    async deleteRecord(baseId, tableName, recordId) {
+        const url = this._buildUrl(baseId, tableName, recordId);
+        return await this._request({
+            method: 'DELETE',
+            url
+        });
+    }
+}

package/src/integrations/confluence.js

@@ -0,0 +1,87 @@
+import axios from 'axios';
+import { emitAPICallEvent } from '../utilities/sanitizeAPICall.js';
+
+export default class ConfluenceIntegration {
+    constructor(config, options = {}) {
+        if (typeof config === 'object') {
+            this.email = config.email;
+            this.apiToken = config.api_token;
+            this.domain = config.domain; // e.g. yourcompany.atlassian.net
+        } else {
+            throw new Error('Confluence integration requires an object with email, api_token, and domain');
+        }
+        this.options = {
+            baseURL: `https://${this.domain}/wiki/api/v2`,
+            timeout: 30000,
+            ...options
+        };
+    }
+
+    async _request(config) {
+        const auth = Buffer.from(`${this.email}:${this.apiToken}`).toString('base64');
+        const requestHeaders = {
+            'Authorization': `Basic ${auth}`,
+            'Accept': 'application/json',
+            'Content-Type': 'application/json',
+            ...config.headers
+        };
+        const startTime = Date.now();
+
+        try {
+            const response = await axios({
+                ...config,
+                headers: requestHeaders,
+                timeout: this.options.timeout
+            });
+
+            await emitAPICallEvent(this._engineConfig, {
+                timestamp: startTime, integration: 'confluence', 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: 'confluence', 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(`Confluence API error (${error.response.status}): ${msg}`);
+            }
+            throw new Error(`Confluence API error: ${error.message}`);
+        }
+    }
+
+    async search(query, options = {}) {
+        const params = {
+            query,
+            limit: options.limit ?? 25
+        };
+        if (options.cursor) params.cursor = options.cursor;
+        if (options.spaceKey) params.spaceKey = options.spaceKey;
+
+        // CQL search via v1 API (v2 doesn't have full CQL support yet)
+        const searchUrl = `https://${this.domain}/wiki/rest/api/content/search`;
+        return await this._request({
+            method: 'GET',
+            url: searchUrl,
+            params: { cql: query, limit: params.limit, start: options.start ?? 0 }
+        });
+    }
+
+    async getPage(pageId, options = {}) {
+        const params = {};
+        if (options.bodyFormat) params['body-format'] = options.bodyFormat;
+
+        return await this._request({
+            method: 'GET',
+            url: `${this.options.baseURL}/pages/${pageId}`,
+            params
+        });
+    }
+}

package/src/integrations/firecrawl.js

@@ -0,0 +1,157 @@
+import axios from 'axios';
+import { emitAPICallEvent } from '../utilities/sanitizeAPICall.js';
+
+export default class FirecrawlIntegration {
+    constructor(apiKey, options = {}) {
+        this.apiKey = apiKey;
+        this.options = {
+            baseURL: 'https://api.firecrawl.dev/v2',
+            timeout: 60000, // Longer timeout for scraping operations
+            ...options
+        };
+    }
+
+    /**
+     * Scrape a single URL with various options
+     * @param {Object} params - Scraping parameters
+     * @returns {Promise<Object>} Scraping response
+     */
+    async scrape(params = {}) {
+        try {
+            const url = `${this.options.baseURL}/scrape`;
+
+            // Remove any params that are null, undefined, or empty strings
+            Object.keys(params).forEach(key => {
+                if (params[key] === '') {
+                    delete params[key];
+                }
+                if (params[key] === null) {
+                    delete params[key];
+                }
+                if (params[key] === undefined) {
+                    delete params[key];
+                }
+                if (Array.isArray(params[key]) && params[key].length === 0) {
+                    delete params[key];
+                }
+            });
+
+            const requestHeaders = { 'Content-Type': 'application/json', 'Authorization': `Bearer ${this.apiKey}` };
+            const startTime = Date.now();
+
+            const response = await axios({
+                url: url,
+                method: 'POST',
+                headers: requestHeaders,
+                data: params,
+                timeout: this.options.timeout
+            });
+
+            await emitAPICallEvent(this._engineConfig, {
+                timestamp: startTime, integration: 'firecrawl', nodeId: null, nodeType: null,
+                request: { method: 'POST', url, headers: requestHeaders, body: params },
+                response: { status: response.status, statusText: response.statusText },
+                duration: Date.now() - startTime, error: null
+            });
+
+            if (response.status >= 400) {
+                throw new Error(`Firecrawl API error: ${response.status} - ${response.data?.error || response.statusText}`);
+            }
+
+            return response.data;
+
+        } catch (error) {
+            // Note: emitAPICallEvent for error case is handled by the catch in the caller
+            // since errors from axios.post throw before we can capture the response
+            if (error.response) {
+                const status = error.response.status;
+                const statusText = error.response.statusText;
+                const responseData = error.response.data;
+                
+                let errorMessage = `Firecrawl API Error (${status} ${statusText})`;
+                if (responseData?.error) {
+                    errorMessage += `: ${responseData.error}`;
+                }
+                
+                throw new Error(errorMessage);
+            } else if (error.request) {
+                throw new Error('Firecrawl API Error: No response received');
+            } else {
+                throw new Error(`Firecrawl API Error: ${error.message}`);
+            }
+        }
+    }
+
+    /**
+     * Helper function to convert comma-separated string to array
+     * @param {string|Array} input - String or array input
+     * @returns {Array} Array of strings
+     */
+    static stringToArray(input) {
+        if (Array.isArray(input)) {
+            return input;
+        }
+        if (typeof input === 'string') {
+            return input.split(',').map(item => item.trim()).filter(item => item.length > 0);
+        }
+        return [];
+    }
+
+    /**
+     * Helper function to build query parameters with array handling
+     * @param {Object} params - Raw parameters
+     * @returns {Object} Processed parameters
+     */
+    static processParams(params) {
+        const processed = { ...params };
+        
+        // Handle parameter name mappings (snake_case input names to API parameter names)
+        const paramMappings = {
+            'include_tags': 'includeTags',
+            'exclude_tags': 'excludeTags',
+            'only_main_content': 'onlyMainContent',
+            'max_age': 'maxAge',
+            'wait_for': 'waitFor',
+            'mobile_device': 'mobile',
+            'skip_tls_verification': 'skipTlsVerification',
+            'remove_base64_images': 'removeBase64Images',
+            'block_ads': 'blockAds',
+            'store_in_cache': 'storeInCache',
+            'zero_data_retention': 'zeroDataRetention'
+        };
+        
+        // Apply parameter name mappings
+        Object.entries(paramMappings).forEach(([inputKey, apiKey]) => {
+            if (processed[inputKey] !== undefined) {
+                processed[apiKey] = processed[inputKey];
+                delete processed[inputKey]; // Remove the old key
+            }
+        });
+        
+        // Fields that should be converted from comma-separated strings to arrays
+        const arrayFields = [
+            'includeTags', 'excludeTags', 'formats'
+        ];
+
+        arrayFields.forEach(field => {
+            if (processed[field] !== undefined) {
+                const arrayValue = this.stringToArray(processed[field]);
+                if (arrayValue.length > 0) {
+                    processed[field] = arrayValue;
+                }
+            }
+        });
+
+        // Handle formats - convert string to array of objects if needed
+        if (processed.formats && Array.isArray(processed.formats)) {
+            processed.formats = processed.formats.map(format => {
+                if (typeof format === 'string') {
+                    return { type: format };
+                }
+                return format;
+            });
+        }
+
+        return processed;
+    }
+}

package/src/integrations/github.js

@@ -0,0 +1,80 @@
+import axios from 'axios';
+import { emitAPICallEvent } from '../utilities/sanitizeAPICall.js';
+
+export default class GithubIntegration {
+    constructor(apiKey, options = {}) {
+        this.apiKey = apiKey;
+        this.options = {
+            baseURL: 'https://api.github.com',
+            timeout: 30000,
+            ...options
+        };
+    }
+
+    async _request(config) {
+        const requestHeaders = {
+            'Authorization': `Bearer ${this.apiKey}`,
+            'Accept': 'application/vnd.github+json',
+            'X-GitHub-Api-Version': '2022-11-28',
+            'Content-Type': 'application/json',
+            ...config.headers
+        };
+        const startTime = Date.now();
+
+        try {
+            const response = await axios({
+                ...config,
+                headers: requestHeaders,
+                timeout: this.options.timeout
+            });
+
+            await emitAPICallEvent(this._engineConfig, {
+                timestamp: startTime, integration: 'github', 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: 'github', 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(`GitHub API error (${error.response.status}): ${msg}`);
+            }
+            throw new Error(`GitHub API error: ${error.message}`);
+        }
+    }
+
+    async createIssue(owner, repo, title, options = {}) {
+        const data = { title };
+        if (options.body) data.body = options.body;
+        if (options.labels) data.labels = options.labels;
+        if (options.assignees) data.assignees = options.assignees;
+
+        return await this._request({
+            method: 'POST',
+            url: `${this.options.baseURL}/repos/${owner}/${repo}/issues`,
+            data
+        });
+    }
+
+    async listIssues(owner, repo, options = {}) {
+        const params = {};
+        if (options.state) params.state = options.state;
+        if (options.labels) params.labels = options.labels;
+        if (options.per_page) params.per_page = options.per_page;
+        if (options.page) params.page = options.page;
+
+        return await this._request({
+            method: 'GET',
+            url: `${this.options.baseURL}/repos/${owner}/${repo}/issues`,
+            params
+        });
+    }
+}

package/src/integrations/google_custom_search.js

@@ -0,0 +1,136 @@
+import axios from 'axios';
+import { emitAPICallEvent } from '../utilities/sanitizeAPICall.js';
+
+export default class GoogleCustomSearchIntegration {
+    constructor(apiKey, options = {}) {
+        this.apiKey = apiKey?.key;
+        this.cx = apiKey?.cx;
+
+        if(!this.apiKey) {
+            throw new Error('Google Custom Search API key is required');
+        }
+
+        this.options = {
+            baseURL: 'https://www.googleapis.com/customsearch/v1',
+            timeout: 30000,
+            ...options
+        };
+    }
+
+    /**
+     * Perform a custom search using Google Custom Search API
+     * @param {Object} params - Search parameters
+     * @returns {Promise<Object>} Search response
+     */
+    async search(params = {}) {
+        try {
+            const url = this.options.baseURL;
+
+            // Remove any params that are null, undefined, or empty strings
+            Object.keys(params).forEach(key => {
+                if (params[key] === '') {
+                    delete params[key];
+                }
+                if (params[key] === null) {
+                    delete params[key];
+                }
+                if (params[key] === undefined) {
+                    delete params[key];
+                }
+                if (Array.isArray(params[key]) && params[key].length === 0) {
+                    delete params[key];
+                }
+            });
+
+            const queryParams = { key: this.apiKey, cx: this.cx, ...params };
+            const startTime = Date.now();
+            // Build full URL with query params for event (sanitizer will redact key)
+            const fullUrl = `${url}?${new URLSearchParams(queryParams).toString()}`;
+
+            const response = await axios({
+                url: url,
+                method: 'GET',
+                params: queryParams,
+                timeout: this.options.timeout
+            });
+
+            await emitAPICallEvent(this._engineConfig, {
+                timestamp: startTime, integration: 'google_custom_search', nodeId: null, nodeType: null,
+                request: { method: 'GET', url: fullUrl, headers: {}, body: null },
+                response: { status: response.status, statusText: response.statusText },
+                duration: Date.now() - startTime, error: null
+            });
+
+            if (response.status >= 400) {
+                throw new Error(`Google Custom Search API error: ${response.status} - ${response.data?.error?.message || response.statusText}`);
+            }
+
+            return response.data;
+
+        } catch (error) {
+            if (error.response) {
+                const status = error.response.status;
+                const statusText = error.response.statusText;
+                const responseData = error.response.data;
+                
+                let errorMessage = `Google Custom Search API Error (${status} ${statusText})`;
+                if (responseData?.error?.message) {
+                    errorMessage += `: ${responseData.error.message}`;
+                } else if (responseData?.error) {
+                    errorMessage += `: ${responseData.error}`;
+                }
+                
+                throw new Error(errorMessage);
+            } else if (error.request) {
+                throw new Error('Google Custom Search API Error: No response received');
+            } else {
+                throw new Error(`Google Custom Search API Error: ${error.message}`);
+            }
+        }
+    }
+
+    /**
+     * Helper function to convert comma-separated string to array
+     * @param {string|Array} input - String or array input
+     * @returns {Array} Array of strings
+     */
+    static stringToArray(input) {
+        if (Array.isArray(input)) {
+            return input;
+        }
+        if (typeof input === 'string') {
+            return input.split(',').map(item => item.trim()).filter(item => item.length > 0);
+        }
+        return [];
+    }
+
+    /**
+     * Helper function to build query parameters with array handling
+     * @param {Object} params - Raw parameters
+     * @returns {Object} Processed parameters
+     */
+    static processParams(params) {
+        const processed = { ...params };
+        
+        // Fields that should be converted from comma-separated strings to arrays
+        const arrayFields = [
+            'excludeTerms', 'fileType', 'rights', 'safe'
+        ];
+
+        arrayFields.forEach(field => {
+            if (processed[field] !== undefined) {
+                const arrayValue = this.stringToArray(processed[field]);
+                if (arrayValue.length > 0) {
+                    processed[field] = arrayValue.join(' ');
+                }
+            }
+        });
+
+        // Special handling for searchType - only include if it's "image"
+        if (processed.searchType && processed.searchType !== 'image') {
+            delete processed.searchType;
+        }
+
+        return processed;
+    }
+}