blaaiz-nodejs-sdk 1.1.1 → 1.2.0

package/README.md

@@ -94,6 +94,23 @@ const customers = await blaaiz.customers.list();
 console.log('Customers:', customers.data);
 ```
 
+You can also pass optional filters and opt-in pagination. Supported filters
+are `email`, `id_number`, `registration_number`, `verification_status`, and
+`type`. Set `paginate: true` to receive a paginated response that includes
+`links` and `meta` (with `current_page`, `total`, etc.) alongside `data`.
+
+```javascript
+const verified = await blaaiz.customers.list({
+  email: 'john@example.com',
+  verification_status: 'VERIFIED',
+  type: 'individual',
+  paginate: true
+});
+
+console.log('Page:', verified.data.meta.current_page);
+console.log('Customers:', verified.data.data);
+```
+
 #### Update Customer
 
 ```javascript
@@ -269,12 +286,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
@@ -674,6 +696,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');
 
@@ -681,7 +705,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
@@ -696,7 +720,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

@@ -35,7 +35,43 @@ export interface CustomerData {
 export interface Customer extends CustomerData {
   id: string;
   business_id: string;
-  verification_status: 'PENDING' | 'VERIFIED' | 'REJECTED';
+  verification_status: 'PENDING' | 'PROCESSING' | 'VERIFIED' | 'REJECTED';
+}
+
+export interface CustomerListFilters {
+  email?: string;
+  id_number?: string;
+  registration_number?: string;
+  verification_status?: 'PENDING' | 'PROCESSING' | 'VERIFIED' | 'REJECTED';
+  type?: 'individual' | 'business';
+  paginate?: boolean;
+  page?: number;
+  per_page?: number;
+  [key: string]: string | number | boolean | undefined;
+}
+
+export interface PaginationLinks {
+  first?: string | null;
+  last?: string | null;
+  prev?: string | null;
+  next?: string | null;
+}
+
+export interface PaginationMeta {
+  current_page: number;
+  from?: number | null;
+  last_page?: number;
+  path?: string;
+  per_page?: number;
+  to?: number | null;
+  total: number;
+}
+
+export interface PaginatedCustomers {
+  data: Customer[];
+  links: PaginationLinks;
+  meta: PaginationMeta;
+  message?: string;
 }
 
 export interface CustomerKYCData {
@@ -103,6 +139,7 @@ export interface PayoutData {
   wallet_address?: string;
   wallet_network?: string;
   wallet_token?: string;
+  note?: string;
 }
 
 export interface PayoutResponse {
@@ -244,7 +281,7 @@ export interface WebhookEvent {
 export declare class CustomerService {
   constructor(client: any);
   create(customerData: CustomerData): Promise<BlaaizResponse<{ data: Customer }>>;
-  list(): Promise<BlaaizResponse<Customer[]>>;
+  list(filters?: CustomerListFilters): Promise<BlaaizResponse<Customer[] | PaginatedCustomers>>;
   get(customerId: string): Promise<BlaaizResponse<Customer>>;
   update(customerId: string, updateData: Partial<CustomerData>): Promise<BlaaizResponse<Customer>>;
   addKYC(customerId: string, kycData: CustomerKYCData): Promise<BlaaizResponse<any>>;
@@ -311,8 +348,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blaaiz-nodejs-sdk",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Official Node.js SDK for Blaaiz RaaS (Remittance as a Service) API",
   "main": "index.js",
   "types": "index.d.ts",
@@ -40,10 +40,10 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/blaaiz/nodejs-sdk.git"
+    "url": "git+https://github.com/Blaaiz/blaaiz-nodejs-sdk.git"
   },
   "bugs": {
-    "url": "https://github.com/blaaiz/nodejs-sdk/issues"
+    "url": "https://github.com/Blaaiz/blaaiz-nodejs-sdk/issues"
   },
   "homepage": "https://docs.business.blaaiz.com",
   "engines": {

package/src/services/CustomerService.js

@@ -25,8 +25,15 @@ class CustomerService {
     return this.client.makeRequest('POST', '/api/external/customer', customerData)
   }
 
-  async list () {
-    return this.client.makeRequest('GET', '/api/external/customer')
+  async list (filters = {}) {
+    const params = new URLSearchParams()
+    for (const [key, value] of Object.entries(filters || {})) {
+      if (value === undefined || value === null) continue
+      params.append(key, typeof value === 'boolean' ? String(value) : value)
+    }
+    const query = params.toString()
+    const endpoint = query ? `/api/external/customer?${query}` : '/api/external/customer'
+    return this.client.makeRequest('GET', endpoint)
   }
 
   async get (customerId) {

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