@signalhousellc/sdk 1.0.66 → 1.0.68

package/src/domains/Notifications.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 export class Notifications {
 	constructor(client, enableAdmin) {
 		this.client = client;
@@ -15,8 +21,8 @@ export class Notifications {
 	 * @param {number} [params.limit] - Results per page (min 1, max 100, default 10)
 	 * @param {string} [params.status] - Filter by status: "READ" or "UNREAD"
 	 * @param {string|string[]} [params.eventTypes] - Event types to filter by (comma-separated string or array)
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response from the server
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} The response from the server
 	 */
 	async getNotifications({ id, groupId, page, limit, status, eventTypes, options = {} }) {
 		this.client._require({ "id or groupId": id ?? groupId });
@@ -31,8 +37,8 @@ export class Notifications {
 	 * @param {Object} params
 	 * @param {string|string[]} params.ids - Notification id or array of notification ids
 	 * @param {string} params.status - New status: "READ" or "UNREAD"
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response from the server
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} The response from the server
 	 */
 	async updateNotificationStatus({ ids, status, options = {} }) {
 		this.client._require({ ids, status });
@@ -45,8 +51,8 @@ export class Notifications {
 	 * @roles signalhouse_api, signalhouse_admin, signalhouse_user, api, admin, developer, billing, user
 	 * @param {Object} params
 	 * @param {string} params.id - The notification id to delete
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} The response from the server
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} The response from the server
 	 */
 	async deleteNotification({ id, options = {} }) {
 		this.client._require({ id });

package/src/domains/Numbers.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 export class Numbers {
   constructor(client, multipartClient, enableAdmin) {
     this.client = client;
@@ -14,8 +20,8 @@ export class Numbers {
          * @param {string} params.portingId - The _id of the port-in request
          * @param {string} params.status - The new status (PENDING, IN_PROGRESS, REJECTED)
          * @param {string} [params.description] - Optional description for the status change
-         * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-         * @returns {Promise<Object>} A promise that resolves to the updated port-in request
+         * @param {RequestOptions} [params.options] - Additional options for the request
+         * @returns {Promise<SdkResponse<any>>} A promise that resolves to the updated port-in request
          */
         changePortingStatus: async ({ portingId, status, description, options = {} }) => {
           this.client._require({ portingId, status });
@@ -33,8 +39,8 @@ export class Numbers {
          * @roles signalhouse
          * @param {Object} params - The parameters for approving the request
          * @param {string} params.portingId - The _id of the port-in request
-         * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-         * @returns {Promise<Object>} A promise that resolves to the updated port-in request
+         * @param {RequestOptions} [params.options] - Additional options for the request
+         * @returns {Promise<SdkResponse<any>>} A promise that resolves to the updated port-in request
          */
         approvePortRequest: async ({ portingId, options = {} }) => {
           this.client._require({ portingId });
@@ -53,8 +59,8 @@ export class Numbers {
          * @param {string} [params.search] - Request or associated identifier search.
          * @param {number} [params.page] - One-based page number.
          * @param {number} [params.limit] - Page size.
-         * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options.
-         * @returns {Promise<Object>} Paginated acquisition requests.
+         * @param {RequestOptions} [params.options] - Additional options.
+         * @returns {Promise<SdkResponse<any>>} Paginated acquisition requests.
          */
         getShortCodeAcquisitionRequests: async ({ status, search, page, limit, options = {} } = {}) => {
           const queryString = this.client._getQueryString({ status, search, page, limit });
@@ -76,7 +82,7 @@ export class Numbers {
    * @param {string} [params.groupId] - Filter by group ID
    * @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
+   * @param {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,
@@ -86,7 +92,15 @@ 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.
-   * @returns {Promise<Object>} A promise that resolves to the list of phone numbers
+   *
+   * 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<SdkResponse<any>>} A promise that resolves to the list of phone numbers
    */
   async getPhoneNumbers({ phoneNumber, campaignId, brandId, subgroupId, groupId, page, limit, options = {} }) {
     const filters = { phoneNumber, campaignId, brandId, subgroupId, groupId, page, limit };
@@ -100,9 +114,9 @@ export class Numbers {
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for reading number health
    * @param {string} params.phoneNumber - Owned phone number to score (11 digits, no + prefix)
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   * @param {RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the phoneNumber parameter is missing
-   * @returns {Promise<Object>} A promise that resolves to `{ phoneNumber, groupId, sevenDay, thirtyDay }`
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ phoneNumber, groupId, sevenDay, thirtyDay }`
    */
   async getNumberHealth({ phoneNumber, options = {} }) {
     this.client._require({ phoneNumber });
@@ -120,13 +134,14 @@ 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
    * @param {number} [params.limit] - The number of items per page for pagination
    * @param {number} [params.page] - The page number for pagination
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-   * @returns {Promise<Object>} A promise that resolves to the list of available phone numbers
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to the list of available phone numbers
    */
   async getAvailablePhoneNumbers({
     smsEnabled,
@@ -134,6 +149,7 @@ export class Numbers {
     voiceEnabled,
     country,
     state,
+    city,
     npa,
     nxx,
     phoneNumber,
@@ -141,7 +157,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 +172,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 {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   * @param {'US'|'CA'} [params.country='US'] - ISO-2 purchase country. Toll-Free always uses the shared registry.
+   * @param {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.
+   * @returns {Promise<SdkResponse<any>>} 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 +193,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 {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   * @param {'US'|'CA'} [params.country='US'] - ISO-2 purchase country. Toll-Free always uses the shared registry.
+   * @param {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.
+   * @returns {Promise<SdkResponse<any>>} 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,23 +213,21 @@ 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 {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.
+  * @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 {Blob|File} [params.leaseReceiptFile] - Required PNG, JPEG, or PDF lease receipt for EXTERNAL_LEASE.
+   * @param {RequestOptions} [params.options] - Additional options for the request.
+   * @returns {Promise<SdkResponse<any>>} A pending acquisition request or pending external-lease number.
    */
   async requestShortCodeAcquisition({
     subgroupId,
     brandId,
     campaignId,
     requestType,
-    existingPhoneNumber,
     requestedVanityCode,
     leaseTermMonths,
     actualCode,
@@ -225,7 +240,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`, {
@@ -245,9 +260,9 @@ export class Numbers {
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for reading the order status
    * @param {string} params.orderId - The order id returned by `purchaseTollFreeNumbers`
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   * @param {RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the orderId parameter is missing
-   * @returns {Promise<Object>} A promise that resolves to `{ orderId, counts: { ready, provisioning, failed }, failures: [{ reason }], numbers: string[] }`.
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to `{ orderId, counts: { ready, provisioning, failed }, failures: [{ reason }], numbers: string[] }`.
    */
   async getTollFreeOrderStatus({ orderId, options = {} }) {
     this.client._require({ orderId });
@@ -265,9 +280,9 @@ export class Numbers {
    * @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
+   * @param {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
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to the updated phone number object
    */
   async updatePhoneNumber({ phoneNumber, updateData, options = {} }) {
     this.client._require({ phoneNumber, updateData });
@@ -288,9 +303,9 @@ export class Numbers {
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for the port-in request
    * @param {Object} params.numberData - The port-in request data including owner info, address, phone numbers, and signature
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   * @param {RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the numberData parameter is missing
-   * @returns {Promise<Object>} A promise that resolves to the created port-in request
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to the created port-in request
    */
   async portInPhoneNumber({ numberData, options = {} }) {
     this.client._require({ numberData });
@@ -307,8 +322,8 @@ export class Numbers {
    * @param {string} [params.status] - Filter by status (PENDING, IN_PROGRESS, COMPLETED, REJECTED, CANCELLED)
    * @param {number} [params.page] - The page number for pagination (default: 1)
    * @param {number} [params.limit] - The number of items per page (default: 20)
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-   * @returns {Promise<Object>} A promise that resolves to the paginated list of port-in requests
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to the paginated list of port-in requests
    */
   async getPortRequests({ groupId, phoneNumber, status, page, limit, options = {} } = {}) {
     const filters = { groupId, phoneNumber, status, page, limit };
@@ -322,8 +337,8 @@ export class Numbers {
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for getting the port request
    * @param {string} params.id - The _id of the port-in request
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-   * @returns {Promise<Object>} A promise that resolves to the port-in request object
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to the port-in request object
    */
   async getPortRequestById({ id, options = {} }) {
     this.client._require({ id });
@@ -339,8 +354,8 @@ export class Numbers {
    * @param {string} [params.portingId] - If provided, fetches a single port request by ID
    * @param {number} [params.page] - Page number for pagination (used when listing)
    * @param {number} [params.limit] - Items per page (used when listing)
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-   * @returns {Promise<Object>} A promise that resolves to the port-in request(s)
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to the port-in request(s)
    */
   async getPortingRequests({ portingId, page, limit, options = {} } = {}) {
     if (portingId) {
@@ -351,17 +366,18 @@ 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
    * @param {string} params.campaignId - The ID of the campaign to assign phone numbers to
    * @param {string[]} params.phoneNumbers - The list of phone numbers to assign to the campaign
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   * @param {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<SdkResponse<any>>} 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 });
@@ -375,9 +391,9 @@ export class Numbers {
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for unassigning phone numbers from campaigns
    * @param {string[]} params.phoneNumbers - The list of phone numbers to unassign from campaigns
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   * @param {RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the phoneNumbers parameter is missing
-   * @returns {Promise<Object>} A promise that resolves to the result of the unassignment operation
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to the result of the unassignment operation
    */
   async unassignPhoneNumbersFromCampaigns({ phoneNumbers, options = {} }) {
     this.client._require({ phoneNumbers });
@@ -385,14 +401,14 @@ 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
    * @param {string[]} params.phoneNumbers - The list of phone numbers to delete
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   * @param {RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the phoneNumbers parameter is missing
-   * @returns {Promise<Object>} A promise that resolves to the result of the deletion operation
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to the result of the deletion operation
    */
   async deletePhoneNumbers({ phoneNumbers, options = {} }) {
     this.client._require({ phoneNumbers });
@@ -405,9 +421,9 @@ export class Numbers {
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for deactivating phone numbers
    * @param {string[]} params.phoneNumbers - The list of phone numbers to deactivate
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   * @param {RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the phoneNumbers parameter is missing
-   * @returns {Promise<Object>} A promise that resolves to an array of updated phone number objects
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to an array of updated phone number objects
    */
   async deactivatePhoneNumbers({ phoneNumbers, options = {} }) {
     this.client._require({ phoneNumbers });
@@ -420,9 +436,9 @@ export class Numbers {
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for reactivating phone numbers
    * @param {string[]} params.phoneNumbers - The list of phone numbers to reactivate
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   * @param {RequestOptions} [params.options] - Additional options for the request
    * @throws {Error} Throws an error if the phoneNumbers parameter is missing
-   * @returns {Promise<Object>} A promise that resolves to an array of updated phone number objects
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to an array of updated phone number objects
    */
   async reactivatePhoneNumbers({ phoneNumbers, options = {} }) {
     this.client._require({ phoneNumbers });
@@ -435,8 +451,8 @@ export class Numbers {
    * @param {Object} params - The parameters for transferring phone numbers
    * @param {string[]} params.phoneNumbers - The list of phone numbers to transfer
    * @param {string} params.newSubgroupId - The ID of the new subgroup to transfer the phone numbers to
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-   * @returns {Promise<Object>} A promise that resolves to the result of the transfer operation
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to the result of the transfer operation
    */
   async transferPhoneNumbers({ phoneNumbers, newSubgroupId, options = {} }) {
     this.client._require({ phoneNumbers, newSubgroupId });
@@ -446,17 +462,17 @@ 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 {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
+   * @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 {RequestOptions} [params.options] - Additional options for the request
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to matching NPA/NXX records or unique NPA/NXX arrays
    */
   async searchNpaNxx({ country, state, city, npa, nxx, options = {} }) {
     const queryString = this.client._getQueryString({ country, state, city, npa, nxx });
@@ -469,8 +485,8 @@ export class Numbers {
    * @roles api, admin, developer, billing, user
    * @param {Object} params - The parameters for the lookup
    * @param {Array<{npa: string, nxx: string}>} params.entries - NPA/NXX pairs to look up (max 50)
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-   * @returns {Promise<Object>} A promise that resolves to an array of {npa, nxx, city, state} objects
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to an array of {npa, nxx, city, state} objects
    */
   async lookupLocations({ entries, options = {} }) {
     return this.client('/number/lookup/location', { method: 'POST', body: { entries }, ...options });
@@ -484,8 +500,8 @@ export class Numbers {
    * @param {string} [params.phoneNumber] - The phone number to migrate
    * @param {string} [params.campaignId] - Campaign ID to migrate all numbers for
    * @param {string} [params.groupId] - Group ID to migrate all numbers for
-   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-   * @returns {Promise<Object>} A promise that resolves to a confirmation with count of queued numbers
+   * @param {RequestOptions} [params.options] - Additional options for the request
+   * @returns {Promise<SdkResponse<any>>} A promise that resolves to a confirmation with count of queued numbers
    */
   async migratePhoneNumberToV2({ phoneNumber, campaignId, groupId, options = {} }) {
     return this.client(`/number/migrate`, { method: 'POST', body: { phoneNumber, campaignId, groupId }, ...options });

package/src/domains/Onboarding.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 export class Onboarding {
 	constructor(client, enableAdmin) {
 		this.client = client;
@@ -11,8 +17,8 @@ export class Onboarding {
 				 * @async
 				 * @roles signalhouse
 				 * @param {Object} [params] - Optional parameters
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-				 * @returns {Promise<Object>} - Array of onboarding records
+				 * @param {RequestOptions} [params.options] - Additional options for the request
+				 * @returns {Promise<SdkResponse<any>>} - Array of onboarding records
 				 */
 				getOnboardings: async ({ options = {} } = {}) => {
 					return this.client(`/group/onboarding`, { method: "GET", ...options });
@@ -24,9 +30,9 @@ export class Onboarding {
 				 * @roles signalhouse
 				 * @param {Object} params
 				 * @param {string} params.groupId - The group ID whose onboarding record to retrieve
-				 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+				 * @param {RequestOptions} [params.options] - Additional options for the request
 				 * @throws {Error} Throws an error if the groupId parameter is missing
-				 * @returns {Promise<Object>} - The onboarding record
+				 * @returns {Promise<SdkResponse<any>>} - The onboarding record
 				 */
 				getOnboarding: async ({ groupId, options = {} }) => {
 					this.client._require({ groupId });
@@ -46,8 +52,8 @@ export class Onboarding {
 	 * record rather than an error, so callers never have to special-case them.
 	 * @async
 	 * @param {Object} [params] - Optional parameters
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} - `{ acceptedTermsOfService: boolean, emailVerified: boolean, products: string[], estimatedVolume: string|null, pendingExternalLink: "ghl"|"shopify"|null }`
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} - `{ acceptedTermsOfService: boolean, emailVerified: boolean, products: string[], estimatedVolume: string|null, pendingExternalLink: "ghl"|"shopify"|null }`
 	 */
 	async getMyOnboarding({ options = {} } = {}) {
 		return this.client(`/group/onboarding/my`, { method: "GET", ...options });
@@ -57,8 +63,8 @@ export class Onboarding {
 	 * Accept the Terms of Service for the caller's active group.
 	 * @async
 	 * @param {Object} [params] - Optional parameters
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} - `{ acceptedTermsOfService: true }`
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} - `{ acceptedTermsOfService: true }`
 	 */
 	async acceptTermsOfService({ options = {} } = {}) {
 		return this.client(`/group/onboarding/my/accept-terms`, {

package/src/domains/Shortlinks.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 export class Shortlinks {
 	constructor(client, enableAdmin) {
 		this.client = client;
@@ -10,8 +16,8 @@ export class Shortlinks {
 	 * @roles public
 	 * @param {Object} params - The parameters for getting the shortlink redirect
 	 * @param {string} params.shortlinkId - The ID of the shortlink
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @returns {Promise<Object>} A promise that resolves to the redirect URL for the shortlink
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} A promise that resolves to the redirect URL for the shortlink
 	 */
 	async getShortlinkRedirect({ shortlinkId, options = {} }) {
 		this.client._require({ shortlinkId });
@@ -33,8 +39,8 @@ export class Shortlinks {
 	 * @param {string} [params.groupId] - Filter by associated group ID
 	 * @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
-	 * @returns {Promise<Object>} A promise that resolves to the shortlink details
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} A promise that resolves to the shortlink details
 	 */
 	async getShortlink({ shortlinkId, messageId, phoneNumber, campaignId, brandId, subgroupId, groupId, page, limit, options = {} }) {
 		const filters = { shortlinkId, messageId, phoneNumber, campaignId, brandId, subgroupId, groupId, page, limit };

package/src/domains/Subgroups.js

@@ -1,3 +1,9 @@
+/** @typedef {import('../SignalHouseSDK.js').RequestOptions} RequestOptions */
+/**
+ * @template T
+ * @typedef {import('../SignalHouseSDK.js').SdkResponse<T>} SdkResponse
+ */
+
 /**
  * @typedef {Object} CreateSubgroupData
  * @property {string} groupId - The ID of the parent group for the subgroup (must be at least 8 characters long and start with 'G')
@@ -51,8 +57,8 @@ export class Subgroups {
 	 * @param {string} [params.groupId] - Filter by parent group ID
 	 * @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
-	 * @returns {Promise<Object>} - The list of subgroups returned from the server
+	 * @param {RequestOptions} [params.options] - Additional options for the request
+	 * @returns {Promise<SdkResponse<any>>} - The list of subgroups returned from the server
 	 */
 	async getSubgroups({ id, groupId, page, limit, options = {} }) {
 		const filters = { id, groupId, page, limit };
@@ -70,8 +76,8 @@ export class Subgroups {
 	 * @param {string} [params.subgroupId] - Restrict results to a subgroup.
 	 * @param {number} [params.limit] - Maximum rows to return.
 	 * @param {number} [params.offset] - Rows to skip; requires limit.
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request.
-	 * @returns {Promise<Object>} - Subgroup-level resource count rows.
+	 * @param {RequestOptions} [params.options] - Additional options for the request.
+	 * @returns {Promise<SdkResponse<any>>} - Subgroup-level resource count rows.
 	 */
 	async getSubgroupCounts({ groupId, subgroupId, limit, offset, options = {} } = {}) {
 		const queryString = this.client._getQueryString({ groupId, subgroupId, limit, offset });
@@ -84,9 +90,9 @@ export class Subgroups {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for creating a subgroup (see CreateSubgroupData typedef for details)
 	 * @param {CreateSubgroupData} params.subgroupData - The data for the subgroup to be created, including required fields such as groupId and subgroupName
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @param {RequestOptions} [params.options] - Additional options for the request
 	 * @throws {Error} Throws an error if the subgroupData parameter is missing or if required fields in subgroupData are missing
-	 * @returns {Promise<Object>} - The created subgroup object returned from the server
+	 * @returns {Promise<SdkResponse<any>>} - The created subgroup object returned from the server
 	 */
 	async createSubgroup({ subgroupData, options = {} }) {
 		this.client._require({ subgroupData: subgroupData });
@@ -100,9 +106,9 @@ export class Subgroups {
 	 * @param {Object} params - The parameters for updating a subgroup (see UpdateSubgroupData typedef for details)
 	 * @param {string} params.id - The ID of the subgroup to update
 	 * @param {UpdateSubgroupData} params.updateData - The data for the subgroup to be updated, including fields such as subgroupName, contact information, and status
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @param {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 subgroup object returned from the server
+	 * @returns {Promise<SdkResponse<any>>} - The updated subgroup object returned from the server
 	 */
 	async updateSubgroup({ id, updateData, options = {} }) {
 		this.client._require({ id, updateData });
@@ -116,9 +122,9 @@ export class Subgroups {
 	 * @roles api, admin, developer, billing, user
 	 * @param {Object} params - The parameters for deleting a subgroup
 	 * @param {string} params.id - The ID of the subgroup to delete
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+	 * @param {RequestOptions} [params.options] - Additional options for the request
 	 * @throws {Error} Throws an error if the id parameter is missing
-	 * @returns {Promise<Object>} - The deleted subgroup object returned from the server
+	 * @returns {Promise<SdkResponse<any>>} - The deleted subgroup object returned from the server
 	 */
 	async deleteSubgroup({ id, options = {} }) {
 		this.client._require({ id });