@signalhousellc/sdk 1.0.65 → 1.0.67

package/src/domains/Numbers.js

@@ -77,6 +77,23 @@ export class Numbers {
    * @param {number} [params.page] - The page number for pagination (default: 1)
    * @param {number} [params.limit] - The number of items per page for pagination (default: 20)
    * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   *
+   * Every record carries a `sentiment` object -- trailing 7-day and 30-day inbound reply sentiment,
+   * refreshed periodically from analytics rather than computed per request: `{ sevenDay, thirtyDay,
+   * updatedAt }`, each window being `{ score, label, scoredCount, positive, neutral, negative }`. The
+   * object is always present and fully populated, so it can be read without a presence check.
+   * `score` is a volume-weighted average in -100..100 and is null when nothing was scored in the
+   * window, which is not the same as a score of 0 -- null means nobody replied, 0 means replies
+   * averaged neutral. `updatedAt` is null until the first rollup writes the record, and it tracks when
+   * the figures last CHANGED, not when the job last ran.
+   *
+   * 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 = {} }) {
@@ -111,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
@@ -125,6 +143,7 @@ export class Numbers {
     voiceEnabled,
     country,
     state,
+    city,
     npa,
     nxx,
     phoneNumber,
@@ -132,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 });
   }
@@ -147,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 });
   }
 
   /**
@@ -167,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
@@ -187,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.
@@ -203,7 +222,6 @@ export class Numbers {
     brandId,
     campaignId,
     requestType,
-    existingPhoneNumber,
     requestedVanityCode,
     leaseTermMonths,
     actualCode,
@@ -216,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`, {
@@ -254,6 +272,8 @@ export class Numbers {
    * @param {string} params.phoneNumber - The phone number to update
    * @param {Object} params.updateData - The data to update for the phone number
    * @param {string} [params.updateData.friendlyName] - An optional friendly name for the phone number
+   * @param {string|null} [params.updateData.primaryInboundWebhookUrl] - Primary inbound voice webhook URL (http/https). When set, inbound calls to this number are driven by the SHML your webhook returns (programmable call control). Pass null or an empty string to clear.
+   * @param {string|null} [params.updateData.secondaryInboundWebhookUrl] - Secondary inbound voice webhook URL (http/https), used for failover when the primary returns an error. Pass null or an empty string to clear.
    * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the phoneNumber or updateData parameter is missing
    * @returns {Promise<Object>} A promise that resolves to the updated phone number object
@@ -340,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
@@ -350,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 });
@@ -374,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
@@ -435,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

package/src/domains/voice/ProgrammableVoiceProfiles.js

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