lt-public-transport-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Giedrius Macevičius
+
+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,283 @@
+# lt-public-transport-sdk
+
+A robust, type-safe TypeScript SDK for accessing **real-time public transport data** in Lithuanian cities.
+
+It handles the complexity of parsing raw GPS streams (HTML/CSV), normalizing coordinate formats, handling text encodings (Windows-1257), and merging live data with static GTFS schedules (routes, stops).
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)
+![Tests](https://img.shields.io/badge/Coverage-100%25-brightgreen.svg)
+
+## 🚀 Why use this SDK?
+
+Raw public transport data in Lithuania (from stops.lt) is fragmented and messy:
+
+- **Inconsistent Formats**: Vilnius uses 18 CSV columns, Kaunas uses 14, Panevėžys uses 9 (with no header).
+- **Weird Encodings**: Data is often in `windows-1257` or mixed encodings.
+- **Weird Coordinates**: Some cities provide WGS84, others provide integers divided by 1,000,000.
+- **Sparse Data**: GPS streams often lack route names or destinations, requiring lookup against GTFS data.
+
+**This SDK solves all of that.** It provides a **single, unified `Vehicle` interface** regardless of the city or underlying data format.
+
+## ✨ Features
+
+- **Unified API**: One method (`getVehicles`) validates and normalizes data for all supported cities.
+- **Auto-Enrichment**: optional automatic merging of live GPS data with GTFS routes (adds `destination`, `tripId`).
+- **Resilience**: Robust error handling for network timeouts, stale data, and malformed responses.
+- **Type-Safe**: Built with TypeScript and Zod for runtime validation.
+
+## 📦 Installation
+
+```bash
+npm install lt-public-transport-sdk
+```
+
+## ⚡ Quick Start
+
+```typescript
+import { LtTransport } from "lt-public-transport-sdk";
+
+// 1. Initialize the client
+const client = new LtTransport({
+  autoEnrich: true, // Automatically download GTFS and match routes
+  cacheDir: "./.cache", // Where to store GTFS/ZIP files
+});
+
+async function main() {
+  try {
+    // 2. Get real-time vehicles for Vilnius
+    console.log("Fetching Vilnius buses...");
+    const vehicles = await client.getVehicles("vilnius");
+
+    console.log(`Found ${vehicles.length} active vehicles:`);
+
+    vehicles.slice(0, 3).forEach((v) => {
+      console.log(`🚌 [${v.route}] ${v.vehicleNumber} -> ${v.destination}`);
+      console.log(`   📍 ${v.latitude}, ${v.longitude} (${v.speed} km/h)`);
+    });
+  } catch (err) {
+    console.error("Error fetching data:", err);
+  }
+}
+
+main();
+```
+
+## 🏙️ Supported Cities
+
+| City             | Tier      | GPS Data | GTFS Data | Formats Handled                        |
+| ---------------- | --------- | -------- | --------- | -------------------------------------- |
+| **Vilnius**      | 🥇 Gold   | ✅ Full  | ✅ Yes    | 18-col CSV, GTFS lookup                |
+| **Kaunas**       | 🥇 Gold   | ✅ Full  | ✅ Yes    | 14-col CSV, Trip/Stop matching         |
+| **Klaipėda**     | 🥇 Gold   | ✅ Full  | ✅ Yes    | 12-col CSV                             |
+| **Alytus**       | 🥇 Gold   | ✅ Full  | ✅ Yes    | 13-col CSV                             |
+| **Druskininkai** | 🥇 Gold   | ✅ Full  | ✅ Yes    | 13-col CSV                             |
+| **Panevėžys**    | 🥈 Silver | ✅ Lite  | ✅ Yes    | 9-col (no header), Integer coords      |
+| **Tauragė**      | 🥈 Silver | ✅ Lite  | ✅ Yes    | 8-col (no header), Alphanumeric routes |
+| **Šiauliai**     | 🥉 Bronze | ❌ No    | ✅ Yes    | GTFS only                              |
+| **Utena**        | 🥉 Bronze | ❌ No    | ✅ Yes    | GTFS only                              |
+
+## 🧩 How It Works
+
+![Architecture Diagram](assets/architecture.png)
+
+> **Note**: Bronze tier cities (Šiauliai, Utena) do not publish real-time GPS data. Calling `getVehicles()` will throw a `GpsNotAvailableError`, but `getRoutes()` and `getStops()` **work normally** with GTFS data.
+
+### `LtTransport` Class
+
+#### Configuration
+
+```typescript
+const client = new LtTransport({
+  // Directory to store downloaded GTFS zip files (default: os.tmpdir())
+  cacheDir: "./cache",
+
+  // Max age of GPS data to consider "live" (default: 5 minutes)
+  staleThresholdMs: 5 * 60 * 1000,
+
+  // Filter out vehicles that haven't updated recently (default: false)
+  filterStale: true,
+
+  // Fetch and parse GTFS to add destination/route info (default: true)
+  autoEnrich: true,
+
+  // Filter out coordinates outside Lithuania (default: true)
+  filterInvalidCoords: true,
+
+  // Request timeout in ms (default: 10000)
+  requestTimeout: 10000,
+});
+```
+
+#### Methods
+
+#### Methods
+
+| Method                    | Returns               | Description                                                                                              |
+| ------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------- |
+| **`getVehicles(city)`**   | `Promise<Vehicle[]>`  | Fetches real-time vehicle positions. If `autoEnrich` is true, ensures GTFS data is synced and merges it. |
+| **`sync(city, force?)`**  | `Promise<SyncResult>` | Manually downloads/updates GTFS static data (routes/stops). Throttled to 60s unless `force=true`.        |
+| **`getRoutes(city)`**     | `Promise<Route[]>`    | Returns the list of static routes from GTFS. Requires prior `sync()`.                                    |
+| **`getStops(city)`**      | `Promise<Stop[]>`     | Returns the list of static stops from GTFS. Requires prior `sync()`.                                     |
+| **`getCities()`**         | `CityId[]`            | Returns a list of all supported city identifiers.                                                        |
+| **`getCityConfig(city)`** | `CityConfig`          | Returns configuration details (tier, URLs) for a specific city.                                          |
+
+### Key Types
+
+#### `Vehicle`
+
+```typescript
+interface Vehicle {
+  /** Unique identifier (e.g. "vilnius-1234") */
+  readonly id: string;
+
+  /** Vehicle number visible on the bus/trolley */
+  readonly vehicleNumber: string;
+
+  /** Route number (e.g. "3G", "10") */
+  readonly route: string;
+
+  /** Type of vehicle */
+  readonly type: "bus" | "trolleybus" | "ferry" | "unknown";
+
+  /** Latitude in WGS84 decimal degrees */
+  readonly latitude: number;
+
+  /** Longitude in WGS84 decimal degrees */
+  readonly longitude: number;
+
+  /** Bearing in degrees (0-360) */
+  readonly bearing: number;
+
+  /** Speed in km/h */
+  readonly speed: number;
+
+  /** Destination name (e.g. "Santariškės") */
+  readonly destination: string | null;
+
+  /** Delay in seconds (positive = late, negative = early) */
+  readonly delaySeconds: number | null;
+
+  /** Trip identifier from source system */
+  readonly tripId: string | null;
+
+  /** GTFS trip reference (Vilnius only) */
+  readonly gtfsTripId: string | null;
+
+  /** Whether data is older than staleThreshold */
+  readonly isStale: boolean;
+
+  /** When the position was measured */
+  readonly measuredAt: Date;
+}
+```
+
+#### `Route` (GTFS)
+
+```typescript
+interface Route {
+  /** Unique route ID (e.g. "routes_123") */
+  readonly id: string;
+
+  /** Short name (e.g. "3G") */
+  readonly shortName: string;
+
+  /** Long name (e.g. "Oro uostas - Centras - Fabijoniškės") */
+  readonly longName: string;
+
+  /** Transport type */
+  readonly type: VehicleType;
+
+  /** Route color (hex without #) */
+  readonly color: string;
+
+  /** Text color (hex without #) */
+  readonly textColor: string;
+}
+```
+
+#### `Stop` (GTFS)
+
+```typescript
+interface Stop {
+  /** Unique stop ID */
+  readonly id: string;
+
+  /** Check digit code (if available) */
+  readonly code: string | null;
+
+  /** Stop name */
+  readonly name: string;
+
+  /** Stop description/details */
+  readonly description: string | null;
+
+  /** Latitude */
+  readonly latitude: number;
+
+  /** Longitude */
+  readonly longitude: number;
+}
+```
+
+## 💾 Caching & Best Practices
+
+By default, GTFS data (routes & stops) is cached in your system's temporary directory (`os.tmpdir()/lt-transport-sdk-cache`).
+
+### Microservices / Docker
+
+If you are running in a containerized environment (Docker, Kubernetes), it is recommended to:
+
+1.  **Persist the cache**: Mount a volume to avoid re-downloading GTFS data (5-10MB) on every container restart.
+2.  **Configure path**: Set `cacheDir` to your mounted volume.
+
+```typescript
+const client = new LtTransport({
+  cacheDir: "/data/cache", // Mount a volume here
+});
+```
+
+### Serverless (AWS Lambda, etc.)
+
+The SDK works in serverless environments by writing to `/tmp`. Note that "cold starts" will incur a latency penalty while GTFS data is downloaded and parsed.
+
+## ⚠️ Error Handling
+
+The SDK throws specific errors you can catch:
+
+```typescript
+import {
+  GpsNotAvailableError, // City doesn't support GPS
+  InvalidCityError, // Typo in city name
+  SyncRequiredError, // Need to run syncGtfs() (if autoEnrich: false)
+  TransportNetworkError, // Network timeout/failure
+} from "lt-public-transport-sdk/errors";
+
+try {
+  await client.getVehicles("unknown-city");
+} catch (err) {
+  if (err instanceof InvalidCityError) {
+    console.log("Invalid city ID!");
+  }
+}
+```
+
+## 🛠️ Development & Testing
+
+This project uses **Vitest** for testing and **TypeScript** for building.
+
+```bash
+# Install dependencies
+npm install
+
+# Run unit tests (fast, using fixtures)
+npm test
+
+# Run integration tests (hits live APIs - verify functionality)
+npm run build
+npm run test:integration
+```
+
+## 📄 License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,221 @@
+/**
+ * City configuration matrix for Lithuanian Public Transport SDK
+ * @module config
+ */
+/**
+ * City data tier classification based on data quality and availability.
+ * - gold: Full GPS streams with rich metadata (destination, delay, equipment)
+ * - silver: Lite GPS streams requiring GTFS enrichment
+ * - bronze: GTFS data only, no real-time GPS
+ */
+export type CityTier = 'gold' | 'silver' | 'bronze';
+/**
+ * GPS data stream configuration for a city.
+ */
+export interface GpsConfig {
+    /** Whether GPS data is available for this city */
+    readonly enabled: boolean;
+    /**
+     * Format of GPS data stream.
+     * - 'full': Header-based CSV with rich metadata (gold tier)
+     * - 'lite': Headerless CSV with minimal data (silver tier)
+     * - null: No GPS data available (bronze tier)
+     */
+    readonly format: 'full' | 'lite' | null;
+    /** URL to fetch GPS data, or null if not available */
+    readonly url: string | null;
+}
+/**
+ * GTFS static data configuration for a city.
+ */
+export interface GtfsConfig {
+    /** Whether GTFS data is available for this city */
+    readonly enabled: boolean;
+    /**
+     * URL to download GTFS ZIP archive.
+     * Pattern: https://www.stops.lt/${city}/${city}/gtfs.zip
+     */
+    readonly url: string;
+}
+/**
+ * Complete configuration for a city's transport data.
+ * Note: 'id' field is typed as string here but CityId union is derived from CITY_CONFIGS keys.
+ */
+export interface CityConfig {
+    /** City identifier */
+    readonly id: string;
+    /** Data quality tier */
+    readonly tier: CityTier;
+    /** GPS stream configuration */
+    readonly gps: GpsConfig;
+    /** GTFS static data configuration */
+    readonly gtfs: GtfsConfig;
+}
+/**
+ * City configuration matrix with all supported cities.
+ *
+ * Data Quality Tiers:
+ * - Gold: Full GPS streams with 12-18 columns including destination, delay, equipment
+ * - Silver: Lite GPS streams with 8-9 columns, requires GTFS enrichment for destinations
+ * - Bronze: GTFS only, no real-time GPS data available
+ *
+ * Column Counts (empirically verified 2026-01-05):
+ * - Vilnius: 18 columns (MatavimoLaikas, KryptiesTipas, ReisoIdGTFS)
+ * - Kaunas: 14 columns (Grafikas, SekanciosStotelesNum, AtvykimoLaikasSekundemis - NO MatavimoLaikas)
+ * - Klaipėda: 12 columns (minimal format)
+ * - Alytus: 13 columns
+ * - Druskininkai: 13 columns
+ * - Panevėžys: 9 columns lite (no header)
+ * - Tauragė: 8 columns lite (no header, alphanumeric routes like S11)
+ */
+declare const CITY_CONFIGS_INTERNAL: {
+    readonly vilnius: {
+        readonly id: "vilnius";
+        readonly tier: "gold";
+        readonly gps: {
+            readonly enabled: true;
+            readonly format: "full";
+            readonly url: string;
+        };
+        readonly gtfs: {
+            readonly enabled: true;
+            readonly url: string;
+        };
+    };
+    readonly kaunas: {
+        readonly id: "kaunas";
+        readonly tier: "gold";
+        readonly gps: {
+            readonly enabled: true;
+            readonly format: "full";
+            readonly url: string;
+        };
+        readonly gtfs: {
+            readonly enabled: true;
+            readonly url: string;
+        };
+    };
+    readonly klaipeda: {
+        readonly id: "klaipeda";
+        readonly tier: "gold";
+        readonly gps: {
+            readonly enabled: true;
+            readonly format: "full";
+            readonly url: string;
+        };
+        readonly gtfs: {
+            readonly enabled: true;
+            readonly url: string;
+        };
+    };
+    readonly alytus: {
+        readonly id: "alytus";
+        readonly tier: "gold";
+        readonly gps: {
+            readonly enabled: true;
+            readonly format: "full";
+            readonly url: string;
+        };
+        readonly gtfs: {
+            readonly enabled: true;
+            readonly url: string;
+        };
+    };
+    readonly druskininkai: {
+        readonly id: "druskininkai";
+        readonly tier: "gold";
+        readonly gps: {
+            readonly enabled: true;
+            readonly format: "full";
+            readonly url: string;
+        };
+        readonly gtfs: {
+            readonly enabled: true;
+            readonly url: string;
+        };
+    };
+    readonly panevezys: {
+        readonly id: "panevezys";
+        readonly tier: "silver";
+        readonly gps: {
+            readonly enabled: true;
+            readonly format: "lite";
+            readonly url: string;
+        };
+        readonly gtfs: {
+            readonly enabled: true;
+            readonly url: string;
+        };
+    };
+    readonly taurage: {
+        readonly id: "taurage";
+        readonly tier: "silver";
+        readonly gps: {
+            readonly enabled: true;
+            readonly format: "lite";
+            readonly url: string;
+        };
+        readonly gtfs: {
+            readonly enabled: true;
+            readonly url: string;
+        };
+    };
+    readonly siauliai: {
+        readonly id: "siauliai";
+        readonly tier: "bronze";
+        readonly gps: {
+            readonly enabled: false;
+            readonly format: null;
+            readonly url: null;
+        };
+        readonly gtfs: {
+            readonly enabled: true;
+            readonly url: string;
+        };
+    };
+    readonly utena: {
+        readonly id: "utena";
+        readonly tier: "bronze";
+        readonly gps: {
+            readonly enabled: false;
+            readonly format: null;
+            readonly url: null;
+        };
+        readonly gtfs: {
+            readonly enabled: true;
+            readonly url: string;
+        };
+    };
+};
+/**
+ * Supported city identifiers derived from configuration keys.
+ * Each city has specific GPS and GTFS data availability.
+ */
+export type CityId = keyof typeof CITY_CONFIGS_INTERNAL;
+/**
+ * City configuration matrix with all supported cities.
+ */
+export declare const CITY_CONFIGS: Readonly<Record<CityId, CityConfig>>;
+/**
+ * List of all supported city IDs.
+ */
+export declare const ALL_CITY_IDS: readonly CityId[];
+/**
+ * Get configuration for a specific city.
+ * @throws Error if city ID is invalid
+ */
+export declare function getCityConfig(city: CityId): CityConfig;
+/**
+ * Get all cities of a specific tier.
+ */
+export declare function getCitiesByTier(tier: CityTier): CityId[];
+/**
+ * Check if a city has GPS data available.
+ */
+export declare function hasGpsData(city: CityId): boolean;
+/**
+ * Check if a city has GTFS data available.
+ */
+export declare function hasGtfsData(city: CityId): boolean;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAMpD;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAExC,sDAAsD;IACtD,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,sBAAsB;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB,wBAAwB;IACxB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAExB,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IAExB,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;CAC3B;AAiCD;;;;;;;;;;;;;;;;GAgBG;AACH,QAAA,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8HjB,CAAC;AAEX;;;GAGG;AACH,MAAM,MAAM,MAAM,GAAG,MAAM,OAAO,qBAAqB,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAyB,CAAC;AAExF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAA0C,CAAC;AAErF;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAEtD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,EAAE,CAExD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEjD"}