@signalhousellc/sdk 1.0.64 → 1.0.66

package/src/domains/Brands.js

@@ -30,7 +30,7 @@
  * @property {string} vertical - The vertical for the brand (PROFESSIONAL, REAL_ESTATE, HEALTHCARE, HUMAN_RESOURCES, ENERGY, ENTERTAINMENT, RETAIL, TRANSPORTATION, AGRICULTURE, INSURANCE, POSTAL, EDUCATION, HOSPITALITY, FINANCIAL, POLITICAL, GAMBLING, LEGAL, CONSTRUCTION, NGO, MANUFACTURING, GOVERNMENT, TECHNOLOGY, COMMUNICATION)
  * @property {string} [referenceId] - A unique reference for the brand
  * @property {Array<string>} [tag] - An array of tags to associate with the brand
- * @property {boolean} [mock] - Whether to create the brand in the mock environment (for testing purposes only)
+ * @property {boolean} [mock] - Whether to register the brand in TCR's mock environment instead of the live registry. TCR is still called and the mock brand auto-approves, so it does not exercise the rejection states a live registration can hit. Brand creation is not billed; campaign registration and number purchase are still billed as normal
  * @property {string} [businessContactEmail] - The email address of the business contact for the brand (required if entityType is PUBLIC_PROFIT or NON_PROFIT)
  */
 
@@ -59,7 +59,7 @@
  * @property {string} [altBusinessIdType] - The type of the alternative business identifier ("NONE", "DUNS", "LEI", "GIIN")
  * @property {string} [brandRelationship] - Not in use - reserved for future use
  * @property {string} [businessContactEmail] - The email address of the business contact for the brand (required if entityType is PUBLIC_PROFIT or NON_PROFIT)
- * @property {Object} [tollFree] - Toll-Free editable fields, used when updating a Toll-Free brand. Optional sub-fields: legalEntityType, businessRegistrationType, taxId, countryCode, supportPhone, taxIdIssuingCountry, businessDBA, businessWebsite. (Toll-Free brands sync to Infobip; only DCA_PENDING/DCA_ACTIVE brands are editable and subgroupId is immutable.)
+ * @property {Object} [tollFree] - Toll-Free editable fields, used when updating a Toll-Free brand. Optional sub-fields: legalEntityType, businessRegistrationType, taxId, countryCode, supportPhone, taxIdIssuingCountry, businessDBA, businessWebsite. supportPhone must be E.164 with an optional leading "+" and no spaces, parentheses or hyphens (e.g. "17025550100"). (Toll-Free brands sync to Infobip; only DCA_PENDING/DCA_ACTIVE brands are editable and subgroupId is immutable.)
  */
 
 /**
@@ -68,7 +68,7 @@
  * @property {string} legalEntityType - The legal entity type (required, one of PRIVATE_COMPANY, PUBLIC_COMPANY, NON_PROFIT, GOVERNMENT, SOLE_PROPRIETOR)
  * @property {string} taxId - The business tax identifier (required, at most 50 characters)
  * @property {string} countryCode - The business country code (required, 2-letter ISO code)
- * @property {string} supportPhone - The customer-support phone number (required, at most 20 characters)
+ * @property {string} supportPhone - The customer-support phone number (required, E.164 with an optional leading "+" and no spaces, parentheses or hyphens, e.g. "17025550100")
  * @property {string} [taxIdIssuingCountry] - The country that issued the tax ID (optional, 2-letter ISO code)
  * @property {string} [businessDBA] - The business "doing business as" name (optional, at most 255 characters)
  * @property {string} [businessWebsite] - The customer's real website, sent to Infobip for brand verification (optional, valid URL, at most 255 characters; distinct from the top-level website / landing URL)
@@ -90,7 +90,7 @@
  * @property {TollFreeBrandDetails} tollFree - The Toll-Free brand details (required)
  * @property {string} [referenceId] - A unique reference for the brand (optional, at most 50 characters)
  * @property {Array<string>} [tag] - An array of tags to associate with the brand (optional)
- * @property {boolean} [mock] - Whether to create the brand in the mock environment (for testing purposes only)
+ * @property {boolean} [mock] - Accepted and stored, but has no effect on Toll-Free registration: Toll-Free does not use TCR and is already free
  * @property {string} [optInLink] - A URL linking to the opt-in flow for the brand (optional, valid URL, at most 255 characters)
  * @property {string} [privacyPolicyLink] - A URL linking to the privacy policy for the brand (optional, valid URL, at most 255 characters)
  * @property {string} [termsAndConditionsLink] - A URL linking to the terms and conditions for the brand (optional, valid URL, at most 255 characters)

package/src/domains/Campaigns.js

@@ -64,7 +64,7 @@
  * @property {string} [privacyPolicyLink] - A URL linking to the privacy policy for the campaign (optional, must be at most 2048 characters if provided)
  * @property {string} [termsAndConditionsLink] - A URL linking to the terms and conditions for the campaign (optional, must be at most 2048 characters if provided)
  * @property {string} [embeddedLinkSample] - A sample of the embedded link used in the campaign (optional, must be at most 255 characters if provided)
- * @property {Object} [tollFree] - Toll-Free editable fields, used when updating a Toll-Free campaign. Mirrors the CreateTollFreeCampaignData `tollFree` object with every field optional (useCase, messageVolume, programSummary (40-500), exampleMessage, customerCareEmail, optInImageURLs, optIns, multiNumberReason (≤500)). Phone numbers cannot be changed via update — Toll-Free numbers are locked to their campaign.
+ * @property {Object} [tollFree] - Toll-Free editable fields, used when updating a Toll-Free campaign. Mirrors the CreateTollFreeCampaignData `tollFree` object with every field optional (useCase, messageVolume, programSummary (40-500), exampleMessage (≤1000), customerCareEmail, optInImageURLs, optIns, multiNumberReason (≤500), useCases, channels, landingId). Phone numbers cannot be changed via update — Toll-Free numbers are locked to their campaign.
  */
 
 /**
@@ -79,7 +79,7 @@
  * @property {string} useCase - The Toll-Free use case (required, e.g. TWO_FA, GENERAL_MARKETING, HEALTHCARE, MIXED — one of the Toll-Free use-case values)
  * @property {string} messageVolume - The estimated monthly message volume tier (required, one of TEN, HUNDRED, THOUSAND, TEN_THOUSAND, HUNDRED_THOUSAND, TWO_HUNDRED_FIFTY_THOUSAND, FIVE_HUNDRED_THOUSAND, SEVEN_HUNDRED_FIFTY_THOUSAND, ONE_MILLION, FIVE_MILLION, TEN_MILLION_PLUS)
  * @property {string} programSummary - A summary of the messaging program (required, 40-500 characters)
- * @property {string} exampleMessage - An example message (required, at most 4096 characters; stored verbatim, no STOP/HELP appended by the server)
+ * @property {string} exampleMessage - An example message (required, at most 1000 characters; holds one sample per use case, stored verbatim, no STOP/HELP appended by the server)
  * @property {string} customerCareEmail - A customer-care contact email (required, valid email)
  * @property {Array<string>} optInImageURLs - URLs to opt-in proof images (required, at least one, each at most 2048 characters)
  * @property {Object} [optIns] - Opt-in method details. Each channel is optional.
@@ -88,6 +88,9 @@
  * @property {TollFreeOptIn} [optIns.keyword] - Keyword opt-in details
  * @property {TollFreeOptIn} [optIns.interactiveVoiceResponse] - IVR opt-in details
  * @property {string} [multiNumberReason] - Internally-stored reason the customer requested more than one Toll-Free number on the campaign (optional, at most 500 characters). Required when more than one phone number is assigned; captured for Signal House review only and never sent to the carrier.
+ * @property {string[]} [useCases] - The sender's real use-case picks (optional). `useCase` above carries the single value the carrier accepts (MIXED when there is more than one); these are what a Signal House landing page renders a consent checkbox per. Never forwarded to the carrier.
+ * @property {string[]} [channels] - The channels consent covers ("SMS", "MMS", "VOICE") (optional). Never forwarded to the carrier.
+ * @property {string} [landingId] - The Signal House landing page whose consent boxes this campaign's call-to-action describes (optional). Must be an ACTIVE page owned by the same brand and group.
  */
 
 /**
@@ -261,6 +264,15 @@ export class Campaigns {
    * @param {string} [params.sortOrder] - Sort direction ("asc" or "desc")
    * @param {string} [params.registrationType] - Filter by registration type ("TEN_DLC", "TOLL_FREE", or "SHORT_CODE")
    * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   *
+   * Every record carries a `sentiment` object -- trailing 7-day and 30-day inbound reply sentiment,
+   * refreshed periodically from analytics rather than computed per request: `{ sevenDay, thirtyDay,
+   * updatedAt }`, each window being `{ score, label, scoredCount, positive, neutral, negative }`. The
+   * object is always present and fully populated, so it can be read without a presence check.
+   * `score` is a volume-weighted average in -100..100 and is null when nothing was scored in the
+   * window, which is not the same as a score of 0 -- null means nobody replied, 0 means replies
+   * averaged neutral. `updatedAt` is null until the first rollup writes the record, and it tracks when
+   * the figures last CHANGED, not when the job last ran.
    * @returns {Promise<Array|Object>} The response from the server - array when unpaginated, or { data, total, page, limit, totalPages } when paginated
    */
   async getCampaigns({
@@ -441,13 +453,18 @@ export class Campaigns {
    * @roles api, admin, developer, user
    * @param {Object} params - The parameters for capturing the opt-in image
    * @param {string} params.brandId - The ID of the brand whose generated landing page should be captured
+   * @param {string} [params.landingId] - The specific page to capture. Required for Toll-Free brands, which have
+   *   one page per campaign — omitted, the request is refused rather than guessing which page to shoot. A 10DLC
+   *   brand has a single page, so it may be omitted there
    * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the brandId parameter is missing
    * @returns {Promise<Object>} The response from the server containing the hosted image's id and URL
    */
-  async captureOptInImageFromLanding({ brandId, options = {} }) {
+  async captureOptInImageFromLanding({ brandId, landingId, options = {} }) {
     this.client._require({ brandId });
-    return this.client(`/campaign/opt-in-image/from-landing`, { method: 'POST', body: { brandId }, ...options });
+    const body = { brandId };
+    if (landingId) body.landingId = landingId;
+    return this.client(`/campaign/opt-in-image/from-landing`, { method: 'POST', body, ...options });
   }
 
   /**

package/src/domains/Groups.js

@@ -6,6 +6,23 @@ export class Groups {
 		// Hidden Admin namespace INSIDE the domain
 		if (enableAdmin) {
 			this.admin = {
+				/**
+					 * Get resource counts grouped by group ID. Only signalhouse_admin can query all groups;
+					 * every other allowed role is restricted to its JWT group scope.
+				 * @async
+					 * @roles signalhouse, api, admin, developer, billing, user
+				 * @param {Object} [params] - Optional group-count filters and pagination.
+				 * @param {string} [params.groupId] - Restrict results to a group.
+				 * @param {number} [params.limit] - Maximum rows to return.
+				 * @param {number} [params.offset] - Rows to skip; requires limit.
+				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+				 * @returns {Promise<Object>} - Group-level resource count rows.
+				 */
+				getGroupCounts: async ({ groupId, limit, offset, options = {} } = {}) => {
+					const queryString = this.client._getQueryString({ groupId, limit, offset });
+					return this.client(`/group/counts${queryString}`, { method: "GET", ...options });
+				},
+
 				/**
 				 * Get a list of all groups with optional pagination parameters
 				 * @async
@@ -27,7 +44,7 @@ export class Groups {
 				 * @async
 				 * @roles signalhouse
 				 * @param {Object} params - The parameters for creating a new group
-				 * @param {Object} params.groupData - The data for the new group, including required fields such as groupName
+				 * @param {Object} params.groupData - The data for the new group, including required fields such as groupName. Optionally accepts `psPartnerKey` and `ownerEmail` to credit a referring partner.
 				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
 				 * @throws {Error} Throws an error if the groupData parameter is missing or if required fields within groupData are missing
 				 * @returns {Promise<Object>} - The created group object returned from the server

package/src/domains/Landings.js

@@ -1,3 +1,18 @@
+/**
+ * @typedef {Object} TollFreeConsentBox
+ * @property {string} useCase - The use case the checkbox covers
+ * @property {string} channel - The channel the checkbox covers ("SMS" or "MMS")
+ * @property {string} text - The wording rendered beside the checkbox
+ */
+
+/**
+ * @typedef {Object} TollFreeLandingData
+ * @property {string[]} useCases - The campaign's real use cases; one consent box is rendered per use case per channel
+ * @property {string[]} channels - The channels consent covers ("SMS", "MMS", "VOICE")
+ * @property {string} consentDisclosure - The shared disclosure rendered once above the consent boxes (max 1024 characters)
+ * @property {TollFreeConsentBox[]} consentBoxes - The consent boxes the page renders (max 16; each text max 512 characters)
+ */
+
 /**
  * @typedef {Object} CreateLandingData
  * @property {string} brandId - The ID of the brand to associate with the landing page
@@ -7,6 +22,11 @@
  * @property {string} primaryTextColor - The primary text color for the landing page (e.g., "#000000")
  * @property {string} secondaryTextColor - The secondary text color for the landing page (e.g., "#333333")
  * @property {Buffer} logo - A logo image file for the landing page, provided as a Buffer
+ * @property {string} [registrationType] - Which page type to build: "TEN_DLC" (default) or "TOLL_FREE"
+ * @property {TollFreeLandingData} [tollFree] - Toll-Free consent content; required when registrationType is "TOLL_FREE"
+ * @property {boolean} [useBrandTemplate] - Toll-Free only. Build the page from the brand's landing page template,
+ *   taking its colors, logo and webhook URL from there. When set, no logo file is required. `description` is
+ *   still sent by the caller, since the About paragraph names the services this campaign's use cases cover.
  */
 
 /**
@@ -17,6 +37,21 @@
  * @property {string} [primaryTextColor] - The primary text color for the landing page (e.g., "#000000")
  * @property {string} [secondaryTextColor] - The secondary text color for the landing page (e.g., "#333333")
  * @property {Buffer} [logo] - A logo image file for the landing page, provided as a Buffer
+ * @property {string} [registrationType] - Which page type to build: "TEN_DLC" or "TOLL_FREE"
+ * @property {TollFreeLandingData} [tollFree] - Replaces the whole Toll-Free consent subdocument when set
+ * @property {boolean} [useBrandTemplate] - Toll-Free only. Re-copy the brand's landing page template into this
+ *   page, so a corrected logo or color reaches a page that already exists instead of creating a second one.
+ */
+
+/**
+ * @typedef {Object} LandingTemplateData
+ * @property {string} userDescription - The customer's own sentence about their business. Not the finished About
+ *   paragraph: the services clause is added per campaign when a page is generated
+ * @property {string} [primaryBackgroundColor] - The primary background color (e.g., "#FFFFFF")
+ * @property {string} [secondaryBackgroundColor] - The secondary background color (e.g., "#F0F0F0")
+ * @property {string} [primaryTextColor] - The primary text color (e.g., "#000000")
+ * @property {string} [secondaryTextColor] - The secondary text color (e.g., "#333333")
+ * @property {string} [webhookUrl] - Where generated pages post opt-in submissions
  */
 
 export class Landings {
@@ -139,6 +174,55 @@ export class Landings {
 		return this.client(`/landing/brand/${safeBrandId}`, { method: "GET", ...options });
 	}
 
+	/**
+	 * Get a brand's Toll-Free landing page template — the reusable look every page the brand generates
+	 * snapshots. Returns an empty array when the brand has no template.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for getting a landing page template
+	 * @param {string} params.brandId - The brand ID to look up the template for
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws an error if the brandId parameter is missing
+	 * @returns {Promise<Object>} - The template returned from the server
+	 */
+	async getLandingTemplate({ brandId, options = {} }) {
+		this.client._require({ brandId });
+		const safeBrandId = encodeURIComponent(brandId);
+		return this.client(`/landing/template/${safeBrandId}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Create or replace a brand's Toll-Free landing page template. Editing a template never alters a page
+	 * that already exists, so a URL already given to a carrier keeps rendering what was declared.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for saving a landing page template
+	 * @param {string} params.brandId - The brand the template belongs to
+	 * @param {LandingTemplateData} params.templateData - The template fields (see LandingTemplateData typedef)
+	 * @param {Buffer} [params.file] - A logo image file, provided as a Buffer. Required the first time only;
+	 *   omit it on a later save to keep the stored logo
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws an error if the brandId parameter is missing
+	 * @returns {Promise<Object>} - The saved template returned from the server
+	 */
+	async upsertLandingTemplate({ brandId, templateData, file, options = {} }) {
+		this.client._require({ brandId });
+		const safeBrandId = encodeURIComponent(brandId);
+		const formData = new FormData();
+
+		if (file) {
+			formData.append("file", file);
+		}
+
+		Object.entries(templateData).forEach(([key, value]) => {
+			if (value !== undefined) {
+				formData.append(key, typeof value === "object" ? JSON.stringify(value) : value);
+			}
+		});
+
+		return this.multipartClient(`/landing/template/${safeBrandId}`, { method: "PUT", body: formData, ...options });
+	}
+
 	async deleteLanding({ landingId, options = {} }) {
 		this.client._require({ landingId });
 		const safeLandingId = encodeURIComponent(landingId);

package/src/domains/Messages.js

@@ -21,16 +21,19 @@ export class Messages {
 	 * @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|string[]} [params.sentimentLabel] - Filter messages by sentiment bucket. Accepts a single value or an array (e.g. ["positive", "negative"]). Allowed values: positive, neutral, negative. Applied as the sentimentScore range the ±25 label threshold produces, so unscored messages match no bucket and outbound messages (never scored) are excluded.
 	 * @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
-	 * @param {string} [params.sortField] - The field to sort the messages by
+	 * @param {string} [params.sortField] - The field to sort the messages by (createdAt, segmentCount, status, sentimentScore)
 	 * @param {string} [params.sortOrder] - The order to sort the messages (asc, desc)
 	 * @param {number} [params.page] - The page number for pagination
 	 * @param {number} [params.limit] - The number of messages per page
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} - A promise that resolves to the list of messages
+	 * @returns {Promise<Object>} - A promise that resolves to the list of messages. Inbound messages also carry
+	 * sentimentScore (-100..100, null when unscored), sentimentLabel ("positive"|"neutral"|"negative", null when
+	 * sentimentScore is null) and sentimentScoredAt. Outbound messages are never scored.
 	 */
 	async getMessages({
 		id,
@@ -47,6 +50,7 @@ export class Messages {
 		channel,
 		matchAny,
 		carrier,
+		sentimentLabel,
 		startDate,
 		endDate,
 		sortField,
@@ -55,7 +59,7 @@ export class Messages {
 		limit,
 		options = {},
 	}) {
-		const filters = { id, campaignId, brandId, subgroupId, groupId, phoneNumber, senderPhoneNumber, recipientPhoneNumber, status, direction, messageType, channel, matchAny, carrier, startDate, endDate, sortField, sortOrder, page, limit };
+		const filters = { id, campaignId, brandId, subgroupId, groupId, phoneNumber, senderPhoneNumber, recipientPhoneNumber, status, direction, messageType, channel, matchAny, carrier, sentimentLabel, startDate, endDate, sortField, sortOrder, page, limit };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/message${queryString}`, { method: "GET", ...options });
 	}
@@ -86,20 +90,28 @@ export class Messages {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for getting analytics
 	 * @param {string} [params.groupId] - Filter analytics by the ID of the associated group
-	 * @param {string} [params.subgroupId] - Filter analytics by the ID of the associated subgroup
-	 * @param {string} [params.brandId] - Filter analytics by the ID of the associated brand
-	 * @param {string} [params.campaignId] - Filter analytics by the ID of the associated campaign
-	 * @param {string} [params.phoneNumber] - Filter analytics by the phone number involved in the messages
-	 * @param {string} [params.carrier] - Filter analytics by the carrier used for sending
+	 * @param {string|string[]} [params.subgroupId] - Filter analytics by the ID of the associated subgroup. Accepts a single value, an array, or a comma-separated string.
+	 * @param {string|string[]} [params.brandId] - Filter analytics by the ID of the associated brand. Accepts a single value, an array, or a comma-separated string.
+	 * @param {string|string[]} [params.campaignId] - Filter analytics by the ID of the associated campaign. Accepts a single value, an array, or a comma-separated string.
+	 * @param {string|string[]} [params.phoneNumber] - Filter analytics by the phone number involved in the messages. Accepts a single value, an array, or a comma-separated string.
+	 * @param {string|string[]} [params.carrier] - Filter analytics by the carrier used for sending. Accepts a single value, an array, or a comma-separated string.
 	 * @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.messageType] - Message type(s) the SENTIMENT figures are scoped to: SMS, MMS or P2P (single value, array, or comma-separated string). Omit for all scored types. Does NOT narrow the message counts, which are always returned split per type (smsInbound/mmsInbound/p2pInbound) and have no filterable type dimension.
 	 * @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
+	 * @returns {Promise<Object>} - A promise that resolves to the analytics data. Also includes inbound-message
+	 * sentiment for the requested scope: sentimentScore (volume-weighted average of every scored inbound message
+	 * in range, -100..100, null when nothing was scored), sentimentLabel ("positive"|"neutral"|"negative", null
+	 * when sentimentScore is null), sentimentScoredCount, sentimentPositive, sentimentNeutral, sentimentNegative.
+	 * plus the same six per message type under smsSentiment*, mmsSentiment* and p2pSentiment* prefixes. Every
+	 * score is divided server-side and the raw sums are never returned: a score is an average and must never be
+	 * summed or re-averaged across types, rows or responses. To weight a subset of message types, pass
+	 * messageType and read sentimentScore.
 	 */
-	async getAnalytics({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel, matchAny, options = {} }) {
-		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel, matchAny };
+	async getAnalytics({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel, messageType, matchAny, options = {} }) {
+		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel, messageType, matchAny };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/message/analytics${queryString}`, { method: "GET", ...options });
 	}
@@ -110,19 +122,26 @@ export class Messages {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for getting detailed analytics
 	 * @param {string} [params.groupId] - Filter analytics by the ID of the associated group
-	 * @param {string} [params.subgroupId] - Filter analytics by the ID of the associated subgroup
-	 * @param {string} [params.brandId] - Filter analytics by the ID of the associated brand
-	 * @param {string} [params.campaignId] - Filter analytics by the ID of the associated campaign
-	 * @param {string} [params.phoneNumber] - Filter analytics by the phone number involved in the messages
-	 * @param {string} [params.carrier] - Filter analytics by the carrier used for sending
+	 * @param {string|string[]} [params.subgroupId] - Filter analytics by the ID of the associated subgroup. Accepts a single value, an array, or a comma-separated string.
+	 * @param {string|string[]} [params.brandId] - Filter analytics by the ID of the associated brand. Accepts a single value, an array, or a comma-separated string.
+	 * @param {string|string[]} [params.campaignId] - Filter analytics by the ID of the associated campaign. Accepts a single value, an array, or a comma-separated string.
+	 * @param {string|string[]} [params.phoneNumber] - Filter analytics by the phone number involved in the messages. Accepts a single value, an array, or a comma-separated string.
+	 * @param {string|string[]} [params.carrier] - Filter analytics by the carrier used for sending. Accepts a single value, an array, or a comma-separated string.
 	 * @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.messageType] - Message type(s) the SENTIMENT figures are scoped to: SMS, MMS or P2P (single value, array, or comma-separated string). Omit for all scored types. Does NOT narrow the message counts, which are always returned split per type (smsInbound/mmsInbound/p2pInbound) and have no filterable type dimension.
 	 * @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
+	 * @returns {Promise<Array>} - A promise that resolves to an array of analytics snapshot records. cardTotals and
+	 * every byDate/byPhoneNumber/byCarrier row also carry that row's own inbound-message sentiment: sentimentScore
+	 * (volume-weighted average, -100..100, null when nothing in that row's scope was scored), sentimentLabel,
+	 * sentimentScoredCount, sentimentPositive, sentimentNeutral, sentimentNegative. The fields are always present;
+	 * plus the same six per message type under smsSentiment*, mmsSentiment* and p2pSentiment* prefixes. Every
+	 * score is divided server-side and the raw sums are never returned: a score is an average and must never be
+	 * summed or re-averaged across types, rows or responses.
 	 */
-	async getAnalyticsDetail({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel, options = {} }) {
-		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel };
+	async getAnalyticsDetail({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel, messageType, options = {} }) {
+		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel, messageType };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/message/analytics/detail${queryString}`, { method: "GET", ...options });
 	}
@@ -160,11 +179,13 @@ export class Messages {
 	 * @param {number} [params.page=1]
 	 * @param {number} [params.limit=50] - max 50 per page
 	 * @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 {(string|string[])} [params.messageType] - Message type(s) the SENTIMENT figures are scoped to: SMS, MMS or P2P (single value, array, or comma-separated string). Omit for all scored types. Does NOT narrow the message counts, which are always returned split per type (smsInbound/mmsInbound/p2pInbound) and have no filterable type dimension.
 	 * @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).
+	 * Each row also carries that subgroup's inbound-message sentiment: `sentimentScore` (volume-weighted average of every scored inbound message in that subgroup, -100..100, null when nothing was scored), `sentimentLabel`, `sentimentScoredCount`, `sentimentPositive`, `sentimentNeutral`, `sentimentNegative`, plus the same six per message type under `smsSentiment*`, `mmsSentiment*` and `p2pSentiment*` prefixes. The score is derived server-side and must never be re-averaged across rows — combine the counts, not the scores.
 	 */
-	async getAnalyticsBySubgroup({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, page, limit, channel, options = {} }) {
-		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, page, limit, channel };
+	async getAnalyticsBySubgroup({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, page, limit, channel, messageType, options = {} }) {
+		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, page, limit, channel, messageType };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/message/analytics/by-subgroup${queryString}`, { method: "GET", ...options });
 	}

package/src/domains/Numbers.js

@@ -77,6 +77,15 @@ export class Numbers {
    * @param {number} [params.page] - The page number for pagination (default: 1)
    * @param {number} [params.limit] - The number of items per page for pagination (default: 20)
    * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   *
+   * Every record carries a `sentiment` object -- trailing 7-day and 30-day inbound reply sentiment,
+   * refreshed periodically from analytics rather than computed per request: `{ sevenDay, thirtyDay,
+   * updatedAt }`, each window being `{ score, label, scoredCount, positive, neutral, negative }`. The
+   * object is always present and fully populated, so it can be read without a presence check.
+   * `score` is a volume-weighted average in -100..100 and is null when nothing was scored in the
+   * window, which is not the same as a score of 0 -- null means nobody replied, 0 means replies
+   * averaged neutral. `updatedAt` is null until the first rollup writes the record, and it tracks when
+   * the figures last CHANGED, not when the job last ran.
    * @returns {Promise<Object>} A promise that resolves to the list of phone numbers
    */
   async getPhoneNumbers({ phoneNumber, campaignId, brandId, subgroupId, groupId, page, limit, options = {} }) {
@@ -254,6 +263,8 @@ export class Numbers {
    * @param {string} params.phoneNumber - The phone number to update
    * @param {Object} params.updateData - The data to update for the phone number
    * @param {string} [params.updateData.friendlyName] - An optional friendly name for the phone number
+   * @param {string|null} [params.updateData.primaryInboundWebhookUrl] - Primary inbound voice webhook URL (http/https). When set, inbound calls to this number are driven by the SHML your webhook returns (programmable call control). Pass null or an empty string to clear.
+   * @param {string|null} [params.updateData.secondaryInboundWebhookUrl] - Secondary inbound voice webhook URL (http/https), used for failover when the primary returns an error. Pass null or an empty string to clear.
    * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the phoneNumber or updateData parameter is missing
    * @returns {Promise<Object>} A promise that resolves to the updated phone number object
@@ -339,15 +350,18 @@ export class Numbers {
   }
 
   /**
-   * Assign phone numbers to a campaign by providing the campaign ID and a list of phone numbers to assign
+   * Assign phone numbers to a campaign by providing the campaign ID and a list of phone numbers to assign.
+   * Numbers that are not found, already RELEASED, already assigned to a different campaign, on a mismatched
+   * DCA, or (for a 10DLC campaign without a number pool) beyond the remaining 49-number-per-campaign limit
+   * are not queued - each is reported back individually in `skipped` instead of failing the whole request.
    * @async
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for assigning phone numbers to a campaign
    * @param {string} params.campaignId - The ID of the campaign to assign phone numbers to
    * @param {string[]} params.phoneNumbers - The list of phone numbers to assign to the campaign
    * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-   * @throws {Error} Throws an error if the campaignId or phoneNumbers parameter is missing
-   * @returns {Promise<Object>} A promise that resolves to the result of the assignment operation
+   * @throws {Error} Throws an error if the campaignId or phoneNumbers parameter is missing, if none of the phone numbers exist in the account, or if the campaign is not found or in a terminal state
+   * @returns {Promise<Object>} A promise that resolves to `{ Message, queued, skipped }` - `queued` numbers were sent for assignment; `skipped` numbers were rejected (not found, RELEASED, already assigned to a campaign, cross-DCA mismatch, or over the 49-number limit).
    */
   async assignPhoneNumberToCampaign({ campaignId, phoneNumbers, options = {} }) {
     this.client._require({ campaignId, phoneNumbers });

package/src/domains/Onboarding.js

@@ -38,12 +38,16 @@ export class Onboarding {
 	}
 
 	/**
-	 * Get the caller's own onboarding record (customer-safe projection).
-	 * Returns `{ acceptedTermsOfService: boolean, emailVerified: boolean }`.
+	 * Get the caller's own onboarding record (customer-safe projection) — the selections captured at
+	 * signup plus the gate flags derived from them. Never returns internal KYC, staff assignment,
+	 * referral, or external-reference data.
+	 *
+	 * Staff roles and sessions with no active group receive a synthetic verified, selection-free
+	 * record rather than an error, so callers never have to special-case them.
 	 * @async
 	 * @param {Object} [params] - Optional parameters
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} - `{ acceptedTermsOfService: boolean, emailVerified: boolean }`
+	 * @returns {Promise<Object>} - `{ acceptedTermsOfService: boolean, emailVerified: boolean, products: string[], estimatedVolume: string|null, pendingExternalLink: "ghl"|"shopify"|null }`
 	 */
 	async getMyOnboarding({ options = {} } = {}) {
 		return this.client(`/group/onboarding/my`, { method: "GET", ...options });

package/src/domains/Subgroups.js

@@ -60,6 +60,24 @@ export class Subgroups {
 		return this.client(`/subgroup${queryString}`, { method: "GET", ...options });
 	}
 
+	/**
+	 * Get resource counts grouped by subgroup ID. Only signalhouse_admin can query all groups;
+	 * every other allowed role is restricted to its JWT group scope.
+	 * @async
+	 * @roles signalhouse, api, admin, developer, billing, user
+	 * @param {Object} [params={}] - Optional count filters.
+	 * @param {string} [params.groupId] - Restrict results to a group.
+	 * @param {string} [params.subgroupId] - Restrict results to a subgroup.
+	 * @param {number} [params.limit] - Maximum rows to return.
+	 * @param {number} [params.offset] - Rows to skip; requires limit.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<Object>} - Subgroup-level resource count rows.
+	 */
+	async getSubgroupCounts({ groupId, subgroupId, limit, offset, options = {} } = {}) {
+		const queryString = this.client._getQueryString({ groupId, subgroupId, limit, offset });
+		return this.client(`/subgroup/counts${queryString}`, { method: "GET", ...options });
+	}
+
 	/**
 	 * Create a new subgroup with the specified subgroup data
 	 * @async

package/src/domains/Tickets.js

@@ -32,6 +32,20 @@ export class Tickets {
 					return this.client(`/admin/ticket/jira/epics${queryString}`, { method: "GET", ...options });
 				},
 
+				/**
+				 * Search open non-Epic, non-Subtask issues for the Subtask parent picker. Staff-only.
+				 * @async
+				 * @roles signalhouse
+				 * @param {Object} [params]
+				 * @param {string} [params.query] - Optional issue summary/key filter
+				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<Object>} - `{ issues: Array<{ id, key, summary }> }`
+				 */
+				searchJiraParentIssues: async ({ query, options = {} } = {}) => {
+					const queryString = this.client._getQueryString({ query });
+					return this.client(`/admin/ticket/jira/parent-issues${queryString}`, { method: "GET", ...options });
+				},
+
 				/**
 				 * Search assignable Jira users for the assignee picker. Staff-only.
 				 * @async

package/src/domains/voice/ProgrammableVoiceProfiles.js

@@ -3,11 +3,12 @@
  * @property {string} name - Profile name (required).
  * @property {string[]} subgroupIds - Subgroups this profile spans (required, at least one).
  * @property {string} [region] - Region/POP label.
- * @property {"FORWARD"|"WEBRTC"|"SIP_TRUNK"|"SIP_PROFILE"} [routeAction] - Inbound call action (default "FORWARD"). Deliver the call to a PSTN number (FORWARD), ring the profile's subgroup registered softphones (WEBRTC), send to a SIP trunk (SIP_TRUNK), or ring a registered SIP endpoint (SIP_PROFILE).
+ * @property {"FORWARD"|"WEBRTC"|"SIP_TRUNK"|"SIP_PROFILE"|"CALL_CONTROL"} [routeAction] - Inbound call action (default "FORWARD"). Deliver the call to a PSTN number (FORWARD), ring the profile's subgroup registered softphones (WEBRTC), send to a SIP trunk (SIP_TRUNK), ring a registered SIP endpoint (SIP_PROFILE), or hand the call to your programmable call-control webhook that returns SHML (CALL_CONTROL).
  * @property {string} [forwardToE164] - Destination number, required when routeAction is "FORWARD".
  * @property {number} [forwardAfterSeconds] - Ring seconds before the action fires.
  * @property {string} [routeSipTrunkId] - SIP trunk id, required when routeAction is "SIP_TRUNK".
  * @property {string} [routeSipProfileId] - SIP endpoint id, required when routeAction is "SIP_PROFILE".
+ * @property {string} [webhookUrl] - Your inbound voice webhook (SHML program URL), required when routeAction is "CALL_CONTROL". Inbound calls to this profile's numbers are driven by the SHML your webhook returns.
  * @property {boolean} [recordingEnabled] - Record calls on this profile.
  * @property {boolean} [enabled] - Active state (default true).
  */
@@ -17,11 +18,12 @@
  * @property {string} [name] - Profile name.
  * @property {string[]} [subgroupIds] - Subgroups this profile spans.
  * @property {string|null} [region] - Region/POP label.
- * @property {"FORWARD"|"WEBRTC"|"SIP_TRUNK"|"SIP_PROFILE"} [routeAction] - Inbound call action (FORWARD | WEBRTC | SIP_TRUNK | SIP_PROFILE).
+ * @property {"FORWARD"|"WEBRTC"|"SIP_TRUNK"|"SIP_PROFILE"|"CALL_CONTROL"} [routeAction] - Inbound call action (FORWARD | WEBRTC | SIP_TRUNK | SIP_PROFILE | CALL_CONTROL).
  * @property {string|null} [forwardToE164] - FORWARD destination.
  * @property {number|null} [forwardAfterSeconds] - Ring seconds before the action fires.
  * @property {string|null} [routeSipTrunkId] - SIP trunk id (required when routeAction is "SIP_TRUNK").
  * @property {string|null} [routeSipProfileId] - SIP endpoint id (required when routeAction is "SIP_PROFILE").
+ * @property {string|null} [webhookUrl] - Inbound voice webhook / SHML program URL (required when routeAction is "CALL_CONTROL"). Pass null to clear.
  * @property {boolean} [recordingEnabled] - Record calls on this profile.
  * @property {boolean} [enabled] - Active state.
  */

package/src/domains/voice/Tokens.js

@@ -61,4 +61,30 @@ export class Tokens {
 	async create({ tokenData = {}, options = {} } = {}) {
 		return this.client(`/voice/tokens`, { method: "POST", body: tokenData, ...options });
 	}
+
+	/**
+	 * Refresh (extend) an existing voice token in place — identity-preserving.
+	 * Wraps voice-backend's `/voice/tokens/refresh`. Keeps the same wrtc_
+	 * identity + SIP credentials and only pushes out `expires_at`, so a
+	 * long-lived softphone stays registered without re-establishing its SIP
+	 * registration (unlike `create()`, which mints a NEW identity). Provide the
+	 * current `token` (its identity is decoded server-side) or the `identity`
+	 * directly. Rejects with a 404 when the token no longer exists for the
+	 * account — mint a fresh one with `create()` in that case.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} [params] - Request parameters.
+	 * @param {string} [params.token] - The current voice token (JWT) whose identity to extend.
+	 * @param {string} [params.identity] - The wrtc_ identity to extend, if held directly (from a prior mint/refresh response).
+	 * @param {number} [params.ttl] - New TTL in seconds. Defaults to the server default, capped at the server maximum.
+	 * @param {import('../../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<CreateTokenResponse>} The refreshed token + embedded SIP credentials (same shape as create()).
+	 */
+	async refresh({ token, identity, ttl, options = {} } = {}) {
+		const body = {};
+		if (token) body.token = token;
+		if (identity) body.identity = identity;
+		if (ttl != null) body.ttl = ttl;
+		return this.client(`/voice/tokens/refresh`, { method: "POST", body, ...options });
+	}
 }