indian-gst-validator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ayush Kumar
+
+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,135 @@
+
+# 🇮🇳 Indian GST Validator
+
+A lightweight JavaScript library to validate Indian GSTIN (Goods and Services Tax Identification Number) and extract useful information from it.
+
+`indian-gst-validator` helps developers validate GSTIN format, verify checksum, extract PAN, and identify the state and GST holder type — all without making an API call.
+
+## Features
+
+- Validate GSTIN format
+- Verify GSTIN checksum
+- Extract PAN from GSTIN
+- Get state name from GST state code
+- Identify GST holder type
+- Validate PAN format
+- Lightweight and easy to use
+- No external API or dependencies required
+
+## Installation
+
+Install the package using npm:
+
+```bash
+npm install indian-gst-validator
+```
+
+## Usage
+
+```js
+const {
+  isValidGST,
+  getStateFromGST,
+  extractPAN,
+  getGSTHolderType
+} = require("indian-gst-validator");
+
+const gstin = "27AAPFU0939F1ZV";
+
+// Validate GSTIN
+console.log(isValidGST(gstin));
+
+// Get state name
+console.log(getStateFromGST(gstin));
+
+// Extract PAN
+console.log(extractPAN(gstin));
+
+// Get GST holder type
+console.log(getGSTHolderType(gstin));
+```
+
+## API Reference
+
+### `isValidGST(gstin)`
+
+Checks whether the provided GSTIN has a valid format and checksum.
+
+```js
+isValidGST("27AAPFU0939F1ZV");
+// true or false
+```
+
+### `getStateFromGST(gstin)`
+
+Returns the state or UT name associated with the GSTIN state code.
+
+```js
+getStateFromGST("27AAPFU0939F1ZV");
+// "Maharashtra"
+```
+
+### `extractPAN(gstin)`
+
+Extracts the PAN embedded in a GSTIN.
+
+```js
+extractPAN("27AAPFU0939F1ZV");
+// "AAPFU0939F"
+```
+
+### `getGSTHolderType(gstin)`
+
+Returns the holder type based on the PAN's fourth character.
+
+```js
+getGSTHolderType("27AAPFU0939F1ZV");
+// "Firm"
+```
+
+> **Note:** Return values depend on the input and the package's implementation. Invalid inputs may return `false`, `null`, or another documented fallback.
+
+## Running Tests
+
+Clone the repository and install dependencies:
+
+```bash
+git clone https://github.com/Ayushkr7380/indian-gst-validator.git
+
+cd indian-gst-validator
+
+npm install
+```
+
+Run the test suite:
+
+```bash
+npm test
+```
+
+## Important Note
+
+This package performs local GSTIN format and checksum validation. It does **not** verify GST registration status, taxpayer details, or active status from the official GST portal.
+
+For official GST registration verification, use the appropriate GST portal or authorized API.
+
+## Contributing
+
+Contributions, bug reports, and feature suggestions are welcome!
+
+1. Fork the repository
+2. Create a new branch
+3. Make your changes
+4. Run the tests
+5. Submit a pull request
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).
+
+## Author
+
+**Ayush Kumar**
+
+- GitHub: [@Ayushkr7380](https://github.com/Ayushkr7380)
+- npm: [indian-gst-validator](https://www.npmjs.com/package/indian-gst-validator)

package/index.js

@@ -0,0 +1,14 @@
+const { isValidGST, getStateFromGST, extractPAN, getGSTHolderType } = require("./src/gstValidator");
+const { getStateName, STATE_CODES } = require("./src/stateCodes");
+const { isValidPANFormat, getHolderType } = require("./src/pan");
+
+module.exports = {
+  isValidGST,
+  getStateFromGST,
+  extractPAN,
+  getGSTHolderType,
+  getStateName,
+  STATE_CODES,
+  isValidPANFormat,
+  getHolderType,
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "indian-gst-validator",
+  "version": "1.0.0",
+  "description": "Validate and extract details from Indian GST numbers",
+  "main": "index.js",
+  "scripts": {
+    "test": "node test/test.js"
+  },
+  "keywords": [
+    "gst",
+    "gstin",
+    "india",
+    "validator",
+    "tax"
+  ],
+  "author": "Ayush Kumar",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Ayushkr7380/indian-gst-validator.git"
+  },
+  "homepage": "https://github.com/Ayushkr7380/indian-gst-validator#readme",
+  "bugs": {
+    "url": "https://github.com/Ayushkr7380/indian-gst-validator/issues"
+  },
+  "engines": {
+    "node": ">=14"
+  }
+}

package/src/checksum.js

@@ -0,0 +1,43 @@
+// Characters used for GST checksum calculation
+const CHAR_SET = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+
+// Calculate the check digit using the first 14 characters of the GST number
+function calculateCheckDigit(gstFirst14) {
+  let sum = 0;
+
+  for (let i = 0; i < gstFirst14.length; i++) {
+    const char = gstFirst14[i];
+    const codePoint = CHAR_SET.indexOf(char);
+
+    // Alternate between multiplying by 1 and 2
+    const factor = i % 2 === 0 ? 1 : 2;
+
+    const product = codePoint * factor;
+
+    // Convert the product into a base-36 digit sum
+    const digit = Math.floor(product / 36) + (product % 36);
+
+    sum += digit;
+  }
+
+  // Calculate the final checksum value
+  const checksumValue = (36 - (sum % 36)) % 36;
+
+  return CHAR_SET[checksumValue];
+}
+
+// Check whether the GST number has a valid checksum
+function isValidChecksum(gstNumber) {
+  if (typeof gstNumber !== "string" || gstNumber.length !== 15) return false;
+
+  const first14 = gstNumber.slice(0, 14).toUpperCase();
+  const providedCheckDigit = gstNumber[14].toUpperCase();
+
+  // Compare the calculated check digit with the provided one
+  const calculated = calculateCheckDigit(first14);
+
+  return calculated === providedCheckDigit;
+}
+
+// Export the checksum functions
+module.exports = { calculateCheckDigit, isValidChecksum };

package/src/gstValidator.js

@@ -0,0 +1,68 @@
+const { getStateName } = require("./stateCodes");
+const { isValidPANFormat, getHolderType } = require("./pan");
+const { isValidChecksum } = require("./checksum");
+
+// Regex to check the basic GST number format
+const GST_REGEX = /^[0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][1-9A-Z]Z[0-9A-Z]$/;
+
+// Check whether the GST number follows the correct format
+function isValidGSTFormat(gst) {
+  if (typeof gst !== "string") return false;
+
+  return GST_REGEX.test(gst.toUpperCase());
+}
+
+// Validate the GST number using its format, state code, PAN and checksum
+function isValidGST(gstNumber) {
+  if (typeof gstNumber !== "string") return false;
+
+  const gst = gstNumber.toUpperCase().trim();
+
+  if (!isValidGSTFormat(gst)) return false;
+
+  // The first two characters represent the state code
+  const stateCode = gst.slice(0, 2);
+  if (!getStateName(stateCode)) return false;
+
+  // Extract and validate the PAN embedded in the GST number
+  const pan = gst.slice(2, 12);
+  if (!isValidPANFormat(pan)) return false;
+
+  // Check whether the last character matches the calculated checksum
+  if (!isValidChecksum(gst)) return false;
+
+  return true;
+}
+
+// Get the state name from the first two characters of the GST number
+function getStateFromGST(gstNumber) {
+  if (typeof gstNumber !== "string" || gstNumber.length < 2) return null;
+
+  const stateCode = gstNumber.slice(0, 2);
+
+  return getStateName(stateCode);
+}
+
+// Extract the PAN from a GST number
+function extractPAN(gstNumber) {
+  if (typeof gstNumber !== "string" || gstNumber.length < 12) return null;
+
+  return gstNumber.slice(2, 12).toUpperCase();
+}
+
+// Get the PAN holder type associated with the GST number
+function getGSTHolderType(gstNumber) {
+  const pan = extractPAN(gstNumber);
+
+  if (!pan) return null;
+
+  return getHolderType(pan);
+}
+
+// Export the GST validation and extraction functions
+module.exports = {
+  isValidGST,
+  getStateFromGST,
+  extractPAN,
+  getGSTHolderType,
+};

package/src/pan.js

@@ -0,0 +1,35 @@
+// PAN format validation pattern
+const PAN_REGEX = /^[A-Z]{3}[ABCFGHLJPT][A-Z][0-9]{4}[A-Z]$/;
+
+// PAN holder types based on the fourth character
+const HOLDER_TYPES = {
+  A: "Association of Persons (AOP)",
+  B: "Body of Individuals (BOI)",
+  C: "Company",
+  F: "Firm / Partnership",
+  G: "Government",
+  H: "Hindu Undivided Family (HUF)",
+  L: "Local Authority",
+  J: "Artificial Juridical Person",
+  P: "Individual",
+  T: "Trust",
+};
+
+// Check whether the given PAN follows the correct format
+function isValidPANFormat(pan) {
+  if (typeof pan !== "string") return false;
+
+  return PAN_REGEX.test(pan.toUpperCase());
+}
+
+// Get the PAN holder type from its fourth character
+function getHolderType(pan) {
+  if (!isValidPANFormat(pan)) return null;
+
+  const fourthChar = pan.toUpperCase()[3];
+
+  return HOLDER_TYPES[fourthChar] || null;
+}
+
+// Export the functions and holder type mapping
+module.exports = { isValidPANFormat, getHolderType, HOLDER_TYPES };

package/src/stateCodes.js

@@ -0,0 +1,49 @@
+// Indian state and union territory codes with their names
+const STATE_CODES = {
+  "01": "Jammu and 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 and Diu",
+  "26": "Dadra and Nagar Haveli",
+  "27": "Maharashtra",
+  "28": "Andhra Pradesh (Old)",
+  "29": "Karnataka",
+  "30": "Goa",
+  "31": "Lakshadweep",
+  "32": "Kerala",
+  "33": "Tamil Nadu",
+  "34": "Puducherry",
+  "35": "Andaman and Nicobar Islands",
+  "36": "Telangana",
+  "37": "Andhra Pradesh",
+  "38": "Ladakh",
+};
+
+// Get the state name using its code
+function getStateName(code) {
+  return STATE_CODES[code] || null;
+}
+
+// Export the codes and function
+module.exports = { STATE_CODES, getStateName };

package/test/test.js

@@ -0,0 +1,32 @@
+const gst = require("../index");
+
+// Test cases for GST number validation
+const tests = [
+  ["27AAPFU0939F1ZV", true, "Valid GST number"],
+  ["27AAPFU0939F1ZX", false, "Wrong checksum"],
+  ["99AAPFU0939F1ZV", false, "Invalid state code"],
+  ["27AAPFU0939F1Z", false, "Too short (14 chars)"],
+  ["", false, "Empty string"],
+  [null, false, "Null input"],
+  [12345, false, "Number instead of string"],
+];
+
+let passed = 0;
+let failed = 0;
+
+// Run each test case and compare the result with the expected value
+tests.forEach(([input, expected, description]) => {
+  const result = gst.isValidGST(input);
+  const status = result === expected ? "PASS" : "FAIL";
+
+  // Keep track of passed and failed test cases
+  if (status === "PASS") passed++;
+  else failed++;
+
+  console.log(
+    `[${status}] ${description} — input: ${input}, expected: ${expected}, got: ${result}`
+  );
+});
+
+// Print the final test summary
+console.log(`\n${passed} passed, ${failed} failed`);