carbon-baas-sdk 1.0.3 → 1.0.4

package/README.md

@@ -22,8 +22,12 @@ const carbon = require('carbon-baas-sdk');
 
 carbon.initialize('your_api_key_here', 'sandbox');
 
-// Create an account
-carbon.createAccount('customer_id', 'static')
+// Create an account for a third-party customer
+carbon.createAccount({
+  account_type: 'static',
+  third_party: true,
+  customer_id: 'customer_123'
+})
   .then(response => console.log(response))
   .catch(error => console.error(error));
 
@@ -31,25 +35,34 @@ carbon.createAccount('customer_id', 'static')
 carbon.fetchAccount('account_number')
   .then(response => console.log(response))
   .catch(error => console.error(error));
+
+// Fetch all accounts with pagination
+carbon.fetchAccounts(1, 10) // page 1, limit 10
+  .then(response => console.log(response))
+  .catch(error => console.error(error));
 ```
 
 ### ES Modules
 
 ```javascript
-import { initialize, createAccount, fetchAccount } from 'carbon-baas-sdk';
+import { initialize, createAccount, fetchAccount, fetchAccounts } from 'carbon-baas-sdk';
 
 initialize('your_api_key_here', 'sandbox');
 
-// Create an account
-const account = await createAccount('customer_id', 'static');
+// Create an account for a third-party customer
+const account = await createAccount({
+  account_type: 'static',
+  third_party: true,
+  customer_id: 'customer_123'
+});
 console.log(account);
 
 // Fetch an account
 const accountDetails = await fetchAccount('account_number');
 console.log(accountDetails);
 
-//Fetch accounts
-const accounts = await fetchAccounts(page?: number, limit?: number);
+// Fetch accounts
+const accounts = await fetchAccounts(1, 10); // page 1, limit 10
 console.log(accounts);
 ```
 
@@ -69,9 +82,16 @@ initialize(apiKey: string, mode: 'live' | 'sandbox')
 ### Accounts
 ```javascript
 createAccount(accountData: CreateAccountRequest)
-// accountData: { customer_id: string, account_type: string }
+// accountData: { 
+//   account_type: "static",      // Must always be "static"
+//   third_party?: boolean,       // true for third-party customer, false for own business sub-account (defaults to true)
+//   customer_id?: string,        // Required if third_party is true
+//   account_name?: string        // Required if third_party is false
+// }
 
 fetchAccount(accountNumber: string)
+
+fetchAccounts(page?: number, limit?: number)
 ```
 
 ### Customers
@@ -150,16 +170,27 @@ resendWebhookEvent(eventId: string)
 
 ### Managing Accounts
 ```javascript
-import { createAccount, fetchAccount } from 'carbon-baas-sdk';
+import { createAccount, fetchAccount, fetchAccounts } from 'carbon-baas-sdk';
+
+// Create an account for a third-party customer
+const newCustomerAccount = await createAccount({
+  account_type: 'static',
+  third_party: true,
+  customer_id: 'customer_123'
+});
 
-// Create an account
-const newAccount = await createAccount({
-  customer_id: 'customer_123',
-  account_type: 'static'
+// Create a sub-account for your own business (for collections)
+const newSubAccount = await createAccount({
+  account_type: 'static',
+  third_party: false,
+  account_name: 'Collections'
 });
 
 // Fetch account details
 const accountDetails = await fetchAccount('1234567890');
+
+// Fetch all accounts (with pagination)
+const accounts = await fetchAccounts(1, 20); // page 1, 20 items per page
 ```
 
 ### Managing Customers

package/dist/accounts.d.ts

@@ -1,6 +1,16 @@
 interface CreateAccountRequest {
-    customer_id: string;
-    account_type: string;
+    /** Must always be "static". */
+    account_type: "static";
+    /**
+     * Set to true when creating an account for a third-party customer (business use).
+     * Set to false when creating a sub-account for your own business (collections).
+     * Defaults to true if not provided.
+     */
+    third_party?: boolean;
+    /** Required if third_party is true. The customer to associate the account with. */
+    customer_id?: string;
+    /** Required if third_party is false. The sub-account name (e.g."SUBACCOUNT" -> BUSINESS NAME - SUBACCOUNT). */
+    account_name?: string;
 }
 export declare function createAccount(accountData: CreateAccountRequest): Promise<any>;
 export declare function fetchAccount(accountNumber: string): Promise<any>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carbon-baas-sdk",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "## Welcome to our API Developer Documentation\n\nCarbon aims to unlock the full potential of your business with a feature-rich account designed for growth.\n\n## Integrations\n\nWe aim to provide our APIs for developers and businesses to offer financial services to their existing customer base through REST APIs without doing the heavy lifting. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\n### Authentication\n\n`Authorization : API Key`\n\nHeader  \n`x-carbon-key : value`\n\n`x-carbon-key` can be generated via developer page on Carbon Business\n\n| Enviroment | URL |\n| --- | --- |\n| Live |  |\n| Sandbox | [https://carbonapistagingsecure.getcarbon.co/baas/api](https://carbonapistagingsecure.getcarbon.co/baas/api) |\n\n### **Handling Errors**\n\nWe use the conventional HTTP response codes to indicate the success or failure of an API request.  \nCodes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.). Codes in the 5xx range indicate an error with our servers.\n\n| Error | Description |\n| --- | --- |\n| 400 - Bad Request | The request was unacceptable, often due to missing a required parameter. |\n| 401 - Unauthorized | Not a valid API key was provided. |\n| 402 - Request Failed | The parameters were valid but the request failed. |\n| 403 - Forbidden | The API key doesn't have permission to perform the request. |\n| 404 - Not Found | The requested resource doesn't exist. |\n| 429 - Too Many Requests | Too many requests hit the API |\n| 500, 502, 503, 504 - Server Errors | System Error |",
   "author":"Gabriel Ajenifuja",
   "main": "dist/index.cjs.js",

package/src/accounts.ts

@@ -2,8 +2,21 @@ import { getInstance } from './index';
 import { handleError } from './util';
 
 interface CreateAccountRequest {
-  customer_id: string;
-  account_type: string;
+  /** Must always be "static". */
+  account_type: "static";
+  
+  /** 
+   * Set to true when creating an account for a third-party customer (business use).
+   * Set to false when creating a sub-account for your own business (collections).
+   * Defaults to true if not provided.
+   */
+  third_party?: boolean;
+  
+  /** Required if third_party is true. The customer to associate the account with. */
+  customer_id?: string;
+  
+  /** Required if third_party is false. The sub-account name (e.g."SUBACCOUNT" -> BUSINESS NAME - SUBACCOUNT). */
+  account_name?: string;
 }
 
 export async function createAccount(accountData: CreateAccountRequest) {

package/tests/accounts.test.ts

@@ -0,0 +1,196 @@
+import { createAccount, fetchAccount, fetchAccounts } from '../src/accounts';
+import { beforeEach, describe, expect, it, jest } from '@jest/globals';
+import axios from 'axios';
+
+// Mock the getInstance function instead of axios directly
+jest.mock('../src/index', () => ({
+  getInstance: () => axios,
+}));
+
+// Now mock axios
+jest.mock('axios');
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+
+describe('Account API', () => {
+  beforeEach(() => {
+    // Clear all mocks before each test
+    jest.clearAllMocks();
+  });
+
+  describe('createAccount', () => {
+    it('should create an account for a third-party customer', async () => {
+      const accountData = {
+        account_type: "static" as const,
+        third_party: true,
+        customer_id: '1732ca47-42b2-4990-a65d-c369e934eed3'
+      };
+
+      const responseData = { 
+        status: 'success',
+        data: { 
+          account_number: '1234567890', 
+          account_name: 'John Doe',
+          ...accountData 
+        } 
+      };
+      
+      mockedAxios.post.mockResolvedValueOnce({ data: responseData });
+
+      const result = await createAccount(accountData);
+      expect(result).toEqual(responseData);
+      expect(mockedAxios.post).toHaveBeenCalledWith('/v1/accounts', accountData);
+    });
+
+    it('should create a sub-account for the business itself', async () => {
+      const accountData = {
+        account_type: "static" as const,
+        third_party: false,
+        account_name: 'Collections'
+      };
+
+      const responseData = { 
+        status: 'success',
+        data: { 
+          account_number: '0987654321', 
+          business_name: 'BUSINESS NAME',
+          ...accountData 
+        } 
+      };
+      
+      mockedAxios.post.mockResolvedValueOnce({ data: responseData });
+
+      const result = await createAccount(accountData);
+      expect(result).toEqual(responseData);
+      expect(mockedAxios.post).toHaveBeenCalledWith('/v1/accounts', accountData);
+    });
+
+    it('should handle API errors during account creation', async () => {
+      const accountData = {
+        account_type: "static" as const,
+        third_party: true,
+        // Missing customer_id which is required when third_party is true
+      };
+
+      const errorResponse = {
+        response: {
+          data: {
+            status: 'failed',
+            message: 'bad request',
+            errors: [
+              { msg: 'customer_id is required when third_party is true', param: 'customer_id' }
+            ],
+          },
+        },
+      };
+
+      mockedAxios.post.mockRejectedValueOnce(errorResponse);
+
+      const result = await createAccount(accountData);
+      expect(result).toEqual(errorResponse.response.data);
+    });
+  });
+
+  describe('fetchAccount', () => {
+    it('should fetch a single account by account number', async () => {
+      const accountNumber = '1234567890';
+      const responseData = { 
+        status: 'success',
+        data: { 
+          account_number: accountNumber, 
+          account_name: 'John Doe',
+          account_type: 'static',
+          balance: '10000.00'
+        } 
+      };
+      
+      mockedAxios.get.mockResolvedValueOnce({ data: responseData });
+
+      const result = await fetchAccount(accountNumber);
+      expect(result).toEqual(responseData);
+      expect(mockedAxios.get).toHaveBeenCalledWith(`/v1/accounts/${accountNumber}`);
+    });
+
+    it('should handle API errors when fetching an account', async () => {
+      const accountNumber = 'invalid-account';
+      const errorResponse = {
+        response: {
+          data: {
+            status: 'failed',
+            message: 'Account not found',
+          },
+        },
+      };
+
+      mockedAxios.get.mockRejectedValueOnce(errorResponse);
+
+      const result = await fetchAccount(accountNumber);
+      expect(result).toEqual(errorResponse.response.data);
+    });
+  });
+
+  describe('fetchAccounts', () => {
+    it('should fetch all accounts with default pagination', async () => {
+      const responseData = { 
+        status: 'success',
+        data: { 
+          accounts: [
+            { account_number: '1234567890', account_name: 'John Doe', account_type: 'static' },
+            { account_number: '0987654321', account_name: 'Jane Smith', account_type: 'static' }
+          ],
+          pagination: {
+            total: 2,
+            page: 1,
+            limit: 10
+          }
+        } 
+      };
+      
+      mockedAxios.get.mockResolvedValueOnce({ data: responseData });
+
+      const result = await fetchAccounts();
+      expect(result).toEqual(responseData);
+      expect(mockedAxios.get).toHaveBeenCalledWith('/v1/accounts', { params: { page: 1, limit: 10 } });
+    });
+
+    it('should fetch accounts with custom pagination', async () => {
+      const page = 2;
+      const limit = 5;
+      const responseData = { 
+        status: 'success',
+        data: { 
+          accounts: [
+            { account_number: '1112223334', account_name: 'Alice Johnson', account_type: 'static' },
+            { account_number: '5556667778', account_name: 'Bob Miller', account_type: 'static' }
+          ],
+          pagination: {
+            total: 7,
+            page: page,
+            limit: limit
+          }
+        } 
+      };
+      
+      mockedAxios.get.mockResolvedValueOnce({ data: responseData });
+
+      const result = await fetchAccounts(page, limit);
+      expect(result).toEqual(responseData);
+      expect(mockedAxios.get).toHaveBeenCalledWith('/v1/accounts', { params: { page, limit } });
+    });
+
+    it('should handle API errors when fetching accounts', async () => {
+      const errorResponse = {
+        response: {
+          data: {
+            status: 'failed',
+            message: 'Unauthorized access',
+          },
+        },
+      };
+
+      mockedAxios.get.mockRejectedValueOnce(errorResponse);
+
+      const result = await fetchAccounts();
+      expect(result).toEqual(errorResponse.response.data);
+    });
+  });
+});