Initial release: @qbirr/sdk v1.0.0

2026-07-17 16:42:18 +02:00
commit 137045b1a6
4 changed files with 345 additions and 0 deletions
@@ -0,0 +1,78 @@
+# @qbirr/sdk
+
+Verify Ethiopian bank transfer receipts in real time — CBE, Telebirr, Awash, Dashen, M-Pesa, Bank of Abyssinia, and eBirr.
+
+## Install
+
+```bash
+npm install @qbirr/sdk
+```
+
+Requires Node.js 18+ (uses built-in `fetch`). Zero dependencies.
+
+## Quick start
+
+```js
+import { Qbirr } from '@qbirr/sdk';
+
+const qb = new Qbirr({ apiKey: process.env.QBIRR_API_KEY });
+
+const r = await qb.verify({
+  provider: 'cbe',
+  ref: 'FT23001234ABC',
+  amount: 500,
+  receiverName: 'YOUR FULL NAME',
+  receiverAccount: '1000017692643',
+});
+
+if (r.verified) {
+  console.log(`✓ Paid by ${r.payer}, amount: ${r.amount}`);
+} else {
+  console.log(`✗ ${r.error}`);
+}
+```
+
+## API
+
+### `new Qbirr(options)`
+
+| Option | Required | Default | Description |
+|---|---|---|---|
+| `apiKey` | ✓ | — | Your key from the qbirr dashboard |
+| `baseUrl` |  | `https://verify.qbirr.com` | Override (e.g. for self-hosted) |
+| `timeoutMs` |  | `30000` | Per-request timeout |
+
+### `qb.verify(req)`
+
+| Field | Type | Required | Notes |
+|---|---|---|---|
+| `provider` | string | ✓ | `cbe` · `telebirr` · `abyssinia` · `dashen` · `mpesa` · `awash` · `ebirr` |
+| `ref` | string | ✓ | Transaction reference. For **Awash**, paste the SMS URL or its token. For **eBirr**, paste the URL or `"tenant/token"`. |
+| `amount` | number | ✓ | Expected payment amount in ETB |
+| `receiverName` | string | ✓ | Exact name on your receiving account |
+| `receiverAccount` | string | for CBE & Abyssinia | Your account number |
+
+Returns `{ verified, payer, amount, error }`.
+
+### `qb.usage()`
+
+Returns the current month's `{ used, limit, remaining, plan, period_start, period_end }`.
+
+## Errors
+
+`QbirrError` is thrown for network failures, HTTP 4xx/5xx, or non-JSON responses. **Verification failures** (wrong amount, wrong receiver, expired receipt) are NOT thrown — they're returned as `{ verified: false, error: '...' }`.
+
+```js
+import { Qbirr, QbirrError } from '@qbirr/sdk';
+try {
+  const r = await qb.verify({ ... });
+} catch (e) {
+  if (e instanceof QbirrError) {
+    console.error(`API error ${e.status}: ${e.message}`);
+  }
+}
+```
+
+## License
+
+MIT