bysquare 3.0.0 → 3.2.0

package/README.md

@@ -1,22 +1,30 @@
 <h1 align="center">bysquare</h1>
 
 <p align="center">
-"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.
+	"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.
 </p>
 
-## Why
-
-It's simple, I couldn't find any implementation of "PAY by square" standard for
-JavaScript, so I decided to create one and share it with the community to help
-individuals and businesses to create QR codes for their invoices.
+<p align="center">
+	<a href="#features">Features</a> •
+	<a href="#installation">Installation</a> •
+	<a href="#usage">Usage</a> •
+	<a href="#cli">CLI</a> •
+	<a href="#validation">Validation</a>
+</p>
 
 ## Features
 
 - TypeScript support
+- CLI tooling
 - Compatible with Slovak banking apps
-- Isomorphic Browser & Runtime-independent implementation
+- Isomorphic Browser & Runtime-independent (Browser, Node.js, Bun, Deno)
+
+> [!NOTE]
+> Since v3, the implementation is considered stable and specification-complete.\
+> No breaking changes are planned. Only minor improvements and bug fixes may be
+> introduced.
 
 ## Installation
 
@@ -34,13 +42,11 @@ $ npm install bysquare
 </script>
 ```
 
-## Quick start
+## Usage
 
 This library provides `encode` and `decode` functions to work with the data
 model directly, allowing you to create customized payment solutions.
 
-### Guides
-
 ### HTML example
 
 This example shows how to generate a payment QR code and display it in a web
@@ -67,9 +73,8 @@ page:
 						amount: 123.45,
 						variableSymbol: "987654",
 						currencyCode: CurrencyCode.EUR,
-						bankAccounts: [
-							{ iban: "SK9611000000002918599669" }
-						],
+						beneficiary: { name: "John Doe" },
+						bankAccounts: [{ iban: "SK9611000000002918599669" }],
 					},
 				],
 			});
@@ -102,9 +107,8 @@ const qrstring = encode({
 			amount: 50.75,
 			variableSymbol: "123456",
 			currencyCode: CurrencyCode.EUR, // "EUR"
-			bankAccounts: [
-				{ iban: "SK9611000000002918599669" },
-			],
+			beneficiary: { name: "John Doe" },
+			bankAccounts: [{ iban: "SK9611000000002918599669" }],
 		},
 	],
 });
@@ -120,9 +124,8 @@ const qrstring = encode({
 			day: 15,
 			month: Month.January, // Single month
 			periodicity: Periodicity.Monthly, // "m"
-			bankAccounts: [
-				{ iban: "SK9611000000002918599669" },
-			],
+			beneficiary: { name: "John Doe" },
+			bankAccounts: [{ iban: "SK9611000000002918599669" }],
 		},
 	],
 });
@@ -135,9 +138,8 @@ const qrstring = encode({
 			amount: 25.0,
 			variableSymbol: "789012",
 			currencyCode: CurrencyCode.EUR, // "EUR"
-			bankAccounts: [
-				{ iban: "SK9611000000002918599669" },
-			],
+			beneficiary: { name: "John Doe" },
+			bankAccounts: [{ iban: "SK9611000000002918599669" }],
 		},
 	],
 });
@@ -170,9 +172,8 @@ const qrstring = encode({
 			month: Month.January | Month.July | Month.October, // Results in 577
 			periodicity: Periodicity.Monthly,
 			lastDate: "20251231",
-			bankAccounts: [
-				{ iban: "SK9611000000002918599669" },
-			],
+			beneficiary: { name: "John Doe" },
+			bankAccounts: [{ iban: "SK9611000000002918599669" }],
 		},
 	],
 });
@@ -192,9 +193,8 @@ const qrstring2 = encode({
 			month: encodedMonths, // Same result: 577
 			periodicity: Periodicity.Monthly,
 			lastDate: "20251231",
-			bankAccounts: [
-				{ iban: "SK9611000000002918599669" },
-			],
+			beneficiary: { name: "John Doe" },
+			bankAccounts: [{ iban: "SK9611000000002918599669" }],
 		},
 	],
 });
@@ -235,6 +235,7 @@ const data = {
 			amount: 100.0,
 			variableSymbol: "123",
 			paymentNote: "hello world",
+			beneficiary: { name: "John Doe" },
 			bankAccounts: [
 				{ iban: "SK9611000000002918599669" },
 				// ...more bank accounts
@@ -315,15 +316,16 @@ all XSD schema restrictions.
 
 ### Validation Behavior
 
-| Aspect        | Behavior                                                        |
-| ------------- | --------------------------------------------------------------- |
-| IBAN          | Validated (format + checksum via ISO 13616)                     |
-| BIC           | Validated (format via ISO 9362)                                 |
-| Currency      | Validated (ISO 4217, case-insensitive, includes XXX)            |
-| Date          | Validated (ISO 8601 format)                                     |
-| Symbols       | Permissive (accepts letters, spaces - XSD pattern not enforced) |
-| Amounts       | Permissive (accepts negative values)                            |
-| Field lengths | Not enforced                                                    |
+| Aspect           | Behavior                                                        |
+| ---------------- | --------------------------------------------------------------- |
+| IBAN             | Validated (format + checksum via ISO 13616)                     |
+| BIC              | Validated (format via ISO 9362)                                 |
+| Currency         | Validated (ISO 4217, case-insensitive, includes XXX)            |
+| Date             | Validated (ISO 8601 format)                                     |
+| Beneficiary name | Required (per spec v1.2.0)                                      |
+| Symbols          | Permissive (accepts letters, spaces - XSD pattern not enforced) |
+| Amounts          | Permissive (accepts negative values)                            |
+| Field lengths    | Not enforced                                                    |
 
 ### XSD Field Constraints Reference
 

package/lib/cli.js

@@ -1,119 +1,192 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, } from "node:fs";
+import { existsSync, readFileSync, statSync, } from "node:fs";
 import process from "node:process";
 import { parseArgs } from "node:util";
 import { decode } from "./decode.js";
-import { encode } from "./encode.js";
-const args = parseArgs({
-    allowPositionals: true,
-    options: {
-        decode: {
-            type: "string",
-            short: "d",
-        },
-        encode: {
-            type: "boolean",
-            short: "e",
-        },
-        validate: {
-            type: "boolean",
-            short: "v",
-        },
-        deburr: {
-            type: "boolean",
-            short: "b",
-        },
-        help: {
-            type: "boolean",
-            short: "h",
+import { encode, } from "./encode.js";
+import { Version } from "./types.js";
+const version = "3.1.0";
+const usage = `bysquare - Slovak PAY by square QR payment standard
+
+USAGE:
+    bysquare encode [OPTIONS] <input.json>
+    bysquare decode <qr-string>
+    bysquare version
+
+COMMANDS:
+    encode    Encode JSON payment data to BySquare QR string
+    decode    Decode BySquare QR string to JSON payment data
+    version   Print version information
+
+ENCODE OPTIONS:
+    -D, --no-deburr           Keep diacritics (deburr enabled by default)
+    -V, --no-validate         Skip validation (validation enabled by default)
+    -s, --spec-version VER    Specification version: 1.0.0, 1.1.0, 1.2.0 (default: 1.2.0)
+
+EXAMPLES:
+    # Encode with defaults (deburr=true, validate=true, version=1.2.0)
+    $ bysquare encode payment.json
+
+    # Encode with specific options
+    $ bysquare encode --no-deburr payment.json
+    $ bysquare encode --spec-version 1.1.0 payment.json
+    $ bysquare encode -s 1.0.0 --no-validate payment.json
+
+    # Encode from stdin
+    $ echo '{"payments":[...]}' | bysquare encode -
+
+    # Encode multiple files (including JSONL)
+    $ bysquare encode file1.json file2.jsonl
+
+    # Decode QR string
+    $ bysquare decode "00D80..."
+
+    # Decode from file
+    $ bysquare decode qr.txt
+
+For more information, visit: https://github.com/xseman/bysquare
+`;
+function errorMessage(error) {
+    return error instanceof Error
+        ? error.message
+        : String(error);
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function readInput(path) {
+    if (path === "-") {
+        return readStdin();
+    }
+    if (!existsSync(path)) {
+        throw new Error(`file ${path} doesn't exist`);
+    }
+    return readFileSync(path, "utf8");
+}
+async function cmdEncode(args) {
+    const parsed = parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            "no-deburr": {
+                type: "boolean",
+                short: "D",
+            },
+            "no-validate": {
+                type: "boolean",
+                short: "V",
+            },
+            "spec-version": {
+                type: "string",
+                short: "s",
+                default: "1.2.0",
+            },
         },
-    },
-});
-if (process.stdin.isTTY) {
-    if (args.values.encode) {
-        if (args.positionals.length === 0) {
-            console.error("No files provided for encoding.");
+    });
+    if (parsed.positionals.length === 0) {
+        console.error("Error: missing input file argument");
+        process.exit(1);
+    }
+    const versionStr = parsed.values["spec-version"];
+    if (!(versionStr in Version)) {
+        console.error("Error: unsupported spec version:", parsed.values["spec-version"]);
+        process.exit(1);
+    }
+    const encodeOpts = {
+        validate: !parsed.values["no-validate"],
+        deburr: !parsed.values["no-deburr"],
+        version: Version[versionStr],
+    };
+    for (const inputFile of parsed.positionals) {
+        let input;
+        try {
+            input = await readInput(inputFile);
+        }
+        catch (error) {
+            console.error("Error:", errorMessage(error));
             process.exit(1);
         }
-        for (const file of args.positionals) {
-            if (existsSync(file) === false) {
-                console.error(`File ${file} doesn't exist`);
-                process.exit(1);
-            }
-            if (file.endsWith(".json") === false
-                && file.endsWith(".jsonl") === false) {
-                console.error(`Unsupported file format for ${file}`);
-                process.exit(1);
+        if (inputFile.endsWith(".jsonl")) {
+            for (const line of input.split("\n")) {
+                if (!line.trim())
+                    continue;
+                encodeAndPrint(line, encodeOpts);
             }
-            const data = readFileSync(file, "utf8");
-            if (file.endsWith(".jsonl")) {
-                const lines = data.split("\n");
-                for (const line of lines) {
-                    if (!line)
-                        continue;
-                    const json = JSON.parse(line);
-                    console.log(encode(json));
-                }
-            }
-            if (file.endsWith(".json")) {
-                console.log(encode(JSON.parse(data), {
-                    validate: Boolean(args.values.validate),
-                    deburr: Boolean(args.values.deburr),
-                }));
-            }
-            process.exit(0);
+            continue;
         }
+        encodeAndPrint(input.trim(), encodeOpts);
     }
-    if (args.values.decode) {
-        const qrstring = args.values.decode;
-        console.log(JSON.stringify(decode(qrstring), null, 4));
-        process.exit(0);
+}
+function encodeAndPrint(jsonStr, opts) {
+    try {
+        const data = JSON.parse(jsonStr);
+        const result = encode(data, opts);
+        console.log(result);
     }
-    if (args.values.help
-        || Object.keys(args.values).length === 0) {
-        console.log([
-            "NAME",
-            "	bysquare - Simple Node.js library to generate and parse PAY bysquare standard",
-            "",
-            "SYNOPSIS",
-            "	bysquare [OPTIONS] [FILES...]",
-            "",
-            "DESCRIPTION",
-            "	bysquare is a command-line tool that provides a simple Node.js library to generate ",
-            "	and parse PAY bysquare standard. It offers functionality to encode JSON data into a ",
-            "	corresponding QR code and decode a QR code string to obtain the associated JSON data.",
-            "",
-            "OPTIONS",
-            "	-d, --decode <qrstring>",
-            "		Decode the specified QR code string and print the corresponding JSON data.",
-            "		The qrstring argument should be a valid QR code string.",
-            "",
-            "	-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.",
-            "",
-            "USAGE",
-            "	Encoding JSON data from one or more files",
-            "",
-            `	${process.argv[1]} --encode file1.json file2.json ...`,
-            "	The file1.json, file2.json, ... arguments should be the paths to the JSON or JSONL",
-            "   files you want to encode. The tool will read each file, generate a QR code representing",
-            "	the JSON data, and print them.",
-            "",
-            "	Decoding a QR code string",
-            "",
-            `	${process.argv[1]} --decode <qrstring>`,
-            "	Replace qrstring with the QR code string you want to decode.",
-            "	The program will parse the QR code string and print the resulting JSON data.",
-            "",
-        ].join("\n"));
+    catch (error) {
+        console.error("Error:", errorMessage(error));
+        process.exit(1);
     }
 }
+async function cmdDecode(args) {
+    if (args.length === 0) {
+        console.error("Error: missing QR string argument");
+        process.exit(1);
+    }
+    const qrInput = args[0];
+    try {
+        let qr;
+        if (qrInput === "-") {
+            qr = await readStdin();
+        }
+        else if (existsSync(qrInput) && statSync(qrInput).isFile()) {
+            qr = readFileSync(qrInput, "utf8");
+        }
+        else {
+            qr = qrInput;
+        }
+        const model = decode(qr.trim());
+        console.log(JSON.stringify(model, null, 2));
+    }
+    catch (error) {
+        console.error("Error:", errorMessage(error));
+        process.exit(1);
+    }
+}
+async function main() {
+    if (process.argv.length < 3) {
+        console.error(usage);
+        process.exit(1);
+    }
+    const command = process.argv[2];
+    switch (command) {
+        case "encode":
+            await cmdEncode(process.argv.slice(3));
+            break;
+        case "decode":
+            await cmdDecode(process.argv.slice(3));
+            break;
+        case "version":
+        case "-v":
+        case "--version":
+            console.log(`bysquare version ${version}`);
+            break;
+        case "help":
+        case "-h":
+        case "--help":
+            console.log(usage);
+            break;
+        default:
+            console.error("Unknown command:", command);
+            console.error(usage);
+            process.exit(1);
+    }
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/lib/decode.js

@@ -29,25 +29,6 @@ function decodeNumber(value) {
 function decodeString(value) {
     return value?.length ? value : undefined;
 }
-/**
- * Converts date from YYYYMMDD format to ISO 8601 format (YYYY-MM-DD)
- * per Pay by Square specification section 3.7.
- *
- * Note: This conversion is only used for paymentDueDate per specification.
- * lastDate remains in YYYYMMDD format.
- *
- * @param input - Date in YYYYMMDD format
- * @returns Date in ISO 8601 format (YYYY-MM-DD) | undefined
- */
-function deserializeDate(input) {
-    if (!input || input.length !== 8) {
-        return undefined;
-    }
-    const year = input.slice(0, 4);
-    const month = input.slice(4, 6);
-    const day = input.slice(6, 8);
-    return year + "-" + month + "-" + day;
-}
 /**
  * Parse a tab-separated intermediate format into DataModel.
  *
@@ -123,12 +104,13 @@ export function deserialize(qr) {
             type: Number(paymentOptions),
             currencyCode: currency ?? CurrencyCode.EUR,
             amount: Number(ammount),
-            paymentDueDate: deserializeDate(dueDate),
+            paymentDueDate: dueDate || undefined,
             variableSymbol: variableSymbol || undefined,
             constantSymbol: constantSymbol || undefined,
             specificSymbol: specificSymbol || undefined,
             originatorsReferenceInformation: originatorRefInfo || undefined,
             paymentNote: paymentNote || undefined,
+            beneficiary: { name: "" },
             bankAccounts: [],
         };
         const numberOfAccounts = Number(data.shift());
@@ -174,17 +156,15 @@ export function deserialize(qr) {
         output.payments.push(payment);
     }
     for (let i = 0; i < paymentslen; i++) {
-        const name = data.shift();
-        const addressLine1 = data.shift();
-        const addressLine2 = data.shift();
-        if (Boolean(name) || Boolean(addressLine1) || Boolean(addressLine2)) {
-            const beneficiary = {
-                name: name || undefined,
-                street: addressLine1 || undefined,
-                city: addressLine2 || undefined,
-            };
-            output.payments[i].beneficiary = beneficiary;
-        }
+        const name = data.shift() ?? "";
+        const addressLine1 = data.shift() ?? "";
+        const addressLine2 = data.shift() ?? "";
+        const beneficiary = {
+            name: name,
+            street: addressLine1 || undefined,
+            city: addressLine2 || undefined,
+        };
+        output.payments[i].beneficiary = beneficiary;
     }
     return output;
 }
@@ -227,7 +207,7 @@ export function decode(qr) {
     const bytes = base32hex.decode(qr);
     const headerBytes = bytes.slice(0, 2);
     const headerData = bysquareHeaderDecoder(headerBytes);
-    if ((headerData.version > Version["1.1.0"])) {
+    if ((headerData.version > Version["1.2.0"])) {
         throw new DecodeError(DecodeErrorMessage.UnsupportedVersion, {
             version: headerData.version,
         });

package/lib/encode.d.ts

@@ -141,7 +141,7 @@ export declare function addChecksum(tabbedPayload: string): Uint8Array;
  */
 export declare function serialize(data: DataModel): string;
 export declare function removeDiacritics(model: DataModel): void;
-type Options = {
+export type EncodeOptions = {
     /**
      * Many banking apps do not support diacritics, which results in errors when
      * serializing data from QR codes.
@@ -158,11 +158,10 @@ type Options = {
     /**
      * Version of the BySquare format to use.
      *
-     * Note: Version 1.1.0 adds beneficiary name and address fields but is not
-     * supported by all banking apps (e.g., TatraBanka). Use 1.0.0 for better
-     * compatibility.
+     * Note: Version 1.2.0 requires beneficiary name. Earlier versions (1.0.0, 1.1.0)
+     * do not require it but may have limited banking app support for beneficiary fields.
      *
-     * @default Version["1.0.0"]
+     * @default Version["1.2.0"]
      */
     version?: Version;
 };
@@ -200,5 +199,4 @@ type Options = {
  *
  * @see 3.16.
  */
-export declare function encode(model: DataModel, options?: Options): string;
-export {};
+export declare function encode(model: DataModel, options?: EncodeOptions): string;

package/lib/encode.js

@@ -4,22 +4,6 @@ import { crc32 } from "./crc32.js";
 import { deburr } from "./deburr.js";
 import { Month, PaymentOptions, Version, } from "./types.js";
 import { validateDataModel } from "./validations.js";
-/**
- * Converts date from ISO 8601 format (YYYY-MM-DD) to YYYYMMDD format
- * per Pay by Square specification section 3.7.
- *
- * Note: This conversion is only used for paymentDueDate per specification.
- * lastDate expects YYYYMMDD format directly.
- *
- * @param input - Date in ISO 8601 format (YYYY-MM-DD)
- * @returns Date in YYYYMMDD format | undefined
- */
-function serializeDate(input) {
-    if (!input) {
-        return undefined;
-    }
-    return input.split("-").join("");
-}
 export const EncodeErrorMessage = {
     /**
      * @description - find invalid value in extensions
@@ -206,7 +190,7 @@ export function serialize(data) {
         serialized.push(p.type.toString());
         serialized.push(p.amount?.toString());
         serialized.push(p.currencyCode);
-        serialized.push(serializeDate(p.paymentDueDate));
+        serialized.push(p.paymentDueDate);
         serialized.push(p.variableSymbol);
         serialized.push(p.constantSymbol);
         serialized.push(p.specificSymbol);
@@ -345,7 +329,7 @@ export function encode(model, options = { deburr: true, validate: true }) {
      */
     const _lzmaHeader = payloadCompressed.subarray(0, 13);
     const lzmaBody = payloadCompressed.subarray(13);
-    const version = options.version ?? Version["1.0.0"];
+    const version = options.version ?? Version["1.2.0"];
     const output = new Uint8Array([
         ...buildBysquareHeader([0x00, version, 0x00, 0x00]),
         ...buildPayloadLength(payloadChecked.byteLength),

package/lib/index.d.ts

@@ -5,6 +5,6 @@
  */
 export { decodeOptions, encodeOptions } from "./classifier.js";
 export { decode } from "./decode.js";
-export { encode } from "./encode.js";
+export { encode, type EncodeOptions } from "./encode.js";
 export { validateDataModel } from "./validations.js";
 export * from "./types.js";

package/lib/types.d.ts

@@ -16,6 +16,12 @@ export declare const Version: {
      * **Released Date:** 2015-06-24
      */
     readonly "1.1.0": 1;
+    /**
+     * Beneficiary name is now a required field
+     *
+     * **Released Date:** 2025-04-01
+     */
+    readonly "1.2.0": 2;
 };
 export type Version = typeof Version[keyof typeof Version];
 /**
@@ -149,11 +155,11 @@ export declare const DirectDebitType: {
 export type DirectDebitType = typeof DirectDebitType[keyof typeof DirectDebitType];
 export type Beneficiary = {
     /**
-     * Beneficiary name.
+     * Beneficiary name (required since v1.2.0).
      *
      * @maxLength 70
      */
-    name?: string;
+    name: string;
     /**
      * Beneficiary street address.
      *
@@ -190,14 +196,13 @@ export type SimplePayment = {
      */
     currencyCode: string | keyof typeof CurrencyCode;
     /**
-     * Payment due date.
+     * Payment due date in YYYYMMDD format per v1.2 specification section 3.7.
      *
      * For standing orders, this indicates the first payment date.
-     * The date will be converted to YYYYMMDD format during encoding per specification section 3.7.
      *
      * @format date
-     * @example "2024-12-31"
-     * @pattern \d{4}-\d{2}-\d{2}
+     * @example "20241231"
+     * @pattern \d{8}
      */
     paymentDueDate?: string;
     /**
@@ -240,7 +245,10 @@ export type SimplePayment = {
      * @minItems 1
      */
     bankAccounts: BankAccount[];
-    beneficiary?: Beneficiary;
+    /**
+     * Beneficiary information (required since v1.2.0).
+     */
+    beneficiary: Beneficiary;
 };
 export type PaymentOrder = SimplePayment & {
     type: typeof PaymentOptions.PaymentOrder;