@unboundcx/sdk 2.3.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "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

@@ -209,9 +209,10 @@ export class PhoneNumbersService {
    * Check portability of phone numbers
    * @param {Object} params
    * @param {string[]} params.phoneNumbers - Array of +E.164 formatted phone numbers
+   * @param {string} [params.portingOrderId] - Optional porting order ID to save results to
    * @returns {Promise<Object>} Portability check results
    */
-  async checkPortability({ phoneNumbers }) {
+  async checkPortability({ phoneNumbers, portingOrderId }) {
     this.sdk.validateParams(
       { phoneNumbers },
       {
@@ -219,21 +220,22 @@ export class PhoneNumbersService {
       },
     );
 
+    const body = { phoneNumbers };
+    if (portingOrderId) body.portingOrderId = portingOrderId;
+
     const result = await this.sdk._fetch(
       '/phoneNumbers/porting/portability-check',
       'POST',
       {
-        body: { phoneNumbers },
+        body: body,
       },
     );
     return result;
   }
 
   /**
-   * Create a draft porting order (no validation - can be built incrementally)
+   * Create a draft porting order (no phone numbers - add them via checkPortability)
    * @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
@@ -252,38 +254,34 @@ export class PhoneNumbersService {
    * @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.activationSettings.focDatetimeRequested] - Requested FOC date/time (ISO 8601 UTC)
+   * @param {boolean} [params.activationSettings.fastPortEligible] - Request fast port if available
    * @param {string[]} [params.tags] - Array of tags for organization
    * @returns {Promise<Object>} Created draft porting order with ID and status 'draft'
+   * @example
+   * // Create empty draft order, then add numbers via checkPortability
+   * const order = await sdk.phoneNumbers.createPortingOrder({
+   *   customerReference: "CUST-123",
+   *   endUser: { admin: { entityName: "My Company" } }
+   * });
+   * 
+   * // Add phone numbers with validation
+   * await sdk.phoneNumbers.checkPortability({
+   *   phoneNumbers: ["+15551234567"],
+   *   portingOrderId: order.id
+   * });
    */
   async createPortingOrder({
-    phoneNumbers,
-    phoneNumberBlocks,
     customerReference,
     endUser,
     activationSettings,
-    phoneNumberConfiguration,
     tags
   } = {}) {
-    // No validation - creates draft order that can be built incrementally
+    // Creates draft order without phone numbers - use checkPortability to add them
     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(
@@ -324,7 +322,20 @@ export class PhoneNumbersService {
     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 },
       {
@@ -335,6 +346,10 @@ export class PhoneNumbersService {
     const params = new URLSearchParams();
     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
@@ -346,18 +361,19 @@ export class PhoneNumbersService {
   }
 
   /**
-   * Update a draft porting order (same parameters as createPortingOrder)
+   * Update a draft porting order (order info only - manage numbers via checkPortability)
    * @param {string} id - Porting order ID
-   * @param {Object} params - Same parameters as createPortingOrder
+   * @param {Object} params - Order information to update
+   * @param {string} [params.customerReference] - Customer-specified reference number
+   * @param {Object} [params.endUser] - End user information
+   * @param {Object} [params.activationSettings] - Activation preferences
+   * @param {string[]} [params.tags] - Array of tags for organization
    * @returns {Promise<Object>} Updated porting order
    */
   async updatePortingOrder(id, {
-    phoneNumbers,
-    phoneNumberBlocks,
     customerReference,
     endUser,
     activationSettings,
-    phoneNumberConfiguration,
     tags
   } = {}) {
     this.sdk.validateParams(
@@ -369,12 +385,9 @@ export class PhoneNumbersService {
 
     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(
@@ -415,6 +428,30 @@ export class PhoneNumbersService {
     return result;
   }
 
+  /**
+   * Delete/cancel a porting order (soft delete)
+   * - Draft orders: Immediately cancelled locally
+   * - Submitted orders: Cancelled via Telnyx, then status updated to cancel-pending
+   * - Cannot delete orders within 48 hours of FOC date
+   * - Cannot delete already completed or cancelled orders
+   * @param {string} id - Porting order ID
+   * @returns {Promise<Object>} Cancellation result with new status
+   */
+  async deletePortingOrder(id) {
+    this.sdk.validateParams(
+      { id },
+      {
+        id: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/phoneNumbers/porting/orders/${id}`,
+      'DELETE'
+    );
+    return result;
+  }
+
   async uploadPortingDocument({
     filename,
     fileContent,