@unboundcx/sdk 4.13.138 → 4.13.140

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.
@@ -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,72 @@ 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
+ }
98
166
  }