bysquare 2.9.0 → 2.11.0

package/README.md

@@ -22,9 +22,10 @@ transformed into images depends on how you implement it. See
 
 ## Installation
 
-**NOTE**: This package is native [ESM][mozzila-esm] and no longer provides a
-CommonJS export. If your project uses CommonJS, you will have to convert to ESM
-or use the dynamic [`import()`][mozzila-import] function.
+> [!NOTE]
+> This package is native [ESM][mozzila-esm] and no longer provides a
+> CommonJS export. If your project uses CommonJS, you will have to convert to ESM
+> or use the dynamic [`import()`][mozzila-import] function.
 
 [mozzila-esm]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
 [mozzila-import]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import
@@ -49,23 +50,17 @@ Since `v1.28+` import from npm registry using `npm:` prefix.
 import {
 	decode,
 	encode,
-} from "npm:bysquare@2.8.0";
+} from "npm:bysquare@latest";
 ```
 
 ### Browser
 
 ```html
 <script type="module">
-	import { encode, decode } from "https://esm.sh/bysquare@2.8.0/";
+	import { encode, decode } from "https://esm.sh/bysquare@latest";
 </script>
 ```
 
-## How it works
-
-### Encoding sequence
-
-![logic](./docs/uml/logic.svg)
-
 ## Usage
 
 ### Encode
@@ -143,6 +138,12 @@ qrstring argument should be a valid QR code string.
 npx bysquare --decode <qrstring>
 ```
 
+## How it works
+
+### Encoding sequence
+
+![logic](./docs/uml/logic.svg)
+
 ## Platform support
 
 I mainly focus on LTS versions of Node.js and try to use the most idiomatic
@@ -163,6 +164,12 @@ to use without additional setup, showing its improved maturity.
 
 The latest version of Chrome, Firefox, and Safari.
 
+## Troubleshooting & Recommendations
+
+### Encoded data are without diacritics
+
+The library removes all diacritics from the input data to ensure maximum compatibility, as not all banks support diacritics, which may lead to errors. If you need to retain diacritics, disable deburr option when encoding data - `encode(model, { deburr: false })`.
+
 ## Related
 
 - <https://bysquare.com/>

package/dist/base32hex.d.ts

@@ -0,0 +1,2 @@
+export declare function encode(input: Uint8Array, addPadding?: boolean): string;
+export declare function decode(input: string, isLoose?: boolean): Uint8Array;

package/dist/base32hex.js

@@ -0,0 +1,53 @@
+const base32Hex = {
+    chars: "0123456789ABCDEFGHIJKLMNOPQRSTUV",
+    bits: 5,
+    mask: 0b11111, // Mask to extract 5 bits
+};
+export function encode(input, addPadding = true) {
+    const output = Array();
+    let buffer = 0;
+    let bitsLeft = 0;
+    for (let i = 0; i < input.length; i++) {
+        buffer = (buffer << 8) | input[i];
+        bitsLeft += 8;
+        while (bitsLeft >= base32Hex.bits) {
+            bitsLeft -= base32Hex.bits;
+            const index = (buffer >> bitsLeft) & base32Hex.mask;
+            output.push(base32Hex.chars[index]);
+        }
+    }
+    if (bitsLeft > 0) {
+        const maskedValue = (buffer << (base32Hex.bits - bitsLeft)) & base32Hex.mask;
+        output.push(base32Hex.chars[maskedValue]);
+    }
+    let base32hex = output.join("");
+    if (addPadding) {
+        const paddedLength = Math.ceil(base32hex.length / 8) * 8;
+        base32hex = base32hex.padEnd(paddedLength, "=");
+    }
+    return base32hex;
+}
+export function decode(input, isLoose = false) {
+    if (isLoose) {
+        input = input.toUpperCase();
+        const paddingNeeded = (8 - (input.length % 8)) % 8;
+        input += "=".repeat(paddingNeeded);
+    }
+    input = input.replace(/=+$/, "");
+    const output = Array();
+    let buffer = 0;
+    let bitsLeft = 0;
+    for (let i = 0; i < input.length; i++) {
+        const index = base32Hex.chars.indexOf(input[i]);
+        if (index === -1) {
+            throw new Error("Invalid base32hex string");
+        }
+        buffer = (buffer << base32Hex.bits) | index;
+        bitsLeft += base32Hex.bits;
+        if (bitsLeft >= 8) {
+            bitsLeft -= 8;
+            output.push((buffer >> bitsLeft) & 0xFF);
+        }
+    }
+    return Uint8Array.from(output);
+}

package/dist/cli.js

@@ -15,6 +15,14 @@ const args = parseArgs({
             type: "boolean",
             short: "e",
         },
+        validate: {
+            type: "boolean",
+            short: "v",
+        },
+        deburr: {
+            type: "boolean",
+            short: "b",
+        },
         help: {
             type: "boolean",
             short: "h",
@@ -48,7 +56,10 @@ if (process.stdin.isTTY) {
                 }
             }
             if (file.endsWith(".json")) {
-                console.log(encode(JSON.parse(data)));
+                console.log(encode(JSON.parse(data), {
+                    validate: Boolean(args.values.validate),
+                    deburr: Boolean(args.values.deburr),
+                }));
             }
             process.exit(0);
         }
@@ -80,6 +91,12 @@ if (process.stdin.isTTY) {
             "	-e, --encode",
             "		Encode JSON data from one or more files and print the corresponding QR code.",
             "",
+            "	-v, --validate",
+            "		Validate JSON data from one or more files before encoding.",
+            "",
+            "	-b, --deburr",
+            "		Deburr JSON data from one or more files before encoding.",
+            "",
             "	-h, --help",
             "		Display the help message and exit.",
             "",

package/dist/crc32.d.ts

@@ -0,0 +1 @@
+export declare function crc32(data: string): number;

package/dist/crc32.js

@@ -0,0 +1,63 @@
+// Computed CRC32 lookup table
+// const CRC32_TABLE = new Uint32Array(256);
+// for (let i = 0; i < CRC32_TABLE.length; i++) {
+// 	let crc = i;
+// 	for (let j = 0; j < 8; j++) {
+// 		crc = (crc >>> 1) ^ (0xEDB88320 * (crc & 1));
+// 	}
+// 	CRC32_TABLE[i] = crc;
+// }
+// dprint-ignore
+const CRC32_TABLE = [
+    0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, 0x706af48f,
+    0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, 0xe0d5e91e, 0x97d2d988,
+    0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, 0x90bf1d91, 0x1db71064, 0x6ab020f2,
+    0xf3b97148, 0x84be41de, 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7,
+    0x136c9856, 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9,
+    0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, 0xa2677172,
+    0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, 0x35b5a8fa, 0x42b2986c,
+    0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, 0x45df5c75, 0xdcd60dcf, 0xabd13d59,
+    0x26d930ac, 0x51de003a, 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423,
+    0xcfba9599, 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924,
+    0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, 0x01db7106,
+    0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, 0x9fbfe4a5, 0xe8b8d433,
+    0x7807c9a2, 0x0f00f934, 0x9609a88e, 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d,
+    0x91646c97, 0xe6635c01, 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e,
+    0x6c0695ed, 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950,
+    0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, 0xfbd44c65,
+    0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, 0x4adfa541, 0x3dd895d7,
+    0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, 0x346ed9fc, 0xad678846, 0xda60b8d0,
+    0x44042d73, 0x33031de5, 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa,
+    0xbe0b1010, 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f,
+    0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, 0x2eb40d81,
+    0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, 0x03b6e20c, 0x74b1d29a,
+    0xead54739, 0x9dd277af, 0x04db2615, 0x73dc1683, 0xe3630b12, 0x94643b84,
+    0x0d6d6a3e, 0x7a6a5aa8, 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1,
+    0xf00f9344, 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb,
+    0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, 0x67dd4acc,
+    0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, 0xd6d6a3e8, 0xa1d1937e,
+    0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, 0xa6bc5767, 0x3fb506dd, 0x48b2364b,
+    0xd80d2bda, 0xaf0a1b4c, 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55,
+    0x316e8eef, 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236,
+    0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, 0xb2bd0b28,
+    0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, 0x2cd99e8b, 0x5bdeae1d,
+    0x9b64c2b0, 0xec63f226, 0x756aa39c, 0x026d930a, 0x9c0906a9, 0xeb0e363f,
+    0x72076785, 0x05005713, 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38,
+    0x92d28e9b, 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242,
+    0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, 0x18b74777,
+    0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, 0x8f659eff, 0xf862ae69,
+    0x616bffd3, 0x166ccf45, 0xa00ae278, 0xd70dd2ee, 0x4e048354, 0x3903b3c2,
+    0xa7672661, 0xd06016f7, 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc,
+    0x40df0b66, 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9,
+    0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, 0xcdd70693,
+    0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, 0x5d681b02, 0x2a6f2b94,
+    0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, 0x2d02ef8d
+];
+export function crc32(data) {
+    let crc = 0 ^ (-1);
+    const encoded = new TextEncoder().encode(data);
+    for (let i = 0; i < encoded.length; i++) {
+        crc = (crc >>> 8) ^ CRC32_TABLE[(crc ^ encoded[i]) & 0xFF];
+    }
+    return (crc ^ (-1)) >>> 0;
+}

package/dist/deburr.d.ts

@@ -1,5 +1,5 @@
 export declare function deburrLetter(key: string): string;
 /**
- * @desc Deburrs string by converting Latin-1 Supplement and Latin Extended-A letters to basic Latin letters and removing [combining diacritical marks](https://en.wikipedia.org/wiki/Combining_Diacritical_Marks).
+ * Deburrs string by converting Latin-1 Supplement and Latin Extended-A letters to basic Latin letters and removing [combining diacritical marks](https://en.wikipedia.org/wiki/Combining_Diacritical_Marks).
  */
 export declare function deburr(text: string): string;

package/dist/deburr.js

@@ -1,5 +1,5 @@
-/** Used to map Latin Unicode letters to basic Latin letters. */
 /** dprint-ignore */
+/** Used to map Latin Unicode letters to basic Latin letters. */
 const deburredLettersMap = {
     // Latin-1 Supplement block.
     '\xc0': 'A', '\xc1': 'A', '\xc2': 'A', '\xc3': 'A', '\xc4': 'A', '\xc5': 'A',
@@ -59,11 +59,17 @@ const deburredLettersMap = {
 export function deburrLetter(key) {
     return deburredLettersMap[key];
 }
-/** Used to match Latin Unicode letters (excluding mathematical operators). */
+/**
+ * Used to match Latin Unicode letters (excluding mathematical operators).
+ */
 const reLatin = /[\xc0-\xd6\xd8-\xf6\xf8-\xff\u0100-\u017f]/g;
-/** Used to compose unicode character classes. */
+/**
+ * Used to compose unicode character classes.
+ */
 const rsComboMarksRange = "\\u0300-\\u036f\\ufe20-\\ufe23", rsComboSymbolsRange = "\\u20d0-\\u20f0";
-/** Used to compose unicode capture groups. */
+/**
+ * Used to compose unicode capture groups.
+ */
 const rsCombo = "[" + rsComboMarksRange + rsComboSymbolsRange + "]";
 /**
  * Used to match [combining diacritical marks](https://en.wikipedia.org/wiki/Combining_Diacritical_Marks) and
@@ -71,7 +77,7 @@ const rsCombo = "[" + rsComboMarksRange + rsComboSymbolsRange + "]";
  */
 const reComboMark = RegExp(rsCombo, "g");
 /**
- * @desc Deburrs string by converting Latin-1 Supplement and Latin Extended-A letters to basic Latin letters and removing [combining diacritical marks](https://en.wikipedia.org/wiki/Combining_Diacritical_Marks).
+ * Deburrs string by converting Latin-1 Supplement and Latin Extended-A letters to basic Latin letters and removing [combining diacritical marks](https://en.wikipedia.org/wiki/Combining_Diacritical_Marks).
  */
 export function deburr(text) {
     return text.replace(reLatin, deburrLetter).replace(reComboMark, "");

package/dist/decode.js

@@ -1,5 +1,5 @@
 import { decompress } from "lzma1";
-import { base32hex } from "rfc4648";
+import * as base32hex from "./base32hex.js";
 import { CurrencyCode, PaymentOptions, Version, } from "./index.js";
 function cleanUndefined(obj) {
     Object.keys(obj).forEach((key) => {
@@ -133,7 +133,7 @@ export function deserialize(qr) {
  * the input header array into four nibbles representing the bysquare header
  * values.
  *
- * @param header 2-bytes sie
+ * @param header 2-bytes size
  */
 function bysquareHeaderDecoder(header) {
     const bytes = (header[0] << 8) | header[1];
@@ -164,16 +164,11 @@ export const parse = decode;
  * @see 3.16.
  */
 export function decode(qr) {
-    let bytes;
-    try {
-        bytes = base32hex.parse(qr, { loose: true });
-    }
-    catch (error) {
-        throw new DecodeError(error, "Unable to decode QR string base32hex encoding");
-    }
+    const bytes = base32hex.decode(qr);
     const bysquareHeader = bytes.slice(0, 2);
-    if ((bysquareHeaderDecoder(bysquareHeader).version > Version["1.1.0"])) {
-        throw new Error("Unsupported Bysquare version");
+    const decodedBysquareHeader = bysquareHeaderDecoder(bysquareHeader);
+    if ((decodedBysquareHeader.version > Version["1.1.0"])) {
+        throw new Error(`Unsupported Bysquare version '${decodedBysquareHeader.version}' in header detected. Only '0' and '1' values are supported`);
     }
     /**
      * The process of decompressing data requires the addition of an LZMA header
@@ -223,17 +218,17 @@ export function decode(qr) {
  * not very reliable, there is room for improvement for the future.
  */
 export function detect(qr) {
-    let parsed;
+    let decoded;
     try {
-        parsed = base32hex.parse(qr, { loose: true });
+        decoded = base32hex.decode(qr, true);
     }
-    catch {
+    catch (error) {
         return false;
     }
-    if (parsed.byteLength < 2) {
+    if (decoded.byteLength < 2) {
         return false;
     }
-    const bysquareHeader = parsed.subarray(0, 2);
+    const bysquareHeader = decoded.subarray(0, 2);
     const header = bysquareHeaderDecoder(bysquareHeader);
     const isValid = [
         header.bysquareType,

package/dist/encode.d.ts

@@ -47,7 +47,13 @@ type Options = {
      *
      * @default true
      */
-    deburr: boolean;
+    deburr?: boolean;
+    /**
+     * If true, validates the data model before encoding it.
+     *
+     * @default true
+     */
+    validate?: boolean;
 };
 /** @deprecated */
 export declare const generate: typeof encode;

package/dist/encode.js

@@ -1,8 +1,10 @@
-import crc32 from "crc-32";
 import { compress } from "lzma1";
-import { base32hex } from "rfc4648";
+import * as base32hex from "./base32hex.js";
+import { crc32 } from "./crc32.js";
 import { deburr } from "./deburr.js";
-import { PaymentOptions, } from "./types.js";
+import { PaymentOptions, Version, } from "./types.js";
+import { validateDataModel } from "./validations.js";
+const MAX_COMPRESSED_SIZE = 131_072; // 2^17
 /**
  * Returns a 2 byte buffer that represents the header of the bysquare
  * specification
@@ -24,9 +26,17 @@ header = [
     0x00, 0x00,
     0x00, 0x00
 ]) {
-    const isValid = header.every((nibble) => 0 <= nibble && nibble <= 15);
-    if (!isValid) {
-        throw new Error("Invalid header byte value, valid range <0,15>");
+    if (header[0] < 0 || header[0] > 15) {
+        throw new Error(`Invalid BySquareType value '${header[0]}' in header, valid range <0,15>`);
+    }
+    if (header[1] < 0 || header[1] > 15) {
+        throw new Error(`Invalid Version value '${header[1]}' in header, valid range <0,15>`);
+    }
+    if (header[2] < 0 || header[2] > 15) {
+        throw new Error(`Invalid DocumentType value '${header[2]}' in header, valid range <0,15>`);
+    }
+    if (header[3] < 0 || header[3] > 15) {
+        throw new Error(`Invalid Reserved value '${header[3]}' in header, valid range <0,15>`);
     }
     const [bySquareType, version, documentType, reserved,] = header;
     // Combine 4-nibbles to 2-bytes
@@ -41,8 +51,8 @@ header = [
  * combination with CRC32 in bytes.
  */
 export function headerDataLength(length) {
-    if (length >= 131072 /** 2^17 */) {
-        throw new Error("The maximum compressed data size has been reached");
+    if (length >= MAX_COMPRESSED_SIZE) {
+        throw new Error(`Data size ${length} exceeds limit of ${MAX_COMPRESSED_SIZE} bytes`);
     }
     const header = new ArrayBuffer(2);
     new DataView(header).setUint16(0, length, true);
@@ -55,7 +65,7 @@ export function headerDataLength(length) {
  */
 export function addChecksum(serialized) {
     const checksum = new ArrayBuffer(4);
-    new DataView(checksum).setUint32(0, crc32.str(serialized), true);
+    new DataView(checksum).setUint32(0, crc32(serialized), true);
     const byteArray = new TextEncoder().encode(serialized);
     return Uint8Array.from([
         ...new Uint8Array(checksum),
@@ -142,25 +152,26 @@ export const generate = encode;
 /**
  * Generate QR string ready for encoding into text QR code
  */
-export function encode(model, options = { deburr: true }) {
-    if (options.deburr) {
+export function encode(model, options) {
+    const { deburr = true, validate = true } = options ?? {};
+    if (deburr) {
         removeDiacritics(model);
     }
+    if (validate) {
+        validateDataModel(model);
+    }
     const payload = serialize(model);
     const withChecksum = addChecksum(payload);
     const compressed = Uint8Array.from(compress(withChecksum));
     const _lzmaHeader = Uint8Array.from(compressed.subarray(0, 13));
     const lzmaBody = Uint8Array.from(compressed.subarray(13));
     const output = Uint8Array.from([
-        // FIXME:
-        // for now other implementation of bysquare doesn't recognize header if
-        // version is specified like TatraBanka
+        // NOTE: Newer version 1.1.0 is not supported by all apps (e.g., TatraBanka).
+        // We recommend using version "1.0.0" for better compatibility.
         // ...headerBysquare([0x00, Version["1.1.0"], 0x00, 0x00]),
-        ...headerBysquare([0x00, 0x00, 0x00, 0x00]),
+        ...headerBysquare([0x00, Version["1.0.0"], 0x00, 0x00]),
         ...headerDataLength(withChecksum.byteLength),
         ...lzmaBody,
     ]);
-    return base32hex.stringify(output, {
-        pad: false,
-    });
+    return base32hex.encode(output, false);
 }

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { decode, detect, parse } from "./decode.js";
 export { encode, generate } from "./encode.js";
+export { validateDataModel, ValidationErrorMessage } from "./validations.js";
 export * from "./types.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export { decode, detect, parse } from "./decode.js";
 export { encode, generate } from "./encode.js";
+export { validateDataModel, ValidationErrorMessage } from "./validations.js";
 export * from "./types.js";

package/dist/types.d.ts

@@ -6,20 +6,22 @@
  */
 export declare enum Version {
     /**
-     * 2013-02-22
-     * Created this document from original by square specifications
+     * Created this document from original by square specifications.
+     *
+     * **Released Date:** 2013-02-22
      */
     "1.0.0" = 0,
     /**
-     * 2015-06-24
      * Added fields for beneficiary name and address
+     *
+     * **Released Date:** 2015-06-24
      */
     "1.1.0" = 1
 }
 /**
  * Kalendárny mesiac.
  */
-export declare enum MonthClassifier {
+export declare enum Month {
     January = 1,
     February = 2,
     March = 4,
@@ -60,13 +62,22 @@ export type Day = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 1
  * Možnosti platby sa dajú kombinovať. Oddeľujú sa medzerou a treba uviesť vždy
  * aspoň jednu z možností:
  *
- * - paymentorder: platobný príkaz
- * - standingorder: trvalý príkaz, údaje sa vyplnia do StandingOrderExt
- * - directdebit: inkaso, údaje sa vyplnia do DirectDebitExt
+ * - `PaymentOrder`: platobný príkaz
+ * - `StandingOrder`: trvalý príkaz, údaje sa vyplnia do StandingOrderExt
+ * - `DirectDebit`: inkaso, údaje sa vyplnia do DirectDebitExt
  */
 export declare enum PaymentOptions {
+    /**
+     * Platobný príkaz
+     */
     PaymentOrder = 1,
+    /**
+     * Trvalý príkaz, údaje sa vyplnia do StandingOrderExt
+     */
     StandingOrder = 2,
+    /**
+     * Inkaso, údaje sa vyplnia do DirectDebitExt
+     */
     DirectDebit = 4
 }
 /**
@@ -74,121 +85,140 @@ export declare enum PaymentOptions {
  */
 export type BankAccount = {
     /**
+     * Medzinárodné číslo bankového účtu vo formáte IBAN. Príklad:
+     *
      * Maximálna dĺžka 34
-     * Pattern: [A-Z]{2}[0-9]{2}[A-Z0-9]{0,30}
      *
-     * Medzinárodné číslo bankového účtu vo formáte IBAN. Príklad:
-     * "SK8209000000000011424060". Viac na
-     * http://www.sbaonline.sk/sk/projekty/financne-vzdelavanie/slovnik-bankovych-pojmov/iii/.
+     * Pattern: `[A-Z]{2}[0-9]{2}[A-Z0-9]{0,30}`
+     *
+     * @example `"SK8209000000000011424060"`
      */
     iban: string;
     /**
-     * Formát ISO 9362 (swift) 8 or 11 characters long
-     * Pattern: [A-Z]{4}[A-Z]{2}[A-Z\d]{2}([A-Z\d]{3})?
-     *
      * Medzinárodný bankový identifikačný kód (z ang. Bank Identification Code).
-     * Viac na http://www.sbaonline.sk/sk/projekty/financne-vzdelavanie/slovnik-bankovych-pojmov/bbb/bic
+     *
+     * Formát [ISO 9362](https://en.wikipedia.org/wiki/ISO_9362) (swift) 8 or 11 characters long
+     *
+     * Pattern: `[A-Z]{4}[A-Z]{2}[A-Z\d]{2}([A-Z\d]{3})?`
+     *
+     * @example "TATRSKBX"
      */
     bic?: string;
 };
 /**
  * Inksaná schéma. Uvádza ja jedna z možností:
  *
- * SEPA - Inkaso zodpovedá schéme
- * SEPA. other - iné
+ * - SEPA - Inkaso zodpovedá schéme
+ * - SEPA. other - iné
  */
 export declare enum DirectDebitScheme {
+    /**
+     * other - iné
+     */
     Other = 0,
+    /**
+     * SEPA - Inkaso zodpovedá schéme
+     */
     Sepa = 1
 }
 /**
- * Maximálna dĺžka 1
- *
  * Typ inkasa. Uvádza ja jedna z možností:
  *
- * one-off - jednorázové inkaso
- * recurrent - opakované inkaso
+ * Maximálna dĺžka 1
+ *
+ * - one-off - jednorázové inkaso
+ * - recurrent - opakované inkaso
  */
 export declare enum DirectDebitType {
+    /**
+     * Jednorázové inkaso
+     */
     OneOff = 0,
+    /**
+     * Opakované inkaso
+     */
     Recurrent = 1
 }
 export type Beneficiary = {
     /**
-     * Maximálna dĺžka 70
-     *
      * Rozšírenie o meno príjemcu
+     *
+     * Maximálna dĺžka 70
      */
     name?: string;
     /**
-     * Maximálna dĺžka 70
-     *
      * Rozšírenie o adresu príjemcu
+     *
+     * Maximálna dĺžka 70
      */
     street?: string;
     /**
-     * Maximálna dĺžka 70
-     *
      * Rozšírenie o adresu príjemcu (druhý riadok)
+     *
+     * Maximálna dĺžka 70
      */
     city?: string;
 };
 export type SimplePayment = {
     /**
-     * Maximálna dĺžka 15
-     *
      * Čiastka platby. Povolené sú len kladné hodnoty. Desatinná čast je
      * oddelená bodkou. Môže ostať nevyplnené, napríklad pre dobrovoľný
-     * príspevok (donations). Príklad: Tisíc sa uvádza ako "1000". Jedna celá
-     * deväťdesiatdeväť sa uvádza ako "1.99". Desať celých peťdesiat sa uvádza
-     * ako "10.5". Nula celá nula osem sa uvádza ako "0.08".
+     * príspevok (donations).
+     *
+     * Príklad: Tisíc sa uvádza ako `1000`. Jedna celá
+     * deväťdesiatdeväť sa uvádza ako `1.99`. Desať celých peťdesiat sa uvádza
+     * ako `10.5`. Nula celá nula osem sa uvádza ako `0.08`.
+     *
+     * Maximálna dĺžka 15
      */
     amount?: number;
     /**
+     * Mena v [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) formáte (3 písmená).
+     *
      * Pattern: [A-Z]{3}
      *
-     * Mena v ISO 4217 formáte (3 písmená). Príklad: "EUR"
+     * @example "EUR"
      */
     currencyCode: string | CurrencyCode;
     /**
-     * Formát YYYYMMDD
+     * Dátum splatnosti vo formáte [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) `"RRRR-MM-DD"`.
+     * Vprípade trvalého príkazu označuje dátum prvej platby.
      *
-     * Dátum splatnosti vo formáte ISO 8601 "RRRR-MM-DD". Nepovinný údaj. V
-     * prípade trvalého príkazu označuje dátum prvej platby.
+     * Formát `YYYY-MM-DD`
      */
     paymentDueDate?: string;
     /**
+     * Variabilný symbol je maximálne 10 miestne číslo.
+     *
      * Maximálna dĺžka 10
      * Pattern: [0-9]{0,10}
-     *
-     * Variabilný symbol je maximálne 10 miestne číslo. Nepovinný údaj.
      */
     variableSymbol?: string;
     /**
+     * Konštantný symbol je 4 miestne identifikačné číslo.
+     *
      * Maximálna dĺžka 4
      * Pattern: [0-9]{0,4}
-     *
-     * Konštantný symbol je 4 miestne identifikačné číslo. Nepovinný údaj.
      */
     constantSymbol?: string;
     /**
+     * Špecifický symbol je maximálne 10 miestne číslo.
+     *
      * Maximálna dĺžka 10
      * Pattern: [0-9]{0,10}
-     *
-     * Špecifický symbol je maximálne 10 miestne číslo. Nepovinný údaj.
      */
     specificSymbol?: string;
     /**
-     * Maximálna dĺžka 35
-     *
      * Referenčná informácia prijímateľa podľa SEPA.
+     *
+     * Maximálna dĺžka 35
      */
     originatorsReferenceInformation?: string;
     /**
-     * Maximálna dĺžka 140
-     *
      * Správa pre prijímateľa. Údaje o platbe, na základe ktorých príjemca bude
-     * môcť platbu identifikovať. Odporúča sa maximálne 140 Unicode znakov.
+     * môcť platbu identifikovať.
+     *
+     * Maximálna dĺžka 140
      */
     paymentNote?: string;
     /**
@@ -214,7 +244,7 @@ export type StandingOrder = SimplePayment & {
     /**
      * Medzerou oddelený zoznam mesiacov, v ktoré sa má platba uskutočniť.
      */
-    month?: MonthClassifier;
+    month?: Month;
     /**
      * Opakovanie (periodicita) trvalého príkazu.
      */
@@ -222,7 +252,7 @@ export type StandingOrder = SimplePayment & {
     /**
      * Dátum poslednej platby v trvalom príkaze.
      *
-     * Formát YYYYMMDD
+     * Formát `YYYYMMDD`
      */
     lastDate?: string;
 };
@@ -234,34 +264,34 @@ export type DirectDebit = SimplePayment & {
     directDebitScheme?: DirectDebitScheme;
     directDebitType?: DirectDebitType;
     /**
-     * Maximálna dĺžka 35
-     *
      * Identifikácia mandátu medzi veriteľom a dlžníkom podľa SEPA.
+     *
+     * Maximálna dĺžka 35
      */
     mandateId?: string;
     /**
-     * Maximálna dĺžka 35
-     *
      * Identifikácia veriteľa podľa SEPA.
+     *
+     * Maximálna dĺžka 35
      */
     creditorId?: string;
     /**
-     * Maximálna dĺžka 35
-     *
      * Identifikácia zmluvy medzi veriteľom a dlžníkom podľa SEPA.
+     *
+     * Maximálna dĺžka 35
      */
     contractId?: string;
     /**
-     * Maximálna dĺžka 15
-     *
      * Maximálna čiastka inkasa.
+     *
+     * Maximálna dĺžka 15
      */
     maxAmount?: number;
     /**
-     * Maximálna dĺžka 8
-     * Formát YYYYMMDD
-     *
      * Dátum platnosti inkasa. Platnosť inkasa zaníka dňom tohto dátumu.
+     *
+     * Maximálna dĺžka 8
+     * Formát `YYYYMMDD`
      */
     validTillDate?: string;
 };
@@ -271,10 +301,10 @@ export type DirectDebit = SimplePayment & {
 export type Payment = PaymentOrder | StandingOrder | DirectDebit;
 export type DataModel = {
     /**
-     * Maximálna dĺžka 10
-     *
      * Číslo faktúry v prípade, že údaje sú súčasťou faktúry, alebo
      * identifikátor pre intérne potreby vystavovateľa.
+     *
+     * Maximálna dĺžka 10
      */
     invoiceId?: string;
     /**
@@ -284,7 +314,7 @@ export type DataModel = {
     payments: Payment[];
 };
 /**
- * ISO-4217
+ * [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217)
  */
 export declare enum CurrencyCode {
     AED = "AED",

package/dist/types.js

@@ -7,34 +7,36 @@
 export var Version;
 (function (Version) {
     /**
-     * 2013-02-22
-     * Created this document from original by square specifications
+     * Created this document from original by square specifications.
+     *
+     * **Released Date:** 2013-02-22
      */
     Version[Version["1.0.0"] = 0] = "1.0.0";
     /**
-     * 2015-06-24
      * Added fields for beneficiary name and address
+     *
+     * **Released Date:** 2015-06-24
      */
     Version[Version["1.1.0"] = 1] = "1.1.0";
 })(Version || (Version = {}));
 /**
  * Kalendárny mesiac.
  */
-export var MonthClassifier;
-(function (MonthClassifier) {
-    MonthClassifier[MonthClassifier["January"] = 1] = "January";
-    MonthClassifier[MonthClassifier["February"] = 2] = "February";
-    MonthClassifier[MonthClassifier["March"] = 4] = "March";
-    MonthClassifier[MonthClassifier["April"] = 8] = "April";
-    MonthClassifier[MonthClassifier["May"] = 16] = "May";
-    MonthClassifier[MonthClassifier["June"] = 32] = "June";
-    MonthClassifier[MonthClassifier["July"] = 64] = "July";
-    MonthClassifier[MonthClassifier["August"] = 128] = "August";
-    MonthClassifier[MonthClassifier["September"] = 256] = "September";
-    MonthClassifier[MonthClassifier["October"] = 512] = "October";
-    MonthClassifier[MonthClassifier["November"] = 1024] = "November";
-    MonthClassifier[MonthClassifier["December"] = 2048] = "December";
-})(MonthClassifier || (MonthClassifier = {}));
+export var Month;
+(function (Month) {
+    Month[Month["January"] = 1] = "January";
+    Month[Month["February"] = 2] = "February";
+    Month[Month["March"] = 4] = "March";
+    Month[Month["April"] = 8] = "April";
+    Month[Month["May"] = 16] = "May";
+    Month[Month["June"] = 32] = "June";
+    Month[Month["July"] = 64] = "July";
+    Month[Month["August"] = 128] = "August";
+    Month[Month["September"] = 256] = "September";
+    Month[Month["October"] = 512] = "October";
+    Month[Month["November"] = 1024] = "November";
+    Month[Month["December"] = 2048] = "December";
+})(Month || (Month = {}));
 /**
  * Deň platby vyplývajúci z opakovania (Periodicity). Deň v mesiaci je číslo
  * medzi 1 a 31. Deň v týždni je číslo medzi 1 a 7 (1 = pondelok, 2=utorok, …, 7
@@ -55,42 +57,63 @@ export var Periodicity;
  * Možnosti platby sa dajú kombinovať. Oddeľujú sa medzerou a treba uviesť vždy
  * aspoň jednu z možností:
  *
- * - paymentorder: platobný príkaz
- * - standingorder: trvalý príkaz, údaje sa vyplnia do StandingOrderExt
- * - directdebit: inkaso, údaje sa vyplnia do DirectDebitExt
+ * - `PaymentOrder`: platobný príkaz
+ * - `StandingOrder`: trvalý príkaz, údaje sa vyplnia do StandingOrderExt
+ * - `DirectDebit`: inkaso, údaje sa vyplnia do DirectDebitExt
  */
 export var PaymentOptions;
 (function (PaymentOptions) {
+    /**
+     * Platobný príkaz
+     */
     PaymentOptions[PaymentOptions["PaymentOrder"] = 1] = "PaymentOrder";
+    /**
+     * Trvalý príkaz, údaje sa vyplnia do StandingOrderExt
+     */
     PaymentOptions[PaymentOptions["StandingOrder"] = 2] = "StandingOrder";
+    /**
+     * Inkaso, údaje sa vyplnia do DirectDebitExt
+     */
     PaymentOptions[PaymentOptions["DirectDebit"] = 4] = "DirectDebit";
 })(PaymentOptions || (PaymentOptions = {}));
 /**
  * Inksaná schéma. Uvádza ja jedna z možností:
  *
- * SEPA - Inkaso zodpovedá schéme
- * SEPA. other - iné
+ * - SEPA - Inkaso zodpovedá schéme
+ * - SEPA. other - iné
  */
 export var DirectDebitScheme;
 (function (DirectDebitScheme) {
+    /**
+     * other - iné
+     */
     DirectDebitScheme[DirectDebitScheme["Other"] = 0] = "Other";
+    /**
+     * SEPA - Inkaso zodpovedá schéme
+     */
     DirectDebitScheme[DirectDebitScheme["Sepa"] = 1] = "Sepa";
 })(DirectDebitScheme || (DirectDebitScheme = {}));
 /**
- * Maximálna dĺžka 1
- *
  * Typ inkasa. Uvádza ja jedna z možností:
  *
- * one-off - jednorázové inkaso
- * recurrent - opakované inkaso
+ * Maximálna dĺžka 1
+ *
+ * - one-off - jednorázové inkaso
+ * - recurrent - opakované inkaso
  */
 export var DirectDebitType;
 (function (DirectDebitType) {
+    /**
+     * Jednorázové inkaso
+     */
     DirectDebitType[DirectDebitType["OneOff"] = 0] = "OneOff";
+    /**
+     * Opakované inkaso
+     */
     DirectDebitType[DirectDebitType["Recurrent"] = 1] = "Recurrent";
 })(DirectDebitType || (DirectDebitType = {}));
 /**
- * ISO-4217
+ * [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217)
  */
 export var CurrencyCode;
 (function (CurrencyCode) {

package/dist/validations.d.ts

@@ -0,0 +1,41 @@
+import { BankAccount, DataModel, SimplePayment } from "./types.js";
+export declare enum ValidationErrorMessage {
+    IBAN = "Invalid IBAN. Make sure ISO 13616 format is used.",
+    BIC = "Invalid BIC. Make sure ISO 9362 format is used.",
+    CurrencyCode = "Invalid currency code. Make sure ISO 4217 format is used.",
+    Date = "Invalid date. Make sure ISO 8601 format is used."
+}
+/**
+ * This error will be thrown in case of a validation issue. It provides message with error description and specific path to issue in dataModel object.
+ */
+export declare class ValidationError extends Error {
+    name: string;
+    path: string;
+    /**
+     * @param message - explains, what is wrong on the specific field
+     * @param path - navigates to the specific field in DataModel, where error occurred
+     */
+    constructor(message: ValidationErrorMessage, path: string);
+}
+/**
+ * validates bankAccount fields:
+ * - iban (ISO 13616)
+ * - bic (ISO 9362)
+ */
+export declare function validateBankAccount(bankAccount: BankAccount, path: string): void;
+/**
+ * validate simple payment fields:
+ * - currencyCode (ISO 4217)
+ * - paymentDueDate (ISO 8601)
+ * - bankAccounts
+ *
+ * @see validateBankAccount
+ */
+export declare function validateSimplePayment(simplePayment: SimplePayment, path: string): void;
+/**
+ * Validate `payments` field of dataModel.
+ *
+ * @see validateSimplePayment
+ * @see ValidationError
+ */
+export declare function validateDataModel(dataModel: DataModel): DataModel;

package/dist/validations.js

@@ -0,0 +1,67 @@
+import validator from "validator";
+export var ValidationErrorMessage;
+(function (ValidationErrorMessage) {
+    ValidationErrorMessage["IBAN"] = "Invalid IBAN. Make sure ISO 13616 format is used.";
+    ValidationErrorMessage["BIC"] = "Invalid BIC. Make sure ISO 9362 format is used.";
+    ValidationErrorMessage["CurrencyCode"] = "Invalid currency code. Make sure ISO 4217 format is used.";
+    ValidationErrorMessage["Date"] = "Invalid date. Make sure ISO 8601 format is used.";
+})(ValidationErrorMessage || (ValidationErrorMessage = {}));
+/**
+ * This error will be thrown in case of a validation issue. It provides message with error description and specific path to issue in dataModel object.
+ */
+export class ValidationError extends Error {
+    name = "ValidationError";
+    path;
+    /**
+     * @param message - explains, what is wrong on the specific field
+     * @param path - navigates to the specific field in DataModel, where error occurred
+     */
+    constructor(message, path) {
+        super(String(message));
+        this.path = path;
+    }
+}
+/**
+ * validates bankAccount fields:
+ * - iban (ISO 13616)
+ * - bic (ISO 9362)
+ */
+export function validateBankAccount(bankAccount, path) {
+    if (!validator.isIBAN(bankAccount.iban)) {
+        throw new ValidationError(ValidationErrorMessage.IBAN, `${path}.iban`);
+    }
+    if (bankAccount.bic && !validator.isBIC(bankAccount.bic)) {
+        throw new ValidationError(ValidationErrorMessage.BIC, `${path}.bic`);
+    }
+}
+/**
+ * validate simple payment fields:
+ * - currencyCode (ISO 4217)
+ * - paymentDueDate (ISO 8601)
+ * - bankAccounts
+ *
+ * @see validateBankAccount
+ */
+export function validateSimplePayment(simplePayment, path) {
+    for (const [index, bankAccount] of simplePayment.bankAccounts.entries()) {
+        validateBankAccount(bankAccount, `${path}.bankAccounts[${index}]`);
+    }
+    if (simplePayment.currencyCode && !validator.isISO4217(simplePayment.currencyCode)) {
+        throw new ValidationError(ValidationErrorMessage.CurrencyCode, `${path}.currencyCode`);
+    }
+    if (simplePayment.paymentDueDate && !validator.isDate(simplePayment.paymentDueDate)) {
+        throw new ValidationError(ValidationErrorMessage.Date, `${path}.paymentDueDate`);
+    }
+}
+/**
+ * Validate `payments` field of dataModel.
+ *
+ * @see validateSimplePayment
+ * @see ValidationError
+ */
+export function validateDataModel(dataModel) {
+    for (const [index, payment] of dataModel.payments.entries()) {
+        validateSimplePayment(payment, `payments[${index}]`);
+    }
+    return dataModel;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "bysquare",
 	"description": "It's a national standard for payment QR codes adopted by Slovak Banking Association (SBA)",
-	"version": "2.9.0",
+	"version": "2.11.0",
 	"license": "Apache-2.0",
 	"funding": "https://github.com/sponsors/xseman",
 	"homepage": "https://github.com/xseman/bysquare#readme",
@@ -20,19 +20,20 @@
 		"prebuild": "tsc --build --clean",
 		"build": "tsc --build",
 		"fmt": "dprint fmt",
+		"fmt:check": "dprint check",
 		"typecheck": "tsc --noEmit",
 		"version": "git checkout develop && npm test",
 		"postversion": "echo 'Now run npm run build && npm publish'",
-		"test": "TS_NODE_TRANSPILE_ONLY=true node --test --loader=ts-node/esm --no-warnings src/*.test.ts",
+		"test": "TS_NODE_TRANSPILE_ONLY=true node --test --experimental-test-coverage --loader=ts-node/esm --no-warnings src/*.test.ts",
 		"test:watch": "TS_NODE_TRANSPILE_ONLY=true node --test --watch --loader=ts-node/esm --no-warnings src/*.test.ts"
 	},
 	"dependencies": {
-		"crc-32": "~1.2.0",
-		"lzma1": "0.0.2",
-		"rfc4648": "~1.5.0"
+		"lzma1": "0.0.3",
+		"validator": "^13.12.0"
 	},
 	"devDependencies": {
-		"@types/node": ">=18.18.2",
+		"@types/node": "^22.5.0",
+		"@types/validator": "^13.12.0",
 		"dprint": "~0.47.0",
 		"ts-node": "~10.9.0",
 		"typescript": "~5.5.0"
@@ -51,7 +52,7 @@
 		"!dist/*.test.*"
 	],
 	"engines": {
-		"node": ">=18.18.2",
+		"node": ">=16",
 		"npm": ">=7"
 	}
 }