zet-api 0.1.0

package/dist/index.js

@@ -0,0 +1,864 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MemoryStorage: () => MemoryStorage,
+  ZETApiError: () => ZETApiError,
+  ZETAuthError: () => ZETAuthError,
+  ZETClient: () => ZETClient,
+  ZETTicketStatus: () => ZETTicketStatus,
+  ZETTripStatus: () => ZETTripStatus,
+  buildTimetable: () => buildTimetable,
+  collectAll: () => collectAll,
+  fetchGtfsRtVehicles: () => fetchGtfsRtVehicles,
+  formatCountdown: () => formatCountdown,
+  getArticleLabel: () => getArticleLabel,
+  getCurrentStopIndex: () => getCurrentStopIndex,
+  getLastArrivedStop: () => getLastArrivedStop,
+  getNearbyVehicles: () => getNearbyVehicles,
+  getNextStop: () => getNextStop,
+  getStandardArticles: () => getStandardArticles,
+  getTicketRemainingSeconds: () => getTicketRemainingSeconds,
+  getTicketVehicleNumber: () => getTicketVehicleNumber,
+  haversineMeters: () => haversineMeters,
+  isBus: () => isBus,
+  isTicketActive: () => isTicketActive,
+  isTram: () => isTram,
+  isTripLive: () => isTripLive,
+  normalizeString: () => normalizeString,
+  paginate: () => paginate
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types/api.ts
+var ZETTicketStatus = /* @__PURE__ */ ((ZETTicketStatus2) => {
+  ZETTicketStatus2[ZETTicketStatus2["Pending"] = 0] = "Pending";
+  ZETTicketStatus2[ZETTicketStatus2["Active"] = 1] = "Active";
+  return ZETTicketStatus2;
+})(ZETTicketStatus || {});
+var ZETTripStatus = /* @__PURE__ */ ((ZETTripStatus2) => {
+  ZETTripStatus2[ZETTripStatus2["Running"] = 0] = "Running";
+  ZETTripStatus2[ZETTripStatus2["Scheduled"] = 3] = "Scheduled";
+  return ZETTripStatus2;
+})(ZETTripStatus || {});
+
+// src/types/errors.ts
+var ZETApiError = class extends Error {
+  constructor(message, status, endpoint) {
+    super(message);
+    this.status = status;
+    this.endpoint = endpoint;
+    this.name = "ZETApiError";
+  }
+};
+var ZETAuthError = class extends ZETApiError {
+  constructor(endpoint) {
+    super("Authentication failed: token expired or invalid", 401, endpoint);
+    this.name = "ZETAuthError";
+  }
+};
+
+// src/core/constants.ts
+var baseUrl = "https://api.zet.hr";
+var gtfsRtUrl = "https://www.zet.hr/gtfs-rt-protobuf";
+var appUid = "ZET.Mobile";
+var userAgent = "okhttp/4.9.2";
+var tenant = "KingICT_ZET_Public";
+var endpoints = {
+  login: "/AuthService.Api/api/auth/login",
+  refreshTokens: "/AuthService.Api/api/auth/refreshTokens",
+  account: "/AccountService.Api/api/account",
+  newsFeed: "/NewsProxyService.Api/api/newsfeed",
+  orders: "/OrderService.Api/api/v1/open/orders/order",
+  orderRedirect: "/OrderService.MVC/order/redirect",
+  orderCancel: "/OrderService.MVC/Order/Cancel",
+  paginatedTickets: "/TicketService.Api/api/v1/open/tickets/ticket/paginatedTickets",
+  filteredTickets: "/TicketService.Api/api/v1/open/tickets/ticket/filteredTickets",
+  ticket: "/TicketService.Api/api/v1/open/tickets/ticket",
+  articles: "/TicketService.Api/api/v1/open/tickets/article",
+  routes: "/TimetableService.Api/api/gtfs/routes",
+  stops: "/TimetableService.Api/api/gtfs/stops",
+  shapes: "/TimetableService.Api/api/gtfs/shapes",
+  routeTrips: "/TimetableService.Api/api/gtfs/routeTrips",
+  tripStopTimes: "/TimetableService.Api/api/gtfs/tripStopTimes",
+  stopIncomingTrips: "/TimetableService.Api/api/gtfs/stopIncomingTrips"
+};
+
+// src/client/storage.ts
+var MemoryStorage = class {
+  store = /* @__PURE__ */ new Map();
+  get(key) {
+    return this.store.get(key) ?? null;
+  }
+  set(key, value) {
+    this.store.set(key, value);
+  }
+  delete(key) {
+    this.store.delete(key);
+  }
+};
+
+// src/helpers/utils.ts
+function isTripLive(trip) {
+  return trip.tripStatus === 0 /* Running */ && trip.hasLiveTracking;
+}
+function getCurrentStopIndex(stops) {
+  return stops.findIndex((stop) => !stop.isArrived);
+}
+function getLastArrivedStop(stops) {
+  const arrivedStops = stops.filter((stop) => stop.isArrived);
+  return arrivedStops[arrivedStops.length - 1] ?? null;
+}
+function getNextStop(stops) {
+  return stops.find((stop) => !stop.isArrived) ?? null;
+}
+function isTram(route) {
+  return route.routeType === 0;
+}
+function isBus(route) {
+  return route.routeType === 3;
+}
+function buildTimetable(trips, direction) {
+  const now = /* @__PURE__ */ new Date();
+  const filtered = trips.filter((trip) => trip.direction === direction).map((trip) => ({
+    trip,
+    departureTime: new Date(trip.departureDateTime),
+    arrivalTime: new Date(trip.arrivalDateTime)
+  })).sort((a, b) => a.departureTime.getTime() - b.departureTime.getTime());
+  const nextIndex = filtered.findIndex((entry) => entry.departureTime > now || entry.trip.tripStatus === 0 /* Running */);
+  return filtered.map((entry, index) => ({
+    ...entry,
+    isPast: entry.departureTime < now && entry.trip.tripStatus !== 0 /* Running */,
+    isLive: isTripLive(entry.trip),
+    isNext: index === nextIndex
+  }));
+}
+function getArticleLabel(article) {
+  const caption = article.articleCaption.toLowerCase();
+  if (caption.includes("30")) return "30 min";
+  if (caption.includes("60")) return "60 min";
+  if (caption.includes("90")) return "90 min";
+  if (caption.includes("180")) return "180 min";
+  if (caption.includes("dnevna") || caption.includes("daily")) return "Dnevna";
+  if (caption.includes("uspinja") || caption.includes("funicular")) return "Uspinja\u010Da";
+  if (article.availableInZones.length > 0 && article.availableInZones.every((zone) => zone.value === 4)) return "Uspinja\u010Da";
+  return article.articleCaption;
+}
+function getStandardArticles(articles) {
+  return articles.filter((article) => article.availableInZones.some((zone) => zone.value === 1 || zone.value === 2));
+}
+function isTicketActive(ticket) {
+  return ticket.statusType === 1 /* Active */ && new Date(ticket.validTo) > /* @__PURE__ */ new Date();
+}
+function getTicketRemainingSeconds(ticket) {
+  return Math.floor((new Date(ticket.validTo).getTime() - Date.now()) / 1e3);
+}
+function formatCountdown(seconds) {
+  const safeSeconds = Math.max(0, seconds);
+  const minutes = Math.floor(safeSeconds / 60);
+  const secondsPart = safeSeconds % 60;
+  return `${minutes}:${String(secondsPart).padStart(2, "0")}`;
+}
+function normalizeString(value) {
+  return value.toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "").replace(/đ/g, "d").replace(/č/g, "c").replace(/ć/g, "c").replace(/š/g, "s").replace(/ž/g, "z").trim();
+}
+function getTicketVehicleNumber(ticket) {
+  return ticket.validations?.[0]?.vehicleNumber ?? null;
+}
+
+// src/client/client.ts
+var ZETClient = class {
+  baseUrl;
+  appKeys;
+  storage;
+  cacheTTL;
+  newsCacheTTL;
+  isRefreshing = false;
+  refreshQueue = [];
+  opts;
+  cachedRoutes = null;
+  cachedStops = null;
+  cachedShapes = null;
+  cachedNews = null;
+  routesCachedAt = null;
+  stopsCachedAt = null;
+  shapesCachedAt = null;
+  newsCachedAt = null;
+  routesLoading = null;
+  stopsLoading = null;
+  shapesLoading = null;
+  newsLoading = null;
+  shapeToRouteTypeMapLoading = null;
+  shapeToRouteTypeMap = /* @__PURE__ */ new Map();
+  constructor(options) {
+    if (!options?.appKeys?.ticket || !options.appKeys.order) throw new Error("appKeys.ticket and appKeys.order are required");
+    if ((options.cacheTTL ?? -1) < -1) throw new Error("cacheTTL must be -1 (no expiry) or a non-negative number in milliseconds");
+    this.baseUrl = options.baseUrl ?? baseUrl;
+    this.appKeys = options.appKeys;
+    this.storage = options.storage ?? new MemoryStorage();
+    this.cacheTTL = options.cacheTTL ?? -1;
+    this.newsCacheTTL = this.resolveNewsCacheTTL(this.cacheTTL);
+    this.opts = {
+      onTokenRefresh: options.onTokenRefresh ?? (() => {
+      }),
+      onAuthFailure: options.onAuthFailure ?? (() => {
+      }),
+      timeout: options.timeout ?? 1e4
+    };
+  }
+  resolveNewsCacheTTL(cacheTtl) {
+    if (cacheTtl === 0) return 0;
+    if (cacheTtl < 0) return 5 * 60 * 1e3;
+    return Math.min(cacheTtl, 5 * 60 * 1e3);
+  }
+  createBaseHeaders() {
+    const headers = new Headers();
+    headers.set("Accept", "application/json, text/plain, */*");
+    headers.set("appuid", appUid);
+    headers.set("x-tenant", tenant);
+    headers.set("language", "hr");
+    headers.set("User-Agent", userAgent);
+    return headers;
+  }
+  async createHeaders(extraHeaders, includeAuth = true) {
+    const headers = this.createBaseHeaders();
+    if (extraHeaders) for (const [key, value] of Object.entries(extraHeaders)) headers.set(key, value);
+    if (includeAuth) {
+      const accessToken = await this.storage.get("accessToken");
+      if (accessToken) headers.set("Authorization", `Bearer ${accessToken}`);
+    }
+    return headers;
+  }
+  buildUrl(endpoint, query) {
+    const normalizedBaseUrl = this.baseUrl.endsWith("/") ? this.baseUrl : `${this.baseUrl}/`;
+    const url = new URL(endpoint, normalizedBaseUrl);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) if (value !== void 0 && value !== null) url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+  }
+  async fetchWithTimeout(url, init) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.opts.timeout);
+    try {
+      return await fetch(url, {
+        ...init,
+        signal: controller.signal
+      });
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") throw new ZETApiError(`Request timed out after ${this.opts.timeout}ms`, 0, url);
+      throw new ZETApiError(error instanceof Error ? error.message : "Network request failed", 0, url);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  async readErrorMessage(response) {
+    const contentType = response.headers.get("content-type")?.toLowerCase() ?? "";
+    try {
+      if (contentType.includes("application/json")) {
+        const data = await response.json();
+        if (typeof data === "object" && data !== null && "message" in data) {
+          const maybeMessage = data.message;
+          if (typeof maybeMessage === "string" && maybeMessage.length > 0) return maybeMessage;
+        }
+        const serialized = JSON.stringify(data);
+        if (serialized.length > 0) return serialized;
+      }
+      const text = await response.text();
+      if (text.length > 0) return text;
+    } catch {
+    }
+    return `Request failed with status ${response.status}`;
+  }
+  async toApiError(response, endpoint) {
+    const message = await this.readErrorMessage(response);
+    return new ZETApiError(message, response.status, endpoint);
+  }
+  async sendRequest(endpoint, options = {}, allowAuthRetry = true) {
+    const url = this.buildUrl(endpoint, options.query);
+    const includeAuth = options.auth !== false;
+    const headers = await this.createHeaders(options.headers, includeAuth);
+    const method = options.method ?? "GET";
+    let body = options.body;
+    if (options.jsonBody !== void 0) {
+      headers.set("Content-Type", "application/json");
+      body = JSON.stringify(options.jsonBody);
+    }
+    const response = await this.fetchWithTimeout(url, {
+      method,
+      headers,
+      body
+    });
+    if (response.status === 401 && includeAuth && allowAuthRetry) {
+      const refreshedAccessToken = await this.handleUnauthorized(endpoint);
+      const retryHeaders = await this.createHeaders(options.headers, includeAuth);
+      retryHeaders.set("Authorization", `Bearer ${refreshedAccessToken}`);
+      if (options.jsonBody !== void 0) retryHeaders.set("Content-Type", "application/json");
+      const retryResponse = await this.fetchWithTimeout(url, {
+        method,
+        headers: retryHeaders,
+        body
+      });
+      if (!retryResponse.ok) throw await this.toApiError(retryResponse, endpoint);
+      return retryResponse;
+    }
+    if (!response.ok) throw await this.toApiError(response, endpoint);
+    return response;
+  }
+  async requestJson(endpoint, options = {}, allowAuthRetry = true) {
+    const response = await this.sendRequest(endpoint, options, allowAuthRetry);
+    return await response.json();
+  }
+  async requestText(endpoint, options = {}, allowAuthRetry = true) {
+    const response = await this.sendRequest(endpoint, options, allowAuthRetry);
+    return await response.text();
+  }
+  async saveTokens(tokens) {
+    await this.storage.set("accessToken", tokens.accessToken);
+    await this.storage.set("refreshToken", tokens.refreshToken);
+  }
+  async refreshTokens(refreshToken) {
+    return await this.requestJson(endpoints.refreshTokens, {
+      method: "POST",
+      jsonBody: { refreshToken }
+    }, false);
+  }
+  resolveRefreshQueue(token) {
+    for (const waiter of this.refreshQueue) waiter.resolve(token);
+    this.refreshQueue = [];
+  }
+  rejectRefreshQueue(error) {
+    for (const waiter of this.refreshQueue) waiter.reject(error);
+    this.refreshQueue = [];
+  }
+  async handleUnauthorized(endpoint) {
+    if (this.isRefreshing) return await new Promise((resolve, reject) => this.refreshQueue.push({ resolve, reject }));
+    this.isRefreshing = true;
+    try {
+      const refreshToken = await this.storage.get("refreshToken");
+      if (!refreshToken) throw new ZETAuthError(endpoint);
+      const tokens = await this.refreshTokens(refreshToken);
+      await this.saveTokens(tokens);
+      this.opts.onTokenRefresh(tokens);
+      this.resolveRefreshQueue(tokens.accessToken);
+      return tokens.accessToken;
+    } catch {
+      const authError = new ZETAuthError(endpoint);
+      this.rejectRefreshQueue(authError);
+      this.opts.onAuthFailure();
+      throw authError;
+    } finally {
+      this.isRefreshing = false;
+    }
+  }
+  ticketHeaders() {
+    return { appkey: this.appKeys.ticket };
+  }
+  orderHeaders() {
+    return { appkey: this.appKeys.order };
+  }
+  isExpired(cachedAt, ttl) {
+    if (ttl === 0) return true;
+    if (ttl < 0) return false;
+    if (cachedAt === null) return true;
+    return Date.now() - cachedAt > ttl;
+  }
+  async fetchRoutesAndCache() {
+    const routes = await this.requestJson(endpoints.routes);
+    this.cachedRoutes = routes;
+    this.routesCachedAt = Date.now();
+    this.invalidateShapeToRouteTypeMap();
+    return routes;
+  }
+  async fetchStopsAndCache() {
+    const stops = await this.requestJson(endpoints.stops);
+    this.cachedStops = stops;
+    this.stopsCachedAt = Date.now();
+    return stops;
+  }
+  async fetchShapesAndCache() {
+    const shapesResponse = await this.requestJson(endpoints.shapes);
+    const shapes = Object.entries(shapesResponse).map(([id, points]) => ({
+      id,
+      points,
+      routeType: this.shapeToRouteTypeMap.get(id)
+    }));
+    this.cachedShapes = shapes;
+    this.shapesCachedAt = Date.now();
+    this.invalidateShapeToRouteTypeMap();
+    return shapes;
+  }
+  async fetchNewsAndCache() {
+    const news = await this.requestJson(endpoints.newsFeed);
+    this.cachedNews = news;
+    this.newsCachedAt = Date.now();
+    return news;
+  }
+  async getRoutesCached() {
+    const needsRefresh = !this.cachedRoutes || this.isExpired(this.routesCachedAt, this.cacheTTL);
+    if (!needsRefresh && this.cachedRoutes) return this.cachedRoutes;
+    if (!this.routesLoading) this.routesLoading = this.fetchRoutesAndCache().finally(() => {
+      this.routesLoading = null;
+    });
+    return await this.routesLoading;
+  }
+  async getStopsCached() {
+    const needsRefresh = !this.cachedStops || this.isExpired(this.stopsCachedAt, this.cacheTTL);
+    if (!needsRefresh && this.cachedStops) return this.cachedStops;
+    if (!this.stopsLoading) this.stopsLoading = this.fetchStopsAndCache().finally(() => {
+      this.stopsLoading = null;
+    });
+    return await this.stopsLoading;
+  }
+  async getShapesCached() {
+    const needsRefresh = !this.cachedShapes || this.isExpired(this.shapesCachedAt, this.cacheTTL);
+    if (!needsRefresh && this.cachedShapes) return this.cachedShapes;
+    if (!this.shapesLoading) this.shapesLoading = this.fetchShapesAndCache().finally(() => {
+      this.shapesLoading = null;
+    });
+    return await this.shapesLoading;
+  }
+  async getNewsCached() {
+    const needsRefresh = !this.cachedNews || this.isExpired(this.newsCachedAt, this.newsCacheTTL);
+    if (!needsRefresh && this.cachedNews) return this.cachedNews;
+    if (!this.newsLoading) this.newsLoading = this.fetchNewsAndCache().finally(() => {
+      this.newsLoading = null;
+    });
+    return await this.newsLoading;
+  }
+  async ensureShapeToRouteTypeMap() {
+    if (this.shapeToRouteTypeMap.size > 0) return;
+    if (this.shapeToRouteTypeMapLoading) return await this.shapeToRouteTypeMapLoading;
+    this.shapeToRouteTypeMapLoading = (async () => {
+      const [routes, shapes] = await Promise.all([
+        this.getRoutes(),
+        this.getShapesCached()
+      ]);
+      const shapeIds = new Set(shapes.map((shape) => shape.id));
+      const nextMap = /* @__PURE__ */ new Map();
+      for (const route of routes) {
+        const trips = await this.getRouteTrips(route.id, { daysFromToday: 0 });
+        for (const trip of trips) {
+          if (!nextMap.has(trip.shapeId) && shapeIds.has(trip.shapeId)) nextMap.set(trip.shapeId, route.routeType);
+        }
+      }
+      this.shapeToRouteTypeMap = nextMap;
+      if (this.cachedShapes) this.cachedShapes = this.cachedShapes.map((shape) => ({
+        ...shape,
+        routeType: nextMap.get(shape.id)
+      }));
+    })();
+    try {
+      await this.shapeToRouteTypeMapLoading;
+    } finally {
+      this.shapeToRouteTypeMapLoading = null;
+    }
+  }
+  invalidateShapeToRouteTypeMap() {
+    this.shapeToRouteTypeMap.clear();
+    if (this.cachedShapes) this.cachedShapes = this.cachedShapes.map((shape) => ({
+      ...shape,
+      routeType: void 0
+    }));
+  }
+  extractHtmlAttribute(tag, attribute) {
+    const regex = new RegExp(`${attribute}\\s*=\\s*"([^"]*)"`, "i");
+    const match = tag.match(regex);
+    return match?.[1] ?? null;
+  }
+  parsePaymentForm(html) {
+    const formTag = html.match(/<form\b[^>]*>/i)?.[0];
+    if (!formTag) throw new Error("Unable to find payment form in redirect HTML");
+    const action = this.extractHtmlAttribute(formTag, "action") ?? "";
+    const method = this.extractHtmlAttribute(formTag, "method") ?? "post";
+    if (!action) throw new Error("Unable to parse payment form action URL");
+    const inputs = {};
+    const inputTags = html.match(/<input\b[^>]*>/gi) ?? [];
+    for (const inputTag of inputTags) {
+      const name = this.extractHtmlAttribute(inputTag, "name");
+      if (!name) continue;
+      inputs[name] = this.extractHtmlAttribute(inputTag, "value") ?? "";
+    }
+    return {
+      action,
+      method,
+      inputs,
+      html
+    };
+  }
+  /** Logs in and stores returned tokens. */
+  async login(credentials) {
+    const tokens = await this.requestJson(endpoints.login, {
+      method: "POST",
+      jsonBody: {
+        username: credentials.username,
+        password: credentials.password,
+        revokeOtherTokens: credentials.revokeOtherTokens ?? false,
+        fcmToken: credentials.fcmToken ?? "zet-api-client"
+      },
+      auth: false
+    });
+    await this.saveTokens(tokens);
+    return tokens;
+  }
+  /** Stores externally obtained access and refresh tokens. */
+  async setTokens(tokens) {
+    await this.saveTokens(tokens);
+  }
+  /** Clears locally stored tokens. */
+  async clearTokens() {
+    await this.storage.delete("accessToken");
+    await this.storage.delete("refreshToken");
+  }
+  /** Returns currently stored access token or `null`. */
+  async getAccessToken() {
+    return await this.storage.get("accessToken");
+  }
+  /** Fetches current account details. */
+  async getAccount() {
+    return await this.requestJson(endpoints.account);
+  }
+  /** Fetches traffic/service news feed with internal cache. */
+  async getNewsFeed() {
+    return await this.getNewsCached();
+  }
+  /** Backward-compatible alias of `getNewsFeed`. */
+  async getNewsfeed() {
+    return await this.getNewsFeed();
+  }
+  /** Fetches news filtered by route line id. */
+  async getNewsByRoute(routeId) {
+    const news = await this.getNewsCached();
+    return news.filter((item) => item.lines.includes(routeId));
+  }
+  /** Fetches top-up/order history. */
+  async getOrders(params = {}) {
+    return await this.requestJson(endpoints.orders, {
+      headers: this.orderHeaders(),
+      query: {
+        completedOnly: params.completedOnly ?? true,
+        PageSize: params.pageSize ?? 20,
+        PageNumber: params.pageNumber ?? 1
+      }
+    });
+  }
+  /**
+   * Opens mPurse top-up redirect and returns raw HTML that auto-submits to CorvusPay.
+   */
+  async getTopUpPaymentHtml(params = {}) {
+    return await this.requestText(endpoints.orderRedirect, {
+      headers: {
+        ...this.orderHeaders(),
+        Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        language: "0"
+      },
+      query: {
+        mPurse: params.mPurse ?? 1
+      }
+    });
+  }
+  /**
+   * Opens mPurse top-up redirect and parses the generated CorvusPay form.
+   * The returned `action` URL is where the user should be redirected.
+   */
+  async getTopUpPaymentForm(params = {}) {
+    const html = await this.getTopUpPaymentHtml(params);
+    return this.parsePaymentForm(html);
+  }
+  /** Returns only top-up payment URL and order number for cancel flow. */
+  async getTopUpPaymentInfo(params = {}) {
+    const form = await this.getTopUpPaymentForm(params);
+    return {
+      url: form.action,
+      orderNumber: form.inputs.order_number ?? null
+    };
+  }
+  /**
+   * Calls `OrderService.MVC/Order/Cancel` with the Corvus order number.
+   * This is the same endpoint the WebView flow calls when payment is canceled.
+   */
+  async cancelTopUpPayment(request) {
+    const formData = new URLSearchParams();
+    formData.set("order_number", request.orderNumber);
+    formData.set("language", request.language ?? "hr");
+    return await this.requestText(endpoints.orderCancel, {
+      method: "POST",
+      headers: {
+        Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        "Content-Type": "application/x-www-form-urlencoded"
+      },
+      body: formData.toString()
+    });
+  }
+  /** Returns cached routes, optionally filtered by route type. */
+  async getRoutes(routeType) {
+    const routes = await this.getRoutesCached();
+    if (routeType === void 0) return routes;
+    return routes.filter((route) => route.routeType === routeType);
+  }
+  /** Returns one route by route id using cached routes. */
+  async getRouteById(routeId) {
+    const routes = await this.getRoutesCached();
+    return routes.find((route) => route.id === routeId) ?? null;
+  }
+  /** Fuzzy-search routes by normalized name and short route code. */
+  async searchRoutes(query, options = {}) {
+    const normalizedQuery = normalizeString(query);
+    const limit = Math.max(1, options.limit ?? 10);
+    const routes = await this.getRoutes(options.routeType);
+    return routes.filter((route) => {
+      const normalizedName = normalizeString(route.normalizedSearchName);
+      return normalizedName.includes(normalizedQuery) || route.shortName.toLowerCase().includes(normalizedQuery);
+    }).slice(0, limit);
+  }
+  /** Returns cached stops, optionally filtered by route type. */
+  async getStops(routeType) {
+    const stops = await this.getStopsCached();
+    if (routeType === void 0) return stops;
+    return stops.filter((stop) => stop.routeType === routeType);
+  }
+  /** Returns one stop by id from cached stops. */
+  async getStopById(stopId) {
+    const stops = await this.getStopsCached();
+    return stops.find((stop) => stop.id === stopId) ?? null;
+  }
+  /** Fuzzy-search stops by normalized stop name. */
+  async searchStops(query, options = {}) {
+    const normalizedQuery = normalizeString(query);
+    const limit = Math.max(1, options.limit ?? 10);
+    const stops = await this.getStops(options.routeType);
+    return stops.filter((stop) => normalizeString(stop.normalizedSearchName).includes(normalizedQuery)).slice(0, limit);
+  }
+  /** Returns cached shapes. */
+  async getShapes() {
+    const shapes = await this.getShapesCached();
+    await this.ensureShapeToRouteTypeMap();
+    return this.cachedShapes ?? shapes;
+  }
+  /** Returns shapes used by trips of the specified route id. */
+  async getShapesByRouteId(routeId) {
+    const trips = await this.getRouteTrips(routeId, { daysFromToday: 0 });
+    const shapeIds = new Set(trips.map((trip) => trip.shapeId));
+    const shapes = await this.getShapes();
+    return shapes.filter((shape) => shapeIds.has(shape.id));
+  }
+  /** Fetches paginated ticket purchase history. */
+  async getTicketHistory(params = {}) {
+    return await this.requestJson(endpoints.paginatedTickets, {
+      headers: this.ticketHeaders(),
+      query: {
+        PageSize: params.pageSize ?? 20,
+        PageNumber: params.pageNumber ?? 1
+      }
+    });
+  }
+  /** Fetches filtered/active tickets. */
+  async getActiveTickets(params = {}) {
+    return await this.requestJson(endpoints.filteredTickets, {
+      headers: this.ticketHeaders(),
+      query: {
+        isControlTicket: params.isControlTicket ?? true,
+        validOnly: params.validOnly ?? true,
+        includeValidations: params.includeValidations ?? true
+      }
+    });
+  }
+  /**
+   * Fetches ticket articles.
+   * If `lat` and `lng` are provided, zone-specific data is requested.
+   */
+  async getArticles(params = {}) {
+    const query = params.lat !== void 0 && params.lng !== void 0 ? {
+      precision: params.precision ?? 5,
+      wkt: `${params.lat},${params.lng}`
+    } : void 0;
+    return await this.requestJson(endpoints.articles, {
+      headers: this.ticketHeaders(),
+      query
+    });
+  }
+  /** Purchases a ticket. */
+  async buyTicket(request) {
+    return await this.requestJson(endpoints.ticket, {
+      method: "POST",
+      headers: this.ticketHeaders(),
+      jsonBody: {
+        trafficZone: request.trafficZone,
+        ticketType: request.ticketType ?? 2,
+        passengers: request.passengers ?? 1,
+        articleId: request.articleId,
+        vehicleNumber: request.vehicleNumber,
+        wkt: request.wkt ?? null,
+        precision: request.precision ?? null,
+        ticketStations: request.ticketStations ?? []
+      }
+    });
+  }
+  /**
+   * Updates active ticket validation by changing the vehicle number.
+   * Mirrors `PUT /TicketService.Api/api/v1/open/tickets/ticket` in `zet.txt`.
+   */
+  async changeTicketVehicle(request) {
+    return await this.requestJson(endpoints.ticket, {
+      method: "PUT",
+      headers: this.ticketHeaders(),
+      jsonBody: {
+        accountId: request.accountId,
+        vehicleNumber: request.vehicleNumber,
+        precision: request.precision ?? null,
+        wkt: request.wkt ?? null
+      }
+    });
+  }
+  /** Fetches all trips for one route and relative day offset. */
+  async getRouteTrips(routeId, params = {}) {
+    return await this.requestJson(endpoints.routeTrips, {
+      query: {
+        routeId,
+        daysFromToday: params.daysFromToday ?? 0
+      }
+    });
+  }
+  /** Fetches stop times and live state for one trip. */
+  async getTripStopTimes(tripId, params = {}) {
+    return await this.requestJson(endpoints.tripStopTimes, {
+      query: {
+        tripId,
+        daysFromToday: params.daysFromToday ?? 0
+      }
+    });
+  }
+  /** Fetches upcoming trips for one stop. */
+  async getStopIncomingTrips(stopId) {
+    return await this.requestJson(endpoints.stopIncomingTrips, {
+      query: {
+        stopId,
+        isMapView: false
+      }
+    });
+  }
+};
+
+// src/helpers/gtfs.ts
+var import_gtfs_realtime_bindings = __toESM(require("gtfs-realtime-bindings"));
+async function fetchGtfsRtVehicles(url = gtfsRtUrl, fetchFn = fetch) {
+  const transitRealtime = import_gtfs_realtime_bindings.default.transit_realtime ?? import_gtfs_realtime_bindings.default.default?.transit_realtime;
+  if (!transitRealtime?.FeedMessage) throw new Error("[zet-api] Unable to initialize gtfs-realtime-bindings FeedMessage parser");
+  const response = await fetchFn(url);
+  if (!response.ok) throw new Error(`GTFS-RT fetch failed: ${response.status}`);
+  const buffer = await response.arrayBuffer();
+  const decoded = transitRealtime.FeedMessage.decode(new Uint8Array(buffer));
+  const feed = transitRealtime.FeedMessage.toObject(decoded, {
+    enums: String,
+    longs: Number,
+    bytes: String,
+    defaults: false,
+    arrays: true,
+    objects: true,
+    oneofs: true
+  });
+  const entityMap = /* @__PURE__ */ new Map();
+  for (const entity of feed.entity ?? []) {
+    const typedEntity = entity;
+    const baseId = String(typedEntity.id).split("_")[0] ?? "";
+    const existing = entityMap.get(baseId) ?? {};
+    entityMap.set(baseId, {
+      vehicle: typedEntity.vehicle ?? existing.vehicle
+    });
+  }
+  const vehicles = [];
+  for (const [baseId, entity] of entityMap) {
+    const vehicle = entity.vehicle;
+    if (vehicle?.position && vehicle.trip) vehicles.push({ vehicleId: vehicle.vehicle?.id ?? baseId, routeId: vehicle.trip.routeId ?? "", latitude: vehicle.position.latitude, longitude: vehicle.position.longitude, timestamp: vehicle.timestamp ?? 0 });
+  }
+  return vehicles;
+}
+function haversineMeters(lat1, lng1, lat2, lng2) {
+  const earthRadiusMeters = 6371e3;
+  const phi1 = lat1 * Math.PI / 180;
+  const phi2 = lat2 * Math.PI / 180;
+  const deltaPhi = (lat2 - lat1) * Math.PI / 180;
+  const deltaLambda = (lng2 - lng1) * Math.PI / 180;
+  const a = Math.sin(deltaPhi / 2) ** 2 + Math.cos(phi1) * Math.cos(phi2) * Math.sin(deltaLambda / 2) ** 2;
+  return earthRadiusMeters * 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a));
+}
+function getNearbyVehicles(vehicles, userLat, userLng, radiusMeters = 150) {
+  return vehicles.map((vehicle) => ({
+    ...vehicle,
+    distanceMeters: haversineMeters(userLat, userLng, vehicle.latitude, vehicle.longitude),
+    vehicleType: vehicle.vehicleId.startsWith("T") ? "tram" : vehicle.vehicleId.startsWith("B") ? "bus" : "unknown"
+  })).filter((vehicle) => vehicle.distanceMeters <= radiusMeters).sort((a, b) => a.distanceMeters - b.distanceMeters);
+}
+
+// src/helpers/pagination.ts
+async function* paginate(fetcher, pageSize = 20) {
+  let page = 1;
+  while (true) {
+    const results = await fetcher(page);
+    if (results.length === 0) break;
+    yield results;
+    if (results.length < pageSize) break;
+    page++;
+  }
+}
+async function collectAll(fetcher, pageSize = 20) {
+  const all = [];
+  for await (const page of paginate(fetcher, pageSize)) all.push(...page);
+  return all;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MemoryStorage,
+  ZETApiError,
+  ZETAuthError,
+  ZETClient,
+  ZETTicketStatus,
+  ZETTripStatus,
+  buildTimetable,
+  collectAll,
+  fetchGtfsRtVehicles,
+  formatCountdown,
+  getArticleLabel,
+  getCurrentStopIndex,
+  getLastArrivedStop,
+  getNearbyVehicles,
+  getNextStop,
+  getStandardArticles,
+  getTicketRemainingSeconds,
+  getTicketVehicleNumber,
+  haversineMeters,
+  isBus,
+  isTicketActive,
+  isTram,
+  isTripLive,
+  normalizeString,
+  paginate
+});