Files
sdk-node/dist/index.d.ts
T
admin 322a1154b9 Docs + scrub: neutral example account number, CBE reference formats, webhooks, quota
- The example account number in the README and in the source docblock was a
  REAL account number. Replaced with an obviously fake one (1000123456789).
  The same scrub had already been applied to sdks/ in qbirr-saas; this repo
  had drifted from it.
- Document that CBE accepts the full receipt link, the "v2-" token and the bare
  token as the SAME payment. qbirr reduces them to one identity, so a receipt
  cannot be verified twice by presenting it differently. Case is ignored for
  that check.
- Document the webhook contract: `verification.created` fires for BOTH outcomes
  so always read data.verified; data.client_ref echoes the tag your own upload
  sent (null if you did not send one); a 4xx response is final and is NOT
  retried, while 5xx / timeouts are retried with exponential backoff.
- Document that only verified lookups count against the monthly quota.
- sdk-node: the committed dist/ comment blocks were updated to match src. The
  change is inside comments only — no executable code differs.
2026-10-06 01:05:06 +03:00

144 lines
5.4 KiB
TypeScript

/**
* @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: '1000123456789',
* });
* console.log(r.verified, r.payer);
*
* Works on Node 18+ (uses the built-in fetch). No dependencies.
*/
export type Provider = 'cbe' | 'telebirr' | 'abyssinia' | 'dashen' | 'mpesa' | 'awash' | 'ebirr' | 'zamzam';
export interface VerifyRequest {
provider: Provider;
/** Transaction reference (or, for Awash/eBirr, the SMS URL / URL token). */
ref: string;
/** Expected payment amount in ETB. */
amount: number;
/** Exact receiver name (case-insensitive, whitespace-normalised match). */
receiverName: string;
/** Required for CBE and Bank of Abyssinia. Ignored for other providers. */
receiverAccount?: string;
}
export interface VerifyResult {
/** True if the receipt is real, the amount matches, and the receiver matches. */
verified: boolean;
/** Payer name as extracted from the receipt. */
payer: string;
/** 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;
limit: number;
remaining: number;
plan: string;
/** ISO date — first instant of the current monthly window. */
period_start: string;
/** ISO date — first instant of the next monthly window. */
period_end: string;
}
export interface QbirrOptions {
/** Your API key from the qbirr dashboard. */
apiKey: string;
/** Override base URL. Defaults to https://verify.qbirr.com */
baseUrl?: string;
/** Per-request timeout (ms). Defaults to 30 000. */
timeoutMs?: number;
/** Optional fetch override (for tests). */
fetch?: typeof fetch;
}
/** Thrown for network failures, HTTP errors, or non-JSON responses. */
export declare class QbirrError extends Error {
readonly status?: number | undefined;
readonly body?: unknown | undefined;
constructor(message: string, status?: number | undefined, body?: unknown | undefined);
}
export declare class Qbirr {
private readonly apiKey;
private readonly baseUrl;
private readonly timeoutMs;
private readonly fetchFn;
constructor(opts: QbirrOptions);
/**
* 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.
*/
verify(req: VerifyRequest): Promise<VerifyResult>;
/**
* 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: '1000123456789',
* file: buf,
* filename: 'receipt.pdf',
* contentType: 'application/pdf',
* });
*/
verifyUpload(opts: {
provider: Provider;
amount: number;
receiverName: string;
receiverAccount?: string;
file: Buffer | Uint8Array | Blob;
filename?: string;
contentType?: string;
}): Promise<VerifyResult>;
/** Returns the current month's quota usage for this API key. */
usage(): Promise<UsageStatus>;
private requestForm;
private request;
}
export default Qbirr;