@unboundcx/sdk 4.13.66 → 4.13.74

package/index.js

@@ -22,6 +22,7 @@ import { PortalsService } from './services/portals.js';
 import { DealRegistrationsService } from './services/dealRegistrations.js';
 import { SipEndpointsService } from './services/sipEndpoints.js';
 import { WebchatService } from './services/webchat.js';
+import { CobrowseService } from './services/cobrowse.js';
 import { MessageTemplatesService } from './services/messageTemplates.js';
 import { ExternalOAuthService } from './services/externalOAuth.js';
 import { GoogleCalendarService } from './services/googleCalendar.js';
@@ -118,6 +119,7 @@ class UnboundSDK extends BaseSDK {
     this.dealRegistrations = new DealRegistrationsService(this);
     this.sipEndpoints = new SipEndpointsService(this);
     this.webchat = new WebchatService(this);
+    this.cobrowse = new CobrowseService(this);
     this.messageTemplates = new MessageTemplatesService(this);
     this.externalOAuth = new ExternalOAuthService(this);
     this.googleCalendar = new GoogleCalendarService(this);
@@ -314,6 +316,7 @@ export { PortalsService } from './services/portals.js';
 export { DealRegistrationsService } from './services/dealRegistrations.js';
 export { SipEndpointsService } from './services/sipEndpoints.js';
 export { WebchatService, WebchatWidgetsService } from './services/webchat.js';
+export { CobrowseService, CobrowseVisitorService } from './services/cobrowse.js';
 export { MessageTemplatesService } from './services/messageTemplates.js';
 export { WebchatVisitorService } from './services/webchat/VisitorService.js';
 export { ExternalOAuthService } from './services/externalOAuth.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "4.13.66",
+  "version": "4.13.74",
   "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/cobrowse.js

@@ -0,0 +1,211 @@
+import { internalRequest } from '../base.js';
+
+function authHeaders(token) {
+  return token ? { headers: { Authorization: `Bearer ${token}` } } : {};
+}
+
+function assertWebchatSource(source, method) {
+  if (source !== 'webchat') {
+    throw new Error(
+      `cobrowse.${method}: source '${source}' is not supported (v1 is webchat only)`,
+    );
+  }
+}
+
+function webchatHostIds(
+  { source, widgetId, hostId, engagementSessionId } = {},
+  method,
+) {
+  const esId = hostId ?? engagementSessionId;
+  assertWebchatSource(source, method);
+  return { widgetId, engagementSessionId: esId };
+}
+
+function conversationCobrowsePath(widgetId, engagementSessionId, suffix = '') {
+  return `/webchat/widgets/${widgetId}/conversations/${engagementSessionId}/cobrowse${suffix}`;
+}
+
+/**
+ * Visitor cobrowse consent (session JWT). Custom UIs; embed uses
+ * webchatApi.js in P1. Paths are public `/webchat/:widgetId/cobrowse/*`.
+ */
+export class CobrowseVisitorService {
+  constructor(sdk) {
+    this.sdk = sdk;
+  }
+
+  async #post(action, { widgetId, token, sid } = {}) {
+    this.sdk.validateParams(
+      { widgetId, token, sid },
+      {
+        widgetId: { type: 'string', required: true },
+        token: { type: 'string', required: true },
+        sid: { type: 'string', required: true },
+      },
+    );
+    return internalRequest(
+      this.sdk,
+      `/webchat/${widgetId}/cobrowse/${action}`,
+      'POST',
+      { body: { sid }, ...authHeaders(token) },
+      true,
+    );
+  }
+
+  /**
+   * Accept a pending cobrowse request. Starts live after API 200.
+   * @param {Object} params
+   * @param {string} params.widgetId
+   * @param {string} params.token - Webchat session JWT
+   * @param {string} params.sid
+   */
+  async accept(params) {
+    return this.#post('accept', params);
+  }
+
+  /**
+   * Decline a pending cobrowse request.
+   * @param {Object} params
+   * @param {string} params.widgetId
+   * @param {string} params.token
+   * @param {string} params.sid
+   */
+  async deny(params) {
+    return this.#post('deny', params);
+  }
+
+  /**
+   * Visitor-initiated end of a live/requested cobrowse session.
+   * @param {Object} params
+   * @param {string} params.widgetId
+   * @param {string} params.token
+   * @param {string} params.sid
+   */
+  async end(params) {
+    return this.#post('end', params);
+  }
+}
+
+/**
+ * Host-agnostic cobrowse surface (`sdk.cobrowse.*`). v1 adapter is
+ * WebChat; Meet later uses the same method names with `source:'meet'`.
+ * No `sdk.webchat.cobrowse`. No `getRecording` in this box.
+ */
+export class CobrowseService {
+  constructor(sdk) {
+    this.sdk = sdk;
+    this.visitor = new CobrowseVisitorService(sdk);
+  }
+
+  /**
+   * Agent request. Nested under the webchat conversation.
+   * @param {Object} params
+   * @param {'webchat'} params.source
+   * @param {string} params.widgetId
+   * @param {string} params.hostId - engagementSessionId when source is webchat
+   * @param {string} [params.engagementSessionId] - alias of hostId
+   * @param {'pointer'|'write'} [params.mode='pointer']
+   * @param {boolean} [params.record=false]
+   */
+  async request({
+    source,
+    widgetId,
+    hostId,
+    engagementSessionId,
+    mode = 'pointer',
+    record = false,
+  } = {}) {
+    const ids = webchatHostIds(
+      { source, widgetId, hostId, engagementSessionId },
+      'request',
+    );
+    this.sdk.validateParams(
+      { source, widgetId, hostId: ids.engagementSessionId, mode, record },
+      {
+        source: { type: 'string', required: true },
+        widgetId: { type: 'string', required: true },
+        hostId: { type: 'string', required: true },
+        mode: { type: 'string', required: false },
+        record: { type: 'boolean', required: false },
+      },
+    );
+    return internalRequest(
+      this.sdk,
+      conversationCobrowsePath(ids.widgetId, ids.engagementSessionId, '/request'),
+      'POST',
+      { body: { mode, record: record === true } },
+    );
+  }
+
+  /**
+   * Agent end. Nested under the conversation because the HTTP route is.
+   * @param {Object} params
+   * @param {string} params.sid
+   * @param {string} params.widgetId
+   * @param {string} [params.hostId]
+   * @param {string} [params.engagementSessionId]
+   * @param {'webchat'} [params.source='webchat']
+   */
+  async end({
+    sid,
+    widgetId,
+    hostId,
+    engagementSessionId,
+    source = 'webchat',
+  } = {}) {
+    const ids = webchatHostIds(
+      { source, widgetId, hostId, engagementSessionId },
+      'end',
+    );
+    this.sdk.validateParams(
+      { sid, widgetId, hostId: ids.engagementSessionId },
+      {
+        sid: { type: 'string', required: true },
+        widgetId: { type: 'string', required: true },
+        hostId: { type: 'string', required: true },
+      },
+    );
+    return internalRequest(
+      this.sdk,
+      conversationCobrowsePath(
+        ids.widgetId,
+        ids.engagementSessionId,
+        `/${sid}/end`,
+      ),
+      'POST',
+    );
+  }
+
+  /**
+   * Current cobrowse session metadata for this host (no DOM).
+   * @param {Object} params
+   * @param {'webchat'} params.source
+   * @param {string} params.widgetId
+   * @param {string} params.hostId
+   * @param {string} [params.engagementSessionId]
+   */
+  async getActive({
+    source,
+    widgetId,
+    hostId,
+    engagementSessionId,
+  } = {}) {
+    const ids = webchatHostIds(
+      { source, widgetId, hostId, engagementSessionId },
+      'getActive',
+    );
+    this.sdk.validateParams(
+      { source, widgetId, hostId: ids.engagementSessionId },
+      {
+        source: { type: 'string', required: true },
+        widgetId: { type: 'string', required: true },
+        hostId: { type: 'string', required: true },
+      },
+    );
+    return internalRequest(
+      this.sdk,
+      conversationCobrowsePath(ids.widgetId, ids.engagementSessionId, '/active'),
+      'GET',
+    );
+  }
+}

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 } : {}),
+      },
+    });
+  },
+};