bysquare 2.0.0 → 2.1.0

package/README.md

@@ -15,45 +15,50 @@ 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](./doc/uml/logic.svg)
+
 ## API
 
 ```ts
-generate(model: DataModel): Promise<string>
-parse(qr: string): Promise<DataModel>
+generate(model: DataModel, options?: Options): string
+parse(qr: string): DataModel
 detect(qr: string): Boolean
 ```
 
-**generate(model: DataModel): Promise\<string>**
+**generate(model: DataModel, options?: Options): string**
 
 ```ts
 import { generate, DataModel, parse, PaymentOptions } from "bysquare"
 
-const model: DataModel = {
+const model {
 	invoiceId: "random-id",
 	payments: [
 		{
@@ -66,22 +71,18 @@ const model: DataModel = {
 			variableSymbol: "123",
 		}
 	]
-}
+} satisfies DataModel
 
-generate(model).then((qr: string) => {
-	// your logic...
-})
+const qr = generate(model)
 ```
 
-**parse(qr: string): Promise\<DataModel>**
+**parse(qr: string): DataModel**
 
 ```ts
-import { parse, DataModel } from "bysquare"
+import { parse } from "bysquare"
 
-const qr = "0004A00090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6C75G19O246KTT5G8LTLM67HOIATP4OOG8F8FDLJ6T26KFCB1690NEVPQVSG0"
-parse(qr).then((model: DataModel) => {
-	// your logic...
-});
+const qr = "0004A00090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6CB54HSI0KH9FCRASHNQBSKAQD2LJ4AU400UVKDNDPFRKLOBEVVVU0QJ000"
+const model = parse(qr)
 ```
 
 **detect(qr: string): Boolean**
@@ -89,7 +90,7 @@ parse(qr).then((model: DataModel) => {
 ```ts
 import { detect } from "bysquare"
 
-const qr = "0004A00090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6C75G19O246KTT5G8LTLM67HOIATP4OOG8F8FDLJ6T26KFCB1690NEVPQVSG0"
+const qr = "0004A00090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6CB54HSI0KH9FCRASHNQBSKAQD2LJ4AU400UVKDNDPFRKLOBEVVVU0QJ000"
 const isBysquare = detect(qr)
 ```
 
@@ -105,9 +106,7 @@ You can use json file with valid model to generate qr-string.
 # 		{
 # 			"type": 1,
 # 			"amount": 100.0,
-# 			"bankAccounts": [
-# 				{ "iban": "SK9611000000002918599669" }
-# 			],
+# 			"bankAccounts": [{ "iban": "SK9611000000002918599669" }],
 # 			"currencyCode": "EUR",
 # 			"variableSymbol": "123"
 # 		}
@@ -115,27 +114,26 @@ You can use json file with valid model to generate qr-string.
 # }
 
 $ npx bysquare ./example.json
-$ 0004A00090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6C75G19O246KTT5G8LTLM67HOIATP4OOG8F8FDLJ6T26KFCB1690NEVPQVSG0
+$ 0004A00090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6CB54HSI0KH9FCRASHNQBSKAQD2LJ4AU400UVKDNDPFRKLOBEVVVU0QJ000
 ```
 
 You can also use stdin.
 
 ```sh
-$ bysquare <<< '{
-	"invoiceId": "random-id",
-	"payments": [
-		{
-			"type": 1,
-			"amount": 100.0,
-			"bankAccounts": [
-				{ "iban": "SK9611000000002918599669" }
-			],
-			"currencyCode": "EUR",
-			"variableSymbol": "123"
-		}
-	]
+$ npx bysquare <<< '{
+    "invoiceId": "random-id",
+    "payments": [
+        {
+            "type": 1,
+            "amount": 100.0,
+            "bankAccounts": [{ "iban": "SK9611000000002918599669" }],
+            "currencyCode": "EUR",
+            "variableSymbol": "123"
+        }
+    ]
 }'
-$ 0004A00090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6C75G19O246KTT5G8LTLM67HOIATP4OOG8F8FDLJ6T26KFCB1690NEVPQVSG0
+
+$ 0004A00090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6CB54HSI0KH9FCRASHNQBSKAQD2LJ4AU400UVKDNDPFRKLOBEVVVU0QJ000
 ```
 
 ## Related
@@ -157,9 +155,9 @@ https://github.com/dherges/npm-version-git-flow
 - Run `npm test`
 - Run `npm version <patch, minor, major>`
 - Commit and push
-- Run `npm version`
 - Follow git-flow instructions
 - Checkout to master
+- Build artefacts
 - Push commits and tag, git push && git push --tags
 - Validate with `npm publish --dry-run`
 - Publish to npm, `npm publish`

package/lib/cjs/cli.js

@@ -0,0 +1,90 @@
+#!/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();
+        console.log(fromJsonString(stdin));
+        process.exit(0);
+    })();
+}
+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");
+        console.log(fromJsonString(file));
+    }
+    else {
+        console.error(`File ${process.argv[2]} doesn't exists`);
+        process.exit(1);
+    }
+}
+function fromJsonString(stdin) {
+    const data = JSON.parse(stdin);
+    return (0, generate_js_1.generate)(data);
+}
+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 <<< \"{",
+        "		\"invoiceId\": \"random-id\",",
+        "		\"payments\": [",
+        "			{",
+        "				\"type\": 1,",
+        "				\"amount\": 100.0,",
+        "				\"bankAccounts\": [{ \"iban\": \"SK9611000000002918599669\" }],",
+        "				\"currencyCode\": \"EUR\",",
+        "				\"variableSymbol\": \"123\"",
+        "			}",
+        "		]",
+        "	}\"",
+    ].join("\n");
+}

package/lib/cjs/generate.d.ts

@@ -0,0 +1,54 @@
+/// <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
+]): Uint8Array;
+/**
+ * @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 addChecksum(model: DataModel): Uint8Array;
+/**
+ * Transform data to ordered tab-separated intermediate representation ready for
+ * encoding
+ *
+ * @see Table 15 PAY by square sequence data model
+ */
+export declare function deserialize(data: DataModel): string;
+type Options = {
+    /**
+     * Many banking apps do not support diacritics, which results in errors when
+     * serializing data from QR codes.
+     *
+     * @default true
+     */
+    deburr: boolean;
+};
+/**
+ * Generate QR string ready for encoding into text QR code
+ */
+export declare function generate(model: DataModel, options?: Options): string;
+export {};

package/lib/cjs/generate.js

@@ -0,0 +1,185 @@
+"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.deserialize = exports.addChecksum = exports.checksum = exports.bysquareHeader = void 0;
+const crc_32_1 = __importDefault(require("crc-32"));
+const lodash_deburr_1 = __importDefault(require("lodash.deburr"));
+const rfc4648_1 = require("rfc4648");
+const types_js_1 = require("./types.js");
+// @ts-ignore: missing types
+const lzma_1 = __importDefault(require("lzma"));
+/**
+ * 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 = Uint8Array.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 datasizeHeader(data) {
+    if (data.byteLength >= 2 ** 16) {
+        throw new Error("The maximum compressed data size has been reached");
+    }
+    const header = new Uint8Array(2);
+    header.set(Uint16Array.from([data.byteLength]));
+    return header;
+}
+/**
+ * @see 3.10 Appending CRC32 checksum
+ */
+function checksum(intermediate) {
+    const data = crc_32_1.default.str(intermediate);
+    const checksum = Buffer.alloc(4);
+    checksum.writeUInt32LE(data);
+    return checksum;
+}
+exports.checksum = checksum;
+/**
+ * Transfer object to a tabbed string and append a CRC32 checksum
+ *
+ * @see 3.10. Appending CRC32 checksum
+ */
+function addChecksum(model) {
+    const intermediate = deserialize(model);
+    const checksum = Uint32Array.from([crc_32_1.default.str(intermediate)]);
+    const byearray = [...intermediate].map(char => char.charCodeAt(0));
+    return Uint8Array.from([
+        ...new Uint8Array(checksum.buffer),
+        ...Uint8Array.from(byearray)
+    ]);
+}
+exports.addChecksum = addChecksum;
+/**
+ * Transform data to ordered tab-separated intermediate representation ready for
+ * encoding
+ *
+ * @see Table 15 PAY by square sequence data model
+ */
+function deserialize(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.deserialize = deserialize;
+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 payload = addChecksum(model);
+    const compressed = Uint8Array.from(lzma_1.default.compress(payload));
+    /**
+     * @see https://docs.fileformat.com/compression/lzma/#lzma-header
+     */
+    const _header = Uint8Array.from(compressed.subarray(0, 13));
+    const data = Uint8Array.from(compressed.subarray(13));
+    const output = Uint8Array.from([
+        ...bysquareHeader(),
+        ...datasizeHeader(payload),
+        ...data
+    ]);
+    return rfc4648_1.base32hex.stringify(output, {
+        pad: false
+    });
+}
+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,71 @@
+{
+  "name": "bysquare",
+  "description": "It's a national standard for payment QR codes adopted by Slovak Banking Association (SBA)",
+  "version": "2.1.0",
+  "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",
+    "typecheck": "tsc --noEmit",
+    "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": {
+    "crc-32": "~1.2.0",
+    "lodash.deburr": "~4.1.0",
+    "lzma": "~2.3.0",
+    "rfc4648": "~1.5.0"
+  },
+  "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"
+  ]
+}

package/lib/{parse.d.ts → cjs/parse.d.ts}

@@ -2,11 +2,11 @@ import { DataModel } from "./index.js";
 /**
  * @see 3.14. Generating by square Code
  */
-export declare function buildModel(qr: string): DataModel;
+export declare function serialize(qr: string): DataModel;
 /**
  * @see 3.16. Decoding client data from QR Code 2005 symbol
  */
-export declare function parse(qr: string): Promise<DataModel>;
+export declare function parse(qr: string): DataModel;
 /**
  * Detect if qr string contains bysquare header.
  *