zet-api 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,561 @@
+/** Auth tokens returned by login and refresh endpoints. */
+interface ZETAuthTokens {
+    accessToken: string;
+    refreshToken: string;
+}
+/** Payload used to authenticate a user. */
+interface ZETLoginRequest {
+    username: string;
+    password: string;
+    revokeOtherTokens?: boolean;
+    fcmToken?: string;
+}
+/** Account details for the currently authenticated user. */
+interface ZETAccount {
+    id: number;
+    uid: string;
+    email: string;
+    firstName: string;
+    lastName: string;
+    ePurseAmount: number;
+    clientId: string | null;
+    language: number;
+    isFullProfileActivationInProgress: boolean;
+    messages: unknown[];
+    processes: unknown | null;
+}
+/** Traffic news item from `/NewsProxyService.Api/api/newsfeed`. */
+interface ZETNewsItem {
+    title: string;
+    description: string;
+    link: string;
+    datePublished: string;
+    type: number;
+    lines: number[];
+    stations: unknown[];
+    validFrom: string;
+    validTo: string;
+}
+/** Wallet top-up/order record. */
+interface ZETOrder {
+    orderId: number;
+    accountId: number;
+    documentContentToken: string;
+    dateTimeCreated: string;
+    caption: string;
+    period: unknown | null;
+    orderNumber: string | null;
+    orderStatus: number;
+    orderType: number;
+    source: number;
+    language: number;
+    amount: number;
+    invoiceNumber: string;
+    installmentNumber: number;
+    paymentType: number;
+    authorizationCode: string;
+    cardName: string;
+    bankName: string;
+    isCorvusCompleted: boolean | null;
+    isCardUpdateNeeded: boolean | null;
+}
+/** Query parameters for order history. */
+interface ZETOrdersParams {
+    completedOnly?: boolean;
+    pageSize?: number;
+    pageNumber?: number;
+}
+/** Zone representation used in multiple responses. */
+interface ZETZoneInfo {
+    value: number;
+    caption: string;
+}
+/**
+ * Ticket validation data.
+ * Fields beyond `id`, `vehicleNumber`, and `wkt` are optional because
+ * some responses include a lighter validation object.
+ */
+interface ZETValidation {
+    id: number;
+    vehicleNumber: string;
+    wkt: unknown | null;
+    precision?: number | null;
+    validationDateTime?: string;
+    validated?: boolean;
+    ticketStations?: unknown[];
+}
+/** Item from paginated ticket purchase history. */
+interface ZETTicketSummary {
+    ticketId: number;
+    created: string;
+    caption: string;
+    vehicleNumber: string;
+    zones: string;
+    mPurseState: number;
+    transactionAmount: number;
+    totalCount: number;
+}
+/** Full ticket model returned by active ticket and purchase endpoints. */
+interface ZETTicket {
+    id: number;
+    ticketType: number;
+    passengers: number;
+    accountId: number;
+    clientId: string | null;
+    caption: string;
+    description: string | null;
+    barcode: string | null;
+    validFrom: string;
+    validTo: string;
+    articleId: number;
+    trafficZone: number;
+    couponId: unknown | null;
+    trafficAreas: unknown[];
+    progress: number;
+    statusType: ZETTicketStatus;
+    currentTime: string;
+    validInZones: ZETZoneInfo[];
+    validations: ZETValidation[];
+    relation: unknown | null;
+    subsidyType: unknown | null;
+    hzStamp: unknown | null;
+}
+/** Ticket status values observed in API responses. */
+declare enum ZETTicketStatus {
+    Pending = 0,
+    Active = 1
+}
+/** Query parameters for paginated ticket history. */
+interface ZETTicketsParams {
+    pageSize?: number;
+    pageNumber?: number;
+}
+/** Query parameters for active/filtered tickets. */
+interface ZETActiveTicketsParams {
+    isControlTicket?: boolean;
+    validOnly?: boolean;
+    includeValidations?: boolean;
+}
+/** Ticket article returned by `/tickets/article`. */
+interface ZETArticle {
+    articleId: number;
+    articleCaption: string;
+    validInZones: ZETZoneInfo[];
+    availableInZones: ZETZoneInfo[];
+    validOnlyInZoneOfAcquisition: boolean;
+    price: number;
+}
+/** Response model for article lookup endpoint. */
+interface ZETArticlesResponse {
+    foundArticles: ZETArticle[];
+    foundInTheVicinityOfStationsIds: unknown | null;
+    extractedZone: ZETZoneInfo;
+}
+/** Query parameters for article lookup endpoint. */
+interface ZETArticlesParams {
+    lat?: number;
+    lng?: number;
+    precision?: number;
+}
+/** Payload used to purchase a ticket. */
+interface ZETBuyTicketRequest {
+    trafficZone: number;
+    ticketType?: number;
+    passengers?: number;
+    articleId: number;
+    vehicleNumber: string;
+    wkt?: string | null;
+    precision?: number | null;
+    ticketStations?: unknown[];
+}
+/** Payload used by `PUT /tickets/ticket` to update vehicle validation. */
+interface ZETChangeVehicleRequest {
+    accountId: number;
+    vehicleNumber: string;
+    precision?: number | null;
+    wkt?: string | null;
+}
+/** Response payload for `PUT /tickets/ticket`. */
+interface ZETChangeVehicleResponse {
+    validatedTickets: ZETTicket[];
+    numberOfValidatedTickets?: number;
+}
+/** Query parameters for opening the mPurse top-up flow. */
+interface ZETPaymentRedirectParams {
+    mPurse?: number;
+}
+/** Parsed Corvus payment form returned by order redirect endpoint. */
+interface ZETPaymentForm {
+    action: string;
+    method: string;
+    inputs: Record<string, string>;
+    html: string;
+}
+/** Minimal top-up payment payload needed by mobile clients. */
+interface ZETTopUpPaymentInfo {
+    url: string;
+    orderNumber: string | null;
+}
+/** Payload used by `OrderService.MVC/Order/Cancel`. */
+interface ZETOrderCancelRequest {
+    orderNumber: string;
+    language?: string;
+}
+/** Public transport route (tram or bus line). */
+interface ZETRoute {
+    id: number;
+    shortName: string;
+    longName: string;
+    routeType: ZETRouteType;
+    departureHeadsign: string;
+    destinationHeadsign: string;
+    normalizedSearchName: string;
+}
+/** Vehicle position embedded in trip data. */
+interface ZETVehiclePosition {
+    id: string;
+    isForDisabledPeople: boolean | null;
+    vehicleTypeId: unknown | null;
+    position: {
+        latitude: number;
+        longitude: number;
+    };
+}
+/** Trip/departure model for a route. */
+interface ZETTrip {
+    id: string;
+    direction: 0 | 1;
+    headsign: string;
+    departureDateTime: string;
+    arrivalDateTime: string;
+    hasLiveTracking: boolean;
+    tripStatus: ZETTripStatus;
+    vehicles: ZETVehiclePosition[];
+    shapeId: string;
+}
+/** Trip status values observed in API responses. */
+declare enum ZETTripStatus {
+    Running = 0,
+    Scheduled = 3
+}
+/** Stop-time row with live arrival state for one stop in a trip. */
+interface ZETStopTime {
+    id: string;
+    stopName: string;
+    stopSequence: number;
+    expectedArrivalDateTime: string;
+    isArrived: boolean;
+    isArrivedPrediction: boolean;
+    stopLat: number;
+    stopLong: number;
+    trip: ZETTrip;
+}
+/** Incoming departures for a specific stop. */
+interface ZETIncomingTrip {
+    tripId: string;
+    routeShortName: string;
+    headsign: string;
+    expectedArrivalDateTime: string;
+    hasLiveTracking: boolean;
+    daysFromToday: number;
+    shapeId: string;
+    vehicles: ZETVehiclePosition[];
+}
+/** Query parameters used by route/trip timetable endpoints. */
+interface ZETRouteTripParams {
+    daysFromToday?: number;
+}
+/** Route type values used across route, stop, and shape models. */
+type ZETRouteType = 0 | 3;
+/** Stop route-headsign helper object from `/gtfs/stops`. */
+interface ZETStopTripHeadsign {
+    routeCode: string;
+    tripHeadsigns: string[];
+}
+/** Stop model from `/TimetableService.Api/api/gtfs/stops`. */
+interface ZETStop {
+    id: string;
+    name: string;
+    routeType: ZETRouteType;
+    trips: ZETStopTripHeadsign[];
+    stopLat: number;
+    stopLong: number;
+    parentStopId: string;
+    normalizedSearchName: string;
+    isForDisabledPeople: boolean;
+    projectNo: string;
+}
+/** One coordinate point in a GTFS shape. */
+interface ZETShapePoint {
+    latitude: number;
+    longitude: number;
+    sequence: number;
+}
+/** Polyline shape model from `/TimetableService.Api/api/gtfs/shapes`. */
+interface ZETShape {
+    id: string;
+    points: ZETShapePoint[];
+    routeType?: ZETRouteType;
+}
+/** Optional controls for fuzzy route search. */
+interface ZETRouteSearchOptions {
+    routeType?: ZETRouteType;
+    limit?: number;
+}
+/** Optional controls for fuzzy stop search. */
+interface ZETStopSearchOptions {
+    routeType?: ZETRouteType;
+    limit?: number;
+}
+
+declare class ZETApiError extends Error {
+    readonly status: number;
+    readonly endpoint: string;
+    constructor(message: string, status: number, endpoint: string);
+}
+declare class ZETAuthError extends ZETApiError {
+    constructor(endpoint: string);
+}
+
+/** Storage adapter used by `ZETClient` for auth tokens. */
+interface ZETTokenStorage {
+    get(key: string): Promise<string | null> | string | null;
+    set(key: string, value: string): Promise<void> | void;
+    delete(key: string): Promise<void> | void;
+}
+/** In-memory token storage. Tokens are lost when the process exits. */
+declare class MemoryStorage implements ZETTokenStorage {
+    private readonly store;
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    delete(key: string): void;
+}
+
+/** App keys required by ticket and order services. */
+interface ZETAppKeys {
+    ticket: string;
+    order: string;
+}
+/** Configuration options for `ZETClient`. */
+interface ZETClientOptions {
+    appKeys: ZETAppKeys;
+    storage?: ZETTokenStorage;
+    onTokenRefresh?: (tokens: ZETAuthTokens) => void;
+    onAuthFailure?: () => void;
+    timeout?: number;
+    baseUrl?: string;
+    cacheTTL?: number;
+}
+/** HTTP client for ZET auth, ticketing, timetable, news, and payment APIs. */
+declare class ZETClient {
+    private readonly baseUrl;
+    private readonly appKeys;
+    private readonly storage;
+    private readonly cacheTTL;
+    private readonly newsCacheTTL;
+    private isRefreshing;
+    private refreshQueue;
+    private readonly opts;
+    private cachedRoutes;
+    private cachedStops;
+    private cachedShapes;
+    private cachedNews;
+    private routesCachedAt;
+    private stopsCachedAt;
+    private shapesCachedAt;
+    private newsCachedAt;
+    private routesLoading;
+    private stopsLoading;
+    private shapesLoading;
+    private newsLoading;
+    private shapeToRouteTypeMapLoading;
+    private shapeToRouteTypeMap;
+    constructor(options: ZETClientOptions);
+    private resolveNewsCacheTTL;
+    private createBaseHeaders;
+    private createHeaders;
+    private buildUrl;
+    private fetchWithTimeout;
+    private readErrorMessage;
+    private toApiError;
+    private sendRequest;
+    private requestJson;
+    private requestText;
+    private saveTokens;
+    private refreshTokens;
+    private resolveRefreshQueue;
+    private rejectRefreshQueue;
+    private handleUnauthorized;
+    private ticketHeaders;
+    private orderHeaders;
+    private isExpired;
+    private fetchRoutesAndCache;
+    private fetchStopsAndCache;
+    private fetchShapesAndCache;
+    private fetchNewsAndCache;
+    private getRoutesCached;
+    private getStopsCached;
+    private getShapesCached;
+    private getNewsCached;
+    private ensureShapeToRouteTypeMap;
+    private invalidateShapeToRouteTypeMap;
+    private extractHtmlAttribute;
+    private parsePaymentForm;
+    /** Logs in and stores returned tokens. */
+    login(credentials: ZETLoginRequest): Promise<ZETAuthTokens>;
+    /** Stores externally obtained access and refresh tokens. */
+    setTokens(tokens: ZETAuthTokens): Promise<void>;
+    /** Clears locally stored tokens. */
+    clearTokens(): Promise<void>;
+    /** Returns currently stored access token or `null`. */
+    getAccessToken(): Promise<string | null>;
+    /** Fetches current account details. */
+    getAccount(): Promise<ZETAccount>;
+    /** Fetches traffic/service news feed with internal cache. */
+    getNewsFeed(): Promise<ZETNewsItem[]>;
+    /** Backward-compatible alias of `getNewsFeed`. */
+    getNewsfeed(): Promise<ZETNewsItem[]>;
+    /** Fetches news filtered by route line id. */
+    getNewsByRoute(routeId: number): Promise<ZETNewsItem[]>;
+    /** Fetches top-up/order history. */
+    getOrders(params?: ZETOrdersParams): Promise<ZETOrder[]>;
+    /**
+     * Opens mPurse top-up redirect and returns raw HTML that auto-submits to CorvusPay.
+     */
+    getTopUpPaymentHtml(params?: ZETPaymentRedirectParams): Promise<string>;
+    /**
+     * Opens mPurse top-up redirect and parses the generated CorvusPay form.
+     * The returned `action` URL is where the user should be redirected.
+     */
+    getTopUpPaymentForm(params?: ZETPaymentRedirectParams): Promise<ZETPaymentForm>;
+    /** Returns only top-up payment URL and order number for cancel flow. */
+    getTopUpPaymentInfo(params?: ZETPaymentRedirectParams): Promise<ZETTopUpPaymentInfo>;
+    /**
+     * Calls `OrderService.MVC/Order/Cancel` with the Corvus order number.
+     * This is the same endpoint the WebView flow calls when payment is canceled.
+     */
+    cancelTopUpPayment(request: ZETOrderCancelRequest): Promise<string>;
+    /** Returns cached routes, optionally filtered by route type. */
+    getRoutes(routeType?: ZETRouteType): Promise<ZETRoute[]>;
+    /** Returns one route by route id using cached routes. */
+    getRouteById(routeId: number): Promise<ZETRoute | null>;
+    /** Fuzzy-search routes by normalized name and short route code. */
+    searchRoutes(query: string, options?: ZETRouteSearchOptions): Promise<ZETRoute[]>;
+    /** Returns cached stops, optionally filtered by route type. */
+    getStops(routeType?: ZETRouteType): Promise<ZETStop[]>;
+    /** Returns one stop by id from cached stops. */
+    getStopById(stopId: string): Promise<ZETStop | null>;
+    /** Fuzzy-search stops by normalized stop name. */
+    searchStops(query: string, options?: ZETStopSearchOptions): Promise<ZETStop[]>;
+    /** Returns cached shapes. */
+    getShapes(): Promise<ZETShape[]>;
+    /** Returns shapes used by trips of the specified route id. */
+    getShapesByRouteId(routeId: number): Promise<ZETShape[]>;
+    /** Fetches paginated ticket purchase history. */
+    getTicketHistory(params?: ZETTicketsParams): Promise<ZETTicketSummary[]>;
+    /** Fetches filtered/active tickets. */
+    getActiveTickets(params?: ZETActiveTicketsParams): Promise<ZETTicket[]>;
+    /**
+     * Fetches ticket articles.
+     * If `lat` and `lng` are provided, zone-specific data is requested.
+     */
+    getArticles(params?: ZETArticlesParams): Promise<ZETArticlesResponse>;
+    /** Purchases a ticket. */
+    buyTicket(request: ZETBuyTicketRequest): Promise<ZETTicket[]>;
+    /**
+     * Updates active ticket validation by changing the vehicle number.
+     * Mirrors `PUT /TicketService.Api/api/v1/open/tickets/ticket` in `zet.txt`.
+     */
+    changeTicketVehicle(request: ZETChangeVehicleRequest): Promise<ZETChangeVehicleResponse>;
+    /** Fetches all trips for one route and relative day offset. */
+    getRouteTrips(routeId: number, params?: ZETRouteTripParams): Promise<ZETTrip[]>;
+    /** Fetches stop times and live state for one trip. */
+    getTripStopTimes(tripId: string, params?: ZETRouteTripParams): Promise<ZETStopTime[]>;
+    /** Fetches upcoming trips for one stop. */
+    getStopIncomingTrips(stopId: string): Promise<ZETIncomingTrip[]>;
+}
+
+/** Vehicle position extracted from the GTFS-RT feed. */
+interface GtfsRtVehicle {
+    vehicleId: string;
+    routeId: string;
+    latitude: number;
+    longitude: number;
+    timestamp: number;
+}
+/** Vehicle plus computed distance and basic type classification. */
+interface NearbyVehicle extends GtfsRtVehicle {
+    distanceMeters: number;
+    vehicleType: 'tram' | 'bus' | 'unknown';
+}
+/**
+ * Fetches and parses the ZET GTFS-RT protobuf feed.
+ *
+ * `gtfs-realtime-bindings` is statically imported and always bundled.
+ */
+declare function fetchGtfsRtVehicles(url?: string, fetchFn?: typeof fetch): Promise<GtfsRtVehicle[]>;
+/** Calculates Haversine distance in meters between two WGS84 coordinates. */
+declare function haversineMeters(lat1: number, lng1: number, lat2: number, lng2: number): number;
+/**
+ * Returns vehicles within `radiusMeters` from user coordinates, sorted by distance.
+ */
+declare function getNearbyVehicles(vehicles: GtfsRtVehicle[], userLat: number, userLng: number, radiusMeters?: number): NearbyVehicle[];
+
+/**
+ * Async generator for paginated ZET endpoints.
+ * The `fetcher` callback must return one page of results for a given page number.
+ */
+declare function paginate<T>(fetcher: (pageNumber: number) => Promise<T[]>, pageSize?: number): AsyncGenerator<T[]>;
+/**
+ * Collects all pages into one array.
+ * Use `paginate` directly if you need streaming behavior.
+ */
+declare function collectAll<T>(fetcher: (pageNumber: number) => Promise<T[]>, pageSize?: number): Promise<T[]>;
+
+/** Returns `true` when a trip is currently running and has live tracking. */
+declare function isTripLive(trip: ZETTrip): boolean;
+/** Returns the first not-yet-arrived stop index, or `-1` if there is none. */
+declare function getCurrentStopIndex(stops: ZETStopTime[]): number;
+/** Returns the last arrived stop, or `null` if no stop is marked as arrived. */
+declare function getLastArrivedStop(stops: ZETStopTime[]): ZETStopTime | null;
+/** Returns the next not-yet-arrived stop, or `null` if all stops are arrived. */
+declare function getNextStop(stops: ZETStopTime[]): ZETStopTime | null;
+/** Returns `true` when the route type is tram (`0`). */
+declare function isTram(route: ZETRoute): boolean;
+/** Returns `true` when the route type is bus (`3`). */
+declare function isBus(route: ZETRoute): boolean;
+/** Normalized trip item returned by `buildTimetable`. */
+interface TimetableEntry {
+    trip: ZETTrip;
+    departureTime: Date;
+    arrivalTime: Date;
+    isPast: boolean;
+    isLive: boolean;
+    isNext: boolean;
+}
+/**
+ * Filters trips by direction, sorts by departure time, and annotates timeline state.
+ */
+declare function buildTimetable(trips: ZETTrip[], direction: 0 | 1): TimetableEntry[];
+/**
+ * Returns a short label for a ticket article caption.
+ * Falls back to the original caption when no known pattern is found.
+ */
+declare function getArticleLabel(article: ZETArticle): string;
+/** Keeps only standard zone 1/2 products and removes funicular-only articles. */
+declare function getStandardArticles(articles: ZETArticle[]): ZETArticle[];
+/** Returns `true` when ticket is active and its validity end is in the future. */
+declare function isTicketActive(ticket: ZETTicket): boolean;
+/** Returns remaining ticket validity in whole seconds. Can be negative if expired. */
+declare function getTicketRemainingSeconds(ticket: ZETTicket): number;
+/** Formats a second count as `M:SS`. */
+declare function formatCountdown(seconds: number): string;
+/**
+ * Normalizes strings for fuzzy matching.
+ * Croatian diacritics are reduced to base ASCII letters.
+ */
+declare function normalizeString(value: string): string;
+/** Returns the validated vehicle number if available. */
+declare function getTicketVehicleNumber(ticket: ZETTicket): string | null;
+
+export { type GtfsRtVehicle, MemoryStorage, type NearbyVehicle, type TimetableEntry, type ZETAccount, type ZETActiveTicketsParams, ZETApiError, type ZETAppKeys, type ZETArticle, type ZETArticlesParams, type ZETArticlesResponse, ZETAuthError, type ZETAuthTokens, type ZETBuyTicketRequest, type ZETChangeVehicleRequest, type ZETChangeVehicleResponse, ZETClient, type ZETClientOptions, type ZETIncomingTrip, type ZETLoginRequest, type ZETNewsItem, type ZETOrder, type ZETOrderCancelRequest, type ZETOrdersParams, type ZETPaymentForm, type ZETPaymentRedirectParams, type ZETRoute, type ZETRouteSearchOptions, type ZETRouteTripParams, type ZETRouteType, type ZETShape, type ZETShapePoint, type ZETStop, type ZETStopSearchOptions, type ZETStopTime, type ZETStopTripHeadsign, type ZETTicket, ZETTicketStatus, type ZETTicketSummary, type ZETTicketsParams, type ZETTokenStorage, type ZETTopUpPaymentInfo, type ZETTrip, ZETTripStatus, type ZETValidation, type ZETVehiclePosition, type ZETZoneInfo, buildTimetable, collectAll, fetchGtfsRtVehicles, formatCountdown, getArticleLabel, getCurrentStopIndex, getLastArrivedStop, getNearbyVehicles, getNextStop, getStandardArticles, getTicketRemainingSeconds, getTicketVehicleNumber, haversineMeters, isBus, isTicketActive, isTram, isTripLive, normalizeString, paginate };