zet-api 0.1.0

package/README.md

@@ -0,0 +1,211 @@
+# zet-api
+
+Unofficial TypeScript client for the [ZET](https://www.zet.hr) (Zagreb Electric Tram) API.
+
+## Install
+
+```bash
+npm install zet-api
+yarn add zet-api
+```
+
+## Quick Start
+
+```ts
+import { ZETClient } from "zet-api";
+
+const zet = new ZETClient({
+  appKeys: {
+    ticket: "YOUR_TICKET_APP_KEY",
+    order: "YOUR_ORDER_APP_KEY",
+  },
+});
+
+await zet.login({
+  username: "your@email.com",
+  password: "your-password",
+});
+
+const account = await zet.getAccount();
+console.log(account.ePurseAmount);
+```
+
+## Expo Token Storage Example
+
+```ts
+import * as SecureStore from "expo-secure-store";
+import { ZETClient } from "zet-api";
+
+const zet = new ZETClient({
+  appKeys: {
+    ticket: "YOUR_TICKET_APP_KEY",
+    order: "YOUR_ORDER_APP_KEY",
+  },
+  storage: {
+    get: (key) => SecureStore.getItemAsync(key),
+    set: (key, value) => SecureStore.setItemAsync(key, value),
+    delete: (key) => SecureStore.deleteItemAsync(key),
+  },
+  onTokenRefresh: (tokens) => {
+    console.log("Refreshed", tokens.accessToken);
+  },
+  onAuthFailure: () => {
+    console.log("Session expired");
+  },
+  cacheTTL: -1,
+});
+```
+
+## Constructor Options
+
+```ts
+type ZETClientOptions = {
+  appKeys: {
+    ticket: string;
+    order: string;
+  };
+  storage?: ZETTokenStorage;
+  onTokenRefresh?: (tokens: ZETAuthTokens) => void;
+  onAuthFailure?: () => void;
+  timeout?: number;
+  baseUrl?: string;
+  cacheTTL?: number; // -1: never expire, 0: always refetch
+};
+```
+
+## API Usage
+
+### Auth
+
+```ts
+await zet.login({ username, password });
+await zet.setTokens({ accessToken, refreshToken });
+await zet.clearTokens();
+const token = await zet.getAccessToken();
+```
+
+### Account
+
+```ts
+const account = await zet.getAccount();
+```
+
+### Routes, Stops, Search
+
+```ts
+const routes = await zet.getRoutes();
+const tramRoutes = await zet.getRoutes(0);
+const route = await zet.getRouteById(1);
+const foundRoutes = await zet.searchRoutes("savski", { limit: 10 });
+
+const stops = await zet.getStops();
+const stop = await zet.getStopById("1234");
+const foundStops = await zet.searchStops("glavni", { routeType: 0, limit: 10 });
+```
+
+### Shapes
+
+```ts
+const shapes = await zet.getShapes();
+const routeShapes = await zet.getShapesByRouteId(1);
+```
+
+### Timetable
+
+```ts
+const trips = await zet.getRouteTrips(1, { daysFromToday: 0 });
+const stopTimes = await zet.getTripStopTimes(trips[0].id, { daysFromToday: 0 });
+const incoming = await zet.getStopIncomingTrips("1234");
+```
+
+### News
+
+```ts
+const news = await zet.getNewsFeed();
+const newsAlias = await zet.getNewsfeed();
+const lineNews = await zet.getNewsByRoute(6);
+```
+
+### Tickets
+
+```ts
+const history = await zet.getTicketHistory({ pageSize: 20, pageNumber: 1 });
+const active = await zet.getActiveTickets({ validOnly: true });
+const articles = await zet.getArticles({ lat: 45.815, lng: 15.982 });
+
+const bought = await zet.buyTicket({
+  trafficZone: 1,
+  articleId: 703,
+  vehicleNumber: "T2113",
+});
+
+const changed = await zet.changeTicketVehicle({
+  accountId: 12345,
+  vehicleNumber: "T2217",
+});
+```
+
+### Orders and Payment Flow
+
+```ts
+const orders = await zet.getOrders({
+  completedOnly: true,
+  pageSize: 20,
+  pageNumber: 1,
+});
+
+const payment = await zet.getTopUpPaymentInfo({ mPurse: 1 });
+// payment.url -> Corvus URL
+// payment.orderNumber -> use for cancel
+
+const cancelHtml = await zet.cancelTopUpPayment({
+  orderNumber: payment.orderNumber ?? "",
+  language: "hr",
+});
+```
+
+### GTFS-RT
+
+```ts
+import { fetchGtfsRtVehicles, getNearbyVehicles } from "zet-api";
+
+const vehicles = await fetchGtfsRtVehicles();
+const nearby = getNearbyVehicles(vehicles, 45.81, 15.98, 500);
+```
+
+## Auth Behavior
+
+- Attaches `Authorization: Bearer <token>` when token exists
+- On `401`, refreshes token once and retries request
+- Queues concurrent requests while refresh is in progress
+- Calls `onAuthFailure()` and throws `ZETAuthError` if refresh fails
+
+## Cache Behavior
+
+- Internal/private in-memory cache
+- No manual refresh/clear required
+- `routes`, `stops`, `shapes` use `cacheTTL`
+- `news` refreshes more frequently with an internal shorter TTL
+- In-flight dedupe prevents duplicate concurrent fetches for same resource
+
+## Error Handling
+
+```ts
+import { ZETApiError, ZETAuthError } from "zet-api";
+
+try {
+  await zet.getAccount();
+} catch (error) {
+  if (error instanceof ZETAuthError) {
+    console.log("Authentication failed!");
+  } else if (error instanceof ZETApiError) {
+    console.log(error.status, error.endpoint);
+  }
+}
+```
+
+## Disclaimer & License
+
+Unofficial client reverse-engineered from observed app traffic. Use responsibly.
+
+This project is licensed under the GNU General Public License v3.0. See [LICENSE](./LICENSE) for details.