@unboundcx/sdk 4.13.139 → 4.13.141

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/index.js CHANGED
@@ -41,6 +41,7 @@ import { RecordTypesService } from './services/recordTypes.js';
41
41
  import { GenerateIdService } from './services/generateId.js';
42
42
  import { EngagementMetricsService } from './services/engagementMetrics.js';
43
43
  import { TaskRouterService } from './services/taskRouter.js';
44
+ import { SkillsService } from './services/skills.js';
44
45
  import { KnowledgeBaseService } from './services/knowledgeBase.js';
45
46
  import { FaxService } from './services/fax.js';
46
47
  import { DocumentsService } from './services/documents.js';
@@ -148,6 +149,7 @@ class UnboundSDK extends BaseSDK {
148
149
  this.generateId = new GenerateIdService(this);
149
150
  this.engagementMetrics = new EngagementMetricsService(this);
150
151
  this.taskRouter = new TaskRouterService(this);
152
+ this.skills = new SkillsService(this);
151
153
  this.text = new TextService(this);
152
154
  this.knowledgeBase = new KnowledgeBaseService(this);
153
155
  this.fax = new FaxService(this);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@unboundcx/sdk",
3
- "version": "4.13.139",
3
+ "version": "4.13.141",
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",
@@ -541,6 +541,27 @@ export class PermissionsService {
541
541
  );
542
542
  }
543
543
 
544
+ /**
545
+ * Account-wide defaults for any settings-catalog key (settingsAccountDefaults
546
+ * table) — a generic tier below systemDefault and above nothing; resolver
547
+ * order is user override -> group -> account default -> systemDefault.
548
+ * @returns {Promise<Object>} { [key]: value }
549
+ */
550
+ async getAccountSettingDefaults() {
551
+ return internalRequest(this.sdk, '/permissions/settings/accountDefaults', 'GET');
552
+ }
553
+
554
+ /** Set one account-wide default for a settings-catalog key. */
555
+ async setAccountSettingDefault(key, value) {
556
+ key = String(key);
557
+ this.sdk.validateParams({ key }, { key: { type: 'string', required: true } });
558
+ return internalRequest(this.sdk,
559
+ `/permissions/settings/accountDefaults/${key}`,
560
+ 'PUT',
561
+ { body: { value } },
562
+ );
563
+ }
564
+
544
565
  /**
545
566
  * Per-user, per-account JSON app state (UI state such as saved tab-sets).
546
567
  * Distinct from settings: free-form JSON, not catalog-validated.
@@ -0,0 +1,207 @@
1
+ import { internalRequest } from '../base.js';
2
+
3
+ // Skill-proficiency tiers (skill-proficiency-tiers-plan.md). Tier-set/sync
4
+ // helpers that don't fit the generic sdk.objects.* shape (userSkills.tier
5
+ // writes do go through sdk.objects.* for single-row create/update; this
6
+ // service is the bulk/group/resync/suggestion surface).
7
+ export class SkillsService {
8
+ constructor(sdk) {
9
+ this.sdk = sdk;
10
+ }
11
+
12
+ /**
13
+ * Set one user's tier on one skill. Requires the user already have the
14
+ * skill assigned (userSkills row must exist) -- this does not assign
15
+ * the skill. Pushes the updated tier to the task-router worker
16
+ * metadata (setSkillTiers) so routing sees it immediately.
17
+ *
18
+ * @param {string} userId
19
+ * @param {string} skillId
20
+ * @param {string} tier - 'expert' | 'proficient' | 'learning'
21
+ * @returns {Promise<Object>} result
22
+ * @returns {number} result.updated - 1 if a matching userSkills row was found, else 0
23
+ *
24
+ * @example
25
+ * await sdk.skills.setUserTier('u123', 'sk456', 'proficient');
26
+ */
27
+ async setUserTier(userId, skillId, tier) {
28
+ this.sdk.validateParams(
29
+ { userId, skillId, tier },
30
+ {
31
+ userId: { type: 'string', required: true },
32
+ skillId: { type: 'string', required: true },
33
+ tier: { type: 'string', required: true },
34
+ },
35
+ );
36
+
37
+ return await internalRequest(this.sdk, '/skills/tiers/set', 'POST', {
38
+ body: { userId, skillId, tier },
39
+ });
40
+ }
41
+
42
+ /**
43
+ * Bulk-set a tier on one skill for a list of users. Only users who
44
+ * already have the skill assigned are affected.
45
+ *
46
+ * @param {object} args
47
+ * @param {string[]} args.userIds
48
+ * @param {string} args.skillId
49
+ * @param {string} args.tier - 'expert' | 'proficient' | 'learning'
50
+ * @returns {Promise<Object>} result
51
+ * @returns {number} result.updated - Count of userSkills rows changed
52
+ *
53
+ * @example
54
+ * const { updated } = await sdk.skills.bulkSetTier({
55
+ * userIds: ['u1', 'u2', 'u3'],
56
+ * skillId: 'sk456',
57
+ * tier: 'expert',
58
+ * });
59
+ */
60
+ async bulkSetTier({ userIds, skillId, tier }) {
61
+ this.sdk.validateParams(
62
+ { userIds, skillId, tier },
63
+ {
64
+ userIds: { type: 'array', required: true },
65
+ skillId: { type: 'string', required: true },
66
+ tier: { type: 'string', required: true },
67
+ },
68
+ );
69
+
70
+ return await internalRequest(
71
+ this.sdk,
72
+ '/skills/tiers/bulkSet',
73
+ 'POST',
74
+ { body: { userIds, skillId, tier } },
75
+ );
76
+ }
77
+
78
+ /**
79
+ * Bulk-set a tier on one skill for every currently-active member of a
80
+ * group/team. Membership (groupMembers.removedAt IS NULL) is resolved
81
+ * server-side at call time, so it can never be stale against the
82
+ * caller's last page load.
83
+ *
84
+ * @param {object} args
85
+ * @param {string} args.groupId
86
+ * @param {string} args.skillId
87
+ * @param {string} args.tier - 'expert' | 'proficient' | 'learning'
88
+ * @returns {Promise<Object>} result
89
+ * @returns {number} result.updated - Count of userSkills rows changed
90
+ *
91
+ * @example
92
+ * await sdk.skills.bulkSetTierForGroup({
93
+ * groupId: 'g789',
94
+ * skillId: 'sk456',
95
+ * tier: 'proficient',
96
+ * });
97
+ */
98
+ async bulkSetTierForGroup({ groupId, skillId, tier }) {
99
+ this.sdk.validateParams(
100
+ { groupId, skillId, tier },
101
+ {
102
+ groupId: { type: 'string', required: true },
103
+ skillId: { type: 'string', required: true },
104
+ tier: { type: 'string', required: true },
105
+ },
106
+ );
107
+
108
+ return await internalRequest(
109
+ this.sdk,
110
+ '/skills/tiers/bulkSetForGroup',
111
+ 'POST',
112
+ { body: { groupId, skillId, tier } },
113
+ );
114
+ }
115
+
116
+ /**
117
+ * Re-push every user-with-a-worker's effective skill tiers to
118
+ * task-router worker metadata for the caller's account. Idempotent:
119
+ * pushes real `userSkills.tier` values when `accounts.useSkillTiers` is
120
+ * on, or `{}` (everyone defaults to Expert) when it's off. Used by the
121
+ * account toggle handler and as a manual "Resync tiers" action.
122
+ *
123
+ * @returns {Promise<Object>} result
124
+ * @returns {number} result.workers - Count of workers resynced
125
+ *
126
+ * @example
127
+ * const { workers } = await sdk.skills.resyncTiers();
128
+ */
129
+ async resyncTiers() {
130
+ return await internalRequest(this.sdk, '/skills/tiers/resync', 'POST', {
131
+ body: {},
132
+ });
133
+ }
134
+
135
+ /**
136
+ * List pending suggested-tier rows for a user (userSkillSuggestions).
137
+ *
138
+ * @param {string} userId
139
+ * @returns {Promise<Object>} result
140
+ * @returns {Object[]} result.suggestions
141
+ *
142
+ * @example
143
+ * const { suggestions } = await sdk.skills.getSuggestions('u123');
144
+ */
145
+ async getSuggestions(userId) {
146
+ this.sdk.validateParams(
147
+ { userId },
148
+ { userId: { type: 'string', required: true } },
149
+ );
150
+
151
+ return await internalRequest(this.sdk, '/skills/suggestions', 'GET', {
152
+ query: { userId },
153
+ });
154
+ }
155
+
156
+ /**
157
+ * Accept a suggested tier: sets userSkills.tier to the suggestion's
158
+ * suggestedTier, pushes the change to the router, and marks the
159
+ * suggestion row accepted.
160
+ *
161
+ * @param {string} id - Suggestion id (userSkillSuggestions.id)
162
+ * @returns {Promise<Object>} result
163
+ * @returns {string} result.id
164
+ * @returns {string} result.tier - The tier now in effect
165
+ * @returns {number} result.updated
166
+ *
167
+ * @example
168
+ * await sdk.skills.acceptSuggestion('sugg123');
169
+ */
170
+ async acceptSuggestion(id) {
171
+ this.sdk.validateParams(
172
+ { id },
173
+ { id: { type: 'string', required: true } },
174
+ );
175
+
176
+ return await internalRequest(
177
+ this.sdk,
178
+ `/skills/suggestions/${id}/accept`,
179
+ 'POST',
180
+ { body: {} },
181
+ );
182
+ }
183
+
184
+ /**
185
+ * Dismiss a suggested tier without changing userSkills.tier.
186
+ *
187
+ * @param {string} id - Suggestion id (userSkillSuggestions.id)
188
+ * @returns {Promise<Object>} result
189
+ * @returns {string} result.id
190
+ *
191
+ * @example
192
+ * await sdk.skills.dismissSuggestion('sugg123');
193
+ */
194
+ async dismissSuggestion(id) {
195
+ this.sdk.validateParams(
196
+ { id },
197
+ { id: { type: 'string', required: true } },
198
+ );
199
+
200
+ return await internalRequest(
201
+ this.sdk,
202
+ `/skills/suggestions/${id}/dismiss`,
203
+ 'POST',
204
+ { body: {} },
205
+ );
206
+ }
207
+ }
@@ -95,4 +95,249 @@ export class QueueService {
95
95
  'GET',
96
96
  );
97
97
  }
98
+
99
+ /**
100
+ * Get a queue's per-channel skill-tier routing steps
101
+ * (skill-proficiency-tiers-plan.md D2/§3.3). Step 0 (Expert only, full
102
+ * requirements) is implicit and never included in the returned list.
103
+ *
104
+ * @param {string} queueId - The queue ID (required)
105
+ * @returns {Promise<Object>} result
106
+ * @returns {string} result.queueId
107
+ * @returns {Object} result.routingSteps - Keyed by channel ('phoneCall'|'chat'|'email'|'sms'),
108
+ * e.g. `{ phoneCall: { steps: [{afterSec, allowedTiers, ignoreOptionalSkills, dropRequiredSkillIds}], learningNeverAutoRoute } }`
109
+ *
110
+ * @example
111
+ * const { routingSteps } = await sdk.taskRouter.queues.getRoutingSteps('queue123');
112
+ */
113
+ async getRoutingSteps(queueId) {
114
+ this.sdk.validateParams(
115
+ { queueId },
116
+ { queueId: { type: 'string', required: true } },
117
+ );
118
+
119
+ return await internalRequest(
120
+ this.sdk,
121
+ `/taskRouter/queues/${queueId}/routingSteps`,
122
+ 'GET',
123
+ );
124
+ }
125
+
126
+ /**
127
+ * Replace a queue's per-channel skill-tier routing steps. `afterSec`
128
+ * must be strictly increasing within each channel's `steps` list; the
129
+ * API validates this and rejects out-of-order steps.
130
+ *
131
+ * @param {string} queueId - The queue ID (required)
132
+ * @param {Object} routingSteps - Keyed by channel ('phoneCall'|'chat'|'email'|'sms')
133
+ * @param {Object[]} routingSteps[channel].steps - `[{afterSec, allowedTiers, ignoreOptionalSkills, dropRequiredSkillIds}]`
134
+ * @param {boolean} [routingSteps[channel].learningNeverAutoRoute] - Coach-only: never auto-route Learning-tier workers on this channel
135
+ * @returns {Promise<Object>} result
136
+ * @returns {string} result.queueId
137
+ * @returns {Object} result.routingSteps - The stored steps, as written (normalized)
138
+ *
139
+ * @example
140
+ * await sdk.taskRouter.queues.setRoutingSteps('queue123', {
141
+ * phoneCall: {
142
+ * steps: [
143
+ * { afterSec: 30, allowedTiers: ['expert', 'proficient'], ignoreOptionalSkills: false, dropRequiredSkillIds: [] },
144
+ * { afterSec: 90, allowedTiers: ['expert', 'proficient', 'learning'], ignoreOptionalSkills: true, dropRequiredSkillIds: [] },
145
+ * ],
146
+ * learningNeverAutoRoute: false,
147
+ * },
148
+ * });
149
+ */
150
+ async setRoutingSteps(queueId, routingSteps) {
151
+ this.sdk.validateParams(
152
+ { queueId, routingSteps },
153
+ {
154
+ queueId: { type: 'string', required: true },
155
+ routingSteps: { type: 'object', required: true },
156
+ },
157
+ );
158
+
159
+ return await internalRequest(
160
+ this.sdk,
161
+ `/taskRouter/queues/${queueId}/routingSteps`,
162
+ 'PUT',
163
+ { body: { routingSteps } },
164
+ );
165
+ }
166
+
167
+ /**
168
+ * List a queue's alert rules (queueAlertRules table). Each rule fires
169
+ * when its trigger metric crosses `threshold` by `comparator` and
170
+ * stays there for `sustainSeconds` (proactive-alerts-plan.md §13/D1-D7).
171
+ *
172
+ * @param {string} queueId - The queue ID (required)
173
+ * @returns {Promise<Object>} result
174
+ * @returns {Object[]} result.alertRules - Rules for the queue
175
+ *
176
+ * @example
177
+ * const { alertRules } = await sdk.taskRouter.queues.alerts.list('queue123');
178
+ */
179
+ async alertsList(queueId) {
180
+ this.sdk.validateParams(
181
+ { queueId },
182
+ { queueId: { type: 'string', required: true } },
183
+ );
184
+
185
+ return await internalRequest(
186
+ this.sdk,
187
+ `/taskRouter/queues/${queueId}/alertRules`,
188
+ 'GET',
189
+ );
190
+ }
191
+
192
+ /**
193
+ * Create a new alert rule on a queue.
194
+ *
195
+ * @param {string} queueId - The queue ID (required)
196
+ * @param {Object} rule - The rule to create
197
+ * @param {string} rule.channel - 'phoneCall' | 'chat' | 'email' | 'sms' | 'fax' | 'other' | 'whatsApp' | 'rcs' | 'all'
198
+ * @param {string} rule.trigger - 'pendingTasks' | 'longestWait' | 'serviceLevel' | 'availableAgents' | 'abandonmentRate' | 'abandonCount' | 'occupancy' | 'overflowMaxWait' | 'overflowNoAgents' | 'overflowCapacity' | 'overflowClosed'
199
+ * @param {string} [rule.comparator] - 'gte' | 'lte' (defaults per trigger: serviceLevel/availableAgents -> lte, else gte)
200
+ * @param {number} rule.threshold
201
+ * @param {number} [rule.hysteresisValue]
202
+ * @param {number} [rule.windowMinutes] - Required 1-60 iff trigger is 'abandonCount'
203
+ * @param {number} [rule.sustainSeconds]
204
+ * @param {number} [rule.cooldownSeconds]
205
+ * @param {number} [rule.dailyCap]
206
+ * @param {string} [rule.scheduleId]
207
+ * @param {boolean} [rule.sendRecovery]
208
+ * @param {number} [rule.escalateAfterSeconds]
209
+ * @param {Object[]} rule.actions - `[{type:'email'|'sms'|'notification', userIds:[], teamIds:[]} | {type:'chat', channelId?, userIds?} | {type:'workflow', workflowId}]`
210
+ * @param {Object[]} [rule.escalateActions] - Same shape as `actions`
211
+ * @param {boolean} [rule.isEnabled]
212
+ * @returns {Promise<Object>} result
213
+ * @returns {Object} result.alertRule - The created rule
214
+ *
215
+ * @example
216
+ * await sdk.taskRouter.queues.alerts.create('queue123', {
217
+ * channel: 'phoneCall',
218
+ * trigger: 'longestWait',
219
+ * threshold: 60,
220
+ * sustainSeconds: 60,
221
+ * actions: [{ type: 'notification', userIds: ['user1'], teamIds: [] }],
222
+ * });
223
+ */
224
+ async alertsCreate(queueId, rule) {
225
+ this.sdk.validateParams(
226
+ { queueId, rule },
227
+ {
228
+ queueId: { type: 'string', required: true },
229
+ rule: { type: 'object', required: true },
230
+ },
231
+ );
232
+
233
+ return await internalRequest(
234
+ this.sdk,
235
+ `/taskRouter/queues/${queueId}/alertRules`,
236
+ 'POST',
237
+ { body: rule },
238
+ );
239
+ }
240
+
241
+ /**
242
+ * Patch an existing alert rule.
243
+ *
244
+ * @param {string} queueId - The queue ID (required)
245
+ * @param {string} ruleId - The alert rule ID (required)
246
+ * @param {Object} patch - Partial fields to update (same shape as `create`'s `rule`)
247
+ * @returns {Promise<Object>} result
248
+ * @returns {Object} result.alertRule - The updated rule
249
+ *
250
+ * @example
251
+ * await sdk.taskRouter.queues.alerts.update('queue123', 'rule1', { threshold: 90 });
252
+ */
253
+ async alertsUpdate(queueId, ruleId, patch) {
254
+ this.sdk.validateParams(
255
+ { queueId, ruleId, patch },
256
+ {
257
+ queueId: { type: 'string', required: true },
258
+ ruleId: { type: 'string', required: true },
259
+ patch: { type: 'object', required: true },
260
+ },
261
+ );
262
+
263
+ return await internalRequest(
264
+ this.sdk,
265
+ `/taskRouter/queues/${queueId}/alertRules/${ruleId}`,
266
+ 'PATCH',
267
+ { body: patch },
268
+ );
269
+ }
270
+
271
+ /**
272
+ * Delete an alert rule.
273
+ *
274
+ * @param {string} queueId - The queue ID (required)
275
+ * @param {string} ruleId - The alert rule ID (required)
276
+ * @returns {Promise<Object>} result
277
+ *
278
+ * @example
279
+ * await sdk.taskRouter.queues.alerts.remove('queue123', 'rule1');
280
+ */
281
+ async alertsRemove(queueId, ruleId) {
282
+ this.sdk.validateParams(
283
+ { queueId, ruleId },
284
+ {
285
+ queueId: { type: 'string', required: true },
286
+ ruleId: { type: 'string', required: true },
287
+ },
288
+ );
289
+
290
+ return await internalRequest(
291
+ this.sdk,
292
+ `/taskRouter/queues/${queueId}/alertRules/${ruleId}`,
293
+ 'DELETE',
294
+ );
295
+ }
296
+
297
+ /**
298
+ * List a queue's alert event history (queueAlertEvents table): fired,
299
+ * escalated, cleared, and suppressed events.
300
+ *
301
+ * @param {string} queueId - The queue ID (required)
302
+ * @param {Object} [options]
303
+ * @param {number} [options.limit] - Max rows to return (default 50)
304
+ * @param {string} [options.before] - ISO timestamp cursor; only events before this time
305
+ * @returns {Promise<Object>} result
306
+ * @returns {Object[]} result.alertEvents
307
+ *
308
+ * @example
309
+ * const { alertEvents } = await sdk.taskRouter.queues.alerts.history('queue123', { limit: 20 });
310
+ */
311
+ async alertsHistory(queueId, { limit, before } = {}) {
312
+ this.sdk.validateParams(
313
+ { queueId },
314
+ { queueId: { type: 'string', required: true } },
315
+ );
316
+
317
+ const query = {};
318
+ if (limit !== undefined) query.limit = limit;
319
+ if (before !== undefined) query.before = before;
320
+
321
+ return await internalRequest(
322
+ this.sdk,
323
+ `/taskRouter/queues/${queueId}/alertEvents`,
324
+ 'GET',
325
+ { query },
326
+ );
327
+ }
98
328
  }
329
+
330
+ // Exposes alert-rule methods as `sdk.taskRouter.queues.alerts.*` while
331
+ // keeping them implemented as plain methods on QueueService above (so they
332
+ // share `this.sdk`/validateParams without a second internalRequest wiring).
333
+ Object.defineProperty(QueueService.prototype, 'alerts', {
334
+ get() {
335
+ return {
336
+ list: (queueId) => this.alertsList(queueId),
337
+ create: (queueId, rule) => this.alertsCreate(queueId, rule),
338
+ update: (queueId, ruleId, patch) => this.alertsUpdate(queueId, ruleId, patch),
339
+ remove: (queueId, ruleId) => this.alertsRemove(queueId, ruleId),
340
+ history: (queueId, options) => this.alertsHistory(queueId, options),
341
+ };
342
+ },
343
+ });