pakdatakit 2.1.1 → 2.1.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.
package/README.md CHANGED
@@ -690,14 +690,19 @@ FBR does not publish its check-digit algorithms, so these check the format only.
690
690
  Builds and reads payment QR codes following the State Bank of Pakistan's QR standard (Circular Letter No. 1 of 2022). Turn the returned string into an image with any QR library.
691
691
 
692
692
  ```ts
693
- // Person-to-person: anyone can pay this IBAN through Raast
693
+ // Person-to-person: anyone can pay this IBAN through Raast; the payer enters the amount
694
+ createRaastP2PQr({ iban: 'PK36SCBL0000001123456702' });
695
+
696
+ // With a fixed amount: banking apps require an expiry
694
697
  const payload = createRaastP2PQr({
695
698
  iban: 'PK36SCBL0000001123456702',
696
699
  amount: 1500,
700
+ expiresAt: new Date(2026, 10, 13, 23, 59),
697
701
  });
698
702
 
699
703
  parseRaastQr(payload);
700
- // { kind: 'p2p', dynamic: true, crcValid: true, iban: 'PK36SCBL0000001123456702', amount: 1500, ... }
704
+ // { kind: 'p2p', dynamic: true, crcValid: true, iban: 'PK36SCBL0000001123456702',
705
+ // amount: 1500, expiresAt: '2026-11-13T23:59', ... }
701
706
 
702
707
  // Merchant QR (EMVCo), with Pakistan-specific bill due dates
703
708
  createMerchantQr({
@@ -716,7 +721,7 @@ createMerchantQr({
716
721
  });
717
722
  ```
718
723
 
719
- Person-to-person QR codes use the same layout as QR codes from banking apps (Faysal Bank, easypaisa), and scan in the Easypaisa and JazzCash apps. This is handy for accounts whose app cannot generate a receiving QR, such as SadaPay.
724
+ Person-to-person QR codes use the same layout as QR codes from banking apps (Faysal Bank and easypaisa without an amount; JazzCash and Mashreq with one), and scan in the Easypaisa and JazzCash apps. This is handy for accounts whose app cannot generate a receiving QR, such as SadaPay. A QR with an amount must have `expiresAt`: apps reject amount QRs without an expiry, and ignore an amount in a QR that has none.
720
725
 
721
726
  SBP reserves merchant-account tags 28–30 for Raast but has shared the layout of the fields inside them only with banks, so `createMerchantQr` takes those sub-fields from you. `parseRaastQr` checks the CRC and finds the IBAN in either kind of QR.
722
727
 
@@ -67,6 +67,23 @@ function formatAmount(amount, maxLength, label) {
67
67
  }
68
68
  return text;
69
69
  }
70
+ function formatP2PAmount(amount) {
71
+ if (!Number.isFinite(amount) || amount <= 0) {
72
+ throw new RangeError("amount must be a positive number");
73
+ }
74
+ const text = Number.isInteger(amount) ? String(amount) : amount.toFixed(2);
75
+ if (text.length > 10) {
76
+ throw new RangeError("amount is too large for a Raast QR code");
77
+ }
78
+ return text;
79
+ }
80
+ function formatExpiry(date) {
81
+ if (Number.isNaN(date.getTime())) {
82
+ throw new RangeError("expiresAt is invalid");
83
+ }
84
+ const two = (n) => String(n).padStart(2, "0");
85
+ return two(date.getDate()) + two(date.getMonth() + 1) + String(date.getFullYear()).padStart(4, "0") + two(date.getHours()) + two(date.getMinutes());
86
+ }
70
87
  function checkLength(value, max, label) {
71
88
  if ([...value].length > max) {
72
89
  throw new RangeError(`${label} must be at most ${max} characters`);
@@ -88,7 +105,7 @@ function createRaastP2PQr(options) {
88
105
  }
89
106
  payload += encodeField("04", iban);
90
107
  if (options.amount !== void 0) {
91
- payload += encodeField("05", formatAmount(options.amount, 10, "amount"));
108
+ payload += encodeField("05", formatP2PAmount(options.amount));
92
109
  }
93
110
  if (options.particulars) {
94
111
  payload += encodeField(
@@ -96,6 +113,12 @@ function createRaastP2PQr(options) {
96
113
  checkLength(options.particulars, 30, "particulars")
97
114
  );
98
115
  }
116
+ if (options.amount !== void 0) {
117
+ if (options.expiresAt === void 0) {
118
+ throw new RangeError("A QR with an amount needs expiresAt");
119
+ }
120
+ payload += encodeField("07", formatExpiry(options.expiresAt));
121
+ }
99
122
  const data = `${payload}1004`;
100
123
  return `${data}${crc16(data)}`;
101
124
  }
@@ -211,6 +234,7 @@ function parseRaastQr(payload) {
211
234
  }
212
235
  const additional = fields.find((field) => field.id === "62")?.children ?? [];
213
236
  const due = fieldValue(additional, "50");
237
+ const expiry = kind === "p2p" ? fieldValue(fields, "07") : null;
214
238
  return {
215
239
  kind,
216
240
  dynamic: fieldValue(fields, "01") === "12",
@@ -218,6 +242,7 @@ function parseRaastQr(payload) {
218
242
  iban,
219
243
  ibanValid: iban !== null && chunkE47SNBWQ_cjs.validateIBAN(iban),
220
244
  amount: toAmount(fieldValue(fields, kind === "p2p" ? "05" : "54")),
245
+ expiresAt: expiry && /^\d{12}$/.test(expiry) ? `${expiry.slice(4, 8)}-${expiry.slice(2, 4)}-${expiry.slice(0, 2)}T${expiry.slice(8, 10)}:${expiry.slice(10)}` : null,
221
246
  bankName: kind === "p2p" ? fieldValue(fields, "03") : null,
222
247
  particulars: kind === "p2p" ? fieldValue(fields, "06") : null,
223
248
  merchantName: kind === "merchant" ? fieldValue(fields, "59") : null,
@@ -65,6 +65,23 @@ function formatAmount(amount, maxLength, label) {
65
65
  }
66
66
  return text;
67
67
  }
68
+ function formatP2PAmount(amount) {
69
+ if (!Number.isFinite(amount) || amount <= 0) {
70
+ throw new RangeError("amount must be a positive number");
71
+ }
72
+ const text = Number.isInteger(amount) ? String(amount) : amount.toFixed(2);
73
+ if (text.length > 10) {
74
+ throw new RangeError("amount is too large for a Raast QR code");
75
+ }
76
+ return text;
77
+ }
78
+ function formatExpiry(date) {
79
+ if (Number.isNaN(date.getTime())) {
80
+ throw new RangeError("expiresAt is invalid");
81
+ }
82
+ const two = (n) => String(n).padStart(2, "0");
83
+ return two(date.getDate()) + two(date.getMonth() + 1) + String(date.getFullYear()).padStart(4, "0") + two(date.getHours()) + two(date.getMinutes());
84
+ }
68
85
  function checkLength(value, max, label) {
69
86
  if ([...value].length > max) {
70
87
  throw new RangeError(`${label} must be at most ${max} characters`);
@@ -86,7 +103,7 @@ function createRaastP2PQr(options) {
86
103
  }
87
104
  payload += encodeField("04", iban);
88
105
  if (options.amount !== void 0) {
89
- payload += encodeField("05", formatAmount(options.amount, 10, "amount"));
106
+ payload += encodeField("05", formatP2PAmount(options.amount));
90
107
  }
91
108
  if (options.particulars) {
92
109
  payload += encodeField(
@@ -94,6 +111,12 @@ function createRaastP2PQr(options) {
94
111
  checkLength(options.particulars, 30, "particulars")
95
112
  );
96
113
  }
114
+ if (options.amount !== void 0) {
115
+ if (options.expiresAt === void 0) {
116
+ throw new RangeError("A QR with an amount needs expiresAt");
117
+ }
118
+ payload += encodeField("07", formatExpiry(options.expiresAt));
119
+ }
97
120
  const data = `${payload}1004`;
98
121
  return `${data}${crc16(data)}`;
99
122
  }
@@ -209,6 +232,7 @@ function parseRaastQr(payload) {
209
232
  }
210
233
  const additional = fields.find((field) => field.id === "62")?.children ?? [];
211
234
  const due = fieldValue(additional, "50");
235
+ const expiry = kind === "p2p" ? fieldValue(fields, "07") : null;
212
236
  return {
213
237
  kind,
214
238
  dynamic: fieldValue(fields, "01") === "12",
@@ -216,6 +240,7 @@ function parseRaastQr(payload) {
216
240
  iban,
217
241
  ibanValid: iban !== null && validateIBAN(iban),
218
242
  amount: toAmount(fieldValue(fields, kind === "p2p" ? "05" : "54")),
243
+ expiresAt: expiry && /^\d{12}$/.test(expiry) ? `${expiry.slice(4, 8)}-${expiry.slice(2, 4)}-${expiry.slice(0, 2)}T${expiry.slice(8, 10)}:${expiry.slice(10)}` : null,
219
244
  bankName: kind === "p2p" ? fieldValue(fields, "03") : null,
220
245
  particulars: kind === "p2p" ? fieldValue(fields, "06") : null,
221
246
  merchantName: kind === "merchant" ? fieldValue(fields, "59") : null,
package/dist/cli.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import { normalizeRomanUrdu, formatHijri, toHijri, formatPKR, formatLakh, parseAddress, getCityByPostalCode, getPostalCode, getProvince, getBankFromIBAN, validateIBAN, analyzePhone, validatePhone, validateCNIC } from 'pakdatakit';
3
3
 
4
4
  // package.json
5
- var version = "2.1.1";
5
+ var version = "2.1.2";
6
6
  var EXIT_OK = 0;
7
7
  var EXIT_NEGATIVE = 1;
8
8
  var EXIT_USAGE = 2;
package/dist/index.cjs CHANGED
@@ -4,7 +4,7 @@ var chunkAPXP7OK7_cjs = require('./chunk-APXP7OK7.cjs');
4
4
  var chunkBSS4Z7NI_cjs = require('./chunk-BSS4Z7NI.cjs');
5
5
  var chunkPHHKIMO2_cjs = require('./chunk-PHHKIMO2.cjs');
6
6
  var chunkYS7MOLK2_cjs = require('./chunk-YS7MOLK2.cjs');
7
- var chunk43ULDYUP_cjs = require('./chunk-43ULDYUP.cjs');
7
+ var chunkQ7XHVR3U_cjs = require('./chunk-Q7XHVR3U.cjs');
8
8
  var chunkH6M6L26S_cjs = require('./chunk-H6M6L26S.cjs');
9
9
  var chunkKEHCTYLO_cjs = require('./chunk-KEHCTYLO.cjs');
10
10
  var chunkKQKW2ZEK_cjs = require('./chunk-KQKW2ZEK.cjs');
@@ -63,15 +63,15 @@ Object.defineProperty(exports, "getNetwork", {
63
63
  });
64
64
  Object.defineProperty(exports, "createMerchantQr", {
65
65
  enumerable: true,
66
- get: function () { return chunk43ULDYUP_cjs.createMerchantQr; }
66
+ get: function () { return chunkQ7XHVR3U_cjs.createMerchantQr; }
67
67
  });
68
68
  Object.defineProperty(exports, "createRaastP2PQr", {
69
69
  enumerable: true,
70
- get: function () { return chunk43ULDYUP_cjs.createRaastP2PQr; }
70
+ get: function () { return chunkQ7XHVR3U_cjs.createRaastP2PQr; }
71
71
  });
72
72
  Object.defineProperty(exports, "parseRaastQr", {
73
73
  enumerable: true,
74
- get: function () { return chunk43ULDYUP_cjs.parseRaastQr; }
74
+ get: function () { return chunkQ7XHVR3U_cjs.parseRaastQr; }
75
75
  });
76
76
  Object.defineProperty(exports, "analyzeNTN", {
77
77
  enumerable: true,
package/dist/index.js CHANGED
@@ -2,7 +2,7 @@ export { amountInWords, numberToWords } from './chunk-QQQKISXT.js';
2
2
  export { analyzeNumber, getAreaCode, getNumberType, validateLandline } from './chunk-T3E4B5MJ.js';
3
3
  export { analyzePhone, formatPhone, validatePhone } from './chunk-432ZYMYV.js';
4
4
  export { getNetwork } from './chunk-L45UXUWX.js';
5
- export { createMerchantQr, createRaastP2PQr, parseRaastQr } from './chunk-44YRK7WO.js';
5
+ export { createMerchantQr, createRaastP2PQr, parseRaastQr } from './chunk-R7UTY3SY.js';
6
6
  export { analyzeNTN, validateNTN, validateSTRN } from './chunk-CEPNSHIC.js';
7
7
  export { normalizeRomanUrdu, normalizeText, toEnglishDigits, toUrduDigits } from './chunk-JKE4AMSZ.js';
8
8
  export { createWhatsAppLink } from './chunk-P4CGOJEM.js';
package/dist/raast.cjs CHANGED
@@ -1,6 +1,6 @@
1
1
  'use strict';
2
2
 
3
- var chunk43ULDYUP_cjs = require('./chunk-43ULDYUP.cjs');
3
+ var chunkQ7XHVR3U_cjs = require('./chunk-Q7XHVR3U.cjs');
4
4
  require('./chunk-E47SNBWQ.cjs');
5
5
  require('./chunk-VPBMIYO2.cjs');
6
6
 
@@ -8,13 +8,13 @@ require('./chunk-VPBMIYO2.cjs');
8
8
 
9
9
  Object.defineProperty(exports, "createMerchantQr", {
10
10
  enumerable: true,
11
- get: function () { return chunk43ULDYUP_cjs.createMerchantQr; }
11
+ get: function () { return chunkQ7XHVR3U_cjs.createMerchantQr; }
12
12
  });
13
13
  Object.defineProperty(exports, "createRaastP2PQr", {
14
14
  enumerable: true,
15
- get: function () { return chunk43ULDYUP_cjs.createRaastP2PQr; }
15
+ get: function () { return chunkQ7XHVR3U_cjs.createRaastP2PQr; }
16
16
  });
17
17
  Object.defineProperty(exports, "parseRaastQr", {
18
18
  enumerable: true,
19
- get: function () { return chunk43ULDYUP_cjs.parseRaastQr; }
19
+ get: function () { return chunkQ7XHVR3U_cjs.parseRaastQr; }
20
20
  });
package/dist/raast.d.cts CHANGED
@@ -19,8 +19,14 @@ interface RaastP2PQrOptions {
19
19
  * `'30'` is the value listed for Raast in SBP's QR standard.
20
20
  */
21
21
  scheme?: '00' | '30';
22
- /** Amount in PKR. When set, the QR is dynamic (point of initiation 12). */
22
+ /**
23
+ * Amount in PKR. When set, the QR is dynamic (point of initiation 12) and
24
+ * `expiresAt` is required: banking apps reject dynamic QR codes without an
25
+ * expiry, and ignore the amount in static ones.
26
+ */
23
27
  amount?: number;
28
+ /** When a QR with an amount stops working (tag 07). Required with `amount`. */
29
+ expiresAt?: Date;
24
30
  /** Payee's bank name (up to 25 characters). */
25
31
  bankName?: string;
26
32
  /** Payment description (up to 30 characters). */
@@ -71,6 +77,8 @@ interface ParsedRaastQr {
71
77
  /** Whether `iban` passes the IBAN checksum. */
72
78
  ibanValid: boolean;
73
79
  amount: number | null;
80
+ /** P2P: expiry of a dynamic QR as local `YYYY-MM-DDTHH:mm`. */
81
+ expiresAt: string | null;
74
82
  /** P2P: bank name. */
75
83
  bankName: string | null;
76
84
  /** P2P: payment description. */
@@ -91,12 +99,22 @@ interface ParsedRaastQr {
91
99
  * scanned by apps such as Easypaisa and JazzCash. Encode the string as a QR
92
100
  * code with any QR library.
93
101
  *
102
+ * A QR with an `amount` is dynamic and needs `expiresAt`; this layout
103
+ * (`01` = `12`, amount in tag 05, expiry in tag 07) matches dynamic QR codes
104
+ * from banking apps and scans in Easypaisa and JazzCash.
105
+ *
94
106
  * @example
95
- * createRaastP2PQr({ iban: 'PK36SCBL0000001123456702', amount: 1500 });
107
+ * createRaastP2PQr({ iban: 'PK36SCBL0000001123456702' });
108
+ * createRaastP2PQr({
109
+ * iban: 'PK36SCBL0000001123456702',
110
+ * amount: 1500,
111
+ * expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
112
+ * });
96
113
  *
97
- * @param options - Payee IBAN and optional amount, bank name and description
114
+ * @param options - Payee IBAN and optional amount with expiry, bank name and description
98
115
  * @returns QR payload string
99
- * @throws {RangeError} If the IBAN is invalid or a field is too long
116
+ * @throws {RangeError} If the IBAN is invalid, a field is too long, or an
117
+ * amount is given without `expiresAt`
100
118
  */
101
119
  declare function createRaastP2PQr(options: RaastP2PQrOptions): string;
102
120
  /**
package/dist/raast.d.ts CHANGED
@@ -19,8 +19,14 @@ interface RaastP2PQrOptions {
19
19
  * `'30'` is the value listed for Raast in SBP's QR standard.
20
20
  */
21
21
  scheme?: '00' | '30';
22
- /** Amount in PKR. When set, the QR is dynamic (point of initiation 12). */
22
+ /**
23
+ * Amount in PKR. When set, the QR is dynamic (point of initiation 12) and
24
+ * `expiresAt` is required: banking apps reject dynamic QR codes without an
25
+ * expiry, and ignore the amount in static ones.
26
+ */
23
27
  amount?: number;
28
+ /** When a QR with an amount stops working (tag 07). Required with `amount`. */
29
+ expiresAt?: Date;
24
30
  /** Payee's bank name (up to 25 characters). */
25
31
  bankName?: string;
26
32
  /** Payment description (up to 30 characters). */
@@ -71,6 +77,8 @@ interface ParsedRaastQr {
71
77
  /** Whether `iban` passes the IBAN checksum. */
72
78
  ibanValid: boolean;
73
79
  amount: number | null;
80
+ /** P2P: expiry of a dynamic QR as local `YYYY-MM-DDTHH:mm`. */
81
+ expiresAt: string | null;
74
82
  /** P2P: bank name. */
75
83
  bankName: string | null;
76
84
  /** P2P: payment description. */
@@ -91,12 +99,22 @@ interface ParsedRaastQr {
91
99
  * scanned by apps such as Easypaisa and JazzCash. Encode the string as a QR
92
100
  * code with any QR library.
93
101
  *
102
+ * A QR with an `amount` is dynamic and needs `expiresAt`; this layout
103
+ * (`01` = `12`, amount in tag 05, expiry in tag 07) matches dynamic QR codes
104
+ * from banking apps and scans in Easypaisa and JazzCash.
105
+ *
94
106
  * @example
95
- * createRaastP2PQr({ iban: 'PK36SCBL0000001123456702', amount: 1500 });
107
+ * createRaastP2PQr({ iban: 'PK36SCBL0000001123456702' });
108
+ * createRaastP2PQr({
109
+ * iban: 'PK36SCBL0000001123456702',
110
+ * amount: 1500,
111
+ * expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000),
112
+ * });
96
113
  *
97
- * @param options - Payee IBAN and optional amount, bank name and description
114
+ * @param options - Payee IBAN and optional amount with expiry, bank name and description
98
115
  * @returns QR payload string
99
- * @throws {RangeError} If the IBAN is invalid or a field is too long
116
+ * @throws {RangeError} If the IBAN is invalid, a field is too long, or an
117
+ * amount is given without `expiresAt`
100
118
  */
101
119
  declare function createRaastP2PQr(options: RaastP2PQrOptions): string;
102
120
  /**
package/dist/raast.js CHANGED
@@ -1,3 +1,3 @@
1
- export { createMerchantQr, createRaastP2PQr, parseRaastQr } from './chunk-44YRK7WO.js';
1
+ export { createMerchantQr, createRaastP2PQr, parseRaastQr } from './chunk-R7UTY3SY.js';
2
2
  import './chunk-4EUKCSLW.js';
3
3
  import './chunk-ENQ7O7VW.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pakdatakit",
3
- "version": "2.1.1",
3
+ "version": "2.1.2",
4
4
  "description": "Production-ready utility toolkit for Pakistani developers — CNIC, phone, WhatsApp, IBAN, postal codes, address parsing, Hijri dates, Roman Urdu, networks, geography, and formatting",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",