npm - bysquare - Versions diffs - 2.13.2 → 3.0.0 - Mend

bysquare 2.13.2 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (28) hide show

package/README.md CHANGED Viewed

@@ -1,8 +1,10 @@
-# bysquare
+<h1 align="center">bysquare</h1>
-"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 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.
+</p>
 ## Why
@@ -14,18 +16,10 @@ individuals and businesses to create QR codes for their invoices.
 - TypeScript support
 - Compatible with Slovak banking apps
-- Runtime-independent JavaScript implementation
+- Isomorphic Browser & Runtime-independent implementation
 ## 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.
-[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
 ### [npm](https://npmjs.com/bysquare)
 ```sh
@@ -45,20 +39,62 @@ $ npm install bysquare
 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
+page:
+```html
+<!DOCTYPE html>
+<html lang="en">
+	<head>
+		<meta charset="UTF-8" />
+		<title>Payment QR Code</title>
+	</head>
+	<body>
+		<div id="qrcode" style="width: 200px"></div>
+		<script type="module">
+			import { QRCode } from "https://esm.sh/@lostinbrittany/qr-esm@latest";
+			import { encode, PaymentOptions, CurrencyCode } from "https://esm.sh/bysquare@latest";
+			const qrstring = encode({
+				payments: [
+					{
+						type: PaymentOptions.PaymentOrder,
+						amount: 123.45,
+						variableSymbol: "987654",
+						currencyCode: CurrencyCode.EUR,
+						bankAccounts: [
+							{ iban: "SK9611000000002918599669" }
+						],
+					},
+				],
+			});
+			const qrElement = document.getElementById("qrcode");
+			qrElement.appendChild(QRCode.generateSVG(qrstring));
+		</script>
+	</body>
+</html>
+```
 ### Creating Payment QR Codes
 To generate QR codes for different payment types, use the `encode` function with
 the appropriate payment configuration:
-#### Simple Payment (Payment Order)
 ```js
 import {
 	CurrencyCode,
 	encode,
 	PaymentOptions,
+	Periodicity,
 } from "bysquare";
+// Simple Payment (Payment Order)
 const qrstring = encode({
 	payments: [
 		{
@@ -72,53 +108,33 @@ const qrstring = encode({
 		},
 	],
 });
-```
-#### Direct Debit
-```js
-import {
-	CurrencyCode,
-	encode,
-	PaymentOptions,
-} from "bysquare";
+// Standing Order
 const qrstring = encode({
 	payments: [
 		{
-			type: PaymentOptions.DirectDebit, // 2
-			amount: 25.0,
-			variableSymbol: "789012",
+			type: PaymentOptions.StandingOrder, // 3
+			amount: 100.0,
+			variableSymbol: "654321",
 			currencyCode: CurrencyCode.EUR, // "EUR"
+			day: 15,
+			month: Month.January, // Single month
+			periodicity: Periodicity.Monthly, // "m"
 			bankAccounts: [
 				{ iban: "SK9611000000002918599669" },
 			],
 		},
 	],
 });
-```
-#### Standing Order
-```js
-import {
-	CurrencyCode,
-	encode,
-	Month,
-	PaymentOptions,
-	Periodicity,
-} from "bysquare";
+// Direct Debit
 const qrstring = encode({
 	payments: [
 		{
-			type: PaymentOptions.StandingOrder, // 3
-			amount: 100.0,
-			variableSymbol: "654321",
+			type: PaymentOptions.DirectDebit, // 2
+			amount: 25.0,
+			variableSymbol: "789012",
 			currencyCode: CurrencyCode.EUR, // "EUR"
-			day: 15,
-			month: Month.January, // Single month
-			periodicity: Periodicity.Monthly, // "m"
 			bankAccounts: [
 				{ iban: "SK9611000000002918599669" },
 			],
@@ -184,45 +200,10 @@ const qrstring2 = encode({
 });
 ```
-### HTML example
-This example shows how to generate a payment QR code and display it in a web
-page:
-```html
-<!DOCTYPE html>
-<html lang="en">
-	<head>
-		<meta charset="UTF-8" />
-		<title>Payment QR Code</title>
-	</head>
-	<body>
-		<div id="qrcode" style="width: 200px"></div>
-		<script type="module">
-			import { QRCode } from "https://esm.sh/@lostinbrittany/qr-esm@latest";
-			import { encode, PaymentOptions, CurrencyCode } from "https://esm.sh/bysquare@latest";
-			const qrstring = encode({
-				payments: [
-					{
-						type: PaymentOptions.PaymentOrder,
-						amount: 123.45,
-						variableSymbol: "987654",
-						currencyCode: CurrencyCode.EUR,
-						bankAccounts: [
-							{ iban: "SK9611000000002918599669" }
-						],
-					},
-				],
-			});
-			const qrElement = document.getElementById("qrcode");
-			qrElement.appendChild(QRCode.generateSVG(qrstring));
-		</script>
-	</body>
-</html>
-```
+> [!NOTE]
+> **Date Format:** Provide date inputs (e.g., `paymentDueDate`, `lastDate`)
+> in ISO 8601 format (`YYYY-MM-DD`). They are automatically converted to
+> `YYYYMMDD` during encoding to match the Pay by Square specification.
 ### Advanced usage
@@ -324,13 +305,53 @@ $ bysquare --decode <qrstring>
 ### Encoding/Decoding Architecture
-<image src="./docs/logic.svg" alt="encode" width="500px">
+<image src="./docs/logic.excalidraw.svg" alt="encode" width="500px">
+## Validation
+This library uses **permissive validation** to ensure maximum compatibility with
+various Slovak banking applications. The validation does not strictly enforce
+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                                                    |
+### XSD Field Constraints Reference
+<https://www.bsqr.co/schema/>
+For reference, the official XSD schema defines these constraints (not enforced
+by this library):
+| Field                             | Max Length | Pattern       |
+| --------------------------------- | ---------- | ------------- |
+| `variableSymbol`                  | 10         | `[0-9]{0,10}` |
+| `constantSymbol`                  | 4          | `[0-9]{0,4}`  |
+| `specificSymbol`                  | 10         | `[0-9]{0,10}` |
+| `paymentNote`                     | 140        | -             |
+| `originatorsReferenceInformation` | 35         | -             |
+| `invoiceId`                       | 10         | -             |
+| `beneficiary.name`                | 70         | -             |
+| `beneficiary.street`              | 70         | -             |
+| `beneficiary.city`                | 70         | -             |
+| `mandateId`                       | 35         | -             |
+| `creditorId`                      | 35         | -             |
+| `contractId`                      | 35         | -             |
+| `amount`                          | 15         | `>= 0`        |
 ## Related
 - <https://bysquare.com/>
 - <https://devel.cz/otazka/qr-kod-pay-by-square>
 - <https://github.com/matusf/pay-by-square>
-- <https://www.bsqr.co/schema/>
 - <https://www.sbaonline.sk/wp-content/uploads/2020/03/pay-by-square-specifications-1_1_0.pdf>
 - <https://www.vutbr.cz/studenti/zav-prace/detail/78439>

package/lib/base32hex.d.ts CHANGED Viewed

@@ -1,2 +1,39 @@
+/**
+ * Encodes bytes to base32hex by converting 8-bit bytes to 5-bit groups.
+ *
+ * ```
+ * Bit packing process (40 bits = 5 bytes → 8 base32hex chars):
+ *
+ * Input bytes:     [   B0   ][   B1   ][   B2   ][   B3   ][   B4   ]
+ * Bit positions:   76543210  76543210  76543210  76543210  76543210
+ *
+ * Output groups:   [C0 ][C1 ][C2 ][C3 ][C4 ][C5 ][C6 ][C7 ]
+ * Bit positions:   43210 43210 43210 43210 43210 43210 43210 43210
+ *
+ * C0 = B0[7:3]   (top 5 bits of B0)
+ * C1 = B0[2:0] + B1[7:6]   (bottom 3 bits of B0 + top 2 bits of B1)
+ * C2 = B1[5:1]   (middle 5 bits of B1)
+ * C3 = B1[0] + B2[7:4]   (bottom 1 bit of B1 + top 4 bits of B2)
+ * ... and so on
+ * ```
+ */
 export declare function encode(input: ArrayLike<number>, addPadding?: boolean): string;
+/**
+ * Decodes base32hex string back to bytes by converting 5-bit groups to 8-bit bytes.
+ *
+ * ```
+ * Bit unpacking process (8 base32hex chars → 5 bytes):
+ *
+ * Input groups:    [C0 ][C1 ][C2 ][C3 ][C4 ][C5 ][C6 ][C7 ]
+ * Bit positions:   43210 43210 43210 43210 43210 43210 43210 43210
+ *
+ * Output bytes:    [   B0   ][   B1   ][   B2   ][   B3   ][   B4   ]
+ * Bit positions:   76543210  76543210  76543210  76543210  76543210
+ *
+ * B0 = C0[4:0] + C1[4:3]   (all of C0 + top 2 bits of C1)
+ * B1 = C1[2:0] + C2[4:0]   (bottom 3 bits of C1 + all of C2)
+ * B2 = C3[4:0] + C4[4:2]   (all of C3 + top 3 bits of C4)
+ * ... and so on
+ * ```
+ */
 export declare function decode(input: string, isLoose?: boolean): Uint8Array;

package/lib/base32hex.js CHANGED Viewed

@@ -3,6 +3,25 @@ const base32Hex = {
     bits: 5,
     mask: 0b11111, // Mask to extract 5 bits
 };
+/**
+ * Encodes bytes to base32hex by converting 8-bit bytes to 5-bit groups.
+ *
+ * ```
+ * Bit packing process (40 bits = 5 bytes → 8 base32hex chars):
+ *
+ * Input bytes:     [   B0   ][   B1   ][   B2   ][   B3   ][   B4   ]
+ * Bit positions:   76543210  76543210  76543210  76543210  76543210
+ *
+ * Output groups:   [C0 ][C1 ][C2 ][C3 ][C4 ][C5 ][C6 ][C7 ]
+ * Bit positions:   43210 43210 43210 43210 43210 43210 43210 43210
+ *
+ * C0 = B0[7:3]   (top 5 bits of B0)
+ * C1 = B0[2:0] + B1[7:6]   (bottom 3 bits of B0 + top 2 bits of B1)
+ * C2 = B1[5:1]   (middle 5 bits of B1)
+ * C3 = B1[0] + B2[7:4]   (bottom 1 bit of B1 + top 4 bits of B2)
+ * ... and so on
+ * ```
+ */
 export function encode(input, addPadding = true) {
     const output = Array();
     let buffer = 0;
@@ -27,6 +46,24 @@ export function encode(input, addPadding = true) {
     }
     return base32hex;
 }
+/**
+ * Decodes base32hex string back to bytes by converting 5-bit groups to 8-bit bytes.
+ *
+ * ```
+ * Bit unpacking process (8 base32hex chars → 5 bytes):
+ *
+ * Input groups:    [C0 ][C1 ][C2 ][C3 ][C4 ][C5 ][C6 ][C7 ]
+ * Bit positions:   43210 43210 43210 43210 43210 43210 43210 43210
+ *
+ * Output bytes:    [   B0   ][   B1   ][   B2   ][   B3   ][   B4   ]
+ * Bit positions:   76543210  76543210  76543210  76543210  76543210
+ *
+ * B0 = C0[4:0] + C1[4:3]   (all of C0 + top 2 bits of C1)
+ * B1 = C1[2:0] + C2[4:0]   (bottom 3 bits of C1 + all of C2)
+ * B2 = C3[4:0] + C4[4:2]   (all of C3 + top 3 bits of C4)
+ * ... and so on
+ * ```
+ */
 export function decode(input, isLoose = false) {
     if (isLoose) {
         input = input.toUpperCase();

package/lib/classifier.d.ts CHANGED Viewed

@@ -4,6 +4,32 @@
  *
  * Supports Month Classifier (Table 10) and other classifiers that use summed
  * values.
+ *
+ * Bit-flag encoding example (Month Classifier):
+ * ```
+ * Month      | Binary         | Decimal | Bit Position
+ * -----------+----------------+---------+-------------
+ * January    | 0b000000000001 | 1       | Bit 0
+ * February   | 0b000000000010 | 2       | Bit 1
+ * March      | 0b000000000100 | 4       | Bit 2
+ * April      | 0b000000001000 | 8       | Bit 3
+ * May        | 0b000000010000 | 16      | Bit 4
+ * June       | 0b000000100000 | 32      | Bit 5
+ * July       | 0b000001000000 | 64      | Bit 6
+ * August     | 0b000010000000 | 128     | Bit 7
+ * September  | 0b000100000000 | 256     | Bit 8
+ * October    | 0b001000000000 | 512     | Bit 9
+ * November   | 0b010000000000 | 1024    | Bit 10
+ * December   | 0b100000000000 | 2048    | Bit 11
+ *
+ * Combined example:
+ *   January + July + October = 1 + 64 + 512 = 577
+ *   Binary: 0b001001000001
+ *           ^^^  ^      ^
+ *           |    |      └─ Bit 0 (January)
+ *           |    └──────── Bit 6 (July)
+ *           └───────────── Bit 9 (October)
+ * ```
  */
 /**
  * Encodes multiple classifier options into a single number by summing their

package/lib/classifier.js CHANGED Viewed

@@ -4,6 +4,32 @@
  *
  * Supports Month Classifier (Table 10) and other classifiers that use summed
  * values.
+ *
+ * Bit-flag encoding example (Month Classifier):
+ * ```
+ * Month      | Binary         | Decimal | Bit Position
+ * -----------+----------------+---------+-------------
+ * January    | 0b000000000001 | 1       | Bit 0
+ * February   | 0b000000000010 | 2       | Bit 1
+ * March      | 0b000000000100 | 4       | Bit 2
+ * April      | 0b000000001000 | 8       | Bit 3
+ * May        | 0b000000010000 | 16      | Bit 4
+ * June       | 0b000000100000 | 32      | Bit 5
+ * July       | 0b000001000000 | 64      | Bit 6
+ * August     | 0b000010000000 | 128     | Bit 7
+ * September  | 0b000100000000 | 256     | Bit 8
+ * October    | 0b001000000000 | 512     | Bit 9
+ * November   | 0b010000000000 | 1024    | Bit 10
+ * December   | 0b100000000000 | 2048    | Bit 11
+ *
+ * Combined example:
+ *   January + July + October = 1 + 64 + 512 = 577
+ *   Binary: 0b001001000001
+ *           ^^^  ^      ^
+ *           |    |      └─ Bit 0 (January)
+ *           |    └──────── Bit 6 (July)
+ *           └───────────── Bit 9 (October)
+ * ```
  */
 /**
  * Encodes multiple classifier options into a single number by summing their

package/lib/decode.d.ts CHANGED Viewed

@@ -20,13 +20,59 @@ export declare class DecodeError extends Error {
     });
 }
 /**
- * Generating by square Code
+ * Parse a tab-separated intermediate format into DataModel.
  *
- * @see 3.14.
+ * Base fields
+ * - Field 0: invoiceId
+ * - Field 1: paymentsCount
+ *
+ * Payment block (repeated `paymentsCount` times)
+ * - Field +0: type
+ * - Field +1: amount
+ * - Field +2: currencyCode
+ * - Field +3: paymentDueDate (YYYYMMDD)
+ * - Field +4: variableSymbol
+ * - Field +5: constantSymbol
+ * - Field +6: specificSymbol
+ * - Field +7: originatorsReferenceInformation
+ * - Field +8: paymentNote
+ * - Field +9: bankAccountsCount
+ *
+ * Bank account block (nested, repeated `bankAccountsCount` times)
+ * - Field +0: iban
+ * - Field +1: bic
+ *
+ * Standing order extension
+ * - Field +X: standingOrderExt ("0" | "1")
+ *   - if "1":
+ *     - Field +1: day
+ *     - Field +2: month (classifier sum)
+ *     - Field +3: periodicity
+ *     - Field +4: lastDate (YYYYMMDD)
+ *
+ * Direct debit extension
+ * - Field +Y: directDebitExt ("0" | "1")
+ *   - if "1":
+ *     - Field +1: directDebitScheme
+ *     - Field +2: directDebitType
+ *     - Field +3: variableSymbol
+ *     - Field +4: specificSymbol
+ *     - Field +5: originatorsReferenceInformation
+ *     - Field +6: mandateId
+ *     - Field +7: creditorId
+ *     - Field +8: contractId
+ *     - Field +9: maxAmount
+ *     - Field +10: validTillDate
+ *
+ * Beneficiary block (repeated per payment)
+ * - Field +0: beneficiaryName
+ * - Field +1: beneficiaryStreet
+ * - Field +2: beneficiaryCity
+ *
+ * @see 3.14
+ * @see Table 15
  */
 export declare function deserialize(qr: string): DataModel;
-/** @deprecated */
-export declare const parse: typeof decode;
 /**
  * Decoding client data from QR Code 2005 symbol
  *
@@ -34,12 +80,3 @@ export declare const parse: typeof decode;
  * @param qr base32hex encoded bysqaure binary data
  */
 export declare function decode(qr: string): DataModel;
-/**
- * Detect if qr string contains bysquare header.
- *
- * 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;