@tmlmobilidade/external 20260604.9.7

package/dist/clients/ccfl/index.d.ts

@@ -0,0 +1,15 @@
+import { type GtfsRtFeedMessage } from '@tmlmobilidade/types';
+export declare const CcflClient: Readonly<{
+    /**
+     * Fetches GTFS-RT Vehicle Positions feed from the CCFL API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Vehicle Positions feed message.
+     */
+    vehiclePositions: () => Promise<GtfsRtFeedMessage>;
+    /**
+     * Fetches GTFS-RT Schedule feed from the CCFL API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Schedule feed message.
+     */
+    schedule: () => Promise<Buffer>;
+}>;

package/dist/clients/ccfl/index.js

@@ -0,0 +1,41 @@
+/* * */
+import { decodeGtfsRtFeed } from '@tmlmobilidade/gtfs-rt';
+/* * */
+const BASE_URL = process.env.CCFL_API_URL;
+async function fetcher(endpoint) {
+    if (!BASE_URL) {
+        throw new Error('Missing CCFL_API_URL environment variable.');
+    }
+    const response = await fetch(`${BASE_URL}${endpoint}`);
+    if (!response.ok) {
+        throw new Error(`Request failed (${response.status}): ${response.statusText}`);
+    }
+    return response;
+}
+const endpoints = {
+    schedule: '/GTFS',
+    vehiclePositions: '/GTFS/realtime/vehiclepositions',
+};
+export const CcflClient = Object.freeze({
+    //
+    /**
+     * Fetches GTFS-RT Vehicle Positions feed from the CCFL API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Vehicle Positions feed message.
+     */
+    vehiclePositions: async () => {
+        const response = await fetcher(endpoints.vehiclePositions);
+        const arrayBuffer = await response.arrayBuffer();
+        return decodeGtfsRtFeed(arrayBuffer);
+    },
+    /**
+     * Fetches GTFS-RT Schedule feed from the CCFL API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Schedule feed message.
+     */
+    schedule: async () => {
+        const response = await fetcher(endpoints.schedule);
+        const arrayBuffer = await response.arrayBuffer();
+        return Buffer.from(arrayBuffer);
+    },
+});

package/dist/clients/cp/auth.d.ts

@@ -0,0 +1,27 @@
+export declare class CPAuthClient {
+    private static _instance;
+    private expiresAt;
+    private token;
+    private tunnel;
+    /**
+     * Disallow direct instantiation of the service.
+     * Use getToken() instead to ensure singleton behavior.
+     */
+    private constructor();
+    getToken(): Promise<string>;
+    /**
+     * Returns the singleton instance of the subclass.
+     */
+    static getInstance(): Promise<CPAuthClient>;
+    private connect;
+    /**
+     * Constructs the authentication URL based on environment variables
+     * and SSH tunneling configuration, and handles both direct connections and SSH-tunneled
+     * connections, validating the necessary environment variables for each case.
+     * This method is called internally by the service and should not be used directly.
+     * @throws Will throw an error if required environment variables are missing or if the SSH tunnel setup fails.
+     * @returns A promise that resolves to the authentication URL.
+     */
+    private getAuthenticationPort;
+}
+export declare const cpAuthClient: CPAuthClient;

package/dist/clients/cp/auth.js

@@ -0,0 +1,171 @@
+/* * */
+import { Logger } from '@tmlmobilidade/logger';
+import { SshTunnelService } from '@tmlmobilidade/ssh';
+import { asyncSingletonProxy } from '@tmlmobilidade/utils';
+import { readFileSync } from 'node:fs';
+import https from 'node:https';
+/* * */
+export class CPAuthClient {
+    //
+    static _instance = null;
+    expiresAt = 0;
+    token = null;
+    tunnel = null;
+    /**
+     * Disallow direct instantiation of the service.
+     * Use getToken() instead to ensure singleton behavior.
+     */
+    constructor() { }
+    async getToken() {
+        if (!this.token) {
+            Logger.info('[CPAuthClient] No token found, fetching a new one...');
+            await this.connect();
+        }
+        if (this.expiresAt - Date.now() < 60 * 1000) {
+            Logger.info('[CPAuthClient] Token is about to expire, refreshing...');
+            await this.connect();
+        }
+        return this.token;
+    }
+    /**
+     * Returns the singleton instance of the subclass.
+     */
+    static async getInstance() {
+        // If no instance exists, create one and store the promise.
+        // This ensures that if multiple calls to getInstance() happen concurrently,
+        // they will all await the same initialization process.
+        if (!this._instance) {
+            this._instance = (async () => {
+                const instance = new CPAuthClient();
+                // This behaves like the constructor,
+                // but allows for async initialization.
+                await instance.connect();
+                return instance;
+            })();
+        }
+        // Await the instance if it's still initializing,
+        // or return it immediately if ready.
+        return await this._instance;
+    }
+    async connect() {
+        //
+        Logger.info('[CPAuthClient] Connecting and fetching token...');
+        //
+        // Get the authentication URL, which also sets up the SSH tunnel if needed.
+        const port = await this.getAuthenticationPort();
+        //
+        // Make the POST request to the Authentication API through the SSH tunnel,
+        // and handle the response, extracting the access token or throwing an error if the request fails.
+        const responseResult = await new Promise((resolve, reject) => {
+            //
+            const requestBody = new URLSearchParams({
+                client_id: process.env.CP_AUTH_CLIENT_ID,
+                client_secret: process.env.CP_AUTH_CLIENT_SECRET,
+                grant_type: 'client_credentials',
+            }).toString();
+            const requestOptions = {
+                headers: {
+                    'Content-Length': Buffer.byteLength(requestBody),
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    'host': process.env.CP_AUTH_HOST,
+                },
+                host: 'localhost',
+                method: 'POST',
+                path: process.env.CP_AUTH_PATH,
+                port: port,
+                rejectUnauthorized: false,
+                servername: process.env.CP_AUTH_HOST,
+            };
+            const callback = (response) => {
+                const chunks = [];
+                response.on('data', chunk => chunks.push(chunk));
+                response.on('end', () => {
+                    const responseText = Buffer.concat(chunks).toString('utf8');
+                    if (response.statusCode < 200 || response.statusCode >= 300) {
+                        reject(new Error(`[CPAuthClient] Token request failed (${response.statusCode}): ${responseText.slice(0, 500)}`));
+                        return;
+                    }
+                    try {
+                        resolve(JSON.parse(responseText));
+                    }
+                    catch {
+                        reject(new Error(`[CPAuthClient] Token response is not JSON: ${responseText.slice(0, 500)}`));
+                    }
+                });
+            };
+            const request = https.request(requestOptions, callback);
+            request.on('error', reject);
+            request.write(requestBody);
+            request.end();
+        });
+        //
+        // With the response data, set the token and calculate the expiration time
+        // based on the current time and the expires_in value from the response.
+        this.expiresAt = Date.now() + (responseResult.expires_in * 1000);
+        this.token = responseResult.access_token;
+    }
+    /**
+     * Constructs the authentication URL based on environment variables
+     * and SSH tunneling configuration, and handles both direct connections and SSH-tunneled
+     * connections, validating the necessary environment variables for each case.
+     * This method is called internally by the service and should not be used directly.
+     * @throws Will throw an error if required environment variables are missing or if the SSH tunnel setup fails.
+     * @returns A promise that resolves to the authentication URL.
+     */
+    async getAuthenticationPort() {
+        //
+        //
+        // Validate required environment variables
+        if (!process.env.CP_AUTH_HOST || !process.env.CP_AUTH_PATH) {
+            throw new Error('Missing CP_AUTH_HOST or CP_AUTH_PATH environment variables.');
+        }
+        if (!process.env.CP_AUTH_CLIENT_ID || !process.env.CP_AUTH_CLIENT_SECRET) {
+            throw new Error('Missing CP_AUTH_CLIENT_ID or CP_AUTH_CLIENT_SECRET environment variables.');
+        }
+        if (!process.env.CP_TUNNEL_LOCAL_PORT) {
+            throw new Error('Missing CP_TUNNEL_LOCAL_PORT environment variable.');
+        }
+        if (!process.env.CP_TUNNEL_SSH_HOST || !process.env.CP_TUNNEL_SSH_USERNAME) {
+            throw new Error('Missing CP_TUNNEL_SSH_HOST or CP_TUNNEL_SSH_USERNAME environment variables.');
+        }
+        const sshConfig = {
+            forwardOptions: {
+                dstAddr: process.env.CP_AUTH_HOST,
+                dstPort: 443,
+                srcAddr: 'localhost',
+                srcPort: Number(process.env.CP_TUNNEL_LOCAL_PORT),
+            },
+            serverOptions: {
+                port: Number(process.env.CP_TUNNEL_LOCAL_PORT),
+            },
+            sshOptions: {
+                agent: process.env.CP_TUNNEL_SSH_KEY_PATH ? undefined : process.env.SSH_AUTH_SOCK,
+                host: process.env.CP_TUNNEL_SSH_HOST,
+                keepaliveCountMax: 20,
+                keepaliveInterval: 10_000,
+                port: 22,
+                privateKey: process.env.CP_TUNNEL_SSH_KEY_PATH ? readFileSync(process.env.CP_TUNNEL_SSH_KEY_PATH) : process.env.CP_TUNNEL_SSH_KEY,
+                username: process.env.CP_TUNNEL_SSH_USERNAME,
+            },
+            tunnelOptions: {
+                autoClose: false,
+                reconnectOnError: true,
+            },
+        };
+        const sshOptions = {
+            maxRetries: 3,
+        };
+        if (!this.tunnel) {
+            this.tunnel = new SshTunnelService(sshConfig, sshOptions);
+            await this.tunnel.connect();
+        }
+        Logger.info('[CPAuthClient] Setting up SSH Tunnel...');
+        const addr = this.tunnel.server.address();
+        if (!addr || typeof addr !== 'object') {
+            throw new Error('[CPAuthClient] Failed to retrieve SSH tunnel address.');
+        }
+        return addr.port;
+    }
+}
+/* * */
+export const cpAuthClient = asyncSingletonProxy(CPAuthClient);

package/dist/clients/cp/index.d.ts

@@ -0,0 +1,21 @@
+import { type GtfsRtFeedMessage } from '@tmlmobilidade/types';
+export declare const CpClient: Readonly<{
+    /**
+     * Fetches the latest GTFS static schedule feed (gtfs.zip) from the CP Partner API.
+     *
+     * @returns {Promise<Buffer>} A promise that resolves with the GTFS zip file as a Buffer.
+     */
+    schedule: () => Promise<Buffer>;
+    /**
+     * Fetches the GTFS-RT Trip Updates feed from the CP Partner API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Trip Updates feed message.
+     */
+    tripUpdates: () => Promise<GtfsRtFeedMessage>;
+    /**
+     * Fetches the GTFS-RT Vehicle Positions feed from the CP Partner API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Vehicle Positions feed message.
+     */
+    vehiclePositions: () => Promise<GtfsRtFeedMessage>;
+}>;

package/dist/clients/cp/index.js

@@ -0,0 +1,65 @@
+/* * */
+import { decodeGtfsRtFeed } from '@tmlmobilidade/gtfs-rt';
+import { cpAuthClient } from './auth.js';
+/* * */
+const BASE_URL = process.env.CP_API_URL;
+async function fetcher(endpoint) {
+    if (!BASE_URL) {
+        throw new Error('Missing CP_API_URL environment variable.');
+    }
+    //
+    // Get the API token
+    const apiToken = await cpAuthClient.getToken();
+    //
+    // Fetch the CP Trip Updates data from API and decode it.
+    const response = await fetch(`${BASE_URL}${endpoint}`, {
+        headers: {
+            'Authorization': `Bearer ${apiToken}`,
+            'x-cp-connect-id': process.env.CP_API_KEY,
+            'x-cp-connect-secret': process.env.CP_API_SECRET,
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Request failed (${response.status}): ${response.statusText}`);
+    }
+    return response;
+}
+const endpoints = {
+    schedule: '/schedule/gtfs.zip',
+    tripUpdates: '/realtime/TripUpdates.pb',
+    vehiclePositions: '/realtime/VehiclePositions.pb',
+};
+export const CpClient = Object.freeze({
+    //
+    /**
+     * Fetches the latest GTFS static schedule feed (gtfs.zip) from the CP Partner API.
+     *
+     * @returns {Promise<Buffer>} A promise that resolves with the GTFS zip file as a Buffer.
+     */
+    schedule: async () => {
+        const response = await fetcher(endpoints.schedule);
+        const arrayBuffer = await response.arrayBuffer();
+        return Buffer.from(arrayBuffer);
+    },
+    /**
+     * Fetches the GTFS-RT Trip Updates feed from the CP Partner API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Trip Updates feed message.
+     */
+    tripUpdates: async () => {
+        const response = await fetcher(endpoints.tripUpdates);
+        const arrayBuffer = await response.arrayBuffer();
+        const decodedMessage = await decodeGtfsRtFeed(arrayBuffer);
+        return decodedMessage;
+    },
+    /**
+     * Fetches the GTFS-RT Vehicle Positions feed from the CP Partner API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Vehicle Positions feed message.
+     */
+    vehiclePositions: async () => {
+        const response = await fetcher(endpoints.vehiclePositions);
+        const arrayBuffer = await response.arrayBuffer();
+        return decodeGtfsRtFeed(arrayBuffer);
+    },
+});

package/dist/clients/crtm-aisa/index.d.ts

@@ -0,0 +1,21 @@
+import { type GtfsRtFeedMessage } from '@tmlmobilidade/types';
+export declare const CrtmAisaClient: Readonly<{
+    /**
+     * Fetches GTFS-RT Vehicle Positions feed from the CRTM AISA API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Vehicle Positions feed message.
+     */
+    vehiclePositions: () => Promise<GtfsRtFeedMessage>;
+    /**
+     * Fetches GTFS-RT Trip Updates feed from the CRTM AISA API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Trip Updates feed message.
+     */
+    tripUpdates: () => Promise<GtfsRtFeedMessage>;
+    /**
+     * Fetches GTFS-RT Schedule feed from the CRTM AISA API.
+     *
+     * @returns {Promise<Buffer>} A promise that resolves with the GTFS zip file as a Buffer.
+     */
+    schedule: () => Promise<Buffer>;
+}>;

package/dist/clients/crtm-aisa/index.js

@@ -0,0 +1,52 @@
+/* * */
+import { decodeGtfsRtFeed } from '@tmlmobilidade/gtfs-rt';
+/* * */
+const BASE_URL = process.env.CRTM_AISA_API_URL;
+async function fetcher(endpoint) {
+    if (!BASE_URL) {
+        throw new Error('Missing CRTM_AISA_API_URL environment variable.');
+    }
+    const response = await fetch(`${BASE_URL}${endpoint}`);
+    if (!response.ok) {
+        throw new Error(`Request failed (${response.status}): ${response.statusText}`);
+    }
+    return response;
+}
+const endpoints = {
+    schedule: '/GTFS-SC/gtfs_sc.zip',
+    tripUpdates: '/GTFS-RT/actualizacionViaje',
+    vehiclePositions: '/GTFS-RT/vehiculosPosicion',
+};
+export const CrtmAisaClient = Object.freeze({
+    //
+    /**
+     * Fetches GTFS-RT Vehicle Positions feed from the CRTM AISA API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Vehicle Positions feed message.
+     */
+    vehiclePositions: async () => {
+        const response = await fetcher(endpoints.vehiclePositions);
+        const arrayBuffer = await response.arrayBuffer();
+        return decodeGtfsRtFeed(arrayBuffer);
+    },
+    /**
+     * Fetches GTFS-RT Trip Updates feed from the CRTM AISA API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Trip Updates feed message.
+     */
+    tripUpdates: async () => {
+        const response = await fetcher(endpoints.tripUpdates);
+        const arrayBuffer = await response.arrayBuffer();
+        return decodeGtfsRtFeed(arrayBuffer);
+    },
+    /**
+     * Fetches GTFS-RT Schedule feed from the CRTM AISA API.
+     *
+     * @returns {Promise<Buffer>} A promise that resolves with the GTFS zip file as a Buffer.
+     */
+    schedule: async () => {
+        const response = await fetcher(endpoints.schedule);
+        const arrayBuffer = await response.arrayBuffer();
+        return Buffer.from(arrayBuffer);
+    },
+});

package/dist/clients/fertagus/auth.d.ts

@@ -0,0 +1,17 @@
+export declare class FertagusAuthClient {
+    private static _instance;
+    private expiresAt;
+    private token;
+    /**
+     * Disallow direct instantiation of the service.
+     * Use getToken() instead to ensure singleton behavior.
+     */
+    private constructor();
+    getToken(): Promise<string>;
+    /**
+     * Returns the singleton instance of the subclass.
+     */
+    static getInstance(): Promise<FertagusAuthClient>;
+    private connect;
+}
+export declare const fertagusAuthClient: FertagusAuthClient;

package/dist/clients/fertagus/auth.js

@@ -0,0 +1,76 @@
+/* * */
+import { Logger } from '@tmlmobilidade/logger';
+import { asyncSingletonProxy } from '@tmlmobilidade/utils';
+/* * */
+export class FertagusAuthClient {
+    //
+    static _instance = null;
+    expiresAt = 0;
+    token = null;
+    /**
+     * Disallow direct instantiation of the service.
+     * Use getToken() instead to ensure singleton behavior.
+     */
+    constructor() { }
+    async getToken() {
+        if (!this.token) {
+            Logger.info('[FertagusAuthClient] No token found, fetching a new one...');
+            await this.connect();
+        }
+        if (this.expiresAt - Date.now() < 60 * 1000) {
+            Logger.info('[FertagusAuthClient] Token is about to expire, refreshing...');
+            await this.connect();
+        }
+        return this.token;
+    }
+    /**
+     * Returns the singleton instance of the subclass.
+     */
+    static async getInstance() {
+        // If no instance exists, create one and store the promise.
+        // This ensures that if multiple calls to getInstance() happen concurrently,
+        // they will all await the same initialization process.
+        if (!this._instance) {
+            this._instance = (async () => {
+                const instance = new FertagusAuthClient();
+                // This behaves like the constructor,
+                // but allows for async initialization.
+                await instance.connect();
+                return instance;
+            })();
+        }
+        // Await the instance if it's still initializing,
+        // or return it immediately if ready.
+        return await this._instance;
+    }
+    async connect() {
+        //
+        Logger.info('[FertagusAuthClient] Connecting and fetching token...');
+        //
+        // Make the POST request to the Authentication API through the SSH tunnel,
+        // and handle the response, extracting the access token or throwing an error if the request fails.
+        const requestBody = new URLSearchParams({
+            grant_type: 'client_credentials',
+            password: process.env.FERTAGUS_AUTH_PASSWORD,
+            username: process.env.FERTAGUS_AUTH_USERNAME,
+        }).toString();
+        const response = await fetch(process.env.FERTAGUS_AUTH_URL, {
+            body: requestBody,
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            method: 'POST',
+        });
+        if (!response.ok) {
+            throw new Error(`[FertagusAuthClient] Token request failed (${response.status}): ${response.statusText}`);
+        }
+        const data = await response.json();
+        //
+        // With the response data, set the token and calculate the expiration time
+        // based on the current time and the expires_in value from the response.
+        this.expiresAt = Date.now() + (data.expires_in * 1000);
+        this.token = data.access_token;
+    }
+}
+/* * */
+export const fertagusAuthClient = asyncSingletonProxy(FertagusAuthClient);

package/dist/clients/fertagus/index.d.ts

@@ -0,0 +1,8 @@
+import { TrainsResponse } from './types.js';
+export declare const FertagusClient: Readonly<{
+    /**
+     * Gets the status of all Fertagus trains.
+     * @returns TrainsResponse object with the current status of all trains.
+     */
+    trains: () => Promise<TrainsResponse>;
+}>;

package/dist/clients/fertagus/index.js

@@ -0,0 +1,33 @@
+/* * */
+import { fertagusAuthClient } from './auth.js';
+/* * */
+const BASE_URL = process.env.FERTAGUS_API_URL;
+async function fetcher(endpoint) {
+    if (!BASE_URL) {
+        throw new Error('Missing FERTAGUS_API_URL environment variable.');
+    }
+    const apiToken = await fertagusAuthClient.getToken();
+    const response = await fetch(`${BASE_URL}${endpoint}`, {
+        headers: {
+            Authorization: `Bearer ${apiToken}`,
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Request failed (${response.status}): ${response.statusText}`);
+    }
+    return response;
+}
+/* * */
+const endpoints = {
+    trains: '/trains',
+};
+export const FertagusClient = Object.freeze({
+    /**
+     * Gets the status of all Fertagus trains.
+     * @returns TrainsResponse object with the current status of all trains.
+     */
+    trains: async () => {
+        const response = await fetcher(endpoints.trains);
+        return await response.json();
+    },
+});

package/dist/clients/fertagus/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * @see GET /trains
+ */
+export type TrainsResponse = Array<{
+    date: string;
+    latitude: null | number;
+    longitude: null | number;
+    startsAt: null | string;
+    stop_id_end: null | string;
+    stop_id_start: null | string;
+    train_id: null | string;
+}>;

package/dist/clients/fertagus/types.js

@@ -0,0 +1,2 @@
+/* * */
+export {};

package/dist/clients/ml/auth.d.ts

@@ -0,0 +1,18 @@
+export declare class MLAuthClient {
+    private static _instance;
+    private expiresAt;
+    private token;
+    private tunnel;
+    /**
+     * Disallow direct instantiation of the service.
+     * Use getToken() instead to ensure singleton behavior.
+     */
+    private constructor();
+    getToken(): Promise<string>;
+    /**
+     * Returns the singleton instance of the subclass.
+     */
+    static getInstance(): Promise<MLAuthClient>;
+    private connect;
+}
+export declare const mlAuthClient: MLAuthClient;

package/dist/clients/ml/auth.js

@@ -0,0 +1,77 @@
+/* * */
+import { Logger } from '@tmlmobilidade/logger';
+import { asyncSingletonProxy } from '@tmlmobilidade/utils';
+/* * */
+export class MLAuthClient {
+    //
+    static _instance = null;
+    expiresAt = 0;
+    token = null;
+    tunnel = null;
+    /**
+     * Disallow direct instantiation of the service.
+     * Use getToken() instead to ensure singleton behavior.
+     */
+    constructor() { }
+    async getToken() {
+        if (!this.token) {
+            Logger.info('[MLAuthClient] No token found, fetching a new one...');
+            await this.connect();
+        }
+        if (this.expiresAt - Date.now() < 60 * 1000) {
+            Logger.info('[MLAuthClient] Token is about to expire, refreshing...');
+            await this.connect();
+        }
+        return this.token;
+    }
+    /**
+     * Returns the singleton instance of the subclass.
+     */
+    static async getInstance() {
+        // If no instance exists, create one and store the promise.
+        // This ensures that if multiple calls to getInstance() happen concurrently,
+        // they will all await the same initialization process.
+        if (!this._instance) {
+            this._instance = (async () => {
+                const instance = new MLAuthClient();
+                // This behaves like the constructor,
+                // but allows for async initialization.
+                await instance.connect();
+                return instance;
+            })();
+        }
+        // Await the instance if it's still initializing,
+        // or return it immediately if ready.
+        return await this._instance;
+    }
+    async connect() {
+        //
+        Logger.info('[MLAuthClient] Connecting and fetching token...');
+        //
+        // Make the POST request to the Authentication API through the SSH tunnel,
+        // and handle the response, extracting the access token or throwing an error if the request fails.
+        const requestBody = new URLSearchParams({
+            grant_type: 'password',
+            password: process.env.ML_AUTH_PASSWORD,
+            username: process.env.ML_AUTH_USERNAME,
+        }).toString();
+        const response = await fetch(process.env.ML_AUTH_URL, {
+            body: requestBody,
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            method: 'POST',
+        });
+        if (!response.ok) {
+            throw new Error(`[MLAuthClient] Token request failed (${response.status}): ${response.statusText}`);
+        }
+        const data = await response.json();
+        //
+        // With the response data, set the token and calculate the expiration time
+        // based on the current time and the expires_in value from the response.
+        this.expiresAt = Date.now() + (data.expires_in * 1000);
+        this.token = data.access_token;
+    }
+}
+/* * */
+export const mlAuthClient = asyncSingletonProxy(MLAuthClient);

package/dist/clients/ml/index.d.ts

@@ -0,0 +1,48 @@
+import { ServiceAlertResponse } from '@tmlmobilidade/types';
+import { BaseResponse, EstadoLinha, InfoEstacao, TempoEspera } from './types.js';
+export declare const MlClient: Readonly<{
+    /**
+     * Gets the status of a specific Metro Lisboa line.
+     * @param linha Line identifier as string.
+     * @returns EstadoLinha object with the current status of the line.
+     */
+    estadoLinha: (linha: string) => Promise<BaseResponse<EstadoLinha>>;
+    /**
+     * Gets the status of all Metro Lisboa lines.
+     * @returns An array of EstadoLinha objects, each representing the status of a line.
+     */
+    estadoLinhaTodas: () => Promise<BaseResponse<EstadoLinha[]>>;
+    /**
+     * Gets information about a specific Metro Lisboa station.
+     * @param estacao Station identifier as string.
+     * @returns InfoEstacao object with details about the station.
+     */
+    infoEstacao: (estacao: string) => Promise<BaseResponse<InfoEstacao>>;
+    /**
+     * Gets information about all Metro Lisboa stations.
+     * @returns An array of InfoEstacao objects, one for each station.
+     */
+    infoEstacaoTodas: () => Promise<BaseResponse<InfoEstacao[]>>;
+    /**
+     * Retrieves current Metro Lisboa service alerts.
+     * @returns A ServiceAlertResponse containing the active service alerts in GTFS-realtime format.
+     */
+    serviceAlerts: () => Promise<BaseResponse<ServiceAlertResponse>>;
+    /**
+     * Gets the current waiting time estimates for a specific station.
+     * @param estacao Station identifier as string.
+     * @returns TempoEspera object with estimated waiting times for the station.
+     */
+    tempoEsperaEstacao: (estacao: string) => Promise<BaseResponse<TempoEspera>>;
+    /**
+     * Gets the current waiting time estimates for a specific line.
+     * @param linha Line identifier as string.
+     * @returns An array of TempoEspera objects, one for each station in the line.
+     */
+    tempoEsperaLinha: (linha: string) => Promise<BaseResponse<TempoEspera[]>>;
+    /**
+     * Gets the current waiting time estimates for all stations.
+     * @returns An array of TempoEspera objects, one for each station.
+     */
+    tempoEsperaTodasEstacoes: () => Promise<BaseResponse<TempoEspera[]>>;
+}>;

package/dist/clients/ml/index.js

@@ -0,0 +1,101 @@
+/* * */
+import { mlAuthClient } from './auth.js';
+/* * */
+const BASE_URL = process.env.ML_API_URL;
+const ALERTS_URL = process.env.ML_ALERTS_URL;
+async function fetcher(endpoint) {
+    if (!BASE_URL) {
+        throw new Error('Missing ML_API_URL environment variable.');
+    }
+    const apiToken = await mlAuthClient.getToken();
+    const response = await fetch(`${BASE_URL}${endpoint}`, {
+        headers: {
+            Authorization: `Bearer ${apiToken}`,
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Request failed (${response.status}): ${response.statusText}`);
+    }
+    return response;
+}
+/* * */
+const endpoints = {
+    estadoLinha: (linha) => `/estadoLinha/${linha}`,
+    estadoLinhaTodas: '/estadoLinha/todos',
+    infoEstacao: (estacao) => `/infoEstacao/${estacao}`,
+    infoEstacaoTodas: '/infoEstacao/todos',
+    serviceAlerts: ALERTS_URL,
+    tempoEsperaEstacao: (estacao) => `/tempoEspera/Estacao/${estacao}`,
+    tempoEsperaLinha: (linha) => `/tempoEspera/Linha/${linha}`,
+    tempoEsperaTodasEstacoes: '/tempoEspera/Estacao/todos',
+};
+export const MlClient = Object.freeze({
+    /**
+     * Gets the status of a specific Metro Lisboa line.
+     * @param linha Line identifier as string.
+     * @returns EstadoLinha object with the current status of the line.
+     */
+    estadoLinha: async (linha) => {
+        const response = await fetcher(endpoints.estadoLinha(linha));
+        return await response.json();
+    },
+    /**
+     * Gets the status of all Metro Lisboa lines.
+     * @returns An array of EstadoLinha objects, each representing the status of a line.
+     */
+    estadoLinhaTodas: async () => {
+        const response = await fetcher(endpoints.estadoLinhaTodas);
+        return await response.json();
+    },
+    /**
+     * Gets information about a specific Metro Lisboa station.
+     * @param estacao Station identifier as string.
+     * @returns InfoEstacao object with details about the station.
+     */
+    infoEstacao: async (estacao) => {
+        const response = await fetcher(endpoints.infoEstacao(estacao));
+        return await response.json();
+    },
+    /**
+     * Gets information about all Metro Lisboa stations.
+     * @returns An array of InfoEstacao objects, one for each station.
+     */
+    infoEstacaoTodas: async () => {
+        const response = await fetcher(endpoints.infoEstacaoTodas);
+        return await response.json();
+    },
+    /**
+     * Retrieves current Metro Lisboa service alerts.
+     * @returns A ServiceAlertResponse containing the active service alerts in GTFS-realtime format.
+     */
+    serviceAlerts: async () => {
+        const response = await fetcher(endpoints.serviceAlerts);
+        return await response.json();
+    },
+    /**
+     * Gets the current waiting time estimates for a specific station.
+     * @param estacao Station identifier as string.
+     * @returns TempoEspera object with estimated waiting times for the station.
+     */
+    tempoEsperaEstacao: async (estacao) => {
+        const response = await fetcher(endpoints.tempoEsperaEstacao(estacao));
+        return await response.json();
+    },
+    /**
+     * Gets the current waiting time estimates for a specific line.
+     * @param linha Line identifier as string.
+     * @returns An array of TempoEspera objects, one for each station in the line.
+     */
+    tempoEsperaLinha: async (linha) => {
+        const response = await fetcher(endpoints.tempoEsperaLinha(linha));
+        return await response.json();
+    },
+    /**
+     * Gets the current waiting time estimates for all stations.
+     * @returns An array of TempoEspera objects, one for each station.
+     */
+    tempoEsperaTodasEstacoes: async () => {
+        const response = await fetcher(endpoints.tempoEsperaTodasEstacoes);
+        return await response.json();
+    },
+});

package/dist/clients/ml/types.d.ts

@@ -0,0 +1,38 @@
+export interface BaseResponse<T> {
+    codigo: number;
+    resposta: T;
+}
+/**
+ * @see GET /tempoEspera/Estacao/todos
+ * @see GET /tempoEspera/Estacao/{estacao}
+ * @see GET /tempoEspera/Linha/{linha}
+ */
+export interface TempoEspera {
+    comboio: string;
+    destino: string;
+    estacao: string;
+    linha: string;
+    nomeEstacao: string;
+    tempoEspera: string;
+}
+/**
+ * @see GET /infoEstacao/todos
+ * @see GET /infoEstacao/{estacao}
+ */
+export interface InfoEstacao {
+    id: string;
+    latitude: number;
+    linha: string;
+    longitude: number;
+    nome: string;
+    url?: string;
+}
+/**
+ * @see GET /estadoLinha/todos
+ * @see GET /estadoLinha/{linha}
+ */
+export interface EstadoLinha {
+    descricao: string;
+    estado: string;
+    linha: string;
+}

package/dist/clients/ml/types.js

@@ -0,0 +1,2 @@
+/* * */
+export {};

package/dist/clients/mobi/index.d.ts

@@ -0,0 +1,15 @@
+import { type GtfsRtFeedMessage } from '@tmlmobilidade/types';
+export declare const MobiClient: Readonly<{
+    /**
+     * Fetches GTFS-RT Trip Updates feed from the Mobi API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Trip Updates feed message.
+     */
+    tripUpdates: () => Promise<GtfsRtFeedMessage>;
+    /**
+     * Fetches GTFS-RT Vehicle Positions feed from the Mobi API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Vehicle Positions feed message.
+     */
+    vehiclePositions: () => Promise<GtfsRtFeedMessage>;
+}>;

package/dist/clients/mobi/index.js

@@ -0,0 +1,42 @@
+/* * */
+import { decodeGtfsRtFeed } from '@tmlmobilidade/gtfs-rt';
+/* * */
+const BASE_URL = process.env.MOBI_API_URL;
+const AUTH_TOKEN = Buffer.from(`${process.env.MOBI_API_USERNAME}:${process.env.MOBI_API_PASSWORD}`).toString('base64');
+async function mobiFetch(endpoint) {
+    if (!BASE_URL) {
+        throw new Error('Missing MOBI_API_URL environment variable.');
+    }
+    const response = await fetch(`${BASE_URL}${endpoint}`, { headers: { Authorization: `Basic ${AUTH_TOKEN}` } });
+    if (!response.ok) {
+        throw new Error(`Request failed (${response.status}): ${response.statusText}`);
+    }
+    return response;
+}
+const endpoints = {
+    tripUpdates: '/gtfs-rt/tripUpdates',
+    vehiclePositions: '/gtfs-rt/vehiclePositions',
+};
+export const MobiClient = Object.freeze({
+    //
+    /**
+     * Fetches GTFS-RT Trip Updates feed from the Mobi API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Trip Updates feed message.
+     */
+    tripUpdates: async () => {
+        const response = await mobiFetch(endpoints.tripUpdates);
+        const arrayBuffer = await response.arrayBuffer();
+        return decodeGtfsRtFeed(arrayBuffer);
+    },
+    /**
+     * Fetches GTFS-RT Vehicle Positions feed from the Mobi API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Vehicle Positions feed message.
+     */
+    vehiclePositions: async () => {
+        const response = await mobiFetch(endpoints.vehiclePositions);
+        const arrayBuffer = await response.arrayBuffer();
+        return decodeGtfsRtFeed(arrayBuffer);
+    },
+});

package/dist/clients/tcb/index.d.ts

@@ -0,0 +1,9 @@
+import { type GtfsRtFeedMessage } from '@tmlmobilidade/types';
+export declare const TcbClient: Readonly<{
+    /**
+     * Fetches GTFS-RT Vehicle Positions feed from the TCB API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Vehicle Positions feed message.
+     */
+    vehiclePositions: () => Promise<GtfsRtFeedMessage>;
+}>;

package/dist/clients/tcb/index.js

@@ -0,0 +1,30 @@
+/* * */
+import { decodeGtfsRtFeed } from '@tmlmobilidade/gtfs-rt';
+/* * */
+const BASE_URL = process.env.TCB_API_URL;
+async function fetcher(endpoint) {
+    if (!BASE_URL) {
+        throw new Error('Missing TCB_API_URL environment variable.');
+    }
+    const response = await fetch(`${BASE_URL}${endpoint}`);
+    if (!response.ok) {
+        throw new Error(`Request failed (${response.status}): ${response.statusText}`);
+    }
+    return response;
+}
+const endpoints = {
+    vehiclePositions: '/gtfs-realtime',
+};
+export const TcbClient = Object.freeze({
+    //
+    /**
+     * Fetches GTFS-RT Vehicle Positions feed from the TCB API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Vehicle Positions feed message.
+     */
+    vehiclePositions: async () => {
+        const response = await fetcher(endpoints.vehiclePositions);
+        const arrayBuffer = await response.arrayBuffer();
+        return decodeGtfsRtFeed(arrayBuffer);
+    },
+});

package/dist/clients/ttsl/index.d.ts

@@ -0,0 +1,9 @@
+import { type GtfsRtFeedMessage } from '@tmlmobilidade/types';
+export declare const TtslClient: Readonly<{
+    /**
+     * Fetches GTFS-RT Vehicle Positions feed from the TTSL API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Vehicle Positions feed message.
+     */
+    vehiclePositions: () => Promise<GtfsRtFeedMessage>;
+}>;

package/dist/clients/ttsl/index.js

@@ -0,0 +1,30 @@
+/* * */
+import { decodeGtfsRtFeed } from '@tmlmobilidade/gtfs-rt';
+/* * */
+const BASE_URL = process.env.TTSL_API_URL;
+async function fetcher(endpoint) {
+    if (!BASE_URL) {
+        throw new Error('Missing TTSL_API_URL environment variable.');
+    }
+    const response = await fetch(`${BASE_URL}${endpoint}`);
+    if (!response.ok) {
+        throw new Error(`Request failed (${response.status}): ${response.statusText}`);
+    }
+    return response;
+}
+const endpoints = {
+    vehiclePositions: '/files/gtfs_rt_vehicles.pb',
+};
+export const TtslClient = Object.freeze({
+    //
+    /**
+     * Fetches GTFS-RT Vehicle Positions feed from the TTSL API.
+     *
+     * @returns {Promise<GtfsRtFeedMessage>} A promise that resolves with the decoded GTFS-RT Vehicle Positions feed message.
+     */
+    vehiclePositions: async () => {
+        const response = await fetcher(endpoints.vehiclePositions);
+        const arrayBuffer = await response.arrayBuffer();
+        return decodeGtfsRtFeed(arrayBuffer);
+    },
+});

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Collection of external transport agency clients.
+ *
+ * Each property provides a typed client to interact with the public API
+ * of a specific transport agency. These clients offer methods to fetch
+ * GTFS-RT feeds and other relevant live data where available.
+ *
+ * - ccfl: Companhia dos Caminhos de Ferro de Lisboa (CCFL) AKA Carris Munícipal API Client.
+ * - cp: Comboios de Portugal (CP) API Client
+ * - crtmAisa: Consorcio Regional de Transportes de Madrid (AISACRTM) API Client
+ * - mobi: MobiCascais API Client
+ * - ml: Metro Lisboa (ML) API Client
+ * - tcb: Transportes Colectivos do Barreiro (TCB) API Client
+ * - ttsl: Transtejo Soflusa (TTSL) API Client
+ */
+export declare const externalClients: Readonly<{
+    ccfl: Readonly<{
+        vehiclePositions: () => Promise<import("@tmlmobilidade/types").GtfsRtFeedMessage>;
+        schedule: () => Promise<Buffer>;
+    }>;
+    cp: Readonly<{
+        schedule: () => Promise<Buffer>;
+        tripUpdates: () => Promise<import("@tmlmobilidade/types").GtfsRtFeedMessage>;
+        vehiclePositions: () => Promise<import("@tmlmobilidade/types").GtfsRtFeedMessage>;
+    }>;
+    crtmAisa: Readonly<{
+        vehiclePositions: () => Promise<import("@tmlmobilidade/types").GtfsRtFeedMessage>;
+        tripUpdates: () => Promise<import("@tmlmobilidade/types").GtfsRtFeedMessage>;
+        schedule: () => Promise<Buffer>;
+    }>;
+    fertagus: Readonly<{
+        trains: () => Promise<import("./clients/fertagus/types.js").TrainsResponse>;
+    }>;
+    ml: Readonly<{
+        estadoLinha: (linha: string) => Promise<import("./clients/ml/types.js").BaseResponse<import("./clients/ml/types.js").EstadoLinha>>;
+        estadoLinhaTodas: () => Promise<import("./clients/ml/types.js").BaseResponse<import("./clients/ml/types.js").EstadoLinha[]>>;
+        infoEstacao: (estacao: string) => Promise<import("./clients/ml/types.js").BaseResponse<import("./clients/ml/types.js").InfoEstacao>>;
+        infoEstacaoTodas: () => Promise<import("./clients/ml/types.js").BaseResponse<import("./clients/ml/types.js").InfoEstacao[]>>;
+        serviceAlerts: () => Promise<import("./clients/ml/types.js").BaseResponse<import("@tmlmobilidade/types").ServiceAlertResponse>>;
+        tempoEsperaEstacao: (estacao: string) => Promise<import("./clients/ml/types.js").BaseResponse<import("./clients/ml/types.js").TempoEspera>>;
+        tempoEsperaLinha: (linha: string) => Promise<import("./clients/ml/types.js").BaseResponse<import("./clients/ml/types.js").TempoEspera[]>>;
+        tempoEsperaTodasEstacoes: () => Promise<import("./clients/ml/types.js").BaseResponse<import("./clients/ml/types.js").TempoEspera[]>>;
+    }>;
+    mobi: Readonly<{
+        tripUpdates: () => Promise<import("@tmlmobilidade/types").GtfsRtFeedMessage>;
+        vehiclePositions: () => Promise<import("@tmlmobilidade/types").GtfsRtFeedMessage>;
+    }>;
+    tcb: Readonly<{
+        vehiclePositions: () => Promise<import("@tmlmobilidade/types").GtfsRtFeedMessage>;
+    }>;
+    ttsl: Readonly<{
+        vehiclePositions: () => Promise<import("@tmlmobilidade/types").GtfsRtFeedMessage>;
+    }>;
+}>;

package/dist/index.js

@@ -0,0 +1,34 @@
+/* * */
+import { CcflClient } from './clients/ccfl/index.js';
+import { CpClient } from './clients/cp/index.js';
+import { CrtmAisaClient } from './clients/crtm-aisa/index.js';
+import { FertagusClient } from './clients/fertagus/index.js';
+import { MlClient } from './clients/ml/index.js';
+import { MobiClient } from './clients/mobi/index.js';
+import { TcbClient } from './clients/tcb/index.js';
+import { TtslClient } from './clients/ttsl/index.js';
+/**
+ * Collection of external transport agency clients.
+ *
+ * Each property provides a typed client to interact with the public API
+ * of a specific transport agency. These clients offer methods to fetch
+ * GTFS-RT feeds and other relevant live data where available.
+ *
+ * - ccfl: Companhia dos Caminhos de Ferro de Lisboa (CCFL) AKA Carris Munícipal API Client.
+ * - cp: Comboios de Portugal (CP) API Client
+ * - crtmAisa: Consorcio Regional de Transportes de Madrid (AISACRTM) API Client
+ * - mobi: MobiCascais API Client
+ * - ml: Metro Lisboa (ML) API Client
+ * - tcb: Transportes Colectivos do Barreiro (TCB) API Client
+ * - ttsl: Transtejo Soflusa (TTSL) API Client
+ */
+export const externalClients = Object.freeze({
+    ccfl: CcflClient,
+    cp: CpClient,
+    crtmAisa: CrtmAisaClient,
+    fertagus: FertagusClient,
+    ml: MlClient,
+    mobi: MobiClient,
+    tcb: TcbClient,
+    ttsl: TtslClient,
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "@tmlmobilidade/external",
+	"version": "20260604.9.7",
+	"author": {
+		"email": "iso@tmlmobilidade.pt",
+		"name": "TML-ISO"
+	},
+	"license": "AGPL-3.0-or-later",
+	"homepage": "https://go.tmlmobilidade.pt",
+	"bugs": {
+		"url": "https://github.com/tmlmobilidade/go/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/tmlmobilidade/go.git"
+	},
+	"keywords": [
+		"external",
+		"tml",
+		"transportes metropolitanos de lisboa",
+		"tmlmobilidade"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"scripts": {
+		"build": "tsc && resolve-tspaths",
+		"lint": "eslint ./src/ && tsc --noEmit",
+		"lint:fix": "eslint ./src/ --fix",
+		"watch": "tsc-watch --onSuccess 'resolve-tspaths'"
+	},
+	"dependencies": {
+		"@tmlmobilidade/gtfs-rt": "*",
+		"@tmlmobilidade/logger": "*",
+		"@tmlmobilidade/ssh": "*",
+		"@tmlmobilidade/types": "*",
+		"@tmlmobilidade/utils": "*"
+	},
+	"devDependencies": {
+		"@tmlmobilidade/tsconfig": "*",
+		"@types/node": "25.9.1",
+		"resolve-tspaths": "0.8.23",
+		"tsc-watch": "7.2.0",
+		"typescript": "5.9.3"
+	}
+}