telebirr-receipt 0.0.1 → 1.0.0

package/README.md

@@ -4,7 +4,7 @@
 
 `telebirr-receipt` Is a small nodejs package to parse and verify
 telebirr transaction receipt. Any telebirr transaction
-receipt can be found through the url
+receipt can be found through 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.
@@ -22,13 +22,13 @@ npm install telebirr-receipt
 ```javascript
 const {receipt, utils: {loadReceipt, parseFromHTML}} = require('telebirr-receipt')
 
-// use it with caution / security warning
+// for debugging only 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) => {
+// TODO: replace `receipt_no`
+loadReceipt({receipt_no: "ADQ..."}).then(htmlAsString => {
+    const {verify, verifyOnly, verifyAll, equals} = receipt(parseFromHTML(htmlAsString), {to: "Someone"})
+    verify((parsed_fields, pre_defined_fields) => {
         // do anything with receipt
     })
 }).catch(reason => {
@@ -41,7 +41,7 @@ loadReceipt({receiptNo: 'ADQ...'}).then(htmlAsString => {
 #### Using custom receipt parser with custom string source
 
 ```javascript
-const {receipt} = require('telebirr-receipt');
+const {receipt} = require("telebirr-receipt");
 
 function parse() {
     const source = 'payer_name=Abebe;amount=5000;to=Kebede'
@@ -58,50 +58,7 @@ function parse() {
 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(verify((parsed_info, my_info) => equals(parsed_info?.to, my_info?.to)))
 
 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

@@ -1,45 +1,45 @@
 /**
  * Initialize receipt
- * @param {Object} parsedFields Parsed receipt information
- * @param {Object} preDefinedFields Expected receipt information, used for verification
+ * @param {Object} parsed_fields Parsed receipt information
+ * @param {Object} pre_defined_fields Expected receipt information, used for verification
  * @return {Object}
  */
-function receipt(parsedFields = {}, preDefinedFields = {}) {
+function receipt(parsed_fields = {}, pre_defined_fields = {}) {
     /**
      * 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`
+     * @param {string} a
+     * @param {string} 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
+        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`
+     * @param {Function} callback Callback function with two parameters `parsed_fields` and `pre_defined_fields` respectively
+     * @return {Boolean} the return value from the callback function, should return `boolean`
      */
     function verify(callback) {
-        return callback(parsedFields, preDefinedFields)
+        return callback(parsed_fields, pre_defined_fields)
     }
 
     /**
      * Match or verify all parsed fields with their corresponding predefined fields
-     * `parsedFields` and `preDefinedFields` must have the same name
+     * `parsed_fields` and `pre_defined_fields` 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`
+     * @return {Boolean} `true` if all fields match otherwise `false`, if `parsed_fields` are empty returns `false`
      */
     function verifyAll(doNotCompare = []) {
-        if (Object.keys(parsedFields).length <= 0) {
+        if (Object.keys(parsed_fields).length <= 0) {
             return false
         }
 
-        for (const key in parsedFields) {
-            if (Object.hasOwnProperty.call(parsedFields, key)) {
+        for (const key in parsed_fields) {
+            if (Object.hasOwnProperty.call(parsed_fields, key)) {
                 if (!doNotCompare.includes(key)) {
-                    if (!equals(parsedFields[key], preDefinedFields[key])) {
+                    if (!equals(parsed_fields[key], pre_defined_fields[key])) {
                         return false
                     }
                 }
@@ -51,17 +51,17 @@ function receipt(parsedFields = {}, preDefinedFields = {}) {
 
     /**
      * 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`
+     * `parsed_fields` and `pre_defined_fields` must have the same name
+     * @param {[string]} field_names List of field names to check
+     * @return {Boolean} `true` if all fields match otherwise `false`, if empty `field_names` passed returns `false`
      */
-    function verifyOnly(fieldNames = []) {
-        if (fieldNames.length <= 0) {
+    function verifyOnly(field_names = []) {
+        if (field_names.length <= 0) {
             return false
         }
 
-        fieldNames.forEach(key => {
-            if (!equals(fieldNames[key], preDefinedFields[key])) {
+        field_names.forEach(key => {
+            if (!equals(field_names[key], pre_defined_fields[key])) {
                 return false
             }
         })
@@ -75,7 +75,7 @@ function receipt(parsedFields = {}, preDefinedFields = {}) {
 /**
  * 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
+ * @return {Object} `parsed_fields` as an object with field names `payer_name`, `payer_phone`, `payer_acc_type`, `credited_party_name`, `credited_party_acc_no`, `transaction_status`, `bank_acc_no`, `receipt_no`, `date`, `settled_amount`, `discount_amount`, `vat_amount`, `total_amount`, `amount_in_word`, `payment_mode`, `payment_reason`, `payment_channel`
  */
 function parseFromHTML(str) {
     const htmlparser = require('htmlparser2')
@@ -90,21 +90,21 @@ function parseFromHTML(str) {
         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']
+    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", "receipt_no", "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 nextValue = getNextValue(index + ((indexOf > 6 && indexOf <= 9) ? 2 : 0));
             let key = keys[indexOf];
 
-            if (key === 'bank_acc_no') {
+            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')) {
+            } else if (key.endsWith("amount")) {
                 fields[key] = parseFloat(nextValue.replace(/birr/ig, '').trim())
             } else {
                 fields[key] = nextValue
@@ -117,32 +117,32 @@ function parseFromHTML(str) {
 
 /**
  * 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
+ * @param {string?} receipt_no Receipt number received from telebirr SMS, high priority
+ * @param {string?} full_url Or full receipt url, less prior
  * @return {Promise<String>} HTML string
  */
-function loadReceipt({receiptNo, fullUrl}) {
+function loadReceipt({receipt_no, full_url}) {
     return new Promise((resolve, reject) => {
-        const url = receiptNo ? `https://transactioninfo.ethiotelecom.et/receipt/${receiptNo}` : fullUrl
+        const url = receipt_no ? `https://transactioninfo.ethiotelecom.et/receipt/${receipt_no}` : full_url
 
-        const https = require('https');
+        const https = require("https");
         const options = new URL(url)
 
-        let data = ''
+        let data = ""
         const req = https.request(options, (res) => {
-            res.on('data', (chunk) => {
+            res.on("data", (chunk) => {
                 data += chunk
             })
 
-            res.on('error', (error) => {
+            res.on("error", (error) => {
                 reject(error)
             })
 
-            res.on('end', () => {
+            res.on("end", () => {
                 resolve(data)
             })
         })
-        req.on('error', (error) => {
+        req.on("error", (error) => {
             reject(error)
         })
         req.end()

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "telebirr-receipt",
   "description": "Telebirr transaction receipt parser and verifier",
-  "version": "0.0.1",
-  "author": "Yonathan Tesfaye <yt040448@gmail.com>",
+  "version": "1.0.0",
   "main": "index.js",
   "scripts": {
     "start": "node index.js",
@@ -16,16 +15,19 @@
     "parse",
     "transaction"
   ],
-  "license": "Apache-2.0",
+  "author": {
+    "name": "Yonathan Tesfaye",
+    "email": "yt040448@gmail.com"
+  },
+  "license": "Apache",
   "repository": {
-    "type": "git",
-    "url": "git://github.com/TheRealYT/telebirr-receipt.git"
+    "url": "https://github.com/TheRealYT/telebirr-receipt"
   },
   "files": [
     "README.md",
-    "LICENSE",
+    "index.js",
     "package.json",
-    "index.js"
+    "package-lock.json"
   ],
   "dependencies": {
     "htmlparser2": "^9.0.0"

package/LICENSE

@@ -1,14 +0,0 @@
-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.