checkbirr 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,10 @@
+The MIT License (MIT)
+
+Copyright (c) 2011-2026 The Bootstrap Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:

package/README.md

@@ -1,3 +1,85 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# CheckBirr 💵
+
+Verify payment screenshots instantly ⚡
+
+---
+
+## Installation
+
+```bash
+npm install checkbirr
+```
+
+## Usage
+
+```ts
+import checkbirr from "checkbirr";
+
+async function main() {
+  try {
+    const output = await checkbirr({
+      src: "./screenshot.jpg",
+      amount: 5000,
+      receiverAccounts: [
+        {
+          bank: "CBE",
+          receiverName: "John Doe Smith",
+          receiverAccountNumber: "1000*****",
+        },
+      ],
+    });
+
+    console.log(output);
+  } catch (error) {
+    console.log(error);
+  }
+}
+
+main();
+```
+
+## Output
+
+```ts
+{
+    verified:true,
+    bank:"CBE",
+    senderName:"Rip Van Winkle",
+    senderAccountNumber:"1000*****",
+    receiverName:"John Doe Smith",
+    receiverAccountNumber:"1000*****",
+    date:"Nov 02, 2026, 4:36 PM",
+    referenceNumber:"FM43812X",
+    amount:5000,
+    checkBirrID:"asd8f87a0d9f8a0as89f8"
+}
+```
+
+## How it works
+
+CheckBirr scans the QrCode present on the screenshot and navigates to the official website of the bank to extract transaction details.
+After the details are extracted it simply compares the values provided by the developer with the ones retrieved from the website.
+Finally, deming the transaction as verified or not depending on the similarity of the two values.
+
+## Why use CheckBirr
+
+CheckBirr does **NOT** simply extract the transaction details from the image using OCR scanning, But rather
+it retrieves them directly from the official site of the bank using web scrapping.
+This makes it very reliable and impossible to trick with fake or edited screenshots.
+
+## Duplicate Receipts
+
+This library does **NOT** detect duplicate transactions nor does it keep a record of previous transactions.
+It is up to the developer to store a history of **checkBirrID**s (which are unique IDs given to each transaction by the library) and compare new receipts in order to detect duplicates.
+
+## Supported Banks
+
+![Commercial Bank of Ethiopia](/assets/cbe.jpg)
+
+## Disclaimer
+
+This is **NOT** an official library published by any of the banks supported.
+
+## License
+
+This project is licensed under the **MIT License**.

package/dist/banks/cbe.d.ts

@@ -0,0 +1,3 @@
+import Transaction from "../types/transaction.js";
+import type { Receipt } from "../utils/validator.js";
+export default function checkCBE(url: string, receipt: Receipt): Promise<Transaction>;

package/dist/banks/cbe.js

@@ -0,0 +1,43 @@
+import puppeteer from "puppeteer";
+import hash from "../utils/hasher.js";
+export default async function checkCBE(url, receipt) {
+    const browser = await puppeteer.launch({ headless: true });
+    const page = await browser.newPage();
+    await page.goto(url, { waitUntil: "networkidle2" });
+    await page.waitForSelector(".md\\:text-lg.text-sm.font-semibold.py-1.md\\:py-2.px-4.text-center.border-b.m-0", { visible: true, timeout: 10000 });
+    const selector = await page.$$eval(`.text-black.text-right.md\\:text-sm.md\\:col-span-1`, (elements) => elements.map((el) => el.textContent?.trim() ?? ""));
+    const bank = "CBE";
+    const senderName = selector[0];
+    const senderAccountNumber = selector[1];
+    const receiverName = selector[2];
+    const receiverAccountNumber = selector[3];
+    const date = selector[5];
+    const referenceNumber = selector[6];
+    const amount = parseFloat(selector[8]);
+    await browser.close();
+    const checkBirrID = hash(bank, referenceNumber);
+    let verified = false;
+    for (let i = 0; i < receipt.receiverAccounts.length; i++) {
+        if (receipt.receiverAccounts[i].bank === "CBE") {
+            if (receipt.amount === amount &&
+                receipt.receiverAccounts[i].receiverAccountNumber.slice(-4) ===
+                    receiverAccountNumber.slice(-4) &&
+                receipt.receiverAccounts[i].receiverName === receiverName) {
+                verified = true;
+            }
+        }
+    }
+    const transaction = {
+        verified,
+        bank,
+        senderName,
+        senderAccountNumber,
+        receiverName,
+        receiverAccountNumber,
+        date,
+        referenceNumber,
+        amount,
+        checkBirrID,
+    };
+    return transaction;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { type Receipt } from "./utils/validator.js";
+export default function checkbirr(receipt: Receipt): Promise<import("./types/transaction.js").default>;

package/dist/index.js

@@ -0,0 +1,25 @@
+import scan from "./utils/scan.js";
+import identifyBank from "./utils/identifyBank.js";
+import validator from "./utils/validator.js";
+import checkCBE from "./banks/cbe.js";
+export default async function checkbirr(receipt) {
+    const validationResult = validator(receipt);
+    if (!validationResult.success) {
+        const messages = validationResult.error.issues.map((issue) => {
+            const path = issue.path.join(".");
+            return path ? `"${path}": ${issue.message}` : issue.message;
+        });
+        throw new Error(`checkbirr: invalid receipt:\n${messages.join("\n")}`);
+    }
+    const validReceipt = validationResult.data;
+    const url = await scan(validReceipt.src);
+    const bank = identifyBank(url);
+    switch (bank) {
+        case "CBE": {
+            const output = await checkCBE(url, validReceipt);
+            return output;
+        }
+        default:
+            throw new Error(`Unsupported bank: ${bank}`);
+    }
+}

package/dist/types/receipt.d.ts

@@ -0,0 +1,9 @@
+export default interface Receipt {
+    imagePath: string;
+    receiverAccounts: {
+        bank: string;
+        receiverAccountNumber: string;
+        receiverName: string;
+    }[];
+    amount: number;
+}

package/dist/types/receipt.js

@@ -0,0 +1 @@
+export {};

package/dist/types/transaction.d.ts

@@ -0,0 +1,12 @@
+export default interface Transaction {
+    verified: boolean;
+    referenceNumber: string;
+    bank: string;
+    senderAccountNumber: string;
+    senderName: string;
+    receiverAccountNumber: string;
+    receiverName: string;
+    amount: number;
+    date: string;
+    checkBirrID: string;
+}

package/dist/types/transaction.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/banks.d.ts

@@ -0,0 +1,5 @@
+declare const banks: {
+    name: string;
+    url: string;
+}[];
+export default banks;

package/dist/utils/banks.js

@@ -0,0 +1,7 @@
+const banks = [
+    {
+        name: "CBE",
+        url: "mbreciept.cbe.com.et",
+    }
+];
+export default banks;

package/dist/utils/hasher.d.ts

@@ -0,0 +1 @@
+export default function hash(bank: string, referenceNumber: string): string;

package/dist/utils/hasher.js

@@ -0,0 +1,7 @@
+import { createHash } from "node:crypto";
+export default function hash(bank, referenceNumber) {
+    const checkBirrID = createHash("sha256")
+        .update(`${bank}:${referenceNumber}`)
+        .digest("hex");
+    return checkBirrID;
+}

package/dist/utils/identifyBank.d.ts

@@ -0,0 +1 @@
+export default function identifyBank(url: string): string;

package/dist/utils/identifyBank.js

@@ -0,0 +1,8 @@
+import banks from "./banks.js";
+export default function identifyBank(url) {
+    const baseURL = new URL(url).hostname;
+    const bank = banks.find(b => b.url === baseURL);
+    if (!bank)
+        throw new Error(`Unknown bank for URL: ${url}`);
+    return bank.name;
+}

package/dist/utils/scan.d.ts

@@ -0,0 +1 @@
+export default function scan(imagePath: string): Promise<string>;

package/dist/utils/scan.js

@@ -0,0 +1,20 @@
+import jsQR from "jsqr";
+import { Jimp } from "jimp";
+export default async function scan(imagePath) {
+    try {
+        const image = await Jimp.read(imagePath);
+        const { data, width, height } = image.bitmap;
+        const code = jsQR.default(new Uint8ClampedArray(data), width, height);
+        if (code) {
+            return code.data;
+        }
+        else {
+            console.log("No QR code found");
+            return `Error: QrCode Not Found`;
+        }
+    }
+    catch (error) {
+        console.log(error);
+        return `Error: ${error}`;
+    }
+}

package/dist/utils/validator.d.ts

@@ -0,0 +1,21 @@
+import * as z from "zod";
+declare const receiptSchema: z.ZodObject<{
+    src: z.ZodString;
+    receiverAccounts: z.ZodArray<z.ZodObject<{
+        bank: z.ZodString;
+        receiverName: z.ZodString;
+        receiverAccountNumber: z.ZodString;
+    }, z.core.$strip>>;
+    amount: z.ZodNumber;
+}, z.core.$strip>;
+export type Receipt = z.infer<typeof receiptSchema>;
+export default function validateReceipt(receipt: unknown): z.ZodSafeParseResult<{
+    src: string;
+    receiverAccounts: {
+        bank: string;
+        receiverName: string;
+        receiverAccountNumber: string;
+    }[];
+    amount: number;
+}>;
+export {};

package/dist/utils/validator.js

@@ -0,0 +1,15 @@
+import * as z from "zod";
+const receiptSchema = z.object({
+    src: z.string(),
+    receiverAccounts: z
+        .array(z.object({
+        bank: z.string(),
+        receiverName: z.string(),
+        receiverAccountNumber: z.string(),
+    }))
+        .min(1, "receiverAccounts must have at least one entry"),
+    amount: z.number(),
+});
+export default function validateReceipt(receipt) {
+    return receiptSchema.safeParse(receipt);
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "checkbirr",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Automatic payment verification for Ethiopian bank receipts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "birr",
+    "checkbirr",
+    "verification",
+    "payment",
+    "payment-verification",
+    "screenshot",
+    "cbe",
+    "Ethiopia"
+  ],
+  "author": "Amieldev",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Amieldev/checkbirr"
+  },
+  "dependencies": {
+    "jimp": "^1.6.1",
+    "jsqr": "^1.4.0",
+    "puppeteer": "^25.10.0",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2"
+  }
+}