@signalhousellc/sdk 1.0.66 → 1.0.67

package/README.md

@@ -55,3 +55,13 @@ For full API reference and advanced usage, visit https://api.signalhouse.io
 
 License
 ISC © Signal House
+
+
+### Geographic availability search
+
+The availability path supports optional `city` as a case-insensitive prefix within an explicit `country` (`CA` or `US`) and `state` (province/state code). City must be supplied with both country and state. Example: `getAvailablePhoneNumbers({ country: "CA", state: "QC", city: "Charny", npa: "367", nxx: "883", limit: 10 })`. Canadian province, city, NPA and NXX matches are checked before the result limit; unrelated substring matches are excluded. Availability may change before purchase.
+
+
+Canadian message estimates return per-recipient `phoneNumber`, `rate`, `amount` and `fallback`, plus segment count and total in microdollars. They use cached carrier information without exposing carrier names or making a paid lookup. Rates remain 75,500 for standard carriers and 81,000 for Ice Wireless/Iristel or unresolved carriers; MMS/group MMS use one segment per recipient.
+
+Available-number searches return `{ numbers, numberCount? }`. `numberCount` is omitted when the total is unknown, including Canadian geographic and US city searches; the page length is not a total. These filtered searches have a 20-second discovery deadline and return HTTP 503 when incomplete. Narrow the location/NPA/NXX or retry later. Successful Infobip samples may be cached for 15 seconds across pages; purchase rechecks availability.

package/package.json

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

package/skills/signalhouse-10dlc/references/tcr-rejection-causes.md

@@ -42,13 +42,10 @@ Two distinct real causes share this code.
 
 **`Invalid sub-usecases: SOCIAL`.** `SOCIAL` is not a valid sub-use-case under any parent,
 neither `LOW_VOLUME` nor `MIXED`. Valid sub-use-cases for `LOW_VOLUME` are
-`ACCOUNT_NOTIFICATION`, `CUSTOMER_CARE`, `DELIVERY_NOTIFICATION`, `MARKETING`. Resubmit with
-`SOCIAL` removed.
-
-⚠️ **Known platform bug, tracked as SHGHL-2943.** Signal House validates `subUsecases` against
-the *use-case* enum, so `SOCIAL` is selectable as a sub-use-case even though the registry always
-rejects it. **Delete this subsection when SHGHL-2943 ships.** It documents a defect, and a
-workaround left in a skill becomes permanent.
+`ACCOUNT_NOTIFICATION`, `CUSTOMER_CARE`, `DELIVERY_NOTIFICATION`, `MARKETING`. Signal House's own
+validation now rejects `SOCIAL` as a `subUsecases` value with an immediate 400 before the request
+ever reaches TCR (SHGHL-2943), so this specific 501 should no longer be reachable through the
+API — `SOCIAL` is still a valid top-level `usecase`, just never a sub-use-case.
 
 **Punctuation in a tag.** A tag of `maria-answers` was rejected for containing a hyphen. The
 campaign content was fine. Fix the tag (`mariaanswers`), then the campaign has to be

package/src/SignalHouseSDK.js

@@ -24,6 +24,7 @@ import { Users } from "./domains/Users.js";
 import { Notifications } from "./domains/Notifications.js";
 import { Webhooks } from "./domains/Webhooks.js";
 import { Voice } from "./domains/Voice.js";
+import { Agents } from "./domains/Agents.js";
 
 export class SignalHouseSDK {
 	/**
@@ -73,6 +74,8 @@ export class SignalHouseSDK {
 		// Voice domain targets the voice-backend service under /voice. Available
 		// like any other domain; gating (if any) will be decided later.
 		this.voice = new Voice(client, this.enableAdmin);
+		// AI Agents domain — customer-facing agent config under /agent.
+		this.agents = new Agents(client, this.enableAdmin);
 	}
 
 	/**

package/src/domains/Agents.js

@@ -0,0 +1,456 @@
+/**
+ * @typedef {Object} CreateAgentProfileData
+ * @property {string} groupId - The parent group id (at least 8 characters, starts with 'G').
+ * @property {string|null} [subgroupId] - Optional subgroup id (at least 8 characters, starts with 'S'); null/omitted = group-level agent.
+ * @property {string} name - The agent's name (required).
+ * @property {string} [status] - Lifecycle status: "active" or "inactive" (defaults to "active").
+ * @property {string} [systemPrompt] - Base system prompt composed into every conversation.
+ * @property {string} [greeting] - Opening line the agent leads with.
+ * @property {string} [guardrails] - Freeform guardrail instructions appended to the composed prompt.
+ * @property {string|null} [voiceId] - ElevenLabs voice id for the voice channel; null until set.
+ * @property {string} [llmProvider] - LLM backend: "bedrock", "openai", "anthropic", or "groq" (defaults to "bedrock").
+ * @property {string|null} [llmModel] - Concrete model id for the provider; null = provider default.
+ * @property {number} [temperature] - Sampling temperature (0-2).
+ */
+
+/**
+ * @typedef {Object} UpdateAgentProfileData
+ * @property {string} [name] - The agent's name.
+ * @property {string} [status] - Lifecycle status: "active" or "inactive".
+ * @property {string} [systemPrompt] - Base system prompt composed into every conversation.
+ * @property {string} [greeting] - Opening line the agent leads with.
+ * @property {string} [guardrails] - Freeform guardrail instructions appended to the composed prompt.
+ * @property {string|null} [voiceId] - ElevenLabs voice id for the voice channel.
+ * @property {string} [llmProvider] - LLM backend: "bedrock", "openai", "anthropic", or "groq".
+ * @property {string|null} [llmModel] - Concrete model id for the provider; null = provider default.
+ * @property {number} [temperature] - Sampling temperature (0-2).
+ */
+
+export class Agents {
+	constructor(client, enableAdmin) {
+		this.client = client;
+		this.enableAdmin = enableAdmin;
+	}
+
+	/**
+	 * List the agent profiles under a group.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for listing agent profiles.
+	 * @param {string} params.groupId - The group whose profiles to list (required).
+	 * @param {number} [params.page] - The page number for pagination.
+	 * @param {number} [params.limit] - The number of items per page for pagination.
+	 * @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 list of agent profiles returned from the server.
+	 */
+	async getAgentProfiles({ groupId, page, limit, options = {} }) {
+		this.client._require({ groupId });
+		const queryString = this.client._getQueryString({ groupId, page, limit });
+		return this.client(`/agent/profiles${queryString}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Get a single agent profile by id.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for getting an agent profile.
+	 * @param {string} params.agentProfileId - The id of the agent profile to fetch.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if the agentProfileId parameter is missing.
+	 * @returns {Promise<Object>} - The agent profile returned from the server.
+	 */
+	async getAgentProfile({ agentProfileId, options = {} }) {
+		this.client._require({ agentProfileId });
+		const safeId = encodeURIComponent(agentProfileId);
+		return this.client(`/agent/profiles/${safeId}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Create a new agent profile.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for creating an agent profile (see CreateAgentProfileData typedef).
+	 * @param {CreateAgentProfileData} params.profileData - The data for the agent profile to create, including required fields groupId and name.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if the profileData parameter is missing.
+	 * @returns {Promise<Object>} - The created agent profile returned from the server.
+	 */
+	async createAgentProfile({ profileData, options = {} }) {
+		this.client._require({ profileData });
+		return this.client(`/agent/profiles`, { method: "POST", body: profileData, ...options });
+	}
+
+	/**
+	 * Update an existing agent profile.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for updating an agent profile (see UpdateAgentProfileData typedef).
+	 * @param {string} params.id - The id of the agent profile to update.
+	 * @param {UpdateAgentProfileData} params.updateData - The data for the agent profile to update.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if the id or updateData parameter is missing.
+	 * @returns {Promise<Object>} - The updated agent profile returned from the server.
+	 */
+	async updateAgentProfile({ id, updateData, options = {} }) {
+		this.client._require({ id, updateData });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/agent/profiles/${safeId}`, { method: "PUT", body: updateData, ...options });
+	}
+
+	/**
+	 * Delete (inactivate) an agent profile by its id.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for deleting an agent profile.
+	 * @param {string} params.id - The id of the agent profile to delete.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if the id parameter is missing.
+	 * @returns {Promise<Object>} - The inactivated agent profile returned from the server.
+	 */
+	async deleteAgentProfile({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/agent/profiles/${safeId}`, { method: "DELETE", ...options });
+	}
+
+	/**
+	 * Send a message to an agent and get its reply — the app-native conversation
+	 * endpoint (webchat / SMS). Omit conversationId to start a new conversation, or
+	 * pass one to continue an existing one. Runs the agent's LLM tool loop server-side
+	 * and returns the assistant's reply along with any tools it invoked.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for sending a message.
+	 * @param {string} params.agentProfileId - The agent to talk to (required).
+	 * @param {string} params.channel - The channel: "webchat", "sms", or "voice" (required).
+	 * @param {string} params.message - The user's message (required).
+	 * @param {string} [params.conversationId] - Continue this conversation; omit to start a new one.
+	 * @param {string} [params.contactIdentifier] - The far-end identifier (webchat visitor id, sender number).
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if agentProfileId, channel, or message is missing.
+	 * @returns {Promise<Object>} - `{ conversationId, conversationSessionId, reply, toolInvocations, ok }` from the server.
+	 */
+	async sendAgentMessage({ agentProfileId, channel, message, conversationId, contactIdentifier, options = {} }) {
+		this.client._require({ agentProfileId, channel, message });
+		const body = { agentProfileId, channel, message };
+		if (conversationId !== undefined && conversationId !== null) body.conversationId = conversationId;
+		if (contactIdentifier !== undefined && contactIdentifier !== null) body.contactIdentifier = contactIdentifier;
+		return this.client(`/agent/messages`, { method: "POST", body, ...options });
+	}
+
+	/**
+	 * List an agent's per-channel settings (the tools enabled per channel, whether the
+	 * channel is on, and any channel-specific prompt/greeting).
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for listing channel settings.
+	 * @param {string} params.agentProfileId - The agent whose channel settings to list.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if the agentProfileId parameter is missing.
+	 * @returns {Promise<Object>} - The agent's channel settings returned from the server.
+	 */
+	async getAgentChannelSettings({ agentProfileId, options = {} }) {
+		this.client._require({ agentProfileId });
+		const safeId = encodeURIComponent(agentProfileId);
+		return this.client(`/agent/profiles/${safeId}/channels`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Get a single per-channel setting for an agent.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for getting a channel setting.
+	 * @param {string} params.agentProfileId - The agent the setting belongs to.
+	 * @param {string} params.channel - The channel: "webchat", "sms", or "voice".
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if agentProfileId or channel is missing.
+	 * @returns {Promise<Object>} - The channel setting returned from the server.
+	 */
+	async getAgentChannelSetting({ agentProfileId, channel, options = {} }) {
+		this.client._require({ agentProfileId, channel });
+		const safeId = encodeURIComponent(agentProfileId);
+		const safeChannel = encodeURIComponent(channel);
+		return this.client(`/agent/profiles/${safeId}/channels/${safeChannel}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Create or update (upsert) an agent's per-channel setting. One row per (agent, channel);
+	 * the channel is taken from the path, the fields from settingData.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for the upsert.
+	 * @param {string} params.agentProfileId - The agent the setting belongs to.
+	 * @param {string} params.channel - The channel: "webchat", "sms", or "voice".
+	 * @param {Object} [params.settingData] - The fields to set: allowedTools (string[]), enabled (boolean), channelPrompt (string), greeting (string|null).
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if agentProfileId or channel is missing.
+	 * @returns {Promise<Object>} - The created or updated channel setting returned from the server.
+	 */
+	async upsertAgentChannelSetting({ agentProfileId, channel, settingData = {}, options = {} }) {
+		this.client._require({ agentProfileId, channel });
+		const safeId = encodeURIComponent(agentProfileId);
+		const safeChannel = encodeURIComponent(channel);
+		return this.client(`/agent/profiles/${safeId}/channels/${safeChannel}`, { method: "PUT", body: settingData, ...options });
+	}
+
+	/**
+	 * Delete an agent's per-channel setting.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for the delete.
+	 * @param {string} params.agentProfileId - The agent the setting belongs to.
+	 * @param {string} params.channel - The channel: "webchat", "sms", or "voice".
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if agentProfileId or channel is missing.
+	 * @returns {Promise<Object>} - The delete confirmation returned from the server.
+	 */
+	async deleteAgentChannelSetting({ agentProfileId, channel, options = {} }) {
+		this.client._require({ agentProfileId, channel });
+		const safeId = encodeURIComponent(agentProfileId);
+		const safeChannel = encodeURIComponent(channel);
+		return this.client(`/agent/profiles/${safeId}/channels/${safeChannel}`, { method: "DELETE", ...options });
+	}
+
+	/**
+	 * Read the tenant AI settings for a scope (group, or a subgroup within it) — brand, tone,
+	 * timezone, business hours, and after-hours message. Returns the scope's own row only (no
+	 * group-level fallback).
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for reading tenant settings.
+	 * @param {string} params.groupId - The group (required).
+	 * @param {string} [params.subgroupId] - The subgroup; omit for the group-level settings.
+	 * @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 tenant settings returned from the server.
+	 */
+	async getTenantAiSettings({ groupId, subgroupId, options = {} }) {
+		this.client._require({ groupId });
+		const queryString = this.client._getQueryString({ groupId, subgroupId });
+		return this.client(`/agent/tenant-settings${queryString}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Create or update (upsert) the tenant AI settings for a scope. The scope is identified by
+	 * the query params; the body carries the settings fields.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for the upsert.
+	 * @param {string} params.groupId - The group (required).
+	 * @param {string} [params.subgroupId] - The subgroup; omit for the group-level settings.
+	 * @param {Object} [params.settingsData] - Fields to set: brandName (string), tone (string), timezone (IANA string), businessHours (array of {day, closed, open, close}), afterHoursMessage (string).
+	 * @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 created or updated tenant settings returned from the server.
+	 */
+	async upsertTenantAiSettings({ groupId, subgroupId, settingsData = {}, options = {} }) {
+		this.client._require({ groupId });
+		const queryString = this.client._getQueryString({ groupId, subgroupId });
+		return this.client(`/agent/tenant-settings${queryString}`, { method: "PUT", body: settingsData, ...options });
+	}
+
+	/**
+	 * Delete the tenant AI settings for a scope.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for the delete.
+	 * @param {string} params.groupId - The group (required).
+	 * @param {string} [params.subgroupId] - The subgroup; omit for the group-level settings.
+	 * @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 delete confirmation returned from the server.
+	 */
+	async deleteTenantAiSettings({ groupId, subgroupId, options = {} }) {
+		this.client._require({ groupId });
+		const queryString = this.client._getQueryString({ groupId, subgroupId });
+		return this.client(`/agent/tenant-settings${queryString}`, { method: "DELETE", ...options });
+	}
+
+	/**
+	 * List the knowledge-base items an agent can answer from (RAG), scoped to a group and
+	 * optionally narrowed to a subgroup and/or a single agent.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for listing knowledge items.
+	 * @param {string} params.groupId - The group whose knowledge to list (required).
+	 * @param {string} [params.subgroupId] - Narrow to a subgroup.
+	 * @param {string} [params.agentProfileId] - Narrow to one agent.
+	 * @param {number} [params.page] - Page number (1-based) for pagination.
+	 * @param {number} [params.limit] - Items per page (max 100; server default 25).
+	 * @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 knowledge items returned from the server.
+	 */
+	async getKnowledgeItems({ groupId, subgroupId, agentProfileId, page, limit, options = {} }) {
+		this.client._require({ groupId });
+		const queryString = this.client._getQueryString({ groupId, subgroupId, agentProfileId, page, limit });
+		return this.client(`/agent/knowledge${queryString}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Get a single knowledge item by id.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for getting a knowledge item.
+	 * @param {string} params.knowledgeItemId - The id of the knowledge item to fetch.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if the knowledgeItemId parameter is missing.
+	 * @returns {Promise<Object>} - The knowledge item returned from the server.
+	 */
+	async getKnowledgeItem({ knowledgeItemId, options = {} }) {
+		this.client._require({ knowledgeItemId });
+		const safeId = encodeURIComponent(knowledgeItemId);
+		return this.client(`/agent/knowledge/${safeId}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Create a knowledge item. The raw `text` is stored and Atlas Vector Search owns the
+	 * embedding — there is no embedding to supply.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for creating a knowledge item.
+	 * @param {Object} params.itemData - The knowledge fields. Required: groupId (starts with 'G'), text.
+	 *                                   Optional: subgroupId (starts with 'S', nullable), agentProfileId
+	 *                                   (nullable = shared across the tenant's agents), title, source
+	 *                                   ("manual" | "url" | "document" | "import"), enabled (boolean), metadata (object|null).
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if the itemData parameter is missing.
+	 * @returns {Promise<Object>} - The created knowledge item returned from the server.
+	 */
+	async createKnowledgeItem({ itemData, options = {} }) {
+		this.client._require({ itemData });
+		return this.client(`/agent/knowledge`, { method: "POST", body: itemData, ...options });
+	}
+
+	/**
+	 * Update a knowledge item. The item's scope (group/subgroup/agent) is immutable and
+	 * cannot be changed.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for updating a knowledge item.
+	 * @param {string} params.id - The id of the knowledge item to update.
+	 * @param {Object} params.updateData - The fields to update: title, text, source, enabled, metadata.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if the id or updateData parameter is missing.
+	 * @returns {Promise<Object>} - The updated knowledge item returned from the server.
+	 */
+	async updateKnowledgeItem({ id, updateData, options = {} }) {
+		this.client._require({ id, updateData });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/agent/knowledge/${safeId}`, { method: "PUT", body: updateData, ...options });
+	}
+
+	/**
+	 * Delete a knowledge item by its id.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for deleting a knowledge item.
+	 * @param {string} params.id - The id of the knowledge item to delete.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if the id parameter is missing.
+	 * @returns {Promise<Object>} - The delete confirmation returned from the server.
+	 */
+	async deleteKnowledgeItem({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/agent/knowledge/${safeId}`, { method: "DELETE", ...options });
+	}
+
+	/**
+	 * List the tools defined under a group — custom webhook tools, configured built-ins, and
+	 * (future) MCP. `webhookAuth` secrets are redacted in the response.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for listing tools.
+	 * @param {string} params.groupId - The group whose tools to list (required).
+	 * @param {string} [params.subgroupId] - Narrow to a subgroup.
+	 * @param {string} [params.agentProfileId] - Narrow to one agent.
+	 * @param {string} [params.type] - Narrow to a tool type: "builtin", "webhook", or "mcp".
+	 * @param {number} [params.page] - Page number (1-based) for pagination.
+	 * @param {number} [params.limit] - Items per page (max 100; server default 25).
+	 * @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 tools returned from the server (secrets redacted).
+	 */
+	async getAgentTools({ groupId, subgroupId, agentProfileId, type, page, limit, options = {} }) {
+		this.client._require({ groupId });
+		const queryString = this.client._getQueryString({ groupId, subgroupId, agentProfileId, type, page, limit });
+		return this.client(`/agent/tools${queryString}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Get a single agent tool by id. `webhookAuth` secrets are redacted in the response.
+	 * @async
+	 * @roles api, admin, developer, billing, user
+	 * @param {Object} params - The parameters for getting a tool.
+	 * @param {string} params.agentToolId - The id of the tool to fetch.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if the agentToolId parameter is missing.
+	 * @returns {Promise<Object>} - The tool returned from the server (secrets redacted).
+	 */
+	async getAgentTool({ agentToolId, options = {} }) {
+		this.client._require({ agentToolId });
+		const safeId = encodeURIComponent(agentToolId);
+		return this.client(`/agent/tools/${safeId}`, { method: "GET", ...options });
+	}
+
+	/**
+	 * Create an agent tool. For a webhook tool, `webhookUrl` must be an https URL that does not
+	 * target a private/internal address (rejected otherwise). `webhookAuth` is stored and never
+	 * echoed back.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for creating a tool.
+	 * @param {Object} params.toolData - The tool fields. Required: groupId (starts with 'G'), name, description.
+	 *                                   Type-specific: type ("builtin" | "webhook" | "mcp"); webhook → webhookUrl, builtin →
+	 *                                   builtinKey, mcp → mcpServerUrl. Optional: subgroupId, agentProfileId (nullable = shared),
+	 *                                   parametersSchema, config, channels (string[]), enabled (boolean), and webhookAuth —
+	 *                                   which MUST be `{ headers?: { [name]: value }, signingSecret?: string }` (any other shape,
+	 *                                   e.g. `{ header, value }`, is rejected with a 400). `headers` are sent verbatim on every
+	 *                                   call (reserved/framing and `x-signalhouse-*` names are rejected); `signingSecret` makes us
+	 *                                   send `X-SignalHouse-Signature: sha256=HMAC-SHA256(`${X-SignalHouse-Timestamp}.${rawBody}`)`
+	 *                                   so you can verify the call and reject replays. Stored, never returned.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if the toolData parameter is missing.
+	 * @returns {Promise<Object>} - The created tool returned from the server (secrets redacted).
+	 */
+	async createAgentTool({ toolData, options = {} }) {
+		this.client._require({ toolData });
+		return this.client(`/agent/tools`, { method: "POST", body: toolData, ...options });
+	}
+
+	/**
+	 * Update an agent tool. The tool's scope (group/subgroup/agent) is immutable. A supplied
+	 * `webhookUrl` is SSRF-checked.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for updating a tool.
+	 * @param {string} params.id - The id of the tool to update.
+	 * @param {Object} params.updateData - The fields to update: name, description, type, builtinKey, parametersSchema, config, webhookUrl, webhookAuth, mcpServerUrl, channels, enabled.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if the id or updateData parameter is missing.
+	 * @returns {Promise<Object>} - The updated tool returned from the server (secrets redacted).
+	 */
+	async updateAgentTool({ id, updateData, options = {} }) {
+		this.client._require({ id, updateData });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/agent/tools/${safeId}`, { method: "PUT", body: updateData, ...options });
+	}
+
+	/**
+	 * Delete an agent tool by its id.
+	 * @async
+	 * @roles api, admin, developer
+	 * @param {Object} params - The parameters for deleting a tool.
+	 * @param {string} params.id - The id of the tool to delete.
+	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
+	 * @throws {Error} Throws an error if the id parameter is missing.
+	 * @returns {Promise<Object>} - The delete confirmation returned from the server.
+	 */
+	async deleteAgentTool({ id, options = {} }) {
+		this.client._require({ id });
+		const safeId = encodeURIComponent(id);
+		return this.client(`/agent/tools/${safeId}`, { method: "DELETE", ...options });
+	}
+}

package/src/domains/Campaigns.js

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

package/src/domains/Messages.js

@@ -5,6 +5,16 @@ export class Messages {
 		this.enableAdmin = enableAdmin;
 	}
 
+	/**
+	 * Estimate Canadian SMS/MMS retail cost without sending or charging.
+	 * @async
+	 * @param {Object} params - Sender, up to 100 recipients, messageBody and request options.
+	 * @returns {Promise<Object>} - Per-recipient rates and total in microdollars; unknown carriers use the upper fallback.
+	 */
+	async estimateMessage({ senderPhoneNumber, recipientPhoneNumbers, messageBody, messageType = "SMS", options = {} }) {
+		return this.client("/message/estimate", { method: "POST", body: { senderPhoneNumber, recipientPhoneNumbers, messageBody, messageType }, ...options });
+	}
+
 	/**
 	 * Get a list of messages with optional filters and pagination parameters
 	 * @async
@@ -18,7 +28,7 @@ export class Messages {
 	 * @param {string} [params.status] - Filter messages by their status (ENQUEUED, DEQUEUED, SENT, FAILED, DELIVERED)
 	 * @param {string} [params.direction] - Filter messages by their direction (INBOUND, OUTBOUND)
 	 * @param {string|string[]} [params.messageType] - Filter messages by their type. Accepts a single value or an array (e.g. ["SMS", "MMS"]). Allowed values: SMS, MMS, RCS, WHATSAPP, VIBER, P2P. When omitted, defaults to all non-P2P types.
-	 * @param {string|string[]} [params.channel] - Filter messages by channel. Accepts a single value or an array. Allowed values: tenDLC, tollFree, shortCode, p2p. Each message records its channel when it is saved, and this filters on that stored value; older messages from before this feature have no channel and count as tenDLC. Ignored when matchAny is true (matchAny takes precedence).
+	 * @param {string|string[]} [params.channel] - Filter messages by channel. Accepts a single value or an array. Allowed values: tenDLC, virtualLongCode, tollFree, shortCode, p2p. Each message records its channel when it is saved, and this filters on that stored value; older messages from before this feature have no channel and count as tenDLC. Ignored when matchAny is true (matchAny takes precedence).
 	 * @param {boolean} [params.matchAny] - When true, the provided campaignId/brandId/phoneNumber filters are OR'd (a message matches ANY of them) instead of the default most-specific-single behavior. subgroupId stays an AND scope. Opt-in/additive.
 	 * @param {string} [params.carrier] - Filter messages by the carrier used for sending
 	 * @param {string|string[]} [params.sentimentLabel] - Filter messages by sentiment bucket. Accepts a single value or an array (e.g. ["positive", "negative"]). Allowed values: positive, neutral, negative. Applied as the sentimentScore range the ±25 label threshold produces, so unscored messages match no bucket and outbound messages (never scored) are excluded.
@@ -95,11 +105,12 @@ export class Messages {
 	 * @param {string|string[]} [params.campaignId] - Filter analytics by the ID of the associated campaign. Accepts a single value, an array, or a comma-separated string.
 	 * @param {string|string[]} [params.phoneNumber] - Filter analytics by the phone number involved in the messages. Accepts a single value, an array, or a comma-separated string.
 	 * @param {string|string[]} [params.carrier] - Filter analytics by the carrier used for sending. Accepts a single value, an array, or a comma-separated string.
+	 * @param {string|string[]} [params.carrierFamily] - Filter analytics by the recipient's resolved carrier family (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P). Accepts a single value, an array, or a comma-separated string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
 	 * @param {string} [params.startDate] - ISO-8601 date or timestamp; normalized to start-of-UTC-day (inclusive)
 	 * @param {string} [params.endDate] - ISO-8601 date or timestamp; normalized to end-of-UTC-day (inclusive). Hourly resolution is not supported
 	 * @param {boolean} [params.matchAny] - When true, the provided campaignId/brandId/phoneNumber filters are OR'd (match ANY) instead of the default most-specific-single behavior. subgroupId stays an AND scope. Opt-in/additive.
 	 * @param {(string|string[])} [params.messageType] - Message type(s) the SENTIMENT figures are scoped to: SMS, MMS or P2P (single value, array, or comma-separated string). Omit for all scored types. Does NOT narrow the message counts, which are always returned split per type (smsInbound/mmsInbound/p2pInbound) and have no filterable type dimension.
-	 * @param {string|string[]} [params.channel] - Filter analytics by channel (tenDLC, tollFree, shortCode, p2p). Filters on the stored channel column; a tenDLC selection also includes older messages that have no channel, and p2p is a real channel here (matched by carrier). Accepts a single value or an array. Ignored when matchAny is true (matchAny takes precedence).
+	 * @param {string|string[]} [params.channel] - Filter analytics by channel (tenDLC, virtualLongCode, tollFree, shortCode, p2p). Filters on the stored channel column; a tenDLC selection also includes older messages that have no channel, and p2p is a real channel here (matched by carrier). Accepts a single value or an array. Ignored when matchAny is true (matchAny takes precedence).
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
 	 * @returns {Promise<Object>} - A promise that resolves to the analytics data. Also includes inbound-message
 	 * sentiment for the requested scope: sentimentScore (volume-weighted average of every scored inbound message
@@ -110,8 +121,8 @@ export class Messages {
 	 * summed or re-averaged across types, rows or responses. To weight a subset of message types, pass
 	 * messageType and read sentimentScore.
 	 */
-	async getAnalytics({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel, messageType, matchAny, options = {} }) {
-		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel, messageType, matchAny };
+	async getAnalytics({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, carrierFamily, startDate, endDate, channel, messageType, matchAny, options = {} }) {
+		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, carrierFamily, startDate, endDate, channel, messageType, matchAny };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/message/analytics${queryString}`, { method: "GET", ...options });
 	}
@@ -127,10 +138,13 @@ export class Messages {
 	 * @param {string|string[]} [params.campaignId] - Filter analytics by the ID of the associated campaign. Accepts a single value, an array, or a comma-separated string.
 	 * @param {string|string[]} [params.phoneNumber] - Filter analytics by the phone number involved in the messages. Accepts a single value, an array, or a comma-separated string.
 	 * @param {string|string[]} [params.carrier] - Filter analytics by the carrier used for sending. Accepts a single value, an array, or a comma-separated string.
-	 * @param {string} [params.startDate] - ISO-8601 date or timestamp; normalized to start-of-UTC-day (inclusive)
-	 * @param {string} [params.endDate] - ISO-8601 date or timestamp; normalized to end-of-UTC-day (inclusive). Hourly resolution is not supported
+	 * @param {string|string[]} [params.carrierFamily] - Filter analytics by the recipient's resolved carrier family (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P). Accepts a single value, an array, or a comma-separated string. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
+	 * @param {string} [params.startDate] - ISO-8601 date or timestamp. At day granularity it is normalized to start-of-UTC-day (inclusive); at hour granularity it is floored to its hour.
+	 * @param {string} [params.endDate] - ISO-8601 date or timestamp. At day granularity it is normalized to end-of-UTC-day (inclusive); at hour granularity it is honoured as given.
 	 * @param {(string|string[])} [params.messageType] - Message type(s) the SENTIMENT figures are scoped to: SMS, MMS or P2P (single value, array, or comma-separated string). Omit for all scored types. Does NOT narrow the message counts, which are always returned split per type (smsInbound/mmsInbound/p2pInbound) and have no filterable type dimension.
-	 * @param {string|string[]} [params.channel] - Filter analytics by channel (tenDLC, tollFree, shortCode, p2p). Filters on the stored channel column; a tenDLC selection also includes older messages that have no channel, and p2p is a real channel here. Accepts a single value or an array.
+	 * @param {string|string[]} [params.channel] - Filter analytics by channel (tenDLC, virtualLongCode, tollFree, shortCode, p2p). Filters on the stored channel column; a tenDLC selection also includes older messages that have no channel, and p2p is a real channel here. Accepts a single value or an array.
+	 * @param {("day"|"hour")} [params.granularity] - Time-bucket grain of the byDate rows. Omit for day (each row's _id is a "YYYY-MM-DD" date). "hour" buckets by hour (each row's _id is a "YYYY-MM-DD HH:MM:SS" UTC hour) and is capped to a 7-day span. Only accepted where the environment serves hourly analytics; elsewhere any value, including "day", is rejected with a 400 -- omit the parameter unless hour grain is wanted.
+	 * @param {("carrier"|"carrierFamily")} [params.breakdown] - Adds a byBreakdown time × dimension series to the response ({ dimension, rows }: each row is one byDate bucket (_id) for one carrier or carrier family (key), over the top 50 keys by volume, 10DLC only) and caps the span at 31 days. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
 	 * @returns {Promise<Array>} - A promise that resolves to an array of analytics snapshot records. cardTotals and
 	 * every byDate/byPhoneNumber/byCarrier row also carry that row's own inbound-message sentiment: sentimentScore
@@ -140,8 +154,8 @@ export class Messages {
 	 * score is divided server-side and the raw sums are never returned: a score is an average and must never be
 	 * summed or re-averaged across types, rows or responses.
 	 */
-	async getAnalyticsDetail({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel, messageType, options = {} }) {
-		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel, messageType };
+	async getAnalyticsDetail({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, carrierFamily, startDate, endDate, channel, messageType, granularity, breakdown, options = {} }) {
+		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, carrierFamily, startDate, endDate, channel, messageType, granularity, breakdown };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/message/analytics/detail${queryString}`, { method: "GET", ...options });
 	}
@@ -174,18 +188,19 @@ export class Messages {
 	 * @param {string|string[]} [params.campaignId]
 	 * @param {string|string[]} [params.phoneNumber]
 	 * @param {string|string[]} [params.carrier]
+	 * @param {string|string[]} [params.carrierFamily] - Resolved carrier family of the recipient (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P); single value, array, or comma-separated. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
 	 * @param {string} [params.startDate]
 	 * @param {string} [params.endDate]
 	 * @param {number} [params.page=1]
 	 * @param {number} [params.limit=50] - max 50 per page
-	 * @param {("tenDLC"|"tollFree"|"shortCode"|"p2p"|"both")|Array<"tenDLC"|"tollFree"|"shortCode"|"p2p">} [params.channel="both"] - Filter and rank rows by the stored channel column. "both" (default) means all activity. tenDLC/tollFree/shortCode/p2p (single value or array) limit to the selected channel(s).
+	 * @param {("tenDLC"|"virtualLongCode"|"tollFree"|"shortCode"|"p2p"|"both")|Array<"tenDLC"|"virtualLongCode"|"tollFree"|"shortCode"|"p2p">} [params.channel="both"] - Filter and rank rows by the stored channel column. "both" (default) means all activity. tenDLC/virtualLongCode/tollFree/shortCode/p2p (single value or array) limit to the selected channel(s).
 	 * @param {(string|string[])} [params.messageType] - Message type(s) the SENTIMENT figures are scoped to: SMS, MMS or P2P (single value, array, or comma-separated string). Omit for all scored types. Does NOT narrow the message counts, which are always returned split per type (smsInbound/mmsInbound/p2pInbound) and have no filterable type dimension.
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options]
 	 * @returns {Promise<Object>} - { rows, totalCount, page, limit }. Each row carries sms/mms/p2p metric columns plus `smsOptOuts` and `mmsOptOuts` from the DNC analytics MV (P2P has no opt-outs).
 	 * Each row also carries that subgroup's inbound-message sentiment: `sentimentScore` (volume-weighted average of every scored inbound message in that subgroup, -100..100, null when nothing was scored), `sentimentLabel`, `sentimentScoredCount`, `sentimentPositive`, `sentimentNeutral`, `sentimentNegative`, plus the same six per message type under `smsSentiment*`, `mmsSentiment*` and `p2pSentiment*` prefixes. The score is derived server-side and must never be re-averaged across rows — combine the counts, not the scores.
 	 */
-	async getAnalyticsBySubgroup({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, page, limit, channel, messageType, options = {} }) {
-		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, page, limit, channel, messageType };
+	async getAnalyticsBySubgroup({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, carrierFamily, startDate, endDate, page, limit, channel, messageType, options = {} }) {
+		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, carrierFamily, startDate, endDate, page, limit, channel, messageType };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/message/analytics/by-subgroup${queryString}`, { method: "GET", ...options });
 	}
@@ -202,16 +217,17 @@ export class Messages {
 	 * @param {string|string[]} [params.campaignId]
 	 * @param {string|string[]} [params.phoneNumber]
 	 * @param {string|string[]} [params.carrier]
+	 * @param {string|string[]} [params.carrierFamily] - Resolved carrier family of the recipient (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile, P2P); single value, array, or comma-separated. Only accepted where the environment serves hourly analytics; elsewhere any value is rejected with a 400 -- omit the parameter unless it is wanted.
 	 * @param {string} [params.startDate]
 	 * @param {string} [params.endDate]
 	 * @param {number} [params.page=1]
 	 * @param {number} [params.limit=50] - max 50 per page
-	 * @param {("tenDLC"|"tollFree"|"shortCode"|"p2p"|"both")|Array<"tenDLC"|"tollFree"|"shortCode"|"p2p">} [params.channel="both"] - Filter and rank rows by the stored channel column. "both" (default) means every code. tenDLC/tollFree/shortCode/p2p (single value or array) limit to the selected channel(s); when one channel is selected, totalErrors reflects only that channel.
+	 * @param {("tenDLC"|"virtualLongCode"|"tollFree"|"shortCode"|"p2p"|"both")|Array<"tenDLC"|"virtualLongCode"|"tollFree"|"shortCode"|"p2p">} [params.channel="both"] - Filter and rank rows by the stored channel column. "both" (default) means every code. tenDLC/virtualLongCode/tollFree/shortCode/p2p (single value or array) limit to the selected channel(s); when one channel is selected, totalErrors reflects only that channel.
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options]
 	 * @returns {Promise<Object>} - { rows, totalCount, totalErrors: { sms, mms, p2p, all }, page, limit }
 	 */
-	async getAnalyticsByErrorCode({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, page, limit, channel, options = {} }) {
-		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, page, limit, channel };
+	async getAnalyticsByErrorCode({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, carrierFamily, startDate, endDate, page, limit, channel, options = {} }) {
+		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, carrierFamily, startDate, endDate, page, limit, channel };
 		const queryString = this.client._getQueryString(filters);
 		return this.client(`/message/analytics/by-error-code${queryString}`, { method: "GET", ...options });
 	}
@@ -229,9 +245,9 @@ export class Messages {
 	 * @param {string} [params.carrier] - Filter by the carrier
 	 * @param {string} [params.startDate] - ISO-8601 date or timestamp; normalized to start-of-UTC-day (inclusive)
 	 * @param {string} [params.endDate] - ISO-8601 date or timestamp; normalized to end-of-UTC-day (inclusive). Hourly resolution is not supported
-	 * @param {string|string[]} [params.channel] - Filter by channel (tenDLC, tollFree, shortCode). Opt-outs are A2P-only, so p2p applies no filter. Filters on the stored channel column; a tenDLC selection also includes older opt-outs that have no channel.
+	 * @param {string|string[]} [params.channel] - Filter by channel (tenDLC, virtualLongCode, tollFree, shortCode). Opt-outs are A2P-only, so p2p applies no filter. Filters on the stored channel column; a tenDLC selection also includes older opt-outs that have no channel.
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} - A promise that resolves to the DNC analytics data (totals, byDate, byPhoneNumber, byCarrier)
+	 * @returns {Promise<Object>} - A promise that resolves to the DNC analytics data (totals, byDate, byPhoneNumber, byCarrier, byKeyword). byKeyword breaks opt-outs down by the normalized keyword that revoked consent ({ optOutKeyword, total, sms, mms }); opt-outs recorded before keyword capture shipped appear as a single optOutKeyword: null bucket ("not recorded"). The distinct keyword set is open-ended (campaigns register their own keywords beyond the mandatory floor) — render top-N plus Other, never a fixed list.
 	 */
 	async getDncAnalytics({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel, options = {} }) {
 		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, channel };
@@ -256,9 +272,9 @@ export class Messages {
 	 * @param {number} [params.limit] - Number of records per page
 	 * @param {string} [params.sortField] - Field to sort by
 	 * @param {string} [params.sortOrder] - Sort direction (asc, desc)
-	 * @param {string|string[]} [params.channel] - Filter by channel (tenDLC, tollFree, shortCode). Opt-outs are A2P-only, so p2p applies no filter. Filters on the stored channel column; a tenDLC selection also includes older opt-outs that have no channel.
+	 * @param {string|string[]} [params.channel] - Filter by channel (tenDLC, virtualLongCode, tollFree, shortCode). Opt-outs are A2P-only, so p2p applies no filter. Filters on the stored channel column; a tenDLC selection also includes older opt-outs that have no channel.
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} - A promise that resolves to the paginated DNC records
+	 * @returns {Promise<Object>} - A promise that resolves to the paginated DNC records. Each record carries optOutKeyword — the normalized keyword that revoked consent (e.g. "stop", "opt out"; a repeat opt-out records the most recent word), null for opt-outs recorded before keyword capture shipped — and carrierFamily, the resolved carrier family of the recipient number (Default, ATT, TMobile, Verizon, USCellular, GoogleVoice, ClearSky, Interop, RogueMobile), copied from the inbound message that triggered the opt-out.
 	 */
 	async getDncRecords({ groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, page, limit, sortField, sortOrder, channel, options = {} }) {
 		const filters = { groupId, subgroupId, brandId, campaignId, phoneNumber, carrier, startDate, endDate, page, limit, sortField, sortOrder, channel };
@@ -282,7 +298,7 @@ export class Messages {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for sending an SMS message
 	 * @param {string} params.senderPhoneNumber - The 5-6 digit Short Code or 10+ digit phone number to send the message from
-	 * @param {string|string[]} params.recipientPhoneNumbers - The phone number(s) to send the message to
+	 * @param {string|string[]} params.recipientPhoneNumbers - The 10+ digit phone number(s) to send the message to. A Short Code sender permits exactly one recipient, and it must be a +1 (US/Canada) number; a bare 10-digit number is treated as +1. The API rejects Short Code sends with multiple recipients or a non-+1 recipient.
 	 * @param {string} params.messageBody - The body of the SMS message
 	 * @param {string} [params.statusCallbackUrl] - The URL to receive status callbacks
 	 * @param {boolean} [params.enableShortlink=false] - Whether to enable shortlink in the message
@@ -363,7 +379,7 @@ export class Messages {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for sending an MMS message
 	 * @param {string} params.senderPhoneNumber - The 5-6 digit Short Code or 10+ digit phone number to send the message from
-	 * @param {string[]} params.recipientPhoneNumbers - The phone number(s) to send the message to
+	 * @param {string[]} params.recipientPhoneNumbers - The 10+ digit phone number(s) to send the message to. A Short Code sender permits exactly one recipient, and it must be a +1 (US/Canada) number; a bare 10-digit number is treated as +1. The API rejects Short Code sends with multiple recipients or a non-+1 recipient.
 	 * @param {string} params.messageBody - The body of the MMS message
 	 * @param {string[]} [params.mediaUrls] - The URLs of the media attachments
 	 * @param {string} [params.statusCallbackUrl] - The URL to receive status callbacks

package/src/domains/Numbers.js

@@ -86,6 +86,14 @@ export class Numbers {
    * window, which is not the same as a score of 0 -- null means nobody replied, 0 means replies
    * averaged neutral. `updatedAt` is null until the first rollup writes the record, and it tracks when
    * the figures last CHANGED, not when the job last ran.
+   *
+   * Every record also carries a `health` object -- trailing 7-day and 30-day delivery/opt-out health from
+   * the same periodic refresh: `{ sevenDay, thirtyDay, updatedAt }`, each window being `{ score,
+   * deliveryRate, optOutRate, deliveryScore, optOutScore, messagesSent, messagesDelivered, messagesFailed,
+   * optOuts }`. `score` is 1.0..10.0 (the mean of the two bucket scores) and is null when nothing was sent
+   * in the window; the volumes say how much traffic sits behind it. A campaign's figure is scored from the
+   * campaign's own summed counters, never averaged from its numbers. For a live figure use GET /number/health
+   * or GET /campaign/health.
    * @returns {Promise<Object>} A promise that resolves to the list of phone numbers
    */
   async getPhoneNumbers({ phoneNumber, campaignId, brandId, subgroupId, groupId, page, limit, options = {} }) {
@@ -120,6 +128,7 @@ export class Numbers {
    * @param {boolean} [params.voiceEnabled] - Filter for phone numbers that are voice enabled
    * @param {string} [params.country] - Filter by country code (e.g., "US")
    * @param {string} [params.state] - Filter by state code (e.g., "CA")
+   * @param {string} [params.city] - City prefix; requires country US/CA and state/province.
    * @param {string} [params.npa] - Filter by NPA (area code)
    * @param {string} [params.nxx] - Filter by NXX (central office code) - the first three digits of the local phone number after the area code
    * @param {string} [params.phoneNumber] - Filter by phone number
@@ -134,6 +143,7 @@ export class Numbers {
     voiceEnabled,
     country,
     state,
+    city,
     npa,
     nxx,
     phoneNumber,
@@ -141,7 +151,7 @@ export class Numbers {
     page,
     options = {},
   }) {
-    const filters = { smsEnabled, mmsEnabled, voiceEnabled, country, state, npa, nxx, phoneNumber, limit, page };
+    const filters = { smsEnabled, mmsEnabled, voiceEnabled, country, state, city, npa, nxx, phoneNumber, limit, page };
     const queryString = this.client._getQueryString(filters);
     return this.client(`/number/available${queryString}`, { method: 'GET', ...options });
   }
@@ -156,13 +166,14 @@ export class Numbers {
    * @param {Object} params - The parameters for purchasing phone numbers
    * @param {string[]} params.phoneNumbers - The list of phone numbers to purchase
    * @param {string} params.subgroupId - The ID of the subgroup to assign the purchased phone numbers to
+   * @param {'US'|'CA'} [params.country='US'] - ISO-2 purchase country. Toll-Free always uses the shared registry.
    * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the phoneNumbers or subgroupId parameter is missing
    * @returns {Promise<Object>} A promise that resolves to `{ message }` once the request is queued.
    */
-  async purchasePhoneNumber({ phoneNumbers, subgroupId, options = {} }) {
+  async purchasePhoneNumber({ phoneNumbers, subgroupId, country = 'US', options = {} }) {
     this.client._require({ phoneNumbers, subgroupId });
-    return this.client(`/number`, { method: 'POST', body: { phoneNumbers, subgroupId }, ...options });
+    return this.client(`/number`, { method: 'POST', body: { phoneNumbers, subgroupId, country }, ...options });
   }
 
   /**
@@ -176,19 +187,19 @@ export class Numbers {
    * @param {Object} params - The parameters for purchasing toll-free numbers
    * @param {number} params.quantity - The number of toll-free numbers to purchase (1-10)
    * @param {string} params.subgroupId - The subgroup the purchased numbers are assigned to
+   * @param {'US'|'CA'} [params.country='US'] - ISO-2 purchase country. Toll-Free always uses the shared registry.
    * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the quantity or subgroupId parameter is missing
    * @returns {Promise<Object>} A promise that resolves to `{ message, orderId }` once the request is queued.
    */
-  async purchaseTollFreeNumbers({ quantity, subgroupId, options = {} }) {
+  async purchaseTollFreeNumbers({ quantity, subgroupId, country = 'US', options = {} }) {
     this.client._require({ quantity, subgroupId });
-    return this.client(`/number/toll-free`, { method: 'POST', body: { quantity, subgroupId }, ...options });
+    return this.client(`/number/toll-free`, { method: 'POST', body: { quantity, subgroupId, country }, ...options });
   }
 
   /**
-   * Request a campaign-bound Short Code acquisition or register a customer-owned Registry lease.
-  * An inventory request soft-holds an existing unassigned Short Code. Random and vanity requests remain pending
-  * until Signal House staff fulfill them. An external lease creates a pending Short Code number immediately; it
+  * Request a campaign-bound Short Code acquisition or register a customer-owned Registry lease.
+  * Random and vanity requests remain pending until Signal House staff fulfill them. An external lease creates a pending Short Code number immediately; it
   * becomes READY only when its campaign becomes ACTIVE.
    * @async
    * @roles api, admin, developer, billing, user
@@ -196,13 +207,12 @@ export class Numbers {
    * @param {string} params.subgroupId - The owning subgroup ID.
    * @param {string} params.brandId - The owning Short Code brand ID.
    * @param {string} params.campaignId - The owning Short Code campaign ID.
-  * @param {'INVENTORY'|'RANDOM'|'VANITY'|'EXTERNAL_LEASE'} params.requestType - Acquisition path.
-  * @param {string} [params.existingPhoneNumber] - Required existing five- or six-digit Short Code for INVENTORY.
+  * @param {'RANDOM'|'VANITY'|'EXTERNAL_LEASE'} params.requestType - Acquisition path.
    * @param {number} [params.leaseTermMonths] - Required 3, 6, or 12-month term for RANDOM/VANITY.
    * @param {string} [params.requestedVanityCode] - Required five- or six-digit desired code for VANITY.
    * @param {string} [params.actualCode] - Required customer-owned five- or six-digit code for EXTERNAL_LEASE.
    * @param {string} [params.orderId] - Required Registry order ID for EXTERNAL_LEASE.
-   * @param {string|Date} [params.leaseEndDate] - Required future Registry lease end date for EXTERNAL_LEASE.
+  * @param {string|Date} [params.leaseEndDate] - Required future Registry lease end date for EXTERNAL_LEASE. A YYYY-MM-DD value expires at 23:59:59 UTC.
   * @param {Buffer|Blob|File} [params.leaseReceiptFile] - Required PNG, JPEG, or PDF lease receipt for EXTERNAL_LEASE.
    * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
    * @returns {Promise<Object>} A pending acquisition request or pending external-lease number.
@@ -212,7 +222,6 @@ export class Numbers {
     brandId,
     campaignId,
     requestType,
-    existingPhoneNumber,
     requestedVanityCode,
     leaseTermMonths,
     actualCode,
@@ -225,7 +234,7 @@ export class Numbers {
     const formData = new FormData();
     formData.append(
       'acquisitionData',
-      JSON.stringify({ subgroupId, brandId, campaignId, requestType, existingPhoneNumber, requestedVanityCode, leaseTermMonths, actualCode, orderId, leaseEndDate }),
+      JSON.stringify({ subgroupId, brandId, campaignId, requestType, requestedVanityCode, leaseTermMonths, actualCode, orderId, leaseEndDate }),
     );
     if (leaseReceiptFile) formData.append('leaseReceipt', leaseReceiptFile);
     return this.multipartClient(`/number/short-code`, {
@@ -351,9 +360,10 @@ export class Numbers {
 
   /**
    * 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.
+   * 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.
    * @async
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for assigning phone numbers to a campaign
@@ -361,7 +371,7 @@ export class Numbers {
    * @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, 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).
+   * @returns {Promise<Object>} A promise that resolves to `{ Message, queued, skipped }` - `queued` numbers were sent for assignment; `skipped` numbers were rejected (not found, RELEASED, currently being 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 });
@@ -385,7 +395,7 @@ export class Numbers {
   }
 
   /**
-   * Delete a list of phone numbers (mark them as RELEASED). The phone numbers will no longer be active or usable but they will still be visible in the system with a status of "RELEASED". Note: This operation is irreversible and should be used with caution.
+   * Delete a list of phone numbers (mark them as RELEASED). The phone numbers will no longer be active or usable but they will still be visible in the system with a status of "RELEASED". A number briefly shows a transient "PENDING_RELEASE" status while the deletion is being processed, before settling to "RELEASED". Note: This operation is irreversible and should be used with caution.
    * @async
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for deleting phone numbers
@@ -446,15 +456,15 @@ export class Numbers {
   /**
    * Search NPA/NXX lookup data with optional filters.
    * At least one search parameter is required.
-   * Location filters (country, state, city) cannot be combined with NPA/NXX filters.
+   * Country may scope NPA/NXX filters; state and city cannot be combined with them.
    * @async
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for searching NPA/NXX data
    * @param {string} [params.country] - Filter by country code
    * @param {string} [params.state] - Filter by state code (2 characters)
    * @param {string} [params.city] - Filter by city name (prefix match, case-insensitive; requires country and state)
-   * @param {string} [params.npa] - Area code filter (1-3 digits; cannot combine with location filters)
-   * @param {string} [params.nxx] - Central office code filter (1-3 digits; cannot combine with location filters)
+   * @param {string} [params.npa] - Area code filter (1-3 digits; optional country, no state/city)
+   * @param {string} [params.nxx] - Central office code filter (1-3 digits; optional country, no state/city)
    * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
    * @returns {Promise<Object>} A promise that resolves to matching NPA/NXX records or unique NPA/NXX arrays
    */

package/src/domains/Webhooks.js

@@ -5,7 +5,9 @@ export class Webhooks {
 	}
 
 	/**
-	 * Get a list of webhooks with optional filters
+	 * Get a list of webhooks with optional filters. Each returned endpoint carries `hasSigningSecret`
+	 * (boolean) instead of the signing secret itself — the plaintext secret is only ever returned once,
+	 * from `createWebhook`, and is never exposed again on any read (SHGHL-2944).
 	 * @async
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for getting webhooks
@@ -25,14 +27,19 @@ export class Webhooks {
 	}
 
 	/**
-	 * Create a new webhook with the specified data
+	 * Create a new webhook with the specified data. The response includes a `signingSecret` — a
+	 * plaintext HMAC-SHA256 secret used to sign every delivery to this endpoint, sent as the
+	 * `X-SignalHouse-Signature` header alongside `X-SignalHouse-Timestamp` (the signed string is
+	 * `${timestamp}.${rawRequestBody}`) and `X-SignalHouse-Delivery-Id` (stable across retries of the
+	 * same event, for receiver-side dedup). Store this secret now: it is never returned again by any
+	 * read (SHGHL-2944).
 	 * @async
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for creating a webhook
 	 * @param {Object} params.webhookData - The data for the new webhook
 	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
 	 * @throws {Error} Throws an error if the webhookData parameter is missing or if required fields in webhookData are missing
-	 * @returns {Promise<Object>} The response from the server
+	 * @returns {Promise<Object>} The response from the server, including the plaintext `signingSecret` (this one time only)
 	 */
 	async createWebhook({ webhookData, options = {} }) {
 		this.client._require({ webhookData: webhookData });
@@ -40,7 +47,9 @@ export class Webhooks {
 	}
 
 	/**
-	 * Update an existing webhook with the specified data
+	 * Update an existing webhook with the specified data. Like every other read of a webhook, the
+	 * response carries `hasSigningSecret` (boolean), never the signing secret itself — see
+	 * `createWebhook` (SHGHL-2944).
 	 * @async
 	 * @roles api, admin, developer
 	 * @param {Object} params - The parameters for updating a webhook