@unboundcx/sdk 2.1.2 → 2.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboundcx/sdk",
-  "version": "2.1.2",
+  "version": "2.2.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/objects.js

@@ -1,87 +1,214 @@
+/**
+ * Objects Service - Manage data objects in the Unbound platform
+ * 
+ * This service supports both new object-based signatures and legacy positional arguments
+ * for backward compatibility. New projects should use the object-based signatures.
+ * 
+ * @example
+ * // Preferred (new) usage:
+ * const result = await sdk.objects.query({
+ *   object: 'users',
+ *   select: ['id', 'name', 'email'],
+ *   where: { status: 'active' },
+ *   limit: 100
+ * });
+ * 
+ * @example  
+ * // Legacy (deprecated) usage still supported:
+ * const result = await sdk.objects.query('users', { status: 'active' });
+ */
 export class ObjectsService {
   constructor(sdk) {
     this.sdk = sdk;
   }
 
-  async byId({ id, expandDetails = false }) {
-    this.sdk.validateParams(
-      { id, expandDetails },
-      {
-        id: { type: 'string', required: true },
-        expandDetails: { type: 'boolean', required: false },
-      },
-    );
+  /**
+   * Retrieve an object by ID
+   * 
+   * Preferred usage (new signature):
+   * sdk.objects.byId({ id: 'someId', expandDetails: true })
+   * 
+   * Legacy usage (deprecated, but supported):
+   * sdk.objects.byId('someId', { 'select[]': ['field1', 'field2'] })
+   * 
+   * @param {string|object} args - Either ID string or options object
+   * @returns {Promise} Object data
+   */
+  async byId(...args) {
+    // New signature: byId({ id, expandDetails })
+    if (args.length === 1 && typeof args[0] === 'object' && !Array.isArray(args[0])) {
+      const { id, expandDetails = false } = args[0];
+      
+      this.sdk.validateParams(
+        { id, expandDetails },
+        {
+          id: { type: 'string', required: true },
+          expandDetails: { type: 'boolean', required: false },
+        },
+      );
 
-    const query = {};
-    if (expandDetails) query.expandDetails = expandDetails;
+      const query = {};
+      if (expandDetails) query.expandDetails = expandDetails;
 
-    const params = {
-      query,
-    };
+      const params = { query };
+      return await this.sdk._fetch(`/object/${id}`, 'GET', params);
+    }
+    
+    // Old signature: byId(id, queryParams) 
+    if (args.length >= 1 && typeof args[0] === 'string') {
+      const [id, queryParams = {}] = args;
+      
+      this.sdk.validateParams(
+        { id },
+        {
+          id: { type: 'string', required: true },
+        },
+      );
 
-    const result = await this.sdk._fetch(`/object/${id}`, 'GET', params);
-    return result;
+      const query = { ...queryParams };
+      const params = { query };
+      return await this.sdk._fetch(`/object/${id}`, 'GET', params);
+    }
+
+    throw new Error('Invalid arguments for byId method');
   }
 
-  async query({
-    object,
-    select = null,
-    where = {},
-    limit = 100,
-    nextId = null,
-    previousId = null,
-    orderByDirection = 'DESC',
-    expandDetails = false,
-  }) {
-    this.sdk.validateParams(
-      { object, select, where, limit, nextId, previousId, orderByDirection, expandDetails },
-      {
-        object: { type: 'string', required: true },
-        select: { type: 'object', required: false }, // array or string
-        where: { type: 'object', required: false },
-        limit: { type: 'number', required: false },
-        nextId: { type: 'string', required: false },
-        previousId: { type: 'string', required: false },
-        orderByDirection: { type: 'string', required: false },
-        expandDetails: { type: 'boolean', required: false },
-      },
-    );
+  /**
+   * Query objects with filters
+   * 
+   * Preferred usage (new signature):
+   * sdk.objects.query({ 
+   *   object: 'users', 
+   *   select: ['id', 'name'], 
+   *   where: { status: 'active' },
+   *   limit: 50,
+   *   expandDetails: true
+   * })
+   * 
+   * Legacy usage (deprecated, but supported):
+   * sdk.objects.query('users', { 'select[]': ['id', 'name'], status: 'active' })
+   * 
+   * @param {object} args - Query parameters
+   * @returns {Promise} Query results
+   */
+  async query(...args) {
+    // New signature: query({ object, select, where, ... })
+    if (args.length === 1 && typeof args[0] === 'object' && args[0].object) {
+      const {
+        object,
+        select = null,
+        where = {},
+        limit = 100,
+        nextId = null,
+        previousId = null,
+        orderByDirection = 'DESC',
+        expandDetails = false,
+      } = args[0];
+
+      this.sdk.validateParams(
+        { object, select, where, limit, nextId, previousId, orderByDirection, expandDetails },
+        {
+          object: { type: 'string', required: true },
+          select: { type: 'object', required: false }, // array or string
+          where: { type: 'object', required: false },
+          limit: { type: 'number', required: false },
+          nextId: { type: 'string', required: false },
+          previousId: { type: 'string', required: false },
+          orderByDirection: { type: 'string', required: false },
+          expandDetails: { type: 'boolean', required: false },
+        },
+      );
+
+      const query = { ...where };
+      if (select !== null) query.select = select;
+      if (limit !== 100) query.limit = limit;
+      if (nextId !== null) query.nextId = nextId;
+      if (previousId !== null) query.previousId = previousId;
+      if (orderByDirection !== 'DESC') query.orderByDirection = orderByDirection;
+      if (expandDetails) query.expandDetails = expandDetails;
+
+      const params = { query };
+      return await this.sdk._fetch(`/object/query/${object}`, 'GET', params);
+    }
 
-    const query = { ...where };
-    if (select !== null) query.select = select;
-    if (limit !== 100) query.limit = limit;
-    if (nextId !== null) query.nextId = nextId;
-    if (previousId !== null) query.previousId = previousId;
-    if (orderByDirection !== 'DESC') query.orderByDirection = orderByDirection;
-    if (expandDetails) query.expandDetails = expandDetails;
+    // Old signature: query(objectName, queryParams)
+    if (args.length === 2 && typeof args[0] === 'string') {
+      const [objectName, queryParams = {}] = args;
 
-    const params = { query };
+      this.sdk.validateParams(
+        { object: objectName },
+        {
+          object: { type: 'string', required: true },
+        },
+      );
 
-    const result = await this.sdk._fetch(`/object/query/${object}`, 'GET', params);
-    return result;
+      const params = { query: queryParams };
+      return await this.sdk._fetch(`/object/query/${objectName}`, 'GET', params);
+    }
+
+    throw new Error('Invalid arguments for query method');
   }
 
-  async updateById({ object, id, update }) {
-    this.sdk.validateParams(
-      { object, id, update },
-      {
-        object: { type: 'string', required: true },
-        id: { type: 'string', required: true },
-        update: { type: 'object', required: true },
-      },
-    );
+  /**
+   * Update an object record by ID
+   * 
+   * Preferred usage (new signature):
+   * sdk.objects.updateById({ object: 'users', id: 'userId', update: { name: 'Jane' } })
+   * 
+   * Legacy usage (deprecated, but supported):
+   * sdk.objects.updateById('users', 'userId', { name: 'Jane' })
+   * 
+   * @param {object} args - Update parameters
+   * @returns {Promise} Updated object data
+   */
+  async updateById(...args) {
+    // New signature: updateById({ object, id, update })
+    if (args.length === 1 && typeof args[0] === 'object' && args[0].object) {
+      const { object, id, update } = args[0];
+
+      this.sdk.validateParams(
+        { object, id, update },
+        {
+          object: { type: 'string', required: true },
+          id: { type: 'string', required: true },
+          update: { type: 'object', required: true },
+        },
+      );
 
-    const params = {
-      body: {
-        where: {
-          id,
+      const params = {
+        body: {
+          where: { id },
+          update,
         },
-        update,
-      },
-    };
+      };
 
-    const result = await this.sdk._fetch(`/object/${object}`, 'PUT', params);
-    return result;
+      return await this.sdk._fetch(`/object/${object}`, 'PUT', params);
+    }
+
+    // Old signature: updateById(object, id, update)
+    if (args.length === 3) {
+      const [object, id, update] = args;
+
+      this.sdk.validateParams(
+        { object, id, update },
+        {
+          object: { type: 'string', required: true },
+          id: { type: 'string', required: true },
+          update: { type: 'object', required: true },
+        },
+      );
+
+      const params = {
+        body: {
+          where: { id },
+          update,
+        },
+      };
+
+      return await this.sdk._fetch(`/object/${object}`, 'PUT', params);
+    }
+
+    throw new Error('Invalid arguments for updateById method');
   }
 
   async update({ object, where, update }) {
@@ -105,21 +232,52 @@ export class ObjectsService {
     return result;
   }
 
-  async create({ object, body }) {
-    this.sdk.validateParams(
-      { object, body },
-      {
-        object: { type: 'string', required: true },
-        body: { type: 'object', required: true },
-      },
-    );
+  /**
+   * Create a new object record
+   * 
+   * Preferred usage (new signature):
+   * sdk.objects.create({ object: 'users', body: { name: 'John', email: 'john@example.com' } })
+   * 
+   * Legacy usage (deprecated, but supported):
+   * sdk.objects.create('users', { name: 'John', email: 'john@example.com' })
+   * 
+   * @param {object} args - Creation parameters
+   * @returns {Promise} Created object data
+   */
+  async create(...args) {
+    // New signature: create({ object, body })
+    if (args.length === 1 && typeof args[0] === 'object' && args[0].object) {
+      const { object, body } = args[0];
+
+      this.sdk.validateParams(
+        { object, body },
+        {
+          object: { type: 'string', required: true },
+          body: { type: 'object', required: true },
+        },
+      );
 
-    const params = {
-      body,
-    };
+      const params = { body };
+      return await this.sdk._fetch(`/object/${object}`, 'POST', params);
+    }
 
-    const result = await this.sdk._fetch(`/object/${object}`, 'POST', params);
-    return result;
+    // Old signature: create(object, body)
+    if (args.length === 2) {
+      const [object, body] = args;
+
+      this.sdk.validateParams(
+        { object, body },
+        {
+          object: { type: 'string', required: true },
+          body: { type: 'object', required: true },
+        },
+      );
+
+      const params = { body };
+      return await this.sdk._fetch(`/object/${object}`, 'POST', params);
+    }
+
+    throw new Error('Invalid arguments for create method');
   }
 
   async delete({ object, where }) {

package/services/phoneNumbers.js

@@ -196,6 +196,151 @@ export class PhoneNumbersService {
     const result = await this.sdk._fetch('/phoneNumbers/supported-countries', 'GET');
     return result;
   }
+
+  // Porting Methods
+  async checkPortability({ phoneNumbers }) {
+    this.sdk.validateParams(
+      { phoneNumbers },
+      {
+        phoneNumbers: { type: 'array', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch('/phoneNumbers/porting/portability-check', 'POST', {
+      phoneNumbers
+    });
+    return result;
+  }
+
+  async createPortingOrder({
+    phoneNumbers,
+    phoneNumberBlocks,
+    customerReference,
+    endUser,
+    activationSettings,
+    webhookUrl,
+    ...additionalData
+  }) {
+    if (!phoneNumbers && !phoneNumberBlocks) {
+      throw new Error('Either phoneNumbers or phoneNumberBlocks is required');
+    }
+
+    const body = {
+      ...additionalData
+    };
+
+    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;
+
+    const result = await this.sdk._fetch('/phoneNumbers/porting/orders', 'POST', body);
+    return result;
+  }
+
+  async getPortingOrders({
+    page,
+    includePhoneNumbers = true,
+    status,
+    customerReference,
+    sort,
+    limit
+  } = {}) {
+    const params = new URLSearchParams();
+    
+    if (page) params.append('page', page);
+    if (includePhoneNumbers !== undefined) params.append('includePhoneNumbers', includePhoneNumbers);
+    if (status) params.append('status', status);
+    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 result = await this.sdk._fetch(url, 'GET');
+    return result;
+  }
+
+  async getPortingOrder(id, { includePhoneNumbers = true } = {}) {
+    this.sdk.validateParams(
+      { id },
+      {
+        id: { type: 'string', required: true },
+      },
+    );
+
+    const params = new URLSearchParams();
+    if (includePhoneNumbers !== undefined) params.append('includePhoneNumbers', includePhoneNumbers);
+    
+    const queryString = params.toString();
+    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) {
+    this.sdk.validateParams(
+      { id, updateData },
+      {
+        id: { type: 'string', required: true },
+        updateData: { type: 'object', required: true },
+      },
+    );
+
+    const result = await this.sdk._fetch(`/phoneNumbers/porting/orders/${id}`, 'PATCH', updateData);
+    return result;
+  }
+
+  async uploadPortingDocument({
+    filename,
+    fileContent,
+    contentType = 'application/pdf',
+    documentType = 'loa',
+    portingOrderId
+  }) {
+    this.sdk.validateParams(
+      { filename, fileContent },
+      {
+        filename: { type: 'string', required: true },
+        fileContent: { type: 'string', required: true },
+      },
+    );
+
+    const body = {
+      filename,
+      fileContent,
+      contentType,
+      documentType
+    };
+
+    if (portingOrderId) body.portingOrderId = portingOrderId;
+
+    const result = await this.sdk._fetch('/phoneNumbers/porting/documents', 'POST', body);
+    return result;
+  }
+
+  async getPortingEvents(id, { page, limit } = {}) {
+    this.sdk.validateParams(
+      { id },
+      {
+        id: { type: 'string', required: true },
+      },
+    );
+
+    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 result = await this.sdk._fetch(url, 'GET');
+    return result;
+  }
 }
 
 export class PhoneNumberCarrierService {