@unboundcx/sdk 4.13.155 → 4.13.156

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unboundcx/sdk",
3
- "version": "4.13.155",
3
+ "version": "4.13.156",
4
4
  "description": "Official JavaScript SDK for the Unbound API - A comprehensive toolkit for integrating with Unbound's communication, AI, and data management services",
5
5
  "main": "index.js",
6
6
  "type": "module",
@@ -1097,6 +1097,302 @@ export class PlaybooksService {
1097
1097
  return result;
1098
1098
  }
1099
1099
 
1100
+ /**
1101
+ * Resolve a playbook session by task only (no workerId/userId needed).
1102
+ * Thin wrapper over `getSession({ taskId })` for callers that only ever
1103
+ * look up by task, such as the live-scoring engine.
1104
+ *
1105
+ * @param {Object} options - Options
1106
+ * @param {string} options.taskId - The task ID
1107
+ * @param {boolean} [options.includeQa] - Include review-only goals and qaReview
1108
+ * @returns {Promise<Object>} Session object with playbookName, goals[] and participants[]
1109
+ *
1110
+ * @example
1111
+ * const session = await sdk.ai.playbooks.getSessionByTask({ taskId: 'task_123' });
1112
+ */
1113
+ async getSessionByTask({ taskId, includeQa }) {
1114
+ this.sdk.validateParams(
1115
+ { taskId },
1116
+ {
1117
+ taskId: { type: "string", required: true },
1118
+ includeQa: { type: "boolean", required: false },
1119
+ },
1120
+ );
1121
+
1122
+ return this.getSession({ taskId, includeQa });
1123
+ }
1124
+
1125
+ /**
1126
+ * Batch-upsert goal rows for a playbook session (replaces per-goal
1127
+ * `logGoal` for the live-scoring engine).
1128
+ *
1129
+ * @param {Object} options - Options
1130
+ * @param {string} options.sessionId - The ID of the session
1131
+ * @param {Array<Object>} options.goals - Goal rows: `[{ goalId, achieved,
1132
+ * missed, score, reason, confidence, evidence, coachingSuggestion }]`
1133
+ * @returns {Promise<Object>} Result with playbookSessionId
1134
+ *
1135
+ * @example
1136
+ * await sdk.ai.playbooks.logGoals({
1137
+ * sessionId: 'pbs_abc123',
1138
+ * goals: [
1139
+ * { goalId: 'goal_456', achieved: true, score: 10, reason: '...', confidence: 0.95 },
1140
+ * { goalId: 'goal_789', achieved: false, missed: true, score: 0 },
1141
+ * ],
1142
+ * });
1143
+ */
1144
+ async logGoals({ sessionId, goals }) {
1145
+ this.sdk.validateParams(
1146
+ { sessionId, goals },
1147
+ {
1148
+ sessionId: { type: "string", required: true },
1149
+ goals: { type: "array", required: true },
1150
+ },
1151
+ );
1152
+
1153
+ const params = {
1154
+ body: { goals },
1155
+ };
1156
+
1157
+ const result = await internalRequest(
1158
+ this.sdk,
1159
+ `/ai/playbooks/sessions/${sessionId}/goals`,
1160
+ "POST",
1161
+ params,
1162
+ );
1163
+ return result;
1164
+ }
1165
+
1166
+ /**
1167
+ * Set (reassign) the owner of a playbook session, e.g. on a task
1168
+ * transfer.
1169
+ *
1170
+ * @param {Object} options - Options
1171
+ * @param {string} options.sessionId - The ID of the session
1172
+ * @param {string} options.workerId - The new owning worker's ID
1173
+ * @param {string} options.userId - The new owning user's ID
1174
+ * @returns {Promise<Object>} Result with playbookSessionId
1175
+ *
1176
+ * @example
1177
+ * await sdk.ai.playbooks.setOwner({
1178
+ * sessionId: 'pbs_abc123',
1179
+ * workerId: 'worker_456',
1180
+ * userId: 'user_789',
1181
+ * });
1182
+ */
1183
+ async setOwner({ sessionId, workerId, userId }) {
1184
+ this.sdk.validateParams(
1185
+ { sessionId, workerId, userId },
1186
+ {
1187
+ sessionId: { type: "string", required: true },
1188
+ workerId: { type: "string", required: true },
1189
+ userId: { type: "string", required: true },
1190
+ },
1191
+ );
1192
+
1193
+ const params = {
1194
+ body: { workerId, userId },
1195
+ };
1196
+
1197
+ const result = await internalRequest(
1198
+ this.sdk,
1199
+ `/ai/playbooks/sessions/${sessionId}/owner`,
1200
+ "PUT",
1201
+ params,
1202
+ );
1203
+ return result;
1204
+ }
1205
+
1206
+ /**
1207
+ * Join or leave a playbook session participant (§7.2.4 / §7.4).
1208
+ *
1209
+ * No `participantId` → join: `POST .../participants` with
1210
+ * `{ workerId, userId, kind, joinedAt }`.
1211
+ * With `participantId` → leave + segment result: `PUT
1212
+ * .../participants/:pid` with `{ leftAt, endReason, segmentTotalScore,
1213
+ * segmentAchievedGoals, segmentTotalGoals, segmentGoals }`.
1214
+ *
1215
+ * @param {Object} options - Options
1216
+ * @param {string} options.sessionId - The ID of the session
1217
+ * @param {string} [options.participantId] - The ID of an existing
1218
+ * participant row to close (leave); omit to join
1219
+ * @param {string} [options.workerId] - The joining worker's ID (join only)
1220
+ * @param {string} [options.userId] - The joining user's ID (join only)
1221
+ * @param {string} [options.kind] - 'human' | 'bot' (join only)
1222
+ * @param {string} [options.joinedAt] - ISO timestamp the participant joined (join only)
1223
+ * @param {string} [options.leftAt] - ISO timestamp the participant left (leave only)
1224
+ * @param {string} [options.endReason] - 'transferred' | 'released' | 'unassigned' | 'completed' (leave only)
1225
+ * @param {number} [options.segmentTotalScore] - Score achieved during this participant's slice
1226
+ * @param {number} [options.segmentAchievedGoals] - Goals achieved during this slice
1227
+ * @param {number} [options.segmentTotalGoals] - Total goals scoped to this slice
1228
+ * @param {Array} [options.segmentGoals] - Per-goal detail for this slice
1229
+ * @returns {Promise<Object>} The created/updated participant row
1230
+ *
1231
+ * @example
1232
+ * // Join
1233
+ * await sdk.ai.playbooks.upsertParticipant({
1234
+ * sessionId: 'pbs_abc123',
1235
+ * workerId: 'worker_456',
1236
+ * userId: 'user_789',
1237
+ * kind: 'human',
1238
+ * joinedAt: new Date().toISOString(),
1239
+ * });
1240
+ *
1241
+ * @example
1242
+ * // Leave
1243
+ * await sdk.ai.playbooks.upsertParticipant({
1244
+ * sessionId: 'pbs_abc123',
1245
+ * participantId: 'pbp_456',
1246
+ * leftAt: new Date().toISOString(),
1247
+ * endReason: 'transferred',
1248
+ * segmentTotalScore: 30,
1249
+ * segmentAchievedGoals: 3,
1250
+ * segmentTotalGoals: 5,
1251
+ * });
1252
+ */
1253
+ async upsertParticipant({
1254
+ sessionId,
1255
+ participantId,
1256
+ workerId,
1257
+ userId,
1258
+ kind,
1259
+ joinedAt,
1260
+ leftAt,
1261
+ endReason,
1262
+ segmentTotalScore,
1263
+ segmentAchievedGoals,
1264
+ segmentTotalGoals,
1265
+ segmentGoals,
1266
+ }) {
1267
+ if (!participantId) {
1268
+ this.sdk.validateParams(
1269
+ { sessionId, workerId, userId, kind, joinedAt },
1270
+ {
1271
+ sessionId: { type: "string", required: true },
1272
+ workerId: { type: "string", required: true },
1273
+ userId: { type: "string", required: true },
1274
+ kind: { type: "string", required: true },
1275
+ joinedAt: { type: "string", required: true },
1276
+ },
1277
+ );
1278
+
1279
+ const result = await internalRequest(
1280
+ this.sdk,
1281
+ `/ai/playbooks/sessions/${sessionId}/participants`,
1282
+ "POST",
1283
+ { body: { workerId, userId, kind, joinedAt } },
1284
+ );
1285
+ return result;
1286
+ }
1287
+
1288
+ this.sdk.validateParams(
1289
+ { sessionId, participantId, leftAt, endReason },
1290
+ {
1291
+ sessionId: { type: "string", required: true },
1292
+ participantId: { type: "string", required: true },
1293
+ leftAt: { type: "string", required: true },
1294
+ endReason: { type: "string", required: false },
1295
+ segmentTotalScore: { type: "number", required: false },
1296
+ segmentAchievedGoals: { type: "number", required: false },
1297
+ segmentTotalGoals: { type: "number", required: false },
1298
+ segmentGoals: { type: "array", required: false },
1299
+ },
1300
+ );
1301
+
1302
+ const result = await internalRequest(
1303
+ this.sdk,
1304
+ `/ai/playbooks/sessions/${sessionId}/participants/${participantId}`,
1305
+ "PUT",
1306
+ {
1307
+ body: {
1308
+ leftAt,
1309
+ endReason,
1310
+ segmentTotalScore,
1311
+ segmentAchievedGoals,
1312
+ segmentTotalGoals,
1313
+ segmentGoals,
1314
+ },
1315
+ },
1316
+ );
1317
+ return result;
1318
+ }
1319
+
1320
+ /**
1321
+ * Join a playbook session participant (§7.2.4 / §7.4). Thin wrapper over
1322
+ * `upsertParticipant` for callers that only ever join, named to match
1323
+ * the API route (`POST /ai/playbooks/sessions/:id/participants`).
1324
+ *
1325
+ * @param {Object} options - Options
1326
+ * @param {string} options.sessionId - The ID of the session
1327
+ * @param {string} options.workerId - The joining worker's ID
1328
+ * @param {string} options.userId - The joining user's ID
1329
+ * @param {string} options.kind - 'human' | 'bot'
1330
+ * @param {string} options.joinedAt - ISO timestamp the participant joined
1331
+ * @returns {Promise<Object>} The created participant row
1332
+ *
1333
+ * @example
1334
+ * await sdk.ai.playbooks.addParticipant({
1335
+ * sessionId: 'pbs_abc123',
1336
+ * workerId: 'worker_456',
1337
+ * userId: 'user_789',
1338
+ * kind: 'human',
1339
+ * joinedAt: new Date().toISOString(),
1340
+ * });
1341
+ */
1342
+ async addParticipant({ sessionId, workerId, userId, kind, joinedAt }) {
1343
+ return this.upsertParticipant({ sessionId, workerId, userId, kind, joinedAt });
1344
+ }
1345
+
1346
+ /**
1347
+ * Close a playbook session participant on leave/transfer/complete
1348
+ * (§7.2.4 / §7.4). Thin wrapper over `upsertParticipant` for callers
1349
+ * that only ever close a slice, named to match the API route
1350
+ * (`PUT /ai/playbooks/sessions/:id/participants/:pid`).
1351
+ *
1352
+ * @param {Object} options - Options
1353
+ * @param {string} options.sessionId - The ID of the session
1354
+ * @param {string} options.participantId - The ID of the participant row to close
1355
+ * @param {string} options.leftAt - ISO timestamp the participant left
1356
+ * @param {string} [options.endReason] - 'transferred' | 'released' | 'unassigned' | 'completed'
1357
+ * @param {number} [options.segmentTotalScore] - Score achieved during this participant's slice
1358
+ * @param {number} [options.segmentAchievedGoals] - Goals achieved during this slice
1359
+ * @param {number} [options.segmentTotalGoals] - Total goals scoped to this slice
1360
+ * @param {Array} [options.segmentGoals] - Per-goal detail for this slice
1361
+ * @returns {Promise<Object>} The updated participant row
1362
+ *
1363
+ * @example
1364
+ * await sdk.ai.playbooks.closeParticipant({
1365
+ * sessionId: 'pbs_abc123',
1366
+ * participantId: 'pbp_456',
1367
+ * leftAt: new Date().toISOString(),
1368
+ * endReason: 'transferred',
1369
+ * segmentTotalScore: 30,
1370
+ * segmentAchievedGoals: 3,
1371
+ * segmentTotalGoals: 5,
1372
+ * });
1373
+ */
1374
+ async closeParticipant({
1375
+ sessionId,
1376
+ participantId,
1377
+ leftAt,
1378
+ endReason,
1379
+ segmentTotalScore,
1380
+ segmentAchievedGoals,
1381
+ segmentTotalGoals,
1382
+ segmentGoals,
1383
+ }) {
1384
+ return this.upsertParticipant({
1385
+ sessionId,
1386
+ participantId,
1387
+ leftAt,
1388
+ endReason,
1389
+ segmentTotalScore,
1390
+ segmentAchievedGoals,
1391
+ segmentTotalGoals,
1392
+ segmentGoals,
1393
+ });
1394
+ }
1395
+
1100
1396
  /**
1101
1397
  * Submit a human QA review for an AI playbook session (replace-semantics).
1102
1398
  *
@@ -1372,6 +1372,40 @@ export class TaskService {
1372
1372
  );
1373
1373
  }
1374
1374
 
1375
+ /**
1376
+ * Get the attributed, cross-channel utterance list for a task (voice, SMS,
1377
+ * webchat, email, workflow), used by the playbook live-scoring engine.
1378
+ * Each row is shaped by `collectUtterances()`: `{ index, channel, role,
1379
+ * text, at, id, speakerUserId, speakerCdrId, participantId, kind }` where
1380
+ * `kind` is `'human' | 'bot' | 'workflow' | 'customer'`.
1381
+ *
1382
+ * @param {string} taskId - The task ID (required)
1383
+ * @param {Object} [options={}] - Query options
1384
+ * @param {string} [options.before] - Cursor (an `at` timestamp) to page
1385
+ * back past the newest-400 window a loader keeps by default.
1386
+ * @returns {Promise<Array>} Utterance rows, oldest first.
1387
+ */
1388
+ async getUtterances(taskId, options = {}) {
1389
+ const { before } = options;
1390
+ this.sdk.validateParams(
1391
+ { taskId, before },
1392
+ {
1393
+ taskId: { type: 'string', required: true },
1394
+ before: { type: 'string', required: false },
1395
+ },
1396
+ );
1397
+
1398
+ const query = {};
1399
+ if (before) query.before = before;
1400
+
1401
+ return await internalRequest(
1402
+ this.sdk,
1403
+ `/taskRouter/tasks/${taskId}/utterances`,
1404
+ 'GET',
1405
+ { query },
1406
+ );
1407
+ }
1408
+
1375
1409
  /**
1376
1410
  * Broadcast a typing indicator to the other participants (owner + joined
1377
1411
  * helpers) on a task's channel. Fire-and-forget signal, not persisted;