railkit 4.0.0

package/.claude/settings.local.json

@@ -0,0 +1,10 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm run *)",
+      "Read(//private/tmp/**)",
+      "Bash(curl -s \"http://localhost:3000/_next/static/chunks/%5Broot-of-the-server%5D__4beb427c._.css\")",
+      "Bash(curl -s http://localhost:3000__TRACKED_VAR__)"
+    ]
+  }
+}

package/README.md

@@ -0,0 +1,775 @@
+# RailKit
+
+[![npm version](https://badge.fury.io/js/irctc-connect.svg)](https://www.npmjs.com/package/irctc-connect)
+[![Downloads](https://img.shields.io/npm/dm/irctc-connect.svg)](https://www.npmjs.com/package/irctc-connect)
+[![License](https://img.shields.io/npm/l/irctc-connect.svg)](https://github.com/RAJIV81205/irctc-connect/blob/main/LICENSE)
+
+<img width="1536" height="657" alt="IRCTC Connect Banner" src="https://github.com/user-attachments/assets/39c770a2-639c-443c-93b6-4e78889e78b0" />
+
+A comprehensive Node.js SDK for Indian Railways. Get real-time PNR status, train information, live tracking, station updates, train search, and seat availability — all through a single, clean API.
+
+---
+
+## ✨ Features
+
+- 🎫 **PNR Status** — Real-time PNR status with full passenger details
+- 🚂 **Train Information** — Complete train details with station-by-station route
+- 📍 **Live Train Tracking** — Real-time position and delay info for any train
+- 🚉 **Live Station Board** — Upcoming trains at any station right now
+- 🔍 **Train Search** — Find all direct trains between two stations
+- 💺 **Seat Availability** — Check availability and fare for any class and quota
+- 💰 **Fare Lookup** — Full fare breakdown for any train, class, and quota
+- ⚡ **Fast & Reliable** — Built-in timeout handling, input validation, and caching
+
+---
+
+## 📦 Installation
+
+```bash
+npm install irctc-connect
+```
+
+---
+
+## 🔑 Getting an API Key
+
+1. Visit **[irctc.rajivdubey.dev](https://irctc.rajivdubey.dev)**
+2. Sign up and navigate to your Dashboard
+3. Generate an API key from the **API Keys** section
+4. Copy the key — you'll use it in the next step
+
+---
+
+## 🚀 Quick Start
+
+### Step 1 — Add your API key to `.env`
+
+```bash
+# .env
+IRCTC_API_KEY=your_api_key_here
+```
+
+### Step 2 — Configure the SDK once at startup
+
+```javascript
+import { configure } from 'irctc-connect';
+
+configure(process.env.IRCTC_API_KEY);
+```
+
+Call `configure()` **once** at the top of your app before using any other function. It stores your key globally for all subsequent calls.
+
+### Step 3 — Use any function
+
+```javascript
+import {
+  configure,
+  checkPNRStatus,
+  getTrainInfo,
+  trackTrain,
+  liveAtStation,
+  searchTrainBetweenStations,
+  getAvailability,
+  fareLookup,
+} from 'irctc-connect';
+
+// Configure once
+configure(process.env.IRCTC_API_KEY);
+
+// Check PNR status
+const pnrResult = await checkPNRStatus('1234567890');
+
+// Get train information
+const trainResult = await getTrainInfo('12301');
+
+// Track live train status (date optional, defaults to today)
+const trackResult = await trackTrain('12301', '31-03-2026');
+
+// Get live trains at a station
+const stationResult = await liveAtStation('NDLS');
+
+// Search trains between stations
+const searchResult = await searchTrainBetweenStations('NDLS', 'BCT');
+
+// Get seat availability with fare breakdown
+const availResult = await getAvailability('12496', 'ASN', 'DDU', '27-12-2025', '2A', 'GN');
+
+// Get fare for a journey
+const fareResult = await fareLookup('12313', 'ASN', 'NDLS', '06-06-2026', '3A', 'GN');
+```
+
+---
+
+## 📖 API Reference
+
+### `configure(apiKey)`
+
+Configure the SDK with your API key. **Must be called once before any other function.**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `apiKey` | string | Your API key from the dashboard |
+
+```javascript
+import { configure } from 'irctc-connect';
+
+configure(process.env.IRCTC_API_KEY);
+```
+
+---
+
+### 1. `checkPNRStatus(pnr)`
+
+Get comprehensive PNR status with passenger details, journey information, chart status, and booking fare.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pnr` | string | 10-digit PNR number |
+
+**Example:**
+```javascript
+const result = await checkPNRStatus('5827194603');
+
+if (result.success) {
+  console.log('PNR:', result.data.pnr);
+  console.log('Train:', result.data.train.name, `(${result.data.train.number})`);
+  console.log('Journey:', `${result.data.journey.source.name} → ${result.data.journey.destination.name}`);
+  console.log('Class:', result.data.journey.class, '| Quota:', result.data.journey.quota);
+  console.log('Fare:', `₹${result.data.booking.fare}`);
+
+  result.data.passengers.forEach(p => {
+    console.log(`${p.serialNumber}: booking ${p.booking.details} → current ${p.current.details}`);
+  });
+}
+```
+
+**Response:**
+```javascript
+{
+  success: true,
+  data: {
+    pnr: "5827194603",
+    train: {
+      number: "12987",
+      name: "SAMPURN K RAJDHANI"
+    },
+    journey: {
+      dateOfJourney: "22 Aug 2026, 04:35:00 pm",
+      class: "3A",
+      quota: "GN",
+      source: { code: "JP", name: "JAIPUR JN" },
+      destination: { code: "NDLS", name: "NEW DELHI" },
+      boardingPoint: { code: "JP", name: "JAIPUR JN" },
+      distance: 471,
+      arrivalDate: "22 Aug 2026, 10:20:00 pm"
+    },
+    chart: { status: "Chart Prepared" },
+    booking: {
+      fare: 1845,
+      ticketFare: 1795,
+      bookingDate: "20 Aug 2026, 11:14:32 am"
+    },
+    passengers: [
+      {
+        serialNumber: "Passenger 1",
+        coachPosition: 0,
+        booking: {
+          status: "CNF",
+          coach: "B5",
+          berthNo: 22,
+          berthCode: "LB",
+          details: "CNF/B5/22/LB"
+        },
+        current: {
+          status: "CNF",
+          coach: "B5",
+          berthNo: 22,
+          berthCode: "LB",
+          details: "CNF , B5 - 22 [LB]"
+        }
+      },
+      {
+        serialNumber: "Passenger 2",
+        coachPosition: 0,
+        booking: {
+          status: "RAC",
+          coach: null,
+          berthNo: 7,
+          berthCode: null,
+          details: "RAC/7"
+        },
+        current: {
+          status: "CNF",
+          coach: "B5",
+          berthNo: 31,
+          berthCode: "UB",
+          details: "CNF , B5 - 31 [UB]"
+        }
+      }
+    ]
+  }
+}
+```
+
+---
+
+### 2. `getTrainInfo(trainNumber)`
+
+Get detailed train information including complete route with station coordinates.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `trainNumber` | string | 5-digit train number |
+
+**Example:**
+```javascript
+const result = await getTrainInfo('12301');
+
+if (result.success) {
+  const { trainInfo, route } = result.data;
+
+  console.log(`🚂 ${trainInfo.train_name} (${trainInfo.train_no})`);
+  console.log(`📍 ${trainInfo.from_stn_name} → ${trainInfo.to_stn_name}`);
+  console.log(`⏱️ ${trainInfo.from_time} → ${trainInfo.to_time} (${trainInfo.travel_time})`);
+  console.log(`📅 Running days: ${trainInfo.running_days}`);
+
+  route.slice(0, 5).forEach(stn => {
+    console.log(`  ${stn.stnName} (${stn.stnCode}) — dep: ${stn.departure}`);
+  });
+}
+```
+
+**Response:**
+```javascript
+{
+  success: true,
+  data: {
+    trainInfo: {
+      train_no: "12301",
+      train_name: "HOWRAH RAJDHANI",
+      from_stn_name: "NEW DELHI",
+      from_stn_code: "NDLS",
+      to_stn_name: "HOWRAH JN",
+      to_stn_code: "HWH",
+      from_time: "17:00",
+      to_time: "09:55",
+      travel_time: "16:55 hrs",
+      running_days: "1111111",
+      type: "RAJDHANI"
+    },
+    route: [
+      {
+        stnCode: "NDLS", stnName: "NEW DELHI",
+        arrival: "--", departure: "17:00",
+        halt: "0 min", distance: "0", day: "1",
+        coordinates: { latitude: 28.6431, longitude: 77.2201 }
+      }
+      // ... more stations
+    ]
+  }
+}
+```
+
+---
+
+### 3. `trackTrain(trainNumber, date?)`
+
+Get real-time live status of a train with a unified station timeline (stoppages + intermediate stations in route order).
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `trainNumber` | string | 5-digit train number |
+| `date` | string *(optional)* | Date in `DD-MM-YYYY` format. Defaults to today if omitted. |
+
+**Example:**
+```javascript
+const result = await trackTrain('12301', '31-03-2026');
+
+if (result.success) {
+  const { trainNo, trainName, statusNote, currentStationCode, timeline } = result.data;
+
+  console.log(`🚂 ${trainName} (${trainNo})`);
+  console.log(`📍 Status: ${statusNote}`);
+  console.log(`🎯 Current station code: ${currentStationCode}`);
+
+  timeline.forEach(point => {
+    console.log(`\n🚉 ${point.stationName} (${point.stationCode})`);
+    console.log(`   Type: ${point.type} | Status: ${point.status}`);
+
+    if (point.type === 'stoppage') {
+      console.log(`   PF: ${point.platform || '-'}`);
+      console.log(`   Arr: ${point.arrival.scheduled} → ${point.arrival.actual} ${point.arrival.delay}`);
+      console.log(`   Dep: ${point.departure.scheduled} → ${point.departure.actual} ${point.departure.delay}`);
+    }
+  });
+}
+```
+
+**Response:**
+```javascript
+{
+  success: true,
+  data: {
+    trainNo: "12301",
+    trainName: "HOWRAH RAJDHANI",
+    date: "31-Mar-2026",
+    statusNote: "Arrived at HOWRAH JN(HWH) — On Time",
+    lastUpdate: "31-Mar-2026 10:01",
+    totalStations: 8, // stoppage count from source
+    currentStationCode: "HWH",
+    timeline: [
+      {
+        type: "stoppage", // stoppage | intermediate
+        status: "passed", // passed | current | upcoming
+        stationCode: "NDLS", stationName: "NEW DELHI",
+        platform: "16", distanceKm: "0",
+        arrival:   { scheduled: "SRC", actual: "SRC",        delay: ""        },
+        departure: { scheduled: "17:00", actual: "17:00",    delay: "On Time" },
+        coachPosition: [
+          { type: "ENG", number: "ENG", position: "0" },
+          { type: "3A",  number: "B1",  position: "5" }
+          // ...
+        ]
+      },
+      {
+        type: "intermediate",
+        status: "current",
+        stationCode: "SZM",
+        stationName: "SUBZI MANDI"
+      }
+      // ... more timeline points
+    ]
+  }
+}
+```
+
+---
+
+### 4. `getTrainHistory(trainNumber, journeyDate)`
+
+Get the completed journey history of a train for a specific journey date. The backend persists a `TrainHistory` record once a train has reached its destination, including the full station-by-station timeline, per-stop delays, and the final coach position.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `trainNumber` | string | 5-digit train number |
+| `journeyDate` | string | Journey date in `DD-MM-YYYY` format |
+
+**Example:**
+```javascript
+const result = await getTrainHistory('12301', '15-04-2025');
+
+if (result.success) {
+  const { trainNo, trainName, journeyDate, stations, coachPosition } = result.data;
+
+  console.log(`🚂 ${trainName} (${trainNo}) — ${journeyDate}`);
+
+  stations.forEach((stop) => {
+    console.log(`\n🚉 ${stop.stationName} (${stop.stationCode})`);
+    console.log(`   PF: ${stop.platform || '-'}`);
+    console.log(`   Arr: ${stop.arrival.scheduled} → ${stop.arrival.actual} (${stop.arrival.delay} min)`);
+    console.log(`   Dep: ${stop.departure.scheduled} → ${stop.departure.actual} (${stop.departure.delay} min)`);
+  });
+}
+```
+
+**Response:**
+```javascript
+{
+  success: true,
+  data: {
+    historyKey: "12301:15-04-2025",
+    trainNo: "12301",
+    trainName: "HOWRAH RAJDHANI",
+    journeyDate: "15-04-2025",
+    sourceStationCode: "NDLS",
+    sourceStationName: "NEW DELHI",
+    destinationStationCode: "HWH",
+    destinationStationName: "HOWRAH JN",
+    stations: [
+      {
+        stationCode: "NDLS",
+        stationName: "NEW DELHI",
+        platform: "16",
+        distanceKm: 0,
+        arrival:   { scheduled: "SRC", actual: "SRC",   delay: 0  },
+        departure: { scheduled: "17:00", actual: "17:00", delay: 0 }
+      },
+      {
+        stationCode: "HWH",
+        stationName: "HOWRAH JN",
+        platform: "9",
+        distanceKm: 1447,
+        arrival:   { scheduled: "09:55", actual: "09:55", delay: 0 },
+        departure: { scheduled: "10:00", actual: "10:00", delay: 0 }
+      }
+    ],
+    coachPosition: [
+      { type: "ENG", number: "ENG", position: "0" },
+      { type: "3A",  number: "B1",  position: "5" }
+    ],
+    lastUpdate: "2025-04-16T10:05:00.000Z"
+  }
+}
+```
+
+> The endpoint returns `404` with `{ success: false, error: "Train history record not found" }` for dates where the train has not yet reached its destination.
+
+---
+
+### 5. `liveAtStation(stnCode, hours?)`
+
+Get the list of upcoming and passing trains at a station in real time, with arrival/departure times, delays, and platform info.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `stnCode` | string | Station code (e.g., `'NDLS'`, `'BCT'`, `'HWH'`) |
+| `hours` | number | Time window — `2`, `4`, or `8` (default `2`) |
+
+**Example:**
+```javascript
+const result = await liveAtStation('NDLS', 2);
+
+if (result.success) {
+  console.log(result.data.summary);
+  console.log(`Total trains: ${result.data.totalTrains}`);
+
+  result.data.trains.forEach(train => {
+    console.log(`🚂 ${train.trainNo} — ${train.trainName}`);
+    console.log(`   📍 ${train.sourceName} → ${train.destName} | PF ${train.platform}`);
+    console.log(`   ⏰ Arr ${train.arrival.actual} (scheduled ${train.arrival.scheduled}, delay ${train.arrival.delay}m)`);
+  });
+}
+```
+
+**Response:**
+```javascript
+{
+  success: true,
+  data: {
+    summary: "20 Trains departing from/arriving at NDLS - NEW DELHI. in next 2 Hrs.",
+    totalTrains: 2,
+    trains: [
+      {
+        trainNo: "12987",
+        trainName: "SAMPURN K RAJDHANI",
+        source: "JP",
+        sourceName: "JAIPUR JN",
+        dest: "NDLS",
+        destName: "NEW DELHI",
+        trainType: "Rajdhani",
+        classes: "1A, 2A, 3A",
+        runDate: "22-Aug-2026",
+        platform: "9",
+        cancelled: false,
+        arrival:   { actual: "10:18", scheduled: "10:20", delay: 0,  delayed: false },
+        departure: { actual: "10:25", scheduled: "10:25", delay: 5,  delayed: true  }
+      },
+      {
+        trainNo: "12309",
+        trainName: "RAJDHANI EXPRESS",
+        source: "HWH",
+        sourceName: "HOWRAH JN",
+        dest: "NDLS",
+        destName: "NEW DELHI",
+        trainType: "Rajdhani",
+        classes: "1A, 2A, 3A",
+        runDate: "22-Aug-2026",
+        platform: "3",
+        cancelled: false,
+        arrival:   { actual: "11:05", scheduled: "11:00", delay: 5,  delayed: true  },
+        departure: { actual: "11:12", scheduled: "11:10", delay: 2,  delayed: true  }
+      }
+    ]
+  }
+}
+```
+
+---
+
+### 6. `searchTrainBetweenStations(fromStnCode, toStnCode)`
+
+Find all direct trains running between two stations.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fromStnCode` | string | Origin station code |
+| `toStnCode` | string | Destination station code |
+
+**Example:**
+```javascript
+const result = await searchTrainBetweenStations('NDLS', 'BCT');
+
+if (result.success) {
+  console.log(`Found ${result.data.length} trains\n`);
+
+  result.data.forEach(train => {
+    console.log(`🚂 ${train.train_name} (${train.train_no})`);
+    console.log(`   📍 ${train.from_stn_name} → ${train.to_stn_name}`);
+    console.log(`   ⏰ ${train.from_time} → ${train.to_time} (${train.travel_time})`);
+    console.log(`   📏 Distance: ${train.distance} km`);
+    console.log(`   📅 Days: ${train.running_days}`);
+  });
+}
+```
+
+**Response:**
+```javascript
+{
+  success: true,
+  data: [
+    {
+      train_no: "12951",
+      train_name: "MUMBAI RAJDHANI",
+      source_stn_name: "NEW DELHI",
+      source_stn_code: "NDLS",
+      dstn_stn_name: "MUMBAI CENTRAL",
+      dstn_stn_code: "BCT",
+      from_stn_name: "NEW DELHI",
+      from_stn_code: "NDLS",
+      to_stn_name: "MUMBAI CENTRAL",
+      to_stn_code: "BCT",
+      from_time: "16:55",
+      to_time: "08:35",
+      travel_time: "15:40 hrs",
+      running_days: "1111111",
+      distance: "1384",
+      halts: 8
+    }
+    // ... more trains (sorted by departure time)
+  ]
+}
+```
+
+---
+
+### 7. `getAvailability(trainNo, fromStnCode, toStnCode, date, coach, quota)`
+
+Check seat availability and fare breakdown for a specific train, class, and date.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `trainNo` | string | 5-digit train number |
+| `fromStnCode` | string | Origin station code (e.g., `'NDLS'`) |
+| `toStnCode` | string | Destination station code (e.g., `'BCT'`) |
+| `date` | string | Journey date in `DD-MM-YYYY` format |
+| `coach` | string | Coach/class code — see [Class & Quota Reference](#-class--quota-reference) |
+| `quota` | string | Quota code — see [Class & Quota Reference](#-class--quota-reference) |
+
+**Example:**
+```javascript
+const result = await getAvailability('12301', 'NDLS', 'HWH', '27-12-2025', '3A', 'GN');
+
+if (result.success) {
+  const { train, fare, availability } = result.data;
+
+  console.log(`🚂 ${train.trainName} (${train.trainNo})`);
+  console.log(`📍 ${train.fromStationName} → ${train.toStationName}`);
+
+  console.log('\n💰 Fare Breakdown:');
+  console.log(`   Base Fare:    ₹${fare.baseFare}`);
+  console.log(`   Reservation:  ₹${fare.reservationCharge}`);
+  console.log(`   Superfast:    ₹${fare.superfastCharge}`);
+  console.log(`   Total:        ₹${fare.totalFare}`);
+
+  console.log('\n📅 Availability:');
+  availability.forEach(day => {
+    console.log(`   ${day.date}: ${day.availabilityText} — ${day.prediction}`);
+  });
+}
+```
+
+---
+
+### 8. `fareLookup(trainNo, fromStnCode, toStnCode, date, travelClass, quota)`
+
+Get the full fare breakdown for a journey — base fare, reservation, superfast, catering, GST, dynamic fare, and total.
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `trainNo` | string | 5-digit train number |
+| `fromStnCode` | string | Origin station code (e.g., `'ASN'`) |
+| `toStnCode` | string | Destination station code (e.g., `'NDLS'`) |
+| `date` | string | Journey date in `DD-MM-YYYY` format |
+| `travelClass` | string | See class codes below |
+| `quota` | string | See quota codes below |
+
+**Class Codes:** see [Class & Quota Reference](#-class--quota-reference)
+
+**Quota Codes:** see [Class & Quota Reference](#-class--quota-reference)
+
+**Example:**
+```javascript
+const result = await fareLookup('12313', 'ASN', 'NDLS', '06-06-2026', '3A', 'GN');
+
+if (result.success) {
+  const d = result.data;
+  console.log(`🚂 ${d.trainName} (${d.trainNo})`);
+  console.log(`📍 ${d.from} → ${d.to}  |  ${d.distance} km`);
+  console.log(`\n💰 Fare Breakdown:`);
+  console.log(`   Base Fare:    ₹${d.baseFare}`);
+  console.log(`   Reservation:  ₹${d.reservation}`);
+  console.log(`   Superfast:    ₹${d.superfast}`);
+  console.log(`   Catering:     ₹${d.catering}`);
+  console.log(`   Dynamic Fare: ₹${d.dynamicFare}`);
+  console.log(`   GST:          ₹${d.gst}`);
+  console.log(`   ─────────────────`);
+  console.log(`   Total:        ₹${d.totalFare}`);
+}
+```
+
+**Response:**
+```javascript
+{
+  success: true,
+  data: {
+    trainNo:     "12313",
+    trainName:   "RAJDHANI EXPRES",
+    from:        "ASN",
+    to:          "NDLS",
+    class:       "3A",
+    distance:    1249,
+    baseFare:    1617,
+    reservation: 40,
+    superfast:   45,
+    catering:    310,
+    dynamicFare: 647,
+    gst:         118,
+    totalFare:   2780,
+    tatkalFare:  0,
+    concession:  0
+  }
+}
+```
+
+---
+
+## ⚠️ Error Handling
+
+All functions return a consistent response structure. Always check `success` before accessing `data`.
+
+```javascript
+// ✅ Success
+{ success: true, data: { /* ... */ } }
+
+// ❌ Failure
+{ success: false, error: "Description of what went wrong" }
+```
+
+**Common error scenarios:**
+
+| Error | Cause |
+|-------|-------|
+| `irctc-connect is not configured` | `configure()` was not called |
+| `Invalid API key` (401) | Key doesn't exist in the system |
+| `API key is inactive` (403) | Key has been deactivated |
+| `Usage limit exceeded` (429) | Monthly request quota reached |
+| `PNR number must be exactly 10 digits` | Bad input |
+| `Invalid train number` | Train number not 5 digits |
+| `Invalid date format. Use DD-MM-YYYY.` | Wrong date format |
+| `Request timed out` | Upstream service too slow |
+
+---
+
+## 🛡️ Input Validation
+
+The SDK validates inputs locally before making any network call:
+
+- **PNR** — must be exactly 10 digits (non-numerics auto-stripped)
+- **Train number** — must be exactly 5 characters
+- **Station codes** — must be uppercase alphabetic, 1–5 chars
+- **Date** — must be `DD-MM-YYYY`, validated for real calendar dates
+- **Coach / Class** — see [Class & Quota Reference](#-class--quota-reference)
+- **Quota** — see [Class & Quota Reference](#-class--quota-reference)
+
+---
+
+## 📊 PNR Status Codes
+
+| Code | Meaning |
+|------|---------|
+| `CNF` | Confirmed |
+| `WL` | Waiting List |
+| `RAC` | Reservation Against Cancellation |
+| `CAN` | Cancelled |
+| `PQWL` | Pooled Quota Waiting List |
+| `TQWL` | Tatkal Quota Waiting List |
+| `GNWL` | General Waiting List |
+
+---
+
+## 🚃 Class & Quota Reference
+
+Used by both `getAvailability` and `fareLookup`.
+
+### Coach / Travel Class
+
+| Code | Class | Functions |
+|------|-------|-----------|
+| `SL` | Sleeper Class | both |
+| `2S` | Second Seating | both |
+| `3A` | Third AC | both |
+| `3E` | Third AC Economy | both |
+| `2A` | Second AC | both |
+| `1A` | First AC | both |
+| `CC` | AC Chair Car | both |
+| `EC` | Executive Class | both |
+| `EA` | Executive Anubhuti | `fareLookup` |
+| `FC` | First Class | `fareLookup` |
+| `VS` | Vistadome Non AC | `fareLookup` |
+| `CH` | Chair Car High Capacity | `fareLookup` |
+| `HS` | Sleeper High Capacity | `fareLookup` |
+| `VC` | Vistadome CC | `fareLookup` |
+| `VA` | Vistadome AC | `fareLookup` |
+
+### Quota
+
+| Code | Quota | Functions |
+|------|-------|-----------|
+| `GN` | General | both |
+| `TQ` | Tatkal | both |
+| `LD` | Ladies | both |
+| `SS` | Senior Citizen | both |
+| `PT` | Premium Tatkal | `fareLookup` |
+| `DF` | Defence | `fareLookup` |
+| `FT` | Foreign Tourist | `fareLookup` |
+| `LB` | Lower Berth | `fareLookup` |
+| `YU` | Yuva | `fareLookup` |
+| `DP` | Duty Pass | `fareLookup` |
+| `HP` | Handicapped | `fareLookup` |
+| `PH` | Parliament House | `fareLookup` |
+
+---
+
+## 🔧 Requirements
+
+- Node.js 18+ (native `fetch` required)
+- Internet connection for API calls
+- A valid IRCTC Connect API key
+
+---
+
+## 🙋 Support
+
+- **Issues:** [GitHub Issues](https://github.com/RAJIV81205/irctc-connect/issues)
+- **Docs:** [irctc.rajivdubey.dev/docs](https://irctc.rajivdubey.dev/docs)
+- **Discussions:** [GitHub Discussions](https://github.com/RAJIV81205/irctc-connect/discussions)
+
+---
+
+*Built with ❤️ for Indian Railways enthusiasts. Happy journey! 🚂*

package/index.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Configure the SDK with your API key before using any other function.
+ * The backend URL is managed by the package - you only need your API key.
+ *
+ * @example
+ * configure('your-api-key-here');
+ */
+export function configure(apiKey: string): void;
+
+/**
+ * Check the PNR status for a given 10-digit PNR number.
+ *
+ * @example
+ * const result = await checkPNRStatus('1234567890');
+ * 
+ */
+export function checkPNRStatus(pnr: string): Promise<any>;
+
+/**
+ * Get detailed information and route for a given 5-digit train number.
+ *
+ * @example
+ * const result = await getTrainInfo('12301');
+ * 
+ */
+export function getTrainInfo(trainNumber: string): Promise<any>;
+
+/**
+ * Get the live running status of a train.
+ * @param date - Journey date in DD-MM-YYYY format (optional, defaults to today)
+ *
+ * @example
+ * const result = await trackTrain('12301', '15-04-2025');
+ *
+ */
+export function trackTrain(trainNumber: string, date?: string): Promise<any>;
+
+/**
+ * Get the completed journey history of a train for a specific journey date.
+ * Returns the persisted TrainHistory record once the train has reached its
+ * destination, including the full station-by-station timeline, per-stop delays,
+ * and the final coach position.
+ * 
+ * @param trainNumber - 5-digit train number
+ * @param journeyDate - Journey date in DD-MM-YYYY format
+ *
+ * @example
+ * const result = await getTrainHistory('12301', '15-04-2025');
+ */
+export function getTrainHistory(trainNumber: string, journeyDate: string): Promise<any>;
+
+/**
+ * Get the list of upcoming trains at a station.
+ * @param stationCode - Station Code (e.g., 'NDLS' for New Delhi)
+ * @param hours - Time window in hours: 2, 4, or 8 (default 2)
+ *
+ * @example
+ * const result = await liveAtStation('NDLS', 2);
+ */
+export function liveAtStation(stationCode: string, hours?: 2 | 4 | 8): Promise<any>;
+
+/**
+ * Search for all direct trains between two stations.
+ * @param fromStnCode - Source station code
+ * @param toStnCode - Destination station code
+ * @param date - Journey date in DD-MM-YYYY format (optional)
+ *
+ * @example
+ * const result = await searchTrainBetweenStations('NDLS', 'BCT', '15-04-2025');
+ */
+export function searchTrainBetweenStations(fromStnCode: string, toStnCode: string, date?: string): Promise<any>;
+
+/**
+ * Check seat availability for a specific train, class, and date.
+ * @param trainNo - 5-digit train number
+ * @param fromStnCode - Source station code
+ * @param toStnCode - Destination station code
+ * @param date - Journey date in DD-MM-YYYY format
+ * @param coach - '2S' | 'SL' | '3A' | '3E' | '2A' | '1A' | 'CC' | 'EC'
+ * @param quota - 'GN' | 'LD' | 'SS' | 'TQ'
+ *
+ * @example
+ * const result = await getAvailability('12301', 'NDLS', 'HWH', '15-04-2025', '3A', 'GN');
+ * 
+ */
+export function getAvailability(
+  trainNo: string,
+  fromStnCode: string,
+  toStnCode: string,
+  date: string,
+  coach: string,
+  quota: string
+): Promise<any>;
+
+/**
+ * Get the fare breakdown for a train journey.
+ * Returns baseFare, reservation, superfast, catering, GST, dynamicFare and totalFare.
+ * 
+ * @param trainNo - 5-digit train number
+ * @param fromStnCode - Source station code
+ * @param toStnCode - Destination station code
+ * @param date - Journey date in DD-MM-YYYY format
+ * @param travelClass - '1A' | '2A' | '3A' | '3E' | 'CC' | 'EC' | 'EA' | 'FC' | 'SL' | '2S' | 'VS' | 'CH' | 'HS' | 'VC' | 'VA'
+ * @param quota       - 'GN' | 'TQ' | 'LD' | 'DF' | 'FT' | 'LB' | 'PT' | 'YU' | 'DP' | 'HP' | 'PH' | 'SS'
+ *
+ * @example
+ * const result = await fareLookup('12313', 'ASN', 'NDLS', '06-06-2026', '3A', 'GN');
+ */
+export function fareLookup(
+  trainNo: string,
+  fromStnCode: string,
+  toStnCode: string,
+  date: string,
+  travelClass: string,
+  quota: string
+): Promise<any>;

package/index.obfuscated.js

@@ -0,0 +1 @@
+const a0_0x11c2ee=a0_0x5187;(function(_0x287da6,_0x1d0872){const _0x6f81cf=a0_0x5187,_0x59cea5=_0x287da6();while(!![]){try{const _0x146809=parseInt(_0x6f81cf(0x203))/0x1*(parseInt(_0x6f81cf(0x20c))/0x2)+-parseInt(_0x6f81cf(0x1f7))/0x3+parseInt(_0x6f81cf(0x20e))/0x4+-parseInt(_0x6f81cf(0x21d))/0x5*(parseInt(_0x6f81cf(0x1fa))/0x6)+parseInt(_0x6f81cf(0x211))/0x7+parseInt(_0x6f81cf(0x200))/0x8+parseInt(_0x6f81cf(0x21a))/0x9*(-parseInt(_0x6f81cf(0x214))/0xa);if(_0x146809===_0x1d0872)break;else _0x59cea5['push'](_0x59cea5['shift']());}catch(_0x4ac069){_0x59cea5['push'](_0x59cea5['shift']());}}}(a0_0x148b,0xb087b));import{createHash,createHmac,randomBytes}from'node:crypto';const _baseUrl=a0_0x11c2ee(0x212),_sdkVersion='1',_defaultSdkSigningSecret='97c56e08b27b161124f88acd4f24d1bd50f48075f11dc23b9ea6c0bc9b2f8794';let _apiKey='',_sdkSigningSecret=_defaultSdkSigningSecret;function configure(_0x36ca5e){const _0x336536=a0_0x11c2ee;if(!_0x36ca5e||typeof _0x36ca5e!=='string')throw new Error('[irctc-connect]\x20configure()\x20requires\x20a\x20valid\x20API\x20key\x20string.');_apiKey=_0x36ca5e[_0x336536(0x218)]();}function a0_0x5187(_0x1191e5,_0x4d3da9){_0x1191e5=_0x1191e5-0x1f3;const _0x148b8b=a0_0x148b();let _0x5187fc=_0x148b8b[_0x1191e5];if(a0_0x5187['eQMwOV']===undefined){var _0x517689=function(_0x18d513){const _0x3b6442='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789+/=';let _0x36ca5e='',_0x3e2880='';for(let _0x21e8db=0x0,_0x322892,_0x12a17b,_0x954c72=0x0;_0x12a17b=_0x18d513['charAt'](_0x954c72++);~_0x12a17b&&(_0x322892=_0x21e8db%0x4?_0x322892*0x40+_0x12a17b:_0x12a17b,_0x21e8db++%0x4)?_0x36ca5e+=String['fromCharCode'](0xff&_0x322892>>(-0x2*_0x21e8db&0x6)):0x0){_0x12a17b=_0x3b6442['indexOf'](_0x12a17b);}for(let _0x2bd8af=0x0,_0x1619d3=_0x36ca5e['length'];_0x2bd8af<_0x1619d3;_0x2bd8af++){_0x3e2880+='%'+('00'+_0x36ca5e['charCodeAt'](_0x2bd8af)['toString'](0x10))['slice'](-0x2);}return decodeURIComponent(_0x3e2880);};a0_0x5187['trkuZY']=_0x517689,a0_0x5187['FdTZhD']={},a0_0x5187['eQMwOV']=!![];}const _0x46d692=_0x148b8b[0x0],_0x30a334=_0x1191e5+_0x46d692,_0x577ba5=a0_0x5187['FdTZhD'][_0x30a334];return!_0x577ba5?(_0x5187fc=a0_0x5187['trkuZY'](_0x5187fc),a0_0x5187['FdTZhD'][_0x30a334]=_0x5187fc):_0x5187fc=_0x577ba5,_0x5187fc;}function _hashPayload(_0x3e2880){const _0x2fc469=a0_0x11c2ee;return createHash(_0x2fc469(0x20d))['update'](_0x3e2880)[_0x2fc469(0x20f)](_0x2fc469(0x1f3));}function _buildSignature({method:_0x21e8db,path:_0x322892,timestamp:_0x12a17b,nonce:_0x954c72,payloadHash:_0x2bd8af}){const _0x457d89=a0_0x11c2ee,_0x1619d3=[_0x21e8db[_0x457d89(0x209)](),_0x322892,_0x12a17b,_0x954c72,_0x2bd8af,_apiKey][_0x457d89(0x201)]('\x0a');return createHmac(_0x457d89(0x20d),_sdkSigningSecret)[_0x457d89(0x213)](_0x1619d3)[_0x457d89(0x20f)]('hex');}function _getSdkSecurityHeaders(_0x1f4eda,_0xdf8ea3,_0x47513b=''){const _0x18c1be=a0_0x11c2ee,_0xa739e8=String(Date[_0x18c1be(0x1ff)]()),_0x9cdad1=randomBytes(0x20)[_0x18c1be(0x216)]('hex'),_0x46fcc5=_hashPayload(_0x47513b),_0x35fb33=_buildSignature({'method':_0x1f4eda,'path':_0xdf8ea3,'timestamp':_0xa739e8,'nonce':_0x9cdad1,'payloadHash':_0x46fcc5});return{'x-irctc-sdk-ts':_0xa739e8,'x-irctc-sdk-nonce':_0x9cdad1,'x-irctc-sdk-payload-sha256':_0x46fcc5,'x-irctc-sdk-signature':_0x35fb33,'x-irctc-sdk-version':_sdkVersion};}async function _get(_0x4b5371){const _0x436211=a0_0x11c2ee;if(!_apiKey)return{'success':![],'error':_0x436211(0x20b)};try{const _0x5e8a6e=_getSdkSecurityHeaders(_0x436211(0x206),_0x4b5371,''),_0x5e0f39=await fetch(''+_baseUrl+_0x4b5371,{'method':'GET','headers':{'x-api-key':_apiKey,'Accept':_0x436211(0x20a),..._0x5e8a6e}}),_0x83e93a=await _0x5e0f39[_0x436211(0x1f4)]();return _0x83e93a;}catch(_0x5b561b){return{'success':![],'error':_0x436211(0x1f9)+_0x5b561b[_0x436211(0x205)]};}}async function checkPNRStatus(_0x3190ac){const _0x8371a7=a0_0x11c2ee;if(!_0x3190ac||typeof _0x3190ac!==_0x8371a7(0x1f6))return{'success':![],'error':_0x8371a7(0x21c)};const _0x21dcd3=_0x3190ac['trim']()['replace'](/\D/g,'');if(_0x21dcd3[_0x8371a7(0x1fb)]!==0xa)return{'success':![],'error':_0x8371a7(0x204)};return _get(_0x8371a7(0x217)+_0x21dcd3);}async function getTrainInfo(_0x278d77){const _0x5abe2c=a0_0x11c2ee;if(!_0x278d77||typeof _0x278d77!==_0x5abe2c(0x1f6)||_0x278d77[_0x5abe2c(0x218)]()[_0x5abe2c(0x1fb)]!==0x5)return{'success':![],'error':'Invalid\x20train\x20number.\x20It\x20must\x20be\x20a\x205-character\x20string.'};return _get('/api/getTrainInfo/'+_0x278d77[_0x5abe2c(0x218)]());}async function trackTrain(_0x5a12d7,_0x59245c){const _0x5a89b8=a0_0x11c2ee;if(!_0x5a12d7||typeof _0x5a12d7!==_0x5a89b8(0x1f6)||_0x5a12d7[_0x5a89b8(0x218)]()[_0x5a89b8(0x1fb)]!==0x5)return{'success':![],'error':_0x5a89b8(0x1fd)};const _0x5108fb=_0x59245c?_0x5a89b8(0x215)+_0x5a12d7['trim']()+'/'+encodeURIComponent(_0x59245c[_0x5a89b8(0x218)]()):_0x5a89b8(0x215)+_0x5a12d7['trim']()+_0x5a89b8(0x210);return _get(_0x5108fb);}function a0_0x148b(){const _0x222e37=['ntyYnJyYngjMu0fksa','zgLNzxn0','l3rVzgf5','odeYmJeZnunJse9WEq','Ahr0Chm6lY9YywLSA2L0lwfWAs5YywPPDMr1yMv5lMrLDG','DxbKyxrL','mJC1mty4nZb6vxvyC1q','l2fWAs90CMfJA1rYywLUlW','Dg9tDhjPBMC','l2fWAs9JAgvJA1bouLn0yxr1CY8','DhjPBq','l2fWAs90CMfPBKHPC3rVCNKV','ovLMyu5rEa','sM91CM5LEsbKyxrLigLZihjLCxvPCMvKigfUzcbTDxn0igjLigLUierelu1nlvLzwvKGzM9YBwf0lG','ue5sig51BwjLCIbPCYbYzxf1AxjLzcbHBMqGBxvZDcbIzsbHihn0CMLUzY4','oty2nwLjAMfvvG','Agv4','ANnVBG','l2fWAs9ZzwfYy2HuCMfPBKjLDhDLzw5tDgf0Aw9UCY8','C3rYAw5N','mtC2otKYnvjbswzoyW','qM90AcbMCM9TigfUzcb0BYbZDgf0Aw9UignVzgvZigfYzsbYzxf1AxjLzcbHBMqGBxvZDcbIzsbZDhjPBMDZlG','uMvXDwvZDcbMywLSzwq6ia','mJu4nNzIEMzvzq','BgvUz3rO','Aw5JBhvKzxm','sw52ywXPzcb0CMfPBIbUDw1IzxiUieL0ig11C3qGyMuGysa1lwnOyxjHy3rLCIbZDhjPBMCU','p2HYCZ0','BM93','mteXntKZmJHqAhbeBuO','AM9PBG','DgvZDa','murcswrREa','ue5sig51BwjLCIbTDxn0igjLigv4ywn0BhKGmtaGzgLNAxrZlG','BwvZC2fNzq','r0vu','l2fWAs9MyxjLtg9VA3vWlW','sw5JB21WBgv0zsbKyxrHlIbqBgvHC2uGChjVDMLKzsbHBgWGCMvXDwLYzwqGzMLLBgrZlG','Dg9vChbLCKnHC2u','yxbWBgLJyxrPB24VANnVBG','AxjJDgmTy29UBMvJDcbPCYbUB3qGy29UzMLNDxjLzc4Gq2fSBcbJB25MAwD1CMuOyxbPs2v5ksbMAxjZDc4','mtG3mtK1mg13z0TUEq','C2HHmJu2'];a0_0x148b=function(){return _0x222e37;};return a0_0x148b();}async function getTrainHistory(_0x98dcf5,_0x3c9319){const _0x3c2b35=a0_0x11c2ee;if(!_0x98dcf5||typeof _0x98dcf5!==_0x3c2b35(0x1f6)||_0x98dcf5['trim']()['length']!==0x5)return{'success':![],'error':_0x3c2b35(0x1fd)};if(!_0x3c9319||typeof _0x3c9319!==_0x3c2b35(0x1f6)||!/^\d{2}-\d{2}-\d{4}$/[_0x3c2b35(0x202)](_0x3c9319['trim']()))return{'success':![],'error':_0x3c2b35(0x21b)};return _get(_0x3c2b35(0x219)+_0x98dcf5[_0x3c2b35(0x218)]()+'/'+encodeURIComponent(_0x3c9319[_0x3c2b35(0x218)]()));}async function liveAtStation(_0x4694ee,_0x42c4ae){const _0x4af69c=a0_0x11c2ee;if(!_0x4694ee||typeof _0x4694ee!==_0x4af69c(0x1f6))return{'success':![],'error':'Station\x20code\x20is\x20required\x20and\x20must\x20be\x20a\x20string.'};let _0x2e8909='';if(_0x42c4ae!==undefined&&_0x42c4ae!==null){const _0x7b3901=Number(_0x42c4ae);if(![0x2,0x4,0x8][_0x4af69c(0x1fc)](_0x7b3901))return{'success':![],'error':'Invalid\x20\x27hours\x27\x20value.\x20Allowed\x20values:\x202,\x204,\x208.'};_0x2e8909=_0x4af69c(0x1fe)+_0x7b3901;}return _get('/api/liveAtStation/'+_0x4694ee[_0x4af69c(0x218)]()['toUpperCase']()+_0x2e8909);}async function searchTrainBetweenStations(_0x1ca1be,_0x201c3e,_0x1ec638){const _0x553fde=a0_0x11c2ee;if(!_0x1ca1be||typeof _0x1ca1be!==_0x553fde(0x1f6)||!_0x201c3e||typeof _0x201c3e!==_0x553fde(0x1f6)||_0x1ec638&&typeof _0x1ec638!==_0x553fde(0x1f6))return{'success':![],'error':_0x553fde(0x1f8)};let _0x285d91=_0x553fde(0x1f5)+_0x1ca1be[_0x553fde(0x218)]()['toUpperCase']()+'/'+_0x201c3e[_0x553fde(0x218)]()[_0x553fde(0x209)]();return _0x1ec638&&(_0x285d91+='?date='+encodeURIComponent(_0x1ec638[_0x553fde(0x218)]())),_get(_0x285d91);}async function getAvailability(_0x2ff60d,_0x50bddc,_0x588c27,_0x256eb4,_0x15d3cc,_0x358d88){const _0x2f1758=a0_0x11c2ee;if(!_0x2ff60d||!_0x50bddc||!_0x588c27||!_0x256eb4||!_0x15d3cc||!_0x358d88)return{'success':![],'error':_0x2f1758(0x208)};const _0x10589f=_0x50bddc[_0x2f1758(0x218)]()[_0x2f1758(0x209)](),_0x317545=_0x588c27[_0x2f1758(0x218)]()[_0x2f1758(0x209)](),_0x39d99c=_0x15d3cc[_0x2f1758(0x218)]()[_0x2f1758(0x209)](),_0x498cb1=_0x358d88[_0x2f1758(0x218)]()[_0x2f1758(0x209)](),_0x514c6e=_0x2ff60d['trim']();return _get('/api/getAvailability/'+_0x514c6e+'/'+_0x10589f+'/'+_0x317545+'/'+encodeURIComponent(_0x256eb4[_0x2f1758(0x218)]())+'/'+_0x39d99c+'/'+_0x498cb1);}async function fareLookup(_0xd642ea,_0x47c6f9,_0x36e7c7,_0x5bcdf6,_0x398f3d,_0x359adf){const _0x1386d5=a0_0x11c2ee;if(!_0xd642ea||!_0x47c6f9||!_0x36e7c7||!_0x5bcdf6||!_0x398f3d||!_0x359adf)return{'success':![],'error':_0x1386d5(0x208)};const _0x54e1b8=_0x47c6f9[_0x1386d5(0x218)]()[_0x1386d5(0x209)](),_0x3b6cbd=_0x36e7c7['trim']()[_0x1386d5(0x209)](),_0x100ee9=_0x398f3d[_0x1386d5(0x218)]()[_0x1386d5(0x209)](),_0x6cd574=_0x359adf[_0x1386d5(0x218)]()[_0x1386d5(0x209)](),_0x1651fb=_0xd642ea[_0x1386d5(0x218)]();return _get(_0x1386d5(0x207)+_0x1651fb+'/'+encodeURIComponent(_0x5bcdf6[_0x1386d5(0x218)]())+'/'+_0x54e1b8+'/'+_0x3b6cbd+'/'+_0x100ee9+'/'+_0x6cd574);}export{configure,checkPNRStatus,getTrainInfo,trackTrain,getTrainHistory,liveAtStation,searchTrainBetweenStations,getAvailability,fareLookup};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "railkit",
+  "version": "4.0.0",
+  "description": "🚂 Complete Node.js SDK for Indian Railways - Check PNR status, train schedules, live running status, seat availability, station information and more. Promise-based API with TypeScript support.",
+  "keywords": [
+    "railkit",
+    "railway",
+    "indian-railways",
+    "irctc",
+    "pnr-status",
+    "train",
+    "train-status",
+    "live-train-status",
+    "railway-api",
+    "railway-sdk",
+    "rail-api",
+    "train-schedules",
+    "station-codes",
+    "seat-availability",
+    "nodejs",
+    "typescript",
+    "sdk",
+    "api-wrapper",
+    "india"
+  ],
+  "homepage": "https://railkit.rajivdubey.dev/",
+  "bugs": {
+    "url": "https://github.com/RAJIV81205/railkit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RAJIV81205/railkit.git"
+  },
+  "license": "ISC",
+  "author": "Rajiv Dubey",
+  "type": "module",
+  "main": "index.obfuscated.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.obfuscated.js",
+      "default": "./index.obfuscated.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "dev": "nodemon index.js",
+    "obfuscate": "npx javascript-obfuscator index.js --output index.obfuscated.js --compact true --string-array true --string-array-encoding base64 --rename-globals false --control-flow-flattening false --dead-code-injection false"
+  }
+}