# pakdatakit 2.5.0

> Release notes for pakdatakit 2.5.0 (TypeScript, Python, Dart, .NET, PHP): what changed, what was fixed and how to upgrade.

Source: https://pakdatakit.dev/releases/2.5.0/

## TypeScript (npm)

[pakdatakit 2.5.0](https://www.npmjs.com/package/pakdatakit/v/2.5.0)

Includes everything prepared for 2.4.0, which was never published on its own: the 2.4.0 changes are listed here with the 2.5.0 ones.

### Added

- `slugify()`, `compareUrdu()`, `isRTL()` and `wrapBidi()` (`pakdatakit/text`).
  `slugify` makes URL slugs that keep Urdu letters (no transliteration), with
  `script: 'any' | 'latin' | 'urdu'`. `compareUrdu` sorts in Urdu alphabetical
  order following the Unicode CLDR collation for Urdu (CLDR 49), with letters
  joined to ھ as letters of their own, the same in every port without ICU.
  `isRTL` checks the first letter's direction; `wrapBidi` wraps text in
  Unicode directional isolates.
- `calculateSalaryTax()`, `calculateMonthlySalaryTax()`, `getSalaryTaxSlabs()`,
  `getSalaryTaxYears()` and `getTaxYear()` (`pakdatakit/incometax`), with the
  new dataset `data/income-tax-slabs.json`: the salaried income tax rate table
  for tax years 2020 to 2027 from FBR's consolidated Income Tax Ordinance.
  Returns the tax, the monthly amount, the effective rate and the slab, rounded
  half up to the paisa. Surcharge, credits and exemptions are not applied.
  The `source` for tax year 2027 is the Finance Act, 2026 as gazetted; FBR
  Circular No. 02 of 2026-27 and the consolidated Ordinance are cited in
  DATA.md.
- `scoreAddress()` and `phoneRiskSignals()` (`pakdatakit/quality`): heuristics
  for cash on delivery. `scoreAddress` scores an address 0 to 100 from its city,
  house number, street, area, postal code (a known post office scores more)
  and landmark words in English, Roman Urdu and Urdu, and lists what is
  missing. `phoneRiskSignals` flags invalid, landline, service, repeated-digit,
  sequential and placeholder numbers. The form adapters gain `pk.codPhone()`
  (`IsCodPhone` for class-validator).
- `getSalesTaxRate()`, `calculateSalesTax()` and `splitInclusive()`
  (`pakdatakit/salestax`): standard sales tax rates with the dates they
  applied, from 1 July 2019, for goods (federal) and for services in Punjab,
  Sindh, Khyber Pakhtunkhwa, Balochistan and Islamabad Capital Territory, each
  with its law and official source (new dataset `sales-tax-rates.json`).
  Amounts are rounded half up to the paisa.
- `parseElectricityRef()`, `validateElectricityRef()` and
  `validateGasConsumerNumber()` (`pakdatakit/bills`): DISCO 14-digit reference
  numbers (with U/R), DISCO customer IDs, K-Electric account numbers, and SNGPL
  and SSGC consumer numbers, in the formats the utilities' bill pages ask for.
  `disco` is `null` for DISCO bills, as no official source maps the digits to a
  company.
- `mapCourierStatus()` and `normalizeCityForCourier()` (`pakdatakit/courier`):
  one status vocabulary for courier statuses, mapping only publicly documented
  statuses (PostEx's API guide v4.1.9 and Leopards' "Returned to Shipper"; TCS,
  M&P, Trax and BlueEx publish none), and city short forms (`LHR`, `Khi`,
  `Pindi`, `Isb`, Lyallpur, Urdu names) mapped to the city list. No API clients
  and no tracking-number detection, as no courier documents its format. The
  status mapping is experimental: its values may change in a minor release
  as more couriers' lists are added (see CONTRIBUTING.md).
- `buildFbrInvoice()` and `validateFbrInvoice()` (`pakdatakit/fbr-invoice`):
  types for FBR's Digital Invoicing JSON, a builder that works out each line's
  sales tax, and an offline validator that reports FBR's error codes, following
  PRAL's "Technical Specification for DI API" v1.12. No HTTP client and no
  tokens.

### Changed

- Package metadata: the description, keywords and homepage now follow the same
  style in every registry, and CI checks that the version, repository URL,
  licence and author agree across ports (`npm run check:metadata`).
- `bin` and `repository.url` in `package.json` are written in the form npm
  publishes, so `npm publish` no longer warns that it corrected them.
- New `NOTICE` file (included in the npm package) and an "Origin and
  attribution" section in the README.
- `test-vectors/README.md` documents the shared test vectors;
  `npm run test:ports` regenerates them and runs every port against them.
- `dataVersion` is now `2026-11-18` (new dataset: sales tax rates).

## Python (PyPI)

[pakdatakit 2.5.0](https://pypi.org/project/pakdatakit/2.5.0/)

Includes everything prepared for 2.4.0, which was never published on its own: the 2.4.0 changes are listed here with the 2.5.0 ones.

### Added

- Urdu text helpers in `pakdatakit.text`: `slugify` (URL slugs that keep Urdu letters, with `script="any" | "latin" | "urdu"`), `compare_urdu` (Urdu alphabetical order from CLDR 49, for `functools.cmp_to_key`), `is_rtl` and `wrap_bidi` (Unicode directional isolates), with the `SlugScript` and `BidiDirection` types.
- Income tax on salary (`pakdatakit.incometax`): `calculate_salary_tax`, `calculate_monthly_salary_tax`, `get_salary_tax_slabs`, `get_salary_tax_years` and `get_tax_year`, with the `SalaryTax`, `SalaryTaxSlab` and `SalaryTaxYear` dataclasses, from the salaried rate table of the Income Tax Ordinance 2001 for tax years 2020 to 2027 (new dataset `income-tax-slabs.json`).
- `score_address()`: scores how complete a delivery address is (0 to 100),
  returning `AddressScore(score, missing, parsed)` with the parts not found,
  weighted by `ADDRESS_WEIGHTS`. `phone_risk_signals()`: flags a delivery
  phone number that is invalid, a landline or service number, or looks made
  up (repeated, sequential or placeholder digits).
- `get_sales_tax_rate()`: standard sales tax rate, with its law and source,
  for goods (FBR) or for services in a province or Islamabad Capital
  Territory on a date, from 1 July 2019. `calculate_sales_tax()` adds the tax
  to an amount (or splits it out with `inclusive=True`) and
  `split_inclusive()` splits a tax-inclusive amount, rounding half up to the
  paisa exactly, as `SalesTaxAmounts(net, tax, gross, rate)`.
- `parse_electricity_ref()` / `validate_electricity_ref()`: reads an
  electricity bill identifier, a DISCO 14-digit reference number (with an
  optional `U`/`R`), a DISCO customer ID (10 digits, 11 for LESCO) or a
  K-Electric 13-digit account number, as `ElectricityRef(type, digits,
formatted, urban_rural, disco)`. `validate_gas_consumer_number()` checks an
  SNGPL (11 digits) or SSGC (10 digits) consumer number. Formats only; no
  check digit is published.
- `map_courier_status()`: maps a courier's own status name, code or numeric
  ID to one `CourierStatus` vocabulary (`pending` ... `cancelled`), for the
  statuses couriers document publicly (PostEx's merchant API guide and
  Leopards' "Returned to Shipper"). `normalize_city_for_courier()`: maps short
  forms (`LHR`, `Khi`, `Pindi`), the old name Lyallpur, a trailing "city" and
  Urdu-script names to the city list. The status mapping is experimental and
  may change in a minor release as more couriers' lists are added.
- `build_fbr_invoice()` / `validate_fbr_invoice()` / `expected_sales_tax()`:
  FBR Digital Invoicing, following PRAL's DI API specification v1.12
  (`FBR_DI_SPEC_VERSION`). The builder works out each line's sales tax
  (`N%` and `Rs.N` rates), fills FBR's defaults and adds up the columns, as
  `FbrInvoiceBuild(invoice, totals)`; the validator returns every problem it
  can find offline with FBR's error code, as `FbrInvoiceValidation(valid,
errors)`. The invoice is a plain `dict` with FBR's camelCase keys
  (`FbrInvoice` / `FbrInvoiceItem` `TypedDict`s). No HTTP client, no tokens.

### Changed

- Package metadata: the description, keywords and homepage now follow the same
  style in every registry, and CI checks that the version, repository URL,
  licence and author agree across ports (`npm run check:metadata`).
- `DATA_VERSION` is now `2026-11-18` (new dataset: sales tax rates).

## Dart (pub.dev)

[pakdatakit 2.5.0](https://pub.dev/packages/pakdatakit/versions/2.5.0)

Includes everything prepared for 2.4.0, which was never published on its own: the 2.4.0 changes are listed here with the 2.5.0 ones.

### Added

- `calculateSalaryTax()` and `calculateMonthlySalaryTax()`: income tax on a
  salaried individual's taxable income from the salaried rate table of the
  Income Tax Ordinance 2001 for tax years 2020 to 2027, as a `SalaryTax`
  (`tax`, `monthly`, `effectiveRate`, `slab`, `taxYear`), rounded half up to
  the paisa, exactly on every platform. `getSalaryTaxSlabs()` returns a
  year's table (`SalaryTaxYear`, `SalaryTaxSlab`) with its law and FBR
  source, `getSalaryTaxYears()` the years covered and `getTaxYear()` the tax
  year of a date. Also as `package:pakdatakit/incometax.dart`.
- `slugify()`: URL slugs that keep Urdu letters (`SlugScript` limits the
  script); `compareUrdu()`: Urdu alphabetical order from the CLDR collation,
  for `List.sort`, without ICU; `isRTL()` and `wrapBidi()` (`BidiDirection`):
  right-to-left detection and Unicode directional isolates.
- `scoreAddress()`: scores how complete a delivery address is (0-100), with
  the `missing` `AddressPart`s and the `parseAddress` result, and warns when
  a known post office code is in a different province from the city.
  `phoneRiskSignals()`: `PhoneRiskFlag`s for a phone number a courier cannot
  reach or that looks made up (landline, service number, repeated or
  sequential digits, placeholder numbers). Also `addressWeights`, and as
  `package:pakdatakit/quality.dart`.
- `getSalesTaxRate()`: the standard sales tax rate on goods (FBR) or on
  services in a province or Islamabad Capital Territory on a date, from 1 July
  2019, with the authority, law and source (`SalesTaxRate`, `SalesTaxKind`).
  `calculateSalesTax()` adds tax at a rate or a looked-up rate, or splits it
  out with `inclusive: true`; `splitInclusive()` splits a tax-inclusive amount.
  Both return `SalesTaxAmounts`, rounded half up to the paisa, exactly on
  every platform. Also as `package:pakdatakit/salestax.dart`.
- `parseElectricityRef()` and `validateElectricityRef()`: a DISCO (WAPDA)
  14-digit reference number with optional U/R, a DISCO customer ID (10 or 11
  digits) or a 13-digit K-Electric account number, as an `ElectricityRef`
  (`type` as an `ElectricityRefType`, `digits`, `formatted`, `urbanRural`,
  `disco`). `validateGasConsumerNumber()` checks an SNGPL (11-digit) or SSGC
  (10-digit) consumer number (`GasCompany`). Format checks only; no utility
  publishes a check digit. Also as `package:pakdatakit/bills.dart`.
- `mapCourierStatus()`: maps a courier's own status (name, numeric ID or
  code) to one vocabulary, `CourierStatus`, from PostEx's merchant API guide
  and Leopards' "Returned to Shipper" (`Courier` names the couriers).
  `normalizeCityForCourier()` maps short forms (`LHR`, `Khi`, `Pindi`), the
  old name Lyallpur, a trailing "city" and Urdu script to the city list. No
  API is called. Also as `package:pakdatakit/courier.dart`.
- `buildFbrInvoice()` and `validateFbrInvoice()`: FBR Digital Invoicing, for
  the invoice JSON (`Map<String, Object?>`, typedef `FbrInvoice`) posted to
  PRAL's DI API (specification 1.12, `fbrDiSpecVersion`). The builder works
  out each line's sales tax (`expectedSalesTax()`: `N%` or `Rs.N` per unit,
  with `calculateSalesTax`), fills FBR's defaults and adds up the columns
  (`FbrInvoiceBuild`, `FbrInvoiceTotals`); the validator returns every
  problem it can find offline with FBR's error code (`FbrInvoiceValidation`,
  `FbrInvoiceError`), optionally rejecting future dates with `today:`. Also
  `FbrInvoiceType` and `FbrRegistrationType`. No HTTP client and no token
  handling. Also as `package:pakdatakit/fbr_invoice.dart`.

### Changed

- Package metadata: the description, keywords and homepage now follow the same
  style in every registry, and CI checks that the version, repository URL,
  licence and author agree across ports (`npm run check:metadata`).
- `dataVersion` is now `2026-11-18` (new dataset: sales tax rates).

## .NET (NuGet)

[PakDataKit 2.5.0](https://www.nuget.org/packages/PakDataKit/2.5.0)

Includes everything prepared for 2.4.0, which was never published on its own: the 2.4.0 changes are listed here with the 2.5.0 ones.

### Added

- `Text.Slugify(input, options)`: a URL slug that keeps Urdu letters as they
  are, folds accented Latin-1 letters and converts Urdu digits
  (`SlugifyOptions.Script`: `SlugScript.Any`, `Latin` or `Urdu`).
  `Text.CompareUrdu(a, b)`: Urdu alphabetical order (CLDR `ur`, with the ھ
  digraphs as letters of their own), for `List.Sort`, built in so it does not
  depend on the culture or ICU. `Text.IsRtl(text)`: whether the first letter
  is right to left. `Text.WrapBidi(text, direction)`: wraps text in a Unicode
  directional isolate (`BidiDirection.Auto`, `Rtl` or `Ltr`).
- `IncomeTax.CalculateSalaryTax(annualIncome, options)` and
  `IncomeTax.CalculateMonthlySalaryTax(monthlySalary, options)`: income tax on
  salary from the salaried rate table for tax years 2020 to 2027, as a
  `SalaryTax` (`Tax`, `Monthly`, `EffectiveRate`, `Slab`, `TaxYear`) rounded
  half up to the paisa in exact integer arithmetic (`SalaryTaxOptions` takes
  `TaxYear`, `Date` or `OnDate`). `IncomeTax.GetSalaryTaxSlabs(taxYear)`
  returns the table as a `SalaryTaxYear` with its `SalaryTaxSlab` bands, law
  and official source, `IncomeTax.GetSalaryTaxYears()` the years covered, and
  `IncomeTax.GetTaxYear(date)` the July-to-June tax year of a date. Invalid
  input returns `null`.
- `Quality.ScoreAddress(address)`: scores how complete a delivery address is
  (0 to 100) for cash on delivery, as an `AddressScore` (`Score`, the
  `Missing` `AddressPart` values and the `Parsed` address with extra
  warnings), using `Quality.AddressWeights`. `Quality.PhoneRiskSignals(phone)`
  returns `PhoneRiskFlag` values for a number a courier cannot reach or that
  looks made up (`Invalid`, `Landline`, `NotMobile`, `RepeatedDigits`,
  `SequentialDigits`, `TestNumber`). New `[CodPhone]` attribute in
  `PakDataKit.DataAnnotations` and `IsCodPhone()` rule in
  `PakDataKit.FluentValidation`: a mobile number with no risk flags.
- `SalesTax.GetRate(query)`: the standard sales tax rate on a date, from
  1 July 2019, for `SalesTaxKind.Goods` (federal, FBR) or
  `SalesTaxKind.Services` in a province or Islamabad Capital Territory, as a
  `SalesTaxRate` with its authority, law and official source
  (`SalesTaxRateQuery` takes `Kind`, `Province` and `Date` or `OnDate`).
  `SalesTax.Calculate(amount, options)` adds the tax for a `Rate` or a
  province's rate (`SalesTaxOptions`, `Inclusive` to split it out) and
  `SalesTax.SplitInclusive(gross, rate)` splits a tax-inclusive amount, both
  returning `SalesTaxAmounts` (`Net`, `Tax`, `Gross`, `Rate`) rounded half up
  to the paisa in exact integer arithmetic. Invalid input returns `null`.
- `Bills.ParseElectricityRef(input)`: reads a DISCO (WAPDA) reference number
  (14 digits, optional `U`/`R`), a DISCO customer ID (10 or 11 digits) or a
  K-Electric account number (13 digits starting `04000`), as an
  `ElectricityRef` (`Type` as `ElectricityRefType.Reference`, `CustomerId` or
  `KElectric`, `Digits`, `Formatted`, `UrbanRural`, `Disco`), or `null`.
  `Bills.ValidateElectricityRef(input)` checks the same formats, and
  `Bills.ValidateGasConsumerNumber(input, company)` checks an 11-digit
  `GasCompany.Sngpl` or 10-digit `GasCompany.Ssgc` consumer number. Format
  checks only; separators and Urdu digits are accepted.
- `Courier.MapStatus(courier, raw)`: maps a courier's own status text, or a
  numeric status ID through the `double` overload, to a `CourierStatus`
  (`Pending`, `Booked`, `PickedUp`, `InTransit`, `OutForDelivery`,
  `Attempted`, `UnderReview`, `Delivered`, `Returning`, `Returned`,
  `Cancelled`). Only publicly documented statuses are mapped (PostEx's
  merchant API guide and Leopards' "Returned to Shipper"); anything else
  returns `null`. The status mapping is experimental and may change in a
  minor release as more couriers' lists are added. `Courier.NormalizeCity(input)` maps short forms (`LHR`,
  `Khi`, `Pindi`), the old name Lyallpur, a trailing "city" and Urdu script to
  a city in the city list. Neither throws.
- `FbrInvoice.Build(input)`, `FbrInvoice.Validate(invoice, today)` and
  `FbrInvoice.ExpectedSalesTax(item)`: FBR Digital Invoicing (PRAL's DI API
  specification 1.12, `FbrInvoice.SpecVersion`) on the invoice JSON
  (`JsonNode`; `Validate` also takes a `JsonElement`). `Build` works out each
  line's `salesTaxApplicable` with `SalesTax.Calculate` (or quantity × `Rs.N`),
  fills FBR's defaults and returns an `FbrInvoiceBuild` (`Invoice` as a
  `JsonObject`, `Totals` as `FbrInvoiceTotals`), or `null`. `Validate` returns
  an `FbrInvoiceValidation` whose `Errors` are `FbrInvoiceError` records
  (`Code`, `Field`, `Message`) with FBR's error codes, checking everything
  that needs no call to FBR, including the sales tax to within one paisa.
  `FbrInvoiceType` and `FbrRegistrationType` hold the allowed strings. No
  HTTP client, no tokens.

### Changed

- Package metadata: the description, keywords and homepage now follow the same
  style in every registry, and CI checks that the version, repository URL,
  licence and author agree across ports (`npm run check:metadata`).
- `PackageProjectUrl` points to the .NET README and `Copyright` matches the
  licence file.
- `PakData.Version` is now `2026-11-18` (new dataset: sales tax rates).

## PHP (Packagist)

[chmuzamil/pakdatakit 2.5.0](https://packagist.org/packages/chmuzamil/pakdatakit#v2.5.0)

Includes everything prepared for 2.4.0, which was never published on its own: the 2.4.0 changes are listed here with the 2.5.0 ones.

### Added

- `Text::slugify()`, `Text::compareUrdu()`, `Text::isRtl()` and `Text::wrapBidi()`: URL slugs that keep Urdu letters (`script`: `Text::SCRIPT_ANY`, `SCRIPT_LATIN`, `SCRIPT_URDU`), Urdu alphabetical order for `usort()` from the CLDR `ur` collation (no intl or ICU needed), right-to-left detection, and Unicode directional isolates (`Text::BIDI_AUTO`, `BIDI_RTL`, `BIDI_LTR`). They accept any value and never throw.
- `IncomeTax::calculateSalary()`, `IncomeTax::calculateMonthlySalary()`, `IncomeTax::getSalarySlabs()`, `IncomeTax::getSalaryYears()` and `IncomeTax::getTaxYear()`: income tax on salary from the salaried rate table of the Income Tax Ordinance 2001 for tax years 2020 to 2027, computed exactly in whole paisa (`SalaryTax`, `SalaryTaxSlab`, `SalaryTaxYear`). They return `null` for any invalid input and never throw.
- `Quality::scoreAddress()`: scores how complete a delivery address is (0 to 100) for cash on delivery, with the `missing` parts (`city`, `houseNumber`,
  `street`, `area`, `postalCode`, `landmark`) and the parsed address as an
  `AddressScore`; `Quality::ADDRESS_WEIGHTS` holds the points per part.
  `Quality::phoneRiskSignals()` flags phone numbers a courier cannot use:
  invalid, landline and service numbers, and repeated, sequential and
  placeholder numbers. New Laravel rule `pk_cod_phone` (and `Rules\CodPhone`)
  passes only when there are no flags, with English and Urdu messages.
- `SalesTax::getRate()`, `SalesTax::calculate()` and `SalesTax::splitInclusive()`: standard sales tax rates for goods (FBR) and services (PRA, SRB, KPRA, BRA, ICT) from 1 July 2019, with the law and source of each, and exact sales tax amounts in whole paisa (`SalesTaxRate`, `SalesTaxAmounts`). They return `null` for any invalid input and never throw.
- `Bills::parseElectricityRef()`, `Bills::validateElectricityRef()` and `Bills::validateGasConsumerNumber()`: electricity bill identifiers (14-digit DISCO reference numbers with optional U/R, DISCO customer IDs and K-Electric account numbers) as an `ElectricityRef`, and SNGPL (11 digits) and SSGC (10 digits) gas consumer numbers. New Laravel rule `pk_electricity_ref` (and `Rules\ElectricityRef`), with English and Urdu messages.
- `Courier::mapStatus()` and `Courier::normalizeCity()`: maps a courier's own status (PostEx's documented order statuses and tracking codes, and Leopards' "Returned to Shipper") to one vocabulary (`Courier::PENDING` … `Courier::CANCELLED`), and maps short forms, old names and Urdu spellings of cities (`LHR`, `Pindi`, `Lyallpur`, `Karachi City`, `لاہور`) to the city list. No API is called; both return `null` for anything unknown and never throw. The status mapping is experimental and may change in a minor release as more couriers' lists are added.
- `FbrInvoice::build()`, `FbrInvoice::validate()` and `FbrInvoice::expectedSalesTax()`: FBR Digital Invoicing (PRAL's DI API specification v1.12, `FbrInvoice::SPEC_VERSION`). `build()` works out each line's sales tax (`N%` and `Rs.N` rates), fills FBR's defaults and adds up the columns; `validate()` checks an invoice (array or decoded JSON object) offline and returns every problem with FBR's error code as an `FbrInvoiceValidation` of `FbrInvoiceError`s. No HTTP client or tokens; they never throw.

### Changed

- `composer.json` now also requires `ext-ctype` and `ext-json` (with `ext-mbstring`), the extensions the code calls, so Composer refuses to install without them. Both are enabled in standard PHP builds.
- `PakData::version()` is now `2026-11-18` (new dataset: sales tax rates).
