@signalhousellc/sdk 1.0.65 → 1.0.67

package/src/domains/Campaigns.js

@@ -2,7 +2,7 @@
  * @typedef {Object} CreateCampaignData
  * @property {string} brandId - The ID of the brand associated with the campaign (required)
  * @property {string} usecase - The use case for the campaign (2FA, ACCOUNT_NOTIFICATION, AGENTS_FRANCHISES, CARRIER_EXEMPT, CHARITY, CUSTOMER_CARE, DELIVERY_NOTIFICATION, EMERGENCY, FRAUD_ALERT, HIGHER_EDUCATION, K12_EDUCATION, LOW_VOLUME, M2M, MARKETING, MIXED, POLITICAL, POLLING_VOTING, PROXY, PUBLIC_SAFETY_RESTRICTED, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT, SOCIAL, SOLE_PROPRIETOR, SWEEPSTAKE, TRIAL, UCAAS_HIGH, UCAAS_LOW)
- * @property {Array<string>} [subUsecases] - An array of sub-use cases for the campaign (2FA, ACCOUNT_NOTIFICATION, AGENTS_FRANCHISES, CARRIER_EXEMPT, CHARITY, CUSTOMER_CARE, DELIVERY_NOTIFICATION, EMERGENCY, FRAUD_ALERT, HIGHER_EDUCATION, K12_EDUCATION, LOW_VOLUME, M2M, MARKETING, MIXED, POLITICAL, POLLING_VOTING, PROXY, PUBLIC_SAFETY_RESTRICTED, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT, SOCIAL, SOLE_PROPRIETOR, SWEEPSTAKE, TRIAL, UCAAS_HIGH, UCAAS_LOW)
+ * @property {Array<string>} [subUsecases] - An array of sub-use cases for the campaign (2FA, ACCOUNT_NOTIFICATION, AGENTS_FRANCHISES, CARRIER_EXEMPT, CHARITY, CUSTOMER_CARE, DELIVERY_NOTIFICATION, EMERGENCY, FRAUD_ALERT, HIGHER_EDUCATION, K12_EDUCATION, LOW_VOLUME, M2M, MARKETING, MIXED, POLITICAL, POLLING_VOTING, PROXY, PUBLIC_SAFETY_RESTRICTED, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT, SOLE_PROPRIETOR, SWEEPSTAKE, TRIAL, UCAAS_HIGH, UCAAS_LOW — NOT SOCIAL, which TCR rejects as a sub-usecase for every parent usecase even though it is valid as the top-level `usecase`)
  * @property {string} description - A detailed description of the campaign (required, must be between 40 and 4096 characters)
  * @property {boolean} [embeddedLink=true] - Whether the campaign includes an embedded link (optional, defaults to true)
  * @property {boolean} [embeddedPhone=false] - Whether the campaign includes an embedded phone number (optional, defaults to false)
@@ -36,7 +36,7 @@
 /**
  * @typedef {Object} UpdateCampaignData
  * @property {string} [usecase] - The use case for the campaign (2FA, ACCOUNT_NOTIFICATION, AGENTS_FRANCHISES, CARRIER_EXEMPT, CHARITY, CUSTOMER_CARE, DELIVERY_NOTIFICATION, EMERGENCY, FRAUD_ALERT, HIGHER_EDUCATION, K12_EDUCATION, LOW_VOLUME, M2M, MARKETING, MIXED, POLITICAL, POLLING_VOTING, PROXY, PUBLIC_SAFETY_RESTRICTED, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT, SOCIAL, SOLE_PROPRIETOR, SWEEPSTAKE, TRIAL, UCAAS_HIGH, UCAAS_LOW)
- * @property {Array<string>} [subUsecases] - An array of sub-use cases for the campaign (2FA, ACCOUNT_NOTIFICATION, AGENTS_FRANCHISES, CARRIER_EXEMPT, CHARITY, CUSTOMER_CARE, DELIVERY_NOTIFICATION, EMERGENCY, FRAUD_ALERT, HIGHER_EDUCATION, K12_EDUCATION, LOW_VOLUME, M2M, MARKETING, MIXED, POLITICAL, POLLING_VOTING, PROXY, PUBLIC_SAFETY_RESTRICTED, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT, SOCIAL, SOLE_PROPRIETOR, SWEEPSTAKE, TRIAL, UCAAS_HIGH, UCAAS_LOW)
+ * @property {Array<string>} [subUsecases] - An array of sub-use cases for the campaign (2FA, ACCOUNT_NOTIFICATION, AGENTS_FRANCHISES, CARRIER_EXEMPT, CHARITY, CUSTOMER_CARE, DELIVERY_NOTIFICATION, EMERGENCY, FRAUD_ALERT, HIGHER_EDUCATION, K12_EDUCATION, LOW_VOLUME, M2M, MARKETING, MIXED, POLITICAL, POLLING_VOTING, PROXY, PUBLIC_SAFETY_RESTRICTED, PUBLIC_SERVICE_ANNOUNCEMENT, SECURITY_ALERT, SOLE_PROPRIETOR, SWEEPSTAKE, TRIAL, UCAAS_HIGH, UCAAS_LOW — NOT SOCIAL, which TCR rejects as a sub-usecase for every parent usecase even though it is valid as the top-level `usecase`)
  * @property {string} [description] - A detailed description of the campaign (optional, must be between 40 and 4096 characters if provided)
  * @property {boolean} [embeddedLink] - Whether the campaign includes an embedded link (optional)
  * @property {boolean} [embeddedPhone] - Whether the campaign includes an embedded phone number (optional)
@@ -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.
  */
 
 /**
@@ -112,7 +115,8 @@
  * @property {string} [doubleOptInMessage] - Required when adultContent is true (20-1024 characters)
  * @property {string} programSummary - Generated-but-editable campaign/program summary (required, 40-2048 characters)
  * @property {string} optInConfirmationMessage - The opt-in confirmation message (required, 20-1024 characters)
- * @property {string} [optInUrl] - Public HTTPS URL for the live opt-in experience. When omitted, Signal House uses the brand's optInLink before capturing its screenshot asynchronously, retrying up to three times.
+ * @property {string} optInUrl - Public HTTPS URL for the live opt-in experience, shown to reviewers as a link (required; private, local, and credentialed URLs are rejected)
+ * @property {string} screenshotUrl - Hosted opt-in proof screenshot URL returned by `uploadOptInImage` (required). Must be a Signal House-hosted opt-in image owned by your group; external URLs are rejected
  */
 
 /**
@@ -126,7 +130,6 @@
  * @property {string} sample1 - Sample message 1 (required, 20-1024 characters)
  * @property {string} sample2 - Sample message 2 (required, 20-1024 characters)
  * @property {string} sample3 - Sample message 3 (required, 20-1024 characters)
- * @property {boolean} [autoRenewal=true] - Whether the campaign should auto-renew (optional, defaults to true)
  * @property {string} [tag] - A tag for the campaign (optional, at most 255 characters)
  * @property {ShortCodeDetails} shortCode - The Short Code campaign details (required)
  */
@@ -183,13 +186,14 @@ export class Campaigns {
         /**
          * Transition a Short Code campaign's review status (SHGHL-2225). A customer-visible reason is
          * required for both rejection states ("REJECTED" = Signal House Rejected, "DCA_REJECTED" =
-         * Rejected). Fulfillment and carrier submission are separate staff operations.
+         * Rejected). Selecting "PENDING_DCA_APPROVAL" runs the guarded carrier-review transition;
+         * fulfillment remains a separate staff operation.
          * @async
          * @roles signalhouse
          * @param {Object} params - The parameters for the status transition
          * @param {string} params.campaignId - The ID of the campaign to transition
-         * @param {string} params.status - The target status: "PENDING_REVIEW", "REJECTED", "PENDING_CREATION", "DCA_REJECTED", or "ACTIVE". Use submitShortCodeCampaignToCarrier for "PENDING_DCA_APPROVAL".
-         * @param {string} [params.rejectionReason] - Required for "REJECTED"/"DCA_REJECTED" (10-1024 characters)
+         * @param {string} params.status - The target status: "PENDING_REVIEW", "REJECTED", "PENDING_DCA_APPROVAL", "DCA_REJECTED", or "ACTIVE". "PENDING_DCA_APPROVAL" requires a Signal House-approved Short Code brand, issued code, and captured opt-in proof.
+         * @param {string} [params.rejectionReason] - Required, nonblank reason for "REJECTED"/"DCA_REJECTED" (max 1024 characters)
          * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
          * @throws {Error} Throws an error if the campaignId or status parameter is missing
          * @returns {Promise<Object>} The updated campaign
@@ -210,16 +214,17 @@ export class Campaigns {
          * @param {Object} params - Fulfillment parameters.
          * @param {string} params.campaignId - Campaign identifier.
          * @param {string} params.actualCode - Issued five- or six-digit Short Code.
+         * @param {string} params.leaseEndDate - Fixed future lease end date. A YYYY-MM-DD value expires at 23:59:59 UTC; timestamps retain their supplied time.
          * @param {string} [params.internalNotes] - Staff-only fulfillment notes.
          * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options.
          * @returns {Promise<Object>} The updated campaign.
          */
-        fulfillShortCodeCampaign: async ({ campaignId, actualCode, internalNotes, options = {} }) => {
-          this.client._require({ campaignId, actualCode });
+        fulfillShortCodeCampaign: async ({ campaignId, actualCode, leaseEndDate, internalNotes, options = {} }) => {
+          this.client._require({ campaignId, actualCode, leaseEndDate });
           const safeCampaignId = encodeURIComponent(campaignId);
           return this.client(`/campaign/short-code/${safeCampaignId}/fulfill`, {
             method: 'POST',
-            body: { actualCode, internalNotes },
+            body: { actualCode, leaseEndDate, internalNotes },
             ...options,
           });
         },
@@ -240,6 +245,39 @@ export class Campaigns {
             ...options,
           });
         },
+        /** Confirm Registry offboarding and complete a pending Short Code cancellation. */
+        completeShortCodeCancellation: async ({ campaignId, requestId, note, options = {} }) => {
+          this.client._require({ campaignId, requestId });
+          const safeCampaignId = encodeURIComponent(campaignId);
+          return this.client(`/campaign/short-code/${safeCampaignId}/cancellation/complete`, {
+            method: 'POST',
+            body: { requestId, note },
+            ...options,
+          });
+        },
+        /** Dismiss a pending Short Code cancellation and restore its prior lifecycle state. */
+        dismissShortCodeCancellation: async ({ campaignId, requestId, note, options = {} }) => {
+          this.client._require({ campaignId, requestId });
+          const safeCampaignId = encodeURIComponent(campaignId);
+          return this.client(`/campaign/short-code/${safeCampaignId}/cancellation/dismiss`, {
+            method: 'POST',
+            body: { requestId, note },
+            ...options,
+          });
+        },
+        /** Read expired Short Code leases awaiting manual Registry offboarding. */
+        getExpiredShortCodeLeases: async ({ page, limit, options = {} } = {}) => {
+          const query = this.client._getQueryString({ page, limit });
+          return this.client(`/campaign/short-code/expired-leases${query}`, { method: 'GET', ...options });
+        },
+        /** Confirm Registry offboarding and mark an expired Short Code released. */
+        releaseExpiredShortCodeLease: async ({ campaignId, note, options = {} }) => {
+          this.client._require({ campaignId });
+          const safeCampaignId = encodeURIComponent(campaignId);
+          return this.client(`/campaign/short-code/${safeCampaignId}/expired-lease/release`, {
+            method: 'POST', body: { note }, ...options,
+          });
+        },
       };
     }
   }
@@ -261,6 +299,23 @@ 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.
+   *
+   * Every record also carries a `health` object -- trailing 7-day and 30-day delivery/opt-out health from
+   * the same periodic refresh: `{ sevenDay, thirtyDay, updatedAt }`, each window being `{ score,
+   * deliveryRate, optOutRate, deliveryScore, optOutScore, messagesSent, messagesDelivered, messagesFailed,
+   * optOuts }`. `score` is 1.0..10.0 (the mean of the two bucket scores) and is null when nothing was sent
+   * in the window; the volumes say how much traffic sits behind it. A campaign's figure is scored from the
+   * campaign's own summed counters, never averaged from its numbers. For a live figure use GET /number/health
+   * or GET /campaign/health.
    * @returns {Promise<Array|Object>} The response from the server - array when unpaginated, or { data, total, page, limit, totalPages } when paginated
    */
   async getCampaigns({
@@ -342,9 +397,9 @@ export class Campaigns {
 
   /**
    * Create a new Short Code campaign and submit it for Signal House review (SHGHL-2225). Requires an
-   * approved (VERIFIED) Short Code brand. `campaignData.shortCode.optInUrl` is optional; Signal House
-  * uses the brand's `optInLink` when it is omitted, then captures its screenshot asynchronously, retrying up to three times. Request or register the
-  * campaign's Short Code separately through `numbers.requestShortCodeAcquisition` after creation.
+   * approved (VERIFIED) Short Code brand. Upload the opt-in proof screenshot first with `uploadOptInImage`
+   * and pass the returned URL as `campaignData.shortCode.screenshotUrl` (required). Request or register the
+   * campaign's Short Code separately through `numbers.requestShortCodeAcquisition` after creation.
    * @async
    * @roles api, admin, developer, user
    * @param {Object} params - The parameters for creating the Short Code campaign
@@ -367,7 +422,7 @@ export class Campaigns {
    * @roles api, admin, developer, user
    * @param {Object} params - The parameters for updating the Short Code campaign
    * @param {string} params.campaignId - The ID of the campaign to update
-   * @param {Object} params.updateData - The fields to update (top-level campaign fields plus an optional `shortCode` object of editable Short Code fields)
+   * @param {Object} params.updateData - The fields to update (top-level campaign fields plus an optional `shortCode` object of editable Short Code fields; pass a new `uploadOptInImage` URL as `shortCode.screenshotUrl` to replace the opt-in proof)
    * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the campaignId parameter is missing
    * @returns {Promise<Object>} The updated campaign
@@ -379,10 +434,9 @@ export class Campaigns {
   }
 
   /**
-   * Cancel a Short Code campaign (SHGHL-2225). Customers may cancel only while the campaign is in Signal
-   * House Review or Signal House Rejected status; Signal House staff may cancel from any non-terminal
-   * status. Persists as "EXPIRED" (displayed as "Cancelled"). A real Registry lease (external or an
-   * already-fulfilled Signal House request) is never auto-released — see SHGHL-2228 for offboarding.
+  * Cancel a Short Code campaign. A customer cancellation for an issued Short Code returns
+  * PENDING_DELETE (displayed as Cancellation Pending) until Signal House confirms Registry offboarding.
+  * Unissued RANDOM/VANITY requests, plus staff-confirmed cancellations, return EXPIRED immediately.
    * @async
    * @roles api, admin, developer, user
    * @param {Object} params - The parameters for cancelling the campaign
@@ -418,7 +472,7 @@ export class Campaigns {
 
   /**
    * Upload an opt-in proof image to be hosted on-platform, returning a publicly-fetchable URL suitable for a
-   * Toll-Free campaign's optInImageURLs
+   * Toll-Free campaign's optInImageURLs or a Short Code campaign's shortCode.screenshotUrl
    * @async
    * @roles api, admin, developer, user
    * @param {Object} params - The parameters for uploading the opt-in image
@@ -441,13 +495,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/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

@@ -5,6 +5,16 @@ export class Messages {
 		this.enableAdmin = enableAdmin;
 	}
 
+	/**
+	 * Estimate Canadian SMS/MMS retail cost without sending or charging.
+	 * @async
+	 * @param {Object} params - Sender, up to 100 recipients, messageBody and request options.
+	 * @returns {Promise<Object>} - Per-recipient rates and total in microdollars; unknown carriers use the upper fallback.
+	 */
+	async estimateMessage({ senderPhoneNumber, recipientPhoneNumbers, messageBody, messageType = "SMS", options = {} }) {
+		return this.client("/message/estimate", { method: "POST", body: { senderPhoneNumber, recipientPhoneNumbers, messageBody, messageType }, ...options });
+	}
+
 	/**
 	 * Get a list of messages with optional filters and pagination parameters
 	 * @async
@@ -18,19 +28,22 @@ 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, 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 {string|string[]} [params.channel] - Filter messages by channel. Accepts a single value or an array. Allowed values: tenDLC, virtualLongCode, 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 +60,7 @@ export class Messages {
 		channel,
 		matchAny,
 		carrier,
+		sentimentLabel,
 		startDate,
 		endDate,
 		sortField,
@@ -55,7 +69,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 +100,29 @@ 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|string[]} [params.carrierFamily] - Filter analytics by the recipient's resolved carrier family (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P). Accepts a single value, an array, or a comma-separated string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
 	 * @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, 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 {(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, virtualLongCode, 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, carrierFamily, startDate, endDate, channel, messageType, matchAny, options = {} }) {
+		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, carrierFamily, startDate, endDate, channel, messageType, matchAny };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/message/analytics${queryString}`, { method: "GET", ...options });
 	}
@@ -110,19 +133,29 @@ 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} [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, 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 {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|string[]} [params.carrierFamily] - Filter analytics by the recipient's resolved carrier family (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P). Accepts a single value, an array, or a comma-separated string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
+	 * @param {string} [params.startDate] - ISO-8601 date or timestamp. At day granularity it is normalized to start-of-UTC-day (inclusive); at hour granularity it is floored to its hour.
+	 * @param {string} [params.endDate] - ISO-8601 date or timestamp. At day granularity it is normalized to end-of-UTC-day (inclusive); at hour granularity it is honoured as given.
+	 * @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, virtualLongCode, 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 {("day"|"hour")} [params.granularity] - Time-bucket grain of the byDate rows. Omit for day (each row's _id is a "YYYY-MM-DD" date). "hour" buckets by hour (each row's _id is a "YYYY-MM-DD HH:MM:SS" UTC hour) and is capped to a 7-day span. Only accepted where the environment serves hourly analytics; elsewhere any value, including "day", is rejected with a 400 -- omit the parameter unless hour grain is wanted.
+	 * @param {("carrier"|"carrierFamily")} [params.breakdown] - Adds a byBreakdown time × dimension series to the response ({ dimension, rows }: each row is one byDate bucket (_id) for one carrier or carrier family (key), over the top 50 keys by volume, 10DLC only) and caps the span at 31 days. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
 	 * @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, carrierFamily, startDate, endDate, channel, messageType, granularity, breakdown, options = {} }) {
+		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, carrierFamily, startDate, endDate, channel, messageType, granularity, breakdown };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/message/analytics/detail${queryString}`, { method: "GET", ...options });
 	}
@@ -155,16 +188,19 @@ export class Messages {
 	 * @param {string|string[]} [params.campaignId]
 	 * @param {string|string[]} [params.phoneNumber]
 	 * @param {string|string[]} [params.carrier]
+	 * @param {string|string[]} [params.carrierFamily] - Resolved carrier family of the recipient (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P); single value, array, or comma-separated. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
 	 * @param {string} [params.startDate]
 	 * @param {string} [params.endDate]
 	 * @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 {("tenDLC"|"virtualLongCode"|"tollFree"|"shortCode"|"p2p"|"both")|Array<"tenDLC"|"virtualLongCode"|"tollFree"|"shortCode"|"p2p">} [params.channel="both"] - Filter and rank rows by the stored channel column. "both" (default) means all activity. tenDLC/virtualLongCode/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, carrierFamily, startDate, endDate, page, limit, channel, messageType, options = {} }) {
+		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, carrierFamily, startDate, endDate, page, limit, channel, messageType };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/message/analytics/by-subgroup${queryString}`, { method: "GET", ...options });
 	}
@@ -181,16 +217,17 @@ export class Messages {
 	 * @param {string|string[]} [params.campaignId]
 	 * @param {string|string[]} [params.phoneNumber]
 	 * @param {string|string[]} [params.carrier]
+	 * @param {string|string[]} [params.carrierFamily] - Resolved carrier family of the recipient (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P); single value, array, or comma-separated. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
 	 * @param {string} [params.startDate]
 	 * @param {string} [params.endDate]
 	 * @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 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 {("tenDLC"|"virtualLongCode"|"tollFree"|"shortCode"|"p2p"|"both")|Array<"tenDLC"|"virtualLongCode"|"tollFree"|"shortCode"|"p2p">} [params.channel="both"] - Filter and rank rows by the stored channel column. "both" (default) means every code. tenDLC/virtualLongCode/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 }
 	 */
-	async getAnalyticsByErrorCode({ 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 getAnalyticsByErrorCode({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, carrierFamily, startDate, endDate, page, limit, channel, options = {} }) {
+		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, carrierFamily, startDate, endDate, page, limit, channel };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/message/analytics/by-error-code${queryString}`, { method: "GET", ...options });
 	}
@@ -208,9 +245,9 @@ 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, 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 {string|string[]} [params.channel] - Filter by channel (tenDLC, virtualLongCode, 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)
+	 * @returns {Promise<Object>} - A promise that resolves to the DNC analytics data (totals, byDate, byPhoneNumber, byCarrier, byKeyword). byKeyword breaks opt-outs down by the normalized keyword that revoked consent ({ optOutKeyword, total, sms, mms }); opt-outs recorded before keyword capture shipped appear as a single optOutKeyword: null bucket ("not recorded"). The distinct keyword set is open-ended (campaigns register their own keywords beyond the mandatory floor) — render top-N plus Other, never a fixed list.
 	 */
 	async getDncAnalytics({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel, options = {} }) {
 		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel };
@@ -235,9 +272,9 @@ 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, 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 {string|string[]} [params.channel] - Filter by channel (tenDLC, virtualLongCode, 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
+	 * @returns {Promise<Object>} - A promise that resolves to the paginated DNC records. Each record carries optOutKeyword — the normalized keyword that revoked consent (e.g. "stop", "opt out"; a repeat opt-out records the most recent word), null for opt-outs recorded before keyword capture shipped — and carrierFamily, the resolved carrier family of the recipient number (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile), copied from the inbound message that triggered the opt-out.
 	 */
 	async getDncRecords({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, page, limit, sortField, sortOrder, channel, options = {} }) {
 		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, page, limit, sortField, sortOrder, channel };
@@ -261,7 +298,7 @@ export class Messages {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for sending an SMS message
 	 * @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|string[]} params.recipientPhoneNumbers - The 10+ digit phone number(s) to send the message to. A Short Code sender permits exactly one recipient, and it must be a +1 (US/Canada) number; a bare 10-digit number is treated as +1. The API rejects Short Code sends with multiple recipients or a non-+1 recipient.
 	 * @param {string} params.messageBody - The body of the SMS message
 	 * @param {string} [params.statusCallbackUrl] - The URL to receive status callbacks
 	 * @param {boolean} [params.enableShortlink=false] - Whether to enable shortlink in the message
@@ -342,7 +379,7 @@ export class Messages {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for sending an MMS message
 	 * @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.recipientPhoneNumbers - The 10+ digit phone number(s) to send the message to. A Short Code sender permits exactly one recipient, and it must be a +1 (US/Canada) number; a bare 10-digit number is treated as +1. The API rejects Short Code sends with multiple recipients or a non-+1 recipient.
 	 * @param {string} params.messageBody - The body of the MMS message
 	 * @param {string[]} [params.mediaUrls] - The URLs of the media attachments
 	 * @param {string} [params.statusCallbackUrl] - The URL to receive status callbacks