@unboundcx/sdk 2.2.6 → 2.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "2.2.6",
+  "version": "2.3.1",
   "description": "Official JavaScript SDK for the Unbound API - A comprehensive toolkit for integrating with Unbound's communication, AI, and data management services",
   "main": "index.js",
   "type": "module",

package/services/phoneNumbers.js

@@ -188,16 +188,29 @@ export class PhoneNumbersService {
   }
 
   async getRoutingOptions() {
-    const result = await this.sdk._fetch('/phoneNumbers/routing-options', 'GET');
+    const result = await this.sdk._fetch(
+      '/phoneNumbers/routing-options',
+      'GET',
+    );
     return result;
   }
 
   async getSupportedCountries() {
-    const result = await this.sdk._fetch('/phoneNumbers/supported-countries', 'GET');
+    const result = await this.sdk._fetch(
+      '/phoneNumbers/supported-countries',
+      'GET',
+    );
     return result;
   }
 
   // Porting Methods
+  
+  /**
+   * Check portability of phone numbers
+   * @param {Object} params
+   * @param {string[]} params.phoneNumbers - Array of +E.164 formatted phone numbers
+   * @returns {Promise<Object>} Portability check results
+   */
   async checkPortability({ phoneNumbers }) {
     this.sdk.validateParams(
       { phoneNumbers },
@@ -206,36 +219,80 @@ export class PhoneNumbersService {
       },
     );
 
-    const result = await this.sdk._fetch('/phoneNumbers/porting/portability-check', 'POST', {
-      body: { phoneNumbers }
-    });
+    const result = await this.sdk._fetch(
+      '/phoneNumbers/porting/portability-check',
+      'POST',
+      {
+        body: { phoneNumbers },
+      },
+    );
     return result;
   }
 
+  /**
+   * Create a draft porting order (no validation - can be built incrementally)
+   * @param {Object} params
+   * @param {string[]} [params.phoneNumbers] - Array of +E.164 formatted phone numbers
+   * @param {Object[]} [params.phoneNumberBlocks] - Array of phone number blocks  
+   * @param {string} [params.customerReference] - Customer-specified reference number
+   * @param {Object} [params.endUser] - End user information
+   * @param {Object} [params.endUser.admin] - Admin contact info
+   * @param {string} [params.endUser.admin.entityName] - Business/entity name
+   * @param {string} [params.endUser.admin.authPersonName] - Authorized person name
+   * @param {string} [params.endUser.admin.billingPhoneNumber] - Billing phone number
+   * @param {string} [params.endUser.admin.accountNumber] - Account number with current provider
+   * @param {string} [params.endUser.admin.taxIdentifier] - Tax identification number (EU)
+   * @param {string} [params.endUser.admin.pinPasscode] - PIN/passcode for account access
+   * @param {string} [params.endUser.admin.businessIdentifier] - Business identifier (EU)
+   * @param {Object} [params.endUser.location] - Location information
+   * @param {string} [params.endUser.location.streetAddress] - Street address
+   * @param {string} [params.endUser.location.extendedAddress] - Apt/suite/etc
+   * @param {string} [params.endUser.location.locality] - City
+   * @param {string} [params.endUser.location.administrativeArea] - State/province
+   * @param {string} [params.endUser.location.postalCode] - ZIP/postal code
+   * @param {string} [params.endUser.location.countryCode] - 2-letter country code
+   * @param {Object} [params.activationSettings] - Activation preferences
+   * @param {string} [params.activationSettings.focDatetimeRequested] - Requested FOC date/time
+   * @param {string} [params.activationSettings.focDatetimeActual] - Actual FOC date/time  
+   * @param {boolean} [params.activationSettings.fastPortEligible] - Fast port eligibility
+   * @param {string} [params.activationSettings.activationStatus] - Activation status
+   * @param {Object} [params.phoneNumberConfiguration] - Phone number config
+   * @param {string} [params.phoneNumberConfiguration.billingGroupId] - Billing group ID
+   * @param {string} [params.phoneNumberConfiguration.connectionId] - Connection ID
+   * @param {string} [params.phoneNumberConfiguration.messagingProfileId] - Messaging profile ID
+   * @param {string} [params.phoneNumberConfiguration.emergencyAddressId] - Emergency address ID
+   * @param {string} [params.phoneNumberConfiguration.phoneNumberType] - Phone number type
+   * @param {string} [params.phoneNumberConfiguration.description] - Description
+   * @param {string[]} [params.tags] - Array of tags for organization
+   * @returns {Promise<Object>} Created draft porting order with ID and status 'draft'
+   */
   async createPortingOrder({
     phoneNumbers,
     phoneNumberBlocks,
     customerReference,
     endUser,
     activationSettings,
-    webhookUrl,
-    ...additionalData
+    phoneNumberConfiguration,
+    tags
   } = {}) {
     // No validation - creates draft order that can be built incrementally
-    const body = {
-      ...additionalData
-    };
+    const body = {};
 
     if (phoneNumbers) body.phoneNumbers = phoneNumbers;
     if (phoneNumberBlocks) body.phoneNumberBlocks = phoneNumberBlocks;
     if (customerReference) body.customerReference = customerReference;
     if (endUser) body.endUser = endUser;
     if (activationSettings) body.activationSettings = activationSettings;
-    if (webhookUrl) body.webhookUrl = webhookUrl;
+    if (phoneNumberConfiguration) body.phoneNumberConfiguration = phoneNumberConfiguration;
+    if (tags) body.tags = tags;
 
-    const result = await this.sdk._fetch('/phoneNumbers/porting/orders', 'POST', {
-      body: body
-    });
+    const result = await this.sdk._fetch(
+      '/phoneNumbers/porting/orders',
+      'POST',
+      {
+        body: body,
+      },
+    );
     return result;
   }
 
@@ -245,25 +302,42 @@ export class PhoneNumbersService {
     status,
     customerReference,
     sort,
-    limit
+    limit,
   } = {}) {
     const params = new URLSearchParams();
-    
+
     if (page) params.append('page', page);
-    if (includePhoneNumbers !== undefined) params.append('includePhoneNumbers', includePhoneNumbers);
+    if (includePhoneNumbers !== undefined)
+      params.append('includePhoneNumbers', includePhoneNumbers);
     if (status) params.append('status', status);
-    if (customerReference) params.append('customerReference', customerReference);
+    if (customerReference)
+      params.append('customerReference', customerReference);
     if (sort) params.append('sort', sort);
     if (limit) params.append('limit', limit);
 
     const queryString = params.toString();
-    const url = queryString ? `/phoneNumbers/porting/orders?${queryString}` : '/phoneNumbers/porting/orders';
-    
+    const url = queryString
+      ? `/phoneNumbers/porting/orders?${queryString}`
+      : '/phoneNumbers/porting/orders';
+
     const result = await this.sdk._fetch(url, 'GET');
     return result;
   }
 
-  async getPortingOrder(id, { includePhoneNumbers = true } = {}) {
+  /**
+   * Get a porting order with optional related data
+   * @param {string} id - Porting order ID
+   * @param {Object} [options]
+   * @param {boolean} [options.includePhoneNumbers=true] - Include phone numbers array
+   * @param {boolean} [options.includeExceptions=true] - Include exceptions array
+   * @param {boolean} [options.includeDocuments=true] - Include documents array with upload status
+   * @returns {Promise<Object>} Porting order with requested related data
+   */
+  async getPortingOrder(id, { 
+    includePhoneNumbers = true, 
+    includeExceptions = true, 
+    includeDocuments = true 
+  } = {}) {
     this.sdk.validateParams(
       { id },
       {
@@ -272,31 +346,70 @@ export class PhoneNumbersService {
     );
 
     const params = new URLSearchParams();
-    if (includePhoneNumbers !== undefined) params.append('includePhoneNumbers', includePhoneNumbers);
-    
+    if (includePhoneNumbers !== undefined)
+      params.append('includePhoneNumbers', includePhoneNumbers);
+    if (includeExceptions !== undefined)
+      params.append('includeExceptions', includeExceptions);
+    if (includeDocuments !== undefined)
+      params.append('includeDocuments', includeDocuments);
+
     const queryString = params.toString();
-    const url = queryString ? `/phoneNumbers/porting/orders/${id}?${queryString}` : `/phoneNumbers/porting/orders/${id}`;
-    
+    const url = queryString
+      ? `/phoneNumbers/porting/orders/${id}?${queryString}`
+      : `/phoneNumbers/porting/orders/${id}`;
+
     const result = await this.sdk._fetch(url, 'GET');
     return result;
   }
 
-  async updatePortingOrder(id, updateData) {
+  /**
+   * Update a draft porting order (same parameters as createPortingOrder)
+   * @param {string} id - Porting order ID
+   * @param {Object} params - Same parameters as createPortingOrder
+   * @returns {Promise<Object>} Updated porting order
+   */
+  async updatePortingOrder(id, {
+    phoneNumbers,
+    phoneNumberBlocks,
+    customerReference,
+    endUser,
+    activationSettings,
+    phoneNumberConfiguration,
+    tags
+  } = {}) {
     this.sdk.validateParams(
-      { id, updateData },
+      { id },
       {
         id: { type: 'string', required: true },
-        updateData: { type: 'object', required: true },
       },
     );
 
-    const result = await this.sdk._fetch(`/phoneNumbers/porting/orders/${id}`, 'PUT', {
-      body: updateData
-    });
+    const body = {};
+
+    if (phoneNumbers) body.phoneNumbers = phoneNumbers;
+    if (phoneNumberBlocks) body.phoneNumberBlocks = phoneNumberBlocks;
+    if (customerReference) body.customerReference = customerReference;
+    if (endUser) body.endUser = endUser;
+    if (activationSettings) body.activationSettings = activationSettings;
+    if (phoneNumberConfiguration) body.phoneNumberConfiguration = phoneNumberConfiguration;
+    if (tags) body.tags = tags;
+
+    const result = await this.sdk._fetch(
+      `/phoneNumbers/porting/orders/${id}`,
+      'PUT',
+      {
+        body: body,
+      },
+    );
     return result;
   }
 
-  async submitPortingOrder(id, submissionData = {}) {
+  /**
+   * Submit a draft porting order for processing (validates all required fields)
+   * @param {string} id - Porting order ID
+   * @returns {Promise<Object>} Submitted porting order with Telnyx status
+   */
+  async submitPortingOrder(id) {
     this.sdk.validateParams(
       { id },
       {
@@ -304,15 +417,18 @@ export class PhoneNumbersService {
       },
     );
 
-    // Add the submit status to trigger validation and Telnyx submission
+    // Submit the draft order (status is implied)
     const body = {
-      ...submissionData,
-      status: 'submit'
+      status: 'submit',
     };
 
-    const result = await this.sdk._fetch(`/phoneNumbers/porting/orders/${id}`, 'PUT', {
-      body: body
-    });
+    const result = await this.sdk._fetch(
+      `/phoneNumbers/porting/orders/${id}`,
+      'PUT',
+      {
+        body: body,
+      },
+    );
     return result;
   }
 
@@ -321,7 +437,7 @@ export class PhoneNumbersService {
     fileContent,
     contentType = 'application/pdf',
     documentType = 'loa',
-    portingOrderId
+    portingOrderId,
   }) {
     this.sdk.validateParams(
       { filename, fileContent },
@@ -335,14 +451,18 @@ export class PhoneNumbersService {
       filename,
       fileContent,
       contentType,
-      documentType
+      documentType,
     };
 
     if (portingOrderId) body.portingOrderId = portingOrderId;
 
-    const result = await this.sdk._fetch('/phoneNumbers/porting/documents', 'POST', {
-      body: body
-    });
+    const result = await this.sdk._fetch(
+      '/phoneNumbers/porting/documents',
+      'POST',
+      {
+        body: body,
+      },
+    );
     return result;
   }
 
@@ -357,10 +477,12 @@ export class PhoneNumbersService {
     const params = new URLSearchParams();
     if (page) params.append('page', page);
     if (limit) params.append('limit', limit);
-    
+
     const queryString = params.toString();
-    const url = queryString ? `/phoneNumbers/porting/orders/${id}/events?${queryString}` : `/phoneNumbers/porting/orders/${id}/events`;
-    
+    const url = queryString
+      ? `/phoneNumbers/porting/orders/${id}/events?${queryString}`
+      : `/phoneNumbers/porting/orders/${id}/events`;
+
     const result = await this.sdk._fetch(url, 'GET');
     return result;
   }