@signalhousellc/sdk 1.4.2 → 1.5.0

package/package.json

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

package/src/SignalHouseSDK.js

@@ -32,6 +32,7 @@ import { Campaigns } from "./domains/Campaigns.js";
 import { Groups } from "./domains/Groups.js";
 import { Landings } from "./domains/Landings.js";
 import { Messages } from "./domains/Messages.js";
+import { Templates } from "./domains/Templates.js";
 import { Numbers } from "./domains/Numbers.js";
 import { Registrations } from "./domains/Registrations.js";
 import { Onboarding } from "./domains/Onboarding.js";
@@ -78,6 +79,7 @@ export class SignalHouseSDK {
 		this.groups = new Groups(client, this.enableAdmin);
 		this.landings = new Landings(client, multipartClient, this.enableAdmin);
 		this.messages = new Messages(client, multipartClient, this.enableAdmin);
+		this.templates = new Templates(client, multipartClient, this.enableAdmin);
 		this.numbers = new Numbers(client, multipartClient, this.enableAdmin);
 		this.registrations = new Registrations(client, this.enableAdmin);
 		this.onboarding = new Onboarding(client, this.enableAdmin);

package/src/domains/Brands.js

@@ -80,6 +80,29 @@
  * @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)
  */
 
+/**
+ * @typedef {Object} BusinessVerificationDetails
+ * @property {string} businessName - The legal business name (required, at most 255 characters)
+ * @property {string} businessType - The business type (required, one of CO_OPERATIVE, CORPORATION, LIMITED_LIABILITY_CORPORATION, NON_PROFIT_CORPORATION, PARTNERSHIP)
+ * @property {string} industry - The business industry (required, one of AGRICULTURE, AUTOMOTIVE, BANKING, CONSTRUCTION, CONSUMER, EDUCATION, ELECTRONICS, ENGINEERING, ENERGY, FAST_MOVING_CONSUMER_GOODS, FINANCIAL, FINTECH, FOOD_AND_BEVERAGE, GOVERNMENT, HEALTHCARE, HOSPITALITY, INSURANCE, JEWELRY, LEGAL, MANUFACTURING, MEDIA, NOT_FOR_PROFIT, OIL_AND_GAS, ONLINE, PROFESSIONAL_SERVICES, RAW_MATERIALS, REAL_ESTATE, RELIGION, RETAIL, TECHNOLOGY, TELECOMMUNICATIONS, TRANSPORTATION, TRAVEL)
+ * @property {string} registrationType - The business registration type (required, one of EIN, CBN, NEQ, PROVINCIAL_NUMBER, CRN, VAT, ACN, ABN, BRN, SIREN, SIRET, NZBN, UST_IDNR, CIF, NIF, CNPJ, UID, OTHER)
+ * @property {string} registrationNumber - The business registration number, e.g. the EIN (required, at most 50 characters)
+ * @property {string} website - The business website (required, valid URL, at most 255 characters)
+ * @property {string} street - The business street address (required, at most 255 characters)
+ * @property {string} [street2] - The second line of the street address (optional, at most 255 characters)
+ * @property {string} city - The business city (required, at most 100 characters)
+ * @property {string} state - The business state or province (required, 2-letter code)
+ * @property {string} postalCode - The business postal code (required, at most 10 characters)
+ * @property {string} country - The business country (required, "US" or "CA")
+ * @property {Object} representative - The business's authorized representative (required)
+ * @property {string} representative.firstName - The representative's first name (required, at most 100 characters)
+ * @property {string} representative.lastName - The representative's last name (required, at most 100 characters)
+ * @property {string} representative.email - The representative's email address (required, valid email, at most 100 characters)
+ * @property {string} representative.phone - The representative's phone number (required, E.164 with an optional leading "+" and no spaces, parentheses or hyphens, e.g. "+17025550100")
+ * @property {string} representative.jobTitle - The representative's job title (required, at most 100 characters)
+ * @property {string} representative.jobLevel - The representative's job level (required, one of DIRECTOR, GM, VP, CEO, CFO, GENERAL_COUNSEL, OTHER)
+ */
+
 /**
  * @typedef {Object} CreateTollFreeBrandData
  * @property {string} subgroupId - The ID of the subgroup to create the brand under (required, exactly 8 characters)
@@ -140,6 +163,7 @@ export class Brands {
    * @param {number} [params.limit] - The number of items per page
    * @param {string} [params.status] - The status of the brand to filter by (PENDING_CREATION, PENDING_APPROVAL, UNVERIFIED, VERIFIED, VETTED_VERIFIED, PENDING_DELETE, DELETED)
    * @param {string} [params.registrationType] - Filter by registration type ("TEN_DLC", "TOLL_FREE", or "SHORT_CODE")
+   * @param {boolean} [params.currentTollFreeCarrier] - With subgroupId or groupId: when true, return only toll-free brands that a new toll-free campaign in that group can use (those on the group's current toll-free carrier)
    * @param {string} [params.search] - Staff-only (no id/subgroupId/groupId): case-insensitive substring over brandId, names, EIN, email, group, subgroup and reference ID
    * @param {string} [params.sortBy] - Staff-only: createdAt, brandId, displayName, groupId, subgroupId, status, entityType or country
    * @param {"asc"|"desc"} [params.sortOrder] - Staff-only: sort direction (default asc)
@@ -153,7 +177,7 @@ export class Brands {
    * @param {boolean} [params.excludeDeleted] - Staff-only: hide DELETED brands when no status is given
    * @param {boolean} [params.includeTotal] - Staff-only: with page and limit, return `{ data, total, page, limit, totalPages }` instead of the array
    * @param {RequestOptions} [params.options] - Additional options for the request
-   * @returns {Promise<SdkResponse<Array<{ _id: string, brandId: string|null, status: string, registrationType: string, [key: string]: any }>|{ data: Array<Object>, total: number, page: number, limit: number, totalPages: number }>>} Brand records. For 10DLC brands in PENDING_CREATION (or rejected before carrier assignment), brandId is null — poll by _id until status advances and brandId is assigned. The staff-only list (no id/subgroupId/groupId) returns the `{ data, total, page, limit, totalPages }` envelope only when includeTotal is sent with page and limit.
+   * @returns {Promise<SdkResponse<Array<{ _id: string, brandId: string|null, status: string, registrationType: string, tollFree?: { isBrandReady?: boolean, maxNumbersPerCampaign?: number, maxOptInMethods?: number, requiresPrivacyPolicy?: boolean, requiresTermsAndConditions?: boolean, maxAppealReasonLength?: number, labelsSamples?: boolean, supportsMms?: boolean, usesBusinessVerification?: boolean, [key: string]: any }, [key: string]: any }>|{ data: Array<Object>, total: number, page: number, limit: number, totalPages: number }>>} Brand records. For 10DLC brands in PENDING_CREATION (or rejected before carrier assignment), brandId is null — poll by _id until status advances and brandId is assigned. Toll-free brands carry `tollFree.isBrandReady` (whether the brand can host campaigns), `tollFree.maxNumbersPerCampaign` (the most numbers one of its campaigns can hold), `tollFree.maxOptInMethods` (the most opt-in methods one of its campaigns can declare), `tollFree.requiresPrivacyPolicy` (whether its campaigns need a privacy policy URL), `tollFree.requiresTermsAndConditions` (whether its campaigns need a terms and conditions URL), `tollFree.maxAppealReasonLength` (the longest appeal reason its campaigns may give), `tollFree.labelsSamples` (whether its campaigns' sample messages each start with their use case's name), `tollFree.supportsMms` (whether its numbers can send MMS and group messages) and `tollFree.usesBusinessVerification` (whether it waits on the group's business verification). The staff-only list (no id/subgroupId/groupId) returns the `{ data, total, page, limit, totalPages }` envelope only when includeTotal is sent with page and limit.
    */
   async getBrands({
     id,
@@ -163,6 +187,7 @@ export class Brands {
     limit,
     status,
     registrationType,
+    currentTollFreeCarrier,
     search,
     sortBy,
     sortOrder,
@@ -185,6 +210,7 @@ export class Brands {
       limit,
       status,
       registrationType,
+      currentTollFreeCarrier,
       search,
       sortBy,
       sortOrder,
@@ -248,6 +274,38 @@ export class Brands {
     return this.client(`/brand/toll-free`, { method: 'POST', body: brandData, ...options });
   }
 
+  /**
+   * Get a group's business verification: whether its toll-free brands need one, its status and the submitted details.
+   * @async
+   * @roles api, admin, developer, billing, user
+   * @param {Object} params - The parameters for getting the business verification
+   * @param {string} params.groupId - The ID of the group whose business verification to get
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @throws {Error} Throws an error if the groupId parameter is missing
+   * @returns {Promise<SdkResponse<{ groupId: string, required: boolean, status: string, details: BusinessVerificationDetails|null, submittedAt: string|null, reviewedAt: string|null, rejectionReason: string|null }>>} The group's business verification. `required` says whether the group's new toll-free brands need one; `status` is NOT_STARTED, SUBMITTING, IN_REVIEW, VERIFIED or NEEDS_CHANGES; `rejectionReason` says why it needs changes, or is null. When `required` is true and `status` is NOT_STARTED, submit it before creating the group's first toll-free brand.
+   */
+  async getBusinessVerification({ groupId, options = {} }) {
+    this.client._require({ groupId });
+    return this.client(`/brand/business-verification/${encodeURIComponent(groupId)}`, { method: 'GET', ...options });
+  }
+
+  /**
+   * Submit or update a group's business verification. Allowed when it is not started or needs changes. Review usually
+   * takes 1–2 business days; the group's toll-free brands stay pending until it is verified.
+   * @async
+   * @roles api, admin, developer, billing, user
+   * @param {Object} params - The parameters for submitting the business verification
+   * @param {string} params.groupId - The ID of the group whose business verification to submit (must be the caller's active group)
+   * @param {BusinessVerificationDetails} params.details - The business verification details (see BusinessVerificationDetails typedef for details)
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @throws {Error} Throws an error if the groupId or details parameter is missing
+   * @returns {Promise<SdkResponse<{ groupId: string, required: boolean, status: string, details: BusinessVerificationDetails|null, submittedAt: string|null, reviewedAt: string|null, rejectionReason: string|null }>>} A 202 with the group's business verification, now SUBMITTING (the same shape as getBusinessVerification).
+   */
+  async submitBusinessVerification({ groupId, details, options = {} }) {
+    this.client._require({ groupId, details });
+    return this.client(`/brand/business-verification/${encodeURIComponent(groupId)}`, { method: 'PUT', body: details, ...options });
+  }
+
   /**
    * Create a local Short Code brand for manual Signal House review.
    * @async

package/src/domains/Campaigns.js

@@ -96,7 +96,7 @@
  * @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[]} [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. Carriers that need specific use cases rather than MIXED take them from here when present; other carriers never receive them.
  * @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.
  */
@@ -105,11 +105,11 @@
  * @typedef {Object} CreateTollFreeCampaignData
  * @property {string} brandId - The ID of the Toll-Free brand associated with the campaign (required, at least 7 characters)
  * @property {TollFreeCampaignDetails} tollFree - The Toll-Free campaign details (required)
- * @property {string} [privacyPolicyLink] - A URL linking to the privacy policy (optional, at most 2048 characters)
- * @property {string} [termsAndConditionsLink] - A URL linking to the terms and conditions (optional, at most 2048 characters)
+ * @property {string} [privacyPolicyLink] - A URL linking to the privacy policy (at most 2048 characters). Required when the brand's `tollFree.requiresPrivacyPolicy` is true and the brand has no `privacyPolicyLink` of its own; optional otherwise.
+ * @property {string} [termsAndConditionsLink] - A URL linking to the terms and conditions (at most 2048 characters). Required when the brand's `tollFree.requiresTermsAndConditions` is true and the brand has no `termsAndConditionsLink` of its own; optional otherwise.
  * @property {string} [tag] - A tag for the campaign (optional, at most 255 characters)
  * @property {boolean} [autoRenewal=true] - Whether the campaign should auto-renew (optional, defaults to true)
- * @property {Array<string>} phoneNumbers - The Toll-Free numbers to assign to the campaign (required, at least 1 and at most 5, each at least 10 digits and digits only). Numbers are locked to the campaign once assigned and cannot be moved or added afterward.
+ * @property {Array<string>} phoneNumbers - The Toll-Free numbers to assign to the campaign (required, 1 up to the brand's tollFree.maxNumbersPerCampaign and at most 5, each at least 10 digits and digits only). The numbers must be on the brand's toll-free carrier, or the campaign is refused. Numbers are locked to the campaign once assigned and cannot be moved or added afterward.
  */
 
 /**

package/src/domains/Messages.js

@@ -108,8 +108,10 @@ export class Messages {
 
 	/**
 	 * Fetch the latest upstream carrier delivery report for a set of messages by ID (SHGHL-1856).
-	 * Useful for reconciling messages stuck in a non-terminal state. SMS and MMS messages are looked up
-	 * against the carrier; other message types are returned with their stored status.
+	 * Useful for reconciling messages stuck in a non-terminal state. Outbound SMS and MMS messages sent from numbers on
+	 * the carrier whose delivery logs we read are looked up there (the logs are kept about 48 hours); every other message,
+	 * including P2P messages and messages sent from numbers on other carriers, is returned with its stored status and
+	 * upstreamReportAvailable false. The request fails with a 500 when the sending numbers can't be read.
 	 * @async
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for fetching delivery reports

package/src/domains/Numbers.js

@@ -81,6 +81,7 @@ export class Numbers {
    * @param {string} [params.brandId] - Filter by brand ID
    * @param {string} [params.subgroupId] - Filter by subgroup ID
    * @param {string} [params.groupId] - Filter by group ID
+   * @param {boolean} [params.currentTollFreeCarrier] - With subgroupId or groupId: when true, return only toll-free numbers that a new toll-free campaign in that group can use (those on the group's current toll-free carrier)
    * @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 {RequestOptions} [params.options] - Additional options for the request
@@ -103,8 +104,8 @@ export class Numbers {
    * or GET /campaign/health.
    * @returns {Promise<SdkResponse<any>>} A promise that resolves to the list of phone numbers
    */
-  async getPhoneNumbers({ phoneNumber, campaignId, registrationId, brandId, subgroupId, groupId, page, limit, options = {} }) {
-    const filters = { phoneNumber, campaignId, registrationId, brandId, subgroupId, groupId, page, limit };
+  async getPhoneNumbers({ phoneNumber, campaignId, registrationId, brandId, subgroupId, groupId, currentTollFreeCarrier, page, limit, options = {} }) {
+    const filters = { phoneNumber, campaignId, registrationId, brandId, subgroupId, groupId, currentTollFreeCarrier, page, limit };
     const queryString = this.client._getQueryString(filters);
     return this.client(`/number${queryString}`, { method: 'GET', ...options });
   }
@@ -261,14 +262,18 @@ export class Numbers {
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for reading the order status
    * @param {string} params.orderId - The order id returned by `purchaseTollFreeNumbers`
+   * @param {string} [params.groupId] - Staff and service callers only: the order's group, whose carrier the read follows.
+   *   Their tokens carry no active group; every other caller's order is read by its active group, so a well-formed
+   *   groupId is ignored and a malformed one gets a 400.
    * @param {RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the orderId parameter is missing
    * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ orderId, counts: { ready, provisioning, failed }, failures: [{ reason }], numbers: string[] }`.
    */
-  async getTollFreeOrderStatus({ orderId, options = {} }) {
+  async getTollFreeOrderStatus({ orderId, groupId, options = {} }) {
     this.client._require({ orderId });
     const safeOrderId = encodeURIComponent(orderId);
-    return this.client(`/number/toll-free/order/${safeOrderId}`, { method: 'GET', ...options });
+    const queryString = this.client._getQueryString({ groupId });
+    return this.client(`/number/toll-free/order/${safeOrderId}${queryString}`, { method: 'GET', ...options });
   }
 
   /**
@@ -298,6 +303,60 @@ export class Numbers {
     });
   }
 
+  /**
+   * Get a phone number's outbound caller name (CNAM) - the name US carriers show for calls from it
+   * @async
+   * @roles api, admin, developer, billing, user
+   * @param {Object} params - The parameters for the request
+   * @param {string} params.phoneNumber - The phone number (E.164, leading + optional)
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @throws {Error} Throws an error if the phoneNumber parameter is missing
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ phoneNumber, cnam, autoApply, eligible, ineligibleReason }`
+   */
+  async getCallerName({ phoneNumber, options = {} }) {
+    this.client._require({ phoneNumber });
+    const safePhoneNumber = encodeURIComponent(phoneNumber);
+    return this.client(`/number/${safePhoneNumber}/cnam`, { method: 'GET', ...options });
+  }
+
+  /**
+   * Set a phone number's outbound caller name (CNAM). The name may only remove characters from the
+   * registered name of the number's brand (its campaign's brand, else `brandId`, else the subgroup's
+   * default caller-ID brand), and must be 1-15 letters, digits, spaces, `-` or `_`.
+   * @async
+   * @roles api, admin, developer
+   * @param {Object} params - The parameters for the request
+   * @param {string} params.phoneNumber - The phone number (E.164, leading + optional)
+   * @param {string} params.name - The caller name to show
+   * @param {string} [params.brandId] - The verified brand the name comes from; only for numbers with no campaign
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @throws {Error} Throws an error if the phoneNumber or name parameter is missing
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ phoneNumber, cnam, autoApply, eligible, ineligibleReason }`
+   */
+  async setCallerName({ phoneNumber, name, brandId, options = {} }) {
+    this.client._require({ phoneNumber, name });
+    const safePhoneNumber = encodeURIComponent(phoneNumber);
+    const body = brandId ? { name, brandId } : { name };
+    return this.client(`/number/${safePhoneNumber}/cnam`, { method: 'PUT', body, ...options });
+  }
+
+  /**
+   * Remove a phone number's own caller name (CNAM). If its subgroup has caller name auto-apply on, the
+   * number goes back to the automatic name.
+   * @async
+   * @roles api, admin, developer
+   * @param {Object} params - The parameters for the request
+   * @param {string} params.phoneNumber - The phone number (E.164, leading + optional)
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @throws {Error} Throws an error if the phoneNumber parameter is missing
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ phoneNumber, cnam, autoApply, eligible, ineligibleReason }`
+   */
+  async deleteCallerName({ phoneNumber, options = {} }) {
+    this.client._require({ phoneNumber });
+    const safePhoneNumber = encodeURIComponent(phoneNumber);
+    return this.client(`/number/${safePhoneNumber}/cnam`, { method: 'DELETE', ...options });
+  }
+
   /**
    * Submit a port-in request for one or more phone numbers from another provider
    * @async
@@ -371,7 +430,9 @@ export class Numbers {
    * Numbers that are not found, already RELEASED, currently being released (transient PENDING_RELEASE
    * status), 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.
+   * reported back individually in `skipped` instead of failing the whole request. A Toll-Free campaign
+   * whose brand reports `tollFree.maxNumbersPerCampaign` as 1 holds one number: a request that would give
+   * it a second is refused with a 400 and nothing is queued.
    * @async
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for assigning phone numbers to a campaign

package/src/domains/Onboarding.js

@@ -40,6 +40,24 @@ export class Onboarding {
 					return this.client(`/group/onboarding/${safeGroupId}`, { method: "GET", ...options });
 				},
 
+				/**
+				 * Set where a group's new toll-free brands and numbers go (`infobip` or `twilio`). Staff-only. Existing brands,
+				 * numbers and campaigns stay where they are.
+				 * @async
+				 * @roles signalhouse
+				 * @param {Object} params
+				 * @param {string} params.groupId - The group ID whose toll-free provider to set
+				 * @param {string} params.tollFreeProvider - The toll-free provider for the group's new toll-free brands and numbers ("infobip" or "twilio")
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @throws {Error} Throws an error if the groupId or tollFreeProvider parameter is missing
+				 * @returns {Promise<SdkResponse<any>>} - The updated onboarding record
+				 */
+				setTollFreeProvider: async ({ groupId, tollFreeProvider, options = {} }) => {
+					this.client._require({ groupId, tollFreeProvider });
+					const safeGroupId = encodeURIComponent(groupId);
+					return this.client(`/group/onboarding/${safeGroupId}/toll-free-provider`, { method: "PUT", body: { tollFreeProvider }, ...options });
+				},
+
 				/**
 				 * Add an internal comment/note to a group's admin Pricing editor. Staff-only.
 				 * @async

package/src/domains/Subgroups.js

@@ -40,6 +40,8 @@
  * @property {string} [status] - The status of the subgroup (e.g., "active", "inactive")
  * @property {string} [carrierIdFamily] - Optional agency-managed carrier ID selection ("Default", "ATT", "TMobile", "Verizon", "USCellular", "GoogleVoice", "ClearSky", "Interop"). Setting this field requires signalhouse_api, signalhouse_admin, signalhouse_user, api, admin, developer, or billing role.
  * @property {string|null} [carrierIdRegion] - Optional ClearSky region ("PRClaro", "GuamDocomo", "GuamGTA", "GuamITE") or null; only valid when carrierIdFamily is "ClearSky". Setting this field requires signalhouse_api, signalhouse_admin, signalhouse_user, api, admin, developer, or billing role.
+ * @property {boolean} [cnamAutoApply] - Turn caller name (CNAM) auto-apply on or off: eligible numbers get their brand's registered name as the name shown on outbound calls. Requires signalhouse_api, signalhouse_admin, signalhouse_user, api, admin or developer role.
+ * @property {string|null} [cnamBrandId] - Default caller-ID brand for numbers with no campaign (e.g. voice-only). Must be a verified brand in this subgroup; required when turning auto-apply on in a subgroup with more than one verified brand.
  */
 
 export class Subgroups {

package/src/domains/Templates.js

@@ -0,0 +1,403 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
+/**
+ * A version selector: a positive version number, "draft" or "published". Omitted means the published
+ * version when one exists, otherwise the draft; an explicit selector never falls back (404 when missing).
+ * @typedef {number|"draft"|"published"} VersionSelector
+ */
+
+/**
+ * @typedef {Object} RcsVariable
+ * @property {string} key - Placeholder key used as {{key}} (/^[a-z][a-z0-9_]{0,63}$/)
+ * @property {string} [label] - Display label
+ * @property {"text"|"number"|"dateTime"|"phoneNumber"|"url"} type - Value type
+ * @property {boolean} required - Whether a send must supply a value
+ * @property {string} [default] - Value used when none is supplied
+ * @property {string} [sample] - Example value for previews
+ */
+
+/**
+ * The raw RCS template body. Unknown keys are rejected at every level; see the API docs for the block,
+ * suggestion and fallback shapes.
+ * @typedef {Object} RcsTemplateBody
+ * @property {"rcs"} channel - Always "rcs"
+ * @property {"rcs.blocks.v1"} contentFormat - Always "rcs.blocks.v1"
+ * @property {{ blocks: Object[] }} content - Ordered blocks of kind text, richCard, video, carousel, suggestions or attachment
+ * @property {RcsVariable[]} [variables] - Declared placeholders; omitted means []
+ * @property {{ trafficType?: string, ttlSeconds?: number }} [defaults] - Send defaults; omitted means {}
+ * @property {{ delivery?: { channel: "sms"|"mms", campaignId?: string, phoneNumber?: string, content: Object }, validitySeconds?: number }} [fallback] - SMS/MMS sent when RCS cannot be delivered; no delivery means no fallback
+ */
+
+/**
+ * @typedef {Object} TemplateHead
+ * @property {string} templateId - "TPL" + 10 characters
+ * @property {string} groupId - Owning group
+ * @property {"rcs"} channel - Template channel
+ * @property {string} name - 1-120 characters, unique per group and channel
+ * @property {string|null} tag - Tag (1-60 characters) or null
+ * @property {string|null} archivedAt - When the template was archived
+ * @property {number|null} draftVersion - The current draft version
+ * @property {number|null} publishedVersion - The current published version
+ * @property {number} revision - Head revision, incremented on every write; starts at 1
+ * @property {string} createdBy - Creating user
+ * @property {string} createdAt - ISO timestamp
+ * @property {string} updatedAt - ISO timestamp
+ */
+
+/**
+ * @typedef {TemplateHead & { state: "DRAFT"|"PUBLISHED"|"ARCHIVED", hasUnpublishedChanges: boolean }} TemplateSummary
+ */
+
+/**
+ * @typedef {Object} VersionSummary
+ * @property {string} templateId - The template ID
+ * @property {string} groupId - Owning group
+ * @property {number} version - Version number
+ * @property {"DRAFT"|"PUBLISHED"} state - Version state
+ * @property {string} contentHash - Hex SHA-256 of the canonical body JSON
+ * @property {string} createdBy - Creating user
+ * @property {string} createdAt - ISO timestamp
+ * @property {string} updatedAt - ISO timestamp
+ * @property {string|null} publishedAt - ISO timestamp
+ */
+
+/**
+ * @typedef {VersionSummary & { body: RcsTemplateBody }} TemplateVersion
+ */
+
+/**
+ * @typedef {Object} TemplateDetail
+ * @property {TemplateSummary} head - The template head
+ * @property {TemplateVersion} version - The selected version
+ */
+
+/**
+ * @template T
+ * @typedef {{ data: T[], total: number, page: number, limit: number }} Page
+ */
+
+/**
+ * @typedef {Object} ValidationIssue
+ * @property {"error"|"warning"} severity - Issue severity
+ * @property {string} path - JSON path of the offending field
+ * @property {string} code - Machine-readable code
+ * @property {string} message - Human-readable message
+ * @property {string} [blockId] - The block the issue belongs to
+ */
+
+/**
+ * @typedef {Object} ValidationResult
+ * @property {boolean} valid - Whether the body is publishable
+ * @property {string} contentHash - Hex SHA-256 of the canonical body JSON
+ * @property {string} validatorVersion - The validator that produced the result
+ * @property {ValidationIssue[]} errors - Publication errors
+ * @property {ValidationIssue[]} warnings - Non-blocking warnings
+ */
+
+/**
+ * @typedef {Object} MediaAsset
+ * @property {string} mediaId - "MED" + 10 characters
+ * @property {string} groupId - Owning group
+ * @property {string} url - Public HTTPS URL to reference from a template body
+ * @property {number} bytes - File size
+ * @property {string} mimeType - MIME type
+ * @property {"image"|"video"|"audio"|"file"} kind - Media kind
+ * @property {number|null} width - Pixel width, when known
+ * @property {number|null} height - Pixel height, when known
+ * @property {string} createdAt - ISO timestamp
+ */
+
+/**
+ * Server-defined channel capabilities; values come from the server and drive client-side editors.
+ * @typedef {Object} Capabilities
+ * @property {"rcs"} channel - The channel described
+ * @property {"rcs.blocks.v1"} contentFormat - The body format
+ * @property {string} validatorVersion - The validator version
+ * @property {string[]} blockKinds - Allowed block kinds
+ * @property {string[]} actionTypes - Allowed suggestion types
+ * @property {string[]} variableTypes - Allowed variable types
+ * @property {string[]} trafficTypes - Allowed traffic types
+ * @property {string[]} cardWidths - Allowed carousel card widths
+ * @property {string[]} mediaHeights - Allowed card media heights
+ * @property {Object<string, number>} limits - Length and count limits (maxBlocks, maxTextLength, maxCarouselCards, ...)
+ * @property {{ maxUploadBytes: number, mimeTypes: string[] }} media - Upload constraints
+ * @property {{ provider: "infobip"|"sinch", adapterVersion: string, limits: Object<string, number>, unsupported: Array<{ feature: string, code: string, message: string }> }|null} provider - Provider-specific limits when a provider was requested
+ */
+
+/**
+ * Build the client-side validation error the SDK throws for a malformed request.
+ * @param {string} message - The error message
+ * @returns {Error & { status?: number }} - An error named SignalHouseValidationError with status 400
+ */
+function validationError(message) {
+	const error = /** @type {Error & { status?: number }} */ (new Error(message));
+	error.name = "SignalHouseValidationError";
+	error.status = 400;
+	return error;
+}
+
+/**
+ * Build the update request body; a null tag stays on the wire, an undefined one is dropped.
+ * @param {Object} params - The update fields
+ * @param {string} params.groupId - The owning group
+ * @param {string} [params.name] - New name
+ * @param {string|null} [params.tag] - New tag; null clears it, undefined leaves it unchanged
+ * @param {RcsTemplateBody} [params.body] - Full replacement body
+ * @returns {Object} - The request body
+ */
+export function templateUpdateBody({ groupId, name, tag, body }) {
+	return { groupId, name, tag, body };
+}
+
+/**
+ * Build the validate request body from exactly one of body or version.
+ * @param {Object} params - The validate fields
+ * @param {string} params.groupId - The owning group
+ * @param {RcsTemplateBody} [params.body] - An unsaved body to validate
+ * @param {VersionSelector} [params.version] - A stored version to validate
+ * @throws {Error} Throws a SignalHouseValidationError unless exactly one of body or version is given
+ * @returns {Object} - The request body
+ */
+export function templateValidateBody({ groupId, body, version }) {
+	const hasBody = body !== undefined && body !== null;
+	const hasVersion = version !== undefined && version !== null;
+	if (hasBody === hasVersion) throw validationError("Pass exactly one of body or version");
+	return hasBody ? { groupId, body } : { groupId, version };
+}
+
+/**
+ * Build the multipart form for a media upload.
+ * @param {Object} params - The upload fields
+ * @param {string} params.groupId - The owning group
+ * @param {Blob|File} params.file - The file to upload
+ * @param {string} [params.fileName] - File name to send with the file
+ * @returns {FormData} - The form with file and groupId fields
+ */
+export function templateMediaForm({ groupId, file, fileName }) {
+	const formData = new FormData();
+	if (fileName) formData.append("file", file, fileName);
+	else formData.append("file", file);
+	formData.append("groupId", groupId);
+	return formData;
+}
+
+/**
+ * Channel-generic message templates under /template. Templates keep an immutable published version and
+ * at most one editable draft; writes apply directly (last write wins). 404 while the environment's RCS
+ * switch is off.
+ */
+export class Templates {
+	constructor(client, multipartClient, enableAdmin) {
+		this.client = client;
+		this.multipartClient = multipartClient;
+		this.enableAdmin = enableAdmin;
+	}
+
+	/**
+	 * Create a template with draft version 1
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for creating a template
+	 * @param {string} params.groupId - The owning group
+	 * @param {string} params.name - Template name (1-120 characters, unique per group and channel)
+	 * @param {string} [params.tag] - Tag (1-60 characters)
+	 * @param {RcsTemplateBody} params.body - The raw template body
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<TemplateDetail>>} A promise that resolves to the new template and its draft (201)
+	 */
+	async create({ groupId, name, tag, body, options = {} }) {
+		this.client._require({ groupId, name, body });
+		return this.client(`/template`, {
+			method: "POST",
+			body: { groupId, name, tag, body },
+			...options,
+		});
+	}
+
+	/**
+	 * List a group's templates
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for listing templates
+	 * @param {string} params.groupId - The owning group
+	 * @param {("DRAFT"|"PUBLISHED"|"ARCHIVED")} [params.state] - Filter by state
+	 * @param {"rcs"} [params.channel] - Filter by channel
+	 * @param {string} [params.tag] - Filter by tag
+	 * @param {string} [params.search] - Search template names
+	 * @param {("name"|"createdAt"|"updatedAt")} [params.sortBy] - Sort field
+	 * @param {("asc"|"desc")} [params.sortOrder] - Sort direction
+	 * @param {number} [params.page] - Page number (default 1)
+	 * @param {number} [params.limit] - Templates per page (default 25, max 100)
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<Page<TemplateSummary>>>} A promise that resolves to { data, total, page, limit }
+	 */
+	async list({ groupId, state, channel, tag, search, sortBy, sortOrder, page, limit, options = {} }) {
+		this.client._require({ groupId });
+		const queryString = this.client._getQueryString({ groupId, state, channel, tag, search, sortBy, sortOrder, page, limit });
+		return this.client(`/template${queryString}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Get a template with one of its versions
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for getting a template
+	 * @param {string} params.templateId - The template ID
+	 * @param {string} params.groupId - The owning group
+	 * @param {VersionSelector} [params.version] - Version to return; defaults to published, else draft
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<TemplateDetail>>} A promise that resolves to { head, version }
+	 */
+	async get({ templateId, groupId, version, options = {} }) {
+		this.client._require({ templateId, groupId });
+		const safeId = encodeURIComponent(templateId);
+		const queryString = this.client._getQueryString({ groupId, version });
+		return this.client(`/template/${safeId}${queryString}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Update a template's name, tag or draft body; editing the body of a published template opens a new draft
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for updating a template
+	 * @param {string} params.templateId - The template ID
+	 * @param {string} params.groupId - The owning group
+	 * @param {string} [params.name] - New name
+	 * @param {string|null} [params.tag] - New tag; null clears it, omitted leaves it unchanged
+	 * @param {RcsTemplateBody} [params.body] - Full replacement body
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<TemplateDetail>>} A promise that resolves to { head, version }
+	 */
+	async update({ templateId, groupId, name, tag, body, options = {} }) {
+		this.client._require({ templateId, groupId });
+		const safeId = encodeURIComponent(templateId);
+		return this.client(`/template/${safeId}`, {
+			method: "PUT",
+			body: templateUpdateBody({ groupId, name, tag, body }),
+			...options,
+		});
+	}
+
+	/**
+	 * Publish a template's current draft; no draft returns 409 NO_DRAFT, a draft changed mid-publish returns 409 DRAFT_CHANGED (publish again) and an incomplete draft returns 400 TEMPLATE_INVALID
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for publishing a template
+	 * @param {string} params.templateId - The template ID
+	 * @param {string} params.groupId - The owning group
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<TemplateDetail>>} A promise that resolves to { head, version } for the published version
+	 */
+	async publish({ templateId, groupId, options = {} }) {
+		this.client._require({ templateId, groupId });
+		const safeId = encodeURIComponent(templateId);
+		return this.client(`/template/${safeId}/publish`, {
+			method: "POST",
+			body: { groupId },
+			...options,
+		});
+	}
+
+	/**
+	 * Archive a template
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for archiving a template
+	 * @param {string} params.templateId - The template ID
+	 * @param {string} params.groupId - The owning group
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<TemplateHead>>} A promise that resolves to the archived template head
+	 */
+	async archive({ templateId, groupId, options = {} }) {
+		this.client._require({ templateId, groupId });
+		const safeId = encodeURIComponent(templateId);
+		return this.client(`/template/${safeId}/archive`, {
+			method: "POST",
+			body: { groupId },
+			...options,
+		});
+	}
+
+	/**
+	 * List a template's versions without their bodies
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for listing versions
+	 * @param {string} params.templateId - The template ID
+	 * @param {string} params.groupId - The owning group
+	 * @param {number} [params.page] - Page number (default 1)
+	 * @param {number} [params.limit] - Versions per page (default 25, max 100)
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<Page<VersionSummary>>>} A promise that resolves to { data, total, page, limit }
+	 */
+	async versions({ templateId, groupId, page, limit, options = {} }) {
+		this.client._require({ templateId, groupId });
+		const safeId = encodeURIComponent(templateId);
+		const queryString = this.client._getQueryString({ groupId, page, limit });
+		return this.client(`/template/${safeId}/versions${queryString}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Validate an unsaved body or a stored version without writing anything
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for validation; pass exactly one of body or version
+	 * @param {string} params.templateId - The template ID
+	 * @param {string} params.groupId - The owning group
+	 * @param {RcsTemplateBody} [params.body] - An unsaved body to validate
+	 * @param {VersionSelector} [params.version] - A stored version to validate
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @throws {Error} Throws a SignalHouseValidationError unless exactly one of body or version is given
+	 * @returns {Promise<SdkResponse<ValidationResult>>} A promise that resolves to { valid, contentHash, validatorVersion, errors, warnings }
+	 */
+	async validate({ templateId, groupId, body, version, options = {} }) {
+		this.client._require({ templateId, groupId });
+		const safeId = encodeURIComponent(templateId);
+		return this.client(`/template/${safeId}/validate`, {
+			method: "POST",
+			body: templateValidateBody({ groupId, body, version }),
+			...options,
+		});
+	}
+
+	/**
+	 * Get a channel's template capabilities: allowed blocks, actions, limits and upload constraints
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for getting capabilities
+	 * @param {string} params.groupId - The owning group
+	 * @param {"rcs"} [params.channel] - The channel (default "rcs")
+	 * @param {("infobip"|"sinch")} [params.provider] - Include this provider's limits and unsupported features
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<Capabilities>>} A promise that resolves to the capabilities
+	 */
+	async capabilities({ groupId, channel, provider, options = {} }) {
+		this.client._require({ groupId });
+		const queryString = this.client._getQueryString({ groupId, channel, provider });
+		return this.client(`/template/capabilities${queryString}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Upload a media file for use in template bodies; returns its public URL. 503 when media storage is not configured
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for the upload
+	 * @param {string} params.groupId - The owning group
+	 * @param {Blob|File} params.file - The file to upload
+	 * @param {string} [params.fileName] - File name to send with the file
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<MediaAsset>>} A promise that resolves to the stored media asset (201)
+	 */
+	async uploadMedia({ groupId, file, fileName, options = {} }) {
+		this.client._require({ groupId, file });
+		return this.multipartClient(`/template/media`, {
+			method: "POST",
+			body: templateMediaForm({ groupId, file, fileName }),
+			...options,
+		});
+	}
+}

package/src/domains/Voice.js

@@ -1,6 +1,7 @@
 import { SipTrunks } from "./voice/SipTrunks.js";
 import { SipProfiles } from "./voice/SipProfiles.js";
 import { ProgrammableVoiceProfiles } from "./voice/ProgrammableVoiceProfiles.js";
+import { NumberRoutes } from "./voice/NumberRoutes.js";
 import { Calls } from "./voice/Calls.js";
 import { CallLogs } from "./voice/CallLogs.js";
 import { GlobalVoiceSettings } from "./voice/GlobalVoiceSettings.js";
@@ -16,6 +17,7 @@ import { Analytics } from "./voice/Analytics.js";
  * - `sdk.voice.sipTrunks`                 — SIP trunk (peer-to-peer connections to PBX/carrier).
  * - `sdk.voice.sipProfiles`               — SIP profile / endpoint (single registerable UA).
  * - `sdk.voice.programmableVoiceProfiles` — Programmable Voice Profile (route a set of numbers through Signal House).
+ * - `sdk.voice.numberRoutes`              — Per-number inbound route (overrides the profile and subgroup settings).
  * - `sdk.voice.calls`                     — Twilio-compat programmatic call control (create/hangup/etc.).
  * - `sdk.voice.callLogs`                  — Account-scoped call history: list/get + presigned recording.
  * - `sdk.voice.globalVoiceSettings`       — Account-wide voice defaults (accepted regions, max spend, E911).
@@ -29,6 +31,7 @@ export class Voice {
 		this.sipTrunks = new SipTrunks(client, enableAdmin);
 		this.sipProfiles = new SipProfiles(client, enableAdmin);
 		this.programmableVoiceProfiles = new ProgrammableVoiceProfiles(client, enableAdmin);
+		this.numberRoutes = new NumberRoutes(client, enableAdmin);
 		this.calls = new Calls(client, enableAdmin);
 		this.callLogs = new CallLogs(client, enableAdmin);
 		this.globalVoiceSettings = new GlobalVoiceSettings(client, enableAdmin);

package/src/domains/Webhooks.js

@@ -43,6 +43,10 @@ export class Webhooks {
 	 * `verifyWebhookSignature` from `@signalhousellc/sdk/webhooks` (Node only). `webhookData.authType` is one of
 	 * `NONE` (default), `BASIC`, `API_KEY`, `OAUTH2` or `HMAC`; `HMAC` (SHGHL-3595) sends no credentials, so the
 	 * receiver authenticates by the signature alone, and must be sent without `credentials` or `apiHeaderPrefix`.
+	 * `webhookData.eventSettings` (SHGHL-3884) holds per-event options keyed by event name:
+	 * `NUMBER_HEALTH_BELOW_THRESHOLD` and `CAMPAIGN_HEALTH_BELOW_THRESHOLD` each take `{ threshold }`, the 7-day
+	 * health score (1.5–10, in 0.5 steps) below which the event fires; a subscribed health event without one is
+	 * stored with the default, 6.
 	 * @async
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for creating a webhook
@@ -62,7 +66,9 @@ export class Webhooks {
 	 * to change the endpoint's own credentials in place: credentials are required when switching to an auth
 	 * type that needs them, and omitted credentials keep the stored ones. Switching to `NONE` or `HMAC` clears
 	 * the stored credentials; `HMAC` is rejected for an endpoint with no signing secret (call
-	 * `rotateWebhookSecret` first). Like every read of a webhook, the
+	 * `rotateWebhookSecret` first). `updateData.eventSettings` changes per-event options by event name
+	 * (`{ NUMBER_HEALTH_BELOW_THRESHOLD: { threshold } }`, `{ CAMPAIGN_HEALTH_BELOW_THRESHOLD: { threshold } }`,
+	 * 1.5–10 in 0.5 steps); events you omit keep their stored settings. Like every read of a webhook, the
 	 * response carries `hasSigningSecret` and `hasCredentials` (booleans), never a secret or credential.
 	 * @async
 	 * @roles api, admin, developer

package/src/domains/voice/NumberRoutes.js

@@ -0,0 +1,82 @@
+/** @typedef {import('../../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
+/**
+ * @typedef {Object} NumberRouteData
+ * @property {"FORWARD"|"WEBRTC"|"SIP_TRUNK"|"SIP_PROFILE"|"CALL_CONTROL"|"AI"|"VOICEMAIL"} routeAction - How inbound calls to the number are handled.
+ * @property {string|null} [forwardToE164] - FORWARD destination (required for FORWARD), or the WEBRTC no-answer destination when noAnswerAction is FORWARD.
+ * @property {"VOICEMAIL"|"FORWARD"|"KEEP_RINGING"|null} [noAnswerAction] - WEBRTC only: what happens when nobody answers (default VOICEMAIL).
+ * @property {number|null} [noAnswerSeconds] - WEBRTC only: seconds to ring before the no-answer action, 5-120 (default 20).
+ * @property {string|null} [routeSipTrunkId] - SIP trunk to deliver to (required for SIP_TRUNK).
+ * @property {string|null} [routeSipProfileId] - SIP endpoint to ring (required for SIP_PROFILE).
+ * @property {string|null} [webhookUrl] - SHML program URL (required for CALL_CONTROL).
+ * @property {string|null} [routeAgentProfileId] - AI agent profile id, AGP… (required for AI).
+ * @property {boolean} [recordingEnabled] - Record calls handled by this route.
+ */
+
+/**
+ * Number Routes — one inbound route set directly on a single phone number. A
+ * number's own route takes priority over its Programmable Voice Profile and
+ * subgroup voice settings. Calls the voice-backend service mounted under
+ * /voice. Accessed via `sdk.voice.numberRoutes`.
+ */
+export class NumberRoutes {
+	constructor(client, enableAdmin) {
+		this.client = client;
+		this.enableAdmin = enableAdmin;
+	}
+
+	/**
+	 * Get a number's own route and the routing currently in effect for it.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.e164 - The phone number in E.164 (leading + optional).
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If e164 is missing.
+	 * @returns {Promise<SdkResponse<any>>} `{ e164, route: {...} | null, effective: {...} }`.
+	 */
+	async get({ e164, options = {} }) {
+		this.client._require({ e164 });
+		const safeE164 = encodeURIComponent(e164);
+		return this.client(`/voice/api/v1/numbers/${safeE164}/route`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Set (create or replace) a number's route. The whole route is replaced:
+	 * fields the new routeAction doesn't use are cleared.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.e164 - The phone number in E.164 (leading + optional).
+	 * @param {NumberRouteData} params.routeData - The route to set.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If e164 or routeData is missing.
+	 * @returns {Promise<SdkResponse<any>>} `{ e164, route: {...}, effective: {...} }`.
+	 */
+	async set({ e164, routeData, options = {} }) {
+		this.client._require({ e164, routeData });
+		const safeE164 = encodeURIComponent(e164);
+		return this.client(`/voice/api/v1/numbers/${safeE164}/route`, { method: "PUT", body: routeData, ...options });
+	}
+
+	/**
+	 * Remove a number's own route. The number falls back to its Programmable
+	 * Voice Profile, subgroup voice settings, or the default.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - Request parameters.
+	 * @param {string} params.e164 - The phone number in E.164 (leading + optional).
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} If e164 is missing.
+	 * @returns {Promise<SdkResponse<any>>} `{ e164, route: null, effective: {...} }`.
+	 */
+	async delete({ e164, options = {} }) {
+		this.client._require({ e164 });
+		const safeE164 = encodeURIComponent(e164);
+		return this.client(`/voice/api/v1/numbers/${safeE164}/route`, { method: "DELETE", ...options });
+	}
+}