@signalhousellc/sdk 1.0.63 → 1.0.65

package/package.json

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

package/src/domains/Auth.js

@@ -2,6 +2,28 @@ export class Auth {
 	constructor(client, enableAdmin) {
 		this.client = client;
         this.enableAdmin = enableAdmin;
+
+		// Hidden Admin namespace INSIDE the domain
+		if (enableAdmin) {
+			this.admin = {
+				/**
+				 * Force-log-out every human user in a specific group (SHGHL-2740) - for account-takeover
+				 * response, independent of the automatic Rejected-lockout trigger.
+				 * @async
+				 * @roles signalhouse
+				 * @param {Object} params - The parameters for forcing a group logout
+				 * @param {string} params.groupId - The ID of the group whose users should be force-logged-out
+				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+				 * @throws {Error} Throws an error if the groupId parameter is missing
+				 * @returns {Promise<Object>} - The response containing loggedOutCount
+				 */
+				forceLogoutGroupUsers: async ({ groupId, options = {} }) => {
+					this.client._require({ groupId });
+					const safeGroupId = encodeURIComponent(groupId);
+					return this.client(`/auth/groups/${safeGroupId}/logout-all`, { method: "POST", ...options });
+				},
+			};
+		}
 	}
 
 	/**
@@ -47,13 +69,22 @@ export class Auth {
 	}
 
 	/**
-	 * Verify an account email using the single-use token from the verification link
+	 * Verify an account email using the single-use token from the verification link, signing the
+	 * account in on success.
+	 *
+	 * The response carries a session JWT (`token`) for the user the link was emailed to, so a click
+	 * from any device establishes a session — use it exactly as you would the token from `login`.
+	 * `token` is omitted when the link cannot establish a session (issued before auto-login shipped,
+	 * or the account is inactive/ineligible); `verified` is still true in that case, so treat a
+	 * missing token as "verified, ask them to log in" rather than as a failure.
+	 *
+	 * Rate limited per source IP. The token is single-use and expires 24 hours after it is issued.
 	 * @async
 	 * @roles public
 	 * @param {Object} params
 	 * @param {string} params.token - The verification token from the email link
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response from the server ({ verified: true })
+	 * @returns {Promise<Object>} The response from the server ({ verified: true, token?: string })
 	 */
 	async verifyEmail({ token, options = {} }) {
 		this.client._require({ token });
@@ -92,7 +123,9 @@ export class Auth {
 	}
 
 	/**
-	 * Resend the account verification email to the authenticated caller
+	 * Resend the account verification email to the authenticated caller.
+	 *
+	 * Rate limited per user; issuing a new link invalidates the previous one.
 	 * @async
 	 * @roles admin, developer, billing, user
 	 * @param {Object} [params]

package/src/domains/Brands.js

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

package/src/domains/Groups.js

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

package/src/domains/Messages.js

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

package/src/domains/Numbers.js

@@ -339,15 +339,18 @@ export class Numbers {
   }
 
   /**
-   * Assign phone numbers to a campaign by providing the campaign ID and a list of phone numbers to assign
+   * Assign phone numbers to a campaign by providing the campaign ID and a list of phone numbers to assign.
+   * Numbers that are not found, already RELEASED, already assigned to a different campaign, on a mismatched
+   * DCA, or (for a 10DLC campaign without a number pool) beyond the remaining 49-number-per-campaign limit
+   * are not queued - each is reported back individually in `skipped` instead of failing the whole request.
    * @async
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for assigning phone numbers to a campaign
    * @param {string} params.campaignId - The ID of the campaign to assign phone numbers to
    * @param {string[]} params.phoneNumbers - The list of phone numbers to assign to the campaign
    * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-   * @throws {Error} Throws an error if the campaignId or phoneNumbers parameter is missing
-   * @returns {Promise<Object>} A promise that resolves to the result of the assignment operation
+   * @throws {Error} Throws an error if the campaignId or phoneNumbers parameter is missing, if none of the phone numbers exist in the account, or if the campaign is not found or in a terminal state
+   * @returns {Promise<Object>} A promise that resolves to `{ Message, queued, skipped }` - `queued` numbers were sent for assignment; `skipped` numbers were rejected (not found, RELEASED, already assigned to a campaign, cross-DCA mismatch, or over the 49-number limit).
    */
   async assignPhoneNumberToCampaign({ campaignId, phoneNumbers, options = {} }) {
     this.client._require({ campaignId, phoneNumbers });

package/src/domains/Onboarding.js

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

package/src/domains/Subgroups.js

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

package/src/domains/Tickets.js

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

package/src/domains/voice/SipProfiles.js

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

package/src/domains/voice/Tokens.js

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

package/src/domains/voice/browser/Device.js

@@ -11,9 +11,14 @@ import { Call } from "./Call.js";
 
 /**
  * @typedef {Object} VoiceTokenResponse
- * @property {string} token - JWT (informational; SDK does not currently re-send it).
- * @property {string} identity - The wrtc_<hex> SIP username.
- * @property {string} expires_at - ISO timestamp.
+ * @property {string} token - JWT (informational). Tokens are ephemeral: refresh
+ *   before `expires_at` (see updateToken()) so the softphone keeps a valid
+ *   registration.
+ * @property {string} identity - The wrtc_<hex> SIP username. The refresh
+ *   endpoint (POST /voice/tokens/refresh) keeps this identity stable; a fresh
+ *   mint (POST /voice/tokens) returns a new one.
+ * @property {string} expires_at - ISO timestamp. The Device schedules a
+ *   `tokenWillExpire` event at this minus `tokenRefreshMs`.
  * @property {SipCredentials} sip_credentials
  */
 
@@ -40,12 +45,33 @@ import { Call } from "./Call.js";
  *   const call = await device.connect({ to: "+15551234", from: "+15559999" });
  *   device.on("incoming", call => call.accept());
  *
- * Token shape mirrors what `POST /voice/tokens` returns from the SignalHouse
- * voice-backend. You can also hand in the inner `sip_credentials` object
- * directly if your app already unwrapped the response.
+ * Token refresh (REQUIRED for long-lived sessions): voice tokens are short-
+ * lived — a token's SIP credential authenticates only until `expires_at`. If
+ * you let it lapse, the softphone can no longer re-register and inbound calls
+ * stop arriving (they go to voicemail). The Device raises a `tokenWillExpire`
+ * event shortly before expiry so you can keep it alive. Mirrors Twilio's
+ * Device.updateToken() model:
+ *
+ *   // Manual — fetch a fresh token from your backend and hand it back:
+ *   device.on("tokenWillExpire", async () => {
+ *     const fresh = await fetch("/my/backend/voice-token").then((r) => r.json());
+ *     await device.updateToken(fresh);
+ *   });
+ *
+ *   // Automatic — let the Device refresh itself:
+ *   const device = new Device(tokenResponse, {
+ *     tokenProvider: () => fetch("/my/backend/voice-token").then((r) => r.json()),
+ *   });
+ *
+ * Preferred: have your backend call POST /voice/tokens/refresh, which extends
+ * the SAME identity in place — the Device then just reschedules and keeps its
+ * existing registration (no re-register, seamless). If instead you mint a fresh
+ * token (new identity), the Device re-registers under it (break-before-make,
+ * deferred while a call is active).
  *
  * Events: "registered", "unregistered", "registrationFailed", "incoming",
- * "connected" (WSS established), "disconnected", "error".
+ * "connected" (WSS established), "disconnected", "tokenWillExpire",
+ * "tokenRefreshFailed", "error".
  */
 export class Device {
 	/**
@@ -54,25 +80,36 @@ export class Device {
 	 * @param {number} [opts.registerExpires=600] - REGISTER expires interval, in seconds.
 	 * @param {string} [opts.userAgent="SignalHouse-Voice-SDK/0.1"]
 	 * @param {boolean} [opts.autoRegister=false] - Call register() on construct.
+	 * @param {number} [opts.tokenRefreshMs=30000] - How long before `expires_at`
+	 *   to raise `tokenWillExpire` (and auto-refresh, when `tokenProvider` is set).
+	 * @param {() => (VoiceTokenResponse|Promise<VoiceTokenResponse>)} [opts.tokenProvider]
+	 *   Optional. A function YOU supply that returns a fresh token — ideally by
+	 *   calling POST /voice/tokens/refresh through your backend (identity-
+	 *   preserving), or a fresh mint. When set, the Device calls it on
+	 *   `tokenWillExpire` and applies the result via updateToken() automatically.
 	 */
 	constructor(tokenOrCreds, opts = {}) {
-		const creds = tokenOrCreds?.sip_credentials || tokenOrCreds;
-		if (!creds?.username || !creds?.password || !creds?.domain || !creds?.wss_url) {
-			throw new Error("Device: token/credentials missing required fields (username, password, domain, wss_url)");
-		}
-
-		this.identity = tokenOrCreds?.identity || creds.username;
+		this._credentials = this._parseCreds(tokenOrCreds, "Device");
+		this.identity = tokenOrCreds?.identity || this._credentials.username;
 		this.expiresAt = tokenOrCreds?.expires_at || null;
 
-		this._credentials = creds;
 		this._opts = {
 			registerExpires: opts.registerExpires ?? 600,
 			userAgent: opts.userAgent ?? "SignalHouse-Voice-SDK/0.1",
+			tokenRefreshMs: opts.tokenRefreshMs ?? 30000,
+			tokenProvider: typeof opts.tokenProvider === "function" ? opts.tokenProvider : null,
 		};
 
 		this._ua = null;
 		this._listeners = new Map();
 		this._registered = false;
+		this._stopped = false;             // set by unregister(); guards in-flight refreshes
+
+		// Token-refresh state.
+		this._refreshTimer = null;         // fires `tokenWillExpire` before expiry
+		this._activeSessions = new Set();  // in-flight calls; defer an identity swap while busy
+		this._pendingToken = null;         // identity-change token handed to updateToken() while busy
+		this._refreshPendingAuto = false;  // tokenProvider refresh deferred while busy
 
 		if (opts.autoRegister) this.register().catch(() => { /* surfaced via "registrationFailed" event */ });
 	}
@@ -81,10 +118,12 @@ export class Device {
 
 	/**
 	 * Open the WSS connection and REGISTER. Resolves on first "registered"
-	 * event, rejects on first "registrationFailed".
+	 * event, rejects on first "registrationFailed". On success, schedules the
+	 * `tokenWillExpire` refresh timer from the current token's `expires_at`.
 	 * @returns {Promise<void>}
 	 */
 	register() {
+		this._stopped = false; // an intentional (re)start re-arms the device
 		if (this._registered) return Promise.resolve();
 		if (!this._ua) this._initUA();
 
@@ -92,6 +131,7 @@ export class Device {
 			const onOk = () => {
 				this._ua.removeListener("registered", onOk);
 				this._ua.removeListener("registrationFailed", onFail);
+				this._scheduleTokenRefresh();
 				resolve();
 			};
 			const onFail = (e) => {
@@ -106,18 +146,55 @@ export class Device {
 	}
 
 	/**
-	 * Unregister and close the WSS connection. Idempotent.
+	 * Unregister and close the WSS connection. Idempotent. Marks the device
+	 * stopped so any in-flight token refresh cannot bring it back online, and
+	 * cancels the refresh timer + pending state.
 	 * @returns {Promise<void>}
 	 */
 	unregister() {
-		if (!this._ua) return Promise.resolve();
-		return new Promise((resolve) => {
-			const done = () => { try { this._ua.stop(); } catch {} resolve(); };
-			if (!this._registered) return done();
-			this._ua.once("unregistered", done);
-			try { this._ua.unregister(); }
-			catch { done(); }
-		});
+		this._stopped = true;
+		this._clearTokenRefresh();
+		this._pendingToken = null;
+		this._refreshPendingAuto = false;
+		return this._teardownUA();
+	}
+
+	/**
+	 * Apply a fresh token so the registration never lapses — call this in
+	 * response to `tokenWillExpire` (or let `tokenProvider` do it).
+	 *
+	 * Identity-preserving fast path: if the token carries the SAME identity +
+	 * password as the current one (i.e. your backend called POST
+	 * /voice/tokens/refresh to extend in place), the existing registration is
+	 * still valid, so the Device just updates `expires_at` and reschedules — no
+	 * re-register, fully seamless, safe even mid-call.
+	 *
+	 * Identity change (a fresh mint): the Device re-registers under the new
+	 * identity (break-before-make), deferred while a call is active and applied
+	 * once the last call ends, so live audio is never disrupted.
+	 *
+	 * @param {VoiceTokenResponse | SipCredentials} tokenOrCreds
+	 * @returns {Promise<void>} resolves once applied (or immediately when a swap
+	 *   is deferred behind an active call).
+	 */
+	async updateToken(tokenOrCreds) {
+		const creds = this._parseCreds(tokenOrCreds, "Device.updateToken");
+		const newIdentity = tokenOrCreds?.identity || creds.username;
+
+		// Identity-preserving fast path — same credential, just extended expiry.
+		if (this._ua && this._registered && !this._stopped &&
+			newIdentity === this.identity && creds.password === this._credentials.password) {
+			this.expiresAt = tokenOrCreds?.expires_at || this.expiresAt;
+			this._scheduleTokenRefresh();
+			return;
+		}
+
+		// Identity changed → full re-register; defer while a call is active.
+		if (this._activeSessions.size > 0) {
+			this._pendingToken = tokenOrCreds;
+			return;
+		}
+		await this._applyToken(tokenOrCreds);
 	}
 
 	/**
@@ -162,6 +239,7 @@ export class Device {
 			extraHeaders: headers,
 		});
 
+		this._trackSession(session);
 		return new Call({ session, direction: "outbound" });
 	}
 
@@ -192,6 +270,173 @@ export class Device {
 		}
 	}
 
+	/**
+	 * Unwrap `sip_credentials` from a token response (or accept a bare creds
+	 * object) and validate the four required SIP fields.
+	 * @param {VoiceTokenResponse | SipCredentials} tokenOrCreds
+	 * @param {string} ctx - Caller label used in the error message.
+	 * @returns {SipCredentials}
+	 * @throws {Error} when a required field is missing.
+	 */
+	_parseCreds(tokenOrCreds, ctx) {
+		const creds = tokenOrCreds?.sip_credentials || tokenOrCreds;
+		if (!creds?.username || !creds?.password || !creds?.domain || !creds?.wss_url) {
+			throw new Error(`${ctx}: token/credentials missing required fields (username, password, domain, wss_url)`);
+		}
+		return creds;
+	}
+
+	/**
+	 * Stop the current UA and close its WSS, without touching lifecycle flags —
+	 * used both by unregister() and by _applyToken()'s break-before-make swap.
+	 * @returns {Promise<void>}
+	 */
+	_teardownUA() {
+		if (!this._ua) return Promise.resolve();
+		return new Promise((resolve) => {
+			const ua = this._ua;
+			const done = () => { try { ua.stop(); } catch {} resolve(); };
+			if (!this._registered) return done();
+			ua.once("unregistered", done);
+			try { ua.unregister(); }
+			catch { done(); }
+		});
+	}
+
+	/**
+	 * Re-register under fresh credentials when the identity changed
+	 * (break-before-make). Only invoked when no call is active (updateToken
+	 * defers while busy). Bails if the app tore the device down mid-swap; if the
+	 * new registration fails, surfaces `tokenRefreshFailed` and re-arms a short
+	 * retry so the device recovers rather than sitting unregistered.
+	 * @param {VoiceTokenResponse | SipCredentials} tokenOrCreds
+	 */
+	async _applyToken(tokenOrCreds) {
+		const creds = this._parseCreds(tokenOrCreds, "Device.updateToken");
+		this._clearTokenRefresh();
+		try { await this._teardownUA(); } catch { /* ignore — tearing down anyway */ }
+		if (this._stopped) return; // unregister() ran while we were tearing down
+
+		this._ua = null;
+		this._registered = false;
+		this._credentials = creds;
+		this.identity = tokenOrCreds?.identity || creds.username;
+		this.expiresAt = tokenOrCreds?.expires_at || null;
+
+		try {
+			await this.register(); // rebuilds the UA + reschedules the refresh timer
+		} catch (err) {
+			this._emit("tokenRefreshFailed", { error: err });
+			if (!this._stopped) {
+				this._clearTokenRefresh();
+				this._refreshTimer = setTimeout(() => this._onTokenWillExpire(), 5000);
+			}
+			throw err; // propagate to a manual updateToken() caller
+		}
+	}
+
+	/** `expires_at` as epoch ms, or null when unparseable/absent. */
+	_expiresAtMs() {
+		const t = Date.parse(this.expiresAt || "");
+		return Number.isFinite(t) ? t : null;
+	}
+
+	/**
+	 * True if the given token has too little life left to safely apply (would
+	 * expire within tokenRefreshMs). Tokens with no parseable expiry are treated
+	 * as usable.
+	 * @param {VoiceTokenResponse} tokenOrCreds
+	 * @returns {boolean}
+	 */
+	_isTokenStale(tokenOrCreds) {
+		const exp = Date.parse(tokenOrCreds?.expires_at || "");
+		if (!Number.isFinite(exp)) return false;
+		return exp - Date.now() <= this._opts.tokenRefreshMs;
+	}
+
+	/** Arm the one-shot `tokenWillExpire` timer for tokenRefreshMs before expiry. */
+	_scheduleTokenRefresh() {
+		this._clearTokenRefresh();
+		const expMs = this._expiresAtMs();
+		if (expMs === null) return; // no expiry info → caller manages refresh manually
+		const delay = Math.max(0, expMs - Date.now() - this._opts.tokenRefreshMs);
+		this._refreshTimer = setTimeout(() => this._onTokenWillExpire(), delay);
+	}
+
+	/** Cancel the pending `tokenWillExpire` timer, if any. */
+	_clearTokenRefresh() {
+		if (this._refreshTimer) { clearTimeout(this._refreshTimer); this._refreshTimer = null; }
+	}
+
+	/**
+	 * Fired shortly before the current token expires. Emits `tokenWillExpire`
+	 * for manual handlers; if a `tokenProvider` is configured, also fetches a
+	 * fresh token and applies it. Deferred while a call is active (the fetch
+	 * happens only once idle, so a fetched token can't go stale in hand). Bails
+	 * if the device was torn down while the fetch was in flight.
+	 */
+	async _onTokenWillExpire() {
+		if (this._stopped) return;
+		this._emit("tokenWillExpire", { identity: this.identity, expiresAt: this.expiresAt });
+		if (!this._opts.tokenProvider) return; // app handles it via updateToken()
+		if (this._activeSessions.size > 0) {
+			this._refreshPendingAuto = true; // fetch + apply once the call ends
+			return;
+		}
+		try {
+			const fresh = await this._opts.tokenProvider();
+			if (this._stopped) return; // torn down while the provider fetch was pending
+			if (!fresh) throw new Error("tokenProvider returned no token");
+			await this.updateToken(fresh);
+		} catch (err) {
+			if (this._stopped) return;
+			this._emit("tokenRefreshFailed", { error: err });
+			// Retry shortly so a transient failure doesn't strand us, provided
+			// there's still time before the current token expires.
+			const expMs = this._expiresAtMs();
+			if (expMs !== null && expMs - Date.now() > 5000) {
+				this._clearTokenRefresh();
+				this._refreshTimer = setTimeout(() => this._onTokenWillExpire(), 5000);
+			}
+		}
+	}
+
+	/** Track a call session so an identity swap can be deferred until it ends. */
+	_trackSession(session) {
+		if (!session) return;
+		this._activeSessions.add(session);
+		const done = () => this._untrackSession(session);
+		try { session.on("ended", done); session.on("failed", done); }
+		catch { /* not a JsSIP session — best-effort tracking only */ }
+	}
+
+	/**
+	 * Stop tracking a finished session. When the line goes fully idle, apply any
+	 * token refresh that was deferred behind the call: a `tokenProvider` fetch
+	 * (fresh) or a stored identity-change token — re-fetching instead if that
+	 * stored token has gone stale while the call ran.
+	 * @param {object} session - The JsSIP session that ended/failed.
+	 */
+	_untrackSession(session) {
+		this._activeSessions.delete(session);
+		if (this._activeSessions.size > 0 || this._stopped) return;
+
+		if (this._refreshPendingAuto) {
+			this._refreshPendingAuto = false;
+			this._onTokenWillExpire();
+		} else if (this._pendingToken) {
+			const pending = this._pendingToken;
+			this._pendingToken = null;
+			// A long call can outlive the token we stashed — don't register with
+			// stale creds; get a fresh one the same way the timer would.
+			if (this._isTokenStale(pending)) {
+				this._onTokenWillExpire();
+			} else {
+				this._applyToken(pending).catch((err) => this._emit("tokenRefreshFailed", { error: err }));
+			}
+		}
+	}
+
 	_initUA() {
 		const socket = new JsSIP.WebSocketInterface(this._credentials.wss_url);
 		this._ua = new JsSIP.UA({
@@ -219,6 +464,7 @@ export class Device {
 
 		this._ua.on("newRTCSession", (e) => {
 			if (e.originator !== "remote") return; // outbound: we already wrap in connect()
+			this._trackSession(e.session);
 			const call = new Call({ session: e.session, direction: "inbound", request: e.request });
 			this._emit("incoming", call);
 		});