@unboundcx/sdk 4.13.63 → 4.13.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "4.13.63",
+  "version": "4.13.73",
   "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/battleCards.js

@@ -366,6 +366,33 @@ export class BattleCardsService {
    *   queueId: 'queue_123'
    * });
    */
+  /**
+   * Search (or list) battle cards assigned to a queue's packs.
+   * Empty query returns the full pack list; a query ranks title/trigger/body.
+   *
+   * @param {Object} options
+   * @param {string} options.queueId
+   * @param {string} [options.query]
+   * @param {string} [options.q]
+   * @returns {Promise<Object>} { results, query }
+   */
+  async searchQueueCards({ queueId, query, q } = {}) {
+    this.sdk.validateParams(
+      { queueId },
+      {
+        queueId: { type: 'string', required: true },
+      },
+    );
+
+    const result = await internalRequest(
+      this.sdk,
+      `/ai/battleCards/queues/${queueId}/cards`,
+      'GET',
+      { query: { q: query || q || '' } },
+    );
+    return result;
+  }
+
   async listQueuePacks({ queueId }) {
     this.sdk.validateParams(
       { queueId },

package/services/fax.js

@@ -263,4 +263,31 @@ export class FaxService {
 
     return await internalRequest(this.sdk, '/fax/status', 'POST', params);
   }
+
+  /**
+   * Retry a failed outbound fax. Resets the same fax document row (status
+   * back to 'pending', clears isError/errorMessage/sipCallId, bumps
+   * sendAttempts) and re-dispatches it through the same media-manager path
+   * as sdk.fax.send() -- only valid for outbound documents currently in
+   * status 'failed'.
+   *
+   * @param {string} id - The fax document ID to retry (required)
+   * @returns {Promise<Object>} Retry result
+   * @returns {string} result.id - The fax document ID
+   * @returns {string} result.status - 'sending' on success, 'failed' on NATS error
+   *
+   * @example
+   * const result = await sdk.fax.retry('158abc123...');
+   * console.log(result.status); // 'sending'
+   */
+  async retry(id) {
+    this.sdk.validateParams(
+      { id },
+      {
+        id: { type: 'string', required: true },
+      },
+    );
+
+    return await internalRequest(this.sdk, `/fax/${id}/retry`, 'POST', {});
+  }
 }

package/services/knowledgeBase.js

@@ -21,7 +21,15 @@ export class KnowledgeBaseService {
    *   Each result's source now also includes isPublic, knowledgeBaseId, knowledgeBaseName.
    * @returns {Promise<Object>} Search results with source attribution
    */
-  async search({ query, knowledgeBaseId, limit, filters, rerank, visibility }) {
+  async search({
+    query,
+    knowledgeBaseId,
+    limit,
+    filters,
+    rerank,
+    visibility,
+    taskId,
+  }) {
     this.sdk.validateParams(
       { query },
       {
@@ -30,7 +38,15 @@ export class KnowledgeBaseService {
     );
 
     const params = {
-      body: { query, knowledgeBaseId, limit, filters, rerank, visibility },
+      body: {
+        query,
+        knowledgeBaseId,
+        limit,
+        filters,
+        rerank,
+        visibility,
+        taskId,
+      },
     };
 
     const result = await internalRequest(this.sdk, 
@@ -41,6 +57,34 @@ export class KnowledgeBaseService {
     return result;
   }
 
+  async listQueueKnowledgeBases({ queueId }) {
+    this.sdk.validateParams(
+      { queueId },
+      { queueId: { type: 'string', required: true } },
+    );
+    return internalRequest(
+      this.sdk,
+      `/knowledgeBase/queues/${queueId}/knowledgeBases`,
+      'GET',
+    );
+  }
+
+  async setQueueKnowledgeBases({ queueId, knowledgeBaseIds }) {
+    this.sdk.validateParams(
+      { queueId, knowledgeBaseIds },
+      {
+        queueId: { type: 'string', required: true },
+        knowledgeBaseIds: { type: 'array', required: true },
+      },
+    );
+    return internalRequest(
+      this.sdk,
+      `/knowledgeBase/queues/${queueId}/knowledgeBases`,
+      'PUT',
+      { body: { knowledgeBaseIds } },
+    );
+  }
+
   /**
    * Discover pages available at a URL
    * Checks for sitemaps (auto-discovery + direct sitemap URLs) and returns
@@ -256,6 +300,12 @@ export class KnowledgeBaseService {
    * @param {Object} [params.filters] - Optional date range, source type filters
    * @returns {Promise<Object>} Analytics data
    */
+  async getAccountAnalytics(filters = {}) {
+    return internalRequest(this.sdk, '/knowledgeBase/analytics', 'GET', {
+      query: filters,
+    });
+  }
+
   async getAnalytics({ knowledgeBaseId, ...filters }) {
     this.sdk.validateParams(
       { knowledgeBaseId },
@@ -304,4 +354,55 @@ export class KnowledgeBaseService {
     );
     return result;
   }
+
+  async listTaskPins({ taskId }) {
+    this.sdk.validateParams(
+      { taskId },
+      { taskId: { type: 'string', required: true } },
+    );
+    return internalRequest(
+      this.sdk,
+      `/knowledgeBase/tasks/${taskId}/pins`,
+      'GET',
+    );
+  }
+
+  async pinTaskSource({
+    taskId,
+    sourceId,
+    sourceType,
+    knowledgeBaseId,
+    title,
+  }) {
+    this.sdk.validateParams(
+      { taskId, sourceId },
+      {
+        taskId: { type: 'string', required: true },
+        sourceId: { type: 'string', required: true },
+      },
+    );
+    return internalRequest(
+      this.sdk,
+      `/knowledgeBase/tasks/${taskId}/pins`,
+      'POST',
+      {
+        body: { sourceId, sourceType, knowledgeBaseId, title },
+      },
+    );
+  }
+
+  async unpinTaskSource({ taskId, pinId }) {
+    this.sdk.validateParams(
+      { taskId, pinId },
+      {
+        taskId: { type: 'string', required: true },
+        pinId: { type: 'string', required: true },
+      },
+    );
+    return internalRequest(
+      this.sdk,
+      `/knowledgeBase/tasks/${taskId}/pins/${pinId}`,
+      'DELETE',
+    );
+  }
 }

package/services/objects.js

@@ -118,6 +118,7 @@ export class ObjectsService {
         limit = 100,
         nextId = null,
         previousId = null,
+        orderBy = null,
         orderByDirection = 'DESC',
         expandDetails = false,
         meta = {},
@@ -131,6 +132,7 @@ export class ObjectsService {
           limit,
           nextId,
           previousId,
+          orderBy,
           orderByDirection,
           expandDetails,
           meta,
@@ -142,6 +144,7 @@ export class ObjectsService {
           limit: { type: 'number', required: false },
           nextId: { type: 'string', required: false },
           previousId: { type: 'string', required: false },
+          orderBy: { type: 'string', required: false }, // base-table column; ties break createdAt ASC, id ASC
           orderByDirection: { type: 'string', required: false },
           expandDetails: { type: 'boolean', required: false },
           meta: { type: 'object', required: false },
@@ -153,6 +156,7 @@ export class ObjectsService {
       if (limit !== 100) query.limit = limit;
       if (nextId !== null) query.nextId = nextId;
       if (previousId !== null) query.previousId = previousId;
+      if (orderBy !== null) query.orderBy = orderBy;
       if (orderByDirection !== 'DESC')
         query.orderByDirection = orderByDirection;
       if (expandDetails) query.expandDetails = expandDetails;

package/services/permissions.js

@@ -570,7 +570,7 @@ export class PermissionsService {
     });
   }
 
-  /** Queues this group grants. @returns {Promise<{results: Array<{queueId, access, autoLogin}>}>} */
+  /** Queues this group grants. @returns {Promise<{results: Array<{queueId, access, autoLogin, role}>}>} */
   async listGroupQueues(groupId) {
     groupId = String(groupId);
     this.sdk.validateParams(
@@ -582,10 +582,11 @@ export class PermissionsService {
 
   /**
    * Replace the group's full queue list.
-   * @param {Array<{queueId: string, access?: boolean, autoLogin?: boolean}>} queues
+   * @param {Array<{queueId: string, access?: boolean, autoLogin?: boolean, role?: string}>} queues
    *   `autoLogin` seeds the derived membership row and takes effect at the
    *   agent's next availability transition — it never logs anyone in
-   *   mid-session.
+   *   mid-session. `role` ('agent'|'manager', default 'agent') is the
+   *   queueUsers.role materialised for group members via this queue.
    */
   async setGroupQueues(groupId, queues) {
     groupId = String(groupId);
@@ -602,6 +603,7 @@ export class PermissionsService {
           queueId: String(q.queueId),
           access: q.access !== false,
           autoLogin: Boolean(q.autoLogin),
+          role: q.role || 'agent',
         })),
       },
     });

package/services/taskRouter/CCService.js

@@ -23,6 +23,29 @@ export class CCService {
     return result;
   }
 
+  /**
+   * Get the queueIds the caller manages (queueUsers.role='manager', direct
+   * or group-materialised) -- for UI that needs a single "is this user a
+   * manager of at least one queue" check without gating on the coarser,
+   * account-wide `getScope().isManager`.
+   *
+   * @returns {Promise<Object>} result
+   * @returns {string[]} result.queueIds - Queue ids the caller manages
+   *
+   * @example
+   * const { queueIds } = await sdk.taskRouter.cc.getManagedQueues();
+   * const isAnyQueueManager = queueIds.length > 0;
+   */
+  async getManagedQueues() {
+    const result = await internalRequest(
+      this.sdk,
+      '/taskRouter/queues/managed',
+      'GET',
+      {},
+    );
+    return result;
+  }
+
   /**
    * Get a live Contact Center snapshot (KPIs, per-queue summaries, team roster
    * with active tasks) scoped to a set of queues.

package/services/taskRouter/ParticipantService.js

@@ -50,6 +50,8 @@ export class ParticipantService {
    * @param {string} [options.displayName] - Optional display name shown for the external caller (kind 'external')
    * @param {string} [options.note] - Optional note shown to the invitee
    * @param {string} [options.bridgeRole='main'] - Voice bridge role (only 'main' is supported until the media update)
+   * @param {boolean} [options.self] - When kind is 'user', true to join the CALLER onto the task themselves (R1 self-join) instead of inviting `userId`
+   * @param {string} [options.role] - Self-join role: 'helper' (visible) or 'monitor' (private/observe, gated server-side)
    * @returns {Promise<Object>} { participant, offerId } for kind 'user'; { helpTaskId } for kind 'queue'; { participant } for kind 'external'
    *
    * @example
@@ -58,6 +60,8 @@ export class ParticipantService {
    * await sdk.taskRouter.participants.add({ taskId: 'task_123', kind: 'queue', queueId: 'queue_789' });
    * @example
    * await sdk.taskRouter.participants.add({ taskId: 'task_123', kind: 'external', phoneNumber: '+15551234567', displayName: 'Jane Doe' });
+   * @example
+   * await sdk.taskRouter.participants.add({ taskId: 'task_123', kind: 'user', self: true, role: 'helper' });
    */
   async add({
     taskId,
@@ -70,6 +74,8 @@ export class ParticipantService {
     displayName,
     note,
     bridgeRole,
+    self,
+    role,
   } = {}) {
     this.sdk.validateParams(
       {
@@ -83,6 +89,8 @@ export class ParticipantService {
         displayName,
         note,
         bridgeRole,
+        self,
+        role,
       },
       {
         taskId: { type: 'string', required: true },
@@ -95,6 +103,8 @@ export class ParticipantService {
         displayName: { type: 'string', required: false },
         note: { type: 'string', required: false },
         bridgeRole: { type: 'string', required: false },
+        self: { type: 'boolean', required: false },
+        role: { type: 'string', required: false },
       },
     );
 
@@ -107,6 +117,8 @@ export class ParticipantService {
     if (displayName !== undefined) params.body.displayName = displayName;
     if (note !== undefined) params.body.note = note;
     if (bridgeRole !== undefined) params.body.bridgeRole = bridgeRole;
+    if (self !== undefined) params.body.self = self;
+    if (role !== undefined) params.body.role = role;
 
     return await internalRequest(
       this.sdk,
@@ -183,8 +195,43 @@ export class ParticipantService {
     );
   }
 
+  /**
+   * Go public: promote the caller's own private (monitor) row to a normal
+   * (helper) participant. Self-only -- the server rejects this for any
+   * participant row other than the caller's own, and only when that row's
+   * current role is 'monitor'. Runs the normal helper-join chain server-side
+   * (worker session, task-router join, capacity, Team-channel membership)
+   * and unmutes the caller's voice leg when the task has one.
+   *
+   * @param {Object} options - Options
+   * @param {string} options.taskId - Task ID
+   * @param {string} options.participantId - The caller's own (monitor) participant ID
+   * @returns {Promise<Object>}
+   *
+   * @example
+   * await sdk.taskRouter.participants.goPublic({ taskId: 'task_123', participantId: 'tp_456' });
+   */
+  async goPublic({ taskId, participantId } = {}) {
+    this.sdk.validateParams(
+      { taskId, participantId },
+      {
+        taskId: { type: 'string', required: true },
+        participantId: { type: 'string', required: true },
+      },
+    );
+
+    return await internalRequest(
+      this.sdk,
+      `/taskRouter/tasks/${taskId}/participants/${participantId}`,
+      'PATCH',
+      { body: { role: 'helper' } },
+    );
+  }
+
   /**
    * Remove a participant: drop them (owner/manager) or leave (self).
+   * Also used for a private (monitor) row's self-leave -- the server routes
+   * a caller's own row through the monitor leave/hangup path automatically.
    *
    * @param {Object} options - Options
    * @param {string} options.taskId - Task ID
@@ -193,6 +240,9 @@ export class ParticipantService {
    *
    * @example
    * await sdk.taskRouter.participants.remove({ taskId: 'task_123', participantId: 'tp_456' });
+   * @example
+   * // Self-leave a private (monitor) row -- same method, own participantId
+   * await sdk.taskRouter.participants.leave({ taskId: 'task_123', participantId: 'tp_456' });
    */
   async remove({ taskId, participantId }) {
     this.sdk.validateParams(
@@ -297,4 +347,22 @@ export class ParticipantService {
       'GET',
     );
   }
+
+  /**
+   * Leave the caller's own participant row (helper or private/monitor).
+   * Alias for {@link remove} scoped to your own row -- the server enforces
+   * self-only removal for a monitor row via the same DELETE route (media
+   * leg hangup, row left, `task_private_leave` audit for a monitor row).
+   *
+   * @param {Object} options - Options
+   * @param {string} options.taskId - Task ID
+   * @param {string} options.participantId - The caller's own participant ID
+   * @returns {Promise<Object>}
+   *
+   * @example
+   * await sdk.taskRouter.participants.leave({ taskId: 'task_123', participantId: 'tp_456' });
+   */
+  async leave({ taskId, participantId }) {
+    return await this.remove({ taskId, participantId });
+  }
 }

package/services/taskRouter/TaskService.js

@@ -1,4 +1,5 @@
 import { internalRequest } from '../../base.js';
+import { taskWorkspaceMethods } from './TaskWorkspaceMethods.js';
 export class TaskService {
   constructor(sdk) {
     this.sdk = sdk;
@@ -1154,3 +1155,7 @@ export class TaskService {
     );
   }
 }
+
+// CC task-workspace methods (claim/observe/unobserve/observers/take/access)
+// live in TaskWorkspaceMethods.js to keep this file from growing further.
+Object.assign(TaskService.prototype, taskWorkspaceMethods);

package/services/taskRouter/TaskWorkspaceMethods.js

@@ -0,0 +1,189 @@
+import { internalRequest } from '../../base.js';
+
+// CC task-workspace methods (claim / observe / self-join-derived access / take)
+// mixed onto TaskService.prototype. Split into its own file to keep
+// TaskService.js from growing further past the 400-line guideline.
+export const taskWorkspaceMethods = {
+  /**
+   * Claim an unassigned task (pending/waiting/parked with no assignee).
+   * Force-assigns the task to the caller's worker with a normal ring/offer
+   * (not assign-connected) -- the caller still sees the usual offer card
+   * and accepts manually.
+   *
+   * @param {Object} options - Parameters
+   * @param {string} options.taskId - The task ID to claim (required)
+   * @returns {Promise<{taskId:string, workerId:string, status:string}>}
+   */
+  async claim(options = {}) {
+    const { taskId } = options;
+
+    this.sdk.validateParams(
+      { taskId },
+      { taskId: { type: 'string', required: true } },
+    );
+
+    return await internalRequest(
+      this.sdk,
+      `/taskRouter/tasks/${taskId}/claim`,
+      'POST',
+      {},
+    );
+  },
+
+  /**
+   * Send an observer-presence heartbeat for a task. Call on an interval
+   * (< 45s) while a manager/queue member is watching a task read-only;
+   * membership expires automatically if heartbeats stop.
+   *
+   * @param {Object} options - Parameters
+   * @param {string} options.taskId - The task ID to observe (required)
+   * @returns {Promise<{ok:boolean}>}
+   */
+  async observe(options = {}) {
+    const { taskId } = options;
+
+    this.sdk.validateParams(
+      { taskId },
+      { taskId: { type: 'string', required: true } },
+    );
+
+    return await internalRequest(
+      this.sdk,
+      `/taskRouter/tasks/${taskId}/observe`,
+      'POST',
+      {},
+    );
+  },
+
+  /**
+   * Stop observing a task (removes the caller from the observer set).
+   *
+   * @param {Object} options - Parameters
+   * @param {string} options.taskId - The task ID to stop observing (required)
+   * @returns {Promise<{ok:boolean}>}
+   */
+  async unobserve(options = {}) {
+    const { taskId } = options;
+
+    this.sdk.validateParams(
+      { taskId },
+      { taskId: { type: 'string', required: true } },
+    );
+
+    return await internalRequest(
+      this.sdk,
+      `/taskRouter/tasks/${taskId}/observe`,
+      'DELETE',
+      {},
+    );
+  },
+
+  /**
+   * List the current observers of a task. Manager-only.
+   *
+   * @param {Object} options - Parameters
+   * @param {string} options.taskId - The task ID (required)
+   * @returns {Promise<Array<{userId:string, name:string, since:string}>>}
+   */
+  async observers(options = {}) {
+    const { taskId } = options;
+
+    this.sdk.validateParams(
+      { taskId },
+      { taskId: { type: 'string', required: true } },
+    );
+
+    return await internalRequest(
+      this.sdk,
+      `/taskRouter/tasks/${taskId}/observers`,
+      'GET',
+      {},
+    );
+  },
+
+  /**
+   * Seize ownership of a currently-assigned task away from its owner.
+   * Queue-manager only; reuses the normal transfer-offer chain with the
+   * caller as target, so the caller gets the usual offer card and accepts
+   * manually (ownership moves on accept, not on this call).
+   *
+   * @param {Object} options - Parameters
+   * @param {string} options.taskId - The task ID to take (required)
+   * @returns {Promise<{offerId:string}>}
+   */
+  async take(options = {}) {
+    const { taskId } = options;
+
+    this.sdk.validateParams(
+      { taskId },
+      { taskId: { type: 'string', required: true } },
+    );
+
+    return await internalRequest(
+      this.sdk,
+      `/taskRouter/tasks/${taskId}/take`,
+      'POST',
+      {},
+    );
+  },
+
+  /**
+   * Compute the caller's entry-point access mode for a task, used to drive
+   * which open/join/take/claim actions the client offers.
+   *
+   * @param {Object} options - Parameters
+   * @param {string} options.taskId - The task ID (required)
+   * @returns {Promise<{
+   *   mode: 'owner'|'helper'|'helperLimited'|'claim'|'observe'|'none',
+   *   canJoin: boolean,
+   *   canPrivate: boolean,
+   *   canTake: boolean,
+   *   canClaim: boolean,
+   *   isQueueManager: boolean,
+   *   isQueueMember: boolean,
+   *   ownerName: string|null,
+   * }>}
+   */
+  async access(options = {}) {
+    const { taskId } = options;
+
+    this.sdk.validateParams(
+      { taskId },
+      { taskId: { type: 'string', required: true } },
+    );
+
+    return await internalRequest(
+      this.sdk,
+      `/taskRouter/tasks/${taskId}/access`,
+      'GET',
+      {},
+    );
+  },
+
+  /**
+   * Exact per-status task counts (GAP B, cc-task-workspace-plan.md §2.2) --
+   * replaces client-side approximations that count a page-size-capped
+   * results list. ACL = logged-in user, scoped to the caller's account.
+   *
+   * @param {Object} options - Parameters
+   * @param {string[]} options.statuses - Task statuses to count, e.g. ['parked']
+   * @param {boolean} [options.mine] - Scope to the caller's own workerId
+   *   (same filter as the mini-card strip's owned-tasks fetch)
+   * @returns {Promise<{counts: Object<string, number>}>}
+   */
+  async counts(options = {}) {
+    const { statuses, mine } = options;
+
+    this.sdk.validateParams(
+      { statuses },
+      { statuses: { type: 'array', required: true } },
+    );
+
+    return await internalRequest(this.sdk, `/taskRouter/tasks/counts`, 'GET', {
+      query: {
+        statuses: statuses.join(','),
+        ...(mine !== undefined ? { mine } : {}),
+      },
+    });
+  },
+};

package/services/taskRouter/WorkerService.js

@@ -195,6 +195,84 @@ export class WorkerService {
     return result;
   }
 
+  /**
+   * Set the authenticated user's own worker paused state
+   * Pauses (or unpauses) the caller's own worker so it stays logged into its queues
+   * but stops receiving new task offers. Requires Contact Center access.
+   *
+   * @param {Object} options - Parameters
+   * @param {boolean} options.paused - Whether the worker should be paused
+   * @returns {Promise<Object>} The updated worker
+   *
+   * @example
+   * // Pause the authenticated user's own worker
+   * const worker = await sdk.taskRouter.worker.setPaused({ paused: true });
+   *
+   * @example
+   * // Unpause
+   * const worker = await sdk.taskRouter.worker.setPaused({ paused: false });
+   */
+  async setPaused(options = {}) {
+    const { paused } = options;
+
+    this.sdk.validateParams(
+      { paused },
+      {
+        paused: { type: 'boolean', required: true },
+      },
+    );
+
+    const params = {
+      body: { paused },
+    };
+
+    const result = await internalRequest(this.sdk,
+      '/taskRouter/workers/me/paused',
+      'PUT',
+      params,
+    );
+    return result;
+  }
+
+  /**
+   * Set another worker's paused state
+   * Pauses (or unpauses) a specific worker by workerId. The caller must be a queue
+   * manager for at least one queue that worker is logged into or assigned to.
+   *
+   * @param {Object} options - Parameters
+   * @param {string} options.workerId - The worker ID to update (required)
+   * @param {boolean} options.paused - Whether the worker should be paused
+   * @returns {Promise<Object>} The updated worker
+   *
+   * @example
+   * const worker = await sdk.taskRouter.worker.setWorkerPaused({
+   *   workerId: '0860002026012400000006665842155429980',
+   *   paused: true,
+   * });
+   */
+  async setWorkerPaused(options = {}) {
+    const { workerId, paused } = options;
+
+    this.sdk.validateParams(
+      { workerId, paused },
+      {
+        workerId: { type: 'string', required: true },
+        paused: { type: 'boolean', required: true },
+      },
+    );
+
+    const params = {
+      body: { paused },
+    };
+
+    const result = await internalRequest(this.sdk,
+      `/taskRouter/workers/${workerId}/paused`,
+      'PUT',
+      params,
+    );
+    return result;
+  }
+
   /**
    * Automatically login all auto-login queues for a worker
    * When a worker goes available, this logs them into all queues marked with autoLogin = true.