@zerowidth/workbench-sdk 2.0.0-alpha.0

package/src/integrations/hubspot.js

@@ -0,0 +1,282 @@
+import axios from 'axios';
+import { isOAuthKey, OAuthRefreshManager } from '../utilities/oauth.js';
+import { emitAPICallEvent } from '../utilities/sanitizeAPICall.js';
+
+export default class HubSpotIntegration {
+  constructor(oauthKey, options = {}) {
+    if (!isOAuthKey(oauthKey)) {
+      throw new Error('HubSpot integration requires an OAuth key with accessToken and onRefresh');
+    }
+
+    this.oauthKey = oauthKey;
+    this.options = {
+      baseURL: 'https://api.hubapi.com',
+      timeout: 30000,
+      ...options
+    };
+
+    // Initialize OAuth refresh manager
+    // Note: config will be set when integration is loaded with full config
+    this.refreshManager = null;
+  }
+
+  /**
+   * Set the OAuth refresh manager (called during integration loading)
+   * @param {OAuthRefreshManager} refreshManager - The refresh manager instance
+   */
+  setRefreshManager(refreshManager) {
+    this.refreshManager = refreshManager;
+  }
+
+  /**
+   * Update OAuth key (called after refresh)
+   * @param {Object} updatedKey - Updated OAuth key object
+   */
+  updateOAuthKey(updatedKey) {
+    this.oauthKey = { ...this.oauthKey, ...updatedKey };
+  }
+
+  /**
+   * Make an API request to HubSpot with automatic OAuth token refresh
+   * @param {string} method - HTTP method (GET, POST, etc.)
+   * @param {string} url - API endpoint (relative to baseURL)
+   * @param {Object} options - Request options (headers, data, params, etc.)
+   * @returns {Promise<Object>} API response data
+   */
+  async request(method, url, options = {}) {
+    if (!this.refreshManager) {
+      throw new Error('OAuth refresh manager not initialized. This integration requires engine config context.');
+    }
+
+    // Ensure absolute URL
+    const fullUrl = url.startsWith('http') ? url : `${this.options.baseURL}${url}`;
+
+    // Ensure token is valid before making request
+    this.oauthKey = await this.refreshManager.ensureValidToken('hubspot', this.oauthKey);
+    this.updateOAuthKey(this.oauthKey);
+
+    // Make request with retry logic for expired tokens
+    let lastError = null;
+    let retries = 0;
+    const maxRetries = 2; // Initial attempt + 1 retry after refresh
+
+    while (retries <= maxRetries) {
+      try {
+        const requestHeaders = {
+          'Authorization': `Bearer ${this.oauthKey.accessToken}`,
+          'Content-Type': 'application/json',
+          ...options.headers
+        };
+        const callStartTime = Date.now();
+
+        const response = await axios({
+          method,
+          url: fullUrl,
+          headers: requestHeaders,
+          data: options.data,
+          params: options.params,
+          timeout: options.timeout || this.options.timeout,
+          validateStatus: () => true // Don't throw on HTTP errors
+        });
+
+        await emitAPICallEvent(this._engineConfig, {
+          timestamp: callStartTime, integration: 'hubspot', nodeId: null, nodeType: null,
+          request: { method, url: fullUrl, headers: requestHeaders, body: options.data || null },
+          response: { status: response.status, statusText: response.statusText },
+          duration: Date.now() - callStartTime, error: null
+        });
+
+        // Check if response indicates token refresh is needed
+        if (OAuthRefreshManager.needsRefresh(response, this._checkHubSpotError)) {
+          if (retries < maxRetries) {
+            // Refresh token and retry
+            this.oauthKey = await this.refreshManager.refreshToken('hubspot', this.oauthKey);
+            this.updateOAuthKey(this.oauthKey);
+            retries++;
+            continue;
+          } else {
+            throw new Error(`HubSpot API error: ${response.status} - Token refresh failed`);
+          }
+        }
+
+        // Check for other HTTP errors
+        if (response.status >= 400) {
+          const errorMessage = this._extractErrorMessage(response);
+          throw new Error(`HubSpot API error: ${response.status} - ${errorMessage}`);
+        }
+
+        return response.data;
+      } catch (error) {
+        // If it's an OAuth refresh error, throw immediately
+        if (error.message && error.message.includes('OAuth refresh failed')) {
+          throw error;
+        }
+
+        // For other errors, try refresh if we haven't exhausted retries
+        if (retries < maxRetries && !lastError) {
+          // Might be a network error - try refreshing token once
+          try {
+            this.oauthKey = await this.refreshManager.refreshToken('hubspot', this.oauthKey);
+            this.updateOAuthKey(this.oauthKey);
+          } catch (refreshError) {
+            // Refresh failed, throw original error
+            throw error;
+          }
+          retries++;
+          continue;
+        }
+
+        // All retries exhausted or not a refresh issue
+        throw error;
+      }
+    }
+
+    throw lastError || new Error('HubSpot API request failed');
+  }
+
+  /**
+   * Check if HubSpot response indicates OAuth refresh is needed
+   * @private
+   * @param {Object} response - HTTP response object
+   * @returns {boolean} True if refresh is needed
+   */
+  _checkHubSpotError(response) {
+    if (!response || !response.data) {
+      return false;
+    }
+
+    const data = response.data;
+    
+    // Check for HubSpot-specific error codes (case-insensitive status check)
+    const status = (data.status || '').toLowerCase();
+    if (status === 'error') {
+      const message = (data.message || '').toLowerCase();
+      const category = data.category || '';
+      
+      // HubSpot error codes that indicate token refresh needed
+      const refreshErrorCodes = [
+        'INVALID_AUTHENTICATION',
+        'EXPIRED_AUTHENTICATION',
+        'TOKEN_EXPIRED',
+        'REFRESH_TOKEN_EXPIRED',
+        'INVALID_REFRESH_TOKEN'
+      ];
+
+      // Check error category (case-sensitive as HubSpot uses uppercase)
+      if (refreshErrorCodes.includes(category)) {
+        return true;
+      }
+
+      // Check message for token-related errors (case-insensitive)
+      if (message.includes('token') || 
+          message.includes('authentication') || 
+          message.includes('unauthorized') ||
+          message.includes('expired')) {
+        return true;
+      }
+    }
+
+    // Check for JSON error objects
+    if (data.error) {
+      const errorCode = data.error.code || data.error.message || '';
+      if (typeof errorCode === 'string') {
+        const lowerError = errorCode.toLowerCase();
+        if (lowerError.includes('token') || 
+            lowerError.includes('auth') || 
+            lowerError.includes('unauthorized') ||
+            lowerError.includes('expired')) {
+          return true;
+        }
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * Extract error message from HubSpot API response
+   * @private
+   * @param {Object} response - HTTP response object
+   * @returns {string} Error message
+   */
+  _extractErrorMessage(response) {
+    if (!response.data) {
+      return response.statusText || 'Unknown error';
+    }
+
+    const data = response.data;
+
+    // HubSpot error format (case-insensitive status check)
+    const status = (data.status || '').toLowerCase();
+    if (status === 'error' && data.message) {
+      return data.message;
+    }
+
+    // Standard error object
+    if (data.error) {
+      if (typeof data.error === 'string') {
+        return data.error;
+      }
+      if (data.error.message) {
+        return data.error.message;
+      }
+    }
+
+    // Fallback
+    return JSON.stringify(data);
+  }
+
+  /**
+   * Convenience methods for common operations
+   */
+
+  /**
+   * GET request
+   * @param {string} url - API endpoint
+   * @param {Object} params - Query parameters
+   * @param {Object} options - Additional request options
+   */
+  async get(url, params = {}, options = {}) {
+    return this.request('GET', url, { params, ...options });
+  }
+
+  /**
+   * POST request
+   * @param {string} url - API endpoint
+   * @param {Object} data - Request body
+   * @param {Object} options - Additional request options
+   */
+  async post(url, data = {}, options = {}) {
+    return this.request('POST', url, { data, ...options });
+  }
+
+  /**
+   * PATCH request
+   * @param {string} url - API endpoint
+   * @param {Object} data - Request body
+   * @param {Object} options - Additional request options
+   */
+  async patch(url, data = {}, options = {}) {
+    return this.request('PATCH', url, { data, ...options });
+  }
+
+  /**
+   * PUT request
+   * @param {string} url - API endpoint
+   * @param {Object} data - Request body
+   * @param {Object} options - Additional request options
+   */
+  async put(url, data = {}, options = {}) {
+    return this.request('PUT', url, { data, ...options });
+  }
+
+  /**
+   * DELETE request
+   * @param {string} url - API endpoint
+   * @param {Object} options - Additional request options
+   */
+  async delete(url, options = {}) {
+    return this.request('DELETE', url, options);
+  }
+}
+

package/src/integrations/jira.js

@@ -0,0 +1,115 @@
+import axios from 'axios';
+import { emitAPICallEvent } from '../utilities/sanitizeAPICall.js';
+
+export default class JiraIntegration {
+    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('Jira integration requires an object with email, api_token, and domain');
+        }
+        this.options = {
+            baseURL: `https://${this.domain}/rest/api/3`,
+            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: 'jira', 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: 'jira', 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 errors = error.response.data?.errorMessages || [];
+                const fieldErrors = error.response.data?.errors || {};
+                const msg = errors.length > 0
+                    ? errors.join('; ')
+                    : Object.entries(fieldErrors).map(([k, v]) => `${k}: ${v}`).join('; ') || error.response.statusText;
+                throw new Error(`Jira API error (${error.response.status}): ${msg}`);
+            }
+            throw new Error(`Jira API error: ${error.message}`);
+        }
+    }
+
+    async createIssue(projectKey, summary, options = {}) {
+        const fields = {
+            project: { key: projectKey },
+            summary,
+            issuetype: { name: options.issueType || 'Task' }
+        };
+
+        if (options.description) {
+            fields.description = {
+                type: 'doc',
+                version: 1,
+                content: [{
+                    type: 'paragraph',
+                    content: [{ type: 'text', text: options.description }]
+                }]
+            };
+        }
+        if (options.assigneeId) fields.assignee = { accountId: options.assigneeId };
+        if (options.priority) fields.priority = { name: options.priority };
+        if (options.labels) fields.labels = options.labels;
+        if (options.parentKey) fields.parent = { key: options.parentKey };
+
+        return await this._request({
+            method: 'POST',
+            url: `${this.options.baseURL}/issue`,
+            data: { fields }
+        });
+    }
+
+    async listIssues(jql, options = {}) {
+        const data = {
+            jql,
+            maxResults: options.maxResults ?? 25,
+            startAt: options.startAt ?? 0,
+            fields: options.fields || ['summary', 'status', 'assignee', 'priority', 'created', 'updated', 'issuetype']
+        };
+
+        return await this._request({
+            method: 'POST',
+            url: `${this.options.baseURL}/search`,
+            data
+        });
+    }
+
+    async updateIssue(issueKey, fields) {
+        return await this._request({
+            method: 'PUT',
+            url: `${this.options.baseURL}/issue/${issueKey}`,
+            data: { fields }
+        });
+    }
+}

package/src/integrations/knowledge-base-interface.js

@@ -0,0 +1,119 @@
+/**
+ * Standard interface for knowledge base integrations
+ * All knowledge base integrations must implement this interface
+ * to ensure compatibility across different backends (SQLite, Pinecone, Weaviate, etc.)
+ */
+
+export class KnowledgeBaseInterface {
+  /**
+   * Execute a raw query against the knowledge base
+   * @param {string} query - SQL or query string
+   * @param {Array} params - Query parameters
+   * @param {string} operation - Type of operation (SELECT, INSERT, UPDATE, DELETE)
+   * @returns {Promise<Object>} Query result
+   */
+  async query(query, params = [], operation = 'SELECT') {
+    throw new Error('query() method must be implemented by knowledge base integration');
+  }
+
+  /**
+   * Execute a SELECT query
+   * @param {string} query - SQL SELECT query
+   * @param {Array} params - Query parameters
+   * @returns {Promise<Array>} Query results
+   */
+  async select(query, params = []) {
+    throw new Error('select() method must be implemented by knowledge base integration');
+  }
+
+  /**
+   * Execute an INSERT query
+   * @param {string} query - SQL INSERT query
+   * @param {Array} params - Query parameters
+   * @returns {Promise<Object>} Insert result with lastID
+   */
+  async insert(query, params = []) {
+    throw new Error('insert() method must be implemented by knowledge base integration');
+  }
+
+  /**
+   * Execute an UPDATE query
+   * @param {string} query - SQL UPDATE query
+   * @param {Array} params - Query parameters
+   * @returns {Promise<Object>} Update result with changes count
+   */
+  async update(query, params = []) {
+    throw new Error('update() method must be implemented by knowledge base integration');
+  }
+
+  /**
+   * Execute a DELETE query
+   * @param {string} query - SQL DELETE query
+   * @param {Array} params - Query parameters
+   * @returns {Promise<Object>} Delete result with changes count
+   */
+  async delete(query, params = []) {
+    throw new Error('delete() method must be implemented by knowledge base integration');
+  }
+
+  /**
+   * Perform semantic search using vector similarity
+   * @param {string} query - Text query to search for
+   * @param {Object} options - Search options
+   * @param {number} options.limit - Maximum number of results
+   * @param {number} options.similarity_threshold - Minimum similarity score
+   * @param {string} options.document_id - Filter by specific document
+   * @returns {Promise<Array>} Search results with similarity scores
+   */
+  async semanticSearch(query, options = {}) {
+    throw new Error('semanticSearch() method must be implemented by knowledge base integration');
+  }
+
+  /**
+   * Get the embedding model used by this knowledge base
+   * @returns {Promise<string>} Embedding model name
+   */
+  async getEmbeddingModel() {
+    throw new Error('getEmbeddingModel() method must be implemented by knowledge base integration');
+  }
+
+  /**
+   * Get basic statistics about the knowledge base
+   * @returns {Promise<Object>} Statistics object
+   */
+  async getStats() {
+    throw new Error('getStats() method must be implemented by knowledge base integration');
+  }
+
+  /**
+   * Validate the knowledge base schema
+   * @returns {Promise<Object>} Validation result
+   */
+  async validateSchema() {
+    throw new Error('validateSchema() method must be implemented by knowledge base integration');
+  }
+
+  /**
+   * Get database schema information
+   * @returns {Promise<Object>} Schema information
+   */
+  async getSchema() {
+    throw new Error('getSchema() method must be implemented by knowledge base integration');
+  }
+
+  /**
+   * Connect to the knowledge base
+   * @returns {Promise<void>}
+   */
+  async connect() {
+    throw new Error('connect() method must be implemented by knowledge base integration');
+  }
+
+  /**
+   * Disconnect from the knowledge base and clean up resources
+   * @returns {Promise<void>}
+   */
+  async disconnect() {
+    throw new Error('disconnect() method must be implemented by knowledge base integration');
+  }
+}

package/src/integrations/linear.js

@@ -0,0 +1,134 @@
+import axios from 'axios';
+import { emitAPICallEvent } from '../utilities/sanitizeAPICall.js';
+
+export default class LinearIntegration {
+    constructor(apiKey, options = {}) {
+        this.apiKey = apiKey;
+        this.options = {
+            baseURL: 'https://api.linear.app',
+            timeout: 30000,
+            ...options
+        };
+    }
+
+    async _graphql(query, variables = {}) {
+        const requestHeaders = { 'Authorization': this.apiKey, 'Content-Type': 'application/json' };
+        const startTime = Date.now();
+        const data = { query, variables };
+
+        try {
+            const response = await axios({
+                method: 'POST',
+                url: `${this.options.baseURL}/graphql`,
+                headers: requestHeaders,
+                data,
+                timeout: this.options.timeout
+            });
+
+            await emitAPICallEvent(this._engineConfig, {
+                timestamp: startTime, integration: 'linear', nodeId: null, nodeType: null,
+                request: { method: 'POST', url: `${this.options.baseURL}/graphql`, headers: requestHeaders, body: data },
+                response: { status: response.status, statusText: response.statusText },
+                duration: Date.now() - startTime, error: null
+            });
+
+            if (response.data.errors) {
+                throw new Error(`Linear API error: ${response.data.errors.map(e => e.message).join('; ')}`);
+            }
+
+            return response.data.data;
+        } catch (error) {
+            if (error.message?.startsWith('Linear API error')) throw error;
+            await emitAPICallEvent(this._engineConfig, {
+                timestamp: startTime, integration: 'linear', nodeId: null, nodeType: null,
+                request: { method: 'POST', url: `${this.options.baseURL}/graphql`, headers: requestHeaders, body: data },
+                response: { status: error.response?.status || 0, statusText: error.response?.statusText || 'Error' },
+                duration: Date.now() - startTime, error: error.message
+            });
+            if (error.response) {
+                throw new Error(`Linear API error (${error.response.status}): ${error.response.statusText}`);
+            }
+            throw new Error(`Linear API error: ${error.message}`);
+        }
+    }
+
+    async createIssue(teamId, title, options = {}) {
+        const mutation = `
+            mutation IssueCreate($input: IssueCreateInput!) {
+                issueCreate(input: $input) {
+                    success
+                    issue {
+                        id
+                        identifier
+                        title
+                        url
+                        state { name }
+                        priority
+                        createdAt
+                    }
+                }
+            }
+        `;
+
+        const input = { teamId, title };
+        if (options.description) input.description = options.description;
+        if (options.priority) input.priority = options.priority;
+        if (options.assigneeId) input.assigneeId = options.assigneeId;
+        if (options.labelIds) input.labelIds = options.labelIds;
+        if (options.stateId) input.stateId = options.stateId;
+
+        const result = await this._graphql(mutation, { input });
+        return result.issueCreate;
+    }
+
+    async listIssues(options = {}) {
+        const query = `
+            query Issues($filter: IssueFilter, $first: Int, $after: String) {
+                issues(filter: $filter, first: $first, after: $after) {
+                    nodes {
+                        id
+                        identifier
+                        title
+                        url
+                        state { name }
+                        priority
+                        assignee { name email }
+                        createdAt
+                        updatedAt
+                    }
+                    pageInfo { hasNextPage endCursor }
+                }
+            }
+        `;
+
+        const variables = {};
+        if (options.first) variables.first = options.first;
+        if (options.after) variables.after = options.after;
+        if (options.filter) variables.filter = options.filter;
+
+        const result = await this._graphql(query, variables);
+        return result.issues;
+    }
+
+    async updateIssue(issueId, updates) {
+        const mutation = `
+            mutation IssueUpdate($id: String!, $input: IssueUpdateInput!) {
+                issueUpdate(id: $id, input: $input) {
+                    success
+                    issue {
+                        id
+                        identifier
+                        title
+                        url
+                        state { name }
+                        priority
+                        updatedAt
+                    }
+                }
+            }
+        `;
+
+        const result = await this._graphql(mutation, { id: issueId, input: updates });
+        return result.issueUpdate;
+    }
+}