bysquare 2.0.0 → 2.0.1

package/README.md

@@ -15,40 +15,45 @@ other payment regulations.
 This library is un-opinionated. Image generation from qr-code string depends on
 your implementation. See [examples](examples).
 
-## How it works
-
-![diagram](./doc/uml/logic.svg)
-
 ## Install
 
-GitHub
+**npm registry**
 
 ```sh
-npm install xseman/bysquare#master
-npm install xseman/bysquare#develop
+npm install bysquare
 ```
 
-npm registry
+**GitHub**
 
 ```sh
-npm install bysquare
+# same as latest released npm registry version
+npm install xseman/bysquare#master
+
+# latest unreleased changes
+npm install xseman/bysquare#develop
 ```
 
-CLI
+**CLI**
 
 ```sh
 npm install --global bysquare
 ```
 
+## How it works
+
+### Encoding sequence
+
+![logic](./docs/uml/logic.svg)
+
 ## API
 
 ```ts
-generate(model: DataModel): Promise<string>
+generate(model: DataModel, options?: Options): Promise<string>
 parse(qr: string): Promise<DataModel>
 detect(qr: string): Boolean
 ```
 
-**generate(model: DataModel): Promise\<string>**
+**generate(model: DataModel, options?: Options): Promise\<string>**
 
 ```ts
 import { generate, DataModel, parse, PaymentOptions } from "bysquare"

package/lib/cjs/cli.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const node_readline_1 = require("node:readline");
+const generate_js_1 = require("./generate.js");
+if (process.stdin.isTTY) {
+    // bysquare "file"
+    handleInput(process.argv[2]);
+}
+else {
+    // echo "data" | bysquare
+    ;
+    (async () => {
+        const stdin = await handleStdin();
+        const qr = await fromJsonString(stdin).catch((e) => {
+            console.error(e);
+            process.exit(1);
+        });
+        console.log(qr);
+        process.exit(0);
+    })();
+}
+async function handleInput(input) {
+    if (input === undefined || input === "-h" || input === "--help") {
+        console.log(help());
+        process.exit(0);
+    }
+    if ((0, node_fs_1.existsSync)(process.argv[2])) {
+        const file = (0, node_fs_1.readFileSync)(process.argv[2], "utf8");
+        const qr = await fromJsonString(file).catch((e) => {
+            console.error(e);
+            process.exit(1);
+        });
+        console.log(qr);
+    }
+    else {
+        console.error(`File ${process.argv[2]} doesn't exists`);
+        process.exit(1);
+    }
+}
+async function fromJsonString(stdin) {
+    return new Promise((resolve, reject) => {
+        try {
+            const data = JSON.parse(stdin);
+            const qrString = (0, generate_js_1.generate)(data);
+            resolve(qrString);
+        }
+        catch (e) {
+            reject(e);
+        }
+    });
+}
+async function handleStdin() {
+    const readline = (0, node_readline_1.createInterface)({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: false
+    });
+    const lines = [];
+    return new Promise((resolve, reject) => {
+        readline
+            .on("line", (line) => {
+            lines.push(line);
+        })
+            .on("close", () => {
+            resolve(lines.join(""));
+        })
+            .on("SIGINT", /* CTRL+C */ reject);
+    });
+}
+function help() {
+    const exe = node_path_1.default.basename(process.argv[1]);
+    return [
+        "Simple Node.js library to generate 'PAY by square' QR string.",
+        "",
+        "Usage:",
+        `   ${exe} file`,
+        "",
+        "File:",
+        "   Valid json file",
+        "",
+        "Flags:",
+        "   -h, --help    display this help and exit",
+        "",
+        "If <file> is omitted, reads from stdin.",
+        "",
+        "Examples:",
+        "   bysquare ./example.json",
+        "",
+        "   echo ",
+        "       {",
+        '           "IBAN": "SK9611000000002918599669"',
+        '           "Amount": 100.0',
+        '           "CurrencyCode": "EUR"',
+        '           "VariableSymbol": "123"',
+        '           "Payments": 1',
+        '           "PaymentOptions": 1',
+        '           "BankAccounts": 1',
+        "       }'",
+        "   | bysquare"
+    ].join("\n");
+}

package/lib/cjs/generate.d.ts

@@ -0,0 +1,48 @@
+/// <reference types="node" />
+import { DataModel } from "./types.js";
+/**
+ * Returns a 2 byte buffer that represents the header of the bysquare
+ * specification
+ *
+ * ```
+ * | Attribute    | Number of bits | Possible values | Note
+ * --------------------------------------------------------------------------------------------
+ * | BySquareType | 4              | 0-15            | by square type
+ * | Version      | 4              | 0-15            | version of the by square type
+ * | DocumentType | 4              | 0-15            | document type within given by square type
+ * | Reserved     | 4              | 0-15            | bits reserved for future needs
+ * ```
+ *
+ * @see 3.5. by square header
+ */
+export declare function bysquareHeader(header?: [
+    bySquareType: number,
+    version: number,
+    documentType: number,
+    reserved: number
+]): Buffer;
+/**
+ * @see 3.10 Appending CRC32 checksum
+ */
+export declare function checksum(intermediate: string): Buffer;
+/**
+ * Transfer object to a tabbed string and append a CRC32 checksum
+ *
+ * @see 3.10. Appending CRC32 checksum
+ */
+export declare function prepareCompression(model: DataModel): Buffer;
+/**
+ * Transform data to ordered tab-separated intermediate representation ready for
+ * encoding
+ *
+ * @see Table 15 PAY by square sequence data model
+ */
+export declare function toIntermediate(data: DataModel): string;
+type Options = {
+    deburr: boolean;
+};
+/**
+ * Generate QR string ready for encoding into text QR code
+ */
+export declare function generate(model: DataModel, options?: Options): Promise<string>;
+export {};

package/lib/cjs/generate.js

@@ -0,0 +1,207 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generate = exports.toIntermediate = exports.prepareCompression = exports.checksum = exports.bysquareHeader = void 0;
+const lodash_deburr_1 = __importDefault(require("lodash.deburr"));
+const lzma_native_1 = __importDefault(require("lzma-native"));
+const rfc4648_1 = require("rfc4648");
+const types_js_1 = require("./types.js");
+// echo "Hello" | xz --format=raw --lzma1=lc=3,lp=0,pb=2,dict=32KiB --stdout | hexdump -C
+/**
+ * Returns a 2 byte buffer that represents the header of the bysquare
+ * specification
+ *
+ * ```
+ * | Attribute    | Number of bits | Possible values | Note
+ * --------------------------------------------------------------------------------------------
+ * | BySquareType | 4              | 0-15            | by square type
+ * | Version      | 4              | 0-15            | version of the by square type
+ * | DocumentType | 4              | 0-15            | document type within given by square type
+ * | Reserved     | 4              | 0-15            | bits reserved for future needs
+ * ```
+ *
+ * @see 3.5. by square header
+ */
+function bysquareHeader(header = [
+    0, 0,
+    0, 0
+]) {
+    const isValid = header.every((nibble) => 0 <= nibble && nibble <= 15);
+    if (!isValid) {
+        throw new Error(`Invalid header byte value, valid range <0,15>`);
+    }
+    const [bySquareType, version, documentType, reserved] = header;
+    // Combine 4-nibbles to 2-bytes
+    const mergedNibbles = Buffer.from([
+        (bySquareType << 4) | (version << 0),
+        (documentType << 4) | (reserved << 0),
+    ]);
+    return mergedNibbles;
+}
+exports.bysquareHeader = bysquareHeader;
+/**
+ * Allocates a new buffer of a 2 bytes that represents LZMA header which
+ * contains 16-bit unsigned integer (word, little-endian), which is the size of
+ * the decompressed data. Therefore the maximum size of compressed data is
+ * limited to 65535
+ *
+ * @see 3.11. LZMA Compression
+ */
+function lzmaHeader(decompressedData) {
+    const bytesCount = decompressedData.length;
+    if (bytesCount >= 2 ** 16) {
+        throw new Error("The maximum compressed data size has been reached");
+    }
+    const dataSize = Buffer.alloc(2);
+    dataSize.writeInt16LE(bytesCount);
+    return dataSize;
+}
+/**
+ * @see 3.10 Appending CRC32 checksum
+ */
+function checksum(intermediate) {
+    // @ts-ignore: Wrong return type
+    const data = lzma_native_1.default.crc32(intermediate);
+    const crc32 = Buffer.alloc(4);
+    crc32.writeUInt32LE(data);
+    return crc32;
+}
+exports.checksum = checksum;
+/**
+ * Transfer object to a tabbed string and append a CRC32 checksum
+ *
+ * @see 3.10. Appending CRC32 checksum
+ */
+function prepareCompression(model) {
+    const intermediate = toIntermediate(model);
+    return Buffer.concat([
+        checksum(intermediate),
+        Buffer.from(intermediate, "utf-8")
+    ]);
+}
+exports.prepareCompression = prepareCompression;
+/**
+ * Transform data to ordered tab-separated intermediate representation ready for
+ * encoding
+ *
+ * @see Table 15 PAY by square sequence data model
+ */
+function toIntermediate(data) {
+    const intermediate = new Array();
+    intermediate.push(data.invoiceId?.toString());
+    intermediate.push(data.payments.length.toString());
+    for (const p of data.payments) {
+        intermediate.push(p.type.toString());
+        intermediate.push(p.amount?.toString());
+        intermediate.push(p.currencyCode);
+        intermediate.push(p.paymentDueDate);
+        intermediate.push(p.variableSymbol);
+        intermediate.push(p.constantSymbol);
+        intermediate.push(p.specificSymbol);
+        intermediate.push(p.originatorRefInfo);
+        intermediate.push(p.paymentNote);
+        intermediate.push(p.bankAccounts.length.toString());
+        for (const ba of p.bankAccounts) {
+            intermediate.push(ba.iban);
+            intermediate.push(ba.bic);
+        }
+        if (p.type === types_js_1.PaymentOptions.StandingOrder) {
+            intermediate.push('1');
+            intermediate.push(p.day?.toString());
+            intermediate.push(p.month?.toString());
+            intermediate.push(p.periodicity);
+            intermediate.push(p.lastDate);
+        }
+        else {
+            intermediate.push('0');
+        }
+        if (p.type === types_js_1.PaymentOptions.DirectDebit) {
+            intermediate.push('1');
+            intermediate.push(p.directDebitScheme?.toString());
+            intermediate.push(p.directDebitType?.toString());
+            intermediate.push(p.variableSymbol?.toString());
+            intermediate.push(p.specificSymbol?.toString());
+            intermediate.push(p.originatorRefInfo?.toString());
+            intermediate.push(p.mandateId?.toString());
+            intermediate.push(p.creditorId?.toString());
+            intermediate.push(p.contractId?.toString());
+            intermediate.push(p.maxAmount?.toString());
+            intermediate.push(p.validTillDate?.toString());
+        }
+        else {
+            intermediate.push('0');
+        }
+    }
+    for (const p of data.payments) {
+        intermediate.push(p.beneficiary?.name);
+        intermediate.push(p.beneficiary?.street);
+        intermediate.push(p.beneficiary?.city);
+    }
+    return intermediate.join('\t');
+}
+exports.toIntermediate = toIntermediate;
+/**
+ * Transfer diacritics to basic latin letters
+ */
+function removeDiacritics(model) {
+    for (const payment of model.payments) {
+        if (payment.paymentNote) {
+            payment.paymentNote = (0, lodash_deburr_1.default)(payment.paymentNote);
+        }
+        if (payment.beneficiary?.name) {
+            payment.beneficiary.name = (0, lodash_deburr_1.default)(payment.beneficiary.name);
+        }
+        if (payment.beneficiary?.city) {
+            payment.beneficiary.city = (0, lodash_deburr_1.default)(payment.beneficiary.city);
+        }
+        if (payment.beneficiary?.street) {
+            payment.beneficiary.street = (0, lodash_deburr_1.default)(payment.beneficiary.street);
+        }
+    }
+}
+/**
+ * Generate QR string ready for encoding into text QR code
+ */
+function generate(model, options = { deburr: true }) {
+    if (options.deburr) {
+        removeDiacritics(model);
+    }
+    const data = prepareCompression(model);
+    const compressedData = [];
+    return new Promise((resolve, reject) => {
+        const encoder = lzma_native_1.default.createStream("rawEncoder", {
+            synchronous: true,
+            // @ts-ignore: Missing filter types
+            filters: [
+                {
+                    // @ts-ignore: Missing filter types
+                    id: lzma_native_1.default.FILTER_LZMA1,
+                    lc: 3,
+                    lp: 0,
+                    pb: 2,
+                    dict_size: 2 ** 17, // 128 kilobytes
+                },
+            ],
+        });
+        encoder
+            .on("end", () => {
+            const output = Buffer.concat([
+                bysquareHeader(),
+                lzmaHeader(data),
+                ...compressedData
+            ]);
+            resolve(rfc4648_1.base32hex.stringify(output, { pad: false }));
+        })
+            .on("data", (chunk) => {
+            compressedData.push(chunk);
+        })
+            .on("error", reject)
+            .write(data, (error) => {
+            error && reject(error);
+            encoder.end();
+        });
+    });
+}
+exports.generate = generate;

package/lib/cjs/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parse = exports.detect = exports.generate = void 0;
+var generate_js_1 = require("./generate.js");
+Object.defineProperty(exports, "generate", { enumerable: true, get: function () { return generate_js_1.generate; } });
+var parse_js_1 = require("./parse.js");
+Object.defineProperty(exports, "detect", { enumerable: true, get: function () { return parse_js_1.detect; } });
+Object.defineProperty(exports, "parse", { enumerable: true, get: function () { return parse_js_1.parse; } });
+__exportStar(require("./types.js"), exports);

package/lib/cjs/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "bysquare",
+  "description": "It's a national standard for payment QR codes adopted by Slovak Banking Association (SBA)",
+  "version": "2.0.1",
+  "license": "Apache-2.0",
+  "type": "commonjs",
+  "funding": "https://github.com/sponsors/xseman",
+  "homepage": "https://github.com/xseman/bysquare#readme",
+  "author": {
+    "name": "Filip Seman",
+    "email": "filip.seman@protonmail.com"
+  },
+  "scripts": {
+    "prebuild": "rm -rf ./lib || :",
+    "build": "tsc --project ./tsconfig.json && tsc --project ./tsconfig.cjs.json",
+    "postbuild": "bash -c 'chmod +x ./lib/{cjs,mjs}/cli.js' && cp package.json ./lib/mjs/ && jq '.type=\"commonjs\"' package.json > lib/cjs/package.json",
+    "test": "xv --loader=tsx ./src",
+    "test:watch": "find ./src/*.ts | entr xv --loader=tsx ./src",
+    "cli:local": "npm run build && npm link bysquare",
+    "version": "git flow release start v$npm_package_version",
+    "prepare": "",
+    "prepublishOnly": "npm run build",
+    "preversion": "git checkout develop",
+    "postversion": ""
+  },
+  "dependencies": {
+    "lodash.deburr": "~4.1.0",
+    "lzma-native": "7.0.1",
+    "rfc4648": "1.5.2"
+  },
+  "devDependencies": {
+    "@types/lodash.deburr": "~4.1.0",
+    "@types/lzma-native": "^4.0.1",
+    "@types/node": "~18.11.0",
+    "tsx": "~3.12.0",
+    "typescript": "~4.9.0",
+    "xv": "~2.1.0"
+  },
+  "bin": "lib/mjs/cli.js",
+  "types": "lib/mjs/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./lib/cjs/index.js",
+      "import": "./lib/mjs/index.js"
+    }
+  },
+  "files": [
+    "lib",
+    "!lib/*.test.*"
+  ],
+  "engines": {
+    "node": ">=16.0",
+    "npm": ">=7.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xseman/bysquare.git"
+  },
+  "keywords": [
+    "pay by square",
+    "by square",
+    "paybysquare",
+    "bysquare",
+    "payments",
+    "qr-string",
+    "qr",
+    "cli"
+  ]
+}