From a0dcd4fd23be54ebb44a00482d9d4d26429e7b32 Mon Sep 17 00:00:00 2001 From: admin Date: Thu, 1 Oct 2026 00:44:02 +0300 Subject: [PATCH] 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. --- dist/index.cjs | 33 +++++++++++++++-------- dist/index.d.ts | 40 ++++++++++++++++++++++++++-- dist/index.js | 22 +++++++++++++--- src/index.ts | 69 +++++++++++++++++++++++++++++++++++++++++++++---- 4 files changed, 143 insertions(+), 21 deletions(-) diff --git a/dist/index.cjs b/dist/index.cjs index e0a3a68..fd3fbb6 100644 --- a/dist/index.cjs +++ b/dist/index.cjs @@ -1,4 +1,3 @@ -"use strict"; /** * @qbirr/sdk — Node.js client for the qbirr payment verification API. * @@ -15,10 +14,25 @@ * * Works on Node 18+ (uses the built-in fetch). No dependencies. */ -Object.defineProperty(exports, "__esModule", { value: true }); -exports.Qbirr = exports.QbirrError = void 0; +/** + * 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. */ -class QbirrError extends Error { +export class QbirrError extends Error { status; body; constructor(message, status, body) { @@ -28,9 +42,8 @@ class QbirrError extends Error { this.name = 'QbirrError'; } } -exports.QbirrError = QbirrError; const DEFAULT_BASE_URL = 'https://verify.qbirr.com'; -class Qbirr { +export class Qbirr { apiKey; baseUrl; timeoutMs; @@ -59,8 +72,7 @@ class Qbirr { }; if (req.receiverAccount) body.receiver_account = req.receiverAccount; - const data = await this.request('POST', '/api/v1/verify', body); - return data; + return normalise(await this.request('POST', '/api/v1/verify', body)); } /** * Verify by uploading the receipt itself — PDF or an image (PNG/JPEG). @@ -89,7 +101,7 @@ class Qbirr { ? opts.file : new Blob([opts.file], { type: opts.contentType || 'application/octet-stream' }); form.append('file', blob, opts.filename || 'upload.pdf'); - return this.requestForm('POST', '/api/v1/verify/upload', form); + return normalise(await this.requestForm('POST', '/api/v1/verify/upload', form)); } /** Returns the current month's quota usage for this API key. */ async usage() { @@ -171,5 +183,4 @@ class Qbirr { } } } -exports.Qbirr = Qbirr; -exports.default = Qbirr; +export default Qbirr; diff --git a/dist/index.d.ts b/dist/index.d.ts index 6dca560..0443f95 100644 --- a/dist/index.d.ts +++ b/dist/index.d.ts @@ -31,10 +31,46 @@ export interface VerifyResult { verified: boolean; /** Payer name as extracted from the receipt. */ payer: string; - /** Amount that was actually paid (per the receipt). */ - amount: number; /** Human-readable failure reason, empty on success. */ error: string; + /** The amount you said should have been paid, echoed back. */ + amount: number; + /** + * The amount the receipt ACTUALLY shows, in ETB. `0` when unreadable. + * On a short payment compare it to `amount` to see what arrived — the + * human-readable `error` tells you the difference but not the figure. + */ + paid_amount: number; + /** + * TRUE means "we could not reach the bank", so `verified: false` is NOT a + * verdict on the payment — it is "not checked yet". + * + * If this is true, retry or fall back to manual review. Never reject an order + * on it. Check this BEFORE acting on `verified: false`. + */ + retryable: boolean; + /** + * Stable machine-readable reason. Branch on this instead of parsing `error`. + * + * `RECEIPT_NOT_FOUND` · `AMOUNT_MISMATCH` · `RECEIVER_MISMATCH` · + * `RECEIPT_EXPIRED` · `RECEIPT_UNREADABLE` · `REFERENCE_INVALID` · + * `RECEIVER_ACCOUNT_REQUIRED` · `UNSUPPORTED_INPUT` · `VERIFICATION_FAILED` · + * `DUPLICATE_REFERENCE` · `UPSTREAM_UNAVAILABLE` (the only retryable one). + * `null` on success. + */ + code: string | null; + /** + * Which receiver identity was actually checked. + * + * `'settings'` — your saved account in the dashboard (strongest). + * `'request'` — the receiver_name/receiver_account you sent. + * `'none'` — NOTHING was checked. `verified: true` with `'none'` means the + * reference exists and the amount matches, but says nothing + * about who received the money. + */ + receiver_source: 'settings' | 'request' | 'none' | null; + /** Only present on sandbox (`TEST-…`) responses. */ + sandbox?: boolean; } export interface UsageStatus { used: number; diff --git a/dist/index.js b/dist/index.js index 68d8182..fd3fbb6 100644 --- a/dist/index.js +++ b/dist/index.js @@ -14,6 +14,23 @@ * * 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; @@ -55,8 +72,7 @@ export class Qbirr { }; if (req.receiverAccount) body.receiver_account = req.receiverAccount; - const data = await this.request('POST', '/api/v1/verify', body); - return data; + return normalise(await this.request('POST', '/api/v1/verify', body)); } /** * Verify by uploading the receipt itself — PDF or an image (PNG/JPEG). @@ -85,7 +101,7 @@ export class Qbirr { ? opts.file : new Blob([opts.file], { type: opts.contentType || 'application/octet-stream' }); form.append('file', blob, opts.filename || 'upload.pdf'); - return this.requestForm('POST', '/api/v1/verify/upload', form); + return normalise(await this.requestForm('POST', '/api/v1/verify/upload', form)); } /** Returns the current month's quota usage for this API key. */ async usage() { diff --git a/src/index.ts b/src/index.ts index 31dab9b..3d09dba 100644 --- a/src/index.ts +++ b/src/index.ts @@ -42,10 +42,70 @@ export interface VerifyResult { verified: boolean; /** Payer name as extracted from the receipt. */ payer: string; - /** Amount that was actually paid (per the receipt). */ - amount: number; /** Human-readable failure reason, empty on success. */ error: string; + /** The amount you said should have been paid, echoed back. */ + amount: number; + + /* + * The fields below are named exactly as the API sends them (snake_case), + * because the SDK returns the response payload as-is. + */ + + /** + * The amount the receipt ACTUALLY shows, in ETB. `0` when unreadable. + * On a short payment compare it to `amount` to see what arrived — the + * human-readable `error` tells you the difference but not the figure. + */ + paid_amount: number; + /** + * TRUE means "we could not reach the bank", so `verified: false` is NOT a + * verdict on the payment — it is "not checked yet". + * + * If this is true, retry or fall back to manual review. Never reject an order + * on it. Check this BEFORE acting on `verified: false`. + */ + retryable: boolean; + /** + * Stable machine-readable reason. Branch on this instead of parsing `error`. + * + * `RECEIPT_NOT_FOUND` · `AMOUNT_MISMATCH` · `RECEIVER_MISMATCH` · + * `RECEIPT_EXPIRED` · `RECEIPT_UNREADABLE` · `REFERENCE_INVALID` · + * `RECEIVER_ACCOUNT_REQUIRED` · `UNSUPPORTED_INPUT` · `VERIFICATION_FAILED` · + * `DUPLICATE_REFERENCE` · `UPSTREAM_UNAVAILABLE` (the only retryable one). + * `null` on success. + */ + code: string | null; + /** + * Which receiver identity was actually checked. + * + * `'settings'` — your saved account in the dashboard (strongest). + * `'request'` — the receiver_name/receiver_account you sent. + * `'none'` — NOTHING was checked. `verified: true` with `'none'` means the + * reference exists and the amount matches, but says nothing + * about who received the money. + */ + receiver_source: 'settings' | 'request' | 'none' | null; + /** Only present on sandbox (`TEST-…`) responses. */ + sandbox?: boolean; +} + +/** + * Fill in the additive fields so a consumer never sees `undefined` — including + * against an older API that predates them. + */ +function normalise(r: Partial & { verified?: boolean }): VerifyResult { + 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 } : {}), + }; } export interface UsageStatus { @@ -113,8 +173,7 @@ export class Qbirr { }; if (req.receiverAccount) body.receiver_account = req.receiverAccount; - const data = await this.request('POST', '/api/v1/verify', body); - return data; + return normalise(await this.request('POST', '/api/v1/verify', body)); } /** @@ -152,7 +211,7 @@ export class Qbirr { : new Blob([opts.file as unknown as BlobPart], { type: opts.contentType || 'application/octet-stream' }); form.append('file', blob, opts.filename || 'upload.pdf'); - return this.requestForm('POST', '/api/v1/verify/upload', form); + return normalise(await this.requestForm('POST', '/api/v1/verify/upload', form)); } /** Returns the current month's quota usage for this API key. */