@signalhousellc/sdk 1.0.56 → 1.0.62

package/src/domains/Numbers.js

@@ -1,400 +1,479 @@
 export class Numbers {
-	constructor(client, enableAdmin) {
-		this.client = client;
-		this.enableAdmin = enableAdmin;
+  constructor(client, multipartClient, enableAdmin) {
+    this.client = client;
+    this.multipartClient = multipartClient;
+    this.enableAdmin = enableAdmin;
 
-		if (enableAdmin) {
-			this.admin = {
-				/**
-				 * Update a port-in request's status (signalhouse only)
-				 * @async
-				 * @roles signalhouse
-				 * @param {Object} params - The parameters for updating the status
-				 * @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
-				 */
-				changePortingStatus: async ({ portingId, status, description, options = {} }) => {
-					this.client._require({ portingId, status });
-					const safeId = encodeURIComponent(portingId);
-					return this.client(`/number/portin/${safeId}/status`, {
-						method: "PUT",
-						body: { status, description },
-						...options,
-					});
-				},
+    if (enableAdmin) {
+      this.admin = {
+        /**
+         * Update a port-in request's status (signalhouse only)
+         * @async
+         * @roles signalhouse
+         * @param {Object} params - The parameters for updating the status
+         * @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
+         */
+        changePortingStatus: async ({ portingId, status, description, options = {} }) => {
+          this.client._require({ portingId, status });
+          const safeId = encodeURIComponent(portingId);
+          return this.client(`/number/portin/${safeId}/status`, {
+            method: 'PUT',
+            body: { status, description },
+            ...options,
+          });
+        },
 
-				/**
-				 * Approve a port-in request, setting its status to SUCCESS (signalhouse only)
-				 * @async
-				 * @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
-				 */
-				approvePortRequest: async ({ portingId, options = {} }) => {
-					this.client._require({ portingId });
-					const safeId = encodeURIComponent(portingId);
-					return this.client(`/number/portin/${safeId}/approve`, {
-						method: "POST",
-						...options,
-					});
-				},
-			};
-		}
-	}
+        /**
+         * Approve a port-in request, setting its status to SUCCESS (signalhouse only)
+         * @async
+         * @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
+         */
+        approvePortRequest: async ({ portingId, options = {} }) => {
+          this.client._require({ portingId });
+          const safeId = encodeURIComponent(portingId);
+          return this.client(`/number/portin/${safeId}/approve`, {
+            method: 'POST',
+            ...options,
+          });
+        },
+        /**
+         * List campaign-bound Short Code acquisition requests for staff.
+         * @async
+         * @roles signalhouse
+         * @param {Object} [params] - Queue filter parameters.
+         * @param {string} [params.status] - PENDING, FULFILLED, or CANCELLED.
+         * @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.
+         */
+        getShortCodeAcquisitionRequests: async ({ status, search, page, limit, options = {} } = {}) => {
+          const queryString = this.client._getQueryString({ status, search, page, limit });
+          return this.client(`/number/short-code/requests${queryString}`, { method: 'GET', ...options });
+        },
+      };
+    }
+  }
 
-	/**
-	 * Get a list of phone numbers with optional filters such as campaignId, brandId, subgroupId, groupId, and pagination parameters
-	 * @async
-	 * @roles api, admin, developer, billing, user
-	 * @param {Object} params - The parameters for filtering the phone numbers
-	 * @param {string} [params.phoneNumber] - Filter by phone number (partial match)
-	 * @param {string} [params.campaignId] - Filter by campaign ID
-	 * @param {string} [params.brandId] - Filter by brand ID
-	 * @param {string} [params.subgroupId] - Filter by subgroup ID
-	 * @param {string} [params.groupId] - Filter by group ID
-	 * @param {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
-	 * @returns {Promise<Object>} 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 };
-		const queryString = this.client._getQueryString(filters);
-		return this.client(`/number${queryString}`, { method: "GET", ...options });
-	}
+  /**
+   * Get a list of phone numbers with optional filters such as campaignId, brandId, subgroupId, groupId, and pagination parameters
+   * @async
+   * @roles api, admin, developer, billing, user
+   * @param {Object} params - The parameters for filtering the phone numbers
+   * @param {string} [params.phoneNumber] - Filter by phone number (partial match)
+   * @param {string} [params.campaignId] - Filter by campaign ID
+   * @param {string} [params.brandId] - Filter by brand ID
+   * @param {string} [params.subgroupId] - Filter by subgroup ID
+   * @param {string} [params.groupId] - Filter by group ID
+   * @param {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
+   * @returns {Promise<Object>} 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 };
+    const queryString = this.client._getQueryString(filters);
+    return this.client(`/number${queryString}`, { method: 'GET', ...options });
+  }
 
-	/**
-	 * Get the portal-parity health score (1–10) for an owned phone number over 7-day and 30-day windows
-	 * @async
-	 * @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
-	 * @throws {Error} Throws an error if the phoneNumber parameter is missing
-	 * @returns {Promise<Object>} A promise that resolves to `{ phoneNumber, groupId, sevenDay, thirtyDay }`
-	 */
-	async getNumberHealth({ phoneNumber, options = {} }) {
-		this.client._require({ phoneNumber });
-		const queryString = this.client._getQueryString({ phoneNumber });
-		return this.client(`/number/health${queryString}`, { method: "GET", ...options });
-	}
+  /**
+   * Get the portal-parity health score (1–10) for an owned phone number over 7-day and 30-day windows
+   * @async
+   * @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
+   * @throws {Error} Throws an error if the phoneNumber parameter is missing
+   * @returns {Promise<Object>} A promise that resolves to `{ phoneNumber, groupId, sevenDay, thirtyDay }`
+   */
+  async getNumberHealth({ phoneNumber, options = {} }) {
+    this.client._require({ phoneNumber });
+    const queryString = this.client._getQueryString({ phoneNumber });
+    return this.client(`/number/health${queryString}`, { method: 'GET', ...options });
+  }
 
-	/**
-	 * Get a list of available phone numbers for purchase with optional filters
-	 * @async
-	 * @roles api, admin, developer, billing, user
-	 * @param {Object} params - The parameters for filtering the available phone numbers
-	 * @param {boolean} [params.smsEnabled] - Filter for phone numbers that are SMS enabled
-	 * @param {boolean} [params.mmsEnabled] - Filter for phone numbers that are MMS enabled
-	 * @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.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
-	 */
-	async getAvailablePhoneNumbers({ smsEnabled, mmsEnabled, voiceEnabled, country, state, npa, nxx, phoneNumber, limit, page, options = {} }) {
-		const filters = { smsEnabled, mmsEnabled, voiceEnabled, country, state, npa, nxx, phoneNumber, limit, page };
-		const queryString = this.client._getQueryString(filters);
-		return this.client(`/number/available${queryString}`, { method: "GET", ...options });
-	}
+  /**
+   * Get a list of available phone numbers for purchase with optional filters
+   * @async
+   * @roles api, admin, developer, billing, user
+   * @param {Object} params - The parameters for filtering the available phone numbers
+   * @param {boolean} [params.smsEnabled] - Filter for phone numbers that are SMS enabled
+   * @param {boolean} [params.mmsEnabled] - Filter for phone numbers that are MMS enabled
+   * @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.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
+   */
+  async getAvailablePhoneNumbers({
+    smsEnabled,
+    mmsEnabled,
+    voiceEnabled,
+    country,
+    state,
+    npa,
+    nxx,
+    phoneNumber,
+    limit,
+    page,
+    options = {},
+  }) {
+    const filters = { smsEnabled, mmsEnabled, voiceEnabled, country, state, npa, nxx, phoneNumber, limit, page };
+    const queryString = this.client._getQueryString(filters);
+    return this.client(`/number/available${queryString}`, { method: 'GET', ...options });
+  }
 
-	/**
-	 * Purchase phone numbers by providing a list of phone numbers and the subgroup ID to assign them to.
-	 *
-	 * Each requested number is queued and processed independently. Per-number success or failure is
-	 * delivered via `NUMBER_PURCHASE_SUCCESSFUL` / `NUMBER_PURCHASE_FAILED` webhooks — not in this response.
-	 * @async
-	 * @roles api, admin, developer, billing, user
-	 * @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
-	 * @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 = {} }) {
-		this.client._require({ phoneNumbers, subgroupId });
-		return this.client(`/number`, { method: "POST", body: { phoneNumbers, subgroupId }, ...options });
-	}
+  /**
+   * Purchase phone numbers by providing a list of phone numbers and the subgroup ID to assign them to.
+   *
+   * Each requested number is queued and processed independently. Per-number success or failure is
+   * delivered via `NUMBER_PURCHASE_SUCCESSFUL` / `NUMBER_PURCHASE_FAILED` webhooks — not in this response.
+   * @async
+   * @roles api, admin, developer, billing, user
+   * @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
+   * @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 = {} }) {
+    this.client._require({ phoneNumbers, subgroupId });
+    return this.client(`/number`, { method: 'POST', body: { phoneNumbers, subgroupId }, ...options });
+  }
 
-	/**
-	 * Purchase one or more Toll-Free numbers via the asynchronous resource-request flow.
-	 *
-	 * Toll-Free numbers are ordered by quantity (not picked individually) and provisioned asynchronously;
-	 * per-number completion is delivered via webhook/polling, not in this response. The returned `orderId`
-	 * can be polled with {@link Numbers#getTollFreeOrderStatus} for the order's outcome.
-	 * @async
-	 * @roles api, admin, developer, billing, user
-	 * @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
-	 * @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 = {} }) {
-		this.client._require({ quantity, subgroupId });
-		return this.client(`/number/toll-free`, { method: "POST", body: { quantity, subgroupId }, ...options });
-	}
+  /**
+   * Purchase one or more Toll-Free numbers via the asynchronous resource-request flow.
+   *
+   * Toll-Free numbers are ordered by quantity (not picked individually) and provisioned asynchronously;
+   * per-number completion is delivered via webhook/polling, not in this response. The returned `orderId`
+   * can be polled with {@link Numbers#getTollFreeOrderStatus} for the order's outcome.
+   * @async
+   * @roles api, admin, developer, billing, user
+   * @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
+   * @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 = {} }) {
+    this.client._require({ quantity, subgroupId });
+    return this.client(`/number/toll-free`, { method: 'POST', body: { quantity, subgroupId }, ...options });
+  }
 
-	/**
-	 * Read the outcome of a Toll-Free number purchase by the `orderId` returned from
-	 * {@link Numbers#purchaseTollFreeNumbers}. Reports per-number status as ready / provisioning / failed
-	 * counts (plus failure reasons) so a client can poll until the order reaches a terminal state, and
-	 * returns the provisioned phone numbers for the order so a client can act on exactly those numbers.
-	 * `numbers` is empty until each number is provisioned (it fills in as the order completes).
-	 * @async
-	 * @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
-	 * @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[] }`.
-	 */
-	async getTollFreeOrderStatus({ orderId, options = {} }) {
-		this.client._require({ orderId });
-		const safeOrderId = encodeURIComponent(orderId);
-		return this.client(`/number/toll-free/order/${safeOrderId}`, { method: "GET", ...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
+  * becomes READY only when its campaign becomes ACTIVE.
+   * @async
+   * @roles api, admin, developer, billing, user
+   * @param {Object} params - Short Code acquisition parameters.
+   * @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 {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.
+   */
+  async requestShortCodeAcquisition({
+    subgroupId,
+    brandId,
+    campaignId,
+    requestType,
+    existingPhoneNumber,
+    requestedVanityCode,
+    leaseTermMonths,
+    actualCode,
+    orderId,
+    leaseEndDate,
+    leaseReceiptFile,
+    options = {},
+  }) {
+    this.client._require({ subgroupId, brandId, campaignId, requestType });
+    const formData = new FormData();
+    formData.append(
+      'acquisitionData',
+      JSON.stringify({ subgroupId, brandId, campaignId, requestType, existingPhoneNumber, requestedVanityCode, leaseTermMonths, actualCode, orderId, leaseEndDate }),
+    );
+    if (leaseReceiptFile) formData.append('leaseReceipt', leaseReceiptFile);
+    return this.multipartClient(`/number/short-code`, {
+      method: 'POST',
+      body: formData,
+      ...options,
+    });
+  }
 
-	/**
-	 * Update an existing phone number's details (e.g., setting a friendly name)
-	 * @async
-	 * @roles api, admin, developer, user
-	 * @param {Object} params - The parameters for updating the phone number
-	 * @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 {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
-	 */
-	async updatePhoneNumber({ phoneNumber, updateData, options = {} }) {
-		this.client._require({ phoneNumber, updateData });
-		
-		// Safely encode the phone number for the URL path
-		const safePhoneNumber = encodeURIComponent(phoneNumber);
-		
-		return this.client(`/number/${safePhoneNumber}`, { 
-			method: "PUT", 
-			body: updateData, 
-			...options 
-		});
-	}
-	
-	/**
-	 * Submit a port-in request for one or more phone numbers from another provider
-	 * @async
-	 * @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
-	 * @throws {Error} Throws an error if the numberData parameter is missing
-	 * @returns {Promise<Object>} A promise that resolves to the created port-in request
-	 */
-	async portInPhoneNumber({ numberData, options = {} }) {
-		this.client._require({ numberData });
-		return this.client(`/number/portin`, { method: "POST", body: numberData, ...options });
-	}
+  /**
+   * Read the outcome of a Toll-Free number purchase by the `orderId` returned from
+   * {@link Numbers#purchaseTollFreeNumbers}. Reports per-number status as ready / provisioning / failed
+   * counts (plus failure reasons) so a client can poll until the order reaches a terminal state, and
+   * returns the provisioned phone numbers for the order so a client can act on exactly those numbers.
+   * `numbers` is empty until each number is provisioned (it fills in as the order completes).
+   * @async
+   * @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
+   * @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[] }`.
+   */
+  async getTollFreeOrderStatus({ orderId, options = {} }) {
+    this.client._require({ orderId });
+    const safeOrderId = encodeURIComponent(orderId);
+    return this.client(`/number/toll-free/order/${safeOrderId}`, { method: 'GET', ...options });
+  }
 
-	/**
-	 * Get port-in requests with optional filters. Signal House staff can view all requests; regular users see only their group's requests.
-	 * @async
-	 * @roles api, admin, developer, billing, user
-	 * @param {Object} [params] - The parameters for filtering port-in requests
-	 * @param {string} [params.groupId] - Filter by group ID
-	 * @param {string} [params.phoneNumber] - Filter by phone number
-	 * @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
-	 */
-	async getPortRequests({ groupId, phoneNumber, status, page, limit, options = {} } = {}) {
-		const filters = { groupId, phoneNumber, status, page, limit };
-		const queryString = this.client._getQueryString(filters);
-		return this.client(`/number/portin${queryString}`, { method: "GET", ...options });
-	}
+  /**
+   * Update an existing phone number's details (e.g., setting a friendly name)
+   * @async
+   * @roles api, admin, developer, user
+   * @param {Object} params - The parameters for updating the phone number
+   * @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 {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
+   */
+  async updatePhoneNumber({ phoneNumber, updateData, options = {} }) {
+    this.client._require({ phoneNumber, updateData });
 
-	/**
-	 * Get a single port-in request by its ID
-	 * @async
-	 * @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
-	 */
-	async getPortRequestById({ id, options = {} }) {
-		this.client._require({ id });
-		const safeId = encodeURIComponent(id);
-		return this.client(`/number/portin/${safeId}`, { method: "GET", ...options });
-	}
+    // Safely encode the phone number for the URL path
+    const safePhoneNumber = encodeURIComponent(phoneNumber);
 
-	/**
-	 * Get porting requests - fetches a single request by portingId, or delegates to getPortRequests for listing
-	 * @async
-	 * @roles api, admin, developer, billing, user
-	 * @param {Object} params - The parameters
-	 * @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)
-	 */
-	async getPortingRequests({ portingId, page, limit, options = {} } = {}) {
-		if (portingId) {
-			return this.getPortRequestById({ id: portingId, options });
-		}
-		return this.getPortRequests({ page, limit, options });
-	}
+    return this.client(`/number/${safePhoneNumber}`, {
+      method: 'PUT',
+      body: updateData,
+      ...options,
+    });
+  }
 
-	/**
-	 * Assign phone numbers to a campaign by providing the campaign ID and a list of phone numbers to assign
-	 * @async
-	 * @roles api, admin, developer, billing, user
-	 * @param {Object} params - The parameters for assigning phone numbers to a campaign
-	 * @param {string} params.campaignId - The ID of the campaign to assign phone numbers to
-	 * @param {string[]} params.phoneNumbers - The list of phone numbers to assign to the campaign
-	 * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
-	 * @throws {Error} Throws an error if the campaignId or phoneNumbers parameter is missing
-	 * @returns {Promise<Object>} A promise that resolves to the result of the assignment operation
-	 */
-	async assignPhoneNumberToCampaign({ campaignId, phoneNumbers, options = {} }) {
-		this.client._require({ campaignId, phoneNumbers });
-		const safeCampaignId = encodeURIComponent(campaignId);
-		return this.client(`/number/assign/${safeCampaignId}`, { method: "POST", body: { phoneNumbers }, ...options });
-	}
+  /**
+   * Submit a port-in request for one or more phone numbers from another provider
+   * @async
+   * @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
+   * @throws {Error} Throws an error if the numberData parameter is missing
+   * @returns {Promise<Object>} A promise that resolves to the created port-in request
+   */
+  async portInPhoneNumber({ numberData, options = {} }) {
+    this.client._require({ numberData });
+    return this.client(`/number/portin`, { method: 'POST', body: numberData, ...options });
+  }
 
-	/**
-	 * Unassign phone numbers from a campaign by providing a list of phone numbers to unassign. Note: This operation will unassign the specified phone numbers from any campaign they are currently assigned to.
-	 * @async
-	 * @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
-	 * @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
-	 */
-	async unassignPhoneNumbersFromCampaigns({ phoneNumbers, options = {} }) {
-		this.client._require({ phoneNumbers });
-		return this.client(`/number/unassign`, { method: "POST", body: { phoneNumbers }, ...options });
-	}
+  /**
+   * Get port-in requests with optional filters. Signal House staff can view all requests; regular users see only their group's requests.
+   * @async
+   * @roles api, admin, developer, billing, user
+   * @param {Object} [params] - The parameters for filtering port-in requests
+   * @param {string} [params.groupId] - Filter by group ID
+   * @param {string} [params.phoneNumber] - Filter by phone number
+   * @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
+   */
+  async getPortRequests({ groupId, phoneNumber, status, page, limit, options = {} } = {}) {
+    const filters = { groupId, phoneNumber, status, page, limit };
+    const queryString = this.client._getQueryString(filters);
+    return this.client(`/number/portin${queryString}`, { method: 'GET', ...options });
+  }
 
-	/**
-	 * 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.
-	 * @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
-	 * @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
-	 */
-	async deletePhoneNumbers({ phoneNumbers, options = {} }) {
-		this.client._require({ phoneNumbers });
-		return this.client(`/number`, { method: "DELETE", body: { phoneNumbers }, ...options });
-	}
+  /**
+   * Get a single port-in request by its ID
+   * @async
+   * @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
+   */
+  async getPortRequestById({ id, options = {} }) {
+    this.client._require({ id });
+    const safeId = encodeURIComponent(id);
+    return this.client(`/number/portin/${safeId}`, { method: 'GET', ...options });
+  }
 
-	/**
-	 * Deactivate one or more phone numbers. Numbers must be in READY status to be deactivated. Deactivated numbers will not be able to send or receive messages but will remain assigned to their subgroup and campaign.
-	 * @async
-	 * @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
-	 * @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
-	 */
-	async deactivatePhoneNumbers({ phoneNumbers, options = {} }) {
-		this.client._require({ phoneNumbers });
-		return this.client(`/number/deactivate`, { method: "POST", body: { phoneNumbers }, ...options });
-	}
+  /**
+   * Get porting requests - fetches a single request by portingId, or delegates to getPortRequests for listing
+   * @async
+   * @roles api, admin, developer, billing, user
+   * @param {Object} params - The parameters
+   * @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)
+   */
+  async getPortingRequests({ portingId, page, limit, options = {} } = {}) {
+    if (portingId) {
+      return this.getPortRequestById({ id: portingId, options });
+    }
+    return this.getPortRequests({ page, limit, options });
+  }
 
-	/**
-	 * Reactivate one or more previously deactivated phone numbers. Numbers must be in DEACTIVATED status to be reactivated. Reactivated numbers will return to PENDING or IN_PROGRESS status depending on their campaign assignment.
-	 * @async
-	 * @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
-	 * @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
-	 */
-	async reactivatePhoneNumbers({ phoneNumbers, options = {} }) {
-		this.client._require({ phoneNumbers });
-		return this.client(`/number/reactivate`, { method: "POST", body: { phoneNumbers }, ...options });
-	}
+  /**
+   * Assign phone numbers to a campaign by providing the campaign ID and a list of phone numbers to assign
+   * @async
+   * @roles api, admin, developer, billing, user
+   * @param {Object} params - The parameters for assigning phone numbers to a campaign
+   * @param {string} params.campaignId - The ID of the campaign to assign phone numbers to
+   * @param {string[]} params.phoneNumbers - The list of phone numbers to assign to the campaign
+   * @param {import('../SignalHouseSDK').RequestOptions} [params.options] - Additional options for the request
+   * @throws {Error} Throws an error if the campaignId or phoneNumbers parameter is missing
+   * @returns {Promise<Object>} A promise that resolves to the result of the assignment operation
+   */
+  async assignPhoneNumberToCampaign({ campaignId, phoneNumbers, options = {} }) {
+    this.client._require({ campaignId, phoneNumbers });
+    const safeCampaignId = encodeURIComponent(campaignId);
+    return this.client(`/number/assign/${safeCampaignId}`, { method: 'POST', body: { phoneNumbers }, ...options });
+  }
 
-	/**
-	 * Transfer unassigned phone numbers from one subgroup to another.
-	 * @async
-	 * @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
-	 */
-	async transferPhoneNumbers({ phoneNumbers, newSubgroupId, options = {} }) {
-		this.client._require({ phoneNumbers, newSubgroupId });
-		return this.client(`/number/transfer`, { method: "POST", body: { phoneNumbers, newSubgroupId }, ...options });
-	}
+  /**
+   * Unassign phone numbers from a campaign by providing a list of phone numbers to unassign. Note: This operation will unassign the specified phone numbers from any campaign they are currently assigned to.
+   * @async
+   * @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
+   * @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
+   */
+  async unassignPhoneNumbersFromCampaigns({ phoneNumbers, options = {} }) {
+    this.client._require({ phoneNumbers });
+    return this.client(`/number/unassign`, { method: 'POST', body: { phoneNumbers }, ...options });
+  }
 
-	/**
-	 * 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.
-	 * @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
-	 */
-	async searchNpaNxx({ country, state, city, npa, nxx, options = {} }) {
-		const queryString = this.client._getQueryString({ country, state, city, npa, nxx });
-		return this.client(`/number/lookup${queryString}`, { method: "GET", ...options });
-	}
+  /**
+   * 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.
+   * @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
+   * @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
+   */
+  async deletePhoneNumbers({ phoneNumbers, options = {} }) {
+    this.client._require({ phoneNumbers });
+    return this.client(`/number`, { method: 'DELETE', body: { phoneNumbers }, ...options });
+  }
 
-	/**
-	 * Batch lookup city/state for NPA/NXX pairs
-	 * @async
-	 * @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
-	 */
-	async lookupLocations({ entries, options = {} }) {
-		return this.client("/number/lookup/location", { method: "POST", body: { entries }, ...options });
-	}
+  /**
+   * Deactivate one or more phone numbers. Numbers must be in READY status to be deactivated. Deactivated numbers will not be able to send or receive messages but will remain assigned to their subgroup and campaign.
+   * @async
+   * @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
+   * @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
+   */
+  async deactivatePhoneNumbers({ phoneNumbers, options = {} }) {
+    this.client._require({ phoneNumbers });
+    return this.client(`/number/deactivate`, { method: 'POST', body: { phoneNumbers }, ...options });
+  }
 
-	/**
-	 * Migrate a phone number (or all numbers in a campaign/group) from v1 to v2
-	 * @async
-	 * @roles api, admin, developer, billing, user, signalhouse_api, signalhouse_admin, signalhouse_user
-	 * @param {Object} params - The parameters for migration
-	 * @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
-	 */
-	async migratePhoneNumberToV2({ phoneNumber, campaignId, groupId, options = {} }) {
-		return this.client(`/number/migrate`, { method: "POST", body: { phoneNumber, campaignId, groupId }, ...options });
-	}
-}
+  /**
+   * Reactivate one or more previously deactivated phone numbers. Numbers must be in DEACTIVATED status to be reactivated. Reactivated numbers will return to PENDING or IN_PROGRESS status depending on their campaign assignment.
+   * @async
+   * @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
+   * @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
+   */
+  async reactivatePhoneNumbers({ phoneNumbers, options = {} }) {
+    this.client._require({ phoneNumbers });
+    return this.client(`/number/reactivate`, { method: 'POST', body: { phoneNumbers }, ...options });
+  }
+
+  /**
+   * Transfer unassigned phone numbers from one subgroup to another.
+   * @async
+   * @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
+   */
+  async transferPhoneNumbers({ phoneNumbers, newSubgroupId, options = {} }) {
+    this.client._require({ phoneNumbers, newSubgroupId });
+    return this.client(`/number/transfer`, { method: 'POST', body: { phoneNumbers, newSubgroupId }, ...options });
+  }
+
+  /**
+   * 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.
+   * @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
+   */
+  async searchNpaNxx({ country, state, city, npa, nxx, options = {} }) {
+    const queryString = this.client._getQueryString({ country, state, city, npa, nxx });
+    return this.client(`/number/lookup${queryString}`, { method: 'GET', ...options });
+  }
+
+  /**
+   * Batch lookup city/state for NPA/NXX pairs
+   * @async
+   * @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
+   */
+  async lookupLocations({ entries, options = {} }) {
+    return this.client('/number/lookup/location', { method: 'POST', body: { entries }, ...options });
+  }
+
+  /**
+   * Migrate a phone number (or all numbers in a campaign/group) from v1 to v2
+   * @async
+   * @roles api, admin, developer, billing, user, signalhouse_api, signalhouse_admin, signalhouse_user
+   * @param {Object} params - The parameters for migration
+   * @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
+   */
+  async migratePhoneNumberToV2({ phoneNumber, campaignId, groupId, options = {} }) {
+    return this.client(`/number/migrate`, { method: 'POST', body: { phoneNumber, campaignId, groupId }, ...options });
+  }
+}