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.
- package/DATA.md +212 -3
- package/LICENSE +1 -1
- package/NOTICE +14 -0
- package/README.md +426 -207
- 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 +74 -11
- 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/README.md
CHANGED
|
@@ -5,204 +5,186 @@
|
|
|
5
5
|
<h1 align="center">🇵🇰 PakDataKit</h1>
|
|
6
6
|
|
|
7
7
|
<p align="center">
|
|
8
|
-
<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
|
-
|
|
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
|
-
|
|
18
|
-
|
|
19
|
-
<a href="https://www.npmjs.com/package/pakdatakit">
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
<img src="https://img.shields.io/npm
|
|
23
|
-
<img src="https://img.shields.io/badge/
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
47
|
-
|
|
|
48
|
-
| [`pakdatakit`](https://www.npmjs.com/package/pakdatakit)
|
|
49
|
-
| [`pakdatakit`
|
|
50
|
-
| [`pakdatakit
|
|
51
|
-
| [`
|
|
52
|
-
| [`
|
|
53
|
-
| [`
|
|
54
|
-
| [`PakDataKit`
|
|
55
|
-
| [`chmuzamil/pakdatakit`
|
|
56
|
-
| [`pakdatakit-
|
|
57
|
-
| [`pakdatakit-
|
|
58
|
-
|
|
59
|
-
|
|
46
|
+
| Package | Registry | Install | Version |
|
|
47
|
+
| ---------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
|
48
|
+
| [`pakdatakit`](https://www.npmjs.com/package/pakdatakit) | npm | `npm install pakdatakit` | [](https://www.npmjs.com/package/pakdatakit) |
|
|
49
|
+
| [`pakdatakit`](https://pypi.org/project/pakdatakit/) ([Python](./python)) | PyPI | `pip install pakdatakit` | [](https://pypi.org/project/pakdatakit/) |
|
|
50
|
+
| [`pakdatakit`](https://pub.dev/packages/pakdatakit) ([Dart](./dart)) | pub.dev | `dart pub add pakdatakit` | [](https://pub.dev/packages/pakdatakit) |
|
|
51
|
+
| [`pakdatakit_flutter`](https://pub.dev/packages/pakdatakit_flutter) ([Flutter](./flutter)) | pub.dev | `flutter pub add pakdatakit_flutter` | [](https://pub.dev/packages/pakdatakit_flutter) |
|
|
52
|
+
| [`PakDataKit`](https://www.nuget.org/packages/PakDataKit) ([.NET](./dotnet)) | NuGet | `dotnet add package PakDataKit` | [](https://www.nuget.org/packages/PakDataKit) |
|
|
53
|
+
| [`PakDataKit.DataAnnotations`](https://www.nuget.org/packages/PakDataKit.DataAnnotations) | NuGet | `dotnet add package PakDataKit.DataAnnotations` | [](https://www.nuget.org/packages/PakDataKit.DataAnnotations) |
|
|
54
|
+
| [`PakDataKit.FluentValidation`](https://www.nuget.org/packages/PakDataKit.FluentValidation) | NuGet | `dotnet add package PakDataKit.FluentValidation` | [](https://www.nuget.org/packages/PakDataKit.FluentValidation) |
|
|
55
|
+
| [`chmuzamil/pakdatakit`](https://packagist.org/packages/chmuzamil/pakdatakit) ([PHP/Laravel](./php)) | Packagist | `composer require chmuzamil/pakdatakit` | [](https://packagist.org/packages/chmuzamil/pakdatakit) |
|
|
56
|
+
| [`pakdatakit-react`](https://www.npmjs.com/package/pakdatakit-react) ([React](./react)) | npm | `npm install pakdatakit-react` | [](https://www.npmjs.com/package/pakdatakit-react) |
|
|
57
|
+
| [`pakdatakit-vue`](https://www.npmjs.com/package/pakdatakit-vue) ([Vue](./vue)) | npm | `npm install pakdatakit-vue` | [](https://www.npmjs.com/package/pakdatakit-vue) |
|
|
58
|
+
| [`pakdatakit-angular`](https://www.npmjs.com/package/pakdatakit-angular) ([Angular](./angular)) | npm | `npm install pakdatakit-angular` | [](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` | [](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` | [](https://www.npmjs.com/package/pakdatakit-pay) |
|
|
60
61
|
|
|
61
62
|
---
|
|
62
63
|
|
|
63
|
-
##
|
|
64
|
+
## 🧩 Modules
|
|
64
65
|
|
|
65
|
-
|
|
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
|
-
|
|
79
|
+
---
|
|
72
80
|
|
|
73
|
-
|
|
81
|
+
## 🚀 Quick start
|
|
74
82
|
|
|
75
|
-
|
|
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
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
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
|
-
|
|
95
|
+
```python
|
|
96
|
+
from pakdatakit import validate_cnic, get_bank_from_iban, calculate_salary_tax
|
|
131
97
|
|
|
132
|
-
|
|
133
|
-
|
|
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
|
-
|
|
103
|
+
**Dart / Flutter**
|
|
137
104
|
|
|
138
|
-
|
|
139
|
-
|
|
105
|
+
```dart
|
|
106
|
+
import 'package:pakdatakit/pakdatakit.dart';
|
|
140
107
|
|
|
141
|
-
|
|
108
|
+
validateCNIC('35202-1234567-1'); // true
|
|
109
|
+
getBankFromIBAN('PK36SCBL0000001123456702'); // Standard Chartered Bank (Pakistan) Limited
|
|
110
|
+
calculateSalaryTax(5000000, taxYear: 2027)?.tax; // 802000
|
|
142
111
|
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
const { analyzePhone } = require('pakdatakit/phone');
|
|
112
|
+
// pakdatakit_flutter
|
|
113
|
+
TextFormField(inputFormatters: [CnicInputFormatter()], validator: PakValidators.cnic());
|
|
146
114
|
```
|
|
147
115
|
|
|
148
|
-
|
|
116
|
+
**.NET** (8+)
|
|
149
117
|
|
|
150
|
-
|
|
118
|
+
```csharp
|
|
119
|
+
using PakDataKit;
|
|
151
120
|
|
|
152
|
-
|
|
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
|
-
|
|
155
|
-
|
|
156
|
-
|
|
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
|
-
|
|
168
|
-
// true
|
|
129
|
+
**PHP / Laravel** (8.2+)
|
|
169
130
|
|
|
170
|
-
|
|
171
|
-
|
|
131
|
+
```php
|
|
132
|
+
use PakDataKit\Cnic;
|
|
133
|
+
use PakDataKit\Iban;
|
|
134
|
+
use PakDataKit\IncomeTax;
|
|
172
135
|
|
|
173
|
-
|
|
174
|
-
// "
|
|
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
|
-
|
|
177
|
-
|
|
140
|
+
// Laravel: $request->validate(['cnic' => ['required', 'pk_cnic'], 'phone' => 'pk_phone']);
|
|
141
|
+
```
|
|
178
142
|
|
|
179
|
-
|
|
180
|
-
// "Standard Chartered Bank (Pakistan) Limited"
|
|
143
|
+
**React, Vue and Angular**
|
|
181
144
|
|
|
182
|
-
|
|
183
|
-
//
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
145
|
+
```tsx
|
|
146
|
+
// React
|
|
147
|
+
import { CNICInput } from 'pakdatakit-react';
|
|
148
|
+
<CNICInput onValueChange={(value, state, info) => {}} />;
|
|
149
|
+
```
|
|
187
150
|
|
|
188
|
-
|
|
189
|
-
|
|
151
|
+
```vue
|
|
152
|
+
<!-- Vue -->
|
|
153
|
+
<input v-model="cnic" v-pak-input:cnic />
|
|
154
|
+
```
|
|
190
155
|
|
|
191
|
-
|
|
192
|
-
|
|
156
|
+
```html
|
|
157
|
+
<!-- Angular: import PakCnicInputDirective; validate with PakValidators.cnic -->
|
|
158
|
+
<input pakCnicInput [formControl]="cnic" />
|
|
193
159
|
```
|
|
194
160
|
|
|
195
|
-
|
|
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
|
|
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.
|
|
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 `
|
|
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
|
|