@tmlmobilidade/controllers 20260817.1945.33 → 20260828.1636.54

package/README.md

@@ -1,3 +1,5 @@
 ## @tmlmobilidade/controllers
 
 These are shared controllers to retrieve and prepare common data across apps.
+
+-

package/dist/exporter/exporter.d.ts

@@ -1,5 +1,5 @@
-import { type FastifyReply, type FastifyRequest } from '@tmlmobilidade/fastify';
-import { type CreateFileExportDto, type FileExport } from '@tmlmobilidade/types';
+import { type FastifyReply, type FastifyRequest } from '@tmlmobilidade/go-clients-fastify';
+import { type CreateFileExportDto, type FileExport } from '@tmlmobilidade/go-types-downloads';
 export declare class ExporterSharedController {
     /**
      * Returns an Agency by ID.

package/dist/exporter/exporter.js

@@ -13,7 +13,12 @@ export class ExporterSharedController {
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     static async create(request, reply) {
-        const fileExportData = await goDb.core.exports.insertOne({ ...request.body, created_by: request.me._id, updated_by: request.me._id });
+        const fileExportData = await goDb.core.exports.insertOne({
+            ...request.body,
+            created_by: request.me._id,
+            processing_status: 'waiting',
+            updated_by: request.me._id,
+        });
         return reply.send({ data: fileExportData, error: null, statusCode: HTTP_STATUS.CREATED });
     }
     /**
@@ -59,7 +64,7 @@ export class ExporterSharedController {
         const filters = {
             created_by: request.me._id,
         };
-        const allFileExport = await goDb.core.exports.findMany(filters, { sort: { created_at: 1 } });
+        const allFileExport = await goDb.core.exports.findMany(filters);
         return reply.send({ data: allFileExport, error: null, statusCode: HTTP_STATUS.OK });
     }
 }

package/dist/index.d.ts

@@ -1,3 +1 @@
-export * from './agencies/index.js';
 export * from './exporter/index.js';
-export * from './operation/index.js';

package/dist/index.js

@@ -1,3 +1 @@
-export * from './agencies/index.js';
 export * from './exporter/index.js';
-export * from './operation/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tmlmobilidade/controllers",
-	"version": "20260817.1945.33",
+	"version": "20260828.1636.54",
 	"author": {
 		"email": "iso@tmlmobilidade.pt",
 		"name": "TML-ISO"
@@ -37,18 +37,20 @@
 	},
 	"dependencies": {
 		"@tmlmobilidade/consts": "*",
-		"@tmlmobilidade/fastify": "*",
+		"@tmlmobilidade/go-clients-fastify": "*",
 		"@tmlmobilidade/go-clients-mongo": "*",
 		"@tmlmobilidade/go-interfaces-godb": "*",
 		"@tmlmobilidade/go-providers-storage": "*",
+		"@tmlmobilidade/go-types-core": "*",
+		"@tmlmobilidade/go-types-downloads": "*",
+		"@tmlmobilidade/go-utils-dates": "*",
 		"@tmlmobilidade/interfaces": "*",
 		"@tmlmobilidade/logger": "*",
 		"@tmlmobilidade/normalizers": "*",
 		"@tmlmobilidade/utils": "*"
 	},
 	"devDependencies": {
-		"@tmlmobilidade/tsconfig": "*",
-		"@tmlmobilidade/types": "*",
+		"@tmlmobilidade/go-utils-tsconfig": "*",
 		"@types/node": "26.1.2",
 		"@types/ws": "8.18.1",
 		"resolve-tspaths": "0.8.23",

package/dist/agencies/agencies.d.ts

@@ -1,27 +0,0 @@
-import { type FastifyReply, type FastifyRequest } from '@tmlmobilidade/fastify';
-import { type ActionsOf, type Agency, type Permission } from '@tmlmobilidade/types';
-interface GetAllAgenciesQuery {
-    actions?: string | string[];
-    scope?: Permission['scope'];
-}
-export declare class AgenciesSharedController {
-    /**
-     * Returns all Agencies sorted by ID.
-     * @param request The request object
-     * @param reply The reply object
-     */
-    static getAll(request: FastifyRequest<{
-        Querystring: GetAllAgenciesQuery;
-    }>, reply: FastifyReply<Agency[]>): Promise<never>;
-    /**
-     * Returns an Agency by ID.
-     * @param request The request object
-     * @param reply The reply object
-     */
-    static getById<S extends Permission['scope']>(request: FastifyRequest<{
-        Params: {
-            id: string;
-        };
-    }>, reply: FastifyReply<Agency>, scope: S, action: ActionsOf<S>): Promise<never>;
-}
-export {};

package/dist/agencies/agencies.js

@@ -1,89 +0,0 @@
-/* * */
-import { HTTP_STATUS, HttpException } from '@tmlmobilidade/consts';
-import { goDb } from '@tmlmobilidade/go-interfaces-godb';
-import { Logger } from '@tmlmobilidade/logger';
-import { PermissionCatalog } from '@tmlmobilidade/types';
-function getAgencyIdsFromPermission(permission) {
-    return permission?.resources?.agency_ids ?? [];
-}
-/* * */
-export class AgenciesSharedController {
-    //
-    /**
-     * Returns all Agencies sorted by ID.
-     * @param request The request object
-     * @param reply The reply object
-     */
-    static async getAll(request, reply) {
-        //
-        // A. Setup variables
-        const scope = request.query.scope;
-        const actions = (Array.isArray(request.query.actions) ? request.query.actions : request.query.actions?.split(','))?.filter(Boolean);
-        if (!scope || !actions?.length) {
-            throw new HttpException(HTTP_STATUS.BAD_REQUEST, 'Missing scope or actions query parameters');
-        }
-        //
-        // Detect which agency_ids the user has access to,
-        // based on their permissions. If none, return an empty array.
-        const permittedAgencyIds = actions.flatMap(action => getAgencyIdsFromPermission(PermissionCatalog.get(request.permissions, scope, action)));
-        if (!permittedAgencyIds.length) {
-            Logger.issue({
-                context: {
-                    action: 'getAll',
-                    feature: 'agencies',
-                    request,
-                },
-                level: 'info',
-                messageOrError: 'No agency_ids found in permissions',
-            });
-            return reply.send({ data: [], error: null, statusCode: HTTP_STATUS.OK });
-        }
-        const allowAllAgencies = permittedAgencyIds.includes(PermissionCatalog.ALLOW_ALL_FLAG);
-        const queryFilters = allowAllAgencies ? {} : { _id: { $in: permittedAgencyIds } };
-        const allAgencies = await goDb.core.agencies.findMany(queryFilters, { sort: { _id: 1 } });
-        reply.send({ data: allAgencies, error: null, statusCode: HTTP_STATUS.OK });
-    }
-    /**
-     * Returns an Agency by ID.
-     * @param request The request object
-     * @param reply The reply object
-     */
-    static async getById(request, reply, scope, action) {
-        //
-        // Detect which agency_ids the user has access to,
-        // based on their permissions. If none, return an empty array.
-        const agenciesPermission = PermissionCatalog.get(request.permissions, scope, action);
-        const permittedAgencyIds = getAgencyIdsFromPermission(agenciesPermission);
-        if (!permittedAgencyIds.length) {
-            Logger.issue({
-                context: {
-                    action: 'getById',
-                    feature: 'agencies',
-                    request,
-                    value: request.params.id,
-                },
-                level: 'info',
-                messageOrError: 'No agency_ids found in permissions',
-            });
-            return reply.send({ data: null, error: null, statusCode: HTTP_STATUS.OK });
-        }
-        const allowAllAgencies = permittedAgencyIds.includes(PermissionCatalog.ALLOW_ALL_FLAG);
-        const queryFilters = allowAllAgencies ? { _id: request.params.id } : { _id: { $eq: request.params.id, $in: permittedAgencyIds } };
-        const agencyData = await goDb.core.agencies.findOne(queryFilters);
-        if (!agencyData) {
-            const error = new HttpException(HTTP_STATUS.NOT_FOUND, 'Agency not found');
-            Logger.issue({
-                context: {
-                    action: 'getById',
-                    feature: 'agencies',
-                    request,
-                    value: request.params.id,
-                },
-                level: 'error',
-                messageOrError: error,
-            });
-            throw error;
-        }
-        reply.send({ data: agencyData, error: null, statusCode: HTTP_STATUS.OK });
-    }
-}

package/dist/agencies/index.d.ts

@@ -1 +0,0 @@
-export * from './agencies.js';

package/dist/agencies/index.js

@@ -1 +0,0 @@
-export * from './agencies.js';

package/dist/operation/hashed-trips/hashed-trips.d.ts

@@ -1,12 +0,0 @@
-import { type FastifyReply, type FastifyRequest } from '@tmlmobilidade/fastify';
-import { type ActionsOf, type GetRidesBatchQuery, type HashedTrip, type Permission } from '@tmlmobilidade/types';
-export declare class HashedTripsSharedController {
-    /**
-     * Gets a batch of HashedTrips built with an aggregation pipeline.
-     * @param request The Fastify request object.
-     * @param reply The Fastify reply object.
-     */
-    static getBatch<S extends Permission['scope']>(request: FastifyRequest<{
-        Querystring: GetRidesBatchQuery;
-    }>, reply: FastifyReply<HashedTrip[]>, scope: S, action: ActionsOf<S>): Promise<never>;
-}

package/dist/operation/hashed-trips/hashed-trips.js

@@ -1,77 +0,0 @@
-/* * */
-import { HTTP_STATUS } from '@tmlmobilidade/consts';
-import { goDb } from '@tmlmobilidade/go-interfaces-godb';
-import { ridesBatchAggregationPipeline } from '@tmlmobilidade/interfaces';
-import { Logger } from '@tmlmobilidade/logger';
-import { GetRidesBatchQuerySchema, PermissionCatalog } from '@tmlmobilidade/types';
-/* * */
-export class HashedTripsSharedController {
-    //
-    /**
-     * Gets a batch of HashedTrips built with an aggregation pipeline.
-     * @param request The Fastify request object.
-     * @param reply The Fastify reply object.
-     */
-    static async getBatch(request, reply, scope, action) {
-        //
-        //
-        // Validate the request query parameters
-        const parsedQuery = GetRidesBatchQuerySchema.parse(request.query);
-        //
-        // Detect which agency_ids the user has access to,
-        // based on their permissions. If none, return an empty array.
-        const ridesPermission = PermissionCatalog.get(request.permissions, scope, action);
-        if (!ridesPermission['resources']?.agency_ids?.length) {
-            Logger.issue({
-                context: {
-                    action: 'getBatch',
-                    feature: 'hashedTrips',
-                    request,
-                },
-                level: 'info',
-                messageOrError: 'No agency_ids found in permissions',
-            });
-            return reply.send({ data: [], error: null, statusCode: HTTP_STATUS.OK });
-        }
-        const allowAllAgencies = ridesPermission['resources'].agency_ids.includes(PermissionCatalog.ALLOW_ALL_FLAG);
-        //
-        // Get the rides batch using native MongoDB cursor
-        // with batchSize to prevent memory issues
-        const pipeline = ridesBatchAggregationPipeline({
-            acceptance_status: parsedQuery.acceptance_status,
-            agency_ids: parsedQuery.agency_ids?.filter(id => allowAllAgencies || ridesPermission['resources'].agency_ids.includes(id)) ?? [],
-            analysis_ended_at_last_stop_grade: parsedQuery.analysis_ended_at_last_stop_grade,
-            analysis_expected_apex_validation_interval: parsedQuery.analysis_expected_apex_validation_interval,
-            analysis_simple_three_vehicle_events_grade: parsedQuery.analysis_simple_three_vehicle_events_grade,
-            analysis_transaction_sequentiality: parsedQuery.analysis_transaction_sequentiality,
-            date_end: parsedQuery.date_end,
-            date_start: parsedQuery.date_start,
-            delay_statuses: parsedQuery.delay_statuses,
-            line_ids: parsedQuery.line_ids,
-            operational_statuses: parsedQuery.operational_statuses,
-            search: parsedQuery.search,
-            seen_statuses: parsedQuery.seen_statuses,
-            stop_ids: parsedQuery.stop_ids,
-        });
-        //
-        // Limit the number of rides to 2000 and sort by start_time_scheduled
-        pipeline.push({ $limit: 2000 }, { $project: { hashed_trip_id: 1 } }, { $sort: { start_time_scheduled: 1 } });
-        //
-        // Fetch the rides batch from the database
-        const ridesBatch = await goDb.operation.rides.aggregate(pipeline);
-        Logger.info({ message: `HashedTripsSharedController.getBatch - ridesBatch count: ${ridesBatch?.length ?? 0}` });
-        //
-        // From the given batch of hashed_trip_ids,
-        // fetch the full HashedTrip documents with a single query.
-        const hashedTripIds = ridesBatch.map(ride => ride.hashed_trip_id);
-        const hashedTripsBatch = await goDb.operation.hashedTrips.findMany({ _id: { $in: hashedTripIds } });
-        //
-        // Send the response
-        reply.send({
-            data: hashedTripsBatch ?? [],
-            error: null,
-            statusCode: HTTP_STATUS.OK,
-        });
-        //
-    }
-}

package/dist/operation/hashed-trips/index.d.ts

@@ -1 +0,0 @@
-export * from './hashed-trips.js';

package/dist/operation/hashed-trips/index.js

@@ -1 +0,0 @@
-export * from './hashed-trips.js';

package/dist/operation/index.d.ts

@@ -1,4 +0,0 @@
-export * from './hashed-trips/index.js';
-export * from './lines/index.js';
-export * from './rides/index.js';
-export * from './stops/index.js';

package/dist/operation/index.js

@@ -1,4 +0,0 @@
-export * from './hashed-trips/index.js';
-export * from './lines/index.js';
-export * from './rides/index.js';
-export * from './stops/index.js';

package/dist/operation/lines/batch.d.ts

@@ -1,2 +0,0 @@
-import { type GetOperationalLinesBatchQuery, type OperationalLine } from '@tmlmobilidade/types';
-export declare function getOperationalLinesBatch(query: GetOperationalLinesBatchQuery): Promise<OperationalLine[]>;

package/dist/operation/lines/batch.js

@@ -1,111 +0,0 @@
-/* * */
-import { goDb } from '@tmlmobilidade/go-interfaces-godb';
-import { Logger } from '@tmlmobilidade/logger';
-/* * */
-export async function getOperationalLinesBatch(query) {
-    //
-    //
-    // Use Rides as the baseline to fetch distinct hashed_pattern_ids matching the query parameters.
-    // Rides are the glue between the different entities (Patterns, Lines, Stops, etc...) that compose an Operation,
-    // Stream the rides to build the Operation Lines batch on the fly, avoiding loading everything in memory at once.
-    const pipeline = [
-        {
-            $match: {
-                agency_id: { $in: query.agency_ids ?? [] },
-                start_time_scheduled: { $gte: query.date_start, $lte: query.date_end },
-            },
-        },
-        {
-            $group: {
-                _id: '$hashed_pattern_id',
-                latest_ride: {
-                    $top: {
-                        output: {
-                            agency_id: '$agency_id',
-                            hashed_pattern_id: '$hashed_pattern_id',
-                            operational_date: '$operational_date',
-                            plan_id: '$plan_id',
-                            start_time_scheduled: '$start_time_scheduled',
-                        },
-                        // deterministic tie-break if same timestamp appears multiple times
-                        // eslint-disable-next-line perfectionist/sort-objects
-                        sortBy: { start_time_scheduled: -1, _id: -1 },
-                    },
-                },
-            },
-        },
-        {
-            $replaceRoot: {
-                newRoot: '$latest_ride',
-            },
-        },
-        {
-            $sort: {
-                start_time_scheduled: -1,
-            },
-        },
-        {
-            $lookup: {
-                as: 'hashed_pattern_doc',
-                foreignField: '_id',
-                from: 'hashed-patterns',
-                localField: 'hashed_pattern_id',
-            },
-        },
-        {
-            $unwind: {
-                path: '$hashed_pattern_doc',
-                preserveNullAndEmptyArrays: true,
-            },
-        },
-        {
-            $project: {
-                _id: 0,
-                agency_id: 1,
-                hashed_pattern_doc: 1, // full joined document
-                operational_date: 1,
-                plan_id: 1,
-                start_time_scheduled: 1,
-            },
-        },
-    ];
-    const ridesCollection = await goDb.operation.rides.getCollection();
-    const pipelineResult = await ridesCollection
-        .aggregate(pipeline, { allowDiskUse: true })
-        .toArray();
-    Logger.info({ message: `OperationalLinesController.getBatch - pipeline result count: ${pipelineResult?.length ?? 0}` });
-    //
-    // Setup the final Map to keep track of the Operation Lines,
-    // using the line_id as the key to avoid duplicates,
-    // since multiple hashed_pattern_ids can belong to the same line_id.
-    const operationalLinesMap = new Map();
-    pipelineResult.forEach((item) => {
-        // Initialize the line in the map if it doesn't exist yet
-        if (!operationalLinesMap.has(item.hashed_pattern_doc.line_id)) {
-            operationalLinesMap.set(item.hashed_pattern_doc.line_id, {
-                agency_id: item.agency_id,
-                hashed_patterns: [],
-                last_operational_date: item.operational_date,
-                last_plan_id: item.plan_id,
-                line_id: item.hashed_pattern_doc.line_id,
-                line_long_name: item.hashed_pattern_doc.line_long_name,
-                line_short_name: item.hashed_pattern_doc.line_short_name,
-                pattern_ids: [],
-                route_color: item.hashed_pattern_doc.route_color,
-                route_ids: [],
-                stop_ids: [],
-            });
-        }
-        // Get the saved line from the map
-        const savedOperationalLine = operationalLinesMap.get(item.hashed_pattern_doc.line_id);
-        // Update the object with the latest fields
-        savedOperationalLine.route_ids = Array.from(new Set([...savedOperationalLine.route_ids, item.hashed_pattern_doc.route_id]));
-        savedOperationalLine.pattern_ids = Array.from(new Set([...savedOperationalLine.pattern_ids, item.hashed_pattern_doc.pattern_id]));
-        savedOperationalLine.stop_ids = Array.from(new Set([...savedOperationalLine.stop_ids, ...(item.hashed_pattern_doc.path.map(stop => stop.stop_id) ?? [])]));
-        savedOperationalLine.hashed_patterns.push(item.hashed_pattern_doc);
-    });
-    //
-    // Send the response
-    return Array.from(operationalLinesMap.values());
-    //
-}

package/dist/operation/lines/controller.d.ts

@@ -1,12 +0,0 @@
-import { type FastifyReply, type FastifyRequest } from '@tmlmobilidade/fastify';
-import { type ActionsOf, type GetOperationalLinesBatchQuery, type OperationalLine, type Permission } from '@tmlmobilidade/types';
-export declare class OperationalLinesSharedController {
-    /**
-     * Gets a batch of Operation Lines built with an aggregation pipeline.
-     * @param request The Fastify request object.
-     * @param reply The Fastify reply object.
-     */
-    static getBatch<S extends Permission['scope']>(request: FastifyRequest<{
-        Querystring: GetOperationalLinesBatchQuery;
-    }>, reply: FastifyReply<OperationalLine[]>, scope: S, action: ActionsOf<S>): Promise<never>;
-}

package/dist/operation/lines/controller.js

@@ -1,49 +0,0 @@
-/* * */
-import { getOperationalLinesBatch } from './batch.js';
-import { HTTP_STATUS } from '@tmlmobilidade/consts';
-import { Logger } from '@tmlmobilidade/logger';
-import { GetOperationalLinesBatchQuerySchema, PermissionCatalog } from '@tmlmobilidade/types';
-/* * */
-export class OperationalLinesSharedController {
-    //
-    /**
-     * Gets a batch of Operation Lines built with an aggregation pipeline.
-     * @param request The Fastify request object.
-     * @param reply The Fastify reply object.
-     */
-    static async getBatch(request, reply, scope, action) {
-        //
-        const parsedQuery = GetOperationalLinesBatchQuerySchema.parse(request.query);
-        //
-        // Detect which agency_ids the user has access to,
-        // based on their permissions. If none, return an empty array.
-        const ridesPermission = PermissionCatalog.get(request.permissions, scope, action);
-        if (!ridesPermission['resources']?.agency_ids?.length) {
-            Logger.issue({
-                context: {
-                    action: 'getBatch',
-                    feature: 'operationalLines',
-                    request,
-                },
-                level: 'info',
-                messageOrError: 'No agency_ids found in permissions',
-            });
-            return reply.send({ data: [], error: null, statusCode: HTTP_STATUS.OK });
-        }
-        const allowAllAgencies = ridesPermission['resources'].agency_ids.includes(PermissionCatalog.ALLOW_ALL_FLAG);
-        //
-        // Run the query
-        const result = await getOperationalLinesBatch({
-            ...parsedQuery,
-            agency_ids: parsedQuery.agency_ids?.filter(id => allowAllAgencies || ridesPermission['resources'].agency_ids.includes(id)) ?? [],
-        });
-        //
-        // Send the response
-        reply.send({
-            data: result,
-            error: null,
-            statusCode: HTTP_STATUS.OK,
-        });
-        //
-    }
-}

package/dist/operation/lines/index.d.ts

@@ -1,2 +0,0 @@
-export * from './batch.js';
-export * from './controller.js';

package/dist/operation/lines/index.js

@@ -1,2 +0,0 @@
-export * from './batch.js';
-export * from './controller.js';

package/dist/operation/rides/index.d.ts

@@ -1,2 +0,0 @@
-export * from './rides.js';
-export * from './watch.js';

package/dist/operation/rides/index.js

@@ -1,2 +0,0 @@
-export * from './rides.js';
-export * from './watch.js';

package/dist/operation/rides/rides.d.ts

@@ -1,31 +0,0 @@
-import { type FastifyReply, type FastifyRequest } from '@tmlmobilidade/fastify';
-import { type ActionsOf, type GetRidesBatchQuery, type Permission, type RideNormalized } from '@tmlmobilidade/types';
-import { type WebSocket } from 'ws';
-export declare class RidesSharedController {
-    /**
-     * Gets a batch of Rides built with an aggregation pipeline.
-     * @param request The Fastify request object.
-     * @param reply The Fastify reply object.
-     */
-    static getBatch<S extends Permission['scope']>(request: FastifyRequest<{
-        Querystring: GetRidesBatchQuery;
-    }>, reply: FastifyReply<RideNormalized[]>, scope: S, action: ActionsOf<S>): Promise<never>;
-    /**
-     * Get a Ride by ID.
-     * @param request The Fastify request object.
-     * @param reply The Fastify reply object.
-     */
-    static getRideById<S extends Permission['scope']>(request: FastifyRequest, reply: FastifyReply<RideNormalized>, scope: S, action: ActionsOf<S>): Promise<never>;
-    /**
-     * Get a Ride by multiple IDs.
-     * @param request The Fastify request object.
-     * @param reply The Fastify reply object.
-     */
-    n: any;
-    static getRideByIds<S extends Permission['scope']>(request: FastifyRequest, reply: FastifyReply<RideNormalized[]>, scope: S, action: ActionsOf<S>): Promise<never>;
-    /**
-     * WebSocket event handler.
-     * @param socket The WebSocket object.
-     */
-    static websocket(socket: WebSocket): () => void;
-}

package/dist/operation/rides/rides.js

@@ -1,191 +0,0 @@
-/* * */
-import { ridesChangeStream } from './watch.js';
-import { HTTP_STATUS } from '@tmlmobilidade/consts';
-import { goDb } from '@tmlmobilidade/go-interfaces-godb';
-import { ridesBatchAggregationPipeline } from '@tmlmobilidade/interfaces';
-import { Logger } from '@tmlmobilidade/logger';
-import { normalizeRide } from '@tmlmobilidade/normalizers';
-import { GetRidesBatchQuerySchema, PermissionCatalog } from '@tmlmobilidade/types';
-/* * */
-export class RidesSharedController {
-    //
-    /**
-     * Gets a batch of Rides built with an aggregation pipeline.
-     * @param request The Fastify request object.
-     * @param reply The Fastify reply object.
-     */
-    static async getBatch(request, reply, scope, action) {
-        //
-        //
-        // Validate the request query parameters
-        const parsedQuery = GetRidesBatchQuerySchema.parse(request.query);
-        //
-        // Detect which agency_ids the user has access to,
-        // based on their permissions. If none, return an empty array.
-        const ridesPermission = PermissionCatalog.get(request.permissions, scope, action);
-        if (!ridesPermission['resources']?.agency_ids?.length) {
-            Logger.issue({
-                context: {
-                    action: 'getBatch',
-                    feature: 'rides',
-                    request,
-                },
-                level: 'info',
-                messageOrError: 'No agency_ids found in permissions',
-            });
-            return reply.send({ data: [], error: null, statusCode: HTTP_STATUS.OK });
-        }
-        const allowAllAgencies = ridesPermission['resources'].agency_ids.includes(PermissionCatalog.ALLOW_ALL_FLAG);
-        //
-        // If search is provided, immediately try to find the ride by ID.
-        // If found, return it as the only result. This optimizes
-        // for the common case of searching by ride ID.
-        const searchQuery = parsedQuery.search?.trim() ?? '';
-        const foundRideById = await goDb.operation.rides.findOne({
-            _id: searchQuery,
-            ...(allowAllAgencies ? {} : { agency_id: { $in: ridesPermission['resources'].agency_ids } }),
-        });
-        if (foundRideById) {
-            const normalizedRide = normalizeRide(foundRideById);
-            return reply.send({ data: [normalizedRide], error: null, statusCode: HTTP_STATUS.OK });
-        }
-        //
-        // Get the rides batch using native MongoDB cursor
-        // with batchSize to prevent memory issues
-        const pipeline = ridesBatchAggregationPipeline({
-            acceptance_status: parsedQuery.acceptance_status,
-            agency_ids: parsedQuery.agency_ids?.filter(id => allowAllAgencies || ridesPermission['resources'].agency_ids.includes(id)) ?? [],
-            analysis_ended_at_last_stop_grade: parsedQuery.analysis_ended_at_last_stop_grade,
-            analysis_expected_apex_validation_interval: parsedQuery.analysis_expected_apex_validation_interval,
-            analysis_simple_three_vehicle_events_grade: parsedQuery.analysis_simple_three_vehicle_events_grade,
-            analysis_transaction_sequentiality: parsedQuery.analysis_transaction_sequentiality,
-            date_end: parsedQuery.date_end,
-            date_start: parsedQuery.date_start,
-            delay_statuses: parsedQuery.delay_statuses,
-            line_ids: parsedQuery.line_ids,
-            operational_statuses: parsedQuery.operational_statuses,
-            search: parsedQuery.search,
-            seen_statuses: parsedQuery.seen_statuses,
-            stop_ids: parsedQuery.stop_ids,
-            //
-            ticketing_status: parsedQuery.ticketing_status,
-        });
-        //
-        // Limit the number of rides to 2000 and sort by start_time_scheduled
-        pipeline.push({ $limit: 2000 }, { $sort: { start_time_scheduled: 1 } });
-        //
-        // Fetch the rides batch from the database
-        const ridesBatch = await goDb.operation.rides.aggregate(pipeline);
-        //
-        // Send the response
-        reply.send({
-            data: ridesBatch ?? [],
-            error: null,
-            statusCode: HTTP_STATUS.OK,
-        });
-        //
-    }
-    /**
-     * Get a Ride by ID.
-     * @param request The Fastify request object.
-     * @param reply The Fastify reply object.
-     */
-    static async getRideById(request, reply, scope, action) {
-        //
-        //
-        // Detect which agency_ids the user has access to,
-        // based on their permissions. If none, return an empty array.
-        const ridesPermission = PermissionCatalog.get(request.permissions, scope, action);
-        if (!ridesPermission['resources']?.agency_ids?.length) {
-            Logger.issue({
-                context: {
-                    action: 'getRideById',
-                    feature: 'rides',
-                    request,
-                    value: request.params['id'],
-                },
-                level: 'info',
-                messageOrError: 'No agency_ids found in permissions',
-            });
-            return reply.send({ data: null, error: null, statusCode: HTTP_STATUS.OK });
-        }
-        const allowAllAgencies = ridesPermission['resources'].agency_ids.includes(PermissionCatalog.ALLOW_ALL_FLAG);
-        //
-        // If search is provided, immediately try to find the ride by ID.
-        // If found, return it as the only result. This optimizes
-        // for the common case of searching by ride ID.
-        const foundRideById = await goDb.operation.rides.findOne({
-            _id: request.params['id'],
-            ...(allowAllAgencies ? {} : { agency_id: { $in: ridesPermission['resources'].agency_ids } }),
-        });
-        if (foundRideById) {
-            const normalizedRide = normalizeRide(foundRideById);
-            return reply.send({ data: normalizedRide, error: null, statusCode: HTTP_STATUS.OK });
-        }
-        //
-    }
-    /**
-     * Get a Ride by multiple IDs.
-     * @param request The Fastify request object.
-     * @param reply The Fastify reply object.
-     */
-    n;
-    static async getRideByIds(request, reply, scope, action) {
-        //
-        //
-        // Detect which agency_ids the user has access to,
-        // based on their permissions. If none, return an empty array.
-        const ridesPermission = PermissionCatalog.get(request.permissions, scope, action);
-        if (!ridesPermission['resources']?.agency_ids?.length) {
-            Logger.issue({
-                context: {
-                    action: 'getRideByIds',
-                    feature: 'rides',
-                    request,
-                    value: request.query['ids'],
-                },
-                level: 'info',
-                messageOrError: 'No agency_ids found in permissions',
-            });
-            return reply.send({ data: null, error: null, statusCode: HTTP_STATUS.OK });
-        }
-        const allowAllAgencies = ridesPermission['resources'].agency_ids.includes(PermissionCatalog.ALLOW_ALL_FLAG);
-        //
-        // If search is provided, immediately try to find the ride by ID.
-        // If found, return it as the only result. This optimizes
-        // for the common case of searching by ride ID.
-        const ids = request.query['ids']?.split(',') ?? [];
-        const foundRidesByIds = await goDb.operation.rides.findMany({
-            _id: { $in: ids },
-            ...(allowAllAgencies ? {} : { agency_id: { $in: ridesPermission['resources'].agency_ids } }),
-        });
-        return reply.send({ data: foundRidesByIds.map(ride => normalizeRide(ride)), error: null, statusCode: HTTP_STATUS.OK });
-        //
-    }
-    /**
-     * WebSocket event handler.
-     * @param socket The WebSocket object.
-     */
-    static websocket(socket) {
-        //
-        //
-        // Create a listener that sends updates to this WebSocket client
-        const listener = (message) => {
-            if (socket.readyState === socket.OPEN && socket.bufferedAmount < 1_000_000) {
-                socket.send(JSON.stringify(message));
-            }
-        };
-        //
-        // Subscribe to the singleton change stream immediately.
-        // Sockets do not emit 'open' or 'connection' events server-side.
-        ridesChangeStream.subscribe(listener);
-        //
-        // Cleanup the subscription to the singleton change stream
-        const cleanup = () => {
-            ridesChangeStream.unsubscribe(listener);
-        };
-        socket.on('close', cleanup);
-        socket.on('error', cleanup);
-        return cleanup;
-    }
-}

package/dist/operation/rides/watch.d.ts

@@ -1,56 +0,0 @@
-import { RideNormalized } from '@tmlmobilidade/types';
-import { HttpResponse } from '@tmlmobilidade/utils';
-/**
- * A listener function for ride changes.
- * Receives normalized ride data wrapped in an HTTP response format.
- */
-export type RideChangeListener = (message: HttpResponse<RideNormalized>) => void;
-/**
- * Singleton manager for MongoDB change streams with pub/sub capabilities.
- *
- * This class creates a single MongoDB change stream that watches for ride updates
- * and broadcasts them to multiple subscribers using an in-memory EventEmitter.
- *
- * The singleton pattern ensures only one change stream is active, regardless of
- * how many WebSocket clients are connected.
- */
-declare class RidesChangeStreamManager {
-    private static instance;
-    /**
-    * In-memory pub/sub event emitter. (@see https://nodejs.org/api/events.html#class-eventemitter)
-    *
-    * This EventEmitter acts as the pub/sub broker between the MongoDB change stream
-    * and WebSocket clients:
-    * - The MongoDB change stream publishes to this emitter when rides change
-    * - WebSocket clients subscribe to this emitter to receive updates
-    * - When unsubscribing, clients are removed from the emitter's listener list
-    *
-    * Setting maxListeners to 0 allows unlimited subscribers without warnings,
-    * which is necessary since we may have many concurrent WebSocket connections.
-    */
-    private emitter;
-    private initialized;
-    /**
-     * Private constructor enforces singleton pattern.
-     * Use `getInstance()` to access the instance.
-     */
-    private constructor();
-    static getInstance(): Promise<RidesChangeStreamManager>;
-    subscribe(listener: RideChangeListener): void;
-    unsubscribe(listener: RideChangeListener): void;
-    /**
-     * Initializes the MongoDB change stream.
-     *
-     * This is called once during getInstance() to set up the change stream.
-     * The stream watches all operations on the rides collection and publishes
-     * changes to the EventEmitter.
-     *
-     * Flow:
-     * 1. MongoDB detects a change → 2. Change stream emits 'change' event →
-     * 3. Normalizes the ride data → 4. Publishes to EventEmitter →
-     * 5. All subscribed listeners receive the update
-     */
-    private init;
-}
-export declare const ridesChangeStream: RidesChangeStreamManager;
-export {};

package/dist/operation/rides/watch.js

@@ -1,113 +0,0 @@
-/* * */
-/**
- * Rides Change Stream Manager
- *
- * This module implements a singleton pattern for MongoDB change streams with in-memory pub/sub:
- *
- * Architecture:
- * ```
- * MongoDB Change Stream (1 singleton)
- *         ↓
- *  EventEmitter pub/sub
- *         ↓
- *   WebSocket clients
- * ```
- *
- * Instead of creating a MongoDB change stream per WebSocket connection (inefficient),
- * this creates a single change stream that publishes to an in-memory EventEmitter.
- * Multiple WebSocket clients can subscribe/unsubscribe to receive real-time updates.
- *
- * Benefits:
- * - Single MongoDB change stream regardless of number of clients
- * - Lazy initialization - stream only starts when first client connects through "asyncSingletonProxy"
- * - Clean subscription management per client
- * - Reduced database load and network overhead
-*/
-import { HTTP_STATUS } from '@tmlmobilidade/consts';
-import { goDb } from '@tmlmobilidade/go-interfaces-godb';
-import { normalizeRide } from '@tmlmobilidade/normalizers';
-import { asyncSingletonProxy } from '@tmlmobilidade/utils';
-import EventEmitter from 'events';
-/**
- * Singleton manager for MongoDB change streams with pub/sub capabilities.
- *
- * This class creates a single MongoDB change stream that watches for ride updates
- * and broadcasts them to multiple subscribers using an in-memory EventEmitter.
- *
- * The singleton pattern ensures only one change stream is active, regardless of
- * how many WebSocket clients are connected.
- */
-class RidesChangeStreamManager {
-    //
-    static instance = null;
-    /**
-    * In-memory pub/sub event emitter. (@see https://nodejs.org/api/events.html#class-eventemitter)
-    *
-    * This EventEmitter acts as the pub/sub broker between the MongoDB change stream
-    * and WebSocket clients:
-    * - The MongoDB change stream publishes to this emitter when rides change
-    * - WebSocket clients subscribe to this emitter to receive updates
-    * - When unsubscribing, clients are removed from the emitter's listener list
-    *
-    * Setting maxListeners to 0 allows unlimited subscribers without warnings,
-    * which is necessary since we may have many concurrent WebSocket connections.
-    */
-    emitter = new EventEmitter();
-    initialized = false;
-    /**
-     * Private constructor enforces singleton pattern.
-     * Use `getInstance()` to access the instance.
-     */
-    constructor() {
-        this.emitter.setMaxListeners(0); // Allow unlimited listeners
-    }
-    static async getInstance() {
-        if (!RidesChangeStreamManager.instance) {
-            RidesChangeStreamManager.instance = new RidesChangeStreamManager();
-            await RidesChangeStreamManager.instance.init();
-        }
-        return RidesChangeStreamManager.instance;
-    }
-    subscribe(listener) {
-        this.emitter.on('change', listener);
-    }
-    unsubscribe(listener) {
-        this.emitter.off('change', listener);
-    }
-    /**
-     * Initializes the MongoDB change stream.
-     *
-     * This is called once during getInstance() to set up the change stream.
-     * The stream watches all operations on the rides collection and publishes
-     * changes to the EventEmitter.
-     *
-     * Flow:
-     * 1. MongoDB detects a change → 2. Change stream emits 'change' event →
-     * 3. Normalizes the ride data → 4. Publishes to EventEmitter →
-     * 5. All subscribed listeners receive the update
-     */
-    async init() {
-        if (this.initialized)
-            return;
-        const ridesCollection = await goDb.operation.rides.getCollection();
-        // Watch all operations with full document updates
-        ridesCollection
-            .watch([], { fullDocument: 'updateLookup' })
-            .on('change', (databaseOperation) => {
-            if (typeof databaseOperation['fullDocument'] === 'undefined') {
-                console.log('Undefined document:', databaseOperation);
-                return;
-            }
-            const normalizedRide = normalizeRide(databaseOperation['fullDocument']);
-            const message = {
-                data: normalizedRide,
-                error: null,
-                statusCode: HTTP_STATUS.OK,
-            };
-            // Publish to all subscribers via EventEmitter
-            this.emitter.emit('change', message);
-        });
-        this.initialized = true;
-    }
-}
-export const ridesChangeStream = asyncSingletonProxy(RidesChangeStreamManager);

package/dist/operation/stops/batch.d.ts

@@ -1,2 +0,0 @@
-import { type GetOperationalStopsBatchQuery, type OperationalStop } from '@tmlmobilidade/types';
-export declare function getOperationalStopsBatch(query: GetOperationalStopsBatchQuery): Promise<OperationalStop[]>;

package/dist/operation/stops/batch.js

@@ -1,112 +0,0 @@
-/* * */
-import { goDb } from '@tmlmobilidade/go-interfaces-godb';
-import { Logger } from '@tmlmobilidade/logger';
-/* * */
-export async function getOperationalStopsBatch(query) {
-    //
-    //
-    // Use Rides as the baseline to fetch distinct hashed_pattern_ids matching the query parameters.
-    // Rides are the glue between the different entities (Patterns, Lines, Stops, etc...) that compose an Operation,
-    // Stream the rides to build the Operation Stops batch on the fly, avoiding loading everything in memory at once.
-    const pipeline = [
-        {
-            $match: {
-                agency_id: { $in: query.agency_ids ?? [] },
-                start_time_scheduled: { $gte: query.date_start, $lte: query.date_end },
-            },
-        },
-        {
-            $group: {
-                _id: '$hashed_pattern_id',
-                latest_ride: {
-                    $top: {
-                        output: {
-                            agency_id: '$agency_id',
-                            hashed_pattern_id: '$hashed_pattern_id',
-                            operational_date: '$operational_date',
-                            plan_id: '$plan_id',
-                            start_time_scheduled: '$start_time_scheduled',
-                        },
-                        // deterministic tie-break if same timestamp appears multiple times
-                        // eslint-disable-next-line perfectionist/sort-objects
-                        sortBy: { start_time_scheduled: -1, _id: -1 },
-                    },
-                },
-            },
-        },
-        {
-            $replaceRoot: {
-                newRoot: '$latest_ride',
-            },
-        },
-        {
-            $sort: {
-                start_time_scheduled: -1,
-            },
-        },
-        {
-            $lookup: {
-                as: 'hashed_pattern_doc',
-                foreignField: '_id',
-                from: 'hashed-patterns',
-                localField: 'hashed_pattern_id',
-            },
-        },
-        {
-            $unwind: {
-                path: '$hashed_pattern_doc',
-                preserveNullAndEmptyArrays: true,
-            },
-        },
-        {
-            $project: {
-                _id: 0,
-                agency_id: 1,
-                hashed_pattern_doc: 1, // full joined document
-                operational_date: 1,
-                plan_id: 1,
-                start_time_scheduled: 1,
-            },
-        },
-    ];
-    const ridesCollection = await goDb.operation.rides.getCollection();
-    const pipelineResult = await ridesCollection
-        .aggregate(pipeline, { allowDiskUse: true })
-        .toArray();
-    Logger.info({ message: `OperationalStopsController.getBatch - pipeline result count: ${pipelineResult?.length ?? 0}` });
-    //
-    // Setup the final Map to keep track of the Operation Stops,
-    // using the stop_id as the key to avoid duplicates,
-    // since multiple hashed_pattern_ids can belong to the same stop_id.
-    const operationalStopsMap = new Map();
-    pipelineResult.forEach((item) => {
-        item.hashed_pattern_doc.path.forEach((waypoint) => {
-            // Initialize the stop in the map if it doesn't exist yet
-            if (!operationalStopsMap.has(waypoint.stop_id)) {
-                operationalStopsMap.set(waypoint.stop_id, {
-                    agency_ids: [],
-                    hashed_patterns: [],
-                    last_operational_date: item.operational_date,
-                    last_plan_id: item.plan_id,
-                    line_ids: [],
-                    pattern_ids: [],
-                    route_ids: [],
-                    stop_id: waypoint.stop_id,
-                    stop_name: waypoint.stop_name,
-                });
-            }
-            // Get the saved stop from the map
-            const savedOperationalStop = operationalStopsMap.get(waypoint.stop_id);
-            // Update the object with the latest fields
-            savedOperationalStop.agency_ids = Array.from(new Set([...savedOperationalStop.agency_ids, item.agency_id]));
-            savedOperationalStop.line_ids = Array.from(new Set([...savedOperationalStop.line_ids, item.hashed_pattern_doc.line_id]));
-            savedOperationalStop.route_ids = Array.from(new Set([...savedOperationalStop.route_ids, item.hashed_pattern_doc.route_id]));
-            savedOperationalStop.pattern_ids = Array.from(new Set([...savedOperationalStop.pattern_ids, item.hashed_pattern_doc.pattern_id]));
-            savedOperationalStop.hashed_patterns.push(item.hashed_pattern_doc);
-        });
-    });
-    //
-    // Send the response
-    return Array.from(operationalStopsMap.values());
-    //
-}

package/dist/operation/stops/controller.d.ts

@@ -1,12 +0,0 @@
-import { type FastifyReply, type FastifyRequest } from '@tmlmobilidade/fastify';
-import { type ActionsOf, type GetOperationalStopsBatchQuery, type OperationalStop, type Permission } from '@tmlmobilidade/types';
-export declare class OperationalStopsSharedController {
-    /**
-     * Gets a batch of Operational Stops built with an aggregation pipeline.
-     * @param request The Fastify request object.
-     * @param reply The Fastify reply object.
-     */
-    static getBatch<S extends Permission['scope']>(request: FastifyRequest<{
-        Querystring: GetOperationalStopsBatchQuery;
-    }>, reply: FastifyReply<OperationalStop[]>, scope: S, action: ActionsOf<S>): Promise<never>;
-}

package/dist/operation/stops/controller.js

@@ -1,49 +0,0 @@
-/* * */
-import { getOperationalStopsBatch } from './batch.js';
-import { HTTP_STATUS } from '@tmlmobilidade/consts';
-import { Logger } from '@tmlmobilidade/logger';
-import { GetOperationalStopsBatchQuerySchema, PermissionCatalog } from '@tmlmobilidade/types';
-/* * */
-export class OperationalStopsSharedController {
-    //
-    /**
-     * Gets a batch of Operational Stops built with an aggregation pipeline.
-     * @param request The Fastify request object.
-     * @param reply The Fastify reply object.
-     */
-    static async getBatch(request, reply, scope, action) {
-        //
-        const parsedQuery = GetOperationalStopsBatchQuerySchema.parse(request.query);
-        //
-        // Detect which agency_ids the user has access to,
-        // based on their permissions. If none, return an empty array.
-        const ridesPermission = PermissionCatalog.get(request.permissions, scope, action);
-        if (!ridesPermission['resources']?.agency_ids?.length) {
-            Logger.issue({
-                context: {
-                    action: 'getBatch',
-                    feature: 'operationalStops',
-                    request,
-                },
-                level: 'info',
-                messageOrError: 'No agency_ids found in permissions',
-            });
-            return reply.send({ data: [], error: null, statusCode: HTTP_STATUS.OK });
-        }
-        const allowAllAgencies = ridesPermission['resources'].agency_ids.includes(PermissionCatalog.ALLOW_ALL_FLAG);
-        //
-        // Run the query
-        const result = await getOperationalStopsBatch({
-            ...parsedQuery,
-            agency_ids: parsedQuery.agency_ids?.filter(id => allowAllAgencies || ridesPermission['resources'].agency_ids.includes(id)) ?? [],
-        });
-        //
-        // Send the response
-        reply.send({
-            data: result,
-            error: null,
-            statusCode: HTTP_STATUS.OK,
-        });
-        //
-    }
-}

package/dist/operation/stops/index.d.ts

@@ -1,2 +0,0 @@
-export * from './batch.js';
-export * from './controller.js';

package/dist/operation/stops/index.js

@@ -1,2 +0,0 @@
-export * from './batch.js';
-export * from './controller.js';