gstin-utils 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ujjwal Pratap
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,340 @@
+# gstin-utils
+
+> A lightweight, zero-dependency utility package for Indian GSTIN validation, parsing, normalization, masking, and metadata extraction.
+
+[![npm version](https://img.shields.io/npm/v/gstin-utils.svg)](https://www.npmjs.com/package/gstin-utils)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+
+---
+
+## Why gstin-utils?
+
+Working with Indian GST (Goods and Services Tax) data is a common requirement in fintech, invoicing, ERP, e-commerce, and tax-compliance applications. GSTIN numbers have a strict 15-character format with embedded state codes, PAN, entity identifiers, and a checksum — yet most codebases validate them with ad-hoc regexes that miss important checks.
+
+**gstin-utils** gives you production-grade utilities to:
+
+- ✅ **Validate** GSTINs with full checksum verification (Luhn mod-36)
+- 🔍 **Parse** a GSTIN into state code, PAN, entity code, and more
+- 🏷️ **Extract** state names, PAN numbers, and metadata
+- 🔒 **Mask** GSTINs for safe display in logs or UI
+- 📐 **Normalize** raw user input (trim + uppercase)
+- 🗺️ **Map** all 37+ Indian state/UT codes to their names
+- 🛡️ **Zero dependencies** — lightweight and secure
+
+---
+
+## Installation
+
+```bash
+npm install gstin-utils
+```
+
+```bash
+yarn add gstin-utils
+```
+
+```bash
+pnpm add gstin-utils
+```
+
+---
+
+## Quick Start
+
+```ts
+import { isValidGSTIN, parseGSTIN, maskGSTIN } from 'gstin-utils';
+
+// Validate
+isValidGSTIN('27AAPFU0939F1ZV'); // true
+isValidGSTIN('INVALIDGSTIN123'); // false
+
+// Parse
+parseGSTIN('27AAPFU0939F1ZV');
+// {
+//   gstin: '27AAPFU0939F1ZV',
+//   stateCode: '27',
+//   stateName: 'Maharashtra',
+//   pan: 'AAPFU0939F',
+//   entityCode: '1',
+//   checksum: 'V',
+//   isValid: true,
+//   ...
+// }
+
+// Mask for display
+maskGSTIN('27AAPFU0939F1ZV'); // "27AAP****39F1ZV"
+```
+
+---
+
+## GSTIN Format Reference
+
+A GSTIN is a **15-character alphanumeric** string with the following structure:
+
+| Position | Characters | Meaning                              | Example |
+| -------- | ---------- | ------------------------------------ | ------- |
+| 1–2      | `27`       | State/UT code                        | `27`    |
+| 3–7      | `AAPFU`    | First 5 characters of PAN (letters)  | `AAPFU` |
+| 8–11     | `0939`     | Next 4 characters of PAN (digits)    | `0939`  |
+| 12       | `F`        | Last character of PAN (letter)       | `F`     |
+| 13       | `1`        | Entity code (1–9 or A–Z)            | `1`     |
+| 14       | `Z`        | Default/reserved character           | `Z`     |
+| 15       | `V`        | Checksum (computed via Luhn mod-36)  | `V`     |
+
+---
+
+## API Reference
+
+### `normalizeGSTIN(gstin: unknown): string`
+
+Trims whitespace and converts to uppercase.
+
+```ts
+normalizeGSTIN('  27aapfu0939f1zv  '); // "27AAPFU0939F1ZV"
+normalizeGSTIN(null);                   // ""
+```
+
+---
+
+### `isValidGSTIN(gstin: unknown): boolean`
+
+Quick boolean check — validates format, state code, and checksum.
+
+```ts
+isValidGSTIN('27AAPFU0939F1ZV'); // true
+isValidGSTIN('00AAPFU0939F1ZV'); // false (invalid state code)
+isValidGSTIN(undefined);          // false
+```
+
+---
+
+### `validateGSTIN(gstin: unknown): GSTINValidationResult`
+
+Returns a detailed validation object with individual check results and error messages.
+
+```ts
+validateGSTIN('27AAPFU0939F1ZV');
+// {
+//   isValid: true,
+//   formatValid: true,
+//   lengthValid: true,
+//   stateCodeValid: true,
+//   panSegmentValid: true,
+//   entityCodeValid: true,
+//   defaultZValid: true,
+//   checksumValid: true,
+//   errors: []
+// }
+
+validateGSTIN('00AAPFU0939F1ZV');
+// {
+//   isValid: false,
+//   stateCodeValid: false,
+//   errors: ['"00" is not a recognized GST state/UT code.', ...]
+// }
+```
+
+---
+
+### `parseGSTIN(gstin: unknown): GSTINParsedResult | null`
+
+Breaks down a GSTIN into its constituent parts. Returns `null` for unusable input.
+
+```ts
+parseGSTIN('27AAPFU0939F1ZV');
+// {
+//   gstin: '27AAPFU0939F1ZV',
+//   normalized: '27AAPFU0939F1ZV',
+//   stateCode: '27',
+//   stateName: 'Maharashtra',
+//   pan: 'AAPFU0939F',
+//   entityCode: '1',
+//   defaultChar: 'Z',
+//   checksum: 'V',
+//   isValid: true
+// }
+```
+
+---
+
+### `getStateCodeFromGSTIN(gstin: unknown): string | null`
+
+Extracts the 2-digit state code.
+
+```ts
+getStateCodeFromGSTIN('27AAPFU0939F1ZV'); // "27"
+getStateCodeFromGSTIN('');                 // null
+```
+
+---
+
+### `getStateNameFromGSTIN(gstin: unknown): string | null`
+
+Returns the human-readable state/UT name.
+
+```ts
+getStateNameFromGSTIN('27AAPFU0939F1ZV'); // "Maharashtra"
+getStateNameFromGSTIN('07AAPFU0939F1ZV'); // "Delhi"
+```
+
+---
+
+### `getPANFromGSTIN(gstin: unknown): string | null`
+
+Extracts the 10-character PAN segment.
+
+```ts
+getPANFromGSTIN('27AAPFU0939F1ZV'); // "AAPFU0939F"
+```
+
+---
+
+### `maskGSTIN(gstin: unknown): string | null`
+
+Masks the middle portion for safe display.
+
+```ts
+maskGSTIN('27AAPFU0939F1ZV'); // "27AAP****39F1ZV"
+```
+
+---
+
+### `isValidStateCode(code: unknown): boolean`
+
+Validates a 2-digit GST state/UT code against the known list.
+
+```ts
+isValidStateCode('27'); // true  (Maharashtra)
+isValidStateCode('00'); // false
+isValidStateCode('99'); // true  (Centre Jurisdiction)
+```
+
+---
+
+### `computeChecksum(gstin: string): string`
+
+Computes the expected checksum character using the Luhn mod-36 algorithm.
+
+```ts
+computeChecksum('27AAPFU0939F1ZV'); // "V"
+```
+
+---
+
+### `isChecksumValid(gstin: string): boolean`
+
+Checks if the 15th character matches the computed checksum.
+
+```ts
+isChecksumValid('27AAPFU0939F1ZV'); // true
+isChecksumValid('27AAPFU0939F1ZA'); // false
+```
+
+---
+
+### Data Exports
+
+```ts
+import { STATE_CODE_MAP, getAllStateCodes, getStateNameByCode } from 'gstin-utils';
+
+STATE_CODE_MAP['27'];       // "Maharashtra"
+getAllStateCodes();           // ['01', '02', '03', ...]
+getStateNameByCode('07');    // "Delhi"
+```
+
+---
+
+## Edge Case Handling
+
+All functions handle these edge cases gracefully:
+
+| Input              | Behavior                                        |
+| ------------------ | ----------------------------------------------- |
+| `null`             | Returns safe default (`""`, `false`, or `null`) |
+| `undefined`        | Returns safe default                            |
+| `""`               | Returns safe default                            |
+| `12345` (number)   | Returns safe default (non-string)               |
+| `"  27aapfu...  "` | Auto-trimmed and uppercased                     |
+| Short strings      | Returns `null` or validation failure            |
+| Long strings       | Returns validation failure                      |
+
+---
+
+## State/UT Codes Supported
+
+The package includes a complete mapping of **37+ GST state and UT codes**, including:
+
+- All 28 Indian states
+- All 8 Union Territories
+- Special codes: `96` (Foreign Country), `97` (Other Territory), `99` (Centre Jurisdiction)
+
+---
+
+## Project Structure
+
+```
+gstin-utils/
+├── src/
+│   ├── index.ts          # Barrel exports
+│   ├── validator.ts      # Core validation & utility functions
+│   ├── checksum.ts       # Luhn mod-36 checksum algorithm
+│   ├── state-codes.ts    # State/UT code mapping
+│   └── types.ts          # TypeScript interfaces
+├── tests/
+│   └── gstin-utils.test.ts
+├── examples/
+│   └── usage.ts
+├── package.json
+├── tsconfig.json
+├── jest.config.js
+├── LICENSE
+└── README.md
+```
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+```
+
+---
+
+## Use Cases
+
+- 🏦 **Fintech** — Validate merchant GSTINs during onboarding
+- 🧾 **Invoicing** — Parse and display GSTIN details on invoices
+- 📋 **ERP systems** — Normalize and store GSTINs consistently
+- 📝 **Form validation** — Client-side or server-side GSTIN validation
+- 📊 **Analytics** — Extract state-level data from GSTIN records
+- 🔒 **Logging** — Mask GSTINs in logs to protect PII
+
+---
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+1. Fork the repository
+2. Create your feature branch: `git checkout -b feature/my-feature`
+3. Commit your changes: `git commit -m 'Add my feature'`
+4. Push to the branch: `git push origin feature/my-feature`
+5. Open a pull request
+
+---
+
+## License
+
+[MIT](./LICENSE) © Ujjwal Pratap

package/dist/checksum.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @module gstin-utils/checksum
+ *
+ * Implements the GSTIN checksum verification algorithm.
+ *
+ * GSTIN uses a **modified Luhn mod-36** algorithm for its 15th (check) character.
+ * The algorithm maps each character of the first 14 characters to a numeric value,
+ * applies a weighted computation, and derives the expected check character.
+ *
+ * Character set (base-36):
+ *   0-9 → 0–9
+ *   A-Z → 10–35
+ *
+ * Algorithm steps:
+ *   1. For each of the first 14 characters, get its numeric value.
+ *   2. Compute: factor = value × (position is odd ? 1 : 2)
+ *   3. Split factor into: quotient = floor(factor / 36), remainder = factor % 36
+ *   4. Sum all (quotient + remainder) values.
+ *   5. Check character value = (36 - (sum % 36)) % 36
+ *   6. Map check character value back to the character set.
+ *
+ * Reference: Government of India GST Portal documentation.
+ */
+/**
+ * Computes the expected checksum character for a GSTIN.
+ *
+ * @param gstin - A 15-character GSTIN string (uppercase, no spaces)
+ * @returns The expected checksum character (the 15th character)
+ *
+ * @example
+ * ```ts
+ * computeChecksum('27AAPFU0939F1ZV'); // 'V'
+ * ```
+ */
+export declare function computeChecksum(gstin: string): string;
+/**
+ * Validates whether the 15th character of a GSTIN matches
+ * the computed checksum.
+ *
+ * @param gstin - A 15-character GSTIN string (uppercase, no spaces)
+ * @returns `true` if checksum is valid, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isChecksumValid('27AAPFU0939F1ZV'); // true
+ * isChecksumValid('27AAPFU0939F1ZA'); // false
+ * ```
+ */
+export declare function isChecksumValid(gstin: string): boolean;
+//# sourceMappingURL=checksum.d.ts.map

package/dist/checksum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.d.ts","sourceRoot":"","sources":["../src/checksum.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAkBrD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAItD"}

package/dist/checksum.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * @module gstin-utils/checksum
+ *
+ * Implements the GSTIN checksum verification algorithm.
+ *
+ * GSTIN uses a **modified Luhn mod-36** algorithm for its 15th (check) character.
+ * The algorithm maps each character of the first 14 characters to a numeric value,
+ * applies a weighted computation, and derives the expected check character.
+ *
+ * Character set (base-36):
+ *   0-9 → 0–9
+ *   A-Z → 10–35
+ *
+ * Algorithm steps:
+ *   1. For each of the first 14 characters, get its numeric value.
+ *   2. Compute: factor = value × (position is odd ? 1 : 2)
+ *   3. Split factor into: quotient = floor(factor / 36), remainder = factor % 36
+ *   4. Sum all (quotient + remainder) values.
+ *   5. Check character value = (36 - (sum % 36)) % 36
+ *   6. Map check character value back to the character set.
+ *
+ * Reference: Government of India GST Portal documentation.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeChecksum = computeChecksum;
+exports.isChecksumValid = isChecksumValid;
+/** The characters used for base-36 encoding */
+const CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+/**
+ * Computes the expected checksum character for a GSTIN.
+ *
+ * @param gstin - A 15-character GSTIN string (uppercase, no spaces)
+ * @returns The expected checksum character (the 15th character)
+ *
+ * @example
+ * ```ts
+ * computeChecksum('27AAPFU0939F1ZV'); // 'V'
+ * ```
+ */
+function computeChecksum(gstin) {
+    const input = gstin.substring(0, 14);
+    let sum = 0;
+    for (let i = 0; i < 14; i++) {
+        const char = input[i];
+        const value = CHARS.indexOf(char);
+        // Positions are 1-indexed: odd positions use factor 1, even use factor 2
+        const factor = value * (i % 2 === 0 ? 1 : 2);
+        const quotient = Math.floor(factor / 36);
+        const remainder = factor % 36;
+        sum += quotient + remainder;
+    }
+    const checkValue = (36 - (sum % 36)) % 36;
+    return CHARS[checkValue];
+}
+/**
+ * Validates whether the 15th character of a GSTIN matches
+ * the computed checksum.
+ *
+ * @param gstin - A 15-character GSTIN string (uppercase, no spaces)
+ * @returns `true` if checksum is valid, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isChecksumValid('27AAPFU0939F1ZV'); // true
+ * isChecksumValid('27AAPFU0939F1ZA'); // false
+ * ```
+ */
+function isChecksumValid(gstin) {
+    if (typeof gstin !== 'string' || gstin.length !== 15)
+        return false;
+    const expected = computeChecksum(gstin);
+    return gstin[14] === expected;
+}
+//# sourceMappingURL=checksum.js.map

package/dist/checksum.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checksum.js","sourceRoot":"","sources":["../src/checksum.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;AAgBH,0CAkBC;AAeD,0CAIC;AAnDD,+CAA+C;AAC/C,MAAM,KAAK,GAAG,sCAAsC,CAAC;AAErD;;;;;;;;;;GAUG;AACH,SAAgB,eAAe,CAAC,KAAa;IAC3C,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACrC,IAAI,GAAG,GAAG,CAAC,CAAC;IAEZ,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAElC,yEAAyE;QACzE,MAAM,MAAM,GAAG,KAAK,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,MAAM,GAAG,EAAE,CAAC;QAE9B,GAAG,IAAI,QAAQ,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED,MAAM,UAAU,GAAG,CAAC,EAAE,GAAG,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC;IAC1C,OAAO,KAAK,CAAC,UAAU,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,eAAe,CAAC,KAAa;IAC3C,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACnE,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACxC,OAAO,KAAK,CAAC,EAAE,CAAC,KAAK,QAAQ,CAAC;AAChC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @module gstin-utils
+ *
+ * A lightweight, zero-dependency utility package for Indian GSTIN
+ * validation, parsing, normalization, masking, and metadata extraction.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   isValidGSTIN,
+ *   parseGSTIN,
+ *   maskGSTIN,
+ * } from 'gstin-utils';
+ *
+ * isValidGSTIN('27AAPFU0939F1ZV'); // true
+ * parseGSTIN('27AAPFU0939F1ZV');   // { stateCode: '27', stateName: 'Maharashtra', ... }
+ * maskGSTIN('27AAPFU0939F1ZV');    // "27AAP****39F1ZV"
+ * ```
+ */
+export { normalizeGSTIN, isValidGSTIN, validateGSTIN, parseGSTIN, getStateCodeFromGSTIN, getStateNameFromGSTIN, getPANFromGSTIN, maskGSTIN, isValidStateCode, } from './validator';
+export { computeChecksum, isChecksumValid } from './checksum';
+export { STATE_CODE_MAP, getAllStateCodes, getStateNameByCode, } from './state-codes';
+export type { GSTINValidationResult, GSTINParsedResult } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EACL,cAAc,EACd,YAAY,EACZ,aAAa,EACb,UAAU,EACV,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,SAAS,EACT,gBAAgB,GACjB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG9D,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AAGvB,YAAY,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * @module gstin-utils
+ *
+ * A lightweight, zero-dependency utility package for Indian GSTIN
+ * validation, parsing, normalization, masking, and metadata extraction.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   isValidGSTIN,
+ *   parseGSTIN,
+ *   maskGSTIN,
+ * } from 'gstin-utils';
+ *
+ * isValidGSTIN('27AAPFU0939F1ZV'); // true
+ * parseGSTIN('27AAPFU0939F1ZV');   // { stateCode: '27', stateName: 'Maharashtra', ... }
+ * maskGSTIN('27AAPFU0939F1ZV');    // "27AAP****39F1ZV"
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getStateNameByCode = exports.getAllStateCodes = exports.STATE_CODE_MAP = exports.isChecksumValid = exports.computeChecksum = exports.isValidStateCode = exports.maskGSTIN = exports.getPANFromGSTIN = exports.getStateNameFromGSTIN = exports.getStateCodeFromGSTIN = exports.parseGSTIN = exports.validateGSTIN = exports.isValidGSTIN = exports.normalizeGSTIN = void 0;
+// --- Core functions --------------------------------------------------------
+var validator_1 = require("./validator");
+Object.defineProperty(exports, "normalizeGSTIN", { enumerable: true, get: function () { return validator_1.normalizeGSTIN; } });
+Object.defineProperty(exports, "isValidGSTIN", { enumerable: true, get: function () { return validator_1.isValidGSTIN; } });
+Object.defineProperty(exports, "validateGSTIN", { enumerable: true, get: function () { return validator_1.validateGSTIN; } });
+Object.defineProperty(exports, "parseGSTIN", { enumerable: true, get: function () { return validator_1.parseGSTIN; } });
+Object.defineProperty(exports, "getStateCodeFromGSTIN", { enumerable: true, get: function () { return validator_1.getStateCodeFromGSTIN; } });
+Object.defineProperty(exports, "getStateNameFromGSTIN", { enumerable: true, get: function () { return validator_1.getStateNameFromGSTIN; } });
+Object.defineProperty(exports, "getPANFromGSTIN", { enumerable: true, get: function () { return validator_1.getPANFromGSTIN; } });
+Object.defineProperty(exports, "maskGSTIN", { enumerable: true, get: function () { return validator_1.maskGSTIN; } });
+Object.defineProperty(exports, "isValidStateCode", { enumerable: true, get: function () { return validator_1.isValidStateCode; } });
+// --- Checksum utilities ----------------------------------------------------
+var checksum_1 = require("./checksum");
+Object.defineProperty(exports, "computeChecksum", { enumerable: true, get: function () { return checksum_1.computeChecksum; } });
+Object.defineProperty(exports, "isChecksumValid", { enumerable: true, get: function () { return checksum_1.isChecksumValid; } });
+// --- State code data & helpers ---------------------------------------------
+var state_codes_1 = require("./state-codes");
+Object.defineProperty(exports, "STATE_CODE_MAP", { enumerable: true, get: function () { return state_codes_1.STATE_CODE_MAP; } });
+Object.defineProperty(exports, "getAllStateCodes", { enumerable: true, get: function () { return state_codes_1.getAllStateCodes; } });
+Object.defineProperty(exports, "getStateNameByCode", { enumerable: true, get: function () { return state_codes_1.getStateNameByCode; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;GAkBG;;;AAEH,8EAA8E;AAC9E,yCAUqB;AATnB,2GAAA,cAAc,OAAA;AACd,yGAAA,YAAY,OAAA;AACZ,0GAAA,aAAa,OAAA;AACb,uGAAA,UAAU,OAAA;AACV,kHAAA,qBAAqB,OAAA;AACrB,kHAAA,qBAAqB,OAAA;AACrB,4GAAA,eAAe,OAAA;AACf,sGAAA,SAAS,OAAA;AACT,6GAAA,gBAAgB,OAAA;AAGlB,8EAA8E;AAC9E,uCAA8D;AAArD,2GAAA,eAAe,OAAA;AAAE,2GAAA,eAAe,OAAA;AAEzC,8EAA8E;AAC9E,6CAIuB;AAHrB,6GAAA,cAAc,OAAA;AACd,+GAAA,gBAAgB,OAAA;AAChB,iHAAA,kBAAkB,OAAA"}

package/dist/state-codes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module gstin-utils/state-codes
+ *
+ * Complete mapping of Indian GST state/UT codes to their names.
+ * This includes all 28 states, 8 union territories, and special codes
+ * used by the GST system.
+ *
+ * Reference: https://www.gst.gov.in
+ */
+export declare const STATE_CODE_MAP: Record<string, string>;
+/**
+ * Returns an array of all valid GST state codes.
+ */
+export declare function getAllStateCodes(): string[];
+/**
+ * Returns the full state/UT name for a given state code.
+ *
+ * @param code - Two-digit state code (e.g., "27")
+ * @returns The state/UT name, or `undefined` if the code is invalid
+ *
+ * @example
+ * ```ts
+ * getStateNameByCode('27'); // "Maharashtra"
+ * getStateNameByCode('99'); // "Centre Jurisdiction"
+ * getStateNameByCode('00'); // undefined
+ * ```
+ */
+export declare function getStateNameByCode(code: string): string | undefined;
+//# sourceMappingURL=state-codes.d.ts.map

package/dist/state-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-codes.d.ts","sourceRoot":"","sources":["../src/state-codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA2CjD,CAAC;AAEF;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAE3C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGnE"}

package/dist/state-codes.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * @module gstin-utils/state-codes
+ *
+ * Complete mapping of Indian GST state/UT codes to their names.
+ * This includes all 28 states, 8 union territories, and special codes
+ * used by the GST system.
+ *
+ * Reference: https://www.gst.gov.in
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STATE_CODE_MAP = void 0;
+exports.getAllStateCodes = getAllStateCodes;
+exports.getStateNameByCode = getStateNameByCode;
+exports.STATE_CODE_MAP = {
+    '01': 'Jammu & Kashmir',
+    '02': 'Himachal Pradesh',
+    '03': 'Punjab',
+    '04': 'Chandigarh',
+    '05': 'Uttarakhand',
+    '06': 'Haryana',
+    '07': 'Delhi',
+    '08': 'Rajasthan',
+    '09': 'Uttar Pradesh',
+    '10': 'Bihar',
+    '11': 'Sikkim',
+    '12': 'Arunachal Pradesh',
+    '13': 'Nagaland',
+    '14': 'Manipur',
+    '15': 'Mizoram',
+    '16': 'Tripura',
+    '17': 'Meghalaya',
+    '18': 'Assam',
+    '19': 'West Bengal',
+    '20': 'Jharkhand',
+    '21': 'Odisha',
+    '22': 'Chhattisgarh',
+    '23': 'Madhya Pradesh',
+    '24': 'Gujarat',
+    '25': 'Daman & Diu',
+    '26': 'Dadra & Nagar Haveli and Daman & Diu',
+    '27': 'Maharashtra',
+    '28': 'Andhra Pradesh (Old)',
+    '29': 'Karnataka',
+    '30': 'Goa',
+    '31': 'Lakshadweep',
+    '32': 'Kerala',
+    '33': 'Tamil Nadu',
+    '34': 'Puducherry',
+    '35': 'Andaman & Nicobar Islands',
+    '36': 'Telangana',
+    '37': 'Andhra Pradesh',
+    '38': 'Ladakh',
+    // Special codes used by GST
+    '96': 'Foreign Country',
+    '97': 'Other Territory',
+    '99': 'Centre Jurisdiction',
+};
+/**
+ * Returns an array of all valid GST state codes.
+ */
+function getAllStateCodes() {
+    return Object.keys(exports.STATE_CODE_MAP);
+}
+/**
+ * Returns the full state/UT name for a given state code.
+ *
+ * @param code - Two-digit state code (e.g., "27")
+ * @returns The state/UT name, or `undefined` if the code is invalid
+ *
+ * @example
+ * ```ts
+ * getStateNameByCode('27'); // "Maharashtra"
+ * getStateNameByCode('99'); // "Centre Jurisdiction"
+ * getStateNameByCode('00'); // undefined
+ * ```
+ */
+function getStateNameByCode(code) {
+    if (typeof code !== 'string')
+        return undefined;
+    return exports.STATE_CODE_MAP[code.trim()];
+}
+//# sourceMappingURL=state-codes.js.map

package/dist/state-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-codes.js","sourceRoot":"","sources":["../src/state-codes.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAkDH,4CAEC;AAeD,gDAGC;AApEY,QAAA,cAAc,GAA2B;IACpD,IAAI,EAAE,iBAAiB;IACvB,IAAI,EAAE,kBAAkB;IACxB,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,aAAa;IACnB,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,OAAO;IACb,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,eAAe;IACrB,IAAI,EAAE,OAAO;IACb,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,mBAAmB;IACzB,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,OAAO;IACb,IAAI,EAAE,aAAa;IACnB,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,cAAc;IACpB,IAAI,EAAE,gBAAgB;IACtB,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,aAAa;IACnB,IAAI,EAAE,sCAAsC;IAC5C,IAAI,EAAE,aAAa;IACnB,IAAI,EAAE,sBAAsB;IAC5B,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,KAAK;IACX,IAAI,EAAE,aAAa;IACnB,IAAI,EAAE,QAAQ;IACd,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,YAAY;IAClB,IAAI,EAAE,2BAA2B;IACjC,IAAI,EAAE,WAAW;IACjB,IAAI,EAAE,gBAAgB;IACtB,IAAI,EAAE,QAAQ;IACd,4BAA4B;IAC5B,IAAI,EAAE,iBAAiB;IACvB,IAAI,EAAE,iBAAiB;IACvB,IAAI,EAAE,qBAAqB;CAC5B,CAAC;AAEF;;GAEG;AACH,SAAgB,gBAAgB;IAC9B,OAAO,MAAM,CAAC,IAAI,CAAC,sBAAc,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,SAAgB,kBAAkB,CAAC,IAAY;IAC7C,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAC/C,OAAO,sBAAc,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;AACrC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @module gstin-utils/types
+ *
+ * Type definitions for the gstin-utils package.
+ * All return types for validation, parsing, and utility functions.
+ */
+/**
+ * Detailed validation result returned by `validateGSTIN()`.
+ * Each field represents one aspect of GSTIN validity.
+ */
+export interface GSTINValidationResult {
+    /** Whether the GSTIN passes all validation checks */
+    isValid: boolean;
+    /** Whether the GSTIN matches the expected regex format */
+    formatValid: boolean;
+    /** Whether the GSTIN is exactly 15 characters */
+    lengthValid: boolean;
+    /** Whether the first two digits are a recognized GST state/UT code */
+    stateCodeValid: boolean;
+    /** Whether characters 3–12 form a valid PAN pattern */
+    panSegmentValid: boolean;
+    /** Whether the 13th character (entity code) is a valid alphanumeric digit */
+    entityCodeValid: boolean;
+    /** Whether the 14th character is 'Z' (default/reserved) */
+    defaultZValid: boolean;
+    /** Whether the 15th character (checksum) is valid per the Luhn-mod-36 algorithm */
+    checksumValid: boolean;
+    /** List of human-readable error messages for each failed check */
+    errors: string[];
+}
+/**
+ * Parsed GSTIN structure returned by `parseGSTIN()`.
+ * Breaks down a GSTIN into its constituent parts.
+ */
+export interface GSTINParsedResult {
+    /** The original GSTIN (as provided) */
+    gstin: string;
+    /** Normalized (trimmed + uppercased) GSTIN */
+    normalized: string;
+    /** First 2 digits — the GST state/UT code */
+    stateCode: string;
+    /** Human-readable state/UT name, or "Unknown" if code is not recognized */
+    stateName: string;
+    /** Characters 3–12 — the PAN of the entity */
+    pan: string;
+    /** 13th character — entity/registration number within the same PAN */
+    entityCode: string;
+    /** 14th character — reserved character (should be 'Z') */
+    defaultChar: string;
+    /** 15th character — checksum digit */
+    checksum: string;
+    /** Whether the GSTIN is valid (passes all checks) */
+    isValid: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,0DAA0D;IAC1D,WAAW,EAAE,OAAO,CAAC;IACrB,iDAAiD;IACjD,WAAW,EAAE,OAAO,CAAC;IACrB,sEAAsE;IACtE,cAAc,EAAE,OAAO,CAAC;IACxB,uDAAuD;IACvD,eAAe,EAAE,OAAO,CAAC;IACzB,6EAA6E;IAC7E,eAAe,EAAE,OAAO,CAAC;IACzB,2DAA2D;IAC3D,aAAa,EAAE,OAAO,CAAC;IACvB,mFAAmF;IACnF,aAAa,EAAE,OAAO,CAAC;IACvB,kEAAkE;IAClE,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;CAClB"}

package/dist/types.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * @module gstin-utils/types
+ *
+ * Type definitions for the gstin-utils package.
+ * All return types for validation, parsing, and utility functions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;GAKG"}

package/dist/validator.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @module gstin-utils/validator
+ *
+ * Core GSTIN validation and utility functions.
+ * All functions accept raw user input and handle edge cases gracefully.
+ */
+import { GSTINValidationResult, GSTINParsedResult } from './types';
+/**
+ * Normalizes a GSTIN string by trimming whitespace and converting
+ * to uppercase. Useful before storing or comparing GSTINs.
+ *
+ * @param gstin - Raw GSTIN input
+ * @returns Cleaned GSTIN string (trimmed + uppercased)
+ *
+ * @example
+ * ```ts
+ * normalizeGSTIN('  27aapfu0939f1zv  '); // "27AAPFU0939F1ZV"
+ * normalizeGSTIN(null);                   // ""
+ * ```
+ */
+export declare function normalizeGSTIN(gstin: unknown): string;
+/**
+ * Quick boolean check: is the given GSTIN structurally valid?
+ *
+ * This checks length, format regex, state code validity, and checksum.
+ * For detailed diagnostics, use `validateGSTIN()` instead.
+ *
+ * @param gstin - Raw GSTIN input
+ * @returns `true` if valid, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isValidGSTIN('27AAPFU0939F1ZV'); // true
+ * isValidGSTIN('INVALIDGSTIN');     // false
+ * isValidGSTIN(undefined);          // false
+ * ```
+ */
+export declare function isValidGSTIN(gstin: unknown): boolean;
+/**
+ * Performs a detailed, multi-step validation of a GSTIN.
+ * Returns an object describing which checks passed and which failed,
+ * along with human-readable error messages.
+ *
+ * @param gstin - Raw GSTIN input
+ * @returns A `GSTINValidationResult` object
+ *
+ * @example
+ * ```ts
+ * const result = validateGSTIN('27AAPFU0939F1ZV');
+ * // {
+ * //   isValid: true,
+ * //   formatValid: true,
+ * //   lengthValid: true,
+ * //   stateCodeValid: true,
+ * //   panSegmentValid: true,
+ * //   entityCodeValid: true,
+ * //   defaultZValid: true,
+ * //   checksumValid: true,
+ * //   errors: []
+ * // }
+ * ```
+ */
+export declare function validateGSTIN(gstin: unknown): GSTINValidationResult;
+/**
+ * Parses a GSTIN into its constituent parts.
+ *
+ * Even if the GSTIN is invalid, this function will still attempt to extract
+ * whatever information it can (state code, PAN, etc.). The `isValid` field
+ * tells you whether the GSTIN passed all validation checks.
+ *
+ * @param gstin - Raw GSTIN input
+ * @returns A `GSTINParsedResult` object, or `null` if input is empty/unusable
+ *
+ * @example
+ * ```ts
+ * parseGSTIN('27AAPFU0939F1ZV');
+ * // {
+ * //   gstin: '27AAPFU0939F1ZV',
+ * //   normalized: '27AAPFU0939F1ZV',
+ * //   stateCode: '27',
+ * //   stateName: 'Maharashtra',
+ * //   pan: 'AAPFU0939F',
+ * //   entityCode: '1',
+ * //   defaultChar: 'Z',
+ * //   checksum: 'V',
+ * //   isValid: true
+ * // }
+ * ```
+ */
+export declare function parseGSTIN(gstin: unknown): GSTINParsedResult | null;
+/**
+ * Extracts the 2-digit state code from a GSTIN.
+ *
+ * @param gstin - Raw GSTIN input
+ * @returns The state code string, or `null` if input is too short
+ *
+ * @example
+ * ```ts
+ * getStateCodeFromGSTIN('27AAPFU0939F1ZV'); // "27"
+ * ```
+ */
+export declare function getStateCodeFromGSTIN(gstin: unknown): string | null;
+/**
+ * Extracts the state/UT name from a GSTIN.
+ *
+ * @param gstin - Raw GSTIN input
+ * @returns The state name, or `null` if the code is unrecognized or input is too short
+ *
+ * @example
+ * ```ts
+ * getStateNameFromGSTIN('27AAPFU0939F1ZV'); // "Maharashtra"
+ * getStateNameFromGSTIN('99XXXXX0000X1ZA'); // "Centre Jurisdiction"
+ * ```
+ */
+export declare function getStateNameFromGSTIN(gstin: unknown): string | null;
+/**
+ * Extracts the PAN (characters 3–12) from a GSTIN.
+ *
+ * @param gstin - Raw GSTIN input
+ * @returns The 10-character PAN string, or `null` if input is too short
+ *
+ * @example
+ * ```ts
+ * getPANFromGSTIN('27AAPFU0939F1ZV'); // "AAPFU0939F"
+ * ```
+ */
+export declare function getPANFromGSTIN(gstin: unknown): string | null;
+/**
+ * Masks the middle portion of a GSTIN for display or logging purposes.
+ * Replaces characters 6–9 (0-indexed: 5–8) with asterisks.
+ *
+ * Format: `XXAAP****39F1ZV`  (first 5 + **** + last 6)
+ *
+ * @param gstin - Raw GSTIN input
+ * @returns The masked GSTIN string, or `null` if input is too short
+ *
+ * @example
+ * ```ts
+ * maskGSTIN('27AAPFU0939F1ZV'); // "27AAP****39F1ZV"
+ * ```
+ */
+export declare function maskGSTIN(gstin: unknown): string | null;
+/**
+ * Checks whether a given 2-digit code is a valid GST state/UT code.
+ *
+ * @param code - A 2-digit state code string
+ * @returns `true` if the code is recognized, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isValidStateCode('27'); // true  (Maharashtra)
+ * isValidStateCode('00'); // false
+ * isValidStateCode('99'); // true  (Centre Jurisdiction)
+ * ```
+ */
+export declare function isValidStateCode(code: unknown): boolean;
+//# sourceMappingURL=validator.d.ts.map

package/dist/validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAoDnE;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAErD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CASpD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,qBAAqB,CAyFnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,GAAG,IAAI,CAyBnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAInE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAInE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAI7D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAOvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAIvD"}

package/dist/validator.js

@@ -0,0 +1,345 @@
+"use strict";
+/**
+ * @module gstin-utils/validator
+ *
+ * Core GSTIN validation and utility functions.
+ * All functions accept raw user input and handle edge cases gracefully.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeGSTIN = normalizeGSTIN;
+exports.isValidGSTIN = isValidGSTIN;
+exports.validateGSTIN = validateGSTIN;
+exports.parseGSTIN = parseGSTIN;
+exports.getStateCodeFromGSTIN = getStateCodeFromGSTIN;
+exports.getStateNameFromGSTIN = getStateNameFromGSTIN;
+exports.getPANFromGSTIN = getPANFromGSTIN;
+exports.maskGSTIN = maskGSTIN;
+exports.isValidStateCode = isValidStateCode;
+const state_codes_1 = require("./state-codes");
+const checksum_1 = require("./checksum");
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/**
+ * Regex pattern for a structurally valid GSTIN.
+ *
+ * Breakdown:
+ *   ^                  — start of string
+ *   [0-9]{2}           — 2-digit state code
+ *   [A-Z]{5}           — 5 letters of PAN (first 5 chars: entity type + name)
+ *   [0-9]{4}           — 4 digits of PAN
+ *   [A-Z]              — 1 letter of PAN (check letter)
+ *   [1-9A-Z]           — entity code (1–9 or A–Z, never 0)
+ *   Z                  — default reserved character
+ *   [0-9A-Z]           — checksum character
+ *   $                  — end of string
+ */
+const GSTIN_REGEX = /^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][1-9A-Z]Z[0-9A-Z]$/;
+/**
+ * Regex pattern for a valid PAN segment (characters 3–12 of GSTIN).
+ *
+ * PAN format: AAAAA9999A
+ *   5 uppercase letters + 4 digits + 1 uppercase letter
+ */
+const PAN_REGEX = /^[A-Z]{5}[0-9]{4}[A-Z]$/;
+// ---------------------------------------------------------------------------
+// Helpers (internal)
+// ---------------------------------------------------------------------------
+/**
+ * Safely coerces input to a trimmed, uppercased string.
+ * Returns an empty string for null, undefined, or non-string values.
+ *
+ * @internal
+ */
+function sanitize(input) {
+    if (input === null || input === undefined)
+        return '';
+    if (typeof input !== 'string')
+        return '';
+    return input.trim().toUpperCase();
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Normalizes a GSTIN string by trimming whitespace and converting
+ * to uppercase. Useful before storing or comparing GSTINs.
+ *
+ * @param gstin - Raw GSTIN input
+ * @returns Cleaned GSTIN string (trimmed + uppercased)
+ *
+ * @example
+ * ```ts
+ * normalizeGSTIN('  27aapfu0939f1zv  '); // "27AAPFU0939F1ZV"
+ * normalizeGSTIN(null);                   // ""
+ * ```
+ */
+function normalizeGSTIN(gstin) {
+    return sanitize(gstin);
+}
+/**
+ * Quick boolean check: is the given GSTIN structurally valid?
+ *
+ * This checks length, format regex, state code validity, and checksum.
+ * For detailed diagnostics, use `validateGSTIN()` instead.
+ *
+ * @param gstin - Raw GSTIN input
+ * @returns `true` if valid, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isValidGSTIN('27AAPFU0939F1ZV'); // true
+ * isValidGSTIN('INVALIDGSTIN');     // false
+ * isValidGSTIN(undefined);          // false
+ * ```
+ */
+function isValidGSTIN(gstin) {
+    const normalized = sanitize(gstin);
+    if (normalized.length !== 15)
+        return false;
+    if (!GSTIN_REGEX.test(normalized))
+        return false;
+    const stateCode = normalized.substring(0, 2);
+    if (!(stateCode in state_codes_1.STATE_CODE_MAP))
+        return false;
+    return (0, checksum_1.isChecksumValid)(normalized);
+}
+/**
+ * Performs a detailed, multi-step validation of a GSTIN.
+ * Returns an object describing which checks passed and which failed,
+ * along with human-readable error messages.
+ *
+ * @param gstin - Raw GSTIN input
+ * @returns A `GSTINValidationResult` object
+ *
+ * @example
+ * ```ts
+ * const result = validateGSTIN('27AAPFU0939F1ZV');
+ * // {
+ * //   isValid: true,
+ * //   formatValid: true,
+ * //   lengthValid: true,
+ * //   stateCodeValid: true,
+ * //   panSegmentValid: true,
+ * //   entityCodeValid: true,
+ * //   defaultZValid: true,
+ * //   checksumValid: true,
+ * //   errors: []
+ * // }
+ * ```
+ */
+function validateGSTIN(gstin) {
+    const normalized = sanitize(gstin);
+    const errors = [];
+    // 1. Length check
+    const lengthValid = normalized.length === 15;
+    if (!lengthValid) {
+        errors.push(`GSTIN must be exactly 15 characters, received ${normalized.length}.`);
+    }
+    // 2. Overall format check
+    const formatValid = GSTIN_REGEX.test(normalized);
+    if (!formatValid && lengthValid) {
+        errors.push('GSTIN does not match the expected format.');
+    }
+    // For the remaining checks we need at least 15 characters
+    let stateCodeValid = false;
+    let panSegmentValid = false;
+    let entityCodeValid = false;
+    let defaultZValid = false;
+    let checksumValid = false;
+    if (lengthValid) {
+        // 3. State code check
+        const stateCode = normalized.substring(0, 2);
+        stateCodeValid = stateCode in state_codes_1.STATE_CODE_MAP;
+        if (!stateCodeValid) {
+            errors.push(`"${stateCode}" is not a recognized GST state/UT code.`);
+        }
+        // 4. PAN segment check (characters 3–12, i.e. index 2–11)
+        const panSegment = normalized.substring(2, 12);
+        panSegmentValid = PAN_REGEX.test(panSegment);
+        if (!panSegmentValid) {
+            errors.push(`PAN segment "${panSegment}" does not match the expected PAN format (AAAAA9999A).`);
+        }
+        // 5. Entity code check (13th character, index 12)
+        const entityCode = normalized[12];
+        entityCodeValid = /^[1-9A-Z]$/.test(entityCode);
+        if (!entityCodeValid) {
+            errors.push(`Entity code "${entityCode}" is invalid. Must be 1–9 or A–Z.`);
+        }
+        // 6. Default 'Z' check (14th character, index 13)
+        defaultZValid = normalized[13] === 'Z';
+        if (!defaultZValid) {
+            errors.push(`14th character must be "Z" (reserved), found "${normalized[13]}".`);
+        }
+        // 7. Checksum check (15th character, index 14)
+        checksumValid = (0, checksum_1.isChecksumValid)(normalized);
+        if (!checksumValid) {
+            const expected = (0, checksum_1.computeChecksum)(normalized);
+            errors.push(`Checksum character "${normalized[14]}" is invalid. Expected "${expected}".`);
+        }
+    }
+    const isValid = lengthValid &&
+        formatValid &&
+        stateCodeValid &&
+        panSegmentValid &&
+        entityCodeValid &&
+        defaultZValid &&
+        checksumValid;
+    return {
+        isValid,
+        formatValid,
+        lengthValid,
+        stateCodeValid,
+        panSegmentValid,
+        entityCodeValid,
+        defaultZValid,
+        checksumValid,
+        errors,
+    };
+}
+/**
+ * Parses a GSTIN into its constituent parts.
+ *
+ * Even if the GSTIN is invalid, this function will still attempt to extract
+ * whatever information it can (state code, PAN, etc.). The `isValid` field
+ * tells you whether the GSTIN passed all validation checks.
+ *
+ * @param gstin - Raw GSTIN input
+ * @returns A `GSTINParsedResult` object, or `null` if input is empty/unusable
+ *
+ * @example
+ * ```ts
+ * parseGSTIN('27AAPFU0939F1ZV');
+ * // {
+ * //   gstin: '27AAPFU0939F1ZV',
+ * //   normalized: '27AAPFU0939F1ZV',
+ * //   stateCode: '27',
+ * //   stateName: 'Maharashtra',
+ * //   pan: 'AAPFU0939F',
+ * //   entityCode: '1',
+ * //   defaultChar: 'Z',
+ * //   checksum: 'V',
+ * //   isValid: true
+ * // }
+ * ```
+ */
+function parseGSTIN(gstin) {
+    var _a;
+    const raw = typeof gstin === 'string' ? gstin : '';
+    const normalized = sanitize(gstin);
+    if (normalized.length < 15)
+        return null;
+    const stateCode = normalized.substring(0, 2);
+    const stateName = (_a = (0, state_codes_1.getStateNameByCode)(stateCode)) !== null && _a !== void 0 ? _a : 'Unknown';
+    const pan = normalized.substring(2, 12);
+    const entityCode = normalized[12];
+    const defaultChar = normalized[13];
+    const checksum = normalized[14];
+    const valid = isValidGSTIN(normalized);
+    return {
+        gstin: raw.trim(),
+        normalized,
+        stateCode,
+        stateName,
+        pan,
+        entityCode,
+        defaultChar,
+        checksum,
+        isValid: valid,
+    };
+}
+/**
+ * Extracts the 2-digit state code from a GSTIN.
+ *
+ * @param gstin - Raw GSTIN input
+ * @returns The state code string, or `null` if input is too short
+ *
+ * @example
+ * ```ts
+ * getStateCodeFromGSTIN('27AAPFU0939F1ZV'); // "27"
+ * ```
+ */
+function getStateCodeFromGSTIN(gstin) {
+    const normalized = sanitize(gstin);
+    if (normalized.length < 2)
+        return null;
+    return normalized.substring(0, 2);
+}
+/**
+ * Extracts the state/UT name from a GSTIN.
+ *
+ * @param gstin - Raw GSTIN input
+ * @returns The state name, or `null` if the code is unrecognized or input is too short
+ *
+ * @example
+ * ```ts
+ * getStateNameFromGSTIN('27AAPFU0939F1ZV'); // "Maharashtra"
+ * getStateNameFromGSTIN('99XXXXX0000X1ZA'); // "Centre Jurisdiction"
+ * ```
+ */
+function getStateNameFromGSTIN(gstin) {
+    var _a;
+    const code = getStateCodeFromGSTIN(gstin);
+    if (!code)
+        return null;
+    return (_a = (0, state_codes_1.getStateNameByCode)(code)) !== null && _a !== void 0 ? _a : null;
+}
+/**
+ * Extracts the PAN (characters 3–12) from a GSTIN.
+ *
+ * @param gstin - Raw GSTIN input
+ * @returns The 10-character PAN string, or `null` if input is too short
+ *
+ * @example
+ * ```ts
+ * getPANFromGSTIN('27AAPFU0939F1ZV'); // "AAPFU0939F"
+ * ```
+ */
+function getPANFromGSTIN(gstin) {
+    const normalized = sanitize(gstin);
+    if (normalized.length < 12)
+        return null;
+    return normalized.substring(2, 12);
+}
+/**
+ * Masks the middle portion of a GSTIN for display or logging purposes.
+ * Replaces characters 6–9 (0-indexed: 5–8) with asterisks.
+ *
+ * Format: `XXAAP****39F1ZV`  (first 5 + **** + last 6)
+ *
+ * @param gstin - Raw GSTIN input
+ * @returns The masked GSTIN string, or `null` if input is too short
+ *
+ * @example
+ * ```ts
+ * maskGSTIN('27AAPFU0939F1ZV'); // "27AAP****39F1ZV"
+ * ```
+ */
+function maskGSTIN(gstin) {
+    const normalized = sanitize(gstin);
+    if (normalized.length < 15)
+        return null;
+    const prefix = normalized.substring(0, 5); // "27AAP"
+    const suffix = normalized.substring(9, 15); // "39F1ZV"
+    return `${prefix}****${suffix}`;
+}
+/**
+ * Checks whether a given 2-digit code is a valid GST state/UT code.
+ *
+ * @param code - A 2-digit state code string
+ * @returns `true` if the code is recognized, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isValidStateCode('27'); // true  (Maharashtra)
+ * isValidStateCode('00'); // false
+ * isValidStateCode('99'); // true  (Centre Jurisdiction)
+ * ```
+ */
+function isValidStateCode(code) {
+    if (typeof code !== 'string')
+        return false;
+    const trimmed = code.trim();
+    return trimmed in state_codes_1.STATE_CODE_MAP;
+}
+//# sourceMappingURL=validator.js.map

package/dist/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "gstin-utils",
+  "version": "1.0.0",
+  "description": "A lightweight, zero-dependency utility package for Indian GSTIN validation, parsing, normalization, masking, and metadata extraction.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "prepublishOnly": "npm run build && npm test",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "gstin",
+    "gst",
+    "india",
+    "tax",
+    "validation",
+    "parser",
+    "fintech",
+    "invoice",
+    "erp",
+    "pan",
+    "state-code",
+    "checksum",
+    "masking",
+    "utility"
+  ],
+  "author": "Dheeraj Singh",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dheeraj0808/gstin-validator"
+  },
+  "bugs": {
+    "url": "https://github.com/dheeraj0808/gstin-validator/issues"
+  },
+  "homepage": "https://github.com/ujjwalpratap/gstin-utils#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.4.5"
+  }
+}