pakdatakit 2.3.0 → 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.
- package/DATA.md +212 -3
- package/LICENSE +1 -1
- package/NOTICE +14 -0
- package/README.md +304 -5
- package/dist/address.cjs +5 -4
- package/dist/address.js +3 -2
- package/dist/bills.cjs +19 -0
- package/dist/bills.d.cts +63 -0
- package/dist/bills.d.ts +63 -0
- package/dist/bills.js +2 -0
- package/dist/{chunk-OKMBYX3F.cjs → chunk-33GOK7EE.cjs} +2 -910
- package/dist/chunk-34U2ZMHR.js +194 -0
- package/dist/chunk-4GSBHJX6.js +165 -0
- package/dist/chunk-5DDHO5Z7.cjs +565 -0
- package/dist/chunk-5EY5DQS7.js +51 -0
- package/dist/chunk-5RGX4DWF.js +559 -0
- package/dist/chunk-5UCRHVI4.cjs +302 -0
- package/dist/{chunk-TQP2T33V.js → chunk-B7DOQ5QF.js} +2 -1
- package/dist/chunk-CF6AMRBU.cjs +198 -0
- package/dist/chunk-CZOZB4K3.js +61 -0
- package/dist/chunk-E2XU6NOW.js +909 -0
- package/dist/chunk-E6GWBOKV.cjs +911 -0
- package/dist/chunk-EA3SIHYT.js +313 -0
- package/dist/{chunk-YTSMFGTW.js → chunk-IDTRFOQW.js} +8 -3
- package/dist/chunk-OTI7HY55.js +297 -0
- package/dist/{chunk-J5ARB4TE.cjs → chunk-QFPEFD67.cjs} +5 -4
- package/dist/chunk-SF4ECUZ6.cjs +56 -0
- package/dist/chunk-UYFTXD4P.js +168 -0
- package/dist/{chunk-TBTWZC74.cjs → chunk-XCFZKCV2.cjs} +8 -3
- package/dist/{chunk-N4S22XX3.js → chunk-XOTCIXY6.js} +2 -909
- package/dist/chunk-XVEG53NN.cjs +322 -0
- package/dist/chunk-YDUXIENX.cjs +172 -0
- package/dist/chunk-YPAWNWFD.cjs +168 -0
- package/dist/chunk-YQFI7W3I.cjs +65 -0
- package/dist/class-validator.cjs +16 -8
- package/dist/class-validator.d.cts +7 -1
- package/dist/class-validator.d.ts +7 -1
- package/dist/class-validator.js +15 -8
- package/dist/cli.js +1 -1
- package/dist/courier.cjs +16 -0
- package/dist/courier.d.cts +51 -0
- package/dist/courier.d.ts +51 -0
- package/dist/courier.js +3 -0
- package/dist/fbr-invoice.cjs +25 -0
- package/dist/fbr-invoice.d.cts +170 -0
- package/dist/fbr-invoice.d.ts +170 -0
- package/dist/fbr-invoice.js +4 -0
- package/dist/geo.cjs +11 -10
- package/dist/geo.js +2 -1
- package/dist/incometax.cjs +27 -0
- package/dist/incometax.d.cts +91 -0
- package/dist/incometax.d.ts +91 -0
- package/dist/incometax.js +2 -0
- package/dist/index.cjs +227 -123
- package/dist/index.d.cts +8 -2
- package/dist/index.d.ts +8 -2
- package/dist/index.js +21 -13
- package/dist/input.cjs +8 -8
- package/dist/input.js +2 -2
- package/dist/joi.cjs +14 -8
- package/dist/joi.d.cts +1 -0
- package/dist/joi.d.ts +1 -0
- package/dist/joi.js +13 -7
- package/dist/quality.cjs +25 -0
- package/dist/quality.d.cts +62 -0
- package/dist/quality.d.ts +62 -0
- package/dist/quality.js +8 -0
- package/dist/salestax.cjs +20 -0
- package/dist/salestax.d.cts +106 -0
- package/dist/salestax.d.ts +106 -0
- package/dist/salestax.js +3 -0
- package/dist/superstruct.cjs +14 -8
- package/dist/superstruct.d.cts +1 -0
- package/dist/superstruct.d.ts +1 -0
- package/dist/superstruct.js +13 -7
- package/dist/text.cjs +21 -5
- package/dist/text.d.cts +90 -1
- package/dist/text.d.ts +90 -1
- package/dist/text.js +1 -1
- package/dist/valibot.cjs +14 -8
- package/dist/valibot.d.cts +1 -0
- package/dist/valibot.d.ts +1 -0
- package/dist/valibot.js +13 -7
- package/dist/yup.cjs +14 -8
- package/dist/yup.d.cts +1 -0
- package/dist/yup.d.ts +1 -0
- package/dist/yup.js +13 -7
- package/dist/zod.cjs +14 -8
- package/dist/zod.d.cts +1 -0
- package/dist/zod.d.ts +1 -0
- package/dist/zod.js +13 -7
- package/package.json +68 -5
- package/dist/chunk-JKE4AMSZ.js +0 -47
- package/dist/chunk-KEHCTYLO.cjs +0 -52
- package/dist/{chunk-A3HBEBXY.js → chunk-7DY26QPN.js} +1 -1
- package/dist/{chunk-FRBPAGEJ.cjs → chunk-TVL6RDAU.cjs} +1 -1
package/DATA.md
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
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
|
|
5
|
-
`holidays.json`, which are edited directly). Two official lists are kept as
|
|
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
6
|
extracted CSV files in `data/sources/` and read by the generator: Pakistan
|
|
7
7
|
Post's post code directory and the 2023 census's administrative units. The exported `dataVersion` is the
|
|
8
8
|
date the data was last checked.
|
|
9
9
|
|
|
10
|
-
**Data version: 2026-11-
|
|
10
|
+
**Data version: 2026-11-18**
|
|
11
11
|
|
|
12
12
|
The datasets were audited against official sources on 16 November 2026;
|
|
13
13
|
[AUDIT.md](AUDIT.md) has the findings, the fixes made and what is still open.
|
|
@@ -319,6 +319,215 @@ that states the same dates). Later years are estimated from the tabular Hijri ca
|
|
|
319
319
|
and marked `estimated: true`. Fixed-date holidays follow the years they applied
|
|
320
320
|
in (e.g. Iqbal Day restored in 2022, Youm-e-Takbeer from 2024).
|
|
321
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
|
+
|
|
322
531
|
## CNIC
|
|
323
532
|
|
|
324
533
|
First digit = province of registration, per FBR's tax-ID description filed with
|
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
|
package/README.md
CHANGED
|
@@ -55,8 +55,9 @@ Validate CNICs, analyze phone numbers, detect networks, build WhatsApp links, ch
|
|
|
55
55
|
| [`chmuzamil/pakdatakit` (PHP)](https://github.com/chmuzamil/pakdatakit/tree/main/php) | Build from `php/` (not on Packagist yet) | PHP 8.2+, same functions and data, with Laravel rules, rule objects and Eloquent casts |
|
|
56
56
|
| [`pakdatakit-vue`](https://github.com/chmuzamil/pakdatakit/tree/main/vue) | Build from `vue/` (not on npm yet) | Vue 3 composables and a `v-pak-input` directive that format as you type |
|
|
57
57
|
| [`pakdatakit-angular`](https://github.com/chmuzamil/pakdatakit/tree/main/angular) | Build from `angular/` (not on npm yet) | Angular directives, pipes and form validators |
|
|
58
|
+
| [`pakdatakit-pay`](https://github.com/chmuzamil/pakdatakit/tree/main/pay) | Build from `pay/` (not on npm yet) | Server-side JazzCash secure hash: build it and verify responses in constant time |
|
|
58
59
|
|
|
59
|
-
The Python, Dart, .NET and PHP packages are checked against the TypeScript library with over
|
|
60
|
+
The Python, Dart, .NET and PHP packages are checked against the TypeScript library with over 25,000 shared test cases, so all five give the same results.
|
|
60
61
|
|
|
61
62
|
---
|
|
62
63
|
|
|
@@ -83,7 +84,7 @@ Most Pakistani apps validate CNICs, mobile numbers and IBANs with a regex copied
|
|
|
83
84
|
| Holidays, Hijri | Not possible | Observed Eid/Ashura/Milad dates from official notifications, Hijri conversion |
|
|
84
85
|
| Amounts, currency | Not possible | Lakh/crore formatting, amounts in words in English and Urdu |
|
|
85
86
|
| Forms | Write each rule per library | Ready rules for Zod, Valibot, Yup, Joi, Superstruct and class-validator (NestJS) |
|
|
86
|
-
| Other languages | Rewrite it | Python and Dart packages with the core functions, checked against over
|
|
87
|
+
| Other languages | Rewrite it | Python and Dart packages with the core functions, checked against over 25,000 shared test cases |
|
|
87
88
|
|
|
88
89
|
The npm package has no runtime dependencies, ships ESM and CommonJS with TypeScript types, and works offline: all data is bundled. Every dataset lists its sources in [DATA.md](./DATA.md).
|
|
89
90
|
|
|
@@ -655,6 +656,53 @@ Formats structured components back into a mailing address string. Only the compo
|
|
|
655
656
|
|
|
656
657
|
---
|
|
657
658
|
|
|
659
|
+
## Cash on Delivery Checks
|
|
660
|
+
|
|
661
|
+
`import { scoreAddress, phoneRiskSignals } from 'pakdatakit/quality'`
|
|
662
|
+
|
|
663
|
+
Heuristics for spotting an order a rider will struggle to deliver. They look only at the text you pass: no lists of real people or numbers, no network calls, and they never throw.
|
|
664
|
+
|
|
665
|
+
### scoreAddress()
|
|
666
|
+
|
|
667
|
+
Scores a delivery address from 0 to 100 and lists what is missing. Built on `parseAddress` and the Pakistan Post directory: a postal code that is a known post office scores higher than an unknown one, and one in a different province from the city lowers the score.
|
|
668
|
+
|
|
669
|
+
```ts
|
|
670
|
+
scoreAddress(
|
|
671
|
+
'House 12, Street 4, Block B, Gulberg III, near Liberty Market, Lahore 54660',
|
|
672
|
+
);
|
|
673
|
+
// { score: 100, missing: [], parsed: { city: "Lahore", postalCode: "54660", ... } }
|
|
674
|
+
|
|
675
|
+
scoreAddress('Lahore').missing;
|
|
676
|
+
// ["houseNumber", "street", "area", "postalCode", "landmark"]
|
|
677
|
+
```
|
|
678
|
+
|
|
679
|
+
| Part | Points | Found when |
|
|
680
|
+
| ------------- | -----: | ------------------------------------------------------------------------------------------------- |
|
|
681
|
+
| `city` | 30 | `parseAddress` finds a city |
|
|
682
|
+
| `houseNumber` | 20 | a number other than the postal code ("House 12", "12b", "Flat 2") |
|
|
683
|
+
| `street` | 15 | street, road, lane, gali, chowk, bazaar, mohalla, گلی, محلہ … |
|
|
684
|
+
| `area` | 10 | an area segment, or block, sector, phase, town, colony, society, بلاک, سیکٹر … |
|
|
685
|
+
| `postalCode` | 15 | a known post office code (an unknown 5-digit code scores 5) |
|
|
686
|
+
| `landmark` | 10 | near, opp, behind, next to; nazd, nazdeek, qareeb, samne, peechay, bilmuqabil; نزد، قریب، سامنے … |
|
|
687
|
+
|
|
688
|
+
The weights are exported as `ADDRESS_WEIGHTS`. Importing `scoreAddress` adds about 44 kB gzipped (the post office directory); `phoneRiskSignals` alone is about 3 kB.
|
|
689
|
+
|
|
690
|
+
### phoneRiskSignals()
|
|
691
|
+
|
|
692
|
+
Returns the reasons to double-check a phone number given for a delivery, or `[]`.
|
|
693
|
+
|
|
694
|
+
```ts
|
|
695
|
+
phoneRiskSignals('0301-2945716'); // []
|
|
696
|
+
phoneRiskSignals('03001234567'); // ["sequential-digits", "test-number"]
|
|
697
|
+
phoneRiskSignals('03000000000'); // ["repeated-digits"]
|
|
698
|
+
phoneRiskSignals('042 35761234'); // ["landline"]
|
|
699
|
+
phoneRiskSignals('12345'); // ["invalid"]
|
|
700
|
+
```
|
|
701
|
+
|
|
702
|
+
Flags: `invalid`, `landline`, `not-mobile` (UAN, toll-free and other service numbers), `repeated-digits` (the 7-digit subscriber part uses at most two digits), `sequential-digits` (`1234567`, `7654321` …) and `test-number` (`03XX-1234567`, `03XX-7654321`, `0312-3456789`). The form adapters have a matching `pk.codPhone()` rule that passes only when there are no flags.
|
|
703
|
+
|
|
704
|
+
---
|
|
705
|
+
|
|
658
706
|
## Text Utilities
|
|
659
707
|
|
|
660
708
|
### normalizeRomanUrdu()
|
|
@@ -665,6 +713,58 @@ Normalizes informal Roman Urdu spellings (`ap kia ker` → `aap kya kar`).
|
|
|
665
713
|
|
|
666
714
|
Convert between English, Urdu, and Arabic-Indic digits.
|
|
667
715
|
|
|
716
|
+
### slugify()
|
|
717
|
+
|
|
718
|
+
Turns text into a URL slug. Urdu letters are kept as they are: Urdu does not write short vowels, so there is no single Roman spelling to transliterate to. Diacritics and zero-width characters are dropped, Urdu digits become `0-9`, and `script` limits which letters are kept (`any`, the default; `latin`; `urdu`).
|
|
719
|
+
|
|
720
|
+
```ts
|
|
721
|
+
slugify('Lahore Fort, 2024'); // "lahore-fort-2024"
|
|
722
|
+
slugify('لاہور قلعہ'); // "لاہور-قلعہ"
|
|
723
|
+
slugify('لاہور Fort', { script: 'latin' }); // "fort"
|
|
724
|
+
slugify('کراچی ۲۰۲۴', { script: 'urdu' }); // "کراچی-2024"
|
|
725
|
+
```
|
|
726
|
+
|
|
727
|
+
### compareUrdu()
|
|
728
|
+
|
|
729
|
+
Sorts Urdu in alphabetical order, following the Unicode CLDR collation for Urdu (CLDR 49): ا آ ب بھ پ پھ ت تھ ٹ … ی یھ ے. A letter joined with ھ (بھ, پھ, کھ …) is a letter of its own, so بھائی comes after every other ب word. The same order is used in every port, without depending on the platform's ICU.
|
|
730
|
+
|
|
731
|
+
```ts
|
|
732
|
+
['ے', 'بھائی', 'آم', 'باغ', 'اب'].sort(compareUrdu);
|
|
733
|
+
// ["اب", "آم", "باغ", "بھائی", "ے"]
|
|
734
|
+
```
|
|
735
|
+
|
|
736
|
+
Digits come before letters (one digit at a time, so `10` before `2`), and other scripts after. The Arabic look-alikes ك ي ه are not Urdu letters in CLDR and sort after ے; write ک ی ہ to sort them as Urdu.
|
|
737
|
+
|
|
738
|
+
### isRTL() / wrapBidi()
|
|
739
|
+
|
|
740
|
+
`isRTL` is `true` when the first letter is from a right-to-left script. `wrapBidi` wraps text in Unicode directional isolates (FSI … PDI, or RLI/LRI with `'rtl'`/`'ltr'`), so an English order number or name does not jumble an Urdu sentence.
|
|
741
|
+
|
|
742
|
+
```ts
|
|
743
|
+
isRTL('123 سلام'); // true
|
|
744
|
+
isRTL('Order نمبر'); // false
|
|
745
|
+
`آرڈر ${wrapBidi('PDK-1042')} بھیج دیا گیا`;
|
|
746
|
+
```
|
|
747
|
+
|
|
748
|
+
---
|
|
749
|
+
|
|
750
|
+
## Income Tax on Salary
|
|
751
|
+
|
|
752
|
+
`import { calculateSalaryTax } from 'pakdatakit/incometax'`
|
|
753
|
+
|
|
754
|
+
Income tax on a salaried individual's taxable income, from the salaried rate table in the Income Tax Ordinance 2001 (First Schedule, Part I, Division I, clause (2), which applies when salary is more than 75% of taxable income). Tax years 2020 to 2027 are covered; a tax year runs from 1 July to 30 June and is named after the June it ends in.
|
|
755
|
+
|
|
756
|
+
```ts
|
|
757
|
+
calculateSalaryTax(1_800_000, { taxYear: 2026 });
|
|
758
|
+
// { tax: 72000, monthly: 6000, effectiveRate: 4,
|
|
759
|
+
// slab: { over: 1200000, upTo: 2200000, fixed: 6000, rate: 11 }, taxYear: 2026 }
|
|
760
|
+
|
|
761
|
+
calculateMonthlySalaryTax(150_000, { taxYear: 2026 })?.monthly; // 6000
|
|
762
|
+
getSalaryTaxSlabs(2027); // the table, its law and FBR source
|
|
763
|
+
getTaxYear('2025-07-01'); // 2026
|
|
764
|
+
```
|
|
765
|
+
|
|
766
|
+
Without `taxYear` or `date`, the current tax year is used, and a year that is not covered returns `null`. Tax is rounded half up to the paisa. Only the rate table is applied: the surcharge, tax credits, exemptions, the separate rate for pensions and withholding adjustments are not. Sources and the full table are in [DATA.md](DATA.md#income-tax-on-salary-income-tax-slabsjson).
|
|
767
|
+
|
|
668
768
|
---
|
|
669
769
|
|
|
670
770
|
## Hijri Calendar
|
|
@@ -783,6 +883,183 @@ FBR does not publish its check-digit algorithms, so these check the format only.
|
|
|
783
883
|
|
|
784
884
|
---
|
|
785
885
|
|
|
886
|
+
## Sales Tax
|
|
887
|
+
|
|
888
|
+
`import { getSalesTaxRate, calculateSalesTax, splitInclusive } from 'pakdatakit/salestax'`
|
|
889
|
+
|
|
890
|
+
Standard sales tax rates with the dates they applied, from 1 July 2019: federal sales tax on goods (FBR), and sales tax on services in Punjab (PRA), Sindh (SRB), Khyber Pakhtunkhwa (KPRA), Balochistan (BRA) and Islamabad Capital Territory (FBR). Each rate carries the law and the official document it comes from ([DATA.md](DATA.md#sales-tax-rates-sales-tax-ratesjson)). Reduced, higher and sector rates are not included.
|
|
891
|
+
|
|
892
|
+
### getSalesTaxRate()
|
|
893
|
+
|
|
894
|
+
```ts
|
|
895
|
+
getSalesTaxRate({ kind: 'goods', date: '2026-11-18' });
|
|
896
|
+
// { kind: "goods", authority: "FBR", province: null, rate: 18, from: "2023-02-23", to: null, law: "Sales Tax Act 1990, s. 3(1), …", source: "https://download1.fbr.gov.pk/…" }
|
|
897
|
+
|
|
898
|
+
getSalesTaxRate({ kind: 'services', province: 'Sindh', date: '2024-06-30' })
|
|
899
|
+
?.rate; // 13
|
|
900
|
+
getSalesTaxRate({ kind: 'services', province: 'ICT' })?.rate; // 15 (today)
|
|
901
|
+
```
|
|
902
|
+
|
|
903
|
+
`province` accepts the province names and `KP`, `KPK`, `ICT` and `Islamabad`. It returns `null` for a date before 1 July 2019, an invalid date, an unknown province, services without a province, or goods in Azad Jammu and Kashmir or Gilgit-Baltistan.
|
|
904
|
+
|
|
905
|
+
### calculateSalesTax() / splitInclusive()
|
|
906
|
+
|
|
907
|
+
```ts
|
|
908
|
+
calculateSalesTax(1000, { rate: 18 });
|
|
909
|
+
// { net: 1000, tax: 180, gross: 1180, rate: 18 }
|
|
910
|
+
|
|
911
|
+
calculateSalesTax(1000, { province: 'Punjab' });
|
|
912
|
+
// { net: 1000, tax: 160, gross: 1160, rate: 16 }
|
|
913
|
+
|
|
914
|
+
calculateSalesTax(1150, { province: 'Sindh', inclusive: true });
|
|
915
|
+
// { net: 1000, tax: 150, gross: 1150, rate: 15 }
|
|
916
|
+
|
|
917
|
+
splitInclusive(99.99, 18);
|
|
918
|
+
// { net: 84.74, tax: 15.25, gross: 99.99, rate: 18 }
|
|
919
|
+
```
|
|
920
|
+
|
|
921
|
+
Amounts are rounded half up to the paisa, reading the number as written (`1.005` is Rs 1.01). For an inclusive amount the value is rounded and the tax is the rest, so `net + tax` always equals `gross`. Amounts from 0 to one trillion rupees and rates from 0 to 100 with at most two decimals are accepted; anything else returns `null`, never an exception.
|
|
922
|
+
|
|
923
|
+
---
|
|
924
|
+
|
|
925
|
+
## Utility Bills
|
|
926
|
+
|
|
927
|
+
`import { parseElectricityRef, validateElectricityRef, validateGasConsumerNumber } from 'pakdatakit/bills'`
|
|
928
|
+
|
|
929
|
+
### parseElectricityRef() / validateElectricityRef()
|
|
930
|
+
|
|
931
|
+
Reads the identifiers printed on electricity bills, in the formats the utilities' own bill pages ask for:
|
|
932
|
+
|
|
933
|
+
| `type` | Format | Example |
|
|
934
|
+
| ------------- | ---------------------------------------------------------- | -------------------- |
|
|
935
|
+
| `reference` | DISCO (WAPDA) reference number: 14 digits, optional U or R | `02 12624 0045901 R` |
|
|
936
|
+
| `customer-id` | DISCO customer ID: 10 digits (11 for LESCO) | `1234567890` |
|
|
937
|
+
| `k-electric` | K-Electric account number: 13 digits starting `04000` | `0400012345678` |
|
|
938
|
+
|
|
939
|
+
```ts
|
|
940
|
+
parseElectricityRef('02-12624-0045901 R');
|
|
941
|
+
// { type: "reference", digits: "02126240045901", formatted: "02 12624 0045901 R", urbanRural: "R", disco: null }
|
|
942
|
+
|
|
943
|
+
parseElectricityRef('0400012345678');
|
|
944
|
+
// { type: "k-electric", digits: "0400012345678", formatted: "0400012345678", urbanRural: null, disco: "K-Electric" }
|
|
945
|
+
|
|
946
|
+
validateElectricityRef('12345'); // false
|
|
947
|
+
```
|
|
948
|
+
|
|
949
|
+
Spaces, dashes and dots are ignored, and Urdu digits are accepted. `disco` is `null` for DISCO bills: no official source maps reference or customer ID digits to a distribution company, so the library does not guess. No utility publishes a check digit, so only the format is checked; a well-formed number may still not exist.
|
|
950
|
+
|
|
951
|
+
### validateGasConsumerNumber()
|
|
952
|
+
|
|
953
|
+
```ts
|
|
954
|
+
validateGasConsumerNumber('12345678901', 'SNGPL'); // true (11 digits)
|
|
955
|
+
validateGasConsumerNumber('1234567890', 'SSGC'); // true (10 digits)
|
|
956
|
+
```
|
|
957
|
+
|
|
958
|
+
Sources are in [DATA.md](DATA.md#electricity-and-gas-bill-numbers).
|
|
959
|
+
|
|
960
|
+
---
|
|
961
|
+
|
|
962
|
+
## Couriers
|
|
963
|
+
|
|
964
|
+
`import { mapCourierStatus, normalizeCityForCourier } from 'pakdatakit/courier'`
|
|
965
|
+
|
|
966
|
+
Helpers for orders shipped with Pakistani couriers. There are no API clients: nothing is sent anywhere.
|
|
967
|
+
|
|
968
|
+
### mapCourierStatus()
|
|
969
|
+
|
|
970
|
+
> **Experimental.** `mapCourierStatus` and the `CourierStatus` values may change in a minor release while more couriers' status lists are added. Pin a minor version if you store these values. To add a courier, see [CONTRIBUTING.md](CONTRIBUTING.md#courier-status-lists).
|
|
971
|
+
|
|
972
|
+
Maps a courier's own status (name, numeric ID or code) to one vocabulary: `pending`, `booked`, `picked-up`, `in-transit`, `out-for-delivery`, `attempted`, `under-review`, `delivered`, `returning`, `returned` or `cancelled`.
|
|
973
|
+
|
|
974
|
+
```ts
|
|
975
|
+
mapCourierStatus('PostEx', 'Out For Delivery'); // "out-for-delivery"
|
|
976
|
+
mapCourierStatus('PostEx', 5); // "delivered"
|
|
977
|
+
mapCourierStatus('PostEx', 'Attempt Made: Customer not available'); // "attempted"
|
|
978
|
+
mapCourierStatus('Leopards', 'Returned to Shipper'); // "returned"
|
|
979
|
+
mapCourierStatus('TCS', 'Delivered'); // null
|
|
980
|
+
```
|
|
981
|
+
|
|
982
|
+
Only statuses a courier documents publicly are mapped: every order status and tracking code in PostEx's merchant API guide (v4.1.9), and Leopards' "Returned to Shipper". TCS, M&P, Trax and BlueEx publish no status list outside their merchant portals, so they return `null` for now, as does any status not in the list. No courier documents its tracking number format, so there is no tracking-number detection. Details are in [DATA.md](DATA.md#couriers).
|
|
983
|
+
|
|
984
|
+
### normalizeCityForCourier()
|
|
985
|
+
|
|
986
|
+
Maps how a customer or a courier writes a city to its name in the city list, so orders can be matched against a courier's service list.
|
|
987
|
+
|
|
988
|
+
```ts
|
|
989
|
+
normalizeCityForCourier('LHR'); // "Lahore"
|
|
990
|
+
normalizeCityForCourier('Khi'); // "Karachi"
|
|
991
|
+
normalizeCityForCourier('Pindi'); // "Rawalpindi"
|
|
992
|
+
normalizeCityForCourier('lyallpur'); // "Faisalabad"
|
|
993
|
+
normalizeCityForCourier('Karachi City'); // "Karachi"
|
|
994
|
+
normalizeCityForCourier('لاہور'); // "Lahore"
|
|
995
|
+
normalizeCityForCourier('Atlantis'); // null
|
|
996
|
+
```
|
|
997
|
+
|
|
998
|
+
---
|
|
999
|
+
|
|
1000
|
+
## FBR Digital Invoicing
|
|
1001
|
+
|
|
1002
|
+
`import { buildFbrInvoice, validateFbrInvoice } from 'pakdatakit/fbr-invoice'`
|
|
1003
|
+
|
|
1004
|
+
Types, a builder and an offline validator for the invoice JSON that FBR's Digital Invoicing API accepts (`postinvoicedata` and `validateinvoicedata`), following PRAL's "Technical Specification for DI API" version 1.12 (`FBR_DI_SPEC_VERSION`) and PRAL's Error Message Guide. There is no HTTP client and no token handling: send the invoice with your own code.
|
|
1005
|
+
|
|
1006
|
+
### buildFbrInvoice()
|
|
1007
|
+
|
|
1008
|
+
Works out each line's `salesTaxApplicable` when you leave it out (with `calculateSalesTax`), fills FBR's defaults and adds up the columns.
|
|
1009
|
+
|
|
1010
|
+
```ts
|
|
1011
|
+
const { invoice, totals } = buildFbrInvoice({
|
|
1012
|
+
invoiceType: 'Sale Invoice',
|
|
1013
|
+
invoiceDate: '2025-04-21',
|
|
1014
|
+
sellerNTNCNIC: '1234567',
|
|
1015
|
+
sellerBusinessName: 'Example Traders',
|
|
1016
|
+
sellerProvince: 'Sindh',
|
|
1017
|
+
sellerAddress: 'Karachi',
|
|
1018
|
+
buyerNTNCNIC: '7654321',
|
|
1019
|
+
buyerBusinessName: 'Example Buyer',
|
|
1020
|
+
buyerProvince: 'Punjab',
|
|
1021
|
+
buyerAddress: 'Lahore',
|
|
1022
|
+
buyerRegistrationType: 'Registered',
|
|
1023
|
+
items: [
|
|
1024
|
+
{
|
|
1025
|
+
hsCode: '0101.2100',
|
|
1026
|
+
productDescription: 'Horses',
|
|
1027
|
+
rate: '18%',
|
|
1028
|
+
uoM: 'Numbers, pieces, units',
|
|
1029
|
+
quantity: 2,
|
|
1030
|
+
valueSalesExcludingST: 1234,
|
|
1031
|
+
saleType: 'Goods at standard rate (default)',
|
|
1032
|
+
},
|
|
1033
|
+
],
|
|
1034
|
+
})!;
|
|
1035
|
+
invoice.items[0].salesTaxApplicable; // 222.12
|
|
1036
|
+
totals.salesTaxApplicable; // 222.12
|
|
1037
|
+
```
|
|
1038
|
+
|
|
1039
|
+
Rates of the form `N%` use the value excluding sales tax (or the retail price for Third Schedule goods); `Rs.N` rates use the quantity. Other rates (`Exempt`, combined rates) get 0 unless you give the tax.
|
|
1040
|
+
|
|
1041
|
+
### validateFbrInvoice()
|
|
1042
|
+
|
|
1043
|
+
Returns every problem it can find without calling FBR, with FBR's error code:
|
|
1044
|
+
|
|
1045
|
+
```ts
|
|
1046
|
+
validateFbrInvoice(invoice);
|
|
1047
|
+
// { valid: true, errors: [] }
|
|
1048
|
+
|
|
1049
|
+
validateFbrInvoice({
|
|
1050
|
+
...invoice,
|
|
1051
|
+
invoiceDate: '21-04-2025',
|
|
1052
|
+
buyerNTNCNIC: invoice.sellerNTNCNIC,
|
|
1053
|
+
});
|
|
1054
|
+
// { valid: false, errors: [
|
|
1055
|
+
// { code: "0005", field: "invoiceDate", message: "Invoice date must be in YYYY-MM-DD format" },
|
|
1056
|
+
// { code: "0058", field: "buyerNTNCNIC", message: "Buyer and seller must be different (self-invoicing is not allowed)" } ] }
|
|
1057
|
+
```
|
|
1058
|
+
|
|
1059
|
+
It checks required fields, formats (date, NTN/CNIC, FBR invoice number, sandbox scenario), amounts (not negative, at most 2 decimals, 4 for quantity), SRO rules and the sales tax arithmetic (to within one paisa). Pass `{ today: 'YYYY-MM-DD' }` to also reject future dates. It cannot check what needs FBR's reference APIs: registration status, and whether a province, HS code, unit, rate, sale type or SRO is in FBR's lists. A `valid` result means FBR's own validation is likely to pass, not that it will.
|
|
1060
|
+
|
|
1061
|
+
---
|
|
1062
|
+
|
|
786
1063
|
## Passports & Vehicle Plates
|
|
787
1064
|
|
|
788
1065
|
### validatePassport()
|
|
@@ -951,7 +1228,7 @@ import { pk } from 'pakdatakit/superstruct';
|
|
|
951
1228
|
const CheckoutForm = object({ cnic: pk.cnic(), phone: optional(pk.phone()) });
|
|
952
1229
|
```
|
|
953
1230
|
|
|
954
|
-
Available schemas: `pk.cnic()`, `pk.phone()`, `pk.iban()`, `pk.ntn()`, `pk.strn()`, `pk.landline()`, `pk.passport()` and `pk.
|
|
1231
|
+
Available schemas: `pk.cnic()`, `pk.phone()`, `pk.iban()`, `pk.ntn()`, `pk.strn()`, `pk.landline()`, `pk.passport()`, `pk.vehiclePlate()` and `pk.codPhone()` (a mobile number with no `phoneRiskSignals` flags). Every factory accepts `{ message }` to replace the default error. The Yup schemas let empty values pass so `.required()` decides whether a field is mandatory.
|
|
955
1232
|
|
|
956
1233
|
### class-validator and NestJS
|
|
957
1234
|
|
|
@@ -974,7 +1251,7 @@ export class CreateCustomerDto {
|
|
|
974
1251
|
}
|
|
975
1252
|
```
|
|
976
1253
|
|
|
977
|
-
Decorators: `IsCNIC`, `IsPakPhone`, `IsPakIBAN` (named so it doesn't clash with class-validator's own `IsIBAN`), `IsNTN`, `IsSTRN`, `IsPakLandline`, `IsPakPassport` and `
|
|
1254
|
+
Decorators: `IsCNIC`, `IsPakPhone`, `IsPakIBAN` (named so it doesn't clash with class-validator's own `IsIBAN`), `IsNTN`, `IsSTRN`, `IsPakLandline`, `IsPakPassport`, `IsVehiclePlate` and `IsCodPhone`, also available as `pk.cnic()` and so on. They accept class-validator's options (`message`, `groups`, `each`, `always`); use `@IsOptional()` for optional fields. Values that are not strings fail.
|
|
978
1255
|
|
|
979
1256
|
### As-you-type helpers
|
|
980
1257
|
|
|
@@ -1133,9 +1410,31 @@ See:
|
|
|
1133
1410
|
|
|
1134
1411
|
---
|
|
1135
1412
|
|
|
1413
|
+
# Origin and attribution
|
|
1414
|
+
|
|
1415
|
+
- First commit: 29 May 2026,
|
|
1416
|
+
[`bdc426a`](https://github.com/chmuzamil/pakdatakit/commit/bdc426a84a1b4359dee218c33196810d6631559d)
|
|
1417
|
+
(git history).
|
|
1418
|
+
- First npm release:
|
|
1419
|
+
[`pakdatakit` 1.0.0](https://www.npmjs.com/package/pakdatakit/v/1.0.0), 29 May
|
|
1420
|
+
2026 (npm registry).
|
|
1421
|
+
|
|
1422
|
+
PakDataKit is released under the MIT licence. This covers the code of every
|
|
1423
|
+
port, the datasets in `data/` and the shared test vectors in `test-vectors/`.
|
|
1424
|
+
Anyone who copies or adapts any substantial part of it, in any language, must
|
|
1425
|
+
keep the copyright notice and the licence text:
|
|
1426
|
+
|
|
1427
|
+
```text
|
|
1428
|
+
Copyright (c) 2026 Muzamil Chaudhery and PakDataKit Contributors
|
|
1429
|
+
```
|
|
1430
|
+
|
|
1431
|
+
The same text is in [NOTICE](NOTICE).
|
|
1432
|
+
|
|
1433
|
+
---
|
|
1434
|
+
|
|
1136
1435
|
# License
|
|
1137
1436
|
|
|
1138
|
-
MIT License
|
|
1437
|
+
MIT License. See [LICENSE](LICENSE).
|
|
1139
1438
|
|
|
1140
1439
|
---
|
|
1141
1440
|
|
package/dist/address.cjs
CHANGED
|
@@ -1,17 +1,18 @@
|
|
|
1
1
|
'use strict';
|
|
2
2
|
|
|
3
|
-
var
|
|
3
|
+
var chunkQFPEFD67_cjs = require('./chunk-QFPEFD67.cjs');
|
|
4
4
|
require('./chunk-I7UUPD3G.cjs');
|
|
5
|
-
require('./chunk-
|
|
5
|
+
require('./chunk-33GOK7EE.cjs');
|
|
6
|
+
require('./chunk-E6GWBOKV.cjs');
|
|
6
7
|
require('./chunk-VPBMIYO2.cjs');
|
|
7
8
|
|
|
8
9
|
|
|
9
10
|
|
|
10
11
|
Object.defineProperty(exports, "formatAddress", {
|
|
11
12
|
enumerable: true,
|
|
12
|
-
get: function () { return
|
|
13
|
+
get: function () { return chunkQFPEFD67_cjs.formatAddress; }
|
|
13
14
|
});
|
|
14
15
|
Object.defineProperty(exports, "parseAddress", {
|
|
15
16
|
enumerable: true,
|
|
16
|
-
get: function () { return
|
|
17
|
+
get: function () { return chunkQFPEFD67_cjs.parseAddress; }
|
|
17
18
|
});
|