@unboundcx/sdk 4.13.146 → 4.13.148

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",
3
+ "version": "4.13.148",
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",
@@ -9,6 +9,8 @@ import { ReportingAiAdoptionService } from './reportingAiAdoption.js';
9
9
  import { ReportingRingGroupsService } from './reportingRingGroups.js';
10
10
  import { ReportingIvrMenusService } from './reportingIvrMenus.js';
11
11
  import { ReportingConversationInsightsService } from './reportingConversationInsights.js';
12
+ import { ReportingSurveysService } from './reportingSurveys.js';
13
+ import { ReportingSalesService } from './reportingSales.js';
12
14
 
13
15
  // Q2: same queryString helper as reportingAgents.js (kept local -- no
14
16
  // shared util module between the two files today).
@@ -40,12 +42,11 @@ export class ReportingService {
40
42
  runs: (...args) => this.listScheduleRuns(...args),
41
43
  runNow: (...args) => this.runScheduleNow(...args),
42
44
  };
43
- // P3 (agent-reporting-plan.md §7 + §8.1): thin presets over the same
44
- // registry above -- /reporting/agents/*. Split into its own file/class
45
- // (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/*.
46
48
  this.agents = new ReportingAgentsService(sdk);
47
- // #14 analytics-expansion A0b: account-wide CDR browse -- own file/class
48
- // (same reason as .agents above).
49
+ // #14 analytics-expansion A0b: account-wide CDR browse.
49
50
  this.callLog = new ReportingCallLogService(sdk);
50
51
  // A1b #11 (per-report-detail.md #11): dedicated endpoint, NOT a generic
51
52
  // metric -- kept as a small namespace (not its own file) since it's one
@@ -53,34 +54,26 @@ export class ReportingService {
53
54
  this.licenses = {
54
55
  utilization: (...args) => this.seatUtilization(...args),
55
56
  };
56
- // #3 analytics-expansion A1a (§4.9): missed-call -> callback funnel --
57
- // own file/class (same reason as .agents above).
57
+ // #3 analytics-expansion A1a (§4.9): missed-call -> callback funnel.
58
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).
59
+ // analytics-expansion A1a (§4.6): number/10DLC connect-rate health.
61
60
  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).
61
+ // analytics-expansion D14/§4.13 (r17-r22): bot containment dedicated endpoint.
64
62
  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).
63
+ // #2 analytics-expansion B0 (§4.1): voice MOS/jitter/loss.
67
64
  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).
65
+ // Work Package E analytics-expansion (§4.12): customer-facing AI feature adoption summarization.
71
66
  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).
67
+ // #1a analytics-expansion A2 (per-report-detail.md #1a): ring group volume/answered/handle + per-member offers.
75
68
  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).
69
+ // #1b analytics-expansion A2 (per-report-detail.md #1b): account-wide IVR/voice-workflow-menu analytics.
79
70
  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).
71
+ // #13 analytics-expansion B1 (per-report-detail.md #13, atlas §C.2): tracked phrases + talk ratio, admin tracker/topic CRUD.
83
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);
84
77
  }
85
78
 
86
79
  /**
@@ -226,12 +219,20 @@ export class ReportingService {
226
219
  }
227
220
 
228
221
  /**
222
+ * @param {Object} [params] - { reportKey?: string } -- analytics-expansion
223
+ * A0b: omit for Explore views only (unchanged default); pass
224
+ * 'callLog' for that report's saved views instead.
229
225
  * @returns {Promise<Object>} { results: [...] }
230
226
  * @example
231
227
  * const { results } = await sdk.reporting.views.list();
228
+ * const { results } = await sdk.reporting.views.list({ reportKey: 'callLog' });
232
229
  */
233
- async listViews() {
234
- return internalRequest(this.sdk, '/reporting/views', 'GET');
230
+ async listViews({ reportKey } = {}) {
231
+ return internalRequest(
232
+ this.sdk,
233
+ `/reporting/views${queryString({ reportKey })}`,
234
+ 'GET',
235
+ );
235
236
  }
236
237
 
237
238
  /**
@@ -111,4 +111,54 @@ export class ReportingCallLogService {
111
111
  { httpOnly: true },
112
112
  );
113
113
  }
114
+
115
+ /**
116
+ * Same filters as list() (no cursor/limit -- a series call always covers
117
+ * the whole window), bucketed answered/missed/voicemail/total over time.
118
+ * Bucket grain (hour vs day) and timezone are server-resolved, not
119
+ * caller-chosen (an explicit `tz` overrides the account default).
120
+ * @param {Object} params - { from, to, direction?: 'inbound'|'outbound',
121
+ * answered?: boolean, queueIds?: string[], ringGroupIds?: string[],
122
+ * userIds?: string[], phoneNumber?: string, recordingOnly?: boolean,
123
+ * tz?: string }
124
+ * @returns {Promise<Object>} { bucket: 'hour'|'day', timezone, series: [{ start, end, answered, missed, voicemail, total }] }
125
+ * @example
126
+ * await sdk.reporting.callLog.series({ from, to });
127
+ */
128
+ async series({
129
+ from,
130
+ to,
131
+ direction,
132
+ answered,
133
+ queueIds,
134
+ ringGroupIds,
135
+ userIds,
136
+ phoneNumber,
137
+ recordingOnly,
138
+ tz,
139
+ } = {}) {
140
+ this.sdk.validateParams(
141
+ { from, to },
142
+ {
143
+ from: { type: 'string', required: true },
144
+ to: { type: 'string', required: true },
145
+ },
146
+ );
147
+ return internalRequest(
148
+ this.sdk,
149
+ `/reporting/callLog/series${queryString({
150
+ from,
151
+ to,
152
+ direction,
153
+ answered,
154
+ queueIds,
155
+ ringGroupIds,
156
+ userIds,
157
+ phoneNumber,
158
+ recordingOnly,
159
+ tz,
160
+ })}`,
161
+ 'GET',
162
+ );
163
+ }
114
164
  }
@@ -139,7 +139,7 @@ export class ReportingConversationInsightsService {
139
139
  this.sdk,
140
140
  '/reporting/conversationInsights/trackers',
141
141
  'POST',
142
- { phraseText, isRegex, topicId, isActive },
142
+ { body: { phraseText, isRegex, topicId, isActive } },
143
143
  );
144
144
  }
145
145
 
@@ -156,7 +156,7 @@ export class ReportingConversationInsightsService {
156
156
  this.sdk,
157
157
  `/reporting/conversationInsights/trackers/${encodeURIComponent(id)}`,
158
158
  'PUT',
159
- params,
159
+ { body: params },
160
160
  );
161
161
  }
162
162
 
@@ -197,7 +197,7 @@ export class ReportingConversationInsightsService {
197
197
  this.sdk,
198
198
  '/reporting/conversationInsights/topics',
199
199
  'POST',
200
- { name },
200
+ { body: { name } },
201
201
  );
202
202
  }
203
203
  }
@@ -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
+ }