@unboundcx/sdk 1.0.0

package/base.js

@@ -0,0 +1,263 @@
+/* eslint-disable indent */
+/* eslint-disable prettier/prettier */
+
+/*
+ * Base SDK Class with Transport Plugin System
+ * 
+ * Optional Dependencies:
+ * - mime-types: For accurate MIME type detection (automatically imported if available)
+ *
+ * This package is optional and the SDK will gracefully fall back to built-in MIME type
+ * detection if not installed. For best MIME type accuracy, it's recommended to install:
+ *
+ * npm install mime-types
+ */
+
+export class BaseSDK {
+  constructor(options = {}) {
+    // Support both object and legacy positional parameters for backwards compatibility
+    if (typeof options === 'string') {
+      // Legacy positional parameters: (namespace, callId, token, fwRequestId)
+      this.namespace = options || process?.env?.namespace;
+      this.callId = arguments[1];
+      this.token = arguments[2];
+      this.fwRequestId = arguments[3];
+    } else {
+      // New object-based parameters
+      const { namespace, callId, token, fwRequestId } = options;
+      this.namespace = namespace || process?.env?.namespace;
+      this.callId = callId;
+      this.token = token;
+      this.fwRequestId = fwRequestId;
+    }
+    
+    this.transports = new Map();
+    this._initializeEnvironment();
+  }
+
+  _initializeEnvironment() {
+    if (typeof window === 'undefined') {
+      // Server-side (Node.js)
+      this.environment = 'node';
+      this.baseURL = `https://${this.namespace ? this.namespace : 'login'}.${
+        process.env?.API_BASE_URL
+      }`;
+    } else {
+      // Client-side (browser)
+      this.environment = 'browser';
+      this.baseUrl = this.baseUrl || process?.env?.API_BASE_URL;
+      if (this.baseUrl && !this.baseUrl.startsWith('api.')) {
+        this.baseUrl = `api.${this.baseUrl}`;
+      }
+      this.setNamespace(this.namespace);
+    }
+  }
+
+  setToken(token) {
+    this.token = token;
+  }
+
+  setNamespace(namespace) {
+    this.namespace = namespace;
+    
+    if (this.environment === 'node') {
+      this.baseURL = `https://${this.namespace ? this.namespace : 'login'}.${
+        process.env?.API_BASE_URL
+      }`;
+    } else {
+      this.fullUrl = `https://${this.namespace}.${this.baseUrl}`;
+    }
+  }
+
+  addTransport(transport) {
+    if (!transport || typeof transport.request !== 'function') {
+      throw new Error('Transport must have a request method');
+    }
+    
+    const priority = transport.getPriority ? transport.getPriority() : 50;
+    const name = transport.name || `transport_${Date.now()}`;
+    
+    this.transports.set(name, {
+      transport,
+      priority
+    });
+  }
+
+  removeTransport(name) {
+    this.transports.delete(name);
+  }
+
+  async _getAvailableTransport(forceFetch = false) {
+    if (forceFetch) {
+      return null; // Use built-in HTTP
+    }
+
+    // Sort transports by priority (lower number = higher priority)
+    const sortedTransports = Array.from(this.transports.values())
+      .sort((a, b) => a.priority - b.priority);
+
+    for (const { transport } of sortedTransports) {
+      try {
+        if (transport.isAvailable && await transport.isAvailable()) {
+          return transport;
+        }
+      } catch (err) {
+        console.debug(`Transport ${transport.name} not available:`, err.message);
+        continue;
+      }
+    }
+
+    return null; // Fall back to HTTP
+  }
+
+  validateParams(params, schema) {
+    for (const key in schema) {
+      if (params[key] === undefined && schema[key].required) {
+        throw new Error(`Missing required parameter ${key}`);
+      }
+
+      if (params[key] !== undefined) {
+        const expectedType = schema[key].type;
+        const actualValue = params[key];
+        let isValidType = false;
+
+        if (expectedType === 'array') {
+          isValidType = Array.isArray(actualValue);
+        } else {
+          isValidType = typeof actualValue === expectedType;
+        }
+
+        if (!isValidType) {
+          const actualType = Array.isArray(actualValue)
+            ? 'array'
+            : typeof actualValue;
+          throw new Error(
+            `Invalid type for parameter ${key}: expected ${expectedType}, got ${actualType}`,
+          );
+        }
+      }
+    }
+  }
+
+  async _fetch(endpoint, method, params = {}, forceFetch = false) {
+    const { body, query, headers = {} } = params;
+
+    this.validateParams(
+      { endpoint, method, body, query, headers },
+      {
+        endpoint: { type: 'string', required: true },
+        method: { type: 'string', required: true },
+        body: { type: 'object', required: false },
+        query: { type: 'object', required: false },
+        headers: { type: 'object', required: false },
+      },
+    );
+
+    // Try transport plugins first
+    const transport = await this._getAvailableTransport(forceFetch);
+    if (transport) {
+      try {
+        const result = await transport.request(endpoint, method, params, {
+          namespace: this.namespace,
+          token: this.token,
+          callId: this.callId,
+          fwRequestId: this.fwRequestId,
+          baseURL: this.baseURL || this.fullUrl,
+        });
+        return result;
+      } catch (err) {
+        console.warn(`Transport ${transport.name} failed, falling back to HTTP:`, err.message);
+        // Fall through to HTTP
+      }
+    }
+
+    // Built-in HTTP transport (fallback)
+    return this._httpRequest(endpoint, method, params);
+  }
+
+  async _httpRequest(endpoint, method, params = {}) {
+    const { body, query, headers = {} } = params;
+    
+    const options = {
+      method,
+      headers: {
+        // Only set Content-Type if not already provided (check both cases)
+        ...(headers?.['Content-Type'] || headers?.['content-type']
+          ? {}
+          : { 'Content-Type': 'application/json' }),
+        ...headers,
+      },
+    };
+
+    // Add auth headers
+    if (this.token) {
+      options.headers.Authorization = `Bearer ${this.token}`;
+    }
+    if (this.fwRequestId) {
+      options.headers['x-request-id-fw'] = this.fwRequestId;
+    }
+    if (this.callId) {
+      options.headers['x-call-id'] = this.callId;
+    }
+
+    // Set credentials for browser environment
+    if (this.environment === 'browser') {
+      options.credentials = 'include';
+    }
+
+    let url;
+    if (this.environment === 'node') {
+      url = `${this.baseURL}${endpoint}`;
+    } else {
+      url = `${this.fullUrl}${endpoint}`;
+    }
+
+    // Add query parameters
+    if (query) {
+      const params = new URLSearchParams(query).toString();
+      url += `?${params}`;
+    }
+
+    // Handle body
+    if (options.method.toLowerCase() === 'get') {
+      delete options.body;
+    } else if (body) {
+      // For FormData or Buffer, pass directly without JSON.stringify
+      const isFormData =
+        body &&
+        (body.constructor.name === 'FormData' ||
+          typeof body.getBoundary === 'function');
+      const isBuffer = Buffer && Buffer.isBuffer && Buffer.isBuffer(body);
+
+      if (isFormData || isBuffer) {
+        options.body = body;
+      } else {
+        options.body = JSON.stringify(body);
+      }
+    }
+
+    const response = await fetch(url, options);
+    const bodyResponse = await response.json();
+
+    const responseHeaders = response.headers;
+    const responseRequestId =
+      responseHeaders?.get?.('x-request-id') ||
+      responseHeaders?.['x-request-id'];
+
+    if (!response.ok) {
+      throw {
+        name: `API :: Error :: https :: ${method} :: ${endpoint} :: ${responseRequestId} :: ${response?.status} :: ${response?.statusText}`,
+        message: bodyResponse?.message || `API Error occured.`,
+        method,
+        endpoint,
+        status: response?.status,
+        statusText: response?.statusText,
+      };
+    }
+    
+    console.log(
+      `API :: https :: ${method} :: ${endpoint} :: ${responseRequestId}`,
+    );
+    return bodyResponse;
+  }
+}

package/index.js

@@ -0,0 +1,181 @@
+/* eslint-disable indent */
+/* eslint-disable prettier/prettier */
+
+import { BaseSDK } from './base.js';
+import { LoginService } from './services/login.js';
+import { ObjectsService } from './services/objects.js';
+import { MessagingService } from './services/messaging.js';
+import { VideoService } from './services/video.js';
+import { VoiceService } from './services/voice.js';
+import { AIService } from './services/ai.js';
+import { LookupService } from './services/lookup.js';
+import { LayoutsService } from './services/layouts.js';
+import { SubscriptionsService } from './services/subscriptions.js';
+import { WorkflowsService } from './services/workflows.js';
+import { NotesService } from './services/notes.js';
+import { StorageService } from './services/storage.js';
+import { VerificationService } from './services/verification.js';
+import { PortalsService } from './services/portals.js';
+import { SipEndpointsService } from './services/sipEndpoints.js';
+import { ExternalOAuthService } from './services/externalOAuth.js';
+import { GoogleCalendarService } from './services/googleCalendar.js';
+import { EnrollService } from './services/enroll.js';
+import { PhoneNumbersService } from './services/phoneNumbers.js';
+import { RecordTypesService } from './services/recordTypes.js';
+import { GenerateIdService } from './services/generateId.js';
+
+class UnboundSDK extends BaseSDK {
+  constructor(options = {}) {
+    // Support both object and legacy positional parameters for backwards compatibility
+    if (typeof options === 'string') {
+      // Legacy positional parameters: (namespace, callId, token, fwRequestId, url, socketStore)
+      const namespace = options;
+      const callId = arguments[1];
+      const token = arguments[2];
+      const fwRequestId = arguments[3];
+      const url = arguments[4];
+      const socketStore = arguments[5];
+      
+      super({ namespace, callId, token, fwRequestId });
+      
+      // Handle client-side specific parameters
+      if (url) {
+        this.baseUrl = url;
+        this._initializeEnvironment();
+      }
+      
+      if (socketStore) {
+        this.socketStore = socketStore;
+      }
+    } else {
+      // New object-based parameters
+      const { namespace, callId, token, fwRequestId, url, socketStore } = options;
+      
+      super({ namespace, callId, token, fwRequestId });
+      
+      // Handle client-side specific parameters
+      if (url) {
+        this.baseUrl = url;
+        this._initializeEnvironment();
+      }
+      
+      if (socketStore) {
+        this.socketStore = socketStore;
+      }
+    }
+    
+    // Initialize all service modules
+    this.login = new LoginService(this);
+    this.objects = new ObjectsService(this);
+    this.messaging = new MessagingService(this);
+    this.video = new VideoService(this);
+    this.voice = new VoiceService(this);
+    this.ai = new AIService(this);
+    this.lookup = new LookupService(this);
+    this.layouts = new LayoutsService(this);
+    this.subscriptions = new SubscriptionsService(this);
+    this.workflows = new WorkflowsService(this);
+    this.notes = new NotesService(this);
+    this.storage = new StorageService(this);
+    this.verification = new VerificationService(this);
+    this.portals = new PortalsService(this);
+    this.sipEndpoints = new SipEndpointsService(this);
+    this.externalOAuth = new ExternalOAuthService(this);
+    this.googleCalendar = new GoogleCalendarService(this);
+    this.enroll = new EnrollService(this);
+    this.phoneNumbers = new PhoneNumbersService(this);
+    this.recordTypes = new RecordTypesService(this);
+    this.generateId = new GenerateIdService(this);
+    
+    // Add additional services that might be missing
+    this._initializeAdditionalServices();
+  }
+
+  _initializeAdditionalServices() {
+    // Placeholder for additional services that might be discovered
+    // This will be populated as we find missing APIs
+  }
+
+  // Extension method for plugins (internal SDK, transport plugins, etc.)
+  use(plugin) {
+    if (typeof plugin === 'function') {
+      plugin(this);
+    } else if (plugin && typeof plugin.install === 'function') {
+      plugin.install(this);
+    } else {
+      throw new Error('Plugin must be a function or have an install method');
+    }
+    return this;
+  }
+
+  extend(extension) {
+    if (typeof extension === 'function') {
+      // Extension is a class constructor
+      const instance = new extension(this);
+      
+      // Merge extension methods/properties into this SDK
+      for (const key in instance) {
+        if (instance.hasOwnProperty(key) && typeof instance[key] !== 'undefined') {
+          this[key] = instance[key];
+        }
+      }
+    } else if (typeof extension === 'object') {
+      // Extension is an object with methods
+      Object.assign(this, extension);
+    } else {
+      throw new Error('Extension must be a class constructor or object');
+    }
+    return this;
+  }
+
+  // Transport plugin methods
+  addTransport(transport) {
+    super.addTransport(transport);
+    return this;
+  }
+
+  removeTransport(name) {
+    super.removeTransport(name);
+    return this;
+  }
+
+  // Backwards compatibility helper methods
+  async buildMasterAuth({ namespace, accountId, userId }) {
+    // This method should only be available in Node.js environment
+    // and will be added via internal SDK extension
+    throw new Error('buildMasterAuth is only available with the internal SDK extension. Please use: sdk.use(InternalExtension)');
+  }
+}
+
+// Export both the class and a factory function for convenience
+export default UnboundSDK;
+export { UnboundSDK };
+
+// Factory function for common usage patterns
+export function createSDK(options = {}) {
+  return new UnboundSDK(options);
+}
+
+// Re-export service classes for advanced usage
+export { LoginService } from './services/login.js';
+export { ObjectsService } from './services/objects.js';
+export { MessagingService } from './services/messaging.js';
+export { VideoService } from './services/video.js';
+export { VoiceService } from './services/voice.js';
+export { AIService } from './services/ai.js';
+export { LookupService } from './services/lookup.js';
+export { LayoutsService } from './services/layouts.js';
+export { SubscriptionsService } from './services/subscriptions.js';
+export { WorkflowsService } from './services/workflows.js';
+export { NotesService } from './services/notes.js';
+export { StorageService } from './services/storage.js';
+export { VerificationService } from './services/verification.js';
+export { PortalsService } from './services/portals.js';
+export { SipEndpointsService } from './services/sipEndpoints.js';
+export { ExternalOAuthService } from './services/externalOAuth.js';
+export { GoogleCalendarService } from './services/googleCalendar.js';
+export { EnrollService } from './services/enroll.js';
+export { PhoneNumbersService, PhoneNumberCarrierService } from './services/phoneNumbers.js';
+export { RecordTypesService, UserRecordTypeDefaultsService } from './services/recordTypes.js';
+export { GenerateIdService } from './services/generateId.js';
+export { BaseSDK } from './base.js';

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@unboundcx/sdk",
+  "version": "1.0.0",
+  "description": "Official JavaScript SDK for the Unbound API - A comprehensive toolkit for integrating with Unbound's communication, AI, and data management services",
+  "main": "index.js",
+  "type": "module",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "keywords": [
+    "unbound",
+    "api",
+    "sdk",
+    "messaging",
+    "voice",
+    "video",
+    "ai",
+    "communication",
+    "javascript",
+    "typescript",
+    "sms",
+    "email",
+    "workflows"
+  ],
+  "author": {
+    "name": "Unbound Team",
+    "email": "support@unbound.cx",
+    "url": "https://unbound.cx"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/unbound/sdk-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/unbound/sdk-js/issues"
+  },
+  "homepage": "https://docs.unbound.cx/sdk",
+  "files": [
+    "*.js",
+    "services/**/*.js",
+    "transports/**/*.js",
+    "types/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "import": "./index.js",
+      "require": "./index.cjs"
+    },
+    "./base": {
+      "import": "./base.js"
+    },
+    "./services/*": {
+      "import": "./services/*.js"
+    }
+  },
+  "scripts": {
+    "build": "echo 'Build complete - ESM modules ready'",
+    "test": "echo 'Tests would run here'",
+    "lint": "echo 'Linting would run here'",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {},
+  "optionalDependencies": {
+    "mime-types": "^2.1.35"
+  },
+  "peerDependencies": {
+    "socket.io-client": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "socket.io-client": {
+      "optional": true
+    }
+  },
+  "devDependencies": {},
+  "browserslist": [
+    "defaults",
+    "not IE 11",
+    "not IE_Mob 11",
+    "maintained node versions"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/services/ai.js

@@ -0,0 +1,151 @@
+export class AIService {
+  constructor(sdk) {
+    this.sdk = sdk;
+    this.generative = new GenerativeService(sdk);
+    this.tts = new TextToSpeechService(sdk);
+  }
+}
+
+export class GenerativeService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  async chat({ prompt, messages, relatedId, model, temperature, subscriptionId, stream, method }) {
+    this.sdk.validateParams(
+      { method },
+      {
+        prompt: { type: 'string', required: false },
+        messages: { type: 'array', required: false },
+        relatedId: { type: 'string', required: false },
+        model: { type: 'string', required: false },
+        temperature: { type: 'number', required: false },
+        subscriptionId: { type: 'string', required: false },
+        stream: { type: 'boolean', required: false },
+        method: { type: 'string', required: true }
+      },
+    );
+
+    const params = {
+      body: {
+        prompt,
+        messages,
+        relatedId,
+        model,
+        temperature,
+        subscriptionId,
+        stream,
+        method,
+      }
+    }
+
+    const result = await this.sdk._fetch('/ai/generative/chat', 'POST', params);
+    return result;
+  }
+
+  async playbook({ prompt, messages, relatedId, model, temperature, subscriptionId, stream, playbookId, sessionId }) {
+    this.sdk.validateParams(
+      { playbookId },
+      {
+        prompt: { type: 'string', required: false },
+        messages: { type: 'array', required: false },
+        relatedId: { type: 'string', required: false },
+        model: { type: 'string', required: false },
+        temperature: { type: 'number', required: false },
+        subscriptionId: { type: 'string', required: false },
+        stream: { type: 'boolean', required: false },
+        playbookId: { type: 'string', required: true },
+        sessionId: { type: 'string', required: false }
+      },
+    );
+
+    const params = {
+      body: {
+        prompt,
+        messages,
+        relatedId,
+        model,
+        temperature,
+        subscriptionId,
+        stream,
+        playbookId,
+        sessionId,
+      }
+    }
+
+    const result = await this.sdk._fetch('/ai/generative/playbook', 'POST', params);
+    return result;
+  }
+
+  async chatOllama({ prompt, messages, relatedId, model, temperature, subscriptionId, stream, method }) {
+    this.sdk.validateParams(
+      { method },
+      {
+        prompt: { type: 'string', required: false },
+        messages: { type: 'array', required: false },
+        relatedId: { type: 'string', required: false },
+        model: { type: 'string', required: false },
+        temperature: { type: 'number', required: false },
+        subscriptionId: { type: 'string', required: false },
+        stream: { type: 'boolean', required: false },
+        method: { type: 'string', required: true }
+      },
+    );
+
+    const params = {
+      body: {
+        prompt,
+        messages,
+        relatedId,
+        model,
+        temperature,
+        subscriptionId,
+        stream,
+        method,
+      }
+    }
+
+    const result = await this.sdk._fetch('/ai/generative/ollama', 'POST', params);
+    return result;
+  }
+}
+
+export class TextToSpeechService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  async create({ text, voice, languageCode, ssmlGender, audioEncoding, speakingRate, pitch, volumeGainDb, effectsProfileIds }) {
+    this.sdk.validateParams(
+      { text },
+      {
+        text: { type: 'string', required: true },
+        voice: { type: 'string', required: false },
+        languageCode: { type: 'string', required: false },
+        ssmlGender: { type: 'string', required: false },
+        audioEncoding: { type: 'string', required: false },
+        speakingRate: { type: 'number', required: false },
+        pitch: { type: 'number', required: false },
+        volumeGainDb: { type: 'number', required: false },
+        effectsProfileIds: { type: 'array', required: false },
+      },
+    );
+
+    const ttsData = { text };
+    if (voice) ttsData.voice = voice;
+    if (languageCode) ttsData.languageCode = languageCode;
+    if (ssmlGender) ttsData.ssmlGender = ssmlGender;
+    if (audioEncoding) ttsData.audioEncoding = audioEncoding;
+    if (speakingRate) ttsData.speakingRate = speakingRate;
+    if (pitch) ttsData.pitch = pitch;
+    if (volumeGainDb) ttsData.volumeGainDb = volumeGainDb;
+    if (effectsProfileIds) ttsData.effectsProfileIds = effectsProfileIds;
+
+    const params = {
+      body: ttsData,
+    };
+
+    const result = await this.sdk._fetch('/ai/tts', 'POST', params);
+    return result;
+  }
+}