chamapay 1.0.0

package/README.md

@@ -0,0 +1,77 @@
+# ChamaPay JavaScript SDK
+
+Official Node.js SDK for the ChamaPay API.
+
+## Installation
+
+```bash
+npm install chamapay
+```
+
+## Usage
+
+```javascript
+import ChamaPay from 'chamapay';
+
+const api = new ChamaPay('cpk_live_your_api_key', 'your_api_secret');
+
+// List members
+const members = await api.members.list({ status: 'Active', page: 1, limit: 20 });
+
+// Create a contribution (idempotent)
+const contribution = await api.contributions.create(
+  { member_id: 'MFT001', amount: 5000 },
+  '550e8400-e29b-41d4-a716-446655440000'  // Idempotency-Key
+);
+
+// Get loan details
+const loan = await api.loans.get('LN001');
+```
+
+## API Reference
+
+Every resource method returns a Promise resolving to the API JSON response.
+
+| Resource    | Methods                                    |
+|-------------|--------------------------------------------|
+| members     | list, get, create, update, delete          |
+| contributions | list, get, create (with idempotency key) |
+| loans       | list, get, create                          |
+| fines       | list, create                               |
+| meetings    | list, create                               |
+| projects    | list, create                               |
+| accounts    | list, get                                  |
+| welfare     | list                                       |
+| dividends   | list                                       |
+| documents   | list                                       |
+| electionNotices | list                                   |
+| documentReminders | list                               |
+| audit       | list                                       |
+| liabilities | list, create                               |
+| reports     | get                                        |
+
+## Error Handling
+
+```javascript
+import { ChamaPayError, RateLimitError, ValidationError } from 'chamapay';
+
+try {
+  await api.members.create({ /* ... */ });
+} catch (err) {
+  if (err instanceof ValidationError) {
+    console.error('Validation failed:', err.details);
+  } else if (err instanceof RateLimitError) {
+    console.error(`Rate limited. Retry after ${err.retryAfter}s`);
+  } else if (err instanceof ChamaPayError) {
+    console.error(`API Error [${err.code}]:`, err.message);
+  }
+}
+```
+
+## Publishing
+
+```bash
+npm publish
+```
+
+Requires an npm account with access to the `chamapay` package.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "chamapay",
+  "version": "1.0.0",
+  "description": "Official Node.js SDK for ChamaPay API — Financial Infrastructure for African Savings Groups",
+  "main": "src/index.js",
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "test": "node --test src/**/*.test.js"
+  },
+  "keywords": [
+    "chamapay",
+    "sacco",
+    "savings",
+    "mpesa",
+    "africa",
+    "fintech"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/client.js

@@ -0,0 +1,84 @@
+import { ChamaPayError, AuthenticationError, RateLimitError, ValidationError, NotFoundError, ServerError } from './errors.js';
+
+const BASE_URL = 'https://api.chamapay.co.ke/v1';
+const DEFAULT_TIMEOUT = 30000;
+
+export class ChamaPayClient {
+  constructor(apiKey, apiSecret, opts = {}) {
+    if (!apiKey || !apiSecret) {
+      throw new ChamaPayError('API key and secret are required');
+    }
+    this.apiKey = apiKey;
+    this.apiSecret = apiSecret;
+    this.baseUrl = opts.baseUrl || BASE_URL;
+    this.timeout = opts.timeout || DEFAULT_TIMEOUT;
+  }
+
+  _token() {
+    return `${this.apiKey}:${this.apiSecret}`;
+  }
+
+  _headers() {
+    return {
+      'Authorization': `Bearer ${this._token()}`,
+      'Content-Type': 'application/json',
+      'User-Agent': 'chamapay-node/1.0.0',
+    };
+  }
+
+  async _request(method, path, opts = {}) {
+    const url = new URL(path, this.baseUrl);
+    if (opts.query) {
+      Object.entries(opts.query).forEach(([k, v]) => url.searchParams.set(k, v));
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const res = await fetch(url, {
+        method,
+        headers: { ...this._headers(), ...opts.headers },
+        body: opts.body ? JSON.stringify(opts.body) : undefined,
+        signal: controller.signal,
+      });
+
+      let data;
+      const ct = res.headers.get('content-type') || '';
+      if (ct.includes('application/json')) {
+        data = await res.json();
+      } else {
+        data = { error: { message: await res.text() } };
+      }
+
+      if (!res.ok) {
+        const err = data.error || data;
+        const msg = err.message || `Request failed with status ${res.status}`;
+        switch (res.status) {
+          case 401: throw new AuthenticationError(msg, err);
+          case 404: throw new NotFoundError(msg, err);
+          case 422: throw new ValidationError(msg, err);
+          case 429: throw new RateLimitError(msg, parseInt(res.headers.get('retry-after') || '30'), err);
+          case 500: throw new ServerError(msg, err);
+          default: throw new ChamaPayError(msg, res.status, err.code, err);
+        }
+      }
+
+      return data;
+    } catch (err) {
+      if (err.name === 'AbortError') {
+        throw new ChamaPayError('Request timed out', 0, 'timeout');
+      }
+      if (err instanceof ChamaPayError) throw err;
+      throw new ChamaPayError(err.message, 0, 'connection_error');
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  get(path, opts) { return this._request('GET', path, opts); }
+  post(path, opts) { return this._request('POST', path, opts); }
+  put(path, opts) { return this._request('PUT', path, opts); }
+  patch(path, opts) { return this._request('PATCH', path, opts); }
+  delete(path, opts) { return this._request('DELETE', path, opts); }
+}

package/src/errors.js

@@ -0,0 +1,45 @@
+export class ChamaPayError extends Error {
+  constructor(message, status, code, details) {
+    super(message);
+    this.name = 'ChamaPayError';
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export class AuthenticationError extends ChamaPayError {
+  constructor(message, details) {
+    super(message, 401, 'authentication_error', details);
+    this.name = 'AuthenticationError';
+  }
+}
+
+export class RateLimitError extends ChamaPayError {
+  constructor(message, retryAfter, details) {
+    super(message, 429, 'rate_limit_error', details);
+    this.name = 'RateLimitError';
+    this.retryAfter = retryAfter;
+  }
+}
+
+export class ValidationError extends ChamaPayError {
+  constructor(message, details) {
+    super(message, 422, 'validation_error', details);
+    this.name = 'ValidationError';
+  }
+}
+
+export class NotFoundError extends ChamaPayError {
+  constructor(message, details) {
+    super(message, 404, 'not_found', details);
+    this.name = 'NotFoundError';
+  }
+}
+
+export class ServerError extends ChamaPayError {
+  constructor(message, details) {
+    super(message, 500, 'server_error', details);
+    this.name = 'ServerError';
+  }
+}

package/src/index.js

@@ -0,0 +1,41 @@
+import { ChamaPayClient } from './client.js';
+import { MembersResource } from './resources/members.js';
+import { ContributionsResource } from './resources/contributions.js';
+import { LoansResource } from './resources/loans.js';
+import { FinesResource } from './resources/fines.js';
+import { MeetingsResource } from './resources/meetings.js';
+import { ProjectsResource } from './resources/projects.js';
+import { AccountsResource } from './resources/accounts.js';
+import { WelfareResource } from './resources/welfare.js';
+import { DividendsResource } from './resources/dividends.js';
+import { DocumentsResource } from './resources/documents.js';
+import { ElectionNoticesResource } from './resources/election_notices.js';
+import { DocumentRemindersResource } from './resources/document_reminders.js';
+import { AuditResource } from './resources/audit.js';
+import { LiabilitiesResource } from './resources/liabilities.js';
+import { ReportsResource } from './resources/reports.js';
+import { ChamaPayError, AuthenticationError, RateLimitError, ValidationError, NotFoundError, ServerError } from './errors.js';
+
+export class ChamaPay {
+  constructor(apiKey, apiSecret, opts) {
+    this._client = new ChamaPayClient(apiKey, apiSecret, opts);
+    this.members = new MembersResource(this._client);
+    this.contributions = new ContributionsResource(this._client);
+    this.loans = new LoansResource(this._client);
+    this.fines = new FinesResource(this._client);
+    this.meetings = new MeetingsResource(this._client);
+    this.projects = new ProjectsResource(this._client);
+    this.accounts = new AccountsResource(this._client);
+    this.welfare = new WelfareResource(this._client);
+    this.dividends = new DividendsResource(this._client);
+    this.documents = new DocumentsResource(this._client);
+    this.electionNotices = new ElectionNoticesResource(this._client);
+    this.documentReminders = new DocumentRemindersResource(this._client);
+    this.audit = new AuditResource(this._client);
+    this.liabilities = new LiabilitiesResource(this._client);
+    this.reports = new ReportsResource(this._client);
+  }
+}
+
+export { ChamaPayError, AuthenticationError, RateLimitError, ValidationError, NotFoundError, ServerError };
+export default ChamaPay;

package/src/resources/accounts.js

@@ -0,0 +1,5 @@
+export class AccountsResource {
+  constructor(client) { this.client = client; }
+  list(query) { return this.client.get('/accounts', { query }); }
+  get(id) { return this.client.get(`/accounts/${id}`); }
+}

package/src/resources/audit.js

@@ -0,0 +1,4 @@
+export class AuditResource {
+  constructor(client) { this.client = client; }
+  list(query) { return this.client.get('/audit', { query }); }
+}

package/src/resources/contributions.js

@@ -0,0 +1,9 @@
+export class ContributionsResource {
+  constructor(client) { this.client = client; }
+  list(query) { return this.client.get('/contributions', { query }); }
+  get(id) { return this.client.get(`/contributions/${id}`); }
+  create(body, idempotencyKey) {
+    const headers = idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {};
+    return this.client.post('/contributions', { body, headers });
+  }
+}

package/src/resources/dividends.js

@@ -0,0 +1,4 @@
+export class DividendsResource {
+  constructor(client) { this.client = client; }
+  list(query) { return this.client.get('/dividends', { query }); }
+}

package/src/resources/document_reminders.js

@@ -0,0 +1,4 @@
+export class DocumentRemindersResource {
+  constructor(client) { this.client = client; }
+  list(query) { return this.client.get('/document_reminders', { query }); }
+}

package/src/resources/documents.js

@@ -0,0 +1,4 @@
+export class DocumentsResource {
+  constructor(client) { this.client = client; }
+  list(query) { return this.client.get('/documents', { query }); }
+}

package/src/resources/election_notices.js

@@ -0,0 +1,4 @@
+export class ElectionNoticesResource {
+  constructor(client) { this.client = client; }
+  list(query) { return this.client.get('/election_notices', { query }); }
+}

package/src/resources/fines.js

@@ -0,0 +1,5 @@
+export class FinesResource {
+  constructor(client) { this.client = client; }
+  list(query) { return this.client.get('/fines', { query }); }
+  create(body) { return this.client.post('/fines', { body }); }
+}

package/src/resources/liabilities.js

@@ -0,0 +1,5 @@
+export class LiabilitiesResource {
+  constructor(client) { this.client = client; }
+  list(query) { return this.client.get('/liabilities', { query }); }
+  create(body) { return this.client.post('/liabilities', { body }); }
+}

package/src/resources/loans.js

@@ -0,0 +1,6 @@
+export class LoansResource {
+  constructor(client) { this.client = client; }
+  list(query) { return this.client.get('/loans', { query }); }
+  get(id) { return this.client.get(`/loans/${id}`); }
+  create(body) { return this.client.post('/loans', { body }); }
+}

package/src/resources/meetings.js

@@ -0,0 +1,5 @@
+export class MeetingsResource {
+  constructor(client) { this.client = client; }
+  list(query) { return this.client.get('/meetings', { query }); }
+  create(body) { return this.client.post('/meetings', { body }); }
+}

package/src/resources/members.js

@@ -0,0 +1,8 @@
+export class MembersResource {
+  constructor(client) { this.client = client; }
+  list(query) { return this.client.get('/members', { query }); }
+  get(id) { return this.client.get(`/members/${id}`); }
+  create(body) { return this.client.post('/members', { body }); }
+  update(id, body) { return this.client.put(`/members/${id}`, { body }); }
+  delete(id) { return this.client.delete(`/members/${id}`); }
+}

package/src/resources/projects.js

@@ -0,0 +1,5 @@
+export class ProjectsResource {
+  constructor(client) { this.client = client; }
+  list(query) { return this.client.get('/projects', { query }); }
+  create(body) { return this.client.post('/projects', { body }); }
+}

package/src/resources/reports.js

@@ -0,0 +1,4 @@
+export class ReportsResource {
+  constructor(client) { this.client = client; }
+  get(query) { return this.client.get('/reports', { query }); }
+}

package/src/resources/welfare.js

@@ -0,0 +1,4 @@
+export class WelfareResource {
+  constructor(client) { this.client = client; }
+  list(query) { return this.client.get('/welfare', { query }); }
+}