Metadata-Version: 2.5
Name: kramank
Version: 0.1.0
Summary: Zero-dependency validators for Indian GSTIN, PAN, IFSC, and pincode formats — checksum-verified, type-hinted.
Project-URL: Homepage, https://kramank.pages.dev
Project-URL: Repository, https://github.com/planbcreator365/IndianAPI
Project-URL: Issues, https://github.com/planbcreator365/IndianAPI/issues
Author: Karndev Jhala
License-Expression: MIT
License-File: LICENSE
Keywords: checksum,gst,gstin,ifsc,india,pan,pincode,validation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# kramank

Zero-dependency validators for Indian identifiers: **GSTIN**, **PAN**, **IFSC**, and **pincode**.
Checksum-verified where a checksum exists (GSTIN), fully type-hinted, pure Python (no runtime dependencies).

This is a line-for-line Python port of the [TypeScript `kramank` package](https://www.npmjs.com/package/kramank) — same error codes, same decoded fields, tested against the exact same fixture files.

> **Format validation only.** These functions check that a string is a well-formed GSTIN/PAN/IFSC/pincode. They do **not** confirm the value is real, active, or currently registered with GSTN, the Income Tax Department, or a bank — that requires a live lookup against those systems, which this package does not do.

## Install

```bash
pip install kramank
```

## Usage

```python
from kramank import validate_gstin, validate_pan, validate_ifsc, validate_pincode

validate_gstin("27AAPFU0939F1ZV")
# {
#   "valid": True,
#   "input": "27AAPFU0939F1ZV",
#   "errors": [],
#   "warnings": [],
#   "stateCode": "27",
#   "state": "Maharashtra",
#   "category": "REGULAR",
#   "pan": "AAPFU0939F",
#   "panEntityType": "Firm",
#   "note": "Format check only — does not confirm this value is real, active, or currently registered.",
#   ...
# }

validate_pan("ABCPD1234E")
# {"valid": True, "entityType": "Individual", ...}

validate_ifsc("HDFC0001234")
# {"valid": True, "bankCode": "HDFC", ...}

validate_pincode("110001")
# {"valid": True, "zoneDigit": "1", "zone": "Northern Region — ...", ...}
```

Every validator returns the same shape — never a bare boolean — so a failed validation always tells you *why* (`errors[0]["code"]`), not just that it failed:

```python
{
    "valid": bool,
    "input": str,            # trimmed, normalized
    "errors": [{"code": str, "message": str}],
    "warnings": [{"code": str, "message": str}],
    # ...plus decoded fields specific to each identifier
}
```

Result keys are `camelCase` (matching the JSON wire format of the hosted API and the TypeScript package) rather than `snake_case`, so a result dict can be serialized straight to JSON and match the API's response shape.

## What this package does *not* do

- No network calls, no live registry lookups, no "is this GSTIN actually registered" check.
- No maintained reference data for IFSC branches or pincode post offices — just the structural/zone rules encoded in the formats themselves.

## The hosted Kramank API

[**Kramank**](https://kramank.pages.dev) (क्रमांक, "number") is a hosted API that builds on these same validators and adds what a pure format check can't give you:

- **IFSC lookup** — real bank, branch, and address data for a given IFSC code, kept up to date.
- **Pincode lookup** — real post office, district, and state data for a given pincode.
- The same GSTIN/PAN/IFSC/pincode format validation as this package, as a hosted endpoint — useful if you'd rather not vendor the logic at all (or aren't on Python/JS).

See the [API reference](https://kramank.pages.dev) for endpoints and free-tier limits, or get a key directly on [RapidAPI](https://rapidapi.com/planbcreator365/api/kramank-india-bank-pincode-gst-data1) — **BASIC** (free, 500 requests/month) and **PRO** ($9/month, 50,000 requests/month) are both live.

## License

MIT
