Files
sdk-node/dist/index.js
T
admin a0dcd4fd23 feat: expose paid_amount, retryable, code, receiver_source, sandbox
The API returns five fields the SDKs were dropping, so a caller could not
act on any of them:

  retryable        TRUE means we could not reach the bank. In that case
                   verified=false is NOT a verdict on the payment -- it is
                   "not checked yet". Retry, or fall back to manual review.
                   Never reject an order on it. Check it BEFORE acting on
                   verified=false.
  code             Stable machine-readable reason; branch on this instead of
                   parsing the human-readable error string. Empty/null on
                   success. RECEIPT_NOT_FOUND, AMOUNT_MISMATCH,
                   RECEIVER_MISMATCH, RECEIPT_EXPIRED, RECEIPT_UNREADABLE,
                   REFERENCE_INVALID, RECEIVER_ACCOUNT_REQUIRED,
                   UNSUPPORTED_INPUT, VERIFICATION_FAILED,
                   DUPLICATE_REFERENCE, UPSTREAM_UNAVAILABLE (retryable).
  paid_amount      What the receipt ACTUALLY shows, so a short payment can be
                   compared to the expected figure rather than only described
                   in prose.
  receiver_source  Which receiver identity was actually checked: 'settings'
                   (your saved dashboard account -- strongest), 'request' (the
                   receiver_name/account you sent), or 'none' (NOTHING was
                   checked: verified=true with 'none' means the reference
                   exists and the amount matches, but says nothing about who
                   received the money).
  sandbox          True only on TEST-... responses.

Additive only. Defaults are filled in on the way out so a caller never sees a
missing value, including against an API build that predates these fields.
2026-10-01 00:44:02 +03:00

187 lines
6.6 KiB
JavaScript

/**
* @qbirr/sdk — Node.js client for the qbirr payment verification API.
*
* 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 NAME',
* receiverAccount: '1000017692643',
* });
* console.log(r.verified, r.payer);
*
* Works on Node 18+ (uses the built-in fetch). No dependencies.
*/
/**
* Fill in the additive fields so a consumer never sees `undefined` — including
* against an older API that predates them.
*/
function normalise(r) {
return {
verified: Boolean(r.verified),
payer: String(r.payer ?? ''),
error: String(r.error ?? ''),
amount: Number(r.amount ?? 0),
paid_amount: Number(r.paid_amount ?? 0),
retryable: Boolean(r.retryable),
code: r.code ?? null,
receiver_source: r.receiver_source ?? null,
...(r.sandbox ? { sandbox: true } : {}),
};
}
/** Thrown for network failures, HTTP errors, or non-JSON responses. */
export class QbirrError extends Error {
status;
body;
constructor(message, status, body) {
super(message);
this.status = status;
this.body = body;
this.name = 'QbirrError';
}
}
const DEFAULT_BASE_URL = 'https://verify.qbirr.com';
export class Qbirr {
apiKey;
baseUrl;
timeoutMs;
fetchFn;
constructor(opts) {
if (!opts.apiKey)
throw new QbirrError('apiKey is required');
this.apiKey = opts.apiKey;
this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
this.timeoutMs = opts.timeoutMs ?? 30_000;
this.fetchFn = opts.fetch ?? globalThis.fetch;
if (!this.fetchFn)
throw new QbirrError('fetch is not available — pass options.fetch on Node < 18');
}
/**
* Verify a single transaction. Returns `{ verified: false, error: '...' }`
* on a real verification failure (wrong amount, wrong receiver, expired
* receipt). Throws QbirrError for network/auth problems.
*/
async verify(req) {
const body = {
provider: req.provider,
ref: req.ref,
amount: req.amount,
receiver_name: req.receiverName,
};
if (req.receiverAccount)
body.receiver_account = req.receiverAccount;
return normalise(await this.request('POST', '/api/v1/verify', body));
}
/**
* Verify by uploading the receipt itself — PDF or an image (PNG/JPEG).
* Images with a QR code (most bank receipts have one) are decoded and
* routed through the URL-based flow automatically.
*
* const buf = await fs.readFile('receipt.pdf');
* await qb.verifyUpload({
* provider: 'cbe',
* amount: 999,
* receiverName: 'YOUR NAME',
* receiverAccount: '1000017692643',
* file: buf,
* filename: 'receipt.pdf',
* contentType: 'application/pdf',
* });
*/
async verifyUpload(opts) {
const form = new FormData();
form.append('provider', opts.provider);
form.append('amount', String(opts.amount));
form.append('receiver_name', opts.receiverName);
if (opts.receiverAccount)
form.append('receiver_account', opts.receiverAccount);
const blob = opts.file instanceof Blob
? opts.file
: new Blob([opts.file], { type: opts.contentType || 'application/octet-stream' });
form.append('file', blob, opts.filename || 'upload.pdf');
return normalise(await this.requestForm('POST', '/api/v1/verify/upload', form));
}
/** Returns the current month's quota usage for this API key. */
async usage() {
return this.request('GET', '/api/v1/usage');
}
async requestForm(method, path, form) {
const url = `${this.baseUrl}${path}`;
const ctrl = new AbortController();
const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
try {
const resp = await this.fetchFn(url, {
method,
headers: { 'X-API-Key': this.apiKey, 'User-Agent': '@qbirr/sdk-node/1.0.0' },
body: form,
signal: ctrl.signal,
});
const text = await resp.text();
let parsed;
try {
parsed = text ? JSON.parse(text) : {};
}
catch {
throw new QbirrError(`Non-JSON response from qbirr (HTTP ${resp.status})`, resp.status, text);
}
if (!resp.ok)
throw new QbirrError(parsed?.error || `HTTP ${resp.status}`, resp.status, parsed);
return parsed;
}
catch (e) {
if (e instanceof QbirrError)
throw e;
if (e?.name === 'AbortError')
throw new QbirrError(`Upload timed out after ${this.timeoutMs}ms`);
throw new QbirrError(`Network error: ${e.message}`);
}
finally {
clearTimeout(timer);
}
}
async request(method, path, body) {
const url = `${this.baseUrl}${path}`;
const ctrl = new AbortController();
const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
try {
const resp = await this.fetchFn(url, {
method,
headers: {
'X-API-Key': this.apiKey,
'Content-Type': 'application/json',
Accept: 'application/json',
'User-Agent': '@qbirr/sdk-node/1.0.0',
},
body: body ? JSON.stringify(body) : undefined,
signal: ctrl.signal,
});
let parsed;
const text = await resp.text();
try {
parsed = text ? JSON.parse(text) : {};
}
catch {
throw new QbirrError(`Non-JSON response from qbirr (HTTP ${resp.status})`, resp.status, text);
}
if (!resp.ok) {
const msg = parsed?.error || `HTTP ${resp.status}`;
throw new QbirrError(msg, resp.status, parsed);
}
return parsed;
}
catch (e) {
if (e instanceof QbirrError)
throw e;
if (e?.name === 'AbortError')
throw new QbirrError(`Request timed out after ${this.timeoutMs}ms`);
throw new QbirrError(`Network error: ${e.message}`);
}
finally {
clearTimeout(timer);
}
}
}
export default Qbirr;