bysquare 2.12.4 → 2.12.5

package/lib/base32hex.d.ts

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

package/lib/decode.d.ts

@@ -31,6 +31,7 @@ export declare const parse: typeof decode;
  * Decoding client data from QR Code 2005 symbol
  *
  * @see 3.16.
+ * @param qr base32hex encoded bysqaure binary data
  */
 export declare function decode(qr: string): DataModel;
 /**
@@ -38,5 +39,7 @@ export declare function decode(qr: string): DataModel;
  *
  * There is not magic header in the bysquare specification.
  * Version is just 4 bites, so it is possible to have false positives.
+ *
+ * @deprecated Will be removed as of v3.
  */
 export declare function detect(qr: string): boolean;

package/lib/decode.js

@@ -60,7 +60,6 @@ export function deserialize(qr) {
         const originatorRefInfo = data.shift();
         const paymentNote = data.shift();
         let payment = {
-            bankAccounts: [],
             type: Number(paymentOptions),
             currencyCode: currency ?? CurrencyCode.EUR,
             amount: Number(ammount),
@@ -70,6 +69,7 @@ export function deserialize(qr) {
             specificSymbol: specificSymbol || undefined,
             originatorsReferenceInformation: originatorRefInfo || undefined,
             paymentNote: paymentNote || undefined,
+            bankAccounts: [],
         };
         const numberOfAccounts = Number(data.shift());
         for (let j = 0; j < numberOfAccounts; j++) {
@@ -156,14 +156,15 @@ export const parse = decode;
  * Decoding client data from QR Code 2005 symbol
  *
  * @see 3.16.
+ * @param qr base32hex encoded bysqaure binary data
  */
 export function decode(qr) {
     const bytes = base32hex.decode(qr);
-    const bysquareHeader = bytes.slice(0, 2);
-    const decodedBysquareHeader = bysquareHeaderDecoder(bysquareHeader);
-    if ((decodedBysquareHeader.version > Version["1.1.0"])) {
+    const headerBytes = bytes.slice(0, 2);
+    const headerData = bysquareHeaderDecoder(headerBytes);
+    if ((headerData.version > Version["1.1.0"])) {
         throw new DecodeError(DecodeErrorMessage.UnsupportedVersion, {
-            version: decodedBysquareHeader.version,
+            version: headerData.version,
         });
     }
     /**
@@ -181,14 +182,22 @@ export function decode(qr) {
      * +---------------+---------------------------+-------------------+
      */
     const defaultProperties = [0x5D]; // lc=3, lp=0, pb=2
-    const defaultDictionarySize = [0x00, 0x02, 0x00, 0x00]; // 2^17
+    const defaultDictionarySize = [0x00, 0x00, 0x20, 0x00]; // 2^21 = 2097152
+    // Parse the payload length from bytes 2-3 and properly expand to 8-byte uncompressed size
+    const payloadLengthBytes = bytes.slice(2, 4);
+    const payloadLength = payloadLengthBytes[0] | (payloadLengthBytes[1] << 8);
     const uncompressedSize = new Uint8Array(8);
-    uncompressedSize.set(bytes.slice(2, 4));
-    const header = new Uint8Array([
+    // Set the full 32-bit value in little-endian format
+    uncompressedSize[0] = payloadLength & 0xFF;
+    uncompressedSize[1] = (payloadLength >> 8) & 0xFF;
+    uncompressedSize[2] = (payloadLength >> 16) & 0xFF;
+    uncompressedSize[3] = (payloadLength >> 24) & 0xFF;
+    // Bytes 4-7 remain 0 for sizes < 2^32
+    const header = [
         ...defaultProperties,
         ...defaultDictionarySize,
         ...uncompressedSize,
-    ]);
+    ];
     const payload = bytes.slice(4);
     const body = new Uint8Array([
         ...header,
@@ -201,9 +210,12 @@ export function decode(qr) {
     catch (error) {
         throw new DecodeError(DecodeErrorMessage.LZMADecompressionFailed, { error });
     }
-    if (typeof decompressed === "string") {
-        return deserialize(decompressed);
+    if (!decompressed) {
+        throw new DecodeError(DecodeErrorMessage.LZMADecompressionFailed, {
+            error: "Decompression returned undefined",
+        });
     }
+    // Extract checksum and body
     const _checksum = decompressed.slice(0, 4);
     const decompressedBody = decompressed.slice(4);
     const decoded = new TextDecoder("utf-8").decode(decompressedBody.buffer);
@@ -214,6 +226,8 @@ export function decode(qr) {
  *
  * There is not magic header in the bysquare specification.
  * Version is just 4 bites, so it is possible to have false positives.
+ *
+ * @deprecated Will be removed as of v3.
  */
 export function detect(qr) {
     let decoded;

package/lib/encode.d.ts

@@ -47,25 +47,25 @@ export declare const MAX_COMPRESSED_SIZE = 131072;
  *
  * @see 3.5.
  */
-export declare function headerBysquare(
+export declare function buildBysquareHeader(
 /** dprint-ignore */
 header?: [
     bySquareType: number,
     version: number,
     documentType: number,
     reserved: number
-]): Uint8Array;
+]): number[];
 /**
- * Creates a one-byte array that represents the length of compressed data in
+ * Creates a 2-byte array that represents the length of compressed data in
  * combination with CRC32 in bytes.
  */
-export declare function headerDataLength(length: number): Uint8Array;
+export declare function buildPayloadLength(length: number): Uint8Array;
 /**
  * Transfer object to a tabbed string and append a CRC32 checksum
  *
  * @see 3.10.
  */
-export declare function addChecksum(serialized: string): Uint8Array;
+export declare function addChecksum(tabbedPayload: string): Uint8Array;
 /**
  * Transform data to ordered tab-separated intermediate representation ready for
  * encoding
@@ -93,6 +93,12 @@ type Options = {
 export declare const generate: typeof encode;
 /**
  * Generate QR string ready for encoding into text QR code
+ *
+ * @param model - Data model to encode
+ * @param options - Options for encoding
+ *
+ * @default options.deburr - true
+ * @default options.validate - true
  */
 export declare function encode(model: DataModel, options?: Options): string;
 export {};

package/lib/encode.js

@@ -54,7 +54,7 @@ export const MAX_COMPRESSED_SIZE = 131_072; // 2^17
  *
  * @see 3.5.
  */
-export function headerBysquare(
+export function buildBysquareHeader(
 /** dprint-ignore */
 header = [
     0x00, 0x00,
@@ -74,17 +74,17 @@ header = [
     }
     const [bySquareType, version, documentType, reserved,] = header;
     // Combine 4-nibbles to 2-bytes
-    const mergedNibbles = Uint8Array.from([
+    const mergedNibbles = [
         (bySquareType << 4) | (version << 0),
         (documentType << 4) | (reserved << 0),
-    ]);
+    ];
     return mergedNibbles;
 }
 /**
- * Creates a one-byte array that represents the length of compressed data in
+ * Creates a 2-byte array that represents the length of compressed data in
  * combination with CRC32 in bytes.
  */
-export function headerDataLength(length) {
+export function buildPayloadLength(length) {
     if (length >= MAX_COMPRESSED_SIZE) {
         throw new EncodeError(EncodeErrorMessage.HeaderDataSize, {
             actualSize: length,
@@ -100,10 +100,10 @@ export function headerDataLength(length) {
  *
  * @see 3.10.
  */
-export function addChecksum(serialized) {
+export function addChecksum(tabbedPayload) {
     const checksum = new ArrayBuffer(4);
-    new DataView(checksum).setUint32(0, crc32(serialized), true);
-    const byteArray = new TextEncoder().encode(serialized);
+    new DataView(checksum).setUint32(0, crc32(tabbedPayload), true);
+    const byteArray = new TextEncoder().encode(tabbedPayload);
     return Uint8Array.from([
         ...new Uint8Array(checksum),
         ...Uint8Array.from(byteArray),
@@ -188,22 +188,33 @@ export function removeDiacritics(model) {
 export const generate = encode;
 /**
  * Generate QR string ready for encoding into text QR code
+ *
+ * @param model - Data model to encode
+ * @param options - Options for encoding
+ *
+ * @default options.deburr - true
+ * @default options.validate - true
  */
-export function encode(model, options) {
-    const { deburr = true, validate = true } = options ?? {};
-    if (deburr) {
+export function encode(model, options = { deburr: true, validate: true }) {
+    if (options.deburr) {
         removeDiacritics(model);
     }
-    if (validate) {
+    if (options.validate) {
         validateDataModel(model);
     }
-    const payload = serialize(model);
-    const payloadChecked = addChecksum(payload);
-    const payloadCompressed = Uint8Array.from(compress(payloadChecked));
+    const payloadTabbed = serialize(model);
+    const payloadChecked = addChecksum(payloadTabbed);
+    const payloadCompressed = compress(payloadChecked);
     /**
+     * Header is ommited, the bysquare doesn't include it in the output
+     *
+     * ---
      * The LZMA files has a 13-byte header that is followed by the LZMA
      * compressed data.
      *
+     * NOTE: We use a custom compression function that sets dictionary size to 2^17
+     * This is required for compatibility with existing QR codes
+     *
      * @see https://docs.fileformat.com/compression/lzma/
      *
      * +---------------+---------------------------+-------------------+
@@ -212,14 +223,14 @@ export function encode(model, options) {
      * | Properties    | Dictionary Size           | Uncompressed Size |
      * +---------------+---------------------------+-------------------+
      */
-    const _lzmaHeader = Uint8Array.from(payloadCompressed.subarray(0, 13));
-    const lzmaBody = Uint8Array.from(payloadCompressed.subarray(13));
-    const output = Uint8Array.from([
+    const _lzmaHeader = payloadCompressed.subarray(0, 13);
+    const lzmaBody = payloadCompressed.subarray(13);
+    const output = new Uint8Array([
         // 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(payloadChecked.byteLength),
+        ...buildBysquareHeader([0x00, Version["1.0.0"], 0x00, 0x00]),
+        ...buildPayloadLength(payloadChecked.byteLength),
         ...lzmaBody,
     ]);
     return base32hex.encode(output, false);

package/lib/types.d.ts

@@ -62,7 +62,7 @@ export type Periodicity = typeof Periodicity[keyof typeof Periodicity];
  * either day of the month (number between 1 and 31) or day of the week
  * (1=Monday,2=Tuesday, …, 7=Sunday).
  *
- * Maximálna dĺžka 2
+ * @maximum 2
  */
 export type Day = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31;
 /**
@@ -95,11 +95,9 @@ 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}`
-     *
      * @example `"SK8209000000000011424060"`
+     * @maximum 34
+     * @pattern [A-Z]{2}[0-9]{2}[A-Z0-9]{0,30}
      */
     iban: string;
     /**
@@ -107,9 +105,8 @@ export type BankAccount = {
      *
      * 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"
+     * @pattern [A-Z]{4}[A-Z]{2}[A-Z\d]{2}([A-Z\d]{3})?
      */
     bic?: string;
 };
@@ -133,7 +130,7 @@ export type DirectDebitScheme = typeof DirectDebitScheme[keyof typeof DirectDebi
 /**
  * Typ inkasa. Uvádza ja jedna z možností:
  *
- * Maximálna dĺžka 1
+ * @maximum 1
  *
  * - one-off - jednorázové inkaso
  * - recurrent - opakované inkaso
@@ -153,19 +150,19 @@ export type Beneficiary = {
     /**
      * Rozšírenie o meno príjemcu
      *
-     * Maximálna dĺžka 70
+     * @maximum 70
      */
     name?: string;
     /**
      * Rozšírenie o adresu príjemcu
      *
-     * Maximálna dĺžka 70
+     * @maximum 70
      */
     street?: string;
     /**
      * Rozšírenie o adresu príjemcu (druhý riadok)
      *
-     * Maximálna dĺžka 70
+     * @maximum 70
      */
     city?: string;
 };
@@ -179,15 +176,14 @@ export type SimplePayment = {
      * 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
+     * @maximum 15
      */
     amount?: number;
     /**
      * Mena v [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) formáte (3 písmená).
      *
-     * Pattern: [A-Z]{3}
-     *
      * @example "EUR"
+     * @pattern [A-Z]{3}
      */
     currencyCode: string | keyof typeof CurrencyCode;
     /**
@@ -200,35 +196,35 @@ export type SimplePayment = {
     /**
      * Variabilný symbol je maximálne 10 miestne číslo.
      *
-     * Maximálna dĺžka 10
-     * Pattern: [0-9]{0,10}
+     * @maximum 10
+     * @pattern [0-9]{0,10}
      */
     variableSymbol?: string;
     /**
      * Konštantný symbol je 4 miestne identifikačné číslo.
      *
-     * Maximálna dĺžka 4
-     * Pattern: [0-9]{0,4}
+     * @maximum 4
+     * @pattern [0-9]{0,4}
      */
     constantSymbol?: string;
     /**
      * Špecifický symbol je maximálne 10 miestne číslo.
      *
-     * Maximálna dĺžka 10
-     * Pattern: [0-9]{0,10}
+     * @maximum 10
+     * @pattern [0-9]{0,10}
      */
     specificSymbol?: string;
     /**
      * Referenčná informácia prijímateľa podľa SEPA.
      *
-     * Maximálna dĺžka 35
+     * @maximum 35
      */
     originatorsReferenceInformation?: string;
     /**
      * Správa pre prijímateľa. Údaje o platbe, na základe ktorých príjemca bude
      * môcť platbu identifikovať.
      *
-     * Maximálna dĺžka 140
+     * @maximum 140
      */
     paymentNote?: string;
     /**
@@ -276,31 +272,31 @@ export type DirectDebit = SimplePayment & {
     /**
      * Identifikácia mandátu medzi veriteľom a dlžníkom podľa SEPA.
      *
-     * Maximálna dĺžka 35
+     * @maximum 35
      */
     mandateId?: string;
     /**
      * Identifikácia veriteľa podľa SEPA.
      *
-     * Maximálna dĺžka 35
+     * @maximum 35
      */
     creditorId?: string;
     /**
      * Identifikácia zmluvy medzi veriteľom a dlžníkom podľa SEPA.
      *
-     * Maximálna dĺžka 35
+     * @maximum 35
      */
     contractId?: string;
     /**
      * Maximálna čiastka inkasa.
      *
-     * Maximálna dĺžka 15
+     * @maximum 15
      */
     maxAmount?: number;
     /**
      * Dátum platnosti inkasa. Platnosť inkasa zaníka dňom tohto dátumu.
      *
-     * Maximálna dĺžka 8
+     * @maximum 8
      * Formát `YYYYMMDD`
      */
     validTillDate?: string;
@@ -314,7 +310,7 @@ export type DataModel = {
      * Čí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
+     * @maximum 10
      */
     invoiceId?: string;
     /**

package/lib/types.js

@@ -95,7 +95,7 @@ export const DirectDebitScheme = {
 /**
  * Typ inkasa. Uvádza ja jedna z možností:
  *
- * Maximálna dĺžka 1
+ * @maximum 1
  *
  * - one-off - jednorázové inkaso
  * - recurrent - opakované inkaso

package/package.json

@@ -2,7 +2,7 @@
 	"name": "bysquare",
 	"description": "It's a national standard for payment QR codes adopted by Slovak Banking Association (SBA)",
 	"type": "module",
-	"version": "2.12.4",
+	"version": "2.12.5",
 	"license": "Apache-2.0",
 	"funding": "https://github.com/sponsors/xseman",
 	"homepage": "https://github.com/xseman/bysquare#readme",
@@ -22,18 +22,19 @@
 		"fmt": "dprint fmt",
 		"fmt:check": "dprint check",
 		"typecheck": "tsc --noEmit",
-		"test": "bun test --coverage ./src/*.test.ts",
-		"test:watch": "bun test --watch --coverage ./src/*.test.ts"
+		"test": "bun test --coverage .",
+		"test:watch": "bun test --watch --coverage ."
 	},
 	"dependencies": {
-		"lzma1": "0.0.3",
+		"lzma1": "0.1.2",
 		"validator": "^13.12.0"
 	},
 	"devDependencies": {
-		"@types/node": "^22.7.0",
-		"@types/validator": "^13.12.0",
-		"dprint": "~0.49.0",
-		"typescript": "~5.8.0"
+		"@types/bun": "^1.2.19",
+		"@types/node": "^24.1.0",
+		"@types/validator": "^13.15.2",
+		"dprint": "~0.50.0",
+		"typescript": "~5.8.3"
 	},
 	"bin": "./lib/cli.js",
 	"exports": {