@unboundcx/sdk 4.13.146-security.4 → 4.13.146

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.146-security.4",
3
+ "version": "4.13.146",
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",
@@ -77,6 +77,17 @@ export class EmergencyService {
77
77
  });
78
78
  }
79
79
 
80
+ // A1b #12 (per-report-detail.md #12): account-wide compliance log, same
81
+ // admin:emergencylocation:manage scope as every other admin route here --
82
+ // no new scope. query: { from, to } ISO, exclusive-end (same contract as
83
+ // reporting.getCallLog), optional digits ('911'|'933') (r1 fix: was a
84
+ // fixed `range` enum that couldn't express ReportShell's picker).
85
+ async report(query = {}) {
86
+ return await internalRequest(this.sdk, '/emergency/calls', 'GET', {
87
+ query,
88
+ });
89
+ }
90
+
80
91
  async deleteSite(id) {
81
92
  this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
82
93
  return await internalRequest(this.sdk, `/emergency/sites/${id}`, 'DELETE', {});
@@ -216,11 +216,18 @@ export class JourneysService {
216
216
  /**
217
217
  * Per-step funnel (journeys-plan.md §9, P6): entered / outcome split /
218
218
  * conversions from journeyMemberEvents. Test members are excluded.
219
+ * **r3 fix (analytics-expansion-plan.md §4.7):** `from`/`to` are now
220
+ * forwarded as query params -- previously this method always sent `{}`,
221
+ * so the shared report-shell's date-range controls had no effect on this
222
+ * screen even once the API side accepted the params.
219
223
  *
220
224
  * @param {string} journeyId
225
+ * @param {Object} [opts]
226
+ * @param {string} [opts.from] ISO date-time
227
+ * @param {string} [opts.to] ISO date-time
221
228
  * @returns {Promise<Object>} { steps: [{ stepKey, type, title, entered, outcomes, conversions }] }
222
229
  */
223
- async funnel(journeyId) {
230
+ async funnel(journeyId, opts = {}) {
224
231
  this.sdk.validateParams(
225
232
  { journeyId },
226
233
  { journeyId: { type: 'string', required: true } },
@@ -229,7 +236,7 @@ export class JourneysService {
229
236
  this.sdk,
230
237
  `/journeys/${journeyId}/funnel`,
231
238
  'GET',
232
- {},
239
+ { query: pickDefined(opts) },
233
240
  );
234
241
  }
235
242
 
@@ -1,5 +1,14 @@
1
1
  import { internalRequest } from '../base.js';
2
2
  import { ReportingAgentsService } from './reportingAgents.js';
3
+ import { ReportingCallLogService } from './reportingCallLog.js';
4
+ import { ReportingMissedCallsService } from './reportingMissedCalls.js';
5
+ import { ReportingNumberHealthService } from './reportingNumberHealth.js';
6
+ import { ReportingBotContainmentService } from './reportingBotContainment.js';
7
+ import { ReportingCallQualityService } from './reportingCallQuality.js';
8
+ import { ReportingAiAdoptionService } from './reportingAiAdoption.js';
9
+ import { ReportingRingGroupsService } from './reportingRingGroups.js';
10
+ import { ReportingIvrMenusService } from './reportingIvrMenus.js';
11
+ import { ReportingConversationInsightsService } from './reportingConversationInsights.js';
3
12
 
4
13
  // Q2: same queryString helper as reportingAgents.js (kept local -- no
5
14
  // shared util module between the two files today).
@@ -35,6 +44,43 @@ export class ReportingService {
35
44
  // registry above -- /reporting/agents/*. Split into its own file/class
36
45
  // (house 400-line limit) since this file was already at 215 lines.
37
46
  this.agents = new ReportingAgentsService(sdk);
47
+ // #14 analytics-expansion A0b: account-wide CDR browse -- own file/class
48
+ // (same reason as .agents above).
49
+ this.callLog = new ReportingCallLogService(sdk);
50
+ // A1b #11 (per-report-detail.md #11): dedicated endpoint, NOT a generic
51
+ // metric -- kept as a small namespace (not its own file) since it's one
52
+ // method.
53
+ this.licenses = {
54
+ utilization: (...args) => this.seatUtilization(...args),
55
+ };
56
+ // #3 analytics-expansion A1a (§4.9): missed-call -> callback funnel --
57
+ // own file/class (same reason as .agents above).
58
+ this.missedCalls = new ReportingMissedCallsService(sdk);
59
+ // analytics-expansion A1a (§4.6): number/10DLC connect-rate health --
60
+ // own file/class (same reason as .agents above).
61
+ this.numberHealth = new ReportingNumberHealthService(sdk);
62
+ // analytics-expansion D14/§4.13 (r17-r22): bot containment dedicated
63
+ // endpoint -- own file/class (same reason as .agents above).
64
+ this.botContainment = new ReportingBotContainmentService(sdk);
65
+ // #2 analytics-expansion B0 (§4.1): voice MOS/jitter/loss -- own
66
+ // file/class (same reason as .agents above).
67
+ this.callQuality = new ReportingCallQualityService(sdk);
68
+ // Work Package E analytics-expansion (§4.12): customer-facing AI
69
+ // feature adoption summarization -- own file/class (same reason as
70
+ // .agents above).
71
+ this.aiAdoption = new ReportingAiAdoptionService(sdk);
72
+ // #1a analytics-expansion A2 (per-report-detail.md #1a): ring group
73
+ // volume/answered/handle + per-member offers -- own file/class (same
74
+ // reason as .agents above).
75
+ this.ringGroups = new ReportingRingGroupsService(sdk);
76
+ // #1b analytics-expansion A2 (per-report-detail.md #1b): account-wide
77
+ // IVR/voice-workflow-menu analytics -- own file/class (same reason as
78
+ // .agents above).
79
+ this.ivrMenus = new ReportingIvrMenusService(sdk);
80
+ // #13 analytics-expansion B1 (per-report-detail.md #13, atlas §C.2):
81
+ // tracked phrases + talk ratio, admin tracker/topic CRUD -- own
82
+ // file/class (same reason as .agents above).
83
+ this.conversationInsights = new ReportingConversationInsightsService(sdk);
38
84
  }
39
85
 
40
86
  /**
@@ -152,6 +198,23 @@ export class ReportingService {
152
198
  );
153
199
  }
154
200
 
201
+ /**
202
+ * A1b #11: idle-seat snapshot (userLicenses joined to last-activity
203
+ * signals) -- gated on the EXISTING admin:license:manage scope, no new
204
+ * scope (security.md §B.1).
205
+ * @param {Object} params - { licenseTypeCode? }
206
+ * @returns {Promise<Object>} { generatedAt, licenseTypes: [{code,label,audience,seatCount,used,needsSeat}], seats: [{userId,userName,isRemoved,licenseTypeCode,licenseLabel,source,assignedAt,lastActiveAt,idleDays,seatCostEstimate}] }
207
+ * @example
208
+ * await sdk.reporting.licenses.utilization({ licenseTypeCode: 'license.support' });
209
+ */
210
+ async seatUtilization({ licenseTypeCode } = {}) {
211
+ return internalRequest(
212
+ this.sdk,
213
+ `/reporting/seatUtilization${queryString({ licenseTypeCode })}`,
214
+ 'GET',
215
+ );
216
+ }
217
+
155
218
  /**
156
219
  * Rollup health: last computed bucket, lag, missing buckets.
157
220
  * @returns {Promise<Object>}
@@ -198,4 +198,96 @@ export class ReportingAgentsService {
198
198
  'GET',
199
199
  );
200
200
  }
201
+
202
+ /**
203
+ * analytics-expansion Phase D: QA/coaching rollup-grain scorecard, one
204
+ * row per agent (or queue/team) across the whole team in range --
205
+ * unlike qualityTrend/topTasks, no single userId is required.
206
+ * @param {Object} params - { from, to, userIds, queueIds, teamIds, groupBy, agentKind }
207
+ * @returns {Promise<Object>} { columns, rows, definitions, meta }
208
+ * @example
209
+ * await sdk.reporting.agents.qualityScorecards({ from, to, groupBy: 'agent' });
210
+ */
211
+ async qualityScorecards({ from, to, userIds, queueIds, teamIds, groupBy, agentKind } = {}) {
212
+ this.sdk.validateParams(
213
+ { from, to },
214
+ { from: { type: 'string', required: true }, to: { type: 'string', required: true } },
215
+ );
216
+ return internalRequest(
217
+ this.sdk,
218
+ `/reporting/agents/qualityScorecards${queryString({ from, to, userIds, queueIds, teamIds, groupBy, agentKind })}`,
219
+ 'GET',
220
+ );
221
+ }
222
+
223
+ /**
224
+ * analytics-expansion Phase D: coaching-suggestion panel rows for one
225
+ * agent -- not-achieved/missed goals in range, each with a
226
+ * `coachingSuggestion` (nullable until generated). userId 'me' resolves
227
+ * to the caller.
228
+ * @param {string} userId
229
+ * @param {Object} params - { from, to, limit }
230
+ * @returns {Promise<Object>} { rows }
231
+ * @example
232
+ * await sdk.reporting.agents.coachingSuggestions('me', { from, to });
233
+ */
234
+ async coachingSuggestions(userId, { from, to, limit } = {}) {
235
+ userId = String(userId);
236
+ this.sdk.validateParams(
237
+ { userId, from, to },
238
+ {
239
+ userId: { type: 'string', required: true },
240
+ from: { type: 'string', required: true },
241
+ to: { type: 'string', required: true },
242
+ },
243
+ );
244
+ return internalRequest(
245
+ this.sdk,
246
+ `/reporting/agents/${userId}/coachingSuggestions${queryString({ from, to, limit })}`,
247
+ 'GET',
248
+ );
249
+ }
250
+
251
+ /**
252
+ * analytics-expansion Phase D fix: per-goal pass-rate rubric breakdown,
253
+ * aggregated across the current filter set (agent-role goals only) --
254
+ * same multi-agent shape as qualityScorecards, no single userId required.
255
+ * @param {Object} params - { from, to, userIds, queueIds, teamIds, agentKind }
256
+ * @returns {Promise<Object>} { rows: [{ playbookGoalId, goalName, achievedCount, totalCount, passRate }] }
257
+ * @example
258
+ * await sdk.reporting.agents.qualityRubricBreakdown({ from, to });
259
+ */
260
+ async qualityRubricBreakdown({ from, to, userIds, queueIds, teamIds, agentKind } = {}) {
261
+ this.sdk.validateParams(
262
+ { from, to },
263
+ { from: { type: 'string', required: true }, to: { type: 'string', required: true } },
264
+ );
265
+ return internalRequest(
266
+ this.sdk,
267
+ `/reporting/agents/qualityRubricBreakdown${queryString({ from, to, userIds, queueIds, teamIds, agentKind })}`,
268
+ 'GET',
269
+ );
270
+ }
271
+
272
+ /**
273
+ * analytics-expansion Phase D fix: AI+human score trend (two series,
274
+ * never averaged) aggregated across the current filter set -- unlike
275
+ * qualityTrend, no single userId is required, for the report-level
276
+ * trend chart alongside the team/queue-wide scorecard.
277
+ * @param {Object} params - { from, to, grain, userIds, queueIds, teamIds, agentKind }
278
+ * @returns {Promise<Object>} { columns, rows, definitions, meta }
279
+ * @example
280
+ * await sdk.reporting.agents.qualityTrendRollup({ from, to, grain: 'day' });
281
+ */
282
+ async qualityTrendRollup({ from, to, grain, userIds, queueIds, teamIds, agentKind } = {}) {
283
+ this.sdk.validateParams(
284
+ { from, to },
285
+ { from: { type: 'string', required: true }, to: { type: 'string', required: true } },
286
+ );
287
+ return internalRequest(
288
+ this.sdk,
289
+ `/reporting/agents/qualityTrendRollup${queryString({ from, to, grain, userIds, queueIds, teamIds, agentKind })}`,
290
+ 'GET',
291
+ );
292
+ }
201
293
  }
@@ -0,0 +1,49 @@
1
+ import { internalRequest } from '../base.js';
2
+
3
+ // Q2-style local helper (same as reporting.js/reportingCallQuality.js --
4
+ // no shared util module between these files today).
5
+ function queryString(params = {}) {
6
+ const parts = [];
7
+ for (const [key, value] of Object.entries(params)) {
8
+ if (value === undefined || value === null || value === '') continue;
9
+ const v = Array.isArray(value) ? value.join(',') : value;
10
+ parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
11
+ }
12
+ return parts.length ? `?${parts.join('&')}` : '';
13
+ }
14
+
15
+ // Work Package E analytics-expansion (plan §4.12, security.md "AI
16
+ // feature adoption" row): customer-facing AI usage summarization. Own
17
+ // file (not reporting.js) same as ReportingCallQualityService -- keeps
18
+ // reporting.js under the repo's 400-line limit. Scope:
19
+ // reporting:aiAdoption:read, family task_router. Account-scoped counts
20
+ // only -- the response never carries cost/pricing, provider, or model.
21
+ export class ReportingAiAdoptionService {
22
+ constructor(sdk) {
23
+ this.sdk = sdk;
24
+ }
25
+
26
+ /**
27
+ * @param {Object} params - { from, to } -- 'YYYY-MM-DD', inclusive,
28
+ * 92 days max.
29
+ * @returns {Promise<Object>} { totals: { turns, requests, anyBotUsage },
30
+ * trend: [{ date, turns, requests }],
31
+ * byFeature: [{ category, feature, turns, requests, distinctUsers }] }
32
+ * @example
33
+ * await sdk.reporting.aiAdoption.summary({ from, to });
34
+ */
35
+ async summary({ from, to } = {}) {
36
+ this.sdk.validateParams(
37
+ { from, to },
38
+ {
39
+ from: { type: 'string', required: true },
40
+ to: { type: 'string', required: true },
41
+ },
42
+ );
43
+ return internalRequest(
44
+ this.sdk,
45
+ `/reporting/aiAdoption${queryString({ from, to })}`,
46
+ 'GET',
47
+ );
48
+ }
49
+ }
@@ -0,0 +1,55 @@
1
+ import { internalRequest } from '../base.js';
2
+
3
+ // Q2-style local helper (same as reporting.js/reportingMissedCalls.js -- no
4
+ // shared util module between these files today).
5
+ function queryString(params = {}) {
6
+ const parts = [];
7
+ for (const [key, value] of Object.entries(params)) {
8
+ if (value === undefined || value === null || value === '') continue;
9
+ const v = Array.isArray(value) ? value.join(',') : value;
10
+ parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
11
+ }
12
+ return parts.length ? `?${parts.join('&')}` : '';
13
+ }
14
+
15
+ // analytics-expansion D14/§4.13 (r17-r22 dedicated-endpoint design): bot
16
+ // containment. Own file (not reporting.js) same as ReportingMissedCallsService
17
+ // -- keeps reporting.js under the repo's 400-line limit.
18
+ export class ReportingBotContainmentService {
19
+ constructor(sdk) {
20
+ this.sdk = sdk;
21
+ }
22
+
23
+ /**
24
+ * @param {Object} params
25
+ * @param {string} params.from - inclusive ISO start.
26
+ * @param {string} params.to - EXCLUSIVE ISO end.
27
+ * @param {'queue'|'agent'} [params.groupBy='queue']
28
+ * @param {string[]} [params.queueIds] - request-level filter (independent
29
+ * of the caller's own visibility scope).
30
+ * @param {string[]} [params.userIds] - request-level filter, same shape.
31
+ * @returns {Promise<Object>} { groupBy, rows: [{ queueId|userId,
32
+ * botContained, botEscalatedHuman, botCallerAbandoned, botFailed,
33
+ * containmentRate }] } -- containmentRate is null (not 0) when a row's
34
+ * four counts are all 0.
35
+ * @example
36
+ * await sdk.reporting.botContainment.summary({ from, to, groupBy: 'agent' });
37
+ */
38
+ async summary({ from, to, groupBy, queueIds, userIds } = {}) {
39
+ this.sdk.validateParams(
40
+ { from, to, groupBy, queueIds, userIds },
41
+ {
42
+ from: { type: 'string', required: true },
43
+ to: { type: 'string', required: true },
44
+ groupBy: { type: 'string', required: false },
45
+ queueIds: { type: 'array', required: false },
46
+ userIds: { type: 'array', required: false },
47
+ },
48
+ );
49
+ return internalRequest(
50
+ this.sdk,
51
+ `/reporting/botContainment${queryString({ from, to, groupBy, queueIds, userIds })}`,
52
+ 'GET',
53
+ );
54
+ }
55
+ }
@@ -0,0 +1,114 @@
1
+ import { internalRequest } from '../base.js';
2
+
3
+ // Q2-style local helper (same as reporting.js/reportingAgents.js -- no
4
+ // shared util module between these files today).
5
+ function queryString(params = {}) {
6
+ const parts = [];
7
+ for (const [key, value] of Object.entries(params)) {
8
+ if (value === undefined || value === null || value === '') continue;
9
+ const v = Array.isArray(value) ? value.join(',') : value;
10
+ parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
11
+ }
12
+ return parts.length ? `?${parts.join('&')}` : '';
13
+ }
14
+
15
+ // #14 analytics-expansion A0b: account-wide CDR browse. Own file (not
16
+ // reporting.js) same as ReportingAgentsService -- keeps reporting.js under
17
+ // the repo's 400-line limit.
18
+ export class ReportingCallLogService {
19
+ constructor(sdk) {
20
+ this.sdk = sdk;
21
+ }
22
+
23
+ /**
24
+ * @param {Object} params - { from, to, direction?: 'inbound'|'outbound',
25
+ * answered?: boolean, queueIds?: string[], ringGroupIds?: string[],
26
+ * userIds?: string[], phoneNumber?: string, recordingOnly?: boolean,
27
+ * cursor?: string, limit?: number }
28
+ * @returns {Promise<Object>} { rows, cursor, hasMore, summary: { totalCalls, answeredCalls, missedCalls, answeredPct, avgBillDurationSec } }
29
+ * @example
30
+ * await sdk.reporting.callLog.list({ from, to, direction: 'inbound' });
31
+ */
32
+ async list({
33
+ from,
34
+ to,
35
+ direction,
36
+ answered,
37
+ queueIds,
38
+ ringGroupIds,
39
+ userIds,
40
+ phoneNumber,
41
+ recordingOnly,
42
+ cursor,
43
+ limit,
44
+ } = {}) {
45
+ this.sdk.validateParams(
46
+ { from, to },
47
+ {
48
+ from: { type: 'string', required: true },
49
+ to: { type: 'string', required: true },
50
+ },
51
+ );
52
+ return internalRequest(
53
+ this.sdk,
54
+ `/reporting/callLog${queryString({
55
+ from,
56
+ to,
57
+ direction,
58
+ answered,
59
+ queueIds,
60
+ ringGroupIds,
61
+ userIds,
62
+ phoneNumber,
63
+ recordingOnly,
64
+ cursor,
65
+ limit,
66
+ })}`,
67
+ 'GET',
68
+ );
69
+ }
70
+
71
+ /**
72
+ * Same filters as list(), streams a CSV (forces HTTP transport).
73
+ * @param {Object} params - same shape as list()
74
+ * @returns {Promise<Object>} raw CSV response (transport-dependent)
75
+ * @example
76
+ * await sdk.reporting.callLog.export({ from, to });
77
+ */
78
+ async export({
79
+ from,
80
+ to,
81
+ direction,
82
+ answered,
83
+ queueIds,
84
+ ringGroupIds,
85
+ userIds,
86
+ phoneNumber,
87
+ recordingOnly,
88
+ } = {}) {
89
+ this.sdk.validateParams(
90
+ { from, to },
91
+ {
92
+ from: { type: 'string', required: true },
93
+ to: { type: 'string', required: true },
94
+ },
95
+ );
96
+ return internalRequest(
97
+ this.sdk,
98
+ `/reporting/callLog${queryString({
99
+ from,
100
+ to,
101
+ direction,
102
+ answered,
103
+ queueIds,
104
+ ringGroupIds,
105
+ userIds,
106
+ phoneNumber,
107
+ recordingOnly,
108
+ format: 'csv',
109
+ })}`,
110
+ 'GET',
111
+ { httpOnly: true },
112
+ );
113
+ }
114
+ }
@@ -0,0 +1,47 @@
1
+ import { internalRequest } from '../base.js';
2
+
3
+ // Q2-style local helper (same as reporting.js/reportingMissedCalls.js --
4
+ // no shared util module between these files today).
5
+ function queryString(params = {}) {
6
+ const parts = [];
7
+ for (const [key, value] of Object.entries(params)) {
8
+ if (value === undefined || value === null || value === '') continue;
9
+ const v = Array.isArray(value) ? value.join(',') : value;
10
+ parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
11
+ }
12
+ return parts.length ? `?${parts.join('&')}` : '';
13
+ }
14
+
15
+ // #2 analytics-expansion B0 (plan §4.1, voice-quality.md): voice MOS /
16
+ // jitter / loss. Own file (not reporting.js) same as
17
+ // ReportingMissedCallsService -- keeps reporting.js under the repo's
18
+ // 400-line limit. Scope: reporting:callQuality:read, family task_router.
19
+ export class ReportingCallQualityService {
20
+ constructor(sdk) {
21
+ this.sdk = sdk;
22
+ }
23
+
24
+ /**
25
+ * @param {Object} params - { from, to }
26
+ * @returns {Promise<Object>} { totalCalls, measuredCalls, avgMos,
27
+ * pctBelowThreshold, lowMosThreshold, worstCalls: [{ callId, cdrId,
28
+ * legSide, avgMos, avgJitterMs, avgRttMs, packetLossPct, codec,
29
+ * queueId, startTime }], trend: [{ date, avgMos }] }
30
+ * @example
31
+ * await sdk.reporting.callQuality.summary({ from, to });
32
+ */
33
+ async summary({ from, to } = {}) {
34
+ this.sdk.validateParams(
35
+ { from, to },
36
+ {
37
+ from: { type: 'string', required: true },
38
+ to: { type: 'string', required: true },
39
+ },
40
+ );
41
+ return internalRequest(
42
+ this.sdk,
43
+ `/reporting/callQuality${queryString({ from, to })}`,
44
+ 'GET',
45
+ );
46
+ }
47
+ }
@@ -0,0 +1,203 @@
1
+ import { internalRequest } from '../base.js';
2
+
3
+ // Q2-style local helper (same as reporting.js/reportingCallQuality.js -- no
4
+ // shared util module between these files today).
5
+ function queryString(params = {}) {
6
+ const parts = [];
7
+ for (const [key, value] of Object.entries(params)) {
8
+ if (value === undefined || value === null || value === '') continue;
9
+ const v = Array.isArray(value) ? value.join(',') : value;
10
+ parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
11
+ }
12
+ return parts.length ? `?${parts.join('&')}` : '';
13
+ }
14
+
15
+ // #13 analytics-expansion B1 (per-report-detail.md #13, atlas §C.2): tracked
16
+ // phrases + talk ratio, one endpoint gated by `view`. Own file (not
17
+ // reporting.js) same as ReportingCallQualityService -- keeps reporting.js
18
+ // under the repo's 400-line limit. Scope: reporting:conversationInsights:read
19
+ // (summary) / admin:conversationInsights:manage (tracker + topic CRUD),
20
+ // family task_router. Report-card visibility is gated client-side on the
21
+ // `managerOnly` flag, NOT on the read scope alone (every Standard User has
22
+ // it by default) -- see reportsNav.js.
23
+ export class ReportingConversationInsightsService {
24
+ constructor(sdk) {
25
+ this.sdk = sdk;
26
+ this.trackers = {
27
+ list: () => this._listTrackers(),
28
+ create: (params) => this._createTracker(params),
29
+ update: (id, params) => this._updateTracker(id, params),
30
+ remove: (id) => this._removeTracker(id),
31
+ };
32
+ this.topics = {
33
+ list: () => this._listTopics(),
34
+ create: (params) => this._createTopic(params),
35
+ };
36
+ }
37
+
38
+ /**
39
+ * @param {Object} params - { from, to, view?, groupBy?, queueIds?, userIds? }
40
+ * view: 'phrases' (default) | 'talkRatio'; groupBy ('queue'|'agent',
41
+ * default 'queue') only applies to view='talkRatio'. For the phrase
42
+ * detail "matching calls" click-through, use `.hits()` below instead.
43
+ * @returns {Promise<Object>} view='phrases': { view, phrases: [{
44
+ * trackerId, phraseText, topicId, agentHits, customerHits, otherHits,
45
+ * totalHits, trend: [{ bucketStart, hits }] }] } (sorted by totalHits
46
+ * desc). view='talkRatio': { view, groupBy, rows: [{ queueId?, userId?,
47
+ * coverageTotal, coverageWithTranscript, talkRatioAgent, talkRatioCustomer,
48
+ * monologueMaxSec, questionCount }] }
49
+ * @example
50
+ * await sdk.reporting.conversationInsights.summary({ from, to, view: 'talkRatio', groupBy: 'agent' });
51
+ */
52
+ async summary({ from, to, view, groupBy, queueIds, userIds } = {}) {
53
+ this.sdk.validateParams(
54
+ { from, to },
55
+ {
56
+ from: { type: 'string', required: true },
57
+ to: { type: 'string', required: true },
58
+ },
59
+ );
60
+ return internalRequest(
61
+ this.sdk,
62
+ `/reporting/conversationInsights${queryString({
63
+ from,
64
+ to,
65
+ view,
66
+ groupBy,
67
+ queueIds,
68
+ userIds,
69
+ })}`,
70
+ 'GET',
71
+ );
72
+ }
73
+
74
+ /**
75
+ * Individual phrase-hit rows for one tracker -- PhraseDetailPanel's
76
+ * "matching calls" transcript click-through (plan §7 B1 / atlas-
77
+ * additions.md §C.2): each hit carries the taskId/occurredAt/
78
+ * transcriptionMessageId/snippet a transcript-viewer deep link needs to
79
+ * seek to the moment, instead of only the 15-min rollup `.summary()`
80
+ * returns.
81
+ * @param {Object} params - { trackerId (required), from (required),
82
+ * to (required), queueIds?, userIds?, limit? (default 50, max 200) }
83
+ * @returns {Promise<Object>} { view: 'hits', trackerId, hits: [{
84
+ * taskId, queueId, userId, speakerSide, occurredAt,
85
+ * transcriptionMessageId, snippet }] } (newest first)
86
+ * @example
87
+ * await sdk.reporting.conversationInsights.hits({ trackerId, from, to });
88
+ */
89
+ async hits({ trackerId, from, to, queueIds, userIds, limit } = {}) {
90
+ this.sdk.validateParams(
91
+ { trackerId, from, to },
92
+ {
93
+ trackerId: { type: 'string', required: true },
94
+ from: { type: 'string', required: true },
95
+ to: { type: 'string', required: true },
96
+ },
97
+ );
98
+ return internalRequest(
99
+ this.sdk,
100
+ `/reporting/conversationInsights${queryString({
101
+ from,
102
+ to,
103
+ view: 'hits',
104
+ trackerId,
105
+ queueIds,
106
+ userIds,
107
+ limit,
108
+ })}`,
109
+ 'GET',
110
+ );
111
+ }
112
+
113
+ /** Admin CRUD (Contact Center Admin only): tracked phrases.
114
+ * @returns {Promise<Object>} { trackers: [{ id, phraseText, isRegex,
115
+ * topicId, isActive, isDeleted, createdAt, createdBy, updatedAt,
116
+ * updatedBy }] }
117
+ * @example await sdk.reporting.conversationInsights.trackers.list();
118
+ */
119
+ async _listTrackers() {
120
+ return internalRequest(
121
+ this.sdk,
122
+ '/reporting/conversationInsights/trackers',
123
+ 'GET',
124
+ );
125
+ }
126
+
127
+ /**
128
+ * @param {Object} params - { phraseText (required), isRegex?, topicId?, isActive? }
129
+ * @returns {Promise<Object>} { tracker }
130
+ * @example
131
+ * await sdk.reporting.conversationInsights.trackers.create({ phraseText: 'cancel my subscription' });
132
+ */
133
+ async _createTracker({ phraseText, isRegex, topicId, isActive } = {}) {
134
+ this.sdk.validateParams(
135
+ { phraseText },
136
+ { phraseText: { type: 'string', required: true } },
137
+ );
138
+ return internalRequest(
139
+ this.sdk,
140
+ '/reporting/conversationInsights/trackers',
141
+ 'POST',
142
+ { phraseText, isRegex, topicId, isActive },
143
+ );
144
+ }
145
+
146
+ /**
147
+ * @param {string} id
148
+ * @param {Object} params - partial, any of { phraseText, isRegex, topicId, isActive }
149
+ * @returns {Promise<Object>} { tracker }
150
+ * @example
151
+ * await sdk.reporting.conversationInsights.trackers.update(id, { isActive: false });
152
+ */
153
+ async _updateTracker(id, params = {}) {
154
+ this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
155
+ return internalRequest(
156
+ this.sdk,
157
+ `/reporting/conversationInsights/trackers/${encodeURIComponent(id)}`,
158
+ 'PUT',
159
+ params,
160
+ );
161
+ }
162
+
163
+ /**
164
+ * Soft delete -- isDeleted:1, isActive:0; historical hit rows untouched.
165
+ * @param {string} id
166
+ * @returns {Promise<Object>} { message }
167
+ * @example await sdk.reporting.conversationInsights.trackers.remove(id);
168
+ */
169
+ async _removeTracker(id) {
170
+ this.sdk.validateParams({ id }, { id: { type: 'string', required: true } });
171
+ return internalRequest(
172
+ this.sdk,
173
+ `/reporting/conversationInsights/trackers/${encodeURIComponent(id)}`,
174
+ 'DELETE',
175
+ );
176
+ }
177
+
178
+ /** @returns {Promise<Object>} { topics: [{ id, name, isActive, isDeleted, createdAt, ... }] }
179
+ * @example await sdk.reporting.conversationInsights.topics.list();
180
+ */
181
+ async _listTopics() {
182
+ return internalRequest(
183
+ this.sdk,
184
+ '/reporting/conversationInsights/topics',
185
+ 'GET',
186
+ );
187
+ }
188
+
189
+ /**
190
+ * @param {Object} params - { name (required) }
191
+ * @returns {Promise<Object>} { topic }
192
+ * @example await sdk.reporting.conversationInsights.topics.create({ name: 'Pricing' });
193
+ */
194
+ async _createTopic({ name } = {}) {
195
+ this.sdk.validateParams({ name }, { name: { type: 'string', required: true } });
196
+ return internalRequest(
197
+ this.sdk,
198
+ '/reporting/conversationInsights/topics',
199
+ 'POST',
200
+ { name },
201
+ );
202
+ }
203
+ }
@@ -0,0 +1,97 @@
1
+ import { internalRequest } from '../base.js';
2
+
3
+ // Q2-style local helper (same as reporting.js/reportingMissedCalls.js --
4
+ // no shared util module between these files today).
5
+ function queryString(params = {}) {
6
+ const parts = [];
7
+ for (const [key, value] of Object.entries(params)) {
8
+ if (value === undefined || value === null || value === '') continue;
9
+ const v = Array.isArray(value) ? value.join(',') : value;
10
+ parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
11
+ }
12
+ return parts.length ? `?${parts.join('&')}` : '';
13
+ }
14
+
15
+ // #1b analytics-expansion A2 (per-report-detail.md #1b): account-wide IVR /
16
+ // voice-workflow-menu analytics (containment/handoff/abandon) + per-session
17
+ // step drill. Own file (same reason as ReportingMissedCallsService). Scope:
18
+ // workflows:workflow:read, family workflows_triggers, capability
19
+ // capability.workflows.
20
+ export class ReportingIvrMenusService {
21
+ constructor(sdk) {
22
+ this.sdk = sdk;
23
+ }
24
+
25
+ /**
26
+ * Account-wide voice-menu workflow summary.
27
+ * @param {Object} params - { from, to }
28
+ * @returns {Promise<Object>} { ivrMenus: [{ workflowId, workflowName,
29
+ * uniqueSessions, containedCount, handoffCount, abandonCount,
30
+ * containmentRate, handoffRate, abandonRate, avgAttempts,
31
+ * endReasonBreakdown: { <endReason>: count } }] }
32
+ * @example
33
+ * await sdk.reporting.ivrMenus.summary({ from, to });
34
+ */
35
+ async summary({ from, to } = {}) {
36
+ this.sdk.validateParams(
37
+ { from, to },
38
+ {
39
+ from: { type: 'string', required: true },
40
+ to: { type: 'string', required: true },
41
+ },
42
+ );
43
+ return internalRequest(
44
+ this.sdk,
45
+ `/reporting/ivrMenus${queryString({ from, to })}`,
46
+ 'GET',
47
+ );
48
+ }
49
+
50
+ /**
51
+ * Per-session step drill.
52
+ * @param {Object} params - { sessionId, from, to }
53
+ * @returns {Promise<Object>} { sessionId, steps: [{ workflowItemId,
54
+ * moduleType, exitPortId, entryPortId, stepCount, attemptCount,
55
+ * failureReason, duration, createdAt, completedAt, isHandoff }] }
56
+ * @example
57
+ * await sdk.reporting.ivrMenus.drill({ sessionId, from, to });
58
+ */
59
+ async drill({ sessionId, from, to } = {}) {
60
+ this.sdk.validateParams(
61
+ { sessionId },
62
+ { sessionId: { type: 'string', required: true } },
63
+ );
64
+ return internalRequest(
65
+ this.sdk,
66
+ `/reporting/ivrMenus${queryString({ sessionId, from, to })}`,
67
+ 'GET',
68
+ );
69
+ }
70
+
71
+ /**
72
+ * Session picker for one workflow (review-fix A2 finding 6): recent
73
+ * sessions in [from, to), with a human-readable label (caller name/
74
+ * number + time) -- never a raw session id as the display text, use
75
+ * `sessionId` only to then call drill().
76
+ * @param {Object} params - { workflowId, from, to }
77
+ * @returns {Promise<Object>} { workflowId, sessions: [{ sessionId, label,
78
+ * channel, createdAt, completedAt, endReason }] }
79
+ * @example
80
+ * await sdk.reporting.ivrMenus.sessions({ workflowId, from, to });
81
+ */
82
+ async sessions({ workflowId, from, to } = {}) {
83
+ this.sdk.validateParams(
84
+ { workflowId, from, to },
85
+ {
86
+ workflowId: { type: 'string', required: true },
87
+ from: { type: 'string', required: true },
88
+ to: { type: 'string', required: true },
89
+ },
90
+ );
91
+ return internalRequest(
92
+ this.sdk,
93
+ `/reporting/ivrMenus${queryString({ workflowId, from, to })}`,
94
+ 'GET',
95
+ );
96
+ }
97
+ }
@@ -0,0 +1,49 @@
1
+ import { internalRequest } from '../base.js';
2
+
3
+ // Q2-style local helper (same as reporting.js/reportingCallLog.js -- no
4
+ // shared util module between these files today).
5
+ function queryString(params = {}) {
6
+ const parts = [];
7
+ for (const [key, value] of Object.entries(params)) {
8
+ if (value === undefined || value === null || value === '') continue;
9
+ const v = Array.isArray(value) ? value.join(',') : value;
10
+ parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
11
+ }
12
+ return parts.length ? `?${parts.join('&')}` : '';
13
+ }
14
+
15
+ // #3 analytics-expansion A1a (plan §4.9): missed-call -> callback funnel.
16
+ // Own file (not reporting.js) same as ReportingCallLogService -- keeps
17
+ // reporting.js under the repo's 400-line limit.
18
+ export class ReportingMissedCallsService {
19
+ constructor(sdk) {
20
+ this.sdk = sdk;
21
+ }
22
+
23
+ /**
24
+ * @param {Object} params - { from, to }
25
+ * @returns {Promise<Object>} { missedCalls, voicemailsLeft, unmatchedAniCount,
26
+ * callbacksMatched, callbackRate, medianTimeToCallbackSec, windowHours,
27
+ * byQueue: [{ queueId, missedCalls, voicemailsLeft, callbacksMatched }],
28
+ * rows: [{ id, startTime, callerAni, peopleId, userId, queueId, queueName,
29
+ * hasVoicemail, callbackAt, callbackOutcome }] } -- `rows` is the
30
+ * most-recent 100 missed calls (review finding 1, A1a); callbackOutcome
31
+ * is one of "Called back after Xm" / "Awaiting callback" / "No callback".
32
+ * @example
33
+ * await sdk.reporting.missedCalls.summary({ from, to });
34
+ */
35
+ async summary({ from, to } = {}) {
36
+ this.sdk.validateParams(
37
+ { from, to },
38
+ {
39
+ from: { type: 'string', required: true },
40
+ to: { type: 'string', required: true },
41
+ },
42
+ );
43
+ return internalRequest(
44
+ this.sdk,
45
+ `/reporting/missedCalls${queryString({ from, to })}`,
46
+ 'GET',
47
+ );
48
+ }
49
+ }
@@ -0,0 +1,46 @@
1
+ import { internalRequest } from '../base.js';
2
+
3
+ // Q2-style local helper (same as reporting.js/reportingCallLog.js -- no
4
+ // shared util module between these files today).
5
+ function queryString(params = {}) {
6
+ const parts = [];
7
+ for (const [key, value] of Object.entries(params)) {
8
+ if (value === undefined || value === null || value === '') continue;
9
+ const v = Array.isArray(value) ? value.join(',') : value;
10
+ parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
11
+ }
12
+ return parts.length ? `?${parts.join('&')}` : '';
13
+ }
14
+
15
+ // analytics-expansion A1a (plan §4.6): number connect-rate, merged with
16
+ // existing 10DLC campaign status by phone number. Own file (not
17
+ // reporting.js) same as ReportingCallLogService -- keeps reporting.js
18
+ // under the repo's 400-line limit.
19
+ export class ReportingNumberHealthService {
20
+ constructor(sdk) {
21
+ this.sdk = sdk;
22
+ }
23
+
24
+ /**
25
+ * @param {Object} params - { from, to }
26
+ * @returns {Promise<Object>} { rows: [{ phoneNumber, name, offered, answered,
27
+ * connectRate, tenDlc: { campaignId, campaignName, campaignStatus,
28
+ * linkingStatus } | null }] }
29
+ * @example
30
+ * await sdk.reporting.numberHealth.connectRate({ from, to });
31
+ */
32
+ async connectRate({ from, to } = {}) {
33
+ this.sdk.validateParams(
34
+ { from, to },
35
+ {
36
+ from: { type: 'string', required: true },
37
+ to: { type: 'string', required: true },
38
+ },
39
+ );
40
+ return internalRequest(
41
+ this.sdk,
42
+ `/reporting/numberHealth${queryString({ from, to })}`,
43
+ 'GET',
44
+ );
45
+ }
46
+ }
@@ -0,0 +1,76 @@
1
+ import { internalRequest } from '../base.js';
2
+
3
+ // Q2-style local helper (same as reporting.js/reportingMissedCalls.js --
4
+ // no shared util module between these files today).
5
+ function queryString(params = {}) {
6
+ const parts = [];
7
+ for (const [key, value] of Object.entries(params)) {
8
+ if (value === undefined || value === null || value === '') continue;
9
+ const v = Array.isArray(value) ? value.join(',') : value;
10
+ parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(v)}`);
11
+ }
12
+ return parts.length ? `?${parts.join('&')}` : '';
13
+ }
14
+
15
+ // #1a analytics-expansion A2 (per-report-detail.md #1a): ring group
16
+ // volume/answered/handle + per-member offers + hour-of-day heatmap. Own
17
+ // file (not reporting.js) same as ReportingMissedCallsService -- keeps
18
+ // reporting.js under the repo's 400-line limit. Scope:
19
+ // admin:ringgroup:manage, family ringGroups.
20
+ export class ReportingRingGroupsService {
21
+ constructor(sdk) {
22
+ this.sdk = sdk;
23
+ }
24
+
25
+ /**
26
+ * Account-wide ring group summary.
27
+ * @param {Object} params - { from, to }
28
+ * @returns {Promise<Object>} { ringGroups: [{ ringGroupId, ringGroupName,
29
+ * offered, answered, abandonRate, avgHandle }], trend: { days: string[],
30
+ * offered: number[], answered: number[], prevOffered: number[] } }
31
+ * (trend is account-wide across all ring groups -- days/offered/answered
32
+ * are the current window bucketed daily, prevOffered is the equal-length
33
+ * PRIOR window's offered count, index-aligned with `days` by day-of-
34
+ * window position, not matching calendar dates -- the ghost compare line)
35
+ * @example
36
+ * await sdk.reporting.ringGroups.summary({ from, to });
37
+ */
38
+ async summary({ from, to } = {}) {
39
+ this.sdk.validateParams(
40
+ { from, to },
41
+ {
42
+ from: { type: 'string', required: true },
43
+ to: { type: 'string', required: true },
44
+ },
45
+ );
46
+ return internalRequest(
47
+ this.sdk,
48
+ `/reporting/ringGroups${queryString({ from, to })}`,
49
+ 'GET',
50
+ );
51
+ }
52
+
53
+ /**
54
+ * Per-ring-group drill: hour-of-day heatmap + per-member offer counts.
55
+ * @param {Object} params - { ringGroupId, from, to }
56
+ * @returns {Promise<Object>} { ringGroupId, hourHeatmap: [{ hour, offered,
57
+ * answered }], members: [{ memberId, memberName, offered, answered }] }
58
+ * @example
59
+ * await sdk.reporting.ringGroups.drill({ ringGroupId, from, to });
60
+ */
61
+ async drill({ ringGroupId, from, to } = {}) {
62
+ this.sdk.validateParams(
63
+ { ringGroupId, from, to },
64
+ {
65
+ ringGroupId: { type: 'string', required: true },
66
+ from: { type: 'string', required: true },
67
+ to: { type: 'string', required: true },
68
+ },
69
+ );
70
+ return internalRequest(
71
+ this.sdk,
72
+ `/reporting/ringGroups${queryString({ ringGroupId, from, to })}`,
73
+ 'GET',
74
+ );
75
+ }
76
+ }
@@ -745,6 +745,8 @@ export class TaskService {
745
745
  * drop already released the leg; see voicemail-drop-plan.md §4.2.4)
746
746
  * @param {string} [options.dispositionId] - Disposition to pre-fill/stamp for this wrap-up
747
747
  * @param {Object} [options.metadata] - Extra context to carry into wrap-up (e.g. voicemail drop id/duration)
748
+ * @param {string} [options.reason] - Why this wrap-up started (e.g. 'draining' -- analytics-expansion
749
+ * D14/§4.13 bot containment capture; optional, most callers omit it)
748
750
  * @returns {Promise<Object>} Object containing the task ID and new status
749
751
  * @returns {string} result.taskId - The task ID that was modified
750
752
  * @returns {string} result.status - The new status ('wrapUp')
@@ -769,15 +771,16 @@ export class TaskService {
769
771
  * });
770
772
  */
771
773
  async wrapUp(options = {}) {
772
- const { taskId, skipSipHangup, dispositionId, metadata } = options;
774
+ const { taskId, skipSipHangup, dispositionId, metadata, reason } = options;
773
775
 
774
776
  this.sdk.validateParams(
775
- { taskId, skipSipHangup, dispositionId, metadata },
777
+ { taskId, skipSipHangup, dispositionId, metadata, reason },
776
778
  {
777
779
  taskId: { type: 'string', required: true },
778
780
  skipSipHangup: { type: 'boolean', required: false },
779
781
  dispositionId: { type: 'string', required: false },
780
782
  metadata: { type: 'object', required: false },
783
+ reason: { type: 'string', required: false },
781
784
  },
782
785
  );
783
786
 
@@ -785,6 +788,7 @@ export class TaskService {
785
788
  if (skipSipHangup !== undefined) body.skipSipHangup = skipSipHangup;
786
789
  if (dispositionId !== undefined) body.dispositionId = dispositionId;
787
790
  if (metadata !== undefined) body.metadata = metadata;
791
+ if (reason !== undefined) body.reason = reason;
788
792
 
789
793
  const params = { body };
790
794