pakdatakit 2.3.0 → 2.5.1

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 (96) hide show
  1. package/DATA.md +212 -3
  2. package/LICENSE +1 -1
  3. package/NOTICE +14 -0
  4. package/README.md +426 -207
  5. package/dist/address.cjs +5 -4
  6. package/dist/address.js +3 -2
  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-OKMBYX3F.cjs → chunk-33GOK7EE.cjs} +2 -910
  12. package/dist/chunk-34U2ZMHR.js +194 -0
  13. package/dist/chunk-4GSBHJX6.js +165 -0
  14. package/dist/chunk-5DDHO5Z7.cjs +565 -0
  15. package/dist/chunk-5EY5DQS7.js +51 -0
  16. package/dist/chunk-5RGX4DWF.js +559 -0
  17. package/dist/chunk-5UCRHVI4.cjs +302 -0
  18. package/dist/{chunk-TQP2T33V.js → chunk-B7DOQ5QF.js} +2 -1
  19. package/dist/chunk-CF6AMRBU.cjs +198 -0
  20. package/dist/chunk-CZOZB4K3.js +61 -0
  21. package/dist/chunk-E2XU6NOW.js +909 -0
  22. package/dist/chunk-E6GWBOKV.cjs +911 -0
  23. package/dist/chunk-EA3SIHYT.js +313 -0
  24. package/dist/{chunk-YTSMFGTW.js → chunk-IDTRFOQW.js} +8 -3
  25. package/dist/chunk-OTI7HY55.js +297 -0
  26. package/dist/{chunk-J5ARB4TE.cjs → chunk-QFPEFD67.cjs} +5 -4
  27. package/dist/chunk-SF4ECUZ6.cjs +56 -0
  28. package/dist/chunk-UYFTXD4P.js +168 -0
  29. package/dist/{chunk-TBTWZC74.cjs → chunk-XCFZKCV2.cjs} +8 -3
  30. package/dist/{chunk-N4S22XX3.js → chunk-XOTCIXY6.js} +2 -909
  31. package/dist/chunk-XVEG53NN.cjs +322 -0
  32. package/dist/chunk-YDUXIENX.cjs +172 -0
  33. package/dist/chunk-YPAWNWFD.cjs +168 -0
  34. package/dist/chunk-YQFI7W3I.cjs +65 -0
  35. package/dist/class-validator.cjs +16 -8
  36. package/dist/class-validator.d.cts +7 -1
  37. package/dist/class-validator.d.ts +7 -1
  38. package/dist/class-validator.js +15 -8
  39. package/dist/cli.js +1 -1
  40. package/dist/courier.cjs +16 -0
  41. package/dist/courier.d.cts +51 -0
  42. package/dist/courier.d.ts +51 -0
  43. package/dist/courier.js +3 -0
  44. package/dist/fbr-invoice.cjs +25 -0
  45. package/dist/fbr-invoice.d.cts +170 -0
  46. package/dist/fbr-invoice.d.ts +170 -0
  47. package/dist/fbr-invoice.js +4 -0
  48. package/dist/geo.cjs +11 -10
  49. package/dist/geo.js +2 -1
  50. package/dist/incometax.cjs +27 -0
  51. package/dist/incometax.d.cts +91 -0
  52. package/dist/incometax.d.ts +91 -0
  53. package/dist/incometax.js +2 -0
  54. package/dist/index.cjs +227 -123
  55. package/dist/index.d.cts +8 -2
  56. package/dist/index.d.ts +8 -2
  57. package/dist/index.js +21 -13
  58. package/dist/input.cjs +8 -8
  59. package/dist/input.js +2 -2
  60. package/dist/joi.cjs +14 -8
  61. package/dist/joi.d.cts +1 -0
  62. package/dist/joi.d.ts +1 -0
  63. package/dist/joi.js +13 -7
  64. package/dist/quality.cjs +25 -0
  65. package/dist/quality.d.cts +62 -0
  66. package/dist/quality.d.ts +62 -0
  67. package/dist/quality.js +8 -0
  68. package/dist/salestax.cjs +20 -0
  69. package/dist/salestax.d.cts +106 -0
  70. package/dist/salestax.d.ts +106 -0
  71. package/dist/salestax.js +3 -0
  72. package/dist/superstruct.cjs +14 -8
  73. package/dist/superstruct.d.cts +1 -0
  74. package/dist/superstruct.d.ts +1 -0
  75. package/dist/superstruct.js +13 -7
  76. package/dist/text.cjs +21 -5
  77. package/dist/text.d.cts +90 -1
  78. package/dist/text.d.ts +90 -1
  79. package/dist/text.js +1 -1
  80. package/dist/valibot.cjs +14 -8
  81. package/dist/valibot.d.cts +1 -0
  82. package/dist/valibot.d.ts +1 -0
  83. package/dist/valibot.js +13 -7
  84. package/dist/yup.cjs +14 -8
  85. package/dist/yup.d.cts +1 -0
  86. package/dist/yup.d.ts +1 -0
  87. package/dist/yup.js +13 -7
  88. package/dist/zod.cjs +14 -8
  89. package/dist/zod.d.cts +1 -0
  90. package/dist/zod.d.ts +1 -0
  91. package/dist/zod.js +13 -7
  92. package/package.json +74 -11
  93. package/dist/chunk-JKE4AMSZ.js +0 -47
  94. package/dist/chunk-KEHCTYLO.cjs +0 -52
  95. package/dist/{chunk-A3HBEBXY.js → chunk-7DY26QPN.js} +1 -1
  96. package/dist/{chunk-FRBPAGEJ.cjs → chunk-TVL6RDAU.cjs} +1 -1
package/README.md CHANGED
@@ -5,204 +5,186 @@
5
5
  <h1 align="center">🇵🇰 PakDataKit</h1>
6
6
 
7
7
  <p align="center">
8
- <strong>The Standard Utility Toolkit for Pakistani Developers</strong>
8
+ <strong>Pakistani data utilities for TypeScript, Python, Dart/Flutter, .NET and PHP/Laravel, with React, Vue and Angular helpers</strong>
9
9
  </p>
10
10
 
11
11
  <p align="center">
12
- Production-ready TypeScript utilities for CNIC validation, phone parsing, WhatsApp links, IBAN validation, postal lookup, network detection, geographic lookup, and PKR formatting.
12
+ <a href="https://github.com/chmuzamil/pakdatakit/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/chmuzamil/pakdatakit/ci.yml?branch=main&label=CI" alt="CI status"></a>
13
+ <a href="https://www.npmjs.com/package/pakdatakit"><img src="https://img.shields.io/npm/v/pakdatakit?label=npm" alt="npm"></a>
14
+ <a href="https://pypi.org/project/pakdatakit/"><img src="https://img.shields.io/pypi/v/pakdatakit?label=PyPI" alt="PyPI"></a>
15
+ <a href="https://pub.dev/packages/pakdatakit"><img src="https://img.shields.io/pub/v/pakdatakit?label=pub.dev" alt="pub.dev pakdatakit"></a>
16
+ <a href="https://pub.dev/packages/pakdatakit_flutter"><img src="https://img.shields.io/pub/v/pakdatakit_flutter?label=pakdatakit_flutter" alt="pub.dev pakdatakit_flutter"></a>
17
+ <a href="https://www.nuget.org/packages/PakDataKit"><img src="https://img.shields.io/nuget/v/PakDataKit?label=NuGet" alt="NuGet"></a>
18
+ <a href="https://packagist.org/packages/chmuzamil/pakdatakit"><img src="https://img.shields.io/packagist/v/chmuzamil/pakdatakit?label=Packagist" alt="Packagist"></a>
19
+ <a href="./LICENSE"><img src="https://img.shields.io/github/license/chmuzamil/pakdatakit" alt="license"></a>
13
20
  </p>
14
21
 
15
22
  <p align="center">
16
- <a href="https://www.npmjs.com/package/pakdatakit">
17
- <img src="https://img.shields.io/npm/v/pakdatakit" alt="npm version">
18
- </a>
19
- <a href="https://www.npmjs.com/package/pakdatakit">
20
- <img src="https://img.shields.io/npm/dm/pakdatakit" alt="npm downloads">
21
- </a>
22
- <img src="https://img.shields.io/npm/l/pakdatakit" alt="license">
23
- <img src="https://img.shields.io/badge/TypeScript-ready-blue" alt="TypeScript">
24
- <a href="https://pakdatakit-playground.vercel.app/">
25
- <img src="https://img.shields.io/badge/playground-try%20it%20live-brightgreen" alt="Playground">
26
- </a>
27
- <a href="https://chmuzamil.github.io/pakdatakit/">
28
- <img src="https://img.shields.io/badge/docs-API%20reference-blue" alt="API docs">
29
- </a>
23
+ <a href="https://www.npmjs.com/package/pakdatakit-react"><img src="https://img.shields.io/npm/v/pakdatakit-react?label=pakdatakit-react" alt="pakdatakit-react"></a>
24
+ <a href="https://www.npmjs.com/package/pakdatakit-vue"><img src="https://img.shields.io/npm/v/pakdatakit-vue?label=pakdatakit-vue" alt="pakdatakit-vue"></a>
25
+ <a href="https://www.npmjs.com/package/pakdatakit-angular"><img src="https://img.shields.io/npm/v/pakdatakit-angular?label=pakdatakit-angular" alt="pakdatakit-angular"></a>
26
+ <a href="https://www.npmjs.com/package/pakdatakit-faker"><img src="https://img.shields.io/npm/v/pakdatakit-faker?label=pakdatakit-faker" alt="pakdatakit-faker"></a>
27
+ <a href="https://www.npmjs.com/package/pakdatakit-pay"><img src="https://img.shields.io/npm/v/pakdatakit-pay?label=pakdatakit-pay" alt="pakdatakit-pay"></a>
28
+ <a href="https://www.npmjs.com/package/pakdatakit"><img src="https://img.shields.io/npm/dm/pakdatakit?label=downloads" alt="npm downloads"></a>
29
+ <a href="https://www.npmjs.com/package/pakdatakit#provenance"><img src="https://img.shields.io/badge/npm-provenance-2ea44f?logo=npm" alt="npm provenance"></a>
30
+ <a href="https://chmuzamil.github.io/pakdatakit/"><img src="https://img.shields.io/badge/docs-API%20reference-blue" alt="API docs"></a>
30
31
  </p>
31
32
 
32
- ---
33
-
34
- ## 🌐 Playground
33
+ PakDataKit validates, formats and looks up Pakistani data: CNICs, mobile and landline numbers, IBANs and banks, NTN/STRN, passports and vehicle plates, Raast QR codes, sales tax and salary income tax, FBR digital invoices, electricity and gas bill references, cities, districts, tehsils, postal codes and post offices, Urdu text, Hijri dates and public holidays.
35
34
 
36
- Try PakDataKit in your browser, no installation needed:
35
+ - **Five languages, one behaviour.** The TypeScript library has ports for Python, Dart/Flutter, .NET and PHP/Laravel. All five run the same 32,388 shared test vectors, so they give the same answer for the same input.
36
+ - **UI helpers.** React, Vue and Angular inputs that format as you type, plus Flutter formatters and form fields.
37
+ - **Offline and dependency-free.** All data is bundled and no function makes a network call. The npm package has no runtime dependencies and ships ESM, CommonJS and types.
38
+ - **Sourced data.** Every dataset lists its official sources in [DATA.md](./DATA.md).
37
39
 
38
- 👉 **[pakdatakit-playground.vercel.app](https://pakdatakit-playground.vercel.app/)**
39
-
40
- Validate CNICs, analyze phone numbers, detect networks, build WhatsApp links, check IBANs and banks, look up postal codes, cities and provinces, format PKR amounts, and try the text and Hijri utilities. Use it to preview outputs before you integrate the library.
40
+ **[Try it in the playground](https://pakdatakit-playground.vercel.app/)** · **[API reference](https://chmuzamil.github.io/pakdatakit/)** · **[llms.txt](https://chmuzamil.github.io/pakdatakit/llms.txt)** / **[llms-full.txt](https://chmuzamil.github.io/pakdatakit/llms-full.txt)** for AI coding assistants
41
41
 
42
42
  ---
43
43
 
44
44
  ## 📦 Packages
45
45
 
46
- | Package | Install | For |
47
- | ------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------- |
48
- | [`pakdatakit`](https://www.npmjs.com/package/pakdatakit) | `npm install pakdatakit` | JavaScript and TypeScript (Node, browsers, Bun, Deno) |
49
- | [`pakdatakit` (Python)](https://github.com/chmuzamil/pakdatakit/tree/main/python) | `pip install pakdatakit` | Python 3.9+, same functions in snake_case, same data |
50
- | [`pakdatakit-react`](https://github.com/chmuzamil/pakdatakit/tree/main/react) | `npm install pakdatakit-react` | React inputs that format as you type, and a Raast QR component |
51
- | [`pakdatakit-faker`](https://github.com/chmuzamil/pakdatakit/tree/main/faker) | `npm install -D pakdatakit-faker` | Seeded mock data: CNICs, phones, IBANs, addresses and whole personas that pass every validator |
52
- | [`pakdatakit` (Dart)](https://github.com/chmuzamil/pakdatakit/tree/main/dart) | `dart pub add pakdatakit` | Dart and Flutter (including web), same functions and data |
53
- | [`pakdatakit_flutter`](https://github.com/chmuzamil/pakdatakit/tree/main/flutter) | `flutter pub add pakdatakit_flutter` | Flutter input formatters, form fields and a Raast QR widget |
54
- | [`PakDataKit` (.NET)](https://github.com/chmuzamil/pakdatakit/tree/main/dotnet) | Build from `dotnet/` (not on NuGet yet) | .NET 8, same functions and data, with DataAnnotations and FluentValidation packages |
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
- | [`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
- | [`pakdatakit-angular`](https://github.com/chmuzamil/pakdatakit/tree/main/angular) | Build from `angular/` (not on npm yet) | Angular directives, pipes and form validators |
58
-
59
- The Python, Dart, .NET and PHP packages are checked against the TypeScript library with over 12,000 shared test cases, so all five give the same results.
46
+ | Package | Registry | Install | Version |
47
+ | ---------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
48
+ | [`pakdatakit`](https://www.npmjs.com/package/pakdatakit) | npm | `npm install pakdatakit` | [![npm](https://img.shields.io/npm/v/pakdatakit?label=)](https://www.npmjs.com/package/pakdatakit) |
49
+ | [`pakdatakit`](https://pypi.org/project/pakdatakit/) ([Python](./python)) | PyPI | `pip install pakdatakit` | [![PyPI](https://img.shields.io/pypi/v/pakdatakit?label=)](https://pypi.org/project/pakdatakit/) |
50
+ | [`pakdatakit`](https://pub.dev/packages/pakdatakit) ([Dart](./dart)) | pub.dev | `dart pub add pakdatakit` | [![pub.dev](https://img.shields.io/pub/v/pakdatakit?label=)](https://pub.dev/packages/pakdatakit) |
51
+ | [`pakdatakit_flutter`](https://pub.dev/packages/pakdatakit_flutter) ([Flutter](./flutter)) | pub.dev | `flutter pub add pakdatakit_flutter` | [![pub.dev](https://img.shields.io/pub/v/pakdatakit_flutter?label=)](https://pub.dev/packages/pakdatakit_flutter) |
52
+ | [`PakDataKit`](https://www.nuget.org/packages/PakDataKit) ([.NET](./dotnet)) | NuGet | `dotnet add package PakDataKit` | [![NuGet](https://img.shields.io/nuget/v/PakDataKit?label=)](https://www.nuget.org/packages/PakDataKit) |
53
+ | [`PakDataKit.DataAnnotations`](https://www.nuget.org/packages/PakDataKit.DataAnnotations) | NuGet | `dotnet add package PakDataKit.DataAnnotations` | [![NuGet](https://img.shields.io/nuget/v/PakDataKit.DataAnnotations?label=)](https://www.nuget.org/packages/PakDataKit.DataAnnotations) |
54
+ | [`PakDataKit.FluentValidation`](https://www.nuget.org/packages/PakDataKit.FluentValidation) | NuGet | `dotnet add package PakDataKit.FluentValidation` | [![NuGet](https://img.shields.io/nuget/v/PakDataKit.FluentValidation?label=)](https://www.nuget.org/packages/PakDataKit.FluentValidation) |
55
+ | [`chmuzamil/pakdatakit`](https://packagist.org/packages/chmuzamil/pakdatakit) ([PHP/Laravel](./php)) | Packagist | `composer require chmuzamil/pakdatakit` | [![Packagist](https://img.shields.io/packagist/v/chmuzamil/pakdatakit?label=)](https://packagist.org/packages/chmuzamil/pakdatakit) |
56
+ | [`pakdatakit-react`](https://www.npmjs.com/package/pakdatakit-react) ([React](./react)) | npm | `npm install pakdatakit-react` | [![npm](https://img.shields.io/npm/v/pakdatakit-react?label=)](https://www.npmjs.com/package/pakdatakit-react) |
57
+ | [`pakdatakit-vue`](https://www.npmjs.com/package/pakdatakit-vue) ([Vue](./vue)) | npm | `npm install pakdatakit-vue` | [![npm](https://img.shields.io/npm/v/pakdatakit-vue?label=)](https://www.npmjs.com/package/pakdatakit-vue) |
58
+ | [`pakdatakit-angular`](https://www.npmjs.com/package/pakdatakit-angular) ([Angular](./angular)) | npm | `npm install pakdatakit-angular` | [![npm](https://img.shields.io/npm/v/pakdatakit-angular?label=)](https://www.npmjs.com/package/pakdatakit-angular) |
59
+ | [`pakdatakit-faker`](https://www.npmjs.com/package/pakdatakit-faker) ([mock data](./faker)) | npm | `npm install -D pakdatakit-faker` | [![npm](https://img.shields.io/npm/v/pakdatakit-faker?label=)](https://www.npmjs.com/package/pakdatakit-faker) |
60
+ | [`pakdatakit-pay`](https://www.npmjs.com/package/pakdatakit-pay) ([JazzCash hash](./pay)) | npm | `npm install pakdatakit-pay` | [![npm](https://img.shields.io/npm/v/pakdatakit-pay?label=)](https://www.npmjs.com/package/pakdatakit-pay) |
60
61
 
61
62
  ---
62
63
 
63
- ## 📚 Documentation
64
+ ## 🧩 Modules
64
65
 
65
- - **[API reference](https://chmuzamil.github.io/pakdatakit/)**: every function, option and return type
66
- - **[llms.txt](https://chmuzamil.github.io/pakdatakit/llms.txt)** and **[llms-full.txt](https://chmuzamil.github.io/pakdatakit/llms-full.txt)**: the library in a form AI coding assistants can read
67
- - **[DATA.md](./DATA.md)**: where every dataset comes from
66
+ Every module is in every port unless noted. In npm, each is also a subpath import (`pakdatakit/cnic`, `pakdatakit/salestax` and so on) to keep bundles small.
68
67
 
69
- ---
68
+ | Area | What it covers | npm modules |
69
+ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
70
+ | **Identity** | CNIC validation with province and gender, passports, vehicle registration plates | `cnic`, `passport`, `vehicle` |
71
+ | **Phone** | Mobile numbers and their original network, landline, UAN, toll-free and premium numbers, WhatsApp links, phone risk signals for cash on delivery | `phone`, `networks`, `numbers`, `whatsapp`, `quality` |
72
+ | **Banking and payments** | IBAN checksum and bank lookup, Raast QR codes (create, parse, validate), electricity and gas bill references, PKR and lakh/crore formatting, amounts in words; JazzCash secure hash in `pakdatakit-pay` | `iban`, `raast`, `bills`, `format`, `words` |
73
+ | **Tax and FBR** | NTN and STRN, federal and provincial sales tax rates, salary income tax (tax years 2020 to 2027), FBR Digital Invoicing build and offline validation | `tax`, `salestax`, `incometax`, `fbr-invoice` |
74
+ | **Geography and postal** | Provinces, cities, districts, divisions and tehsils (2023 census), postal codes and about 2,560 post offices, address parsing and delivery-address scoring, courier status and city matching (experimental) | `geo`, `postal`, `address`, `quality`, `courier` |
75
+ | **Text and Urdu** | Roman Urdu normalization, Urdu and English digits, Urdu-aware slugs, Urdu alphabetical order, right-to-left detection and bidi isolation | `text` |
76
+ | **Dates** | Hijri dates, Ramadan, public holidays with observed moon-sighting dates | `hijri`, `holidays` |
77
+ | **Forms** | As-you-type formatting and checking; schemas for Zod, Valibot, Yup, Joi and Superstruct; class-validator decorators for NestJS; Laravel rules, DataAnnotations and FluentValidation in the ports; React, Vue, Angular and Flutter inputs | `input`, `zod`, `valibot`, `yup`, `joi`, `superstruct`, `class-validator` |
70
78
 
71
- ## Why PakDataKit?
79
+ ---
72
80
 
73
- Most Pakistani apps validate CNICs, mobile numbers and IBANs with a regex copied from somewhere. A regex checks the shape. PakDataKit checks what the shape can't show:
81
+ ## 🚀 Quick start
74
82
 
75
- | Task | Typical regex | PakDataKit |
76
- | ----------------- | ---------------------------- | ----------------------------------------------------------------------------------------------- |
77
- | CNIC | 13 digits, maybe with dashes | Province code, province and gender decoding, Urdu digits |
78
- | Mobile number | `03` + 9 digits | Allocated `03XX` prefixes only, `+92` / `0092` / `0` forms, original network |
79
- | IBAN | `PK` + 22 characters | Mod-97 checksum, bank name and type from the bank code |
80
- | NTN / STRN | Digit count | CNIC-based and business NTNs, display formats |
81
- | Passport, plates | Usually not handled | Common-shape checks, with sources and limits in [DATA.md](./DATA.md) |
82
- | Raast QR | Not possible | Create, parse and check payment QR codes (CRC, IBAN, amount, expiry) |
83
- | Holidays, Hijri | Not possible | Observed Eid/Ashura/Milad dates from official notifications, Hijri conversion |
84
- | Amounts, currency | Not possible | Lakh/crore formatting, amounts in words in English and Urdu |
85
- | 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 12,000 shared test cases |
87
-
88
- 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).
83
+ **TypeScript / JavaScript** (Node 20+, browsers, Bun, Deno; `import` or `require`)
89
84
 
90
- ---
85
+ ```ts
86
+ import { validateCNIC, getBankFromIBAN, calculateSalaryTax } from 'pakdatakit';
91
87
 
92
- ## Features
93
-
94
- - ✅ CNIC Validation
95
- - ✅ CNIC Province & Gender Decoding
96
- - ✅ Phone Number Validation
97
- - ✅ Phone Number Normalization
98
- - ✅ Phone Intelligence (`analyzePhone`)
99
- - ✅ WhatsApp Link Generator
100
- - ✅ IBAN Validation
101
- - ✅ Bank Detection from IBAN
102
- - ✅ Postal Code Lookup
103
- - ✅ Address Parsing
104
- - ✅ Roman Urdu Normalization
105
- - ✅ Hijri Date Utilities
106
- - ✅ CLI Tool
107
- - ✅ Mobile Network Detection
108
- - ✅ City → Province Lookup
109
- - ✅ PKR Formatting
110
- - ✅ Lakh / Crore Formatting
111
- - ✅ Amounts in Words (English & Urdu, cheque style)
112
- - ✅ Zod, Valibot & Yup Form Validation
113
- - ✅ As-You-Type Formatting for CNIC, Phone & IBAN
114
- - ✅ NTN & STRN Validation
115
- - ✅ Landline, UAN (111), Toll-Free (0800) & Premium (0900) Numbers
116
- - ✅ Raast QR Codes (SBP standard)
117
- - ✅ Pakistan Public Holidays (moon-sighting aware)
118
-
119
- ### Developer Friendly
120
-
121
- - Fully Typed (TypeScript)
122
- - Zero Runtime Dependencies (form libraries are optional peers)
123
- - Tree-Shakeable
124
- - Lightweight & Fast
125
- - ESM and CommonJS, with per-module subpath imports
126
- - Production Ready
88
+ validateCNIC('35202-1234567-1'); // true
89
+ getBankFromIBAN('PK36SCBL0000001123456702'); // "Standard Chartered Bank (Pakistan) Limited"
90
+ calculateSalaryTax(5_000_000, { taxYear: 2027 })?.tax; // 802000
91
+ ```
127
92
 
128
- ---
93
+ **Python** (3.9+)
129
94
 
130
- ## Installation
95
+ ```python
96
+ from pakdatakit import validate_cnic, get_bank_from_iban, calculate_salary_tax
131
97
 
132
- ```bash
133
- npm install pakdatakit
98
+ validate_cnic("35202-1234567-1") # True
99
+ get_bank_from_iban("PK36SCBL0000001123456702") # "Standard Chartered Bank (Pakistan) Limited"
100
+ calculate_salary_tax(5_000_000, tax_year=2027).tax # 802000
134
101
  ```
135
102
 
136
- Requirements:
103
+ **Dart / Flutter**
137
104
 
138
- - Node.js 20+
139
- - Works with both `import` and `require()`
105
+ ```dart
106
+ import 'package:pakdatakit/pakdatakit.dart';
140
107
 
141
- Import everything from `pakdatakit`, or a single module to keep bundles small:
108
+ validateCNIC('35202-1234567-1'); // true
109
+ getBankFromIBAN('PK36SCBL0000001123456702'); // Standard Chartered Bank (Pakistan) Limited
110
+ calculateSalaryTax(5000000, taxYear: 2027)?.tax; // 802000
142
111
 
143
- ```ts
144
- import { validateCNIC } from 'pakdatakit/cnic';
145
- const { analyzePhone } = require('pakdatakit/phone');
112
+ // pakdatakit_flutter
113
+ TextFormField(inputFormatters: [CnicInputFormatter()], validator: PakValidators.cnic());
146
114
  ```
147
115
 
148
- Subpaths: `address`, `cnic`, `format`, `geo`, `hijri`, `holidays`, `iban`, `input`, `networks`, `numbers`, `passport`, `phone`, `postal`, `raast`, `tax`, `text`, `vehicle`, `whatsapp`, `words`, plus the form adapters `zod`, `valibot`, `yup`, `joi`, `superstruct` and `class-validator`.
116
+ **.NET** (8+)
149
117
 
150
- ---
118
+ ```csharp
119
+ using PakDataKit;
151
120
 
152
- ## Quick Start
121
+ Cnic.Validate("35202-1234567-1"); // true
122
+ Iban.GetBank("PK36SCBL0000001123456702"); // "Standard Chartered Bank (Pakistan) Limited"
123
+ IncomeTax.CalculateSalaryTax(5_000_000, new SalaryTaxOptions { TaxYear = 2027 })?.Tax; // 802000
153
124
 
154
- ```ts
155
- import {
156
- validateCNIC,
157
- analyzePhone,
158
- createWhatsAppLink,
159
- validateIBAN,
160
- getBankFromIBAN,
161
- getPostalCode,
162
- getCityByPostalCode,
163
- getNetwork,
164
- formatLakh,
165
- } from 'pakdatakit';
125
+ // PakDataKit.DataAnnotations: [Cnic] public string Cnic { get; set; }
126
+ // PakDataKit.FluentValidation: RuleFor(x => x.Cnic).IsCnic();
127
+ ```
166
128
 
167
- validateCNIC('35202-1234567-1');
168
- // true
129
+ **PHP / Laravel** (8.2+)
169
130
 
170
- analyzePhone('03001234567');
171
- // { valid: true, formatted: "+923001234567", network: "Jazz" }
131
+ ```php
132
+ use PakDataKit\Cnic;
133
+ use PakDataKit\Iban;
134
+ use PakDataKit\IncomeTax;
172
135
 
173
- createWhatsAppLink('03001234567', 'Assalamualaikum');
174
- // "https://wa.me/923001234567?text=Assalamualaikum"
136
+ Cnic::validate('35202-1234567-1'); // true
137
+ Iban::getBank('PK36SCBL0000001123456702'); // "Standard Chartered Bank (Pakistan) Limited"
138
+ IncomeTax::calculateSalary(5000000, ['taxYear' => 2027])?->tax; // 802000
175
139
 
176
- validateIBAN('PK36SCBL0000001123456702');
177
- // true
140
+ // Laravel: $request->validate(['cnic' => ['required', 'pk_cnic'], 'phone' => 'pk_phone']);
141
+ ```
178
142
 
179
- getBankFromIBAN('PK36SCBL0000001123456702');
180
- // "Standard Chartered Bank (Pakistan) Limited"
143
+ **React, Vue and Angular**
181
144
 
182
- getPostalCode('Multan');
183
- // "60000"
184
-
185
- getCityByPostalCode('60000');
186
- // "Multan"
145
+ ```tsx
146
+ // React
147
+ import { CNICInput } from 'pakdatakit-react';
148
+ <CNICInput onValueChange={(value, state, info) => {}} />;
149
+ ```
187
150
 
188
- getNetwork('03001234567');
189
- // "Jazz"
151
+ ```vue
152
+ <!-- Vue -->
153
+ <input v-model="cnic" v-pak-input:cnic />
154
+ ```
190
155
 
191
- formatLakh(2500000);
192
- // "25 Lakh"
156
+ ```html
157
+ <!-- Angular: import PakCnicInputDirective; validate with PakValidators.cnic -->
158
+ <input pakCnicInput [formControl]="cnic" />
193
159
  ```
194
160
 
195
- ### CLI
161
+ **CLI**
196
162
 
197
163
  ```bash
198
164
  npx pakdatakit validate-cnic 35202-1234567-1
199
165
  npx pakdatakit analyze-phone 03001234567
200
166
  npx pakdatakit parse-address "House 12, Gulberg III, Lahore, Punjab 54660"
201
- npx pakdatakit hijri
202
- npx pakdatakit normalize-urdu "ap kia ker rhe ho"
203
167
  ```
204
168
 
205
- The CLI exits with status 0 when the input is valid or found, 1 when it is invalid or not found, and 2 for usage errors, so it can be used in scripts. Run `npx pakdatakit --help` for all commands.
169
+ The CLI exits with 0 when the input is valid or found, 1 when it is not, and 2 for usage errors. Run `npx pakdatakit --help` for every command.
170
+
171
+ ---
172
+
173
+ ## Why PakDataKit?
174
+
175
+ Most Pakistani apps validate CNICs, mobile numbers and IBANs with a regex copied from somewhere. A regex checks the shape. PakDataKit checks what the shape can't show:
176
+
177
+ | Task | Typical regex | PakDataKit |
178
+ | --------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- |
179
+ | CNIC | 13 digits, maybe with dashes | Province code, province and gender decoding, Urdu digits |
180
+ | Mobile number | `03` + 9 digits | Allocated `03XX` prefixes only, `+92` / `0092` / `0` forms, original network |
181
+ | IBAN | `PK` + 22 characters | Mod-97 checksum, bank name and type from the bank code |
182
+ | NTN / STRN | Digit count | CNIC-based and business NTNs, display formats |
183
+ | Sales tax, income tax | Hard-coded rates | Rates by authority and date with their legal source; exact amounts in whole paisa |
184
+ | FBR invoices | Found out at submission | Offline validation with FBR's own error codes |
185
+ | Raast QR | Not possible | Create, parse and check payment QR codes (CRC, IBAN, amount, expiry) |
186
+ | Holidays, Hijri | Not possible | Observed Eid/Ashura/Milad dates from official notifications, Hijri conversion |
187
+ | Forms | Write each rule per library | Ready rules for Zod, Valibot, Yup, Joi, Superstruct, class-validator, Laravel, DataAnnotations and FluentValidation |
206
188
 
207
189
  ---
208
190
 
@@ -655,6 +637,53 @@ Formats structured components back into a mailing address string. Only the compo
655
637
 
656
638
  ---
657
639
 
640
+ ## Cash on Delivery Checks
641
+
642
+ `import { scoreAddress, phoneRiskSignals } from 'pakdatakit/quality'`
643
+
644
+ 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.
645
+
646
+ ### scoreAddress()
647
+
648
+ 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.
649
+
650
+ ```ts
651
+ scoreAddress(
652
+ 'House 12, Street 4, Block B, Gulberg III, near Liberty Market, Lahore 54660',
653
+ );
654
+ // { score: 100, missing: [], parsed: { city: "Lahore", postalCode: "54660", ... } }
655
+
656
+ scoreAddress('Lahore').missing;
657
+ // ["houseNumber", "street", "area", "postalCode", "landmark"]
658
+ ```
659
+
660
+ | Part | Points | Found when |
661
+ | ------------- | -----: | ------------------------------------------------------------------------------------------------- |
662
+ | `city` | 30 | `parseAddress` finds a city |
663
+ | `houseNumber` | 20 | a number other than the postal code ("House 12", "12b", "Flat 2") |
664
+ | `street` | 15 | street, road, lane, gali, chowk, bazaar, mohalla, گلی, محلہ … |
665
+ | `area` | 10 | an area segment, or block, sector, phase, town, colony, society, بلاک, سیکٹر … |
666
+ | `postalCode` | 15 | a known post office code (an unknown 5-digit code scores 5) |
667
+ | `landmark` | 10 | near, opp, behind, next to; nazd, nazdeek, qareeb, samne, peechay, bilmuqabil; نزد، قریب، سامنے … |
668
+
669
+ The weights are exported as `ADDRESS_WEIGHTS`. Importing `scoreAddress` adds about 44 kB gzipped (the post office directory); `phoneRiskSignals` alone is about 3 kB.
670
+
671
+ ### phoneRiskSignals()
672
+
673
+ Returns the reasons to double-check a phone number given for a delivery, or `[]`.
674
+
675
+ ```ts
676
+ phoneRiskSignals('0301-2945716'); // []
677
+ phoneRiskSignals('03001234567'); // ["sequential-digits", "test-number"]
678
+ phoneRiskSignals('03000000000'); // ["repeated-digits"]
679
+ phoneRiskSignals('042 35761234'); // ["landline"]
680
+ phoneRiskSignals('12345'); // ["invalid"]
681
+ ```
682
+
683
+ 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.
684
+
685
+ ---
686
+
658
687
  ## Text Utilities
659
688
 
660
689
  ### normalizeRomanUrdu()
@@ -665,6 +694,58 @@ Normalizes informal Roman Urdu spellings (`ap kia ker` → `aap kya kar`).
665
694
 
666
695
  Convert between English, Urdu, and Arabic-Indic digits.
667
696
 
697
+ ### slugify()
698
+
699
+ 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`).
700
+
701
+ ```ts
702
+ slugify('Lahore Fort, 2024'); // "lahore-fort-2024"
703
+ slugify('لاہور قلعہ'); // "لاہور-قلعہ"
704
+ slugify('لاہور Fort', { script: 'latin' }); // "fort"
705
+ slugify('کراچی ۲۰۲۴', { script: 'urdu' }); // "کراچی-2024"
706
+ ```
707
+
708
+ ### compareUrdu()
709
+
710
+ 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.
711
+
712
+ ```ts
713
+ ['ے', 'بھائی', 'آم', 'باغ', 'اب'].sort(compareUrdu);
714
+ // ["اب", "آم", "باغ", "بھائی", "ے"]
715
+ ```
716
+
717
+ 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.
718
+
719
+ ### isRTL() / wrapBidi()
720
+
721
+ `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.
722
+
723
+ ```ts
724
+ isRTL('123 سلام'); // true
725
+ isRTL('Order نمبر'); // false
726
+ `آرڈر ${wrapBidi('PDK-1042')} بھیج دیا گیا`;
727
+ ```
728
+
729
+ ---
730
+
731
+ ## Income Tax on Salary
732
+
733
+ `import { calculateSalaryTax } from 'pakdatakit/incometax'`
734
+
735
+ 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.
736
+
737
+ ```ts
738
+ calculateSalaryTax(1_800_000, { taxYear: 2026 });
739
+ // { tax: 72000, monthly: 6000, effectiveRate: 4,
740
+ // slab: { over: 1200000, upTo: 2200000, fixed: 6000, rate: 11 }, taxYear: 2026 }
741
+
742
+ calculateMonthlySalaryTax(150_000, { taxYear: 2026 })?.monthly; // 6000
743
+ getSalaryTaxSlabs(2027); // the table, its law and FBR source
744
+ getTaxYear('2025-07-01'); // 2026
745
+ ```
746
+
747
+ 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).
748
+
668
749
  ---
669
750
 
670
751
  ## Hijri Calendar
@@ -783,6 +864,183 @@ FBR does not publish its check-digit algorithms, so these check the format only.
783
864
 
784
865
  ---
785
866
 
867
+ ## Sales Tax
868
+
869
+ `import { getSalesTaxRate, calculateSalesTax, splitInclusive } from 'pakdatakit/salestax'`
870
+
871
+ 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.
872
+
873
+ ### getSalesTaxRate()
874
+
875
+ ```ts
876
+ getSalesTaxRate({ kind: 'goods', date: '2026-11-18' });
877
+ // { 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/…" }
878
+
879
+ getSalesTaxRate({ kind: 'services', province: 'Sindh', date: '2024-06-30' })
880
+ ?.rate; // 13
881
+ getSalesTaxRate({ kind: 'services', province: 'ICT' })?.rate; // 15 (today)
882
+ ```
883
+
884
+ `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.
885
+
886
+ ### calculateSalesTax() / splitInclusive()
887
+
888
+ ```ts
889
+ calculateSalesTax(1000, { rate: 18 });
890
+ // { net: 1000, tax: 180, gross: 1180, rate: 18 }
891
+
892
+ calculateSalesTax(1000, { province: 'Punjab' });
893
+ // { net: 1000, tax: 160, gross: 1160, rate: 16 }
894
+
895
+ calculateSalesTax(1150, { province: 'Sindh', inclusive: true });
896
+ // { net: 1000, tax: 150, gross: 1150, rate: 15 }
897
+
898
+ splitInclusive(99.99, 18);
899
+ // { net: 84.74, tax: 15.25, gross: 99.99, rate: 18 }
900
+ ```
901
+
902
+ 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.
903
+
904
+ ---
905
+
906
+ ## Utility Bills
907
+
908
+ `import { parseElectricityRef, validateElectricityRef, validateGasConsumerNumber } from 'pakdatakit/bills'`
909
+
910
+ ### parseElectricityRef() / validateElectricityRef()
911
+
912
+ Reads the identifiers printed on electricity bills, in the formats the utilities' own bill pages ask for:
913
+
914
+ | `type` | Format | Example |
915
+ | ------------- | ---------------------------------------------------------- | -------------------- |
916
+ | `reference` | DISCO (WAPDA) reference number: 14 digits, optional U or R | `02 12624 0045901 R` |
917
+ | `customer-id` | DISCO customer ID: 10 digits (11 for LESCO) | `1234567890` |
918
+ | `k-electric` | K-Electric account number: 13 digits starting `04000` | `0400012345678` |
919
+
920
+ ```ts
921
+ parseElectricityRef('02-12624-0045901 R');
922
+ // { type: "reference", digits: "02126240045901", formatted: "02 12624 0045901 R", urbanRural: "R", disco: null }
923
+
924
+ parseElectricityRef('0400012345678');
925
+ // { type: "k-electric", digits: "0400012345678", formatted: "0400012345678", urbanRural: null, disco: "K-Electric" }
926
+
927
+ validateElectricityRef('12345'); // false
928
+ ```
929
+
930
+ 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.
931
+
932
+ ### validateGasConsumerNumber()
933
+
934
+ ```ts
935
+ validateGasConsumerNumber('12345678901', 'SNGPL'); // true (11 digits)
936
+ validateGasConsumerNumber('1234567890', 'SSGC'); // true (10 digits)
937
+ ```
938
+
939
+ Sources are in [DATA.md](DATA.md#electricity-and-gas-bill-numbers).
940
+
941
+ ---
942
+
943
+ ## Couriers
944
+
945
+ `import { mapCourierStatus, normalizeCityForCourier } from 'pakdatakit/courier'`
946
+
947
+ Helpers for orders shipped with Pakistani couriers. There are no API clients: nothing is sent anywhere.
948
+
949
+ ### mapCourierStatus()
950
+
951
+ > **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).
952
+
953
+ 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`.
954
+
955
+ ```ts
956
+ mapCourierStatus('PostEx', 'Out For Delivery'); // "out-for-delivery"
957
+ mapCourierStatus('PostEx', 5); // "delivered"
958
+ mapCourierStatus('PostEx', 'Attempt Made: Customer not available'); // "attempted"
959
+ mapCourierStatus('Leopards', 'Returned to Shipper'); // "returned"
960
+ mapCourierStatus('TCS', 'Delivered'); // null
961
+ ```
962
+
963
+ 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).
964
+
965
+ ### normalizeCityForCourier()
966
+
967
+ 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.
968
+
969
+ ```ts
970
+ normalizeCityForCourier('LHR'); // "Lahore"
971
+ normalizeCityForCourier('Khi'); // "Karachi"
972
+ normalizeCityForCourier('Pindi'); // "Rawalpindi"
973
+ normalizeCityForCourier('lyallpur'); // "Faisalabad"
974
+ normalizeCityForCourier('Karachi City'); // "Karachi"
975
+ normalizeCityForCourier('لاہور'); // "Lahore"
976
+ normalizeCityForCourier('Atlantis'); // null
977
+ ```
978
+
979
+ ---
980
+
981
+ ## FBR Digital Invoicing
982
+
983
+ `import { buildFbrInvoice, validateFbrInvoice } from 'pakdatakit/fbr-invoice'`
984
+
985
+ 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.
986
+
987
+ ### buildFbrInvoice()
988
+
989
+ Works out each line's `salesTaxApplicable` when you leave it out (with `calculateSalesTax`), fills FBR's defaults and adds up the columns.
990
+
991
+ ```ts
992
+ const { invoice, totals } = buildFbrInvoice({
993
+ invoiceType: 'Sale Invoice',
994
+ invoiceDate: '2025-04-21',
995
+ sellerNTNCNIC: '1234567',
996
+ sellerBusinessName: 'Example Traders',
997
+ sellerProvince: 'Sindh',
998
+ sellerAddress: 'Karachi',
999
+ buyerNTNCNIC: '7654321',
1000
+ buyerBusinessName: 'Example Buyer',
1001
+ buyerProvince: 'Punjab',
1002
+ buyerAddress: 'Lahore',
1003
+ buyerRegistrationType: 'Registered',
1004
+ items: [
1005
+ {
1006
+ hsCode: '0101.2100',
1007
+ productDescription: 'Horses',
1008
+ rate: '18%',
1009
+ uoM: 'Numbers, pieces, units',
1010
+ quantity: 2,
1011
+ valueSalesExcludingST: 1234,
1012
+ saleType: 'Goods at standard rate (default)',
1013
+ },
1014
+ ],
1015
+ })!;
1016
+ invoice.items[0].salesTaxApplicable; // 222.12
1017
+ totals.salesTaxApplicable; // 222.12
1018
+ ```
1019
+
1020
+ 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.
1021
+
1022
+ ### validateFbrInvoice()
1023
+
1024
+ Returns every problem it can find without calling FBR, with FBR's error code:
1025
+
1026
+ ```ts
1027
+ validateFbrInvoice(invoice);
1028
+ // { valid: true, errors: [] }
1029
+
1030
+ validateFbrInvoice({
1031
+ ...invoice,
1032
+ invoiceDate: '21-04-2025',
1033
+ buyerNTNCNIC: invoice.sellerNTNCNIC,
1034
+ });
1035
+ // { valid: false, errors: [
1036
+ // { code: "0005", field: "invoiceDate", message: "Invoice date must be in YYYY-MM-DD format" },
1037
+ // { code: "0058", field: "buyerNTNCNIC", message: "Buyer and seller must be different (self-invoicing is not allowed)" } ] }
1038
+ ```
1039
+
1040
+ 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.
1041
+
1042
+ ---
1043
+
786
1044
  ## Passports & Vehicle Plates
787
1045
 
788
1046
  ### validatePassport()
@@ -951,7 +1209,7 @@ import { pk } from 'pakdatakit/superstruct';
951
1209
  const CheckoutForm = object({ cnic: pk.cnic(), phone: optional(pk.phone()) });
952
1210
  ```
953
1211
 
954
- Available schemas: `pk.cnic()`, `pk.phone()`, `pk.iban()`, `pk.ntn()`, `pk.strn()`, `pk.landline()`, `pk.passport()` and `pk.vehiclePlate()`. Every factory accepts `{ message }` to replace the default error. The Yup schemas let empty values pass so `.required()` decides whether a field is mandatory.
1212
+ 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
1213
 
956
1214
  ### class-validator and NestJS
957
1215
 
@@ -974,7 +1232,7 @@ export class CreateCustomerDto {
974
1232
  }
975
1233
  ```
976
1234
 
977
- Decorators: `IsCNIC`, `IsPakPhone`, `IsPakIBAN` (named so it doesn't clash with class-validator's own `IsIBAN`), `IsNTN`, `IsSTRN`, `IsPakLandline`, `IsPakPassport` and `IsVehiclePlate`, 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.
1235
+ 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
1236
 
979
1237
  ### As-you-type helpers
980
1238
 
@@ -1057,67 +1315,6 @@ const budget = formatLakh(2500000);
1057
1315
 
1058
1316
  ---
1059
1317
 
1060
- # Roadmap
1061
-
1062
- ### v0.2 ✅
1063
-
1064
- - Phone Intelligence (`analyzePhone`)
1065
- - WhatsApp Link Generator
1066
- - IBAN Validation
1067
- - Bank Detection from IBAN
1068
- - Postal Code Lookup
1069
- - Expanded datasets (cities, districts, postal codes, banks)
1070
-
1071
- ### v0.3 ✅
1072
-
1073
- - Address Parsing (`parseAddress`, `formatAddress`)
1074
- - Expanded Postal Data (`getPostalAreas`, `searchPostalCodes`)
1075
-
1076
- ### v0.4 ✅
1077
-
1078
- - Roman Urdu Utilities (`normalizeRomanUrdu`)
1079
- - Text Normalization (`normalizeText`, `toUrduDigits`, `toEnglishDigits`)
1080
-
1081
- ### v0.5 ✅
1082
-
1083
- - Islamic Calendar Utilities (`toHijri`, `fromHijri`, `formatHijri`)
1084
- - Hijri Date Helpers (`getHijriMonthName`, `isRamadan`)
1085
-
1086
- ### v1.0 ✅
1087
-
1088
- - CLI Tool (`pakdatakit` command)
1089
- - Dataset-backed lookup APIs
1090
- - Community Contributions (see CONTRIBUTING.md)
1091
-
1092
- ### v1.1 ✅
1093
-
1094
- - Interactive Playground ([pakdatakit-playground.vercel.app](https://pakdatakit-playground.vercel.app/))
1095
-
1096
- ### v2.0 ✅
1097
-
1098
- - Bug-fix release; see [CHANGELOG.md](./CHANGELOG.md) for breaking changes
1099
- - CommonJS build and subpath imports
1100
- - Corrected Hijri dates, datasets and validation
1101
-
1102
- ### v2.1 ✅
1103
-
1104
- - CNIC province & gender decoding (`getCNICInfo`)
1105
- - Amounts in words in English and Urdu (`amountInWords`, `numberToWords`)
1106
- - Zod, Valibot and Yup adapters
1107
- - NTN and STRN validation
1108
- - Landline, UAN, toll-free and premium numbers
1109
- - Raast QR codes
1110
- - Public holidays with observed moon-sighting dates
1111
-
1112
- ### v2.2 ✅
1113
-
1114
- - Python package on PyPI, Dart package on pub.dev
1115
- - `pakdatakit-react` form inputs, `pakdatakit-faker` test data and
1116
- `pakdatakit_flutter` widgets
1117
- - Bank details (`getBankInfo`, `getBanks`), API docs and `llms.txt`
1118
-
1119
- ---
1120
-
1121
1318
  # Contributing
1122
1319
 
1123
1320
  Contributions are welcome.
@@ -1133,9 +1330,31 @@ See:
1133
1330
 
1134
1331
  ---
1135
1332
 
1333
+ # Origin and attribution
1334
+
1335
+ - First commit: 29 May 2026,
1336
+ [`bdc426a`](https://github.com/chmuzamil/pakdatakit/commit/bdc426a84a1b4359dee218c33196810d6631559d)
1337
+ (git history).
1338
+ - First npm release:
1339
+ [`pakdatakit` 1.0.0](https://www.npmjs.com/package/pakdatakit/v/1.0.0), 29 May
1340
+ 2026 (npm registry).
1341
+
1342
+ PakDataKit is released under the MIT licence. This covers the code of every
1343
+ port, the datasets in `data/` and the shared test vectors in `test-vectors/`.
1344
+ Anyone who copies or adapts any substantial part of it, in any language, must
1345
+ keep the copyright notice and the licence text:
1346
+
1347
+ ```text
1348
+ Copyright (c) 2026 Muzamil Chaudhery and PakDataKit Contributors
1349
+ ```
1350
+
1351
+ The same text is in [NOTICE](NOTICE).
1352
+
1353
+ ---
1354
+
1136
1355
  # License
1137
1356
 
1138
- MIT License
1357
+ MIT License. See [LICENSE](LICENSE).
1139
1358
 
1140
1359
  ---
1141
1360