@unboundcx/sdk 4.13.97 → 4.13.99

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "4.13.97",
+  "version": "4.13.99",
   "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",

package/services/ai/tts.js

@@ -0,0 +1,155 @@
+import { internalRequest } from '../../base.js';
+
+/**
+ * Text-to-speech. `sdk.ai.tts.*`.
+ *
+ * @see app1-api src/services/ai/routes/tts.js
+ */
+export class TextToSpeechService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  /**
+   * Render text to speech and get back a storage id/url (buffered — waits
+   * for the whole file). For low-latency playback (e.g. a voice bot) use
+   * `stream()` instead.
+   * @param {Object} params
+   * @param {string} params.text
+   * @param {string} [params.voice]
+   * @param {string} [params.languageCode]
+   * @param {string} [params.ssmlGender]
+   * @param {string} [params.audioEncoding]
+   * @param {number} [params.speakingRate]
+   * @param {number} [params.pitch]
+   * @param {number} [params.volumeGainDb]
+   * @param {string[]} [params.effectsProfileIds]
+   * @param {boolean} [params.createAccessKey]
+   * @returns {Promise<Object>} `{ id, storageId, url? }`
+   */
+  async create({
+    text,
+    voice,
+    languageCode,
+    ssmlGender,
+    audioEncoding,
+    speakingRate,
+    pitch,
+    volumeGainDb,
+    effectsProfileIds,
+    createAccessKey,
+  }) {
+    this.sdk.validateParams(
+      {
+        text,
+        voice,
+        languageCode,
+        ssmlGender,
+        audioEncoding,
+        speakingRate,
+        pitch,
+        volumeGainDb,
+        effectsProfileIds,
+        createAccessKey,
+      },
+      {
+        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 },
+        createAccessKey: { type: 'boolean', 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;
+    if (createAccessKey) ttsData.createAccessKey = createAccessKey;
+
+    const params = {
+      body: ttsData,
+    };
+
+    const result = await internalRequest(this.sdk, '/ai/tts', 'POST', params);
+    return result;
+  }
+
+  /**
+   * List available TTS voices
+   * @returns {Promise<Object>} { voices: Array, count: number, supportedEncodings: Array, supportedLanguages: Array }
+   */
+  async list() {
+    const result = await internalRequest(this.sdk, '/ai/tts', 'GET');
+    return result;
+  }
+
+  /**
+   * Stream TTS audio as it's generated — first bytes can arrive well before
+   * the whole utterance finishes rendering (Groq voices: TTFB ~0.2s).
+   * Always renders wav; shares its cache with `create()` when
+   * audioEncoding:'wav' is used there.
+   *
+   * Node: wrap the result in `Readable.fromWeb(result.body)` to get a
+   * normal Node stream (e.g. to pipe into ffmpeg). Browser: `result.body`
+   * is already a web ReadableStream you can read directly or hand to
+   * `new Response(result.body)` / a `<audio>` element via a Blob.
+   *
+   * Response headers of note: `x-tts-cache` (`hit`|`miss`) and `x-tts-id`
+   * (set on a cache hit, when the id is already known).
+   *
+   * @param {Object} params
+   * @param {string} params.text
+   * @param {string} [params.voice]
+   * @param {string} [params.languageCode]
+   * @returns {Promise<{body: ReadableStream, headers: Headers, status: number}>}
+   * @example
+   * const result = await sdk.ai.tts.stream({ text: 'Hi there', voice: 'hannah' });
+   * const nodeStream = Readable.fromWeb(result.body);
+   * nodeStream.pipe(ffmpegProcess.stdin);
+   */
+  async stream({ text, voice, languageCode }) {
+    this.sdk.validateParams(
+      { text, voice, languageCode },
+      {
+        text: { type: 'string', required: true },
+        voice: { type: 'string', required: false },
+        languageCode: { type: 'string', required: false },
+      },
+    );
+
+    const ttsData = { text };
+    if (voice) ttsData.voice = voice;
+    if (languageCode) ttsData.languageCode = languageCode;
+
+    const params = {
+      body: ttsData,
+      returnRawResponse: true,
+    };
+
+    // forceFetch: true — NATS transport can't carry a streamed body.
+    const response = await internalRequest(
+      this.sdk,
+      '/ai/tts/stream',
+      'POST',
+      params,
+      true,
+    );
+
+    return {
+      body: response.body,
+      headers: response.headers,
+      status: response.status,
+    };
+  }
+}

package/services/ai.js

@@ -5,6 +5,7 @@ import { AssistService } from './ai/assist.js';
 import { VocabularyService } from './ai/vocabulary.js';
 import { EmailService } from './ai/email.js';
 import { ModelsService } from './ai/models.js';
+import { TextToSpeechService } from './ai/tts.js';
 import { translate as translateItems } from './ai/translate.js';
 import {
   getSettings as getAiSettings,
@@ -487,79 +488,6 @@ export class GenerativeService {
   // }
 }
 
-export class TextToSpeechService {
-  constructor(sdk) {
-    this.sdk = sdk;
-  }
-
-  async create({
-    text,
-    voice,
-    languageCode,
-    ssmlGender,
-    audioEncoding,
-    speakingRate,
-    pitch,
-    volumeGainDb,
-    effectsProfileIds,
-    createAccessKey,
-  }) {
-    this.sdk.validateParams(
-      {
-        text,
-        voice,
-        languageCode,
-        ssmlGender,
-        audioEncoding,
-        speakingRate,
-        pitch,
-        volumeGainDb,
-        effectsProfileIds,
-        createAccessKey,
-      },
-      {
-        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 },
-        createAccessKey: { type: 'boolean', 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;
-    if (createAccessKey) ttsData.createAccessKey = createAccessKey;
-
-    const params = {
-      body: ttsData,
-    };
-
-    const result = await internalRequest(this.sdk, '/ai/tts', 'POST', params);
-    return result;
-  }
-
-  /**
-   * List available TTS voices
-   * @returns {Promise<Object>} { voices: Array, count: number, supportedEncodings: Array, supportedLanguages: Array }
-   */
-  async list() {
-    const result = await internalRequest(this.sdk, '/ai/tts', 'GET');
-    return result;
-  }
-}
-
 export class SpeechToTextService {
   constructor(sdk) {
     this.sdk = sdk;

package/services/taskRouter/TaskService.js

@@ -439,6 +439,80 @@ export class TaskService {
     );
   }
 
+  /**
+   * Release a task back to the queue for a human (same queue, same task
+   * id) — the bot-task-lifecycle release contract. Stamps
+   * botEligible:false (when humanOnly) plus named release-reason
+   * metadata, and for a voice task in 'callback' mode hands the customer
+   * off to the existing queue-wait callback contract (hangs up, task goes
+   * pending, human accept later auto-dials the customer back).
+   *
+   * @param {Object} options - Parameters
+   * @param {string} options.taskId - The task ID to release (required)
+   * @param {'live'|'callback'} [options.mode] - Required for a voice task (has a live call); ignored for a digital task
+   * @param {string} options.reasonCode - Release reason code (required) — e.g. 'callback_promised', 'human_requested', 'no_human_available', 'bot_cannot_resolve', 'customer_frustrated', 'review_failed', 'policy_human_only', 'other'
+   * @param {string} options.reason - One-sentence reason shown to the next agent (required)
+   * @param {string} [options.callbackNumber] - E.164 callback number ('callback' mode only; defaults to the task's `from`)
+   * @param {boolean} [options.humanOnly=true] - Stamp botEligible:false so only a human is offered this task
+   * @param {boolean} [options.hangup=true] - Hang up the customer leg ('callback' mode only)
+   * @returns {Promise<Object>} { taskId, status: 'pending', mode, humanOnly, reasonCode }
+   *
+   * @example
+   * // Caller confirmed a callback -- release and hang up
+   * await sdk.taskRouter.task.release({
+   *   taskId: 'task123',
+   *   mode: 'callback',
+   *   reasonCode: 'callback_promised',
+   *   reason: 'Caller asked for a callback once an agent frees up',
+   * });
+   *
+   * @example
+   * // Caller wants to hold for a human -- release, keep the call live
+   * await sdk.taskRouter.task.release({
+   *   taskId: 'task123',
+   *   mode: 'live',
+   *   reasonCode: 'no_human_available',
+   *   reason: 'No agents available, caller chose to hold',
+   * });
+   */
+  async release(options = {}) {
+    const {
+      taskId,
+      mode,
+      reasonCode,
+      reason,
+      callbackNumber,
+      humanOnly,
+      hangup,
+    } = options;
+
+    this.sdk.validateParams(
+      { taskId, mode, reasonCode, reason, callbackNumber, humanOnly, hangup },
+      {
+        taskId: { type: 'string', required: true },
+        mode: { type: 'string', required: false },
+        reasonCode: { type: 'string', required: true },
+        reason: { type: 'string', required: true },
+        callbackNumber: { type: 'string', required: false },
+        humanOnly: { type: 'boolean', required: false },
+        hangup: { type: 'boolean', required: false },
+      },
+    );
+
+    const params = { body: { taskId, reasonCode, reason } };
+    if (mode !== undefined) params.body.mode = mode;
+    if (callbackNumber !== undefined) params.body.callbackNumber = callbackNumber;
+    if (humanOnly !== undefined) params.body.humanOnly = humanOnly;
+    if (hangup !== undefined) params.body.hangup = hangup;
+
+    return await internalRequest(
+      this.sdk,
+      '/taskRouter/tasks/release',
+      'PUT',
+      params,
+    );
+  }
+
   /**
    * Staff-only internal note on a task (webchat/SMS/voice feed, or
    * timeline). Never sent to the customer.
@@ -871,6 +945,8 @@ export class TaskService {
    * @param {string} [options.subject] - The new subject/title for the task
    * @param {string} [options.summary] - The overall summary for the task
    * @param {string} [options.disposition] - The disposition code or outcome for the task (e.g., 'resolved', 'escalated', 'callback-scheduled')
+   * @param {boolean} [options.botEligible] - Routing flag. `false` = never offer this task to bot workers (human only); `true` re-allows bots
+   * @param {?string} [options.humanFollowUp] - What a human still owes this customer: 'callback' | 'message' | 'dispatch' | 'quote' | 'other', or null to clear. Read by the caller-hangup safety net so an abandoned call with this set releases to the queue instead of completing.
    * @returns {Promise<Object>} Object containing the task ID
    * @returns {string} result.taskId - The task ID that was updated
    *
@@ -898,6 +974,10 @@ export class TaskService {
    *   disposition: 'escalated'
    * });
    * console.log(result.taskId); // "task789"
+   *
+   * @example
+   * // Human-only routing: bot workers are no longer offered this task
+   * await sdk.taskRouter.task.update({ taskId: 'task789', botEligible: false });
    */
   async update(options = {}) {
     const {
@@ -908,10 +988,22 @@ export class TaskService {
       cdrId,
       summary,
       sentiment,
+      botEligible,
+      humanFollowUp,
     } = options;
 
     this.sdk.validateParams(
-      { taskId, subject, disposition, sipCallId, cdrId, summary, sentiment },
+      {
+        taskId,
+        subject,
+        disposition,
+        sipCallId,
+        cdrId,
+        summary,
+        sentiment,
+        botEligible,
+        humanFollowUp,
+      },
       {
         taskId: { type: 'string', required: true },
         subject: { type: 'string', required: false },
@@ -920,6 +1012,10 @@ export class TaskService {
         sipCallId: { type: 'string', required: false },
         summary: { type: 'string', required: false },
         sentiment: { type: 'object', required: false },
+        botEligible: { type: 'boolean', required: false },
+        // validateParams already skips type-checking a null value (see
+        // base.js) -- 'string' here only constrains the non-null case.
+        humanFollowUp: { type: 'string', required: false },
       },
     );
 
@@ -929,6 +1025,14 @@ export class TaskService {
       },
     };
 
+    if (botEligible !== undefined) {
+      params.body.botEligible = botEligible;
+    }
+
+    if (humanFollowUp !== undefined) {
+      params.body.humanFollowUp = humanFollowUp;
+    }
+
     if (subject !== undefined) {
       params.body.subject = subject;
     }
@@ -1141,22 +1245,37 @@ export class TaskService {
    * @param {string} [options.target.queueId] - Destination queue ID
    * @param {string} [options.target.workerId] - Destination worker ID
    * @param {string} [options.note] - Optional note for the receiving agent
+   * @param {string} [options.reasonCode] - Transfer reason code — e.g. 'wrong_department', 'customer_requested', 'out_of_scope', 'policy_never_bot', 'language', 'other'. Required when the caller's worker is a bot.
+   * @param {string} [options.reason] - One-sentence transfer reason. Required when the caller's worker is a bot.
    * @returns {Promise<Object>} { taskId, newTaskId }
+   *
+   * @example
+   * // Bot transferring to a configured queue target
+   * await sdk.taskRouter.task.transfer({
+   *   taskId: 'task123',
+   *   target: { queueId: 'billingQueue1' },
+   *   reasonCode: 'wrong_department',
+   *   reason: 'Caller has a billing question',
+   * });
    */
   async transfer(options = {}) {
-    const { taskId, target, note } = options;
+    const { taskId, target, note, reasonCode, reason } = options;
 
     this.sdk.validateParams(
-      { taskId, target, note },
+      { taskId, target, note, reasonCode, reason },
       {
         taskId: { type: 'string', required: true },
         target: { type: 'object', required: true },
         note: { type: 'string', required: false },
+        reasonCode: { type: 'string', required: false },
+        reason: { type: 'string', required: false },
       },
     );
 
     const params = { body: { taskId, target } };
     if (note !== undefined) params.body.note = note;
+    if (reasonCode !== undefined) params.body.reasonCode = reasonCode;
+    if (reason !== undefined) params.body.reason = reason;
 
     return await internalRequest(
       this.sdk,