@signalhousellc/sdk 1.0.61 → 1.0.63

package/src/domains/Voice.js

@@ -5,6 +5,7 @@ import { Calls } from "./voice/Calls.js";
 import { CallLogs } from "./voice/CallLogs.js";
 import { GlobalVoiceSettings } from "./voice/GlobalVoiceSettings.js";
 import { Tokens } from "./voice/Tokens.js";
+import { Analytics } from "./voice/Analytics.js";
 
 /**
  * Voice domain — wraps the voice-backend service (mounted under /voice on the
@@ -19,6 +20,7 @@ import { Tokens } from "./voice/Tokens.js";
  * - `sdk.voice.callLogs`                  — Account-scoped call history: list/get + presigned recording.
  * - `sdk.voice.globalVoiceSettings`       — Account-wide voice defaults (accepted regions, max spend, E911).
  * - `sdk.voice.tokens`                    — Mint ephemeral SIP credentials for the browser voice SDK.
+ * - `sdk.voice.analytics`                 — Aggregated call analytics (summary tiles + byDate/byNumber/byCarrier breakdowns).
  */
 export class Voice {
 	constructor(client, enableAdmin) {
@@ -31,5 +33,6 @@ export class Voice {
 		this.callLogs = new CallLogs(client, enableAdmin);
 		this.globalVoiceSettings = new GlobalVoiceSettings(client, enableAdmin);
 		this.tokens = new Tokens(client, enableAdmin);
+		this.analytics = new Analytics(client, enableAdmin);
 	}
 }

package/src/domains/voice/Analytics.js

@@ -0,0 +1,76 @@
+/**
+ * @typedef {Object} VoiceAnalyticsFilters
+ * @property {string} [dateFrom] - ISO-8601 lower bound on call start time.
+ * @property {string} [dateTo] - ISO-8601 upper bound on call start time.
+ * @property {"day"|"week"|"month"} [groupBy] - Bucket size for the byDate breakdown (default "day").
+ * @property {"INBOUND"|"OUTBOUND"} [direction] - Restrict the breakdowns to one direction. Summary tiles always cover both.
+ * @property {string} [callSource] - Comma-separated CallLog.callSource list (SIP_TRUNK, PROGRAMMABLE_VOICE, AI_VOICE, WEBRTC, VOICEMAIL, CONFERENCE, PSTN).
+ * @property {string} [subgroupId] - Filter by owning subgroup.
+ * @property {string} [number] - Substring match against either leg (from OR to).
+ * @property {string} [carrier] - Filter by carrier.
+ */
+
+/**
+ * @typedef {Object} VoiceDirectionSummary
+ * @property {number} totalCalls
+ * @property {number} successfulCalls
+ * @property {number} successRate - Percentage (0–100).
+ * @property {number} avgCallsPerDay
+ * @property {number|null} avgCallDurationSeconds
+ * @property {number} totalCallMinutes
+ * @property {number} answerRate - Percentage (ASR / answer seizure rate).
+ * @property {number} abandonmentRate - Percentage (CANCELED before answer).
+ * @property {number} failedCalls
+ * @property {number} failureRate - Percentage.
+ * @property {number} pctUnder6s - Percentage of answered calls under 6 seconds.
+ * @property {number|null} avgRingDurationSeconds - Average answer_time − start_time.
+ * @property {number|null} sentimentScore - Positive-sentiment percentage.
+ * @property {"Positive"|"Negative"|"Neutral"|null} sentimentLabel
+ */
+
+/**
+ * @typedef {Object} VoiceBreakdownBucket
+ * @property {string} key - The date / number / carrier this bucket aggregates.
+ * @property {number} total
+ * @property {number} completed
+ * @property {number} failed
+ * @property {number} noAnswer
+ * @property {number} busy
+ * @property {number} canceled
+ * @property {number} inProgress
+ * @property {number} totalDurationSeconds
+ * @property {number|null} avgSentimentScore
+ */
+
+/**
+ * Voice Analytics — aggregated call metrics for the portal Voice Analytics view
+ * (voice-backend `GET /voice/stats/voice-analytics`). Returns per-direction
+ * summary tiles (both directions) plus byDate / byNumber / byCarrier status
+ * breakdowns for charts. Distinct from `voice.callLogs`, which is the raw call
+ * history. Accessed via `sdk.voice.analytics`.
+ */
+export class Analytics {
+	constructor(client, enableAdmin) {
+		this.client = client;
+		this.enableAdmin = enableAdmin;
+	}
+
+	/**
+	 * Get aggregated voice analytics for the current account.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} [params] - Request parameters.
+	 * @param {VoiceAnalyticsFilters} [params.filters] - Optional filters. Summary tiles honor every filter except `direction`; breakdowns honor all filters.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<Object>} `{ success, range, outbound: VoiceDirectionSummary, inbound: VoiceDirectionSummary, byDate: VoiceBreakdownBucket[], byNumber: VoiceBreakdownBucket[], byCarrier: VoiceBreakdownBucket[], byChannel: VoiceBreakdownBucket[] }` (byChannel = per-callSource breakdown).
+	 */
+	async get({ filters = {}, options = {} } = {}) {
+		const query = new URLSearchParams();
+		for (const [k, v] of Object.entries(filters)) {
+			if (v !== undefined && v !== null && v !== "") query.set(k, String(v));
+		}
+		const qs = query.toString();
+		const path = qs ? `/voice/stats/voice-analytics?${qs}` : `/voice/stats/voice-analytics`;
+		return this.client(path, { method: "GET", ...options });
+	}
+}

package/src/domains/voice/SipTrunks.js

@@ -157,4 +157,41 @@ export class SipTrunks {
 	async getPops({ options = {} } = {}) {
 		return this.client(`/voice/sip-trunks/pops`, { method: "GET", ...options });
 	}
+
+	/**
+	 * Attach one or more phone numbers (by E.164) to a SIP trunk — routes each
+	 * DID down the trunk. Idempotent; numbers already configured on a SIP profile
+	 * are skipped and returned in `skipped` with a reason.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The SIP trunk UUID.
+	 * @param {string[]} params.phoneNumbers - Phone numbers in E.164 (a leading "+" is optional).
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id or phoneNumbers is missing.
+	 * @returns {Promise<Object>} `{ assigned: string[], skipped: { e164, reason }[] }`.
+	 */
+	async assignNumbers({ id, phoneNumbers, options = {} }) {
+		this.client._require({ id, phoneNumbers });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/sip-trunks/${safeId}/assign-numbers`, { method: "POST", body: { phoneNumbers }, ...options });
+	}
+
+	/**
+	 * Detach one or more phone numbers (by E.164) from a SIP trunk — removes each
+	 * number's SIP_TRUNK inbound route when it points at this trunk.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.id - The SIP trunk UUID.
+	 * @param {string[]} params.phoneNumbers - Phone numbers in E.164 (a leading "+" is optional).
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If id or phoneNumbers is missing.
+	 * @returns {Promise<Object>} `{ unassigned: string[] }`.
+	 */
+	async unassignNumbers({ id, phoneNumbers, options = {} }) {
+		this.client._require({ id, phoneNumbers });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/voice/sip-trunks/${safeId}/unassign-numbers`, { method: "POST", body: { phoneNumbers }, ...options });
+	}
 }