bysquare 2.10.0 → 2.12.0

package/README.md

@@ -1,24 +1,18 @@
 # bysquare
 
-Simple JavaScript library to encode and decode "PAY by square" string.
+"PAY by square" is a national standard for QR code payments that was adopted by
+the Slovak Banking Association in 2013. It is incorporated into a variety of
+invoices, reminders and other payment regulations.
 
-**What is `PAY by square`?**
+## What it is
 
-It's a national standard for QR code payments that was adopted by the Slovak
-Banking Association in 2013. It is incorporated into a variety of invoices,
-reminders and other payment regulations.
+- Simple JavaScript library to encode and decode "PAY by square" string.
+- Aim to support simpe programming interface to encode and decode data for QR.
 
-**Can I generate an image?**
+## What it is not
 
-This library doesn't have a specific opinion and how the QR code string is
-transformed into images depends on how you implement it. See
-[examples](./docs/examples/).
-
-## Features
-
-- Encode data to qr string
-- Decode data to json
-- Detect bysquare from qr string
+- Generating QR code images.
+- Parsing QR code images.
 
 ## Installation
 
@@ -63,59 +57,58 @@ import {
 
 ## Usage
 
-### Encode
+### Basic Usage
+
+Simple helper functions to wrap encoding for most common use cases.
+
+- `simplePayment` - Encode simple payment data.
+- `directDebit` - Encode direct debit data.
+- `standingOrder` - Encode standing order data.
+
+```typescript
+import { simplePayment } from "bysquare";
+
+const qrstring = simplePayment({
+	amount: 100,
+	variableSymbol: "123456",
+	currencyCode: CurrencyCode.EUR,
+	iban: "SK9611000000002918599669",
+});
+```
+
+### Adavanced usage
+
+For more complex data use `encode` and `decode` functions:
 
 ```ts
 import {
 	CurrencyCode,
 	DataModel,
+	decode,
 	encode,
 	PaymentOptions,
 } from "bysquare";
 
-// string ready to be encoded to QR
-const qrString = encode({
+const data = {
 	invoiceId: "random-id",
 	payments: [
 		{
 			type: PaymentOptions.PaymentOrder,
-			amount: 100.0,
-			bankAccounts: [
-				{
-					iban: "SK9611000000002918599669",
-				},
-			],
 			currencyCode: CurrencyCode.EUR,
+			amount: 100.0,
 			variableSymbol: "123",
+			paymentNote: "hello world",
+			bankAccounts: [{ iban: "SK9611000000002918599669" }],
+			// ...more fields
 		},
 	],
-});
-```
+} satisfies DataModel;
 
-### Decode
+// Encode data to a QR string
+const qrstring = encode(data);
 
-```ts
-import { decode } from "bysquare";
-
-const model = decode(
-	"0405QH8090IFU27IV0J6HGGLIOTIBVHNQQJQ6LAVGNBT363HR13JC6CB54HSI0KH9FCRASHNQBSKAQD2LJ4AU400UVKDNDPFRKLOBEVVVU0QJ000",
-);
-
-// {
-// 	invoiceId: "random-id",
-// 	payments: [
-// 		{
-// 			type: 1,
-// 			amount: 100.0,
-// 			bankAccounts: [
-// 				{ iban: "SK9611000000002918599669" },
-// 			],
-// 			currencyCode: "EUR",
-// 			variableSymbol: "123",
-// 		}
-// 	]
-// }
-//
+// Decode QR string back to the original data model
+const model = decode(qrstring);
 ```
 
 ## CLI

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/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/decode.d.ts

@@ -1,15 +1,31 @@
 import { DataModel } from "./index.js";
+export declare enum DecodeErrorMessage {
+    MissingIBAN = "IBAN is missing",
+    /**
+     * @description - find original LZMA error in extensions
+     */
+    LZMADecompressionFailed = "LZMA decompression failed",
+    /**
+     * @description - find found version in extensions
+     * @see {@link ./types#Version} for valid ranges
+     */
+    UnsupportedVersion = "Unsupported version"
+}
+export declare class DecodeError extends Error {
+    name: string;
+    extensions?: {
+        [name: string]: any;
+    };
+    constructor(message: DecodeErrorMessage, extensions?: {
+        [name: string]: any;
+    });
+}
 /**
  * Generating by square Code
  *
  * @see 3.14.
  */
 export declare function deserialize(qr: string): DataModel;
-export declare class DecodeError extends Error {
-    cause: Error;
-    name: string;
-    constructor(cause: Error, msg?: string);
-}
 /** @deprecated */
 export declare const parse: typeof decode;
 /**
@@ -21,7 +37,7 @@ export declare function decode(qr: string): DataModel;
 /**
  * Detect if qr string contains bysquare header.
  *
- * Bysquare header does not have too much information, therefore it is
- * not very reliable, there is room for improvement for the future.
+ * There is not magic header in the bysquare specification.
+ * Version is just 4 bites, so it is possible to have false positives.
  */
 export declare function detect(qr: string): boolean;

package/dist/decode.js

@@ -1,6 +1,29 @@
 import { decompress } from "lzma1";
-import { base32hex } from "rfc4648";
+import * as base32hex from "./base32hex.js";
 import { CurrencyCode, PaymentOptions, Version, } from "./index.js";
+export var DecodeErrorMessage;
+(function (DecodeErrorMessage) {
+    DecodeErrorMessage["MissingIBAN"] = "IBAN is missing";
+    /**
+     * @description - find original LZMA error in extensions
+     */
+    DecodeErrorMessage["LZMADecompressionFailed"] = "LZMA decompression failed";
+    /**
+     * @description - find found version in extensions
+     * @see {@link ./types#Version} for valid ranges
+     */
+    DecodeErrorMessage["UnsupportedVersion"] = "Unsupported version";
+})(DecodeErrorMessage || (DecodeErrorMessage = {}));
+export class DecodeError extends Error {
+    name = "DecodeError";
+    extensions;
+    constructor(message, extensions) {
+        super(message);
+        if (extensions) {
+            this.extensions = extensions;
+        }
+    }
+}
 function cleanUndefined(obj) {
     Object.keys(obj).forEach((key) => {
         if (typeof obj[key] === "undefined") {
@@ -8,6 +31,12 @@ function cleanUndefined(obj) {
         }
     });
 }
+function decodeNumber(value) {
+    return value?.length ? Number(value) : undefined;
+}
+function decodeString(value) {
+    return value?.length ? value : undefined;
+}
 /**
  * Generating by square Code
  *
@@ -26,82 +55,62 @@ export function deserialize(qr) {
         const ammount = data.shift();
         const currency = data.shift();
         const dueDate = data.shift();
-        const variables = data.shift();
-        const constants = data.shift();
-        const specifics = data.shift();
+        const variableSymbol = data.shift();
+        const constantSymbol = data.shift();
+        const specificSymbol = data.shift();
         const originatorRefInfo = data.shift();
         const paymentNote = data.shift();
         let payment = {
             bankAccounts: [],
             type: Number(paymentOptions),
             currencyCode: currency ?? CurrencyCode.EUR,
-            amount: ammount?.length
-                ? Number(ammount)
-                : undefined,
-            paymentDueDate: dueDate?.length
-                ? dueDate
-                : undefined,
-            variableSymbol: variables?.length
-                ? variables
-                : undefined,
-            constantSymbol: constants?.length
-                ? constants
-                : undefined,
-            specificSymbol: specifics?.length
-                ? specifics
-                : undefined,
-            originatorsReferenceInformation: originatorRefInfo?.length
-                ? originatorRefInfo
-                : undefined,
-            paymentNote: paymentNote?.length
-                ? paymentNote
-                : undefined,
+            amount: Number(ammount),
+            paymentDueDate: dueDate || undefined,
+            variableSymbol: variableSymbol || undefined,
+            constantSymbol: constantSymbol || undefined,
+            specificSymbol: specificSymbol || undefined,
+            originatorsReferenceInformation: originatorRefInfo || undefined,
+            paymentNote: paymentNote || undefined,
         };
-        const accountslen = Number(data.shift());
-        for (let j = 0; j < accountslen; j++) {
+        const numberOfAccounts = Number(data.shift());
+        for (let j = 0; j < numberOfAccounts; j++) {
             const iban = data.shift();
             if (iban === undefined || iban.length === 0) {
-                throw new Error("Missing IBAN");
+                throw new DecodeError(DecodeErrorMessage.MissingIBAN);
             }
             const bic = data.shift();
             const account = {
                 iban: iban,
-                bic: bic?.length
-                    ? bic
-                    : undefined,
+                bic: bic || undefined,
             };
             cleanUndefined(account);
             payment.bankAccounts.push(account);
         }
-        data.shift(); // StandingOrderExt
-        data.shift(); // DirectDebitExt
-        // narrowing payment type
-        switch (payment.type) {
-            case PaymentOptions.PaymentOrder:
-                break;
-            case PaymentOptions.StandingOrder:
-                payment = {
-                    ...payment,
-                    day: Number(data.shift()),
-                    month: Number(data.shift()),
-                    periodicity: data.shift(),
-                    lastDate: data.shift(),
-                };
-                break;
-            case PaymentOptions.DirectDebit:
-                payment = {
-                    ...payment,
-                    directDebitScheme: Number(data.shift()),
-                    directDebitType: Number(data.shift()),
-                    mandateId: data.shift(),
-                    creditorId: data.shift(),
-                    contractId: data.shift(),
-                    maxAmount: Number(data.shift()),
-                    validTillDate: data.shift(),
-                };
-                break;
-            default:
-                break;
+        const standingOrderExt = data.shift();
+        if (standingOrderExt === "1" && payment.type === PaymentOptions.StandingOrder) {
+            payment = {
+                ...payment,
+                day: decodeNumber(data.shift()),
+                month: decodeNumber(data.shift()),
+                periodicity: decodeString(data.shift()),
+                lastDate: decodeString(data.shift()),
+            };
+        }
+        const directDebitExt = data.shift();
+        if (directDebitExt === "1" && payment.type === PaymentOptions.DirectDebit) {
+            payment = {
+                ...payment,
+                directDebitScheme: decodeNumber(data.shift()),
+                directDebitType: decodeNumber(data.shift()),
+                variableSymbol: decodeString(data.shift()),
+                specificSymbol: decodeString(data.shift()),
+                originatorsReferenceInformation: decodeString(data.shift()),
+                mandateId: decodeString(data.shift()),
+                creditorId: decodeString(data.shift()),
+                contractId: decodeString(data.shift()),
+                maxAmount: decodeNumber(data.shift()),
+                validTillDate: decodeString(data.shift()),
+            };
         }
         cleanUndefined(payment);
         output.payments.push(payment);
@@ -112,15 +121,9 @@ export function deserialize(qr) {
         const addressLine2 = data.shift();
         if (Boolean(name) || Boolean(addressLine1) || Boolean(addressLine2)) {
             const beneficiary = {
-                name: name?.length
-                    ? name
-                    : undefined,
-                street: addressLine1?.length
-                    ? addressLine1
-                    : undefined,
-                city: addressLine2?.length
-                    ? addressLine2
-                    : undefined,
+                name: name || undefined,
+                street: addressLine1 || undefined,
+                city: addressLine2 || undefined,
             };
             cleanUndefined(beneficiary);
             output.payments[i].beneficiary = beneficiary;
@@ -148,14 +151,6 @@ function bysquareHeaderDecoder(header) {
         reserved,
     };
 }
-export class DecodeError extends Error {
-    cause;
-    name = "DecodeError";
-    constructor(cause, msg) {
-        super(msg);
-        this.cause = cause;
-    }
-}
 /** @deprecated */
 export const parse = decode;
 /**
@@ -164,17 +159,13 @@ 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);
     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`);
+        throw new DecodeError(DecodeErrorMessage.UnsupportedVersion, {
+            version: decodedBysquareHeader.version,
+        });
     }
     /**
      * The process of decompressing data requires the addition of an LZMA header
@@ -182,11 +173,13 @@ export function decode(qr) {
      * algorithm to properly interpret and extract the original uncompressed
      * data. Bysquare only store properties
      *
-     * <----------------------- 13-bytes ----------------------->
+     * @see https://docs.fileformat.com/compression/lzma/
      *
-     * +------------+----+----+----+----+--+--+--+--+--+--+--+--+
-     * | Properties |  Dictionary Size  |   Uncompressed Size   |
-     * +------------+----+----+----+----+--+--+--+--+--+--+--+--+
+     * +---------------+---------------------------+-------------------+
+     * |      1B       |           4B              |         8B        |
+     * +---------------+---------------------------+-------------------+
+     * | Properties    | Dictionary Size           | Uncompressed Size |
+     * +---------------+---------------------------+-------------------+
      */
     const defaultProperties = [0x5D]; // lc=3, lp=0, pb=2
     const defaultDictionarySize = [0x00, 0x02, 0x00, 0x00]; // 2^17
@@ -207,7 +200,7 @@ export function decode(qr) {
         decompressed = decompress(body);
     }
     catch (error) {
-        throw new DecodeError(error, "LZMA decompression failed");
+        throw new DecodeError(DecodeErrorMessage.LZMADecompressionFailed, { error });
     }
     if (typeof decompressed === "string") {
         return deserialize(decompressed);
@@ -220,21 +213,21 @@ export function decode(qr) {
 /**
  * Detect if qr string contains bysquare header.
  *
- * Bysquare header does not have too much information, therefore it is
- * not very reliable, there is room for improvement for the future.
+ * There is not magic header in the bysquare specification.
+ * Version is just 4 bites, so it is possible to have false positives.
  */
 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

@@ -1,4 +1,38 @@
 import { DataModel } from "./types.js";
+export declare enum EncodeErrorMessage {
+    /**
+     * @description - find invalid value in extensions
+     */
+    BySquareType = "Invalid BySquareType value in header, valid range <0,15>",
+    /**
+     * @description - find invalid value in extensions
+     * @see {@link ./types#Version} for valid ranges
+     */
+    Version = "Invalid Version value in header",
+    /**
+     * @description - find invalid value in extensions
+     */
+    DocumentType = "Invalid DocumentType value in header, valid range <0,15>",
+    /**
+     * @description - find invalid value in extensions
+     */
+    Reserved = "Invalid Reserved value in header, valid range <0,15>",
+    /**
+     * @description - find actual size of header in extensions
+     * @see MAX_COMPRESSED_SIZE
+     */
+    HeaderDataSize = "Allowed header data size exceeded"
+}
+export declare class EncodeError extends Error {
+    name: string;
+    extensions?: {
+        [name: string]: any;
+    };
+    constructor(message: EncodeErrorMessage, extensions?: {
+        [name: string]: any;
+    });
+}
+export declare const MAX_COMPRESSED_SIZE = 131072;
 /**
  * Returns a 2 byte buffer that represents the header of the bysquare
  * specification
@@ -40,6 +74,7 @@ export declare function addChecksum(serialized: string): Uint8Array;
  * @see Table 15.
  */
 export declare function serialize(data: DataModel): string;
+export declare function removeDiacritics(model: DataModel): void;
 type Options = {
     /**
      * Many banking apps do not support diacritics, which results in errors when

package/dist/encode.js

@@ -1,10 +1,45 @@
-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, Version, } from "./types.js";
 import { validateDataModel } from "./validations.js";
-const MAX_COMPRESSED_SIZE = 131_072; // 2^17
+export var EncodeErrorMessage;
+(function (EncodeErrorMessage) {
+    /**
+     * @description - find invalid value in extensions
+     */
+    EncodeErrorMessage["BySquareType"] = "Invalid BySquareType value in header, valid range <0,15>";
+    /**
+     * @description - find invalid value in extensions
+     * @see {@link ./types#Version} for valid ranges
+     */
+    EncodeErrorMessage["Version"] = "Invalid Version value in header";
+    /**
+     * @description - find invalid value in extensions
+     */
+    EncodeErrorMessage["DocumentType"] = "Invalid DocumentType value in header, valid range <0,15>";
+    /**
+     * @description - find invalid value in extensions
+     */
+    EncodeErrorMessage["Reserved"] = "Invalid Reserved value in header, valid range <0,15>";
+    /**
+     * @description - find actual size of header in extensions
+     * @see MAX_COMPRESSED_SIZE
+     */
+    EncodeErrorMessage["HeaderDataSize"] = "Allowed header data size exceeded";
+})(EncodeErrorMessage || (EncodeErrorMessage = {}));
+export class EncodeError extends Error {
+    name = "EncodeError";
+    extensions;
+    constructor(message, extensions) {
+        super(message);
+        if (extensions) {
+            this.extensions = extensions;
+        }
+    }
+}
+export const MAX_COMPRESSED_SIZE = 131_072; // 2^17
 /**
  * Returns a 2 byte buffer that represents the header of the bysquare
  * specification
@@ -27,16 +62,16 @@ header = [
     0x00, 0x00
 ]) {
     if (header[0] < 0 || header[0] > 15) {
-        throw new Error(`Invalid BySquareType value '${header[0]}' in header, valid range <0,15>`);
+        throw new EncodeError(EncodeErrorMessage.BySquareType, { invalidValue: header[0] });
     }
     if (header[1] < 0 || header[1] > 15) {
-        throw new Error(`Invalid Version value '${header[1]}' in header, valid range <0,15>`);
+        throw new EncodeError(EncodeErrorMessage.Version, { invalidValue: header[1] });
     }
     if (header[2] < 0 || header[2] > 15) {
-        throw new Error(`Invalid DocumentType value '${header[2]}' in header, valid range <0,15>`);
+        throw new EncodeError(EncodeErrorMessage.DocumentType, { invalidValue: header[2] });
     }
     if (header[3] < 0 || header[3] > 15) {
-        throw new Error(`Invalid Reserved value '${header[3]}' in header, valid range <0,15>`);
+        throw new EncodeError(EncodeErrorMessage.Reserved, { invalidValue: header[3] });
     }
     const [bySquareType, version, documentType, reserved,] = header;
     // Combine 4-nibbles to 2-bytes
@@ -52,7 +87,10 @@ header = [
  */
 export function headerDataLength(length) {
     if (length >= MAX_COMPRESSED_SIZE) {
-        throw new Error(`Data size ${length} exceeds limit of ${MAX_COMPRESSED_SIZE} bytes`);
+        throw new EncodeError(EncodeErrorMessage.HeaderDataSize, {
+            actualSize: length,
+            allowedSize: MAX_COMPRESSED_SIZE,
+        });
     }
     const header = new ArrayBuffer(2);
     new DataView(header).setUint16(0, length, true);
@@ -65,7 +103,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),
@@ -131,7 +169,7 @@ export function serialize(data) {
     }
     return serialized.join("\t");
 }
-function removeDiacritics(model) {
+export function removeDiacritics(model) {
     for (const payment of model.payments) {
         if (payment.paymentNote) {
             payment.paymentNote = deburr(payment.paymentNote);
@@ -161,19 +199,29 @@ export function encode(model, options) {
         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 payloadChecked = addChecksum(payload);
+    const payloadCompressed = Uint8Array.from(compress(payloadChecked));
+    /**
+     * The LZMA files has a 13-byte header that is followed by the LZMA
+     * compressed data.
+     *
+     * @see https://docs.fileformat.com/compression/lzma/
+     *
+     * +---------------+---------------------------+-------------------+
+     * |      1B       |           4B              |         8B        |
+     * +---------------+---------------------------+-------------------+
+     * | Properties    | Dictionary Size           | Uncompressed Size |
+     * +---------------+---------------------------+-------------------+
+     */
+    const _lzmaHeader = Uint8Array.from(payloadCompressed.subarray(0, 13));
+    const lzmaBody = Uint8Array.from(payloadCompressed.subarray(13));
     const output = Uint8Array.from([
         // 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, Version["1.0.0"], 0x00, 0x00]),
-        ...headerDataLength(withChecksum.byteLength),
+        ...headerDataLength(payloadChecked.byteLength),
         ...lzmaBody,
     ]);
-    return base32hex.stringify(output, {
-        pad: false,
-    });
+    return base32hex.encode(output, false);
 }

package/dist/helpers.d.ts

@@ -0,0 +1,16 @@
+import { type BankAccount, SimplePayment, type StandingOrder } from "./types.js";
+type PaymentInput = Pick<BankAccount, "iban"> & Pick<SimplePayment, "amount" | "currencyCode" | "variableSymbol">;
+/**
+ * Vytvorí QR pre jednorázovú platbu
+ */
+export declare function simplePayment(input: PaymentInput): string;
+/**
+ * Vytvorí QR pre inkaso
+ */
+export declare function directDebit(input: PaymentInput): string;
+type StandingInput = PaymentInput & Pick<StandingOrder, "day" | "periodicity">;
+/**
+ * Vytvorí QR pre trvalý príkaz
+ */
+export declare function standingOrder(input: StandingInput): string;
+export {};

package/dist/helpers.js

@@ -0,0 +1,52 @@
+import { encode } from "./encode.js";
+import { CurrencyCode, PaymentOptions, } from "./types.js";
+/**
+ * Vytvorí QR pre jednorázovú platbu
+ */
+export function simplePayment(input) {
+    return encode({
+        payments: [
+            {
+                type: PaymentOptions.PaymentOrder,
+                amount: input.amount,
+                variableSymbol: input.variableSymbol,
+                currencyCode: CurrencyCode.EUR,
+                bankAccounts: [{ iban: input.iban }],
+            },
+        ],
+    });
+}
+/**
+ * Vytvorí QR pre inkaso
+ */
+export function directDebit(input) {
+    return encode({
+        payments: [
+            {
+                type: PaymentOptions.DirectDebit,
+                amount: input.amount,
+                variableSymbol: input.variableSymbol,
+                currencyCode: CurrencyCode.EUR,
+                bankAccounts: [{ iban: input.iban }],
+            },
+        ],
+    });
+}
+/**
+ * Vytvorí QR pre trvalý príkaz
+ */
+export function standingOrder(input) {
+    return encode({
+        payments: [
+            {
+                type: PaymentOptions.StandingOrder,
+                day: input.day,
+                periodicity: input.periodicity,
+                amount: input.amount,
+                variableSymbol: input.variableSymbol,
+                currencyCode: CurrencyCode.EUR,
+                bankAccounts: [{ iban: input.iban }],
+            },
+        ],
+    });
+}

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/test_assets.d.ts

@@ -0,0 +1,43 @@
+import { CurrencyCode, PaymentOptions, Periodicity } from "./types.js";
+export declare const payloadWithPaymentOrder: {
+    invoiceId: string;
+    payments: {
+        type: PaymentOptions.PaymentOrder;
+        amount: number;
+        bankAccounts: {
+            iban: string;
+        }[];
+        currencyCode: CurrencyCode;
+        variableSymbol: string;
+    }[];
+};
+export declare const serializedPaymentOrder: string;
+export declare const payloadWithStandingOrder: {
+    invoiceId: string;
+    payments: {
+        type: PaymentOptions.StandingOrder;
+        amount: number;
+        bankAccounts: {
+            iban: string;
+        }[];
+        periodicity: Periodicity.Monthly;
+        currencyCode: CurrencyCode;
+        variableSymbol: string;
+        lastDate: string;
+        day: number;
+    }[];
+};
+export declare const serializedStandingOrder: string;
+export declare const payloadWithDirectDebit: {
+    invoiceId: string;
+    payments: {
+        type: PaymentOptions.DirectDebit;
+        amount: number;
+        bankAccounts: {
+            iban: string;
+        }[];
+        currencyCode: CurrencyCode;
+        variableSymbol: string;
+    }[];
+};
+export declare const serializedDirectDebit: string;

package/dist/test_assets.js

@@ -0,0 +1,123 @@
+import { CurrencyCode, PaymentOptions, Periodicity, } from "./types.js";
+export const payloadWithPaymentOrder = {
+    invoiceId: "random-id",
+    payments: [
+        {
+            type: PaymentOptions.PaymentOrder,
+            amount: 100.0,
+            bankAccounts: [
+                { iban: "SK9611000000002918599669" },
+            ],
+            currencyCode: CurrencyCode.EUR,
+            variableSymbol: "123",
+        },
+    ],
+};
+export const serializedPaymentOrder = /** dprint-ignore */ [
+    "random-id",
+    "\t", "1",
+    "\t", "1",
+    "\t", "100",
+    "\t", "EUR",
+    "\t",
+    "\t", "123",
+    "\t",
+    "\t",
+    "\t",
+    "\t",
+    "\t", "1",
+    "\t", "SK9611000000002918599669",
+    "\t",
+    "\t", "0",
+    "\t", "0",
+    "\t",
+    "\t",
+    "\t",
+].join("");
+export const payloadWithStandingOrder = {
+    invoiceId: "random-id",
+    payments: [
+        {
+            type: PaymentOptions.StandingOrder,
+            amount: 100.0,
+            bankAccounts: [
+                { iban: "SK9611000000002918599669" },
+            ],
+            periodicity: Periodicity.Monthly,
+            currencyCode: CurrencyCode.EUR,
+            variableSymbol: "123",
+            lastDate: "20241011",
+            day: 1,
+        },
+    ],
+};
+export const serializedStandingOrder = /** dprint-ignore */ [
+    "random-id",
+    "\t", "1",
+    "\t", "2",
+    "\t", "100",
+    "\t", "EUR",
+    "\t",
+    "\t", "123",
+    "\t",
+    "\t",
+    "\t",
+    "\t",
+    "\t", "1",
+    "\t", "SK9611000000002918599669",
+    "\t",
+    "\t", "1",
+    "\t", "1",
+    "\t",
+    "\t", "m",
+    "\t", "20241011",
+    "\t", "0",
+    "\t",
+    "\t",
+    "\t",
+].join("");
+export const payloadWithDirectDebit = {
+    invoiceId: "random-id",
+    payments: [
+        {
+            type: PaymentOptions.DirectDebit,
+            amount: 100.0,
+            bankAccounts: [
+                { iban: "SK9611000000002918599669" },
+            ],
+            currencyCode: CurrencyCode.EUR,
+            variableSymbol: "123",
+        },
+    ],
+};
+export const serializedDirectDebit = /** dprint-ignore */ [
+    "random-id",
+    "\t", "1",
+    "\t", "4",
+    "\t", "100",
+    "\t", "EUR",
+    "\t",
+    "\t", "123",
+    "\t",
+    "\t",
+    "\t",
+    "\t",
+    "\t", "1",
+    "\t", "SK9611000000002918599669",
+    "\t",
+    "\t", "0",
+    "\t", "1",
+    "\t",
+    "\t",
+    "\t", "123",
+    "\t",
+    "\t",
+    "\t",
+    "\t",
+    "\t",
+    "\t",
+    "\t",
+    "\t",
+    "\t",
+    "\t",
+].join("");

package/dist/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/base32hex.test.ts","../src/base32hex.ts","../src/cli.ts","../src/crc32.test.ts","../src/crc32.ts","../src/deburr.test.ts","../src/deburr.ts","../src/decode.test.ts","../src/decode.ts","../src/encode.test.ts","../src/encode.ts","../src/helper.test.ts","../src/helpers.ts","../src/index.ts","../src/test_assets.ts","../src/types.ts","../src/validations.test.ts","../src/validations.ts"],"version":"5.6.2"}

package/dist/types.d.ts

@@ -248,7 +248,7 @@ export type StandingOrder = SimplePayment & {
     /**
      * Opakovanie (periodicita) trvalého príkazu.
      */
-    periodicity?: Periodicity;
+    periodicity: Periodicity;
     /**
      * Dátum poslednej platby v trvalom príkaze.
      *

package/dist/validations.js

@@ -17,7 +17,7 @@ export class ValidationError extends Error {
      * @param path - navigates to the specific field in DataModel, where error occurred
      */
     constructor(message, path) {
-        super(String(message));
+        super(message);
         this.path = path;
     }
 }

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.10.0",
+	"version": "2.12.0",
 	"license": "Apache-2.0",
 	"funding": "https://github.com/sponsors/xseman",
 	"homepage": "https://github.com/xseman/bysquare#readme",
@@ -24,21 +24,19 @@
 		"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.7.0",
 		"@types/validator": "^13.12.0",
 		"dprint": "~0.47.0",
 		"ts-node": "~10.9.0",
-		"typescript": "~5.5.0"
+		"typescript": "~5.6.0"
 	},
 	"type": "module",
 	"bin": "./dist/cli.js",
@@ -54,7 +52,7 @@
 		"!dist/*.test.*"
 	],
 	"engines": {
-		"node": ">=18.18.2",
+		"node": ">=16",
 		"npm": ">=7"
 	}
 }