@unboundcx/sdk 4.13.146-security.4 → 4.13.147

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.147",
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,16 @@
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';
12
+ import { ReportingSurveysService } from './reportingSurveys.js';
13
+ import { ReportingSalesService } from './reportingSales.js';
3
14
 
4
15
  // Q2: same queryString helper as reportingAgents.js (kept local -- no
5
16
  // shared util module between the two files today).
@@ -31,10 +42,38 @@ export class ReportingService {
31
42
  runs: (...args) => this.listScheduleRuns(...args),
32
43
  runNow: (...args) => this.runScheduleNow(...args),
33
44
  };
34
- // P3 (agent-reporting-plan.md §7 + §8.1): thin presets over the same
35
- // registry above -- /reporting/agents/*. Split into its own file/class
36
- // (house 400-line limit) since this file was already at 215 lines.
45
+ // Each namespace below is its own file/class to keep this file under
46
+ // the repo's 400-line limit (house convention, see .agents below).
47
+ // P3 (agent-reporting-plan.md §7 + §8.1): thin presets over the registry above -- /reporting/agents/*.
37
48
  this.agents = new ReportingAgentsService(sdk);
49
+ // #14 analytics-expansion A0b: account-wide CDR browse.
50
+ this.callLog = new ReportingCallLogService(sdk);
51
+ // A1b #11 (per-report-detail.md #11): dedicated endpoint, NOT a generic
52
+ // metric -- kept as a small namespace (not its own file) since it's one
53
+ // method.
54
+ this.licenses = {
55
+ utilization: (...args) => this.seatUtilization(...args),
56
+ };
57
+ // #3 analytics-expansion A1a (§4.9): missed-call -> callback funnel.
58
+ this.missedCalls = new ReportingMissedCallsService(sdk);
59
+ // analytics-expansion A1a (§4.6): number/10DLC connect-rate health.
60
+ this.numberHealth = new ReportingNumberHealthService(sdk);
61
+ // analytics-expansion D14/§4.13 (r17-r22): bot containment dedicated endpoint.
62
+ this.botContainment = new ReportingBotContainmentService(sdk);
63
+ // #2 analytics-expansion B0 (§4.1): voice MOS/jitter/loss.
64
+ this.callQuality = new ReportingCallQualityService(sdk);
65
+ // Work Package E analytics-expansion (§4.12): customer-facing AI feature adoption summarization.
66
+ this.aiAdoption = new ReportingAiAdoptionService(sdk);
67
+ // #1a analytics-expansion A2 (per-report-detail.md #1a): ring group volume/answered/handle + per-member offers.
68
+ this.ringGroups = new ReportingRingGroupsService(sdk);
69
+ // #1b analytics-expansion A2 (per-report-detail.md #1b): account-wide IVR/voice-workflow-menu analytics.
70
+ this.ivrMenus = new ReportingIvrMenusService(sdk);
71
+ // #13 analytics-expansion B1 (per-report-detail.md #13, atlas §C.2): tracked phrases + talk ratio, admin tracker/topic CRUD.
72
+ this.conversationInsights = new ReportingConversationInsightsService(sdk);
73
+ // Work Package B2 analytics-expansion (§4.4, security.md "Surveys / NPS" row): survey/NPS summary.
74
+ this.surveys = new ReportingSurveysService(sdk);
75
+ // Work Package C analytics-expansion (§4.5, §7 C row): Rep activity-to-revenue + Pipeline/deal-risk.
76
+ this.sales = new ReportingSalesService(sdk);
38
77
  }
39
78
 
40
79
  /**
@@ -152,6 +191,23 @@ export class ReportingService {
152
191
  );
153
192
  }
154
193
 
194
+ /**
195
+ * A1b #11: idle-seat snapshot (userLicenses joined to last-activity
196
+ * signals) -- gated on the EXISTING admin:license:manage scope, no new
197
+ * scope (security.md §B.1).
198
+ * @param {Object} params - { licenseTypeCode? }
199
+ * @returns {Promise<Object>} { generatedAt, licenseTypes: [{code,label,audience,seatCount,used,needsSeat}], seats: [{userId,userName,isRemoved,licenseTypeCode,licenseLabel,source,assignedAt,lastActiveAt,idleDays,seatCostEstimate}] }
200
+ * @example
201
+ * await sdk.reporting.licenses.utilization({ licenseTypeCode: 'license.support' });
202
+ */
203
+ async seatUtilization({ licenseTypeCode } = {}) {
204
+ return internalRequest(
205
+ this.sdk,
206
+ `/reporting/seatUtilization${queryString({ licenseTypeCode })}`,
207
+ 'GET',
208
+ );
209
+ }
210
+
155
211
  /**
156
212
  * Rollup health: last computed bucket, lag, missing buckets.
157
213
  * @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
+ { body: { 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
+ { body: 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
+ { body: { 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
+ }
@@ -0,0 +1,114 @@
1
+ import { internalRequest } from '../base.js';
2
+
3
+ // Q2-style local helper (same as reporting.js/reportingAiAdoption.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 C analytics-expansion (plan §4.5, §7 C row, per-report-
16
+ // detail.md #4/#5): Rep activity-to-revenue + Pipeline/deal-risk panel.
17
+ // Own file/class (same 400-line-limit reason as every other reporting.*
18
+ // sub-namespace -- see reporting.js's own comments). Scope:
19
+ // reporting:sales:read, family task_router. Every read on the API side
20
+ // goes through UOQL/recordType enforcement (security.md §B.2) -- a
21
+ // zero-recordType-grant user gets zero opportunity rows back, not an
22
+ // error, same shape as every other GET here.
23
+ export class ReportingSalesService {
24
+ constructor(sdk) {
25
+ this.sdk = sdk;
26
+ }
27
+
28
+ /**
29
+ * Per-rep activity (calls/SMS, CC data) joined with CRM pipeline
30
+ * movement (opportunities, owner-scoped UOQL) -- NOT Journeys, which the
31
+ * client calls directly via `sdk.journeys.funnel()`/`.repsMetrics()`
32
+ * (per-report-detail.md #4, plan §4.7/§8 r2 fix).
33
+ * @param {Object} params - { from, to, limit?, offset? } -- 'YYYY-MM-DD'/ISO.
34
+ * @returns {Promise<Object>} { rows: [{userId, userName, callCount,
35
+ * answeredCount, outboundCount, smsCount, sentCount, pipelineOpenCount,
36
+ * pipelineOpenAmount, pipelineClosedWonCount, pipelineClosedWonAmount,
37
+ * pipelineClosedLostCount}], rollup, pagination: {total,limit,offset,hasMore} }
38
+ * -- CRM fields are `null` (render "-") for a rep with no CRM rows at
39
+ * all in range, never `0` (per-report-detail.md #4 edge case).
40
+ * @example
41
+ * await sdk.reporting.sales.repActivity({ from, to });
42
+ */
43
+ async repActivity({ from, to, limit, offset } = {}) {
44
+ this.sdk.validateParams(
45
+ { from, to },
46
+ {
47
+ from: { type: 'string', required: true },
48
+ to: { type: 'string', required: true },
49
+ },
50
+ );
51
+ return internalRequest(
52
+ this.sdk,
53
+ `/reporting/sales/repActivity${queryString({ from, to, limit, offset })}`,
54
+ 'GET',
55
+ );
56
+ }
57
+
58
+ /**
59
+ * Open pipeline by stage + win/loss by lostReasonId (live UOQL
60
+ * aggregates) + funnel/stage-conversion % (opportunityStageHistory_acct).
61
+ * @param {Object} params - { from, to } -- `to` bounds the win/loss
62
+ * `closedAt` window and the funnel's `enteredAt` window.
63
+ * @returns {Promise<Object>} { stages: [{stageId,stageName,order,
64
+ * openCount,openAmount}], winLoss: [{isWon,lostReasonId,count,amount}],
65
+ * funnel: [{stageId,stageName,order,enteredCount,conversionFromPriorPct}] }
66
+ * @example
67
+ * await sdk.reporting.sales.pipeline({ from, to });
68
+ */
69
+ async pipeline({ from, to } = {}) {
70
+ this.sdk.validateParams(
71
+ { from, to },
72
+ {
73
+ from: { type: 'string', required: true },
74
+ to: { type: 'string', required: true },
75
+ },
76
+ );
77
+ return internalRequest(
78
+ this.sdk,
79
+ `/reporting/sales/pipeline${queryString({ from, to })}`,
80
+ 'GET',
81
+ );
82
+ }
83
+
84
+ /**
85
+ * Open-opportunity risk-pill list: daysInStage, daysSinceLastActivity,
86
+ * stageSkipFlag blended into a 0-100 `riskScore`/`riskTier`
87
+ * ('low'|'medium'|'high'). This list is intentionally UNWINDOWED --
88
+ * `from`/`to` are required/validated for contract consistency with the
89
+ * other /sales/* endpoints but are never applied as a filter (every open
90
+ * deal is scored regardless of forecastedCloseDate; see dealRisk.js's
91
+ * own "review fix (blocker)" comment for why).
92
+ * @param {Object} params - { from, to }
93
+ * @returns {Promise<Object>} { rows: [{opportunityId, name, ownerId,
94
+ * ownerName, stageId, stageName, amount, forecastedCloseDate,
95
+ * daysInStage, daysInStageEstimated, daysSinceLastActivity,
96
+ * stageSkipFlag, riskScore, riskTier}], summary: {high,medium,low} }
97
+ * @example
98
+ * await sdk.reporting.sales.dealRisk({ from, to });
99
+ */
100
+ async dealRisk({ from, to } = {}) {
101
+ this.sdk.validateParams(
102
+ { from, to },
103
+ {
104
+ from: { type: 'string', required: true },
105
+ to: { type: 'string', required: true },
106
+ },
107
+ );
108
+ return internalRequest(
109
+ this.sdk,
110
+ `/reporting/sales/dealRisk${queryString({ from, to })}`,
111
+ 'GET',
112
+ );
113
+ }
114
+ }
@@ -0,0 +1,48 @@
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 B2 analytics-expansion (plan §4.4, security.md "Surveys /
16
+ // NPS" row): Surveys / NPS beyond CSAT. Own file (not reporting.js) same
17
+ // as ReportingCallQualityService -- keeps reporting.js under the repo's
18
+ // 400-line limit. Scope: reporting:surveys:read, family task_router.
19
+ // Recordtype-scoped read (security.md §B.4) -- a caller with zero grants
20
+ // gets zero rows back, not every row.
21
+ export class ReportingSurveysService {
22
+ constructor(sdk) {
23
+ this.sdk = sdk;
24
+ }
25
+
26
+ /**
27
+ * @param {Object} params - { from, to }
28
+ * @returns {Promise<Object>} { totalResponses, npsResponseCount, nps,
29
+ * promoterPct, detractorPct, csatResponseCount, avgCsatScore,
30
+ * trend: [{ date, nps }] }
31
+ * @example
32
+ * await sdk.reporting.surveys.summary({ from, to });
33
+ */
34
+ async summary({ from, to } = {}) {
35
+ this.sdk.validateParams(
36
+ { from, to },
37
+ {
38
+ from: { type: 'string', required: true },
39
+ to: { type: 'string', required: true },
40
+ },
41
+ );
42
+ return internalRequest(
43
+ this.sdk,
44
+ `/reporting/surveys${queryString({ from, to })}`,
45
+ 'GET',
46
+ );
47
+ }
48
+ }
@@ -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