bysquare 2.12.0 → 2.12.2

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 (14) hide show
  1. package/README.md +111 -67
  2. package/dist/decode.d.ts +6 -7
  3. package/dist/decode.js +6 -7
  4. package/dist/encode.d.ts +8 -9
  5. package/dist/encode.js +8 -9
  6. package/dist/index.d.ts +5 -0
  7. package/dist/index.js +5 -0
  8. package/dist/test_assets.d.ts +7 -8
  9. package/dist/types.d.ts +219 -208
  10. package/dist/types.js +204 -207
  11. package/dist/validations.d.ts +7 -8
  12. package/dist/validations.js +7 -8
  13. package/package.json +10 -17
  14. package/dist/tsconfig.tsbuildinfo +0 -1
package/README.md CHANGED
@@ -4,15 +4,17 @@
4
4
  the Slovak Banking Association in 2013. It is incorporated into a variety of
5
5
  invoices, reminders and other payment regulations.
6
6
 
7
- ## What it is
7
+ ## Why
8
8
 
9
- - Simple JavaScript library to encode and decode "PAY by square" string.
10
- - Aim to support simpe programming interface to encode and decode data for QR.
9
+ It's simple, I couldn't find any implementation of "PAY by square" standard for
10
+ JavaScript, so I decided to create one and share it with the community to help
11
+ individuals and businesses to create QR codes for their invoices.
11
12
 
12
- ## What it is not
13
+ ## Features
13
14
 
14
- - Generating QR code images.
15
- - Parsing QR code images.
15
+ - TypeScript support
16
+ - Compatible with Slovak banking apps
17
+ - Runtime-independent JavaScript implementation
16
18
 
17
19
  ## Installation
18
20
 
@@ -24,30 +26,13 @@ invoices, reminders and other payment regulations.
24
26
  [mozzila-esm]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules
25
27
  [mozzila-import]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import
26
28
 
27
- ### npm registry
29
+ ### [npm](https://npmjs.com/bysquare)
28
30
 
29
31
  ```sh
30
- npm install bysquare
32
+ $ npm install bysquare
31
33
  ```
32
34
 
33
- ### CLI Node `v18+`
34
-
35
- ```sh
36
- npm install --global bysquare
37
- ```
38
-
39
- ### deno
40
-
41
- Since `v1.28+` import from npm registry using `npm:` prefix.
42
-
43
- ```ts
44
- import {
45
- decode,
46
- encode,
47
- } from "npm:bysquare@latest";
48
- ```
49
-
50
- ### Browser
35
+ ### browser
51
36
 
52
37
  ```html
53
38
  <script type="module">
@@ -55,31 +40,106 @@ import {
55
40
  </script>
56
41
  ```
57
42
 
58
- ## Usage
59
-
60
- ### Basic Usage
43
+ ## Quick start
61
44
 
62
- Simple helper functions to wrap encoding for most common use cases.
45
+ There are helper functions for the most common use cases, such as simple payment,
46
+ direct debit, and standing order. Also you can use `encode` and `decode` functions
47
+ to work with the data model directly.
63
48
 
64
- - `simplePayment` - Encode simple payment data.
65
- - `directDebit` - Encode direct debit data.
66
- - `standingOrder` - Encode standing order data.
49
+ ### Simple Payment
67
50
 
68
- ```typescript
69
- import { simplePayment } from "bysquare";
51
+ ```js
52
+ import {
53
+ CurrencyCode,
54
+ simplePayment,
55
+ } from "bysquare";
70
56
 
71
57
  const qrstring = simplePayment({
72
- amount: 100,
58
+ amount: 50.75,
59
+ iban: "SK9611000000002918599669",
73
60
  variableSymbol: "123456",
74
61
  currencyCode: CurrencyCode.EUR,
62
+ });
63
+ ```
64
+
65
+ ### Direct Debit
66
+
67
+ ```js
68
+ import {
69
+ CurrencyCode,
70
+ directDebit,
71
+ } from "bysquare";
72
+
73
+ const qrstring = directDebit({
74
+ amount: 25.00,
75
75
  iban: "SK9611000000002918599669",
76
+ variableSymbol: "789012",
77
+ currencyCode: CurrencyCode.EUR,
76
78
  });
77
79
  ```
78
80
 
81
+ ### Standing Order
82
+
83
+ ```js
84
+ import {
85
+ CurrencyCode,
86
+ Periodicity,
87
+ standingOrder,
88
+ } from "bysquare";
89
+
90
+ const qrstring = standingOrder({
91
+ amount: 100.00,
92
+ iban: "SK9611000000002918599669",
93
+ variableSymbol: "654321",
94
+ day: 15,
95
+ periodicity: Periodicity.Monthly,
96
+ });
97
+ ```
98
+
99
+ ### HTML example
100
+
101
+ This example shows how to generate a payment QR code and display it in a web
102
+ page:
103
+
104
+ ```html
105
+ <!DOCTYPE html>
106
+ <html lang="en">
107
+ <head>
108
+ <meta charset="UTF-8">
109
+ <title>Payment QR Code</title>
110
+ </head>
111
+ <body>
112
+ <div id="qrcode" style="width: 200px"></div>
113
+
114
+ <script type="module">
115
+ import { QRCode } from "https://esm.sh/@lostinbrittany/qr-esm@latest";
116
+ import { simplePayment } from "https://esm.sh/bysquare@latest";
117
+
118
+ const qrstring = simplePayment({
119
+ amount: 123.45,
120
+ iban: "SK9611000000002918599669",
121
+ variableSymbol: "987654",
122
+ });
123
+
124
+ const qrElement = document.getElementById('qrcode');
125
+ qrElement.appendChild(QRCode.generateSVG(qrstring));
126
+ </script>
127
+ </body>
128
+ </html>
129
+ ```
130
+
79
131
  ### Adavanced usage
80
132
 
81
133
  For more complex data use `encode` and `decode` functions:
82
134
 
135
+ > [!NOTE]
136
+ > Encoded data are without diacritics
137
+ >
138
+ > The library removes all diacritics from the input data to ensure maximum
139
+ > compatibility, as not all banks support diacritics, which may lead to errors.
140
+ > If you need to retain diacritics, disable deburr option when encoding data -
141
+ > `encode(model, { deburr: false })`.
142
+
83
143
  ```ts
84
144
  import {
85
145
  CurrencyCode,
@@ -98,9 +158,13 @@ const data = {
98
158
  amount: 100.0,
99
159
  variableSymbol: "123",
100
160
  paymentNote: "hello world",
101
- bankAccounts: [{ iban: "SK9611000000002918599669" }],
161
+ bankAccounts: [
162
+ { iban: "SK9611000000002918599669" },
163
+ // ...more bank accounts
164
+ ],
102
165
  // ...more fields
103
166
  },
167
+ // ...more payments
104
168
  ],
105
169
  } satisfies DataModel;
106
170
 
@@ -113,13 +177,17 @@ const model = decode(qrstring);
113
177
 
114
178
  ## CLI
115
179
 
180
+ ```sh
181
+ $ npm install --global bysquare
182
+ ```
183
+
116
184
  ### Encode
117
185
 
118
186
  Encode JSON or JSONL data from files and print the corresponding QR code.
119
187
 
120
188
  ```sh
121
- npx bysquare --encode file1.json file2.json...
122
- npx bysquare --encode file.jsonl
189
+ $ bysquare --encode file1.json file2.json...
190
+ $ bysquare --encode file.jsonl
123
191
  ```
124
192
 
125
193
  ### Decode
@@ -128,40 +196,16 @@ Decode the specified QR code string and print the corresponding JSON data. The
128
196
  qrstring argument should be a valid QR code string.
129
197
 
130
198
  ```sh
131
- npx bysquare --decode <qrstring>
199
+ $ bysquare --decode <qrstring>
132
200
  ```
133
201
 
134
202
  ## How it works
135
203
 
136
- ### Encoding sequence
137
-
138
- ![logic](./docs/uml/logic.svg)
139
-
140
- ## Platform support
141
-
142
- I mainly focus on LTS versions of Node.js and try to use the most idiomatic
143
- ECMAScript possible to avoid specific runtime coupling.
144
-
145
- This doesn't mean that the library won't work on older versions, but it might
146
- not be as reliable.
147
-
148
- As of `v1.28`, Deno now includes built-in support for npm modules and is ready
149
- to use without additional setup, showing its improved maturity.
150
-
151
- ### Node.js & Deno
152
-
153
- - Node.js `v18` and later.
154
- - Deno `v1.28` and later.
155
-
156
- ### Browser
157
-
158
- The latest version of Chrome, Firefox, and Safari.
159
-
160
- ## Troubleshooting & Recommendations
204
+ ### Data Flow
161
205
 
162
- ### Encoded data are without diacritics
206
+ ### Encoding/Decoding Architecture
163
207
 
164
- The library removes all diacritics from the input data to ensure maximum compatibility, as not all banks support diacritics, which may lead to errors. If you need to retain diacritics, disable deburr option when encoding data - `encode(model, { deburr: false })`.
208
+ <image src="./docs/logic.svg" alt="encode" width="500px">
165
209
 
166
210
  ## Related
167
211
 
package/dist/decode.d.ts CHANGED
@@ -1,22 +1,21 @@
1
1
  import { DataModel } from "./index.js";
2
- export declare enum DecodeErrorMessage {
3
- MissingIBAN = "IBAN is missing",
2
+ export declare const DecodeErrorMessage: {
3
+ readonly MissingIBAN: "IBAN is missing";
4
4
  /**
5
5
  * @description - find original LZMA error in extensions
6
6
  */
7
- LZMADecompressionFailed = "LZMA decompression failed",
7
+ readonly LZMADecompressionFailed: "LZMA decompression failed";
8
8
  /**
9
9
  * @description - find found version in extensions
10
10
  * @see {@link ./types#Version} for valid ranges
11
11
  */
12
- UnsupportedVersion = "Unsupported version"
13
- }
12
+ readonly UnsupportedVersion: "Unsupported version";
13
+ };
14
14
  export declare class DecodeError extends Error {
15
- name: string;
16
15
  extensions?: {
17
16
  [name: string]: any;
18
17
  };
19
- constructor(message: DecodeErrorMessage, extensions?: {
18
+ constructor(message: string, extensions?: {
20
19
  [name: string]: any;
21
20
  });
22
21
  }
package/dist/decode.js CHANGED
@@ -1,24 +1,23 @@
1
1
  import { decompress } from "lzma1";
2
2
  import * as base32hex from "./base32hex.js";
3
3
  import { CurrencyCode, PaymentOptions, Version, } from "./index.js";
4
- export var DecodeErrorMessage;
5
- (function (DecodeErrorMessage) {
6
- DecodeErrorMessage["MissingIBAN"] = "IBAN is missing";
4
+ export const DecodeErrorMessage = {
5
+ MissingIBAN: "IBAN is missing",
7
6
  /**
8
7
  * @description - find original LZMA error in extensions
9
8
  */
10
- DecodeErrorMessage["LZMADecompressionFailed"] = "LZMA decompression failed";
9
+ LZMADecompressionFailed: "LZMA decompression failed",
11
10
  /**
12
11
  * @description - find found version in extensions
13
12
  * @see {@link ./types#Version} for valid ranges
14
13
  */
15
- DecodeErrorMessage["UnsupportedVersion"] = "Unsupported version";
16
- })(DecodeErrorMessage || (DecodeErrorMessage = {}));
14
+ UnsupportedVersion: "Unsupported version",
15
+ };
17
16
  export class DecodeError extends Error {
18
- name = "DecodeError";
19
17
  extensions;
20
18
  constructor(message, extensions) {
21
19
  super(message);
20
+ this.name = this.constructor.name;
22
21
  if (extensions) {
23
22
  this.extensions = extensions;
24
23
  }
package/dist/encode.d.ts CHANGED
@@ -1,34 +1,33 @@
1
1
  import { DataModel } from "./types.js";
2
- export declare enum EncodeErrorMessage {
2
+ export declare const EncodeErrorMessage: {
3
3
  /**
4
4
  * @description - find invalid value in extensions
5
5
  */
6
- BySquareType = "Invalid BySquareType value in header, valid range <0,15>",
6
+ readonly BySquareType: "Invalid BySquareType value in header, valid range <0,15>";
7
7
  /**
8
8
  * @description - find invalid value in extensions
9
9
  * @see {@link ./types#Version} for valid ranges
10
10
  */
11
- Version = "Invalid Version value in header",
11
+ readonly Version: "Invalid Version value in header";
12
12
  /**
13
13
  * @description - find invalid value in extensions
14
14
  */
15
- DocumentType = "Invalid DocumentType value in header, valid range <0,15>",
15
+ readonly DocumentType: "Invalid DocumentType value in header, valid range <0,15>";
16
16
  /**
17
17
  * @description - find invalid value in extensions
18
18
  */
19
- Reserved = "Invalid Reserved value in header, valid range <0,15>",
19
+ readonly Reserved: "Invalid Reserved value in header, valid range <0,15>";
20
20
  /**
21
21
  * @description - find actual size of header in extensions
22
22
  * @see MAX_COMPRESSED_SIZE
23
23
  */
24
- HeaderDataSize = "Allowed header data size exceeded"
25
- }
24
+ readonly HeaderDataSize: "Allowed header data size exceeded";
25
+ };
26
26
  export declare class EncodeError extends Error {
27
- name: string;
28
27
  extensions?: {
29
28
  [name: string]: any;
30
29
  };
31
- constructor(message: EncodeErrorMessage, extensions?: {
30
+ constructor(message: string, extensions?: {
32
31
  [name: string]: any;
33
32
  });
34
33
  }
package/dist/encode.js CHANGED
@@ -4,36 +4,35 @@ import { crc32 } from "./crc32.js";
4
4
  import { deburr } from "./deburr.js";
5
5
  import { PaymentOptions, Version, } from "./types.js";
6
6
  import { validateDataModel } from "./validations.js";
7
- export var EncodeErrorMessage;
8
- (function (EncodeErrorMessage) {
7
+ export const EncodeErrorMessage = {
9
8
  /**
10
9
  * @description - find invalid value in extensions
11
10
  */
12
- EncodeErrorMessage["BySquareType"] = "Invalid BySquareType value in header, valid range <0,15>";
11
+ BySquareType: "Invalid BySquareType value in header, valid range <0,15>",
13
12
  /**
14
13
  * @description - find invalid value in extensions
15
14
  * @see {@link ./types#Version} for valid ranges
16
15
  */
17
- EncodeErrorMessage["Version"] = "Invalid Version value in header";
16
+ Version: "Invalid Version value in header",
18
17
  /**
19
18
  * @description - find invalid value in extensions
20
19
  */
21
- EncodeErrorMessage["DocumentType"] = "Invalid DocumentType value in header, valid range <0,15>";
20
+ DocumentType: "Invalid DocumentType value in header, valid range <0,15>",
22
21
  /**
23
22
  * @description - find invalid value in extensions
24
23
  */
25
- EncodeErrorMessage["Reserved"] = "Invalid Reserved value in header, valid range <0,15>";
24
+ Reserved: "Invalid Reserved value in header, valid range <0,15>",
26
25
  /**
27
26
  * @description - find actual size of header in extensions
28
27
  * @see MAX_COMPRESSED_SIZE
29
28
  */
30
- EncodeErrorMessage["HeaderDataSize"] = "Allowed header data size exceeded";
31
- })(EncodeErrorMessage || (EncodeErrorMessage = {}));
29
+ HeaderDataSize: "Allowed header data size exceeded",
30
+ };
32
31
  export class EncodeError extends Error {
33
- name = "EncodeError";
34
32
  extensions;
35
33
  constructor(message, extensions) {
36
34
  super(message);
35
+ this.name = this.constructor.name;
37
36
  if (extensions) {
38
37
  this.extensions = extensions;
39
38
  }
package/dist/index.d.ts CHANGED
@@ -1,3 +1,8 @@
1
+ /**
2
+ * @license
3
+ * Copyright Filip Seman
4
+ * SPDX-License-Identifier: Apache-2.0
5
+ */
1
6
  export { decode, detect, parse } from "./decode.js";
2
7
  export { encode, generate } from "./encode.js";
3
8
  export { validateDataModel, ValidationErrorMessage } from "./validations.js";
package/dist/index.js CHANGED
@@ -1,3 +1,8 @@
1
+ /**
2
+ * @license
3
+ * Copyright Filip Seman
4
+ * SPDX-License-Identifier: Apache-2.0
5
+ */
1
6
  export { decode, detect, parse } from "./decode.js";
2
7
  export { encode, generate } from "./encode.js";
3
8
  export { validateDataModel, ValidationErrorMessage } from "./validations.js";
package/dist/test_assets.d.ts CHANGED
@@ -1,13 +1,12 @@
1
- import { CurrencyCode, PaymentOptions, Periodicity } from "./types.js";
2
1
  export declare const payloadWithPaymentOrder: {
3
2
  invoiceId: string;
4
3
  payments: {
5
- type: PaymentOptions.PaymentOrder;
4
+ type: 1;
6
5
  amount: number;
7
6
  bankAccounts: {
8
7
  iban: string;
9
8
  }[];
10
- currencyCode: CurrencyCode;
9
+ currencyCode: "EUR";
11
10
  variableSymbol: string;
12
11
  }[];
13
12
  };
@@ -15,13 +14,13 @@ export declare const serializedPaymentOrder: string;
15
14
  export declare const payloadWithStandingOrder: {
16
15
  invoiceId: string;
17
16
  payments: {
18
- type: PaymentOptions.StandingOrder;
17
+ type: 2;
19
18
  amount: number;
20
19
  bankAccounts: {
21
20
  iban: string;
22
21
  }[];
23
- periodicity: Periodicity.Monthly;
24
- currencyCode: CurrencyCode;
22
+ periodicity: "m";
23
+ currencyCode: "EUR";
25
24
  variableSymbol: string;
26
25
  lastDate: string;
27
26
  day: number;
@@ -31,12 +30,12 @@ export declare const serializedStandingOrder: string;
31
30
  export declare const payloadWithDirectDebit: {
32
31
  invoiceId: string;
33
32
  payments: {
34
- type: PaymentOptions.DirectDebit;
33
+ type: 4;
35
34
  amount: number;
36
35
  bankAccounts: {
37
36
  iban: string;
38
37
  }[];
39
- currencyCode: CurrencyCode;
38
+ currencyCode: "EUR";
40
39
  variableSymbol: string;
41
40
  }[];
42
41
  };