carbon-baas-sdk 1.0.0

package/dist/payouts.d.ts

@@ -0,0 +1,18 @@
+interface InitiatePayoutRequest {
+    amount: number;
+    source: {
+        account_number: string;
+    };
+    beneficiary: {
+        bank_code: string;
+        bank_name: string;
+        account_number: string;
+        account_name: string;
+    };
+    reference: string;
+    meta_data: object;
+    remark: string;
+}
+export declare function initiatePayout(payoutData: InitiatePayoutRequest): Promise<any>;
+export declare function fetchPayout(payoutId: string): Promise<any>;
+export {};

package/dist/transactions.d.ts

@@ -0,0 +1,2 @@
+export declare function verifyTransaction(accountNumber: string, reference: string): Promise<any>;
+export declare function fetchTransactions(accountNumber: string, page?: number, limit?: number): Promise<any>;

package/dist/util.d.ts

@@ -0,0 +1 @@
+export declare function handleError(error: any): any;

package/dist/webhook.d.ts

@@ -0,0 +1,8 @@
+interface UpdateWebhookRequest {
+    url: string;
+}
+export declare function fetchWebhook(): Promise<any>;
+export declare function updateWebhook(data: UpdateWebhookRequest): Promise<any>;
+export declare function fetchWebhookHistory(page?: number, limit?: number): Promise<any>;
+export declare function resendWebhookEvent(eventId: string): Promise<any>;
+export {};

package/example/index.js

@@ -0,0 +1,48 @@
+// Import the SDK
+const carbon = require('../dist/index.umd.js');
+const dotenv = require('dotenv');
+dotenv.config({ path: '../.env' });
+
+// Initialize the SDK
+carbon.initialize(process.env.CARBON_API_KEY, process.env.ENV);
+
+
+// Example function to create a customer
+async function exampleCreateCustomer() {
+  const customerData = {
+    first_name: 'John',
+    last_name: 'Doe',
+    email: 'john.doe@example.com',
+    phone: '+1234567890',
+    dob: '1990-01-01',
+    gender: 'male',
+    street: '123 Main St',
+    city: 'Ikeja',
+    state: 'Lagos State',
+    country: 'NG',
+    bvn: '1234567890',
+    nin: '12345678901', //optional
+  };
+
+  try {
+    const newCustomer = await carbon.createCustomer(customerData);
+    console.log('Customer created:', newCustomer);
+    return newCustomer;
+  } catch (error) {
+    console.error('Error creating customer:', error);
+  }
+}
+
+// Example function to fetch a customer
+async function exampleFetchCustomers() {
+  try {
+    const customers = await carbon.fetchCustomers();
+    console.log('Customers:', customers);
+  } catch (error) {
+    console.error('Error fetching customers:', error);
+  }
+}
+
+// Run the examples
+exampleFetchCustomers();
+

package/example/test-mcp.ts

@@ -0,0 +1,74 @@
+import { MCPClient } from '../src';
+import { MCPAgent } from '../src/agents/mcp-agent';
+import { MCPResponse } from '../src/core/mcp-types';
+import dotenv from 'dotenv';
+
+// Load environment variables
+dotenv.config();
+
+async function testMCP() {
+    try {
+        // Initialize MCP client
+        const mcpClient = new MCPClient({
+            apiKey: process.env.CARBON_API_KEY || '',
+            mode: 'sandbox',
+            defaultCurrency: 'NGN',
+            supportedCurrencies: [
+                { code: 'NGN', name: 'Nigerian Naira', symbol: '₦' },
+                { code: 'USD', name: 'US Dollar', symbol: '$' },
+            ],
+        });
+
+        // Initialize MCP agent
+        const mcpAgent = new MCPAgent(mcpClient);
+
+        // Test commands
+        const commands = [
+            'create customer called Tech Corp with email tech@example.com and phone 2348012345678',
+            'fetch customers',
+            'create account for Tech Corp',
+            'check balance for account 1234567890',
+            'fetch banks',
+            'check uptime for banks'
+        ];
+
+        console.log('Starting MCP tests...\n');
+
+        let context: MCPResponse | undefined;
+
+        for (const command of commands) {
+            console.log(`\nExecuting command: "${command}"`);
+            try {
+                // Pass context from previous interaction
+                const result = await mcpAgent.processCommand(command);
+                console.log('Result:', JSON.stringify({
+                    message: result.message,
+                    metadata: result.metadata,
+                    suggestedActions: result.suggestedActions || []
+                }, null, 2));
+                
+                // Store context for next interaction
+                context = result;
+
+                const suggestedActions = result.suggestedActions || [];
+                if (suggestedActions.length > 0) {
+                    console.log('Suggested next actions:', suggestedActions);
+                }
+                
+                const availableTools = result.availableTools || [];
+                if (availableTools.length > 0) {
+                    console.log('Available tools:', availableTools.map(t => t.name));
+                }
+            } catch (error) {
+                console.error(`Error processing command "${command}":`, error);
+            }
+            console.log('-'.repeat(80));
+        }
+
+    } catch (error) {
+        console.error('Test failed:', error);
+    }
+}
+
+// Run the test
+testMCP().catch(console.error); 

package/jest.config.js

@@ -0,0 +1,8 @@
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    testMatch: ['**/tests/**/*.test.ts'],
+    transform: {
+      '^.+\\.tsx?$': 'ts-jest',
+    },
+  };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "carbon-baas-sdk",
+  "version": "1.0.0",
+  "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 |",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.esm.js",
+  "browser": "dist/index.umd.js",
+  "scripts": {
+    "build": "rollup -c",
+    "test": "jest --coverage"
+  },
+  "keywords": [
+    "getcarbon",
+    "carbon business"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@types/node": "^22.13.10",
+    "axios": "^1.8.3",
+    "dotenv": "^16.4.7",
+    "typescript": "^5.8.2"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^28.0.3",
+    "@rollup/plugin-json": "^6.1.0",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@types/jest": "^29.5.14",
+    "jest": "^29.7.0",
+    "rollup": "^4.35.0",
+    "rollup-plugin-typescript2": "^0.36.0",
+    "ts-jest": "^29.2.6"
+  }
+}

package/rollup.config.mjs

@@ -0,0 +1,34 @@
+import commonjs from '@rollup/plugin-commonjs';
+import resolve from '@rollup/plugin-node-resolve';
+import typescript from 'rollup-plugin-typescript2';
+import json from '@rollup/plugin-json';
+
+export default {
+  input: 'src/index.ts',
+  output: [
+    {
+      file: 'dist/index.cjs.js',
+      format: 'cjs',
+      sourcemap: true,
+    },
+    {
+      file: 'dist/index.esm.js',
+      format: 'esm',
+      sourcemap: true,
+    },
+    {
+      file: 'dist/index.umd.js',
+      format: 'umd',
+      name: 'carbon-baas-sdk',
+      sourcemap: true,
+    },
+  ],
+  plugins: [
+    resolve(),
+    commonjs(),
+    json(),
+    typescript({
+      tsconfig: './tsconfig.json',
+    }),
+  ],
+};

package/src/accounts.ts

@@ -0,0 +1,26 @@
+import { getInstance } from './index';
+import { handleError } from './util';
+
+interface CreateAccountRequest {
+  customer_id: string;
+  account_type: string;
+}
+
+export async function createAccount(accountData: CreateAccountRequest) {
+  try {
+    const response = await getInstance().post('/v1/accounts', accountData);
+    return response.data;
+  } catch (error) {
+    return handleError(error);
+  }
+}
+
+export async function fetchAccount(accountNumber: string) {
+  try {
+    const response = await getInstance().get(`/v1/accounts/${accountNumber}`);
+    return response.data;
+  } catch (error) {
+    return handleError(error);
+  }
+}
+

package/src/banks.ts

@@ -0,0 +1,44 @@
+import { getInstance } from './index';
+import { handleError } from './util';
+
+interface ResolveAccountRequest {
+  account_number: string;
+  bank_code: string;
+}
+
+interface UptimeResponse {
+  status: string;
+  message: string;
+  data: Array<{
+    cbnBankCode: string;
+    nipBankCode: string;
+    uptime: number;
+  }>;
+}
+
+export async function fetchBanks() {
+  try {
+    const response = await getInstance().get('/v1/banks');
+    return response.data;
+  } catch (error) {
+    return handleError(error);
+  }
+}
+
+export async function resolveAccount(accountData: ResolveAccountRequest) {
+  try {
+    const response = await getInstance().post('/v1/banks/resolve', accountData);
+    return response.data;
+  } catch (error) {
+    return handleError(error);
+  }
+}
+
+export async function fetchBanksUptime() {
+  try {
+    const response = await getInstance().get('/v1/banks/uptime');
+    return response.data;
+  } catch (error) {
+    return handleError(error);
+  }
+}

package/src/customers.ts

@@ -0,0 +1,47 @@
+import axios from 'axios';
+import { getInstance } from './index';
+import { handleError } from './util';
+
+interface CreateCustomerRequest {
+  first_name: string;
+  last_name: string;
+  email: string;
+  phone: string;
+  dob: string;
+  gender: string;
+  street: string;
+  city: string;
+  state: string;
+  country: string;
+  bvn: string;
+  nin: string;
+}
+
+export async function createCustomer(customerData: CreateCustomerRequest) {
+  try {
+    const response = await getInstance().post('/v1/customers', customerData);
+    return response.data;
+  } catch (error) {
+    return handleError(error);
+  }
+}
+
+export async function fetchCustomer(customerId: string) {
+  try {
+    const response = await getInstance().get(`/v1/customers/${customerId}`);
+    return response.data;
+  } catch (error) {
+    return handleError(error);
+  }
+}
+
+export async function fetchCustomers(page: number = 1, limit: number = 10) {
+  try {
+    const response = await getInstance().get('/v1/customers', {
+      params: { page, limit },
+    });
+    return response.data;
+  } catch (error) {
+    return handleError(error);
+  }
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+import axios, { AxiosInstance } from 'axios';
+
+let instance: AxiosInstance;
+
+export function initialize(apiKey: string, mode: 'live' | 'sandbox') {
+  const baseUrl = mode === 'live' ? 'https://carbonapisecure.getcarbon.co/baas/api' : 'https://carbonapistagingsecure.getcarbon.co/baas/api';
+  const accessKey = 'baas-consumers';
+
+  if (!apiKey) {
+    throw new Error('API key must be provided');
+  }
+  
+  instance = axios.create({
+    baseURL: baseUrl,
+    headers: {
+      'x-carbon-key': apiKey,
+      'apiKey': accessKey,
+    },
+  });
+}
+
+export function getInstance(): AxiosInstance {
+  if (!instance) {
+    throw new Error('SDK not initialized. Call initialize() first.');
+  }
+  return instance;
+}
+
+export { createAccount, fetchAccount } from './accounts';
+export { verifyTransaction, fetchTransactions } from './transactions';
+export { createCustomer, fetchCustomer, fetchCustomers } from './customers';
+export { initiatePayout, fetchPayout } from './payouts';
+export { fetchBanks, resolveAccount } from './banks';
+export { fetchWebhook, fetchWebhookHistory, updateWebhook, resendWebhookEvent } from './webhook';

package/src/payouts.ts

@@ -0,0 +1,36 @@
+import { getInstance } from './index';
+import { handleError } from './util';
+
+interface InitiatePayoutRequest {
+  amount: number;
+  source: {
+    account_number: string;
+  };
+  beneficiary: {
+    bank_code: string;
+    bank_name: string;
+    account_number: string;
+    account_name: string;
+  };
+  reference: string;
+  meta_data: object;
+  remark: string;
+}
+
+export async function initiatePayout(payoutData: InitiatePayoutRequest) {
+  try {
+    const response = await getInstance().post('/v1/payouts', payoutData);
+    return response.data;
+  } catch (error) {
+    return handleError(error);
+  }
+}
+
+export async function fetchPayout(payoutId: string) {
+  try {
+    const response = await getInstance().get(`/v1/payouts/${payoutId}`);
+    return response.data;
+  } catch (error) {
+    return handleError(error);
+  }
+}

package/src/transactions.ts

@@ -0,0 +1,22 @@
+import { getInstance } from './index';
+import { handleError } from './util';
+
+export async function verifyTransaction(accountNumber: string, reference: string) {
+  try {
+    const response = await getInstance().get(`/v1/accounts/${accountNumber}/transactions/${reference}`);
+    return response.data;
+  } catch (error) {
+    return handleError(error);
+  }
+}
+
+export async function fetchTransactions(accountNumber: string, page: number = 1, limit: number = 10) {
+  try {
+    const response = await getInstance().get(`/v1/accounts/${accountNumber}/transactions`, {
+      params: { page, limit },
+    });
+    return response.data;
+  } catch (error) {
+    return handleError(error);
+  }
+}

package/src/util.ts

@@ -0,0 +1,9 @@
+export function handleError(error: any) {
+  if (error.response) {
+    console.error('Error response:', error.response.data);
+    return error.response.data;
+  } else {
+    console.error('Error message:', error.message);
+    throw error.message; 
+  }
+}

package/src/webhook.ts

@@ -0,0 +1,94 @@
+import { getInstance } from './index';
+import { handleError } from './util';
+
+interface UpdateWebhookRequest {
+  url: string;
+}
+
+interface WebhookResponse {
+  status: string;
+  message: string;
+  data: {
+    url: string;
+    signature_secret: string | null;
+    status: string;
+    mode: string;
+  };
+}
+
+interface WebhookHistoryResponse {
+  status: string;
+  message: string;
+  data: Array<{
+    event_id: string;
+    event_type: string;
+    data: {
+      event: string;
+      data: {
+        id: string;
+        amount: number;
+        currency: string;
+        transactionType: string;
+        entryDate: string;
+        uniqueRef: string;
+        account: {
+          id: string;
+          bankAccount: {
+            accountName: string;
+            accountNumber: string;
+            bank: {
+              code: string;
+              name: string;
+            };
+          };
+          static: boolean;
+          currency: string;
+          clientId: string;
+        };
+      };
+    };
+    created_at: string;
+    updated_at: string;
+  }>;
+  total: number;
+}
+
+export async function fetchWebhook() {
+  try {
+    const response = await getInstance().get('/v1/webhook');
+    return response.data;
+  } catch (error) {
+    return handleError(error);
+  }
+}
+
+export async function updateWebhook(data: UpdateWebhookRequest) {
+  try {
+    const response = await getInstance().put('/v1/webhook', data);
+    return response.data;
+  } catch (error) {
+    return handleError(error);
+  }
+}
+
+export async function fetchWebhookHistory(page: number = 0, limit: number = 10) {
+  try {
+    const response = await getInstance().get('/v1/webhook/history', {
+      params: { page, limit },
+    });
+    return response.data;
+  } catch (error) {
+    return handleError(error);
+  }
+}
+
+export async function resendWebhookEvent(eventId: string) {
+  try {
+    const response = await getInstance().post('/v1/webhook/resend-webhook-event', {
+      event_id: eventId,
+    });
+    return response.data;
+  } catch (error) {
+    return handleError(error);
+  }
+}

package/tests/customers.test.ts

@@ -0,0 +1,88 @@
+import { createCustomer, fetchCustomer } from '../src/customers';
+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('Customer API', () => {
+  beforeEach(() => {
+    // Clear all mocks before each test
+    jest.clearAllMocks();
+  });
+
+  it('should create a customer', async () => {
+    const customerData = {
+      first_name: 'John',
+      last_name: 'Doe',
+      email: 'john.doe@example.com',
+      phone: '+1234567890',
+      dob: '1990-01-01',
+      gender: 'male',
+      street: '123 Main St',
+      city: 'Anytown',
+      state: 'CA',
+      country: 'US',
+      bvn: '1234567890',
+      nin: '1234567890',
+    };
+
+    const responseData = { data: { id: '123', ...customerData } };
+    mockedAxios.post.mockResolvedValueOnce({ data: responseData });
+
+    const result = await createCustomer(customerData);
+    expect(result).toEqual(responseData);
+    expect(mockedAxios.post).toHaveBeenCalledWith('/v1/customers', customerData);
+  });
+
+  it('should fetch a customer', async () => {
+    const customerId = '123';
+    const responseData = { data: { id: customerId, first_name: 'John', last_name: 'Doe' } };
+    mockedAxios.get.mockResolvedValueOnce({ data: responseData });
+
+    const result = await fetchCustomer(customerId);
+    expect(result).toEqual(responseData);
+    expect(mockedAxios.get).toHaveBeenCalledWith(`/v1/customers/${customerId}`);
+  });
+
+  it('should handle API errors', async () => {
+    const customerData = {
+      first_name: 'John',
+      last_name: 'Doe',
+      email: 'john.doe@example.com',
+      phone: '+1234567890',
+      dob: '1990-01-01',
+      gender: 'male',
+      street: '123 Main St',
+      city: 'Anytown',
+      state: 'CA',
+      country: 'US',
+      bvn: '1234567890',
+      nin: '1234567890',
+    };
+
+    const errorResponse = {
+      response: {
+        data: {
+          status: 'failed',
+          message: 'bad request',
+          errors: [
+            { msg: 'BVN must be 11 numbers long', param: 'bvn' },
+            { msg: 'NIN must be 11 numbers long', param: 'nin' },
+          ],
+        },
+      },
+    };
+
+    mockedAxios.post.mockRejectedValueOnce(errorResponse);
+
+    const result = await createCustomer(customerData);
+    expect(result).toEqual(errorResponse.response.data);
+  });
+});