telebirr-receipt 0.0.1

package/LICENSE

@@ -0,0 +1,14 @@
+Copyright 2023 Yonathan Tesfaye
+Email: yt040448@gmail.com
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,107 @@
+# telebirr-receipt
+
+### What is telebirr-receipt
+
+`telebirr-receipt` Is a small nodejs package to parse and verify
+telebirr transaction receipt. Any telebirr transaction
+receipt can be found through the url
+`https://transactioninfo.ethiotelecom.et/receipt/{receipt_no}`
+by replacing `{receipt_no}` with receipt number or id which is sent from telebirr
+transaction SMS or the full receipt url is also sent via SMS.
+
+### How to install
+
+``
+npm install telebirr-receipt
+``
+
+### Basic usage
+
+#### Loading receipt from url
+
+```javascript
+const {receipt, utils: {loadReceipt, parseFromHTML}} = require('telebirr-receipt')
+
+// use it with caution / security warning
+process.env['NODE_TLS_REJECT_UNAUTHORIZED'] = 0
+
+// TODO: replace `receiptNo`
+loadReceipt({receiptNo: 'ADQ...'}).then(htmlAsString => {
+    const {verify, verifyOnly, verifyAll, equals} = receipt(parseFromHTML(htmlAsString), {to: 'Someone'})
+    verify((parsedFields, preDefinedFields) => {
+        // do anything with receipt
+    })
+}).catch(reason => {
+    console.error(reason)
+}).finally(() => {
+    process.env['NODE_TLS_REJECT_UNAUTHORIZED'] = 1
+})
+```
+
+#### Using custom receipt parser with custom string source
+
+```javascript
+const {receipt} = require('telebirr-receipt');
+
+function parse() {
+    const source = 'payer_name=Abebe;amount=5000;to=Kebede'
+    const result = {};
+
+    source.split(';').forEach(pair => {
+        const field = pair.split('=');
+        result[field[0]] = field[1];
+    });
+
+    return result;
+}
+
+const {verifyAll, verify, equals} = receipt(parse(), {to: 'Kebede', amount: '5000'})
+
+// match expected receiver's name with the name found on receipt
+console.log(verify((parsedInfo, myInfo) => equals(parsedInfo?.to, myInfo?.to))) // match any field
+
+console.log(verifyAll(['payer_name'])) // match every field but `payer_name`
+```
+
+### Use case
+
+The main use case of this project is to overcome payment api unavailability and requirements in Ethiopia. Based on this
+project you can get paid and verify your payment transactions.
+
+1. Your customers may fill their personal or payment information
+2. Your customers pay you via telebirr
+3. You let your customers know how to verify their payment by entering their transaction number or link which is
+   received from 127 / telebirr SMS.
+4. So you can verify that who send the money to you.
+
+### IMPORTANT
+
+The telebirr receipt website may be modified or changed at anytime, so it is important to test HTML parser every time
+before letting users pay and before verifying.
+You could test the parser simply by hard coding a sample transaction information manually and matching it with parsed
+from url.
+
+### Known issues
+
+1. `loadReceipt` fails with error: `unable to verify the first certificate`, code: `UNABLE_TO_VERIFY_LEAF_SIGNATURE`.
+   Disabling certificate verification could fix the problem, but it is not recommended.
+   Let me know if there is good solution to this problem.
+2. `parseFromHTML` may return different receipt field values or even empty and omit field values because of
+   the variability of the receipt website based on transaction such as transferring to bank and direct telebirr
+   transferring have different receipt format and soon. Thus, you should take a look at the return data of the
+   function `parseFromHTML` for different transaction destinations.
+
+### DISCLAIMER
+
+The open-source code provided is offered "as is" without warranty of any kind, either express or implied, including, but
+not limited to, the implied warranties of merchantability and fitness for a particular purpose. The author of this code
+shall not be liable for any damages arising from the use of this code, including, but not limited to, direct, indirect,
+incidental, special, or consequential damages.
+
+Users of this open-source code are solely responsible for testing and verifying the code's suitability for their
+specific purposes. The author of this code makes no representations or warranties about the code's accuracy,
+reliability, completeness, or timeliness. The user assumes all risk associated with the use of this code and agrees to
+indemnify and hold harmless the author of this code from any and all claims, damages, or liabilities arising from the
+use of this code.
+
+By using this open-source code, the user acknowledges and agrees to these terms and conditions.

package/index.js

@@ -0,0 +1,152 @@
+/**
+ * Initialize receipt
+ * @param {Object} parsedFields Parsed receipt information
+ * @param {Object} preDefinedFields Expected receipt information, used for verification
+ * @return {Object}
+ */
+function receipt(parsedFields = {}, preDefinedFields = {}) {
+    /**
+     * Compare two strings or numbers
+     * @param {string|number} a
+     * @param {string|number} b
+     * @return {boolean} `true` if a and b are both string or number and equal otherwise `false`
+     */
+    function equals(a, b) {
+        // considering `undefined === undefined`
+        return (typeof a === 'string' && typeof b === 'string' || typeof a === 'number' && typeof b === 'number') && a === b
+    }
+
+    /**
+     * Verify any parsed field with its corresponding predefined field
+     * @param {function(Object, Object) : boolean} callback Callback function with two parameters `parsedFields` and `preDefinedFields` respectively
+     * @return {boolean} the return value from the callback function, should return `boolean`
+     */
+    function verify(callback) {
+        return callback(parsedFields, preDefinedFields)
+    }
+
+    /**
+     * Match or verify all parsed fields with their corresponding predefined fields
+     * `parsedFields` and `preDefinedFields` must have the same name
+     * @param {[string]} doNotCompare List of field names to ignore from checking
+     * @return {boolean} `true` if all fields match otherwise `false`, if `parsedFields` are empty returns `false`
+     */
+    function verifyAll(doNotCompare = []) {
+        if (Object.keys(parsedFields).length <= 0) {
+            return false
+        }
+
+        for (const key in parsedFields) {
+            if (Object.hasOwnProperty.call(parsedFields, key)) {
+                if (!doNotCompare.includes(key)) {
+                    if (!equals(parsedFields[key], preDefinedFields[key])) {
+                        return false
+                    }
+                }
+            }
+        }
+
+        return true
+    }
+
+    /**
+     * Match or verify specified list of fields with their corresponding predefined fields
+     * `parsedFields` and `preDefinedFields` must have the same name
+     * @param {[string]} fieldNames List of field names to check
+     * @return {boolean} `true` if all fields match otherwise `false`, if empty `fieldNames` passed returns `false`
+     */
+    function verifyOnly(fieldNames = []) {
+        if (fieldNames.length <= 0) {
+            return false
+        }
+
+        fieldNames.forEach(key => {
+            if (!equals(fieldNames[key], preDefinedFields[key])) {
+                return false
+            }
+        })
+
+        return true
+    }
+
+    return {equals, verify, verifyOnly, verifyAll}
+}
+
+/**
+ * Parse fields from HTML string
+ * @param {string} str HTML string
+ * @return {{payer_name:string?, payer_phone:string?, payer_acc_type:string?, credited_party_name:string?, credited_party_acc_no:string?, transaction_status:string?, bank_acc_no:string?, receiptNo:string?, date:string?, settled_amount:number?, discount_amount:number?, vat_amount:number?, total_amount:number?, amount_in_word:string?, payment_mode:string?, payment_reason:string?, payment_channel:string?}} `parsedFields` as an object with field names and values
+ */
+function parseFromHTML(str) {
+    const htmlparser = require('htmlparser2')
+    const document = htmlparser.parseDocument(str)
+    const td = htmlparser.DomUtils.getElementsByTagName('td', document)
+    const fields = {}
+
+    function getNextValue(index) {
+        if (index + 1 < td.length) {
+            return htmlparser.DomUtils.textContent(td[index + 1]).replace(/[\n\r\t]/ig, '').replace(/\s+/ig, ' ').trim();
+        }
+        return ''
+    }
+
+    const names = ['የከፋይስም/payername', 'የከፋይቴሌብርቁ./payertelebirrno.', 'የከፋይአካውንትአይነት/payeraccounttype', 'የገንዘብተቀባይስም/creditedpartyname', 'የገንዘብተቀባይቴሌብርቁ./creditedpartyaccountno', 'የክፍያውሁኔታ/transactionstatus', 'የባንክአካውንትቁጥር/bankaccountnumber', 'የክፍያቁጥር/receiptno.', 'የክፍያቀን/paymentdate', 'የተከፈለውመጠን/settledamount', 'ቅናሽ/discountamount', '15%ቫት/vat', 'ጠቅላላየተክፈለ/totalamountpaid', 'የገንዘቡልክበፊደል/totalamountinword', 'የክፍያዘዴ/paymentmode', 'የክፍያምክንያት/paymentreason', 'የክፍያመንገድ/paymentchannel']
+    const keys = ['payer_name', 'payer_phone', 'payer_acc_type', 'credited_party_name', 'credited_party_acc_no', 'transaction_status', 'bank_acc_no', 'receiptNo', 'date', 'settled_amount', 'discount_amount', 'vat_amount', 'total_amount', 'amount_in_word', 'payment_mode', 'payment_reason', 'payment_channel']
+
+    td.forEach((value, index) => {
+        let s = htmlparser.DomUtils.textContent(value).replace(/[\n\r\s\t]/ig, '').trim().toLowerCase();
+
+        const indexOf = names.indexOf(s)
+        if (indexOf >= 0) {
+            let nextValue = getNextValue(index + (indexOf > 6 && indexOf <= 9 ? 2 : 0));
+            let key = keys[indexOf];
+
+            if (key === 'bank_acc_no') {
+                fields['to'] = nextValue.replace(/^[0-9]+/g, '').trim()
+                fields[key] = nextValue.replace(/[A-Z]/ig, '').trim()
+            } else if (key.endsWith('amount')) {
+                fields[key] = parseFloat(nextValue.replace(/birr/ig, '').trim())
+            } else {
+                fields[key] = nextValue
+            }
+        }
+    })
+
+    return fields
+}
+
+/**
+ * Load receipt HTML string from receipt number or any url
+ * @param {string} [receiptNo] Receipt number received from telebirr SMS, high priority
+ * @param {string} [fullUrl] Or full receipt url, less prior
+ * @return {Promise<String>} HTML string
+ */
+function loadReceipt({receiptNo, fullUrl}) {
+    return new Promise((resolve, reject) => {
+        const url = receiptNo ? `https://transactioninfo.ethiotelecom.et/receipt/${receiptNo}` : fullUrl
+
+        const https = require('https');
+        const options = new URL(url)
+
+        let data = ''
+        const req = https.request(options, (res) => {
+            res.on('data', (chunk) => {
+                data += chunk
+            })
+
+            res.on('error', (error) => {
+                reject(error)
+            })
+
+            res.on('end', () => {
+                resolve(data)
+            })
+        })
+        req.on('error', (error) => {
+            reject(error)
+        })
+        req.end()
+    })
+}
+
+module.exports = {receipt, utils: {parseFromHTML, loadReceipt}}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "telebirr-receipt",
+  "description": "Telebirr transaction receipt parser and verifier",
+  "version": "0.0.1",
+  "author": "Yonathan Tesfaye <yt040448@gmail.com>",
+  "main": "index.js",
+  "scripts": {
+    "start": "node index.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "telebirr",
+    "payment",
+    "gateway",
+    "api",
+    "parse",
+    "transaction"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/TheRealYT/telebirr-receipt.git"
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "package.json",
+    "index.js"
+  ],
+  "dependencies": {
+    "htmlparser2": "^9.0.0"
+  }
+}