blaaiz-nodejs-sdk 1.1.2 → 1.3.0

package/README.md

@@ -29,6 +29,43 @@ const isConnected = await blaaiz.testConnection();
 console.log('API Connected:', isConnected);
 ```
 
+## Authentication
+
+The SDK supports two authentication methods.
+
+### OAuth 2.0 client credentials (recommended for new integrations)
+
+Provide a `client_id` and `client_secret` and the SDK handles the OAuth
+`client_credentials` flow for you: it fetches a bearer token from
+`/oauth/token`, caches it in memory, and refreshes it automatically shortly
+before it expires.
+
+```javascript
+const { Blaaiz } = require('blaaiz-nodejs-sdk');
+
+const blaaiz = new Blaaiz({
+  client_id: process.env.BLAAIZ_CLIENT_ID,
+  client_secret: process.env.BLAAIZ_CLIENT_SECRET,
+  // oauth_scope: 'wallet:read payout:create', // Optional: defaults to the full scope set
+  // baseURL: 'https://api.blaaiz.com',         // Optional: defaults to dev environment
+  // timeout: 30000                             // Optional: request timeout in milliseconds
+});
+```
+
+When `oauth_scope` is omitted the SDK requests the full set of supported scopes.
+
+### API key (legacy)
+
+API keys are still supported for existing integrations.
+
+```javascript
+const blaaiz = new Blaaiz('your-api-key-here');
+// or, using the options object:
+const blaaiz2 = new Blaaiz({ api_key: process.env.BLAAIZ_API_KEY });
+```
+
+When both OAuth credentials and an API key are configured, OAuth is used.
+
 ## Features
 
 - **Customer Management**: Create, update, and manage customers with KYC verification
@@ -286,12 +323,17 @@ const payout = await blaaiz.payouts.initiate({
   to_currency_id: "NGN",
   bank_id: "bank-id", // Required for NGN
   account_number: "0123456789",
-  phone_number: "+2348012345678" // Optional
+  phone_number: "+2348012345678", // Optional
+  note: "Acme Ltd" // Optional — appears in the transaction description; defaults to business name
 });
 
 console.log('Payout Status:', payout.data.transaction.status);
 ```
 
+#### Passing additional fields
+
+`payouts.initiate()` forwards the entire payload verbatim to the API, so any field documented in the [Blaaiz API reference](https://docs.business.blaaiz.com) can be included even if it isn't listed in this README. For example, `note` sets the transaction description (defaulting to the business name when omitted). This means the SDK stays compatible with new API fields without requiring an update here.
+
 #### Bank Transfer Payout (GBP)
 
 ```javascript
@@ -691,6 +733,8 @@ The Blaaiz API has a rate limit of 100 requests per minute. The SDK automaticall
 
 The SDK provides built-in webhook signature verification to ensure webhook authenticity. The signature is computed using HMAC-SHA256 with the format `timestamp.payload`.
 
+> **Important:** `payload` must be the **raw request body string** exactly as received. Do not pass a parsed object — parsing and re-serializing (e.g. `JSON.stringify`) changes the bytes and will break signature verification. Capture the raw body with `express.raw({ type: 'application/json' })` and pass `req.body.toString()` (see the Express example below).
+
 ```javascript
 const { Blaaiz } = require('blaaiz-nodejs-sdk');
 
@@ -698,7 +742,7 @@ const blaaiz = new Blaaiz('your-api-key');
 
 // Method 1: Verify signature manually
 const isValid = blaaiz.webhooks.verifySignature(
-  payload,        // Raw webhook payload (string or object)
+  payload,        // Raw request body string (do not pass a parsed object)
   signature,      // Signature from webhook headers (x-blaaiz-signature)
   timestamp,      // Timestamp from webhook headers (x-blaaiz-timestamp)
   webhookSecret   // Your webhook secret key
@@ -713,7 +757,7 @@ if (isValid) {
 // Method 2: Construct verified event (recommended)
 try {
   const event = blaaiz.webhooks.constructEvent(
-    payload,        // Raw webhook payload
+    payload,        // Raw request body string (do not pass a parsed object)
     signature,      // Signature from webhook headers
     timestamp,      // Timestamp from webhook headers
     webhookSecret   // Your webhook secret key

package/index.d.ts

@@ -4,7 +4,12 @@
 
 export interface BlaaizOptions {
   baseURL?: string;
+  base_url?: string;
   timeout?: number;
+  api_key?: string;
+  client_id?: string;
+  client_secret?: string;
+  oauth_scope?: string;
 }
 
 export interface BlaaizResponse<T = any> {
@@ -139,6 +144,7 @@ export interface PayoutData {
   wallet_address?: string;
   wallet_network?: string;
   wallet_token?: string;
+  note?: string;
 }
 
 export interface PayoutResponse {
@@ -347,8 +353,8 @@ export declare class WebhookService {
   get(): Promise<BlaaizResponse<WebhookData>>;
   update(webhookData: Partial<WebhookData>): Promise<BlaaizResponse<any>>;
   replay(replayData: WebhookReplayData): Promise<BlaaizResponse<any>>;
-  verifySignature(payload: string | object, signature: string, secret: string): boolean;
-  constructEvent(payload: string | object, signature: string, secret: string): WebhookEvent;
+  verifySignature(payload: string, signature: string, timestamp: string, secret: string): boolean;
+  constructEvent(payload: string, signature: string, timestamp: string, secret: string): WebhookEvent;
 }
 
 // Main SDK Class
@@ -366,7 +372,8 @@ export declare class Blaaiz {
   public webhooks: WebhookService;
 
   constructor(apiKey: string, options?: BlaaizOptions);
-  
+  constructor(options: BlaaizOptions);
+
   testConnection(): Promise<boolean>;
   
   createCompletePayout(payoutConfig: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blaaiz-nodejs-sdk",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "description": "Official Node.js SDK for Blaaiz RaaS (Remittance as a Service) API",
   "main": "index.js",
   "types": "index.d.ts",

package/src/client.js

@@ -1,26 +1,169 @@
 const https = require('https')
 const http = require('http')
-const { URL } = require('url')
+const { URL, URLSearchParams } = require('url')
 const BlaaizError = require('./error')
 
+const ALL_SCOPES = [
+  'wallet:read', 'currency:read', 'bank:read', 'customer:read', 'customer:write',
+  'beneficiary:read', 'virtual-account:read', 'virtual-account:create', 'virtual-account:close',
+  'collection:create', 'collection:crypto:create', 'collection:interac:accept',
+  'payout:create', 'swap:create', 'transaction:read', 'fees:read', 'file:upload',
+  'webhook:read', 'webhook:write', 'webhook:replay', 'rates:read'
+]
+
+function isPresent (value) {
+  return typeof value === 'string' && value !== '' && value !== '0'
+}
+
 class BlaaizAPIClient {
   constructor (apiKey, options = {}) {
-    if (!apiKey) {
-      throw new Error('API key is required')
+    if (apiKey && typeof apiKey === 'object') {
+      options = apiKey
+      apiKey = undefined
     }
 
-    this.apiKey = apiKey
-    this.baseURL = options.baseURL || 'https://api-dev.blaaiz.com'
+    this.clientId = options.client_id || ''
+    this.clientSecret = options.client_secret || ''
+    this.oauthScope = (options.oauth_scope === undefined || options.oauth_scope === null)
+      ? ALL_SCOPES.join(' ')
+      : options.oauth_scope
+    this.apiKey = apiKey || options.api_key || ''
+    this.baseURL = options.baseURL || options.base_url || 'https://api-dev.blaaiz.com'
     this.timeout = options.timeout || 30000
+
+    this.useOAuth = isPresent(this.clientId) && isPresent(this.clientSecret)
+
+    if (!this.useOAuth && !isPresent(this.apiKey)) {
+      throw new BlaaizError(
+        'Authentication required: provide either client_id and client_secret for OAuth, or an API key for legacy authentication'
+      )
+    }
+
+    this.accessToken = null
+    this.tokenExpiresAt = null
+
     this.defaultHeaders = {
-      'x-blaaiz-api-key': this.apiKey,
       Accept: 'application/json',
       'Content-Type': 'application/json',
       'User-Agent': 'Blaaiz-NodeJS-SDK/1.0.0'
     }
   }
 
+  async getOAuthToken () {
+    const now = Math.floor(Date.now() / 1000)
+    if (this.accessToken && this.tokenExpiresAt && now < this.tokenExpiresAt) {
+      return this.accessToken
+    }
+
+    const body = new URLSearchParams({
+      grant_type: 'client_credentials',
+      client_id: this.clientId,
+      client_secret: this.clientSecret,
+      scope: this.oauthScope
+    }).toString()
+
+    let response
+    try {
+      response = await this._requestToken(body)
+    } catch (error) {
+      throw new BlaaizError(
+        `OAuth token request failed: ${error.message}`,
+        null,
+        'OAUTH_ERROR'
+      )
+    }
+
+    if (response.status < 200 || response.status >= 300) {
+      let errorData = null
+      try {
+        errorData = JSON.parse(response.body)
+      } catch (error) {
+        errorData = null
+      }
+      throw new BlaaizError(
+        (errorData && (errorData.error_description || errorData.message)) ||
+          `OAuth token request failed: HTTP ${response.status}`,
+        response.status,
+        (errorData && errorData.error) || 'OAUTH_ERROR'
+      )
+    }
+
+    let parsed = null
+    try {
+      parsed = JSON.parse(response.body)
+    } catch (error) {
+      parsed = null
+    }
+
+    if (!parsed || !parsed.access_token) {
+      throw new BlaaizError(
+        'Failed to parse OAuth token response',
+        response.status,
+        'OAUTH_PARSE_ERROR'
+      )
+    }
+
+    let expiresIn = Number(parsed.expires_in)
+    if (!Number.isFinite(expiresIn)) expiresIn = 900
+    this.accessToken = parsed.access_token
+    this.tokenExpiresAt = Math.floor(Date.now() / 1000) + expiresIn - 60
+
+    return this.accessToken
+  }
+
+  async getAuthHeaders () {
+    if (this.useOAuth) {
+      const token = await this.getOAuthToken()
+      return { Authorization: `Bearer ${token}` }
+    }
+    return { 'x-blaaiz-api-key': this.apiKey }
+  }
+
+  _requestToken (body) {
+    return new Promise((resolve, reject) => {
+      const url = new URL('/oauth/token', this.baseURL)
+      const options = {
+        hostname: url.hostname,
+        port: url.port || (url.protocol === 'https:' ? 443 : 80),
+        path: url.pathname + url.search,
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+          'Content-Length': Buffer.byteLength(body)
+        },
+        timeout: this.timeout
+      }
+
+      const client = url.protocol === 'https:' ? https : http
+      const req = client.request(options, (res) => {
+        let responseData = ''
+
+        res.on('data', (chunk) => {
+          responseData += chunk
+        })
+
+        res.on('end', () => {
+          resolve({ status: res.statusCode, body: responseData })
+        })
+      })
+
+      req.on('error', (error) => {
+        reject(error)
+      })
+
+      req.on('timeout', () => {
+        req.destroy()
+        reject(new Error('OAuth token request timeout'))
+      })
+
+      req.write(body)
+      req.end()
+    })
+  }
+
   async makeRequest (method, endpoint, data = null, headers = {}) {
+    const authHeaders = await this.getAuthHeaders()
+
     return new Promise((resolve, reject) => {
       const url = new URL(endpoint, this.baseURL)
       const options = {
@@ -28,7 +171,7 @@ class BlaaizAPIClient {
         port: url.port || (url.protocol === 'https:' ? 443 : 80),
         path: url.pathname + url.search,
         method: method.toUpperCase(),
-        headers: { ...this.defaultHeaders, ...headers },
+        headers: { ...this.defaultHeaders, ...authHeaders, ...headers },
         timeout: this.timeout
       }
 
@@ -93,4 +236,6 @@ class BlaaizAPIClient {
   }
 }
 
+BlaaizAPIClient.ALL_SCOPES = ALL_SCOPES
+
 module.exports = BlaaizAPIClient

package/src/services/WebhookService.js

@@ -54,13 +54,16 @@ class WebhookService {
       throw new Error('Webhook secret is required for signature verification')
     }
 
-    const crypto = require('crypto')
+    // The payload must be the raw request body string. Parsing and
+    // re-serializing an object changes the bytes and breaks verification.
+    if (typeof payload !== 'string') {
+      throw new Error('Webhook payload must be the raw request body string. Do not pass a parsed object — parsing and re-serializing changes the bytes and breaks signature verification. Use the raw body (e.g. express.raw({ type: "application/json" }) then req.body.toString()).')
+    }
 
-    // Convert payload to string if it's an object
-    const payloadString = typeof payload === 'string' ? payload : JSON.stringify(payload)
+    const crypto = require('crypto')
 
     // Create signed payload with timestamp
-    const signedPayload = `${timestamp}.${payloadString}`
+    const signedPayload = `${timestamp}.${payload}`
 
     // Create HMAC signature
     const expectedSignature = crypto