zet-api 1.0.0

package/README.md

@@ -0,0 +1,257 @@
+# 🚊 ZET API - Zagreb Electric Tram API Client
+
+> TypeScript/Node.js client for **ZET (Zagreb Electric Tram)** public transportation API.
+> Access real-time data for routes, trips, stops, vehicles, and service updates.
+
+---
+
+## ✨ Features
+
+- 🚋 Get all **tram and bus routes**
+- 🚌 Fetch **real-time trip information**
+- ⏱️ Get **trip stop times** with live tracking
+- 📰 Access **ZET newsfeed** for service updates
+- 🚗 Track **live vehicle positions** with GPS coordinates
+- � **Automatic authentication** with token refresh
+- 💾 Built-in **TTL-based caching** for optimal performance
+- ✅ **Zod schema validation** for type-safe data
+- ⚡ Written in **TypeScript**, ready for Node.js (≥20.2.0)
+
+---
+
+## 📦 Installation
+
+```bash
+npm install zet-api
+# or
+pnpm add zet-api
+```
+
+---
+
+## 🚀 Quick Start
+
+```typescript
+import { ZetManager } from "zet-api";
+
+// Create manager with infinite cache (default)
+const zet = new ZetManager();
+
+// Get all routes (cached)
+const routes = await zet.getRoutes();
+console.log("Total routes:", routes.length);
+
+// Search for a specific route
+const results = await zet.searchRoutes({ query: "Borongaj", limit: 5 });
+
+// Get real-time trips for route 1
+const trips = await zet.getRouteTrips({ routeId: 1, daysFromToday: 0 });
+
+// Get stop times with parsed dates
+const stopTimes = await zet.getTripStopTimes({
+  tripId: "0_5_105_1_10687",
+});
+console.log("Next stop:", stopTimes.find((s) => !s.isArrived)?.stopName);
+
+// Get live vehicles for route 1
+const vehicles = await zet.getLiveVehicles({ routeId: 1 });
+console.log("Active vehicles:", vehicles.length);
+```
+
+---
+
+## 🎯 Caching Strategy
+
+The `ZetManager` caches static data (routes, stops, news) for performance while always fetching fresh real-time data (trips, vehicles).
+
+### Constructor Options
+
+```typescript
+// Infinite cache (never expires) - default
+const zet = new ZetManager();
+
+// 5 minute cache
+const zet = new ZetManager(5 * 60 * 1000);
+
+// No cache (always fetch fresh)
+const zet = new ZetManager(0);
+```
+
+### What Gets Cached?
+
+| Data Type  | Cached? | Reason               |
+| ---------- | ------- | -------------------- |
+| Routes     | ✅ Yes  | Rarely changes       |
+| Stops      | ✅ Yes  | Rarely changes       |
+| News       | ✅ Yes  | Changes occasionally |
+| Trips      | ❌ No   | Real-time data       |
+| Stop Times | ❌ No   | Real-time data       |
+| Vehicles   | ❌ No   | Real-time positions  |
+
+## 🔐 Authentication
+
+The `ZetManager` includes an integrated `authManager` that handles authentication automatically. Use it to access user-specific features like account information and ePurse balance.
+
+### Basic Usage
+
+```typescript
+import { ZetManager } from "zet-api";
+
+const zet = new ZetManager();
+
+// Login once
+await zet.authManager.login({
+  username: "your-email@example.com",
+  password: "your-password",
+});
+
+// Access user data (tokens refresh automatically)
+const account = await zet.authManager.getAccount();
+console.log(`Welcome, ${account.firstName}!`);
+console.log(`Balance: ${account.ePurseAmount}€`);
+
+// Check authentication status
+if (zet.authManager.isAuthenticated()) {
+  console.log("User is logged in");
+}
+
+// Logout when done
+await zet.authManager.logout();
+```
+
+### Register New Account
+
+```typescript
+await zet.authManager.register({
+  email: "your-email@example.com",
+  password: "your-secure-password",
+  confirmPassword: "your-secure-password",
+});
+
+console.log("✅ Registration successful! Check your email to confirm.");
+```
+
+### Long-Running Service Example
+
+```typescript
+import { ZetManager } from "zet-api";
+
+const zet = new ZetManager();
+
+// Login once at startup
+await zet.authManager.login({
+  username: process.env.ZET_EMAIL!,
+  password: process.env.ZET_PASSWORD!,
+});
+
+console.log("🚀 Service started with automatic auth");
+
+// Poll live data every 30 seconds
+setInterval(async () => {
+  try {
+    // Tokens refresh automatically - no manual management needed
+    const trips = await zet.getStopIncomingTrips({ stopId: "317_1" });
+    console.log(
+      `[${new Date().toLocaleTimeString()}] ${trips.length} incoming trips`
+    );
+  } catch (error) {
+    console.error("Error:", error.message);
+  }
+}, 30000);
+```
+
+---
+
+## 💡 Usage Examples
+
+### Real-Time Trip Tracking
+
+```typescript
+const zet = new ZetManager();
+
+// Get route info
+const route = await zet.getRouteById(1);
+console.log(`Tracking: ${route?.longName}`);
+
+// Get active trips
+const trips = await zet.getRouteTrips({ routeId: 1 });
+const activeTrips = trips.filter((t) => t.tripStatus === 2);
+
+// Track first active trip
+if (activeTrips[0]) {
+  const stopTimes = await zet.getTripStopTimes({
+    tripId: activeTrips[0].id,
+  });
+
+  const nextStops = stopTimes.filter((st) => !st.isArrived);
+  console.log("Upcoming stops:");
+  nextStops.forEach((stop) => {
+    const time = stop.expectedArrivalDateTime.toLocaleTimeString();
+    console.log(`  ${stop.stopName} - ${time}`);
+  });
+}
+```
+
+### Live Data Polling
+
+```typescript
+const zet = new ZetManager(60000); // 1-minute cache for static data
+
+// Poll route 6 every 10 seconds
+setInterval(async () => {
+  const liveData = await zet.getLiveTripsForRoute(6);
+  console.log(
+    `[${new Date().toLocaleTimeString()}] ${liveData.size} active trips`
+  );
+
+  for (const [tripId, stopTimes] of liveData.entries()) {
+    const nextStop = stopTimes.find((st) => !st.isArrived);
+    if (nextStop) {
+      console.log(`  Trip ${tripId}: Next stop ${nextStop.stopName}`);
+    }
+  }
+}, 10000);
+```
+
+### Search and Filter
+
+```typescript
+const zet = new ZetManager();
+
+// Search stops
+const stops = await zet.searchStops({
+  query: "Glavni kolodvor",
+  limit: 5,
+});
+
+stops.forEach((stop) => {
+  console.log(`${stop.name}`);
+  console.log(`  Routes: ${stop.trips.map((t) => t.routeCode).join(", ")}`);
+});
+```
+
+### Service Updates
+
+```typescript
+const zet = new ZetManager();
+
+// Get active news
+const newsWithDates = await zet.getNewsfeed();
+const now = new Date();
+
+const activeNews = newsWithDates.filter(
+  (n) => n.validFrom <= now && n.validTo >= now
+);
+
+console.log(`${activeNews.length} active service updates`);
+activeNews.forEach((item) => {
+  console.log(`📰 ${item.title}`);
+  console.log(`   Lines: ${item.lines.join(", ") || "All"}`);
+});
+```
+
+---
+
+## 📄 License
+
+This project is licensed under the GPL-v3 License. See the [LICENSE](LICENSE) file for details.

package/dist/auth/manager.d.ts

@@ -0,0 +1,19 @@
+import { LoginCredentials, RegisterCredentials, AuthTokensLogin } from './types';
+export declare class ZetAuthManager {
+    private tokens;
+    private refreshPromise;
+    private readonly tokenExpiryBufferMs;
+    private readonly defaultTokenExpiryMs;
+    isAuthenticated(): boolean;
+    getAccessToken(): Promise<string>;
+    login(credentials: LoginCredentials): Promise<AuthTokensLogin>;
+    register(credentials: RegisterCredentials): Promise<void>;
+    logout(): Promise<void>;
+    private tryReuseAccessToken;
+    private tryRefreshToken;
+    private performPasswordLogin;
+    private ensureTokenRefresh;
+    private performTokenRefresh;
+    private storeTokens;
+    private clearTokens;
+}

package/dist/auth/manager.js

@@ -0,0 +1,228 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZetAuthManager = void 0;
+const types_1 = require("./types");
+const config_1 = __importStar(require("../core/config"));
+const utils_1 = require("../core/utils");
+const axios_1 = __importDefault(require("axios"));
+class ZetAuthManager {
+    tokens = null;
+    refreshPromise = null;
+    tokenExpiryBufferMs = 120000; // 2 minutes before expiry, consider it expired.
+    defaultTokenExpiryMs = 900000; // 15 minutes default expiry if not provided.
+    isAuthenticated() {
+        return this.tokens !== null && Date.now() < this.tokens.expiresAt - this.tokenExpiryBufferMs;
+    }
+    async getAccessToken() {
+        if (!this.tokens)
+            throw new Error('Not authenticated. Please login first.');
+        if (Date.now() < this.tokens.expiresAt - this.tokenExpiryBufferMs)
+            return this.tokens.access;
+        await this.ensureTokenRefresh();
+        if (!this.tokens || Date.now() >= this.tokens.expiresAt - this.tokenExpiryBufferMs)
+            throw new Error('Token expired. Please login again.');
+        return this.tokens.access;
+    }
+    async login(credentials) {
+        const validated = types_1.LoginCredentialsSchema.parse(credentials);
+        if (validated.accessToken && validated.refreshToken) {
+            const reusedTokens = this.tryReuseAccessToken(validated.accessToken, validated.refreshToken);
+            if (reusedTokens)
+                return reusedTokens;
+        }
+        if (validated.refreshToken) {
+            const refreshedTokens = await this.tryRefreshToken(validated.refreshToken);
+            if (refreshedTokens)
+                return refreshedTokens;
+        }
+        return await this.performPasswordLogin(validated);
+    }
+    async register(credentials) {
+        const validated = types_1.RegisterCredentialsSchema.parse(credentials);
+        if (validated.password !== validated.confirmPassword)
+            throw new Error('Passwords do not match.');
+        const response = await axios_1.default.post(`${config_1.default.accountServiceUrl}/register`, validated, { headers: config_1.headers }).catch((err) => err.response);
+        if (!response || response.status !== 200) {
+            const errorMsg = response?.data?.message || response?.statusText || 'Unknown error';
+            throw new Error(`Registration failed: ${errorMsg}`);
+        }
+    }
+    async logout() {
+        if (this.tokens?.refresh) {
+            try {
+                const validated = types_1.RefreshTokenRequestSchema.parse({ refreshToken: this.tokens.refresh });
+                await axios_1.default.post(`${config_1.default.authServiceUrl}/logout`, validated, { headers: config_1.headers }).catch(() => { });
+            }
+            catch {
+                // *
+            }
+        }
+        this.clearTokens();
+    }
+    tryReuseAccessToken(accessToken, refreshToken) {
+        try {
+            const parts = accessToken.split('.');
+            if (parts.length !== 3 || !parts[1])
+                return null;
+            const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString('utf8'));
+            if (!payload.exp)
+                return null;
+            const expiresAt = payload.exp * 1000;
+            const now = Date.now();
+            if (expiresAt > now + this.tokenExpiryBufferMs) {
+                this.storeTokens({ accessToken, refreshToken }, expiresAt);
+                return {
+                    accessToken: this.tokens.access,
+                    refreshToken: this.tokens.refresh,
+                    expiresIn: Math.max(0, this.tokens.expiresAt - now),
+                    viaTokenRefresh: false,
+                    viaAccessToken: true,
+                };
+            }
+            return null;
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    async tryRefreshToken(refreshToken) {
+        try {
+            const validated = types_1.RefreshTokenRequestSchema.parse({ refreshToken });
+            const response = await axios_1.default.post(`${config_1.default.authServiceUrl}/refreshTokens`, validated, { headers: config_1.headers }).catch((err) => err.response);
+            if (!response || response.status !== 200)
+                return null;
+            const parsed = types_1.AuthTokensSchema.safeParse(response.data);
+            if (!parsed.success)
+                return null;
+            this.storeTokens(parsed.data);
+            return {
+                accessToken: this.tokens.access,
+                refreshToken: this.tokens.refresh,
+                expiresIn: Math.max(0, this.tokens.expiresAt - Date.now()),
+                viaTokenRefresh: true,
+                viaAccessToken: false,
+            };
+        }
+        catch (error) {
+            return null;
+        }
+    }
+    async performPasswordLogin(validated) {
+        if (!validated.username || !validated.password)
+            throw new Error('Username and password are required for login.');
+        const loginData = {
+            username: validated.username,
+            password: validated.password,
+            revokeOtherTokens: validated.revokeOtherTokens,
+            fcmToken: validated.fcmToken,
+        };
+        const response = await axios_1.default.post(`${config_1.default.authServiceUrl}/login`, loginData, { headers: config_1.headers }).catch((err) => err.response);
+        if (!response || response.status !== 200)
+            throw new Error(`Login failed: ${response?.statusText || 'Unknown error'}`);
+        const parsed = types_1.AuthTokensSchema.safeParse(response.data);
+        if (!parsed.success)
+            throw new Error(`Failed to parse login response: ${(0, utils_1.parseZodError)(parsed.error).join(', ')}`);
+        this.storeTokens(parsed.data);
+        return {
+            accessToken: this.tokens.access,
+            refreshToken: this.tokens.refresh,
+            expiresIn: Math.max(0, this.tokens.expiresAt - Date.now()),
+            viaTokenRefresh: false,
+            viaAccessToken: false,
+        };
+    }
+    async ensureTokenRefresh() {
+        if (this.refreshPromise)
+            return this.refreshPromise;
+        this.refreshPromise = this.performTokenRefresh();
+        try {
+            await this.refreshPromise;
+        }
+        finally {
+            this.refreshPromise = null;
+        }
+    }
+    async performTokenRefresh() {
+        if (!this.tokens?.refresh)
+            throw new Error('No refresh token available.');
+        const refreshToken = this.tokens.refresh;
+        try {
+            const validated = types_1.RefreshTokenRequestSchema.parse({ refreshToken });
+            const response = await axios_1.default.post(`${config_1.default.authServiceUrl}/refreshTokens`, validated, { headers: config_1.headers }).catch((err) => err.response);
+            if (!response || response.status !== 200) {
+                this.clearTokens();
+                throw new Error(`Token refresh failed: ${response?.statusText || 'Unknown error'}. Please login again.`);
+            }
+            const parsed = types_1.AuthTokensSchema.safeParse(response.data);
+            if (!parsed.success) {
+                this.clearTokens();
+                throw new Error(`Failed to parse refresh response: ${(0, utils_1.parseZodError)(parsed.error).join(', ')}`);
+            }
+            this.storeTokens(parsed.data);
+        }
+        catch (error) {
+            this.clearTokens();
+            throw error;
+        }
+    }
+    storeTokens(tokens, expiresAt) {
+        if (!expiresAt) {
+            try {
+                const parts = tokens.accessToken.split('.');
+                if (parts.length === 3 && parts[1]) {
+                    const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString('utf8'));
+                    expiresAt = payload.exp ? payload.exp * 1000 : Date.now() + this.defaultTokenExpiryMs;
+                }
+            }
+            catch {
+                // *
+            }
+        }
+        this.tokens = {
+            access: tokens.accessToken,
+            refresh: tokens.refreshToken,
+            expiresAt: expiresAt || Date.now() + this.defaultTokenExpiryMs,
+        };
+    }
+    clearTokens() {
+        this.tokens = null;
+        this.refreshPromise = null;
+    }
+}
+exports.ZetAuthManager = ZetAuthManager;