@unboundcx/sdk 4.13.66 → 4.13.73

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "4.13.66",
+  "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/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 } : {}),
+      },
+    });
+  },
+};