pakdatakit 2.2.1 → 2.5.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 (154) hide show
  1. package/DATA.md +512 -34
  2. package/LICENSE +1 -1
  3. package/NOTICE +14 -0
  4. package/README.md +472 -28
  5. package/dist/address.cjs +6 -5
  6. package/dist/address.js +4 -3
  7. package/dist/bills.cjs +19 -0
  8. package/dist/bills.d.cts +63 -0
  9. package/dist/bills.d.ts +63 -0
  10. package/dist/bills.js +2 -0
  11. package/dist/{chunk-4VSGCQ6K.cjs → chunk-2OBKPYJZ.cjs} +3 -3
  12. package/dist/chunk-33GOK7EE.cjs +5312 -0
  13. package/dist/chunk-33QMFE2Z.js +21244 -0
  14. package/dist/chunk-34U2ZMHR.js +194 -0
  15. package/dist/chunk-4GSBHJX6.js +165 -0
  16. package/dist/chunk-5DDHO5Z7.cjs +565 -0
  17. package/dist/chunk-5EY5DQS7.js +51 -0
  18. package/dist/chunk-5RGX4DWF.js +559 -0
  19. package/dist/chunk-5UCRHVI4.cjs +302 -0
  20. package/dist/{chunk-TTARJWGT.js → chunk-7DY26QPN.js} +2 -2
  21. package/dist/chunk-7E7L3NYS.cjs +11 -0
  22. package/dist/{chunk-3ZA265SK.cjs → chunk-AUQFA7EE.cjs} +172 -4
  23. package/dist/{chunk-QKH7W2CC.js → chunk-B7DOQ5QF.js} +6 -5
  24. package/dist/{chunk-HBOZIITD.js → chunk-CADQM4ZN.js} +14 -14
  25. package/dist/chunk-CF6AMRBU.cjs +198 -0
  26. package/dist/chunk-CZOZB4K3.js +61 -0
  27. package/dist/{chunk-3IARSCO6.cjs → chunk-DHOP7LQX.cjs} +25 -14
  28. package/dist/chunk-E2XU6NOW.js +909 -0
  29. package/dist/chunk-E6GWBOKV.cjs +911 -0
  30. package/dist/chunk-E6HSKRAE.js +9 -0
  31. package/dist/chunk-EA3SIHYT.js +313 -0
  32. package/dist/{chunk-33FXHM2E.cjs → chunk-ESKXG7Y6.cjs} +5 -5
  33. package/dist/chunk-I7UUPD3G.cjs +21252 -0
  34. package/dist/{chunk-YPPKY5XZ.js → chunk-IBZPJS4H.js} +26 -15
  35. package/dist/chunk-IDTRFOQW.js +35 -0
  36. package/dist/{chunk-XCXFGTHW.cjs → chunk-J5ZF46NZ.cjs} +14 -14
  37. package/dist/{chunk-NZQ47NWD.js → chunk-KRYHLYN2.js} +1 -1
  38. package/dist/{chunk-RXNYY5K5.js → chunk-LQHM3ADX.js} +172 -4
  39. package/dist/{chunk-HTERSQGF.cjs → chunk-MTS6SVNP.cjs} +4 -4
  40. package/dist/chunk-OTI7HY55.js +297 -0
  41. package/dist/{chunk-6IPPANNX.js → chunk-P7LVE2TF.js} +2 -2
  42. package/dist/{chunk-47P7HILD.cjs → chunk-QFPEFD67.cjs} +9 -8
  43. package/dist/chunk-RZQJAZKC.js +22 -0
  44. package/dist/{chunk-PLDVGOKZ.js → chunk-S274QFFB.js} +2 -2
  45. package/dist/chunk-SF4ECUZ6.cjs +56 -0
  46. package/dist/chunk-SQIHFEXI.cjs +25 -0
  47. package/dist/{chunk-NAJGGUAM.cjs → chunk-TC3VRWZV.cjs} +2 -2
  48. package/dist/{chunk-U7MWHXMF.cjs → chunk-TVL6RDAU.cjs} +4 -4
  49. package/dist/chunk-UYFTXD4P.js +168 -0
  50. package/dist/{chunk-AZV45DMG.js → chunk-V2XE3NCG.js} +2 -2
  51. package/dist/chunk-XCFZKCV2.cjs +37 -0
  52. package/dist/chunk-XOTCIXY6.js +5301 -0
  53. package/dist/chunk-XVEG53NN.cjs +322 -0
  54. package/dist/chunk-YDUXIENX.cjs +172 -0
  55. package/dist/chunk-YPAWNWFD.cjs +168 -0
  56. package/dist/chunk-YQFI7W3I.cjs +65 -0
  57. package/dist/{chunk-NTD4JLDW.cjs → chunk-YTLE5K7G.cjs} +1 -1
  58. package/dist/{chunk-EMH4IP2U.js → chunk-ZRONAQBV.js} +1 -1
  59. package/dist/class-validator.cjs +65 -0
  60. package/dist/class-validator.d.cts +63 -0
  61. package/dist/class-validator.d.ts +63 -0
  62. package/dist/class-validator.js +54 -0
  63. package/dist/cli.js +1 -1
  64. package/dist/courier.cjs +16 -0
  65. package/dist/courier.d.cts +51 -0
  66. package/dist/courier.d.ts +51 -0
  67. package/dist/courier.js +3 -0
  68. package/dist/fbr-invoice.cjs +25 -0
  69. package/dist/fbr-invoice.d.cts +170 -0
  70. package/dist/fbr-invoice.d.ts +170 -0
  71. package/dist/fbr-invoice.js +4 -0
  72. package/dist/geo.cjs +23 -6
  73. package/dist/geo.d.cts +56 -1
  74. package/dist/geo.d.ts +56 -1
  75. package/dist/geo.js +2 -1
  76. package/dist/holidays.cjs +4 -4
  77. package/dist/holidays.js +1 -1
  78. package/dist/iban.cjs +5 -5
  79. package/dist/iban.d.cts +8 -6
  80. package/dist/iban.d.ts +8 -6
  81. package/dist/iban.js +1 -1
  82. package/dist/incometax.cjs +27 -0
  83. package/dist/incometax.d.cts +91 -0
  84. package/dist/incometax.d.ts +91 -0
  85. package/dist/incometax.js +2 -0
  86. package/dist/index.cjs +253 -111
  87. package/dist/index.d.cts +12 -4
  88. package/dist/index.d.ts +12 -4
  89. package/dist/index.js +25 -15
  90. package/dist/input.cjs +9 -9
  91. package/dist/input.js +3 -3
  92. package/dist/joi.cjs +43 -0
  93. package/dist/joi.d.cts +25 -0
  94. package/dist/joi.d.ts +25 -0
  95. package/dist/joi.js +37 -0
  96. package/dist/networks.cjs +3 -3
  97. package/dist/networks.js +2 -2
  98. package/dist/numbers.cjs +6 -6
  99. package/dist/numbers.js +2 -2
  100. package/dist/passport.cjs +11 -0
  101. package/dist/passport.d.cts +27 -0
  102. package/dist/passport.d.ts +27 -0
  103. package/dist/passport.js +2 -0
  104. package/dist/phone.cjs +8 -8
  105. package/dist/phone.js +3 -3
  106. package/dist/postal.cjs +14 -6
  107. package/dist/postal.d.cts +54 -2
  108. package/dist/postal.d.ts +54 -2
  109. package/dist/postal.js +1 -1
  110. package/dist/quality.cjs +25 -0
  111. package/dist/quality.d.cts +62 -0
  112. package/dist/quality.d.ts +62 -0
  113. package/dist/quality.js +8 -0
  114. package/dist/raast.cjs +6 -6
  115. package/dist/raast.js +2 -2
  116. package/dist/salestax.cjs +20 -0
  117. package/dist/salestax.d.cts +106 -0
  118. package/dist/salestax.d.ts +106 -0
  119. package/dist/salestax.js +3 -0
  120. package/dist/superstruct.cjs +41 -0
  121. package/dist/superstruct.d.cts +25 -0
  122. package/dist/superstruct.d.ts +25 -0
  123. package/dist/superstruct.js +39 -0
  124. package/dist/text.cjs +21 -5
  125. package/dist/text.d.cts +90 -1
  126. package/dist/text.d.ts +90 -1
  127. package/dist/text.js +1 -1
  128. package/dist/valibot.cjs +18 -8
  129. package/dist/valibot.d.cts +3 -0
  130. package/dist/valibot.d.ts +3 -0
  131. package/dist/valibot.js +17 -7
  132. package/dist/vehicle.cjs +15 -0
  133. package/dist/vehicle.d.cts +43 -0
  134. package/dist/vehicle.d.ts +43 -0
  135. package/dist/vehicle.js +2 -0
  136. package/dist/whatsapp.cjs +3 -3
  137. package/dist/whatsapp.js +2 -2
  138. package/dist/yup.cjs +18 -8
  139. package/dist/yup.d.cts +3 -0
  140. package/dist/yup.d.ts +3 -0
  141. package/dist/yup.js +17 -7
  142. package/dist/zod.cjs +18 -8
  143. package/dist/zod.d.cts +3 -0
  144. package/dist/zod.d.ts +3 -0
  145. package/dist/zod.js +17 -7
  146. package/package.json +167 -6
  147. package/dist/chunk-34CJGJ67.cjs +0 -1697
  148. package/dist/chunk-4VVFS6FN.cjs +0 -715
  149. package/dist/chunk-E6DT2DWQ.js +0 -1689
  150. package/dist/chunk-GJENL6VK.cjs +0 -22
  151. package/dist/chunk-HUQY2WR5.js +0 -20
  152. package/dist/chunk-JKE4AMSZ.js +0 -47
  153. package/dist/chunk-KEHCTYLO.cjs +0 -52
  154. package/dist/chunk-LIYNKIKS.js +0 -709
package/DATA.md CHANGED
@@ -1,11 +1,16 @@
1
1
  # Data sources
2
2
 
3
3
  PakDataKit's datasets live in `data/` and are generated by
4
- `scripts/generate-data.mjs` (except `networks.json`, `area-codes.json` and
5
- `holidays.json`, which are edited directly). The exported `dataVersion` is the
4
+ `scripts/generate-data.mjs` (except `networks.json`, `area-codes.json`,
5
+ `holidays.json` and `sales-tax-rates.json`, which are edited directly). Two official lists are kept as
6
+ extracted CSV files in `data/sources/` and read by the generator: Pakistan
7
+ Post's post code directory and the 2023 census's administrative units. The exported `dataVersion` is the
6
8
  date the data was last checked.
7
9
 
8
- **Data version: 2026-11-07**
10
+ **Data version: 2026-11-18**
11
+
12
+ The datasets were audited against official sources on 16 November 2026;
13
+ [AUDIT.md](AUDIT.md) has the findings, the fixes made and what is still open.
9
14
 
10
15
  Official bodies (PTA, NADRA, SBP, Pakistan Post) publish few machine-readable
11
16
  lists, so some entries rest on secondary sources. Each section says how sure we
@@ -15,53 +20,139 @@ are. To correct an entry, open an issue or pull request with a source.
15
20
 
16
21
  SBP does not publish a list of IBAN bank codes, and IBAN codes do not always
17
22
  match SWIFT BIC prefixes (e.g. Silkbank is `SAUD`). Codes are therefore checked
18
- against real IBANs.
19
-
20
- - **Confirmed from real IBANs:** most commercial and microfinance banks, from
21
- SBP's account lists for the 2022 flood relief fund and the 2023 Türkiye–Syria
22
- earthquake relief fund, plus charity donation pages (TCF, Alkhidmat). This
23
- includes `KHBL` (Khushhali), `JCMA` and `WMBL` (Mobilink Bank), `TMFB`
24
- (easypaisa), `FMFB` (HBL Microfinance), `FINC` (ABHI), `UMBL`, `NRSP`,
25
- `APNA`, `BKCH`, `ICBK`, `CITI`, `SUMB` (Bank Makramah), `SAMB`, `SMES` and
26
- `SAUD`.
23
+ against real IBANs. Names follow SBP's lists of regulated institutions
24
+ (https://www.sbp.org.pk/sbp-regulated-institutions/commercial-banks and
25
+ .../microfinance-banks, retrieved 2026-11-16), with a former name kept in
26
+ brackets where people still search for it.
27
+
28
+ - **Confirmed from IBANs printed by SBP:** 35 codes, from SBP's list of dam
29
+ fund accounts at every bank
30
+ (https://archive.sbp.org.pk/notifications/FD/DamFund/Detail-1.pdf, undated,
31
+ about 2018, retrieved 2026-11-16): `AIIN`, `ABPA`, `ASCM`, `ALFH`, `BAHL`,
32
+ `BKIP`, `KHYB`, `BPUN`, `BKCH`, `CITI`, `DEUT`, `DUIB`, `FAYS`, `FWOM`,
33
+ `HABB`, `MPBL`, `ICBK`, `JSBL`, `MUCB`, `MCIB`, `MEZN`, `NBPA`, `SAMB`,
34
+ `SAUD`, `SIND`, `SMES`, `SONE`, `SCBL`, `SUMB`, `UNIL`, `ZTBL` (Zarai
35
+ Taraqiati Bank), `TMFB`, `WMBL`, `FMFB` and `SMFB` (Sindh Microfinance
36
+ Bank). The same list shows an `SBPP` IBAN in use. `ZTBL` and `SMFB` were
37
+ added on 2026-11-16 from this list. (It prints ICBC's IBAN with a digit `1`
38
+ for the `I`; the checksum is only valid with `ICBK`.)
39
+ - **Also confirmed from IBANs printed by SBP:** `KHBL` (Khushhali), `JCMA`
40
+ (Mobilink Microfinance Bank), `FINC` (ABHI, as FINCA), `UMBL`, `NRSP` and
41
+ `APNA`, from SBP's account lists for the Prime Minister's Flood Relief Fund
42
+ 2022 (https://archive.sbp.org.pk/IBANs-of-PM-Flood-Relief-Fund.pdf) and the
43
+ 2023 relief fund for Türkiye and Syria
44
+ (https://archive.sbp.org.pk/ReliefFund-Turkiye.pdf), both retrieved
45
+ 2026-11-16. That makes 41 codes confirmed by SBP documents.
27
46
  - **Confirmed from published IBANs on smaller sites:** `SADA` (SadaPay), `NAYA`
28
47
  (NayaPay).
29
48
  - **Confirmed from real account IBANs shared by a maintainer:** `RQMI` (Raqami
30
49
  Islamic Digital Bank) and `MSHQ` (Mashreq Bank Pakistan), both digital banks.
31
- - **Likely, not confirmed by a real IBAN:** `DEUT` (Deutsche Bank), `SBPP`
32
- (State Bank of Pakistan).
33
- - **Not included, because no code could be confirmed:** HugoBank (in pilot,
34
- not yet issuing IBANs), KT Bank (reportedly renamed Buraq Bank), LOLC Microfinance
35
- (formerly Pak Oman), Zarai Taraqiati Bank and Bank of AJK.
50
+ - **Legacy codes with no official source:** `MCBL`, `NBPB`, `TAMW` and `NIBP`.
51
+ - **Not included, because no code could be confirmed:** Punjab Provincial
52
+ Cooperative Bank, LOLC Microfinance Bank (formerly Pak Oman), Halan
53
+ Microfinance Bank (formerly Advans), ASA Microfinance Bank, the EMIs Finja,
54
+ Akhtar Fuiou Technologies, E-Processing Systems, Wemsol and YAP Pakistan,
55
+ HugoBank, KT Bank and Bank of AJK. A second search on 2026-11-16 (SBP's
56
+ relief-fund lists and each institution's own website) found no printed IBAN
57
+ for any of them.
58
+ - **Types** follow SBP's groups on its list of regulated institutions:
59
+ "Public Sector Commercial Banks" are `public-sector` (National Bank of
60
+ Pakistan, Sindh Bank, The Bank of Khyber, The Bank of Punjab), "Local
61
+ Private Banks" are `commercial`, and "Islamic", "Foreign", "Specialized"
62
+ and "Digital" banks have the type of the same name.
63
+ - **Spelling.** Names use each bank's own styling ("Bank Alfalah Limited",
64
+ "Bank Al Habib Limited", "BankIslami Pakistan Limited", "Citibank N.A.
65
+ Pakistan"). SBP's list spells some differently, and not consistently
66
+ ("Bank Al-Falah Limited", "Bank Al-Habib Limited", "Al-Baraka Bank
67
+ (Pakistan) Limited", "Bank Islami Pakistan Limited", "Citi Bank N.A",
68
+ "Industrial & Commercial Bank of China", "Allied Bank limited"), so it is
69
+ recorded here and not copied.
70
+ - **Closed:** `SMES` → "SME Bank Limited (in liquidation)", `active: false`.
71
+ SBP cancelled its licence and de-scheduled it on 17 March 2025
72
+ (https://archive.sbp.org.pk/notifications/bprd/2025/ntf6.htm). `NIBP` was
73
+ de-scheduled on 7 July 2017 on its merger into MCB Bank
74
+ (https://archive.sbp.org.pk/notifications/bprd/2017/ntf2.htm).
36
75
  - **Merged or renamed** banks keep their code with the current name, e.g.
37
- `SAUD` → "Silkbank Limited (merged into United Bank Limited)".
76
+ `SAUD` → "Silkbank Limited (merged into United Bank Limited)" (de-scheduled
77
+ by SBP on 10 March 2025,
78
+ https://archive.sbp.org.pk/notifications/bprd/2025/ntf4.htm) and `TMFB` →
79
+ "Easypaisa Bank Limited" (a scheduled bank from 23 January 2025,
80
+ https://archive.sbp.org.pk/notifications/bprd/2025/ntf1.htm).
38
81
 
39
82
  ## Mobile networks (`networks.json`)
40
83
 
41
- `03XX` prefixes and the operator each was originally allocated to. PTA does not
42
- publish an allocation table; prefixes are cross-checked with Google
84
+ `03XX` prefixes and the operator each was originally allocated to. PTA has no
85
+ current operator-by-prefix table. Its National Numbering Plan 2008 paper
86
+ (https://www.pta.gov.pk/assets/media/nnp_08_final.pdf, retrieved 2026-11-16)
87
+ gives the two-digit allocations: 30 Mobilink (Jazz), 31 Paktel (now Zong), 32
88
+ Warid (now Jazz), 33 Ufone, 34 Telenor, 35 SCO, 36 Instaphone, and 37 to 39
89
+ "for future use". Individual prefixes are cross-checked with Google
43
90
  libphonenumber and operator announcements.
44
91
 
45
92
  - `0329` (Jazz) and `0355` (SCO) included.
46
- - `0370`–`0371` (Zong) included; `0372`–`0379` are **not**, as no allocation or
47
- use was found.
93
+ - `0370`–`0371` (Zong) included, from libphonenumber only. **Unverified:**
94
+ two searches in November 2026 (PTA's annual reports for 2021 to 2024, its
95
+ numbering documents and licensee list, the ITU page for Pakistan and
96
+ zong.com.pk) found no official document that gives 037x to an operator. `0372`–`0379` are **not**
97
+ included, as no allocation or use was found.
48
98
  - `0364` (Instaphone, licence cancelled in 2008) is not included.
49
- - `034x` is labelled Telenor, the original allocation; Telenor Pakistan merged
50
- into PTML (Ufone) in 2026. With number portability, the current operator can
51
- differ for any prefix.
99
+ - `034x` is labelled Telenor, the original allocation. Telenor Pakistan was
100
+ merged into PTML (Ufone) in July 2026: PTCL announced the "successful
101
+ completion of the amalgamation" on 2 July 2026
102
+ (https://ptcl.com.pk/Home/PressReleaseDetail/?ItemId=934&linkId=130,
103
+ retrieved 2026-11-16). The label is kept because the dataset records the
104
+ operator a prefix was allocated to, no new brand has been announced
105
+ officially (PTCL still writes "Ufone 5G"), and PTA's own pages still list
106
+ Telenor Pakistan. With number portability, the current operator can differ
107
+ for any prefix.
52
108
 
53
109
  ## Landline area codes (`area-codes.json`)
54
110
 
55
- From PTCL's national dialling-code list, cross-checked with libphonenumber's
56
- geocoding data. Muzaffarabad, Mirpur and Gilgit codes are left out because only
57
- third-party sources give them. Number patterns in `numbers.ts` come from
58
- libphonenumber's PK metadata (v9.0.41).
111
+ 114 codes, from the numbering plan PTA sent to the ITU on 9 November 2021
112
+ (https://www.itu.int/dms_pub/itu-t/oth/02/02/T02020000A10002PDFE.pdf,
113
+ retrieved 2026-11-16), which lists every code with its district. The 73 codes
114
+ held before November 2026 came from PTCL's national dialling-code list
115
+ (https://ptcl.com.pk/Info/National-Dialing-Codes) and all appear in the ITU
116
+ plan with the same districts.
117
+
118
+ - **Added 2026-11-16 from the ITU plan:** 18 codes in Balochistan (`822`
119
+ Zhob to `856` Awaran), 8 in Khyber Pakhtunkhwa (`924` Khyber and Mohmand,
120
+ `932` Malakand, `939` Buner, `942` Bajaur, `944` Upper Dir, `945` Lower
121
+ Dir, `965` South Waziristan, `996` Shangla), 7 in Gilgit-Baltistan (`5811`
122
+ Gilgit to `5817` Astore) and 8 in Azad Jammu and Kashmir (`5821` Neelum to
123
+ `5828` Bhimber).
124
+ - Names are the districts the plan gives, spelt as in `districts.json` so
125
+ that `getAreaCode` finds them: the plan writes "Neelum", "Sudonthi",
126
+ "Bhimer" and "K.Abdullah / Pishin" for Neelam, Sudhnuti, Bhimber and Killa
127
+ Abdullah and Pishin. `832` is listed there as Bolan, the former name of
128
+ Kachhi district; both names find it. For the two districts split since
129
+ 2021, the successors are listed with the plan's name: `835` Dera Bugti,
130
+ North Dera Bugti and South Dera Bugti; `965` South Waziristan, Lower South
131
+ Waziristan and Upper South Waziristan.
132
+ - PTCL's own list differs for Azad Jammu and Kashmir (Muzaffarabad "58",
133
+ Kotli "574") and has no Mirpur or Gilgit entry. The ITU plan is the newer
134
+ list from PTA, so it is followed.
135
+ - **Number lengths** are not taken from the ITU plan (its length table could
136
+ not be read reliably). The patterns in `numbers.ts` come from
137
+ libphonenumber's PK metadata (v9.0.41), which already accepted numbers in
138
+ all 41 added codes: ten digits in all for the `58xx` codes, so a four-digit
139
+ code is followed by six digits.
59
140
 
60
141
  ## Districts (`districts.json`)
61
142
 
62
143
  177 districts as of October 2026: Punjab 41, Sindh 30, Khyber Pakhtunkhwa 40,
63
144
  Balochistan 41, Gilgit-Baltistan 14, Azad Jammu and Kashmir 10, Islamabad 1.
64
145
 
146
+ > **Unverified: Central Dir, Allai and Paharpur** (Khyber Pakhtunkhwa). They
147
+ > rest on a news report of January 2026, not on a notification. Official
148
+ > pages updated in November 2026 do not show them: Malakand Division lists
149
+ > 10 districts without Central Dir (cmd.kp.gov.pk), Hazara Division lists 8
150
+ > without Allai (chd.kp.gov.pk), and the KP Bureau of Statistics'
151
+ > Development Statistics 2026 has Allai as a tehsil of Batagram and Paharpur
152
+ > as a tehsil of Dera Ismail Khan (all retrieved 2026-11-16). They are kept
153
+ > until a notification settles it either way. Nine more districts are also
154
+ > not confirmed on an official page; see the end of this section.
155
+
65
156
  - **Khyber Pakhtunkhwa** (APP, January 2026: "increased to 40"): Lower and Upper
66
157
  South Waziristan (2022), Central Dir and Allai (January 2023), Paharpur
67
158
  (November 2025), Bar Swat (January 2026; reported as "Upper Swat" before
@@ -78,28 +169,415 @@ Balochistan 41, Gilgit-Baltistan 14, Azad Jammu and Kashmir 10, Islamabad 1.
78
169
  so current names are kept.
79
170
  - Former names (Quetta, Dera Bugti, Upper Dera Bugti, South Waziristan, Upper
80
171
  Swat) still resolve in `getDistrictProvince`.
172
+ - **Official confirmation, checked 2026-11-16** (details in AUDIT.md,
173
+ section 9). Confirmed on official pages: Murree, Talagang, Wazirabad, Kot
174
+ Addu and Taunsa (Punjab Board of Revenue list); Lower and Upper South
175
+ Waziristan and Hub (Election Commission delimitation report, 2023); Bar
176
+ Swat (Malakand Division's website); Usta Muhammad, Barshore and Tump
177
+ (Balochistan budget documents, June 2026). **Not confirmed on any official
178
+ page that could be read:** Central Dir, Allai and Paharpur (Khyber
179
+ Pakhtunkhwa's divisional websites and its Development Statistics 2026
180
+ still show Allai and Paharpur as tehsils and list no Central Dir); Quetta
181
+ East and West, North and South Dera Bugti and Wadh (Balochistan); and
182
+ Darel, Tangir, Gupis-Yasin and Roundu (Gilgit-Baltistan's 2024-25
183
+ development programme treats them as sub-divisions). These stay in the
184
+ dataset on the strength of the notifications and reports cited above, and
185
+ are the entries most likely to need correcting.
81
186
 
82
187
  ## Cities (`cities.json`)
83
188
 
84
189
  District headquarters and major towns, plus every city that has a postal code
85
190
  in `postal-codes.json`, each mapped to its province.
86
191
 
87
- ## Postal codes (`postal-codes.json`)
192
+ ## Postal codes (`postal-codes.json`, `post-offices.json`)
193
+
194
+ Both files come from Pakistan Post's "Post Code Directory of Delivery Post
195
+ Offices" (Part I), a 45-page PDF dated February 2021
196
+ (https://www.pakpost.gov.pk/images/national%20post%20code%20directory.pdf,
197
+ retrieved 2026-11-16). Its office name, code, account office and province
198
+ columns are extracted to `data/sources/pakpost-delivery-post-offices.csv`
199
+ (2,564 rows), and `scripts/generate-data.mjs` builds both files from it.
200
+
201
+ - **`post-offices.json`** (2,560 entries, for `getPostOffice` and
202
+ `searchPostOffices`): every office, as `code`, `office` (the directory's
203
+ name in title case), `town`, `district` and `province`. The directory
204
+ lists four codes twice, for the same place under two spellings (`22190`,
205
+ `40520`, `56320`, `63050`); the first row is kept.
206
+ - **`postal-codes.json`** (457 entries, for `getCityByPostalCode`,
207
+ `getPostalCode`, `getPostalCodes`, `getPostalAreas` and
208
+ `searchPostalCodes`): only the offices that belong to a city in
209
+ `cities.json`, as `city`, `postalCode`, `area` (the office name),
210
+ `province`, and `district` and `primary` where they apply.
211
+ - **Which city an office belongs to.** The directory has no city column, so
212
+ this is worked out:
213
+ 1. the 110 entries checked by hand before the import keep their city
214
+ (including the eight codes corrected in November 2026);
215
+ 2. an office named after a city in `cities.json`, in the same province,
216
+ belongs to that city ("ABBOTTABAD GPO" → Abbottabad);
217
+ 3. every office under the Karachi, Lahore and Islamabad account offices
218
+ belongs to that city;
219
+ 4. an office whose name starts or ends with the city of its own account
220
+ office belongs to that city ("GULISTAN COLONY, FAISALABAD").
221
+
222
+ Any other office is in a town or village that is not on the city list. It
223
+ is only in `post-offices.json`, where `town` is the office's own name
224
+ ("Dulmial"); `getCityByPostalCode` returns `null` for it.
225
+
226
+ - **District** is given only where the town is the headquarters a district
227
+ is named after (349 offices). An account office can serve several
228
+ districts, so it is not used to guess one.
229
+ - **Province** is the directory's, with its spelling normalised ("Azad
230
+ Kashmir" → Azad Jammu and Kashmir, "Federal Capital" → Islamabad Capital
231
+ Territory, and the misprints "Punjba" and "SIndh").
232
+ - **Primary.** `getPostalCode(city)` returns the hand-checked code for the 95
233
+ cities that had one. For 63 more cities it returns the code of the office
234
+ named "<city> GPO", or else the office named after the city.
235
+ - **Names** are converted from the directory's capitals to title case; its
236
+ spellings are kept, including misprints ("Islamabad Primr Minister
237
+ Sectt.").
238
+ - **Not included:** the 740 or so non-delivery post offices of Part II
239
+ (https://www.pakpost.gov.pk/images/LIST%20OF%20NON%20DELIVERY%20POs.pdf).
240
+ - The directory is dated 2021. Pakistan Post's web table
241
+ (https://www.pakpost.gov.pk/postcodes.php) is missing many offices, so it
242
+ is not the source; it was used for the spot-check below.
243
+
244
+ ## Divisions and tehsils (`divisions.json`, `tehsils.json`)
245
+
246
+ From Table 1 of the 2023 census (Pakistan Bureau of Statistics), which lists
247
+ every administrative unit with its area and population. Retrieved 2026-11-16:
248
+
249
+ - tehsils by district:
250
+ https://www.pbs.gov.pk/wp-content/uploads/census_tables/tables/table_1_punjab_districts.pdf
251
+ and the same file name for `sindh`, `kp` and `balochistan`, plus
252
+ `table_1_islamabad.pdf`;
253
+ - districts by division: `table_1_punjab_province.pdf` and the same for the
254
+ other three provinces.
255
+
256
+ The rows are extracted to `data/sources/census-2023-admin-units.csv`. The
257
+ totals match the census report's Table 1.1: **30 divisions, 136 districts and
258
+ 591 tehsil-level units** (Punjab 146, Sindh 138, Khyber Pakhtunkhwa 148,
259
+ Balochistan 158, Islamabad 1).
88
260
 
89
- Principal post office codes for major cities (109 entries). Pakistan Post has no
90
- downloadable dataset, only a lookup tool, so coverage is limited.
261
+ - **Tehsil-level units** are what the census counts: 306 tehsils, 107
262
+ talukas (Sindh), 134 sub-divisions (Karachi, the merged districts of Khyber
263
+ Pakhtunkhwa and much of Balochistan), 43 sub-tehsils (Balochistan) and one
264
+ de-excluded area (Rajanpur). Each entry has a `type`.
265
+ - **Census district.** Every tehsil has a `censusDistrict`: the district it
266
+ was in at the census. The census had 136 districts; `districts.json` has
267
+ the 177 of today. Three census districts have since been split and are no
268
+ longer district names: Quetta, Dera Bugti and South Waziristan.
269
+ - **Current district.** `currentDistrict` is the same as `censusDistrict`
270
+ for the 119 census districts that have not lost territory to a new
271
+ district. For tehsils of the 17 that have (Rawalpindi, Chakwal,
272
+ Gujranwala, Muzaffargarh, Dera Ghazi Khan, South Waziristan, Upper Dir,
273
+ Batagram, Dera Ismail Khan, Swat, Lasbela, Jaffarabad, Quetta, Dera Bugti,
274
+ Pishin, Kech and Khuzdar) it is set only where an official
275
+ source confirms where the tehsil is now, and is `null` otherwise.
276
+ - **Confirmed (Punjab, all 25 tehsils of the five parent districts):**
277
+ Murree and Kotli Sattian are in Murree district; Talagang and Lawa in
278
+ Talagang; Wazirabad in Wazirabad; Kot Addu and Chowk Sarwar Shaheed in
279
+ Kot Addu; Taunsa and Koh-e-Suleman in Taunsa; the others stay in
280
+ Rawalpindi, Chakwal, Gujranwala, Muzaffargarh and Dera Ghazi Khan.
281
+ Source: the Board of Revenue's list of tehsils by district as on 31
282
+ December 2023, in the Punjab Bureau of Statistics' Statistical Pocket
283
+ Book 2025
284
+ (https://bos.punjab.gov.pk/system/files/Statistical%20Pocket%20Book%202025%20Final.pdf,
285
+ retrieved 2026-11-16). That list also has tehsils created since the
286
+ census (Vehova, Alipur Chatha and others), which are not in this data.
287
+ - **Not confirmed, so `null` (78 tehsils):** the tehsils of Swat, Upper
288
+ Dir, Batagram, Dera Ismail Khan and South Waziristan (Khyber
289
+ Pakhtunkhwa) and of Quetta, Dera Bugti, Pishin, Kech, Khuzdar, Lasbela
290
+ and Jaffarabad (Balochistan). No official list of tehsils by district
291
+ for today's districts could be read for either province.
292
+ - **Divisions** are the census's 30. Divisions created since (Gujrat in
293
+ Punjab, listed on punjab.gov.pk) are not included, and districts created
294
+ since the census have no division here.
295
+ - **Not covered:** Azad Jammu and Kashmir (3 divisions, 10 districts, 32
296
+ tehsils per "AJK at a Glance 2023") and Gilgit-Baltistan. The census tables
297
+ have no rows for them, and no official list of their tehsils was found.
298
+ - **Spelling** is the census's, in title case, with district names changed
299
+ to ours ("UMER KOT" → Umerkot, "KAMBAR SHAHDAD KOT" → Qambar Shahdadkot,
300
+ "TORGHAR" → Tor Ghar).
301
+ - **Repaired by hand.** The letters "LLA" are missing from four names in the
302
+ district tables' text (the PDF prints them, but they do not come out of
303
+ it). They are restored in `data/sources/census-2023-admin-units.csv`:
304
+
305
+ | Census text | Restored to | Evidence |
306
+ | -------------- | --------------- | -------------------------------------------------------- |
307
+ | `AI` | Allai | Allai tehsil of Batagram; KP Development Statistics 2026 |
308
+ | `KAR KAHAR` | Kallar Kahar | Punjab Board of Revenue tehsil list ("Kalar Kahar") |
309
+ | `KAR SAYADDAN` | Kallar Sayaddan | Punjab Board of Revenue tehsil list ("Kallar Syedan") |
310
+ | `TANDO AHYAR` | Tando Allahyar | The census's own province table prints "TANDO ALLAHYAR" |
91
311
 
92
312
  ## Public holidays (`holidays.json`)
93
313
 
94
314
  Eid ul Fitr, Eid ul Adha, Ashura and Eid Milad un Nabi dates actually observed
95
- in 2020–2026, from Cabinet Division notifications and SBP circulars; each entry
96
- has a `source` URL. Later years are estimated from the tabular Hijri calendar
315
+ in 2020–2026; each entry has a `source` URL, and every source is a Cabinet
316
+ Division notification or an SBP circular letter (checked 2026-11-16; the last
317
+ seven news links, for 2020–2023, were replaced that day with the SBP circular
318
+ that states the same dates). Later years are estimated from the tabular Hijri calendar
97
319
  and marked `estimated: true`. Fixed-date holidays follow the years they applied
98
320
  in (e.g. Iqbal Day restored in 2022, Youm-e-Takbeer from 2024).
99
321
 
322
+ ## Sales tax rates (`sales-tax-rates.json`)
323
+
324
+ Standard rates only, from 1 July 2019, each with the period it applied, the
325
+ law that sets it and an official document. Edited directly. Reduced, higher
326
+ and sector rates (telecom at 19.5%, restaurants paid by card, Third Schedule
327
+ goods, further tax and so on) are not included. All documents retrieved
328
+ 2026-11-18.
329
+
330
+ | Tax | Rate | Applied | Source |
331
+ | ------------------------------------------- | ---- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
332
+ | Goods, federal (FBR) | 17% | to 22 February 2023 | Sales Tax Act 1990, s. 3(1); the Finance (Supplementary) Act 2023 replaces "seventeen" with "eighteen" (https://download1.fbr.gov.pk/Docs/20232231921422957Finance(Supplementary)Act,2023.pdf) |
333
+ | Goods, federal (FBR) | 18% | from 23 February 2023 | The same Act, in force at once on 23 February 2023; FBR Circular 01/2023; still 18% in FBR's Sales Tax Act "updated up to 30.06.2026" (https://download1.fbr.gov.pk/Docs/20267171373418951SalesTaxAct1990updatedupto30.06.2026.pdf) |
334
+ | Services, Punjab (PRA) | 16% | whole period | Punjab Sales Tax on Services Act 2012, s. 2(41A) ("Standard Rate" means sixteen percent) and Second Schedule, 17th edition 2026-27 (https://pra.punjab.gov.pk/Downloads/THE-PUNJAB-SALES-TAX-ON-SERVICES-ACT-2012-17th-Edition-2026-2027.pdf) |
335
+ | Services, Sindh (SRB) | 13% | to 30 June 2024 | The Sindh Finance Act 2024 (Sindh Act II of 2024) replaces "13%" with "15%" (https://www.pas.gov.pk/uploads/acts/Sindh%20Act%20No.II%20of%202024.pdf) |
336
+ | Services, Sindh (SRB) | 15% | from 1 July 2024 | The same Act, from 1 July 2024; s. 8(1) of the Sindh Sales Tax on Services Act 2011 as consolidated for 2025-26 (https://www.srb.gos.pk/srb/wp-content/uploads/2026/01/Sindh-Sales-Tax-Act-2011-25-26-2.pdf) |
337
+ | Services, Khyber Pakhtunkhwa (KPRA) | 15% | whole period | KP Finance Act 2019, Second Schedule, from 1 July 2019 (https://kpcode.kp.gov.pk/uploads/The_Khyber_Pakhtunkhwa_Finance_Act_2019.pdf); KP Sales Tax on Services Act 2022, s. 9(1), updated to the Finance Act 2026 (https://kpra.gov.pk/wp-content/uploads/2026/09/KPSTSA-2022-Updated-Finance-act-2026.pdf) |
338
+ | Services, Balochistan (BRA) | 15% | whole period | Balochistan Sales Tax on Services Act 2015, s. 10(1) and Second Schedule, consolidated to the Finance Act 2024 (https://bra.gob.pk/NewsDirectory/2015_BSTS_Act_Ver01.pdf); BRA's FAQ (https://bra.gob.pk/FAQs.aspx) |
339
+ | Services, Islamabad Capital Territory (FBR) | 16% | to 30 June 2022 | ICT (Tax on Services) Ordinance 2001, Schedule, Table 1; the Finance Act 2022 replaces "Sixteen" with "Fifteen" (https://fbr.gov.pk/Budget2022-23/FinanceAct/Finance-Act-2022.pdf) |
340
+ | Services, Islamabad Capital Territory (FBR) | 15% | from 1 July 2022 | The same Act, from 1 July 2022; FBR's ICT Ordinance "updated up to 30.06.2025" (https://download1.fbr.gov.pk/Docs/2025711172945966ICTOUpdatedupto30.06.2025.pdf) |
341
+
342
+ How sure we are:
343
+
344
+ - **Verified** from the Act or Finance Act itself: every change of rate and
345
+ every current rate.
346
+ - **The earlier rates (federal 17%, Sindh 13%, ICT 16%)** are confirmed as the
347
+ rate the amending Act replaced. That they applied all the way back to
348
+ 1 July 2019 rests on finding no amendment in between, not on a 2019
349
+ consolidation.
350
+ - **The federal rise to 18%** was first notified by S.R.O. 179(I)/2023 of
351
+ 14 February 2023, which is not on FBR's website; the dataset uses
352
+ 23 February 2023, when the Finance (Supplementary) Act 2023 took effect.
353
+ - **Balochistan for 2025-26 and 2026-27**: BRA's consolidated Act goes up to
354
+ the Finance Act 2024, and BRA's own FAQ, which is undated, still gives 15%.
355
+ The Balochistan Finance Acts 2025 and 2026 were not found online.
356
+ - **Islamabad Capital Territory after 30 June 2025**: FBR has not published a
357
+ 2026 consolidation; the Finance Act 2026 does not amend the ICT Ordinance.
358
+ - In Balochistan, ICT and (before 2022) Khyber Pakhtunkhwa the law has no
359
+ single "standard rate": it is the rate on almost every line of the
360
+ Schedule, which BRA's FAQ and FBR's circular call the standard rate.
361
+
362
+ ## Income tax on salary (`income-tax-slabs.json`)
363
+
364
+ The salaried rate table for each tax year: Division I of Part I of the First
365
+ Schedule to the Income Tax Ordinance 2001, clause (2), which applies where
366
+ salary is more than 75% of taxable income. Edited directly. Each year was
367
+ read from FBR's own consolidated Ordinance for that year, and checked against
368
+ the next year's consolidation, whose footnote quotes the table it replaced.
369
+ Every band's fixed amount equals the previous band's fixed amount plus its
370
+ rate on its width (the tests check this). All documents retrieved 2026-11-18.
371
+
372
+ | Tax year | Law | Source |
373
+ | -------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
374
+ | 2020 (2019-20) | Finance Act 2019 | https://download1.fbr.gov.pk/Docs/20199191692232848IncomeTaxOrdinance,2001amendedupto30-06-2019.pdf |
375
+ | 2021 (2020-21) | Finance Act 2019, unchanged by Finance Act 2020 | https://download1.fbr.gov.pk/Docs/202011414113915861I.T.OrdinanceAmendedupto(30-06-2020).pdf |
376
+ | 2022 (2021-22) | Finance Act 2019, unchanged by Finance Act 2021 | https://download1.fbr.gov.pk/Docs/20217141672549772IncomeTaxOrdinanceAmendedupto30.06.2021.pdf |
377
+ | 2023 (2022-23) | Finance Act 2022 | https://download1.fbr.gov.pk/Docs/202412215123222278IncomeTaxOrdinanceAmendedupto30.06.2022.pdf |
378
+ | 2024 (2023-24) | Finance Act 2023 | https://download1.fbr.gov.pk/Docs/202412215122448762IncomeTaxOrdinance,2001Amendedupto30.06.2023.pdf |
379
+ | 2025 (2024-25) | Finance Act 2024 | https://download1.fbr.gov.pk/Docs/2024751675120641IncomeTaxOrdinance,2001-amended-upto30.06.2024.pdf |
380
+ | 2026 (2025-26) | Finance Act 2025 | https://download1.fbr.gov.pk/Docs/2025881983148210Income-Tax-Ordinance,-2001-Amended-upto-31.07.2025.pdf |
381
+ | 2027 (2026-27) | Finance Act 2026 | Finance Act 2026 (primary) and two further sources, listed below |
382
+
383
+ Tax year 2027 has three sources, all retrieved 2026-11-18:
384
+
385
+ 1. **Primary: the Finance Act, 2026**, Gazette of Pakistan (Extraordinary),
386
+ Part I, 26 June 2026
387
+ (https://download1.fbr.gov.pk/Docs/20266291261044366FinanceAct2026.pdf).
388
+ - Section 5(44)(a)(i) substitutes the table in clause (2) of Division I,
389
+ Part I, First Schedule (Gazette page 580). Its eight bands, fixed
390
+ amounts and rates match `income-tax-slabs.json` exactly.
391
+ - Section 1(2) brings the Act into force on 1 July 2026, the first day of
392
+ tax year 2027.
393
+ - Section 5(2)(b) replaces the 9% salaried surcharge in the proviso to
394
+ section 4AB with "no surcharge shall be payable".
395
+ - This is the URL in the dataset's `source` field for 2027.
396
+ 2. **FBR's explanation: Circular No. 02 of 2026-27 (Income Tax)**, C. No.
397
+ 1(50)S(ITP)/2026, 8 September 2026
398
+ (https://download1.fbr.gov.pk/Docs/202698139527880CircularNo.2of2026-27.pdf).
399
+ - Paragraph 7 restates the same table.
400
+ - Paragraph 8 confirms that the 9% surcharge on salaried individuals is
401
+ withdrawn, while the 10% surcharge on other individuals and associations
402
+ of persons continues.
403
+ - The circular does not name a tax year, which is why the commencement
404
+ comes from the Act.
405
+ 3. **FBR's consolidated Ordinance**
406
+ (https://download1.fbr.gov.pk/Docs/2026724177725705IncomeTaxOrdinanace2001.pdf).
407
+ It prints the same table, with a footnote quoting the 2026 table it
408
+ replaced.
409
+
410
+ How sure we are, and what is left out:
411
+
412
+ - **Verified** from FBR's consolidated Ordinance for each year. For 2027 the
413
+ table was also checked against the Finance Act, 2026 as gazetted and FBR
414
+ Circular No. 02 of 2026-27. For earlier years the Finance Act texts
415
+ (Gazette) were not read; FBR's consolidations are the source.
416
+ - **Not applied** (out of scope): the surcharge under section 4AB (from tax
417
+ year 2025: 10% of the tax over Rs 10 million of taxable income; 9% for
418
+ salaried individuals in 2026; none for salaried individuals in 2027), tax
419
+ credits, exemptions, the separate rate for pension from a former employer
420
+ (2026 onwards: 0% up to Rs 10 million, 5% above), and withholding
421
+ adjustments.
422
+ - Tax is rounded half up to the paisa; the Ordinance's own rounding to whole
423
+ rupees is left to the caller.
424
+
425
+ ## Urdu alphabetical order (no dataset)
426
+
427
+ `compareUrdu` follows the Unicode CLDR collation tailoring for Urdu
428
+ (`common/collation/ur.xml`, "standard", CLDR release 49, unchanged since
429
+ 2015), https://github.com/unicode-org/cldr/blob/release-49/common/collation/ur.xml,
430
+ retrieved 2026-11-18. Its own reference is the CRULP/PAN Localization paper
431
+ "Urdu Encoding and Collation Sequence". The government's National Language
432
+ Promotion Department (https://nlpd.gov.pk) does not publish a sort order
433
+ online, so CLDR is the order cited. The implementation was checked against
434
+ ICU's `ur` collator (Node.js, CLDR 48, identical rules) on 200,000 random
435
+ pairs of Urdu words.
436
+
437
+ ## Electricity and gas bill numbers
438
+
439
+ No dataset: `parseElectricityRef` and `validateGasConsumerNumber` check the
440
+ formats that the utilities' own bill pages ask for. All pages were retrieved
441
+ on 2026-11-18.
442
+
443
+ - **DISCO reference number**: 14 digits, with urban or rural chosen
444
+ separately (`U`/`R`), on PITC's bill pages for all 11 companies
445
+ (https://bill.pitc.com.pk/lescobill and the same for gepco, fesco, iesco,
446
+ mepco, pesco, hazeco, hesco, sepco, qesco and tesco). PITC's illustration
447
+ groups it as 2 + 5 + 7 digits, which is how `formatted` shows it.
448
+ - **DISCO customer ID**: 10 digits, or 11 for LESCO (the same PITC pages).
449
+ - **K-Electric account number**: "13 digits KE Account Number starting from
450
+ 04000" (https://beta.ke.com.pk/know-your-area-status/ and
451
+ https://ke.com.pk/bills-e-payments/). K-Electric says its contract and
452
+ consumer numbers are for its internal use, so they are not accepted.
453
+ - **SNGPL consumer number**: 11 digits
454
+ (https://www.sngpl.com.pk/login.jsp?mdids=85).
455
+ - **SSGC customer number**: "10-digit Customer Number"
456
+ (https://viewbill.ssgc.com.pk/web/).
457
+ - **Not published**: what the reference number's digit groups mean, which
458
+ digits belong to which DISCO, and any check digit. So `disco` is `null`
459
+ except for K-Electric, and only the format is checked. IESCO also notes
460
+ that reference numbers can change
461
+ (https://www.iesco.com.pk/search-reference-number).
462
+
463
+ ## Couriers
464
+
465
+ No dataset: `mapCourierStatus` maps only the statuses a courier documents
466
+ publicly. All pages were retrieved on 2026-11-18.
467
+
468
+ - **PostEx**: "Merchant API Integration Guide", version M- v4.1.9 (undated):
469
+ order status IDs 1 to 9 and 15 to 18 (§3.15) and tracking history codes
470
+ 0001 to 0008 and 0013 (§3.8). The guide is PostEx's own, but it is hosted
471
+ on Amazon S3
472
+ (https://merchant-api-guide.s3.ap-south-1.amazonaws.com/PostEx-COD_API_Integration_Guide_V4.1.9.pdf)
473
+ and not linked from postex.pk. Its history codes 0002, 0006 and 0007 all
474
+ read "Returned"; "Package on Root" is mapped as written and also as "on
475
+ route".
476
+ - **Leopards**: only "Returned to Shipper", defined in its e-commerce FAQ
477
+ (https://ecom.leopardscourier.com/faqs). Its API documentation site
478
+ (https://merchantapi.leopardscourier.com) has no content.
479
+ - **TCS, M&P, Trax and BlueEx**: no public status list. Their API documents
480
+ are behind merchant or developer logins, so nothing is mapped. Copies on
481
+ third-party sites were not used.
482
+ - **Tracking numbers**: no courier documents a format, so there is no
483
+ tracking-number detection. PostEx's guide only uses the placeholder
484
+ `CX-XXXXXXXXXXX`.
485
+
486
+ `normalizeCityForCourier`'s short forms (`LHR`, `Khi`, `Pindi`, `ISB`, `FSD`,
487
+ the former name Lyallpur, Urdu names and so on) are common usage, not an
488
+ official list. Each maps to a city in `cities.json`.
489
+
490
+ ## FBR Digital Invoicing
491
+
492
+ No dataset: `buildFbrInvoice` and `validateFbrInvoice` follow these
493
+ documents, retrieved on 2026-11-18:
494
+
495
+ - **PRAL, "Technical Specification for DI API", version 1.12** (issued
496
+ 7 April 2025, last updated 24 July 2025):
497
+ https://download1.fbr.gov.pk/Docs/20257301172130815TechnicalDocumentationforDIAPIV1.12.pdf,
498
+ linked from https://www.fbr.gov.pk/di-technical-assistance/173967/173970.
499
+ PRAL's download index (https://dicrm.pral.com.pk/assets/docs/documents.json)
500
+ lists it as the current version. It gives the fields, the sale types and
501
+ the error codes.
502
+ - **PRAL, "Error Message Guide (Sales)"**:
503
+ https://dicrm.pral.com.pk/assets/docs/Manuals/Error%20Message%20Guide%20-%20(Sales).pdf.
504
+ This is the source of the rules on numbers (0300: not negative or empty;
505
+ 0302: at most 2 decimals, 4 for quantity), on SROs (0077, 0078) and on
506
+ reduced-rate goods (0091).
507
+ - **PRAL, "DI Scenarios Description for Sandbox Testing"** (v1.11): the sample
508
+ invoices, used for the arithmetic examples (1000 × 18% = 180; Rs.3 × 12 =
509
+ 36; retail price 100 × 18% = 18 for Third Schedule goods).
510
+ - **Legal basis**: S.R.O. 69(I)/2025, Sales Tax Rules chapter XIV
511
+ (https://download1.fbr.gov.pk/SROs/2025129141598258SRO69(I)2025.pdf).
512
+
513
+ Where the documents disagree or are silent, the code does this:
514
+
515
+ - **Key names** are those of the specification's sample JSON
516
+ (`invoiceType`, `buyerRegistrationType`), not the misspellings in its field
517
+ table, and `invoiceType` is `Sale Invoice` (the table says "Sales
518
+ Invoice", but the samples and the document type API say "Sale Invoice").
519
+ - **NTN length** is 7 (error 0002's text also mentions 9, but 0401, 0402 and
520
+ the guide say 7 or 13).
521
+ - **Rounding**: none is documented. Sales tax is rounded half up to the
522
+ paisa, and a declared tax within one paisa of it is accepted. This is the
523
+ library's choice.
524
+ - **Sale types** are compared ignoring case and spaces, because the
525
+ specification's table and its samples differ in capitals.
526
+ - **Not checked**: anything that needs FBR's reference APIs or records
527
+ (registration, provinces, HS codes, units, rates, sale types, SRO lists,
528
+ the original invoice of a debit note). There are no string length limits
529
+ in the specification, so none are checked.
530
+
100
531
  ## CNIC
101
532
 
102
533
  First digit = province of registration, per FBR's tax-ID description filed with
103
534
  the OECD (1 Khyber Pakhtunkhwa, 2 former FATA, 3 Punjab, 4 Sindh, 5
104
535
  Balochistan, 6 Islamabad, 7 Gilgit-Baltistan). `8` for Azad Jammu and Kashmir
105
536
  comes from secondary sources only. Last digit odd = male, even = female.
537
+
538
+ ## Passport numbers
539
+
540
+ `validatePassport` accepts two letters followed by seven digits (`AB1234567`).
541
+ DGIP does not publish the format, and its forms only ask for "Passport Number".
542
+
543
+ - **Source:** the EU Council's PRADO register gives this pattern for the 2013
544
+ ordinary passport
545
+ (https://www.consilium.europa.eu/prado/en/PAK-AO-02003/index.html). The page
546
+ sits behind a bot check, so it was confirmed through search-result text, not
547
+ the page itself.
548
+ - **Observed on real passports:** the maintainer checked real ordinary
549
+ (green) and official (blue) Pakistani passports in November 2026; their
550
+ numbers have this shape. No numbers are recorded here.
551
+ - **Fits ICAO Doc 9303:** the document-number field is 9 characters, with the
552
+ check digit stored separately in the machine-readable zone
553
+ (https://www.icao.int/publications/Documents/9303_p4_cons_en.pdf).
554
+ - **Still unconfirmed:** diplomatic (red) passports and the e-passport
555
+ variants (2022 onwards), and what the letters mean. A real number in another
556
+ shape will be rejected; treat `false` as unusual, not fake.
557
+
558
+ ## Vehicle registration plates
559
+
560
+ `parseVehiclePlate` accepts 1–4 letters, then 1–4 digits, optionally followed
561
+ by a two-digit year after a separator (`LEA-1234-19`). There is no national
562
+ format: each province's excise department sets its own.
563
+
564
+ - **Reported formats** (Wikipedia, partly inconsistent,
565
+ https://en.wikipedia.org/wiki/Vehicle_registration_plates_of_Pakistan):
566
+ Sindh cars 3 letters + 3 digits; Islamabad and Balochistan 2 letters + 3
567
+ digits; Khyber Pakhtunkhwa 2 letters + 4 digits; Gilgit-Baltistan 3 letters +
568
+ 2 digits; AJK motorcycles and public transport 4 letters + 3 digits; older
569
+ Punjab plates 4 digits plus a two-digit year.
570
+ - **Number length:** Punjab's excise department auctions registration marks of
571
+ 1 to 4 digits (https://excise.punjab.gov.pk/auctions).
572
+ - **Recent changes:** numbers now stay with the owner in Islamabad
573
+ (https://profit.pakistantoday.com.pk/2025/07/20/ict-excise-deptt-introduces-personalized-number-plates-digital-cards-online-tax-payment/),
574
+ Khyber Pakhtunkhwa
575
+ (https://arynews.tv/kp-new-vehicle-registration-number-plate-system-sep-17-2025)
576
+ and Sindh, from 16 February 2026
577
+ (https://profit.pakistantoday.com.pk/2026/02/16/sindh-enforces-cnic-based-number-plates-owners-can-retain-registration-marks/).
578
+ Punjab announced new series from May 2026
579
+ (https://propakistani.pk/2026/04/29/punjab-to-launch-five-new-vehicle-number-series/)
580
+ without publishing their layout.
581
+ - **Not checked:** series letters against districts (no official list, e.g. for
582
+ `LEA`/`LEB` = Lahore), and labels printed on the plate such as "ICT" or
583
+ "PUNJAB", which are not part of the number.
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 PakDataKit Contributors
3
+ Copyright (c) 2026 Muzamil Chaudhery and PakDataKit Contributors
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/NOTICE ADDED
@@ -0,0 +1,14 @@
1
+ PakDataKit
2
+ https://github.com/chmuzamil/pakdatakit
3
+
4
+ Origin
5
+ - First commit: 29 May 2026, commit bdc426a (git history).
6
+ - First npm release: pakdatakit 1.0.0, 29 May 2026 (npm registry).
7
+
8
+ Licence and reuse
9
+ PakDataKit is released under the MIT licence (see LICENSE). This covers the
10
+ code of every port, the datasets in data/ and the shared test vectors in
11
+ test-vectors/. Anyone who copies or adapts any substantial part of it, in
12
+ any language, must keep this copyright notice and the licence text:
13
+
14
+ Copyright (c) 2026 Muzamil Chaudhery and PakDataKit Contributors