@unboundcx/sdk 2.4.2 → 2.5.0

package/package.json

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

@@ -206,21 +206,32 @@ export class PhoneNumbersService {
   // Porting Methods
   
   /**
-   * Check portability of phone numbers
+   * Check portability of phone numbers using two-phase validation
+   * 
+   * Phase 1 (Default): Internal validation using LRN lookup
+   * - Validates ownership, duplicates, and carrier compatibility
+   * - Sets portabilityStatus to 'pending'
+   * 
+   * Phase 2 (runPortabilityCheck: true): External validation 
+   * - Runs full portability check with carrier
+   * - Updates portabilityStatus to 'portable', 'not-portable', or 'error'
+   * 
    * @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
+   * @param {boolean} [params.runPortabilityCheck=false] - Run external portability validation
    * @returns {Promise<Object>} Portability check results
    */
-  async checkPortability({ phoneNumbers, portingOrderId }) {
+  async checkPortability({ phoneNumbers, portingOrderId, runPortabilityCheck = false }) {
     this.sdk.validateParams(
-      { phoneNumbers },
+      { phoneNumbers, runPortabilityCheck },
       {
         phoneNumbers: { type: 'array', required: true },
+        runPortabilityCheck: { type: 'boolean', required: false },
       },
     );
 
-    const body = { phoneNumbers };
+    const body = { phoneNumbers, runPortabilityCheck };
     if (portingOrderId) body.portingOrderId = portingOrderId;
 
     const result = await this.sdk._fetch(
@@ -265,11 +276,18 @@ export class PhoneNumbersService {
    *   endUser: { admin: { entityName: "My Company" } }
    * });
    * 
-   * // Add phone numbers with validation
+   * // Phase 1: Add numbers with internal validation (pending status)
    * await sdk.phoneNumbers.checkPortability({
    *   phoneNumbers: ["+15551234567"],
    *   portingOrderId: order.id
    * });
+   * 
+   * // Phase 2: Run external portability check when ready
+   * await sdk.phoneNumbers.checkPortability({
+   *   phoneNumbers: ["+15551234567"],
+   *   portingOrderId: order.id,
+   *   runPortabilityCheck: true
+   * });
    */
   async createPortingOrder({
     customerReference,