@unboundcx/sdk 2.6.6 → 2.6.8

package/package.json

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

@@ -654,6 +654,162 @@ export class PhoneNumbersService {
     );
     return result;
   }
+
+  /**
+   * Sync a porting order with the carrier
+   * Fetches the latest order details and comments from the carrier and updates the local database
+   * @param {string} id - Porting order ID
+   * @returns {Promise<Object>} Sync results including updates made and comments added
+   * @example
+   * const syncResult = await sdk.phoneNumbers.syncPortingOrder("port_123...");
+   * // Returns:
+   * // {
+   * //   id: "port_123...",
+   * //   carrierOrderId: "carrier_abc123",
+   * //   orderUpdated: true,
+   * //   commentsAdded: 2,
+   * //   errors: []
+   * // }
+   */
+  async syncPortingOrder(id) {
+    this.sdk.validateParams(
+      { id },
+      {
+        id: { type: 'string', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/phoneNumbers/porting/orders/${id}/sync`,
+      'POST',
+    );
+    return result;
+  }
+
+  /**
+   * Get comments for a porting order
+   * @param {string} id - Porting order ID
+   * @param {Object} [options] - Query options
+   * @param {string} [options.includeInternal='true'] - Include internal comments ('true', 'false', 'only')
+   * @returns {Promise<Object>} Comments list with metadata
+   * @example
+   * // Get all comments
+   * const allComments = await sdk.phoneNumbers.getPortingComments("port_123...");
+   * 
+   * // Get only public comments
+   * const publicComments = await sdk.phoneNumbers.getPortingComments("port_123...", { includeInternal: 'false' });
+   * 
+   * // Get only internal comments
+   * const internalComments = await sdk.phoneNumbers.getPortingComments("port_123...", { includeInternal: 'only' });
+   */
+  async getPortingComments(id, { includeInternal = 'true' } = {}) {
+    this.sdk.validateParams(
+      { id },
+      {
+        id: { type: 'string', required: true },
+      },
+    );
+
+    const params = new URLSearchParams();
+    if (includeInternal !== 'true') {
+      params.append('includeInternal', includeInternal);
+    }
+
+    const queryString = params.toString();
+    const url = `/phoneNumbers/porting/orders/${id}/comments${queryString ? '?' + queryString : ''}`;
+
+    const result = await this.sdk._fetch(url, 'GET');
+    return result;
+  }
+
+  /**
+   * Post a comment on a porting order
+   * @param {string} id - Porting order ID
+   * @param {Object} params - Comment parameters
+   * @param {string} params.comment - Comment body text
+   * @param {boolean} [params.isInternal=false] - Whether this is an internal comment (not shared with carrier)
+   * @returns {Promise<Object>} Created comment details
+   * @example
+   * // Post a public comment (shared with carrier)
+   * const publicComment = await sdk.phoneNumbers.postPortingComment("port_123...", {
+   *   comment: "Please expedite this port request",
+   *   isInternal: false
+   * });
+   * 
+   * // Post an internal comment (team use only)
+   * const internalComment = await sdk.phoneNumbers.postPortingComment("port_123...", {
+   *   comment: "Customer called - they need this ASAP",
+   *   isInternal: true
+   * });
+   */
+  async postPortingComment(id, { comment, isInternal = false }) {
+    this.sdk.validateParams(
+      { id, comment },
+      {
+        id: { type: 'string', required: true },
+        comment: { type: 'string', required: true },
+        isInternal: { type: 'boolean', required: false },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      `/phoneNumbers/porting/orders/${id}/comments`,
+      'POST',
+      {
+        body: { comment, isInternal },
+      },
+    );
+    return result;
+  }
+
+  /**
+   * Auto-create porting orders by grouping phone numbers by carrier
+   * 
+   * Analyzes phone numbers using internal LRN lookup, groups them by carrier,
+   * and either previews the groupings (dry run) or creates separate porting 
+   * orders for each carrier group.
+   * 
+   * @param {Object} params
+   * @param {string[]} params.phoneNumbers - Array of +E.164 formatted phone numbers (max 100)
+   * @param {string} params.name - Base name for orders (will be appended with carrier names)
+   * @param {boolean} [params.dryRun=false] - If true, returns preview without creating orders
+   * @returns {Promise<Object>} Carrier groups and creation results
+   * @example
+   * // Preview carrier groupings
+   * const preview = await sdk.phoneNumbers.autoCreateOrders({
+   *   phoneNumbers: ['+15551234567', '+15551234568', '+15551234569'],
+   *   name: 'Q1 2025 Port',
+   *   dryRun: true
+   * });
+   * // Returns carrier groups with proposed order names
+   * 
+   * // Create orders for each carrier
+   * const result = await sdk.phoneNumbers.autoCreateOrders({
+   *   phoneNumbers: ['+15551234567', '+15551234568', '+15551234569'],
+   *   name: 'Q1 2025 Port',
+   *   dryRun: false
+   * });
+   * // Returns created orders and any errors
+   */
+  async autoCreateOrders({ phoneNumbers, name, dryRun = false }) {
+    this.sdk.validateParams(
+      { phoneNumbers, name },
+      {
+        phoneNumbers: { type: 'array', required: true },
+        name: { type: 'string', required: true },
+        dryRun: { type: 'boolean', required: false },
+      },
+    );
+
+    const result = await this.sdk._fetch(
+      '/phoneNumbers/porting/auto-create-orders',
+      'POST',
+      {
+        body: { phoneNumbers, name, dryRun },
+      },
+    );
+    return result;
+  }
 }
 
 export class PhoneNumberCarrierService {