@unboundcx/sdk 2.8.5 → 2.8.7

package/README.md

@@ -11,7 +11,7 @@ The official JavaScript SDK for Unbound's comprehensive communication and AI pla
 - 📱 **Messaging**: SMS/MMS and Email with templates and campaigns
 - 📞 **Voice**: Call management, conferencing, recording, transcription
 - 📹 **Video**: Video conferencing with advanced controls
-- 🤖 **AI**: Generative AI chat and text-to-speech
+- 🤖 **AI**: Generative AI chat, text-to-speech, and speech-to-text
 - 💾 **Data**: Object management with queries and relationships
 - 🔄 **Workflows**: Programmable workflow execution
 - 🔌 **Extensible**: Plugin system for transports and extensions
@@ -276,6 +276,53 @@ const audio = await api.ai.tts.create({
   voice: 'en-US-Standard-A',
   audioEncoding: 'MP3',
 });
+
+// Speech-to-Text - File/Storage Transcription
+const transcription = await api.ai.stt.create({
+  sourceType: 'storage',
+  storageId: 'audio-file-id',
+  engine: 'google',
+  languageCode: 'en-US',
+  metadata: {
+    diarization: true,
+    speakerCount: 2,
+  },
+});
+
+// Speech-to-Text - Real-Time Streaming (NEW Simplified API)
+const stream = await api.ai.stt.stream({
+  engine: 'google',
+  model: 'phone_call',
+  languageCode: 'en-US',
+  encoding: 'LINEAR16',
+  sampleRateHertz: 16000,
+  engagementSessionId: 'eng-123',
+});
+
+// Handle transcription events
+stream.on('transcript', (result) => {
+  console.log(`${result.isFinal ? '[FINAL]' : '[interim]'} ${result.text}`);
+  // Transcripts are automatically saved to database!
+});
+
+stream.on('error', (error) => console.error('Stream error:', error));
+stream.on('close', () => console.log('Stream closed'));
+
+// Write audio chunks
+stream.write(audioChunk); // Buffer or Uint8Array
+stream.end(); // Close when done
+
+// Later: Retrieve full transcript from database (automatic storage)
+const savedTranscript = await api.ai.stt.get(stream.sessionId, {
+  includeMessages: true,
+});
+
+// List all transcriptions
+const transcriptions = await api.ai.stt.list({
+  engagementSessionId: 'eng-123',
+  status: 'completed',
+  limit: 50,
+});
 ```
 
 ### Utility Services

package/base.js

@@ -167,6 +167,7 @@ export class BaseSDK {
   }
 
   async _fetch(endpoint, method, params = {}, forceFetch = false) {
+    const startTime = Date.now();
     const { body, query, headers = {}, returnRawResponse = false } = params;
 
     this.validateParams(
@@ -195,7 +196,6 @@ export class BaseSDK {
     params.headers = headers;
 
     // Try transport plugins first
-    console.log(`sdk :: request :: forceFetch:${forceFetch} :: endpoint:${endpoint}`);
     const transport = await this._getAvailableTransport(forceFetch);
     let response;
     if (transport) {
@@ -221,14 +221,27 @@ export class BaseSDK {
         );
 
         // Built-in HTTP transport (fallback)
-        return this._httpRequest(endpoint, method, params, returnRawResponse);
+        return this._httpRequest(
+          endpoint,
+          method,
+          params,
+          returnRawResponse,
+          startTime,
+        );
       }
     } else {
       // No transport available, fallback to HTTP
       if (forceFetch && process.env.AUTH_V3_TOKEN_TYPE_OVERRIDE) {
-        params.headers['x-token-type-override'] = process.env.AUTH_V3_TOKEN_TYPE_OVERRIDE;
+        params.headers['x-token-type-override'] =
+          process.env.AUTH_V3_TOKEN_TYPE_OVERRIDE;
       }
-      return this._httpRequest(endpoint, method, params, returnRawResponse);
+      return this._httpRequest(
+        endpoint,
+        method,
+        params,
+        returnRawResponse,
+        startTime,
+      );
     }
 
     // For streaming requests, return the raw response from transports
@@ -236,7 +249,14 @@ export class BaseSDK {
       return response;
     }
 
-    return this._processResponse(response, transport.name, method, endpoint);
+    const duration = Date.now() - startTime;
+    return this._processResponse(
+      response,
+      transport.name,
+      method,
+      endpoint,
+      duration,
+    );
   }
 
   _isMultipartBody(body) {
@@ -269,7 +289,13 @@ export class BaseSDK {
     return false;
   }
 
-  async _httpRequest(endpoint, method, params = {}, returnRawResponse = false) {
+  async _httpRequest(
+    endpoint,
+    method,
+    params = {},
+    returnRawResponse = false,
+    startTime = Date.now(),
+  ) {
     const { body, query, headers = {} } = params;
 
     const options = {
@@ -325,16 +351,17 @@ export class BaseSDK {
     }
 
     const response = await fetch(url, options);
+    const duration = Date.now() - startTime;
 
     // For streaming requests, return the raw fetch response
     if (returnRawResponse) {
       return response;
     }
 
-    return this._processResponse(response, 'https', method, endpoint);
+    return this._processResponse(response, 'https', method, endpoint, duration);
   }
 
-  async _processResponse(response, transport, method, endpoint) {
+  async _processResponse(response, transport, method, endpoint, duration = 0) {
     // Check if the response indicates an HTTP error
     // These are API/configuration errors, not transport failures
 
@@ -400,9 +427,11 @@ export class BaseSDK {
       // Debug logging for successful HTTP requests
       if (this.debugMode) {
         console.log(
-          `API :: ERROR :: ${transport} :: ${method.toUpperCase()} :: ${endpoint} :: ${
+          `API :: ERROR :: ${transport} :: ${method.toUpperCase()} :: ${
+            this.baseURL
+          }${endpoint} :: ${
             response?.status
-          } :: ${responseRequestId}`,
+          } :: ${responseRequestId} :: ${duration}ms`,
           httpError,
         );
       }
@@ -443,9 +472,11 @@ export class BaseSDK {
     // Debug logging for successful HTTP requests
     if (this.debugMode) {
       console.log(
-        `API :: ${transport} :: ${method.toUpperCase()} :: ${endpoint} :: ${
+        `API :: ${transport} :: ${method.toUpperCase()} :: ${
+          this.baseURL
+        }${endpoint} :: ${
           response?.status
-        } :: ${responseRequestId}`,
+        } :: ${responseRequestId} :: ${duration}ms`,
       );
     }
 

package/index.js

@@ -24,6 +24,7 @@ import { PhoneNumbersService } from './services/phoneNumbers.js';
 import { RecordTypesService } from './services/recordTypes.js';
 import { GenerateIdService } from './services/generateId.js';
 import { EngagementMetricsService } from './services/engagementMetrics.js';
+import { TaskRouterService } from './services/taskRouter.js';
 
 class UnboundSDK extends BaseSDK {
   constructor(options = {}) {
@@ -89,6 +90,7 @@ class UnboundSDK extends BaseSDK {
     this.recordTypes = new RecordTypesService(this);
     this.generateId = new GenerateIdService(this);
     this.engagementMetrics = new EngagementMetricsService(this);
+    this.taskRouter = new TaskRouterService(this);
 
     // Add additional services that might be missing
     this._initializeAdditionalServices();
@@ -153,6 +155,77 @@ class UnboundSDK extends BaseSDK {
       'buildMasterAuth is only available with the internal SDK extension. Please use: sdk.use(InternalExtension)',
     );
   }
+
+  /**
+   * Check SDK configuration and API connectivity
+   * Calls the /health endpoint to verify SDK setup
+   *
+   * @returns {Promise<Object>} Health check result with:
+   *   - healthy: boolean - If API is reachable
+   *   - hasAuthorization: boolean - If auth credentials were received by API
+   *   - authType: string|null - Type of auth detected by API ('bearer', 'cookie', or 'bearer+cookie')
+   *   - namespace: string - Current namespace
+   *   - environment: string - 'node' or 'browser'
+   *   - transport: string - Transport method used ('HTTP', 'WebSocket', etc.)
+   */
+  async status() {
+    try {
+      const response = await this._fetch('/health', 'GET', {
+        returnRawResponse: true,
+      });
+
+      // Parse response
+      let healthData;
+      try {
+        if (typeof response.json === 'function') {
+          healthData = await response.json();
+        } else if (response.body) {
+          healthData =
+            typeof response.body === 'string'
+              ? JSON.parse(response.body)
+              : response.body;
+        } else {
+          healthData = {};
+        }
+      } catch (e) {
+        healthData = {};
+      }
+
+      return {
+        healthy: response.ok || response.status === 200,
+        hasAuthorization: healthData.hasAuthorization || false,
+        authType: healthData.authType || null,
+        namespace: this.namespace,
+        environment: this.environment,
+        transport: healthData.transport || 'unknown',
+        timestamp: healthData.timestamp,
+        url: healthData.url || null,
+        statusCode: response.status,
+      };
+    } catch (error) {
+      return {
+        healthy: false,
+        hasAuthorization: false,
+        authType: null,
+        namespace: this.namespace,
+        environment: this.environment,
+        error: error.message,
+        statusCode: error.status || null,
+      };
+    }
+  }
+
+  /**
+   * Get the client's IP address
+   * Always uses fetch transport (never WebSocket or other transports)
+   *
+   * @returns {Promise<Object>} Response with:
+   *   - ip: string - The client's IP address
+   */
+  async getIp() {
+    // Force fetch transport (pass true as forceFetch parameter)
+    return await this._fetch('/get-ip', 'GET', {}, true);
+  }
 }
 
 // Export both the class and a factory function for convenience
@@ -193,4 +266,6 @@ export {
 } from './services/recordTypes.js';
 export { GenerateIdService } from './services/generateId.js';
 export { EngagementMetricsService } from './services/engagementMetrics.js';
+export { TaskRouterService } from './services/taskRouter.js';
+export { WorkerService } from './services/taskRouter/WorkerService.js';
 export { BaseSDK } from './base.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "2.8.5",
+  "version": "2.8.7",
   "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",
@@ -41,6 +41,7 @@
     "services/**/*.js",
     "transports/**/*.js",
     "types/**/*.d.ts",
+    "proto/**/*.proto",
     "README.md",
     "LICENSE"
   ],
@@ -64,7 +65,9 @@
   },
   "dependencies": {},
   "optionalDependencies": {
-    "mime-types": "^2.1.35"
+    "mime-types": "^2.1.35",
+    "@grpc/grpc-js": "^1.14.1",
+    "@grpc/proto-loader": "^0.7.15"
   },
   "peerDependencies": {
     "socket.io-client": "^4.0.0"

package/proto/transcription.proto

@@ -0,0 +1,207 @@
+syntax = "proto3";
+
+package transcription;
+
+// Transcription Service Definition
+service TranscriptionService {
+  // Bidirectional streaming for real-time transcription
+  // Client streams audio chunks, server streams back transcription results
+  rpc StreamTranscribe(stream AudioRequest) returns (stream TranscriptResponse);
+
+  // Get transcription session status
+  rpc GetSessionStatus(SessionStatusRequest) returns (SessionStatusResponse);
+}
+
+// Audio streaming request message
+message AudioRequest {
+  // Audio data chunk (raw bytes)
+  bytes audio_chunk = 1;
+
+  // Session ID for this transcription session
+  string session_id = 2;
+
+  // Authentication token
+  string token = 3;
+
+  // Language code (optional, will auto-detect if not provided)
+  // Examples: "en", "es", "fr", "de", "ja", "zh"
+  string language = 4;
+
+  // Transcription engine to use
+  // Options: "whisper", "google"
+  string engine = 5;
+
+  // Audio configuration
+  AudioConfig config = 6;
+
+  // Flag to indicate this is the first chunk
+  bool is_first_chunk = 7;
+
+  // Flag to indicate this is the last chunk
+  bool is_last_chunk = 8;
+
+  // SIP call identifier (required for multi-stream support)
+  // Used to identify which call this audio belongs to
+  string sip_call_id = 9;
+
+  // Audio stream side (required for multi-stream support)
+  // Options: "send" (outgoing), "recv" (incoming)
+  string side = 10;
+
+  // Speaker role (optional)
+  // Examples: "customer", "agent", "system"
+  string role = 11;
+
+  // VAD event type (optional - sent by media manager for speech detection)
+  // Options: "speaking_started", "speaking_stopped"
+  // When provided, this is a VAD event (not audio data)
+  string vad_event = 12;
+
+  // VAD event energy level (for speaking_started events)
+  double vad_energy = 13;
+
+  // VAD event speech duration in ms (for speaking_stopped events)
+  int64 vad_duration = 14;
+
+  // VAD event timestamp
+  int64 vad_timestamp = 15;
+
+  // Playbook identifier (optional - links transcription to a playbook session)
+  string playbook_id = 16;
+
+  // Bridge identifier (optional - links related transcription streams)
+  // When multiple bridged call legs have transcription active,
+  // bridge_id lets the transcription service correlate them
+  string bridge_id = 17;
+
+  // Task identifier (optional - links transcription to a specific task)
+  string task_id = 18;
+
+  // Worker identifier (optional)
+  string worker_id = 19;
+
+  // Generate subject from transcription (optional)
+  bool generate_subject = 20;
+
+  // Generate transcript summary (optional)
+  bool generate_transcript_summary = 21;
+
+  // Generate sentiment analysis (optional)
+  bool generate_sentiment = 22;
+}
+
+// Audio configuration
+message AudioConfig {
+  // Audio encoding format
+  // Examples: "LINEAR16", "FLAC", "MP3", "OGG_OPUS", "WEBM_OPUS"
+  string encoding = 1;
+
+  // Sample rate in Hertz
+  // Recommended: 16000 for most cases
+  int32 sample_rate_hertz = 2;
+
+  // Number of audio channels
+  // Mono = 1, Stereo = 2
+  int32 audio_channel_count = 3;
+
+  // Language code (deprecated, use AudioRequest.language instead)
+  string language_code = 4;
+
+  // Voice Activity Detection (VAD) configuration
+  // Enable VAD to filter out silence and improve transcription quality
+  bool vad_enabled = 5;
+
+  // Minimum silence duration in milliseconds to split segments
+  // Typical values: 300ms (fast, live calls) to 700ms (accurate, voicemails)
+  // Default: 500ms
+  int32 min_silence_duration_ms = 6;
+
+  // Padding around speech segments in milliseconds
+  // Adds context before/after detected speech
+  // Default: 400ms
+  int32 speech_pad_ms = 7;
+}
+
+// Transcription response message
+message TranscriptResponse {
+  // Transcribed text
+  string transcript = 1;
+
+  // Confidence score (0.0 to 1.0)
+  float confidence = 2;
+
+  // Whether this is a final result or interim
+  bool is_final = 3;
+
+  // Detected or specified language
+  string language = 4;
+
+  // Timestamp of this result (milliseconds since epoch)
+  int64 timestamp = 5;
+
+  // Word-level details (optional)
+  repeated WordInfo words = 6;
+
+  // Start time of this segment (seconds)
+  float start_time = 7;
+
+  // End time of this segment (seconds)
+  float end_time = 8;
+
+  // SIP call identifier (echoed back from AudioRequest)
+  string sip_call_id = 9;
+
+  // Audio stream side (echoed back from AudioRequest)
+  string side = 10;
+
+  // Speaker role (echoed back from AudioRequest)
+  string role = 11;
+}
+
+// Word-level information
+message WordInfo {
+  // The word text
+  string word = 1;
+
+  // Start time of the word (seconds)
+  float start_time = 2;
+
+  // End time of the word (seconds)
+  float end_time = 3;
+
+  // Confidence score for this word (0.0 to 1.0)
+  float confidence = 4;
+}
+
+// Session status request
+message SessionStatusRequest {
+  // Session ID to query
+  string session_id = 1;
+
+  // Authentication token
+  string token = 2;
+}
+
+// Session status response
+message SessionStatusResponse {
+  // Session ID
+  string session_id = 1;
+
+  // Session status: "active", "completed", "failed", "not_found"
+  string status = 2;
+
+  // Detected or specified language
+  string language = 3;
+
+  // Engine being used
+  string engine = 4;
+
+  // Session start time (milliseconds since epoch)
+  int64 start_time = 5;
+
+  // Total chunks processed
+  int32 total_chunks = 6;
+
+  // Error message (if status is "failed")
+  string error = 7;
+}