@signalhousellc/sdk 1.0.62 → 1.0.64

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalhousellc/sdk",
-  "version": "1.0.62",
+  "version": "1.0.64",
   "description": "Signal House SDK for use with the Signal House platform",
   "type": "module",
   "main": "src/SignalHouseSDK.js",

package/src/domains/Groups.js

@@ -53,6 +53,24 @@ export class Groups {
 					return this.client(`/group/${safeGroupId}`, { method: "DELETE", ...options });
 				},
 
+				/**
+				 * Set a group's KYC complianceStatus (SHGHL-2740). Only flips the field — it does not
+				 * trigger any lockout side effects (halted sends, revoked API keys, etc.) for "rejected".
+				 * @async
+				 * @roles signalhouse
+				 * @param {Object} params - The parameters for updating a group's compliance status
+				 * @param {string} params.groupId - The ID of the group to update
+				 * @param {string} params.complianceStatus - One of "unverified", "pending", "verified", "rejected"
+				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+				 * @throws {Error} Throws an error if the groupId or complianceStatus parameter is missing
+				 * @returns {Promise<Object>} - The updated group object returned from the server
+				 */
+				updateComplianceStatus: async ({ groupId, complianceStatus, options = {} }) => {
+					this.client._require({ groupId, complianceStatus });
+					const safeGroupId = encodeURIComponent(groupId);
+					return this.client(`/group/${safeGroupId}/compliance-status`, { method: "PUT", body: { complianceStatus }, ...options });
+				},
+
 				/**
 				 * Link an external tenant (GHL/Shopify) to a V2 group (server-to-server). Exchanges a
 				 * single-use link token for a canonical group, adopting an empty portal group, repointing

package/src/domains/Messages.js

@@ -18,10 +18,10 @@ export class Messages {
 	 * @param {string} [params.status] - Filter messages by their status (ENQUEUED, DEQUEUED, SENT, FAILED, DELIVERED)
 	 * @param {string} [params.direction] - Filter messages by their direction (INBOUND, OUTBOUND)
 	 * @param {string|string[]} [params.messageType] - Filter messages by their type. Accepts a single value or an array (e.g. ["SMS", "MMS"]). Allowed values: SMS, MMS, RCS, WHATSAPP, VIBER, P2P. When omitted, defaults to all non-P2P types.
-	 * @param {string|string[]} [params.channel] - Filter messages by channel. Accepts a single value or an array. Allowed values: tenDLC, tollFree, p2p. Each message records its channel when it is saved, and this filters on that stored value; older messages from before this feature have no channel and count as tenDLC. Ignored when matchAny is true (matchAny takes precedence).
+	 * @param {string|string[]} [params.channel] - Filter messages by channel. Accepts a single value or an array. Allowed values: tenDLC, tollFree, shortCode, p2p. Each message records its channel when it is saved, and this filters on that stored value; older messages from before this feature have no channel and count as tenDLC. Ignored when matchAny is true (matchAny takes precedence).
 	 * @param {boolean} [params.matchAny] - When true, the provided campaignId/brandId/phoneNumber filters are OR'd (a message matches ANY of them) instead of the default most-specific-single behavior. subgroupId stays an AND scope. Opt-in/additive.
 	 * @param {string} [params.carrier] - Filter messages by the carrier used for sending
-	 * @param {string} [params.senderPhoneNumber] - Filter messages by the sender's phone number
+	 * @param {string} [params.senderPhoneNumber] - Filter messages by the sender's 5-6 digit Short Code or 10+ digit phone number
 	 * @param {string} [params.recipientPhoneNumber] - Filter messages by the recipient's phone number
 	 * @param {string} [params.startDate] - ISO-8601 date or timestamp; normalized to start-of-UTC-day (inclusive)
 	 * @param {string} [params.endDate] - ISO-8601 date or timestamp; normalized to end-of-UTC-day (inclusive). Hourly resolution is not supported
@@ -94,7 +94,7 @@ export class Messages {
 	 * @param {string} [params.startDate] - ISO-8601 date or timestamp; normalized to start-of-UTC-day (inclusive)
 	 * @param {string} [params.endDate] - ISO-8601 date or timestamp; normalized to end-of-UTC-day (inclusive). Hourly resolution is not supported
 	 * @param {boolean} [params.matchAny] - When true, the provided campaignId/brandId/phoneNumber filters are OR'd (match ANY) instead of the default most-specific-single behavior. subgroupId stays an AND scope. Opt-in/additive.
-	 * @param {string|string[]} [params.channel] - Filter analytics by channel (tenDLC, tollFree, p2p). Filters on the stored channel column; a tenDLC selection also includes older messages that have no channel, and p2p is a real channel here (matched by carrier). Accepts a single value or an array. Ignored when matchAny is true (matchAny takes precedence).
+	 * @param {string|string[]} [params.channel] - Filter analytics by channel (tenDLC, tollFree, shortCode, p2p). Filters on the stored channel column; a tenDLC selection also includes older messages that have no channel, and p2p is a real channel here (matched by carrier). Accepts a single value or an array. Ignored when matchAny is true (matchAny takes precedence).
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
 	 * @returns {Promise<Object>} - A promise that resolves to the analytics data
 	 */
@@ -117,7 +117,7 @@ export class Messages {
 	 * @param {string} [params.carrier] - Filter analytics by the carrier used for sending
 	 * @param {string} [params.startDate] - ISO-8601 date or timestamp; normalized to start-of-UTC-day (inclusive)
 	 * @param {string} [params.endDate] - ISO-8601 date or timestamp; normalized to end-of-UTC-day (inclusive). Hourly resolution is not supported
-	 * @param {string|string[]} [params.channel] - Filter analytics by channel (tenDLC, tollFree, p2p). Filters on the stored channel column; a tenDLC selection also includes older messages that have no channel, and p2p is a real channel here. Accepts a single value or an array.
+	 * @param {string|string[]} [params.channel] - Filter analytics by channel (tenDLC, tollFree, shortCode, p2p). Filters on the stored channel column; a tenDLC selection also includes older messages that have no channel, and p2p is a real channel here. Accepts a single value or an array.
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
 	 * @returns {Promise<Array>} - A promise that resolves to an array of analytics snapshot records
 	 */
@@ -159,7 +159,7 @@ export class Messages {
 	 * @param {string} [params.endDate]
 	 * @param {number} [params.page=1]
 	 * @param {number} [params.limit=50] - max 50 per page
-	 * @param {("tenDLC"|"tollFree"|"p2p"|"both")|Array<"tenDLC"|"tollFree"|"p2p">} [params.channel="both"] - Filter and rank rows by the stored channel column. "both" (default) means all activity. tenDLC/tollFree/p2p (single value or array) limit to the selected channel(s); toll-free is kept separate from 10DLC using the stored channel column.
+	 * @param {("tenDLC"|"tollFree"|"shortCode"|"p2p"|"both")|Array<"tenDLC"|"tollFree"|"shortCode"|"p2p">} [params.channel="both"] - Filter and rank rows by the stored channel column. "both" (default) means all activity. tenDLC/tollFree/shortCode/p2p (single value or array) limit to the selected channel(s).
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options]
 	 * @returns {Promise<Object>} - { rows, totalCount, page, limit }. Each row carries sms/mms/p2p metric columns plus `smsOptOuts` and `mmsOptOuts` from the DNC analytics MV (P2P has no opt-outs).
 	 */
@@ -185,7 +185,7 @@ export class Messages {
 	 * @param {string} [params.endDate]
 	 * @param {number} [params.page=1]
 	 * @param {number} [params.limit=50] - max 50 per page
-	 * @param {("tenDLC"|"tollFree"|"p2p"|"both")|Array<"tenDLC"|"tollFree"|"p2p">} [params.channel="both"] - Filter and rank rows by the stored channel column. "both" (default) means every code. tenDLC/tollFree/p2p (single value or array) limit to the selected channel(s); when one channel is selected, totalErrors reflects only that channel.
+	 * @param {("tenDLC"|"tollFree"|"shortCode"|"p2p"|"both")|Array<"tenDLC"|"tollFree"|"shortCode"|"p2p">} [params.channel="both"] - Filter and rank rows by the stored channel column. "both" (default) means every code. tenDLC/tollFree/shortCode/p2p (single value or array) limit to the selected channel(s); when one channel is selected, totalErrors reflects only that channel.
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options]
 	 * @returns {Promise<Object>} - { rows, totalCount, totalErrors: { sms, mms, p2p, all }, page, limit }
 	 */
@@ -208,7 +208,7 @@ export class Messages {
 	 * @param {string} [params.carrier] - Filter by the carrier
 	 * @param {string} [params.startDate] - ISO-8601 date or timestamp; normalized to start-of-UTC-day (inclusive)
 	 * @param {string} [params.endDate] - ISO-8601 date or timestamp; normalized to end-of-UTC-day (inclusive). Hourly resolution is not supported
-	 * @param {string|string[]} [params.channel] - Filter by channel (tenDLC, tollFree). Opt-outs are A2P-only, so p2p applies no filter. Filters on the stored channel column; a tenDLC selection also includes older opt-outs that have no channel.
+	 * @param {string|string[]} [params.channel] - Filter by channel (tenDLC, tollFree, shortCode). Opt-outs are A2P-only, so p2p applies no filter. Filters on the stored channel column; a tenDLC selection also includes older opt-outs that have no channel.
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
 	 * @returns {Promise<Object>} - A promise that resolves to the DNC analytics data (totals, byDate, byPhoneNumber, byCarrier)
 	 */
@@ -235,7 +235,7 @@ export class Messages {
 	 * @param {number} [params.limit] - Number of records per page
 	 * @param {string} [params.sortField] - Field to sort by
 	 * @param {string} [params.sortOrder] - Sort direction (asc, desc)
-	 * @param {string|string[]} [params.channel] - Filter by channel (tenDLC, tollFree). Opt-outs are A2P-only, so p2p applies no filter. Filters on the stored channel column; a tenDLC selection also includes older opt-outs that have no channel.
+	 * @param {string|string[]} [params.channel] - Filter by channel (tenDLC, tollFree, shortCode). Opt-outs are A2P-only, so p2p applies no filter. Filters on the stored channel column; a tenDLC selection also includes older opt-outs that have no channel.
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
 	 * @returns {Promise<Object>} - A promise that resolves to the paginated DNC records
 	 */
@@ -260,7 +260,7 @@ export class Messages {
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for sending an SMS message
-	 * @param {string} params.senderPhoneNumber - The phone number to send the message from
+	 * @param {string} params.senderPhoneNumber - The 5-6 digit Short Code or 10+ digit phone number to send the message from
 	 * @param {string|string[]} params.recipientPhoneNumbers - The phone number(s) to send the message to
 	 * @param {string} params.messageBody - The body of the SMS message
 	 * @param {string} [params.statusCallbackUrl] - The URL to receive status callbacks
@@ -341,7 +341,7 @@ export class Messages {
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for sending an MMS message
-	 * @param {string} params.senderPhoneNumber - The phone number to send the message from
+	 * @param {string} params.senderPhoneNumber - The 5-6 digit Short Code or 10+ digit phone number to send the message from
 	 * @param {string[]} params.recipientPhoneNumbers - The phone number(s) to send the message to
 	 * @param {string} params.messageBody - The body of the MMS message
 	 * @param {string[]} [params.mediaUrls] - The URLs of the media attachments

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/SipProfiles.js

@@ -147,44 +147,50 @@ export class SipProfiles {
 	}
 
 	/**
-	 * Assign a phone number to this SIP profile (routes inbound calls on that
-	 * number to the endpoint).
+	 * Assign a phone number to this SIP profile — routes inbound calls on that
+	 * number to the endpoint. Prefer `e164` (numbers are Mongo-authoritative); the
+	 * legacy `phoneNumberId` (a voice-backend phone-number UUID) is still accepted.
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The SIP profile UUID.
-	 * @param {string} params.phoneNumberId - The phone number UUID to assign.
+	 * @param {string} [params.e164] - The phone number in E.164 to assign (preferred).
+	 * @param {string} [params.phoneNumberId] - Legacy: a voice-backend phone number UUID.
 	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
-	 * @throws {Error} If id or phoneNumberId is missing.
+	 * @throws {Error} If id is missing, or neither e164 nor phoneNumberId is provided.
 	 * @returns {Promise<Object>} `{ sipProfile: {...} }`.
 	 */
-	async assignNumber({ id, phoneNumberId, options = {} }) {
-		this.client._require({ id, phoneNumberId });
+	async assignNumber({ id, e164, phoneNumberId, options = {} }) {
+		this.client._require({ id });
+		if (!e164 && !phoneNumberId) this.client._require({ e164 });
 		const safeId = encodeURIComponent(id);
 		return this.client(`/voice/sip-profiles/${safeId}/assign-number`, {
 			method: "POST",
-			body: { phoneNumberId },
+			body: e164 ? { e164 } : { phoneNumberId },
 			...options,
 		});
 	}
 
 	/**
-	 * Unassign a phone number from this SIP profile.
+	 * Unassign a phone number from this SIP profile. Prefer `e164`; the legacy
+	 * `phoneNumberId` (a voice-backend phone-number UUID) is still accepted.
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - Request parameters.
 	 * @param {string} params.id - The SIP profile UUID.
-	 * @param {string} params.phoneNumberId - The phone number UUID to unassign.
+	 * @param {string} [params.e164] - The phone number in E.164 to unassign (preferred).
+	 * @param {string} [params.phoneNumberId] - Legacy: a voice-backend phone number UUID.
 	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
-	 * @throws {Error} If id or phoneNumberId is missing.
+	 * @throws {Error} If id is missing, or neither e164 nor phoneNumberId is provided.
 	 * @returns {Promise<Object>} `{ sipProfile: {...} }`.
 	 */
-	async unassignNumber({ id, phoneNumberId, options = {} }) {
-		this.client._require({ id, phoneNumberId });
+	async unassignNumber({ id, e164, phoneNumberId, options = {} }) {
+		this.client._require({ id });
+		if (!e164 && !phoneNumberId) this.client._require({ e164 });
 		const safeId = encodeURIComponent(id);
 		return this.client(`/voice/sip-profiles/${safeId}/unassign-number`, {
 			method: "POST",
-			body: { phoneNumberId },
+			body: e164 ? { e164 } : { phoneNumberId },
 			...options,
 		});
 	}