@tmlmobilidade/interfaces 20260513.1602.22 → 20260514.1347.54

package/dist/interfaces/auth/roles.d.ts

@@ -33,7 +33,7 @@ declare class RolesClass extends MongoCollectionClass<Role, CreateRoleDto, Updat
             };
         } | {
             scope: "sams";
-            action: "read";
+            action: "read" | "export";
         } | {
             scope: "gtfs_validations";
             action: "create" | "read" | "lock" | "request_approval" | "update_processing_status";
@@ -60,7 +60,7 @@ declare class RolesClass extends MongoCollectionClass<Role, CreateRoleDto, Updat
             action: "create" | "update" | "delete" | "read" | "lock";
         } | {
             scope: "stops";
-            action: "create" | "update" | "delete" | "read" | "lock";
+            action: "create" | "update" | "delete" | "read" | "lock" | "edit_coordinates";
             resources: {
                 municipality_ids: string[];
                 agency_ids: string[];
@@ -163,7 +163,7 @@ declare class RolesClass extends MongoCollectionClass<Role, CreateRoleDto, Updat
             };
         } | {
             scope: "sams";
-            action: "read";
+            action: "read" | "export";
         } | {
             scope: "gtfs_validations";
             action: "create" | "read" | "lock" | "request_approval" | "update_processing_status";
@@ -190,7 +190,7 @@ declare class RolesClass extends MongoCollectionClass<Role, CreateRoleDto, Updat
             action: "create" | "update" | "delete" | "read" | "lock";
         } | {
             scope: "stops";
-            action: "create" | "update" | "delete" | "read" | "lock";
+            action: "create" | "update" | "delete" | "read" | "lock" | "edit_coordinates";
             resources: {
                 municipality_ids: string[];
                 agency_ids: string[];
@@ -289,7 +289,7 @@ declare class RolesClass extends MongoCollectionClass<Role, CreateRoleDto, Updat
             };
         } | {
             scope: "sams";
-            action: "read";
+            action: "read" | "export";
         } | {
             scope: "gtfs_validations";
             action: "create" | "read" | "lock" | "request_approval" | "update_processing_status";
@@ -316,7 +316,7 @@ declare class RolesClass extends MongoCollectionClass<Role, CreateRoleDto, Updat
             action: "create" | "update" | "delete" | "read" | "lock";
         } | {
             scope: "stops";
-            action: "create" | "update" | "delete" | "read" | "lock";
+            action: "create" | "update" | "delete" | "read" | "lock" | "edit_coordinates";
             resources: {
                 municipality_ids: string[];
                 agency_ids: string[];

package/dist/interfaces/auth/users.d.ts

@@ -57,7 +57,7 @@ declare class UsersClass extends MongoCollectionClass<User_UNSAFE, CreateUserDto
             };
         } | {
             scope: "sams";
-            action: "read";
+            action: "read" | "export";
         } | {
             scope: "gtfs_validations";
             action: "create" | "read" | "lock" | "request_approval" | "update_processing_status";
@@ -84,7 +84,7 @@ declare class UsersClass extends MongoCollectionClass<User_UNSAFE, CreateUserDto
             action: "create" | "update" | "delete" | "read" | "lock";
         } | {
             scope: "stops";
-            action: "create" | "update" | "delete" | "read" | "lock";
+            action: "create" | "update" | "delete" | "read" | "lock" | "edit_coordinates";
             resources: {
                 municipality_ids: string[];
                 agency_ids: string[];
@@ -194,7 +194,7 @@ declare class UsersClass extends MongoCollectionClass<User_UNSAFE, CreateUserDto
             };
         } | {
             scope: "sams";
-            action: "read";
+            action: "read" | "export";
         } | {
             scope: "gtfs_validations";
             action: "create" | "read" | "lock" | "request_approval" | "update_processing_status";
@@ -221,7 +221,7 @@ declare class UsersClass extends MongoCollectionClass<User_UNSAFE, CreateUserDto
             action: "create" | "update" | "delete" | "read" | "lock";
         } | {
             scope: "stops";
-            action: "create" | "update" | "delete" | "read" | "lock";
+            action: "create" | "update" | "delete" | "read" | "lock" | "edit_coordinates";
             resources: {
                 municipality_ids: string[];
                 agency_ids: string[];
@@ -335,7 +335,7 @@ declare class UsersClass extends MongoCollectionClass<User_UNSAFE, CreateUserDto
             };
         } | {
             scope: "sams";
-            action: "read";
+            action: "read" | "export";
         } | {
             scope: "gtfs_validations";
             action: "create" | "read" | "lock" | "request_approval" | "update_processing_status";
@@ -362,7 +362,7 @@ declare class UsersClass extends MongoCollectionClass<User_UNSAFE, CreateUserDto
             action: "create" | "update" | "delete" | "read" | "lock";
         } | {
             scope: "stops";
-            action: "create" | "update" | "delete" | "read" | "lock";
+            action: "create" | "update" | "delete" | "read" | "lock" | "edit_coordinates";
             resources: {
                 municipality_ids: string[];
                 agency_ids: string[];
@@ -472,7 +472,7 @@ declare class UsersClass extends MongoCollectionClass<User_UNSAFE, CreateUserDto
             };
         } | {
             scope: "sams";
-            action: "read";
+            action: "read" | "export";
         } | {
             scope: "gtfs_validations";
             action: "create" | "read" | "lock" | "request_approval" | "update_processing_status";
@@ -499,7 +499,7 @@ declare class UsersClass extends MongoCollectionClass<User_UNSAFE, CreateUserDto
             action: "create" | "update" | "delete" | "read" | "lock";
         } | {
             scope: "stops";
-            action: "create" | "update" | "delete" | "read" | "lock";
+            action: "create" | "update" | "delete" | "read" | "lock" | "edit_coordinates";
             resources: {
                 municipality_ids: string[];
                 agency_ids: string[];

package/dist/interfaces/sams/aggregations/apex-versions.d.ts

@@ -0,0 +1,12 @@
+import { type AggregationPipeline } from '../../../common/aggregation-pipeline.js';
+import { type Sam } from '@tmlmobilidade/types';
+/**
+ * Builds a pipeline that enumerates all distinct `latest_apex_version`
+ * values present in SAM documents (ignores per-analysis versions).
+ *
+ * @param matchAnd - Optional array of $match conditions (ANDed).
+ * @returns Aggregation pipeline for MongoDB.
+ */
+export declare function samsApexVersionsAggregationPipeline({ matchAnd, }: {
+    matchAnd: Record<string, unknown>[];
+}): AggregationPipeline<Sam>;

package/dist/interfaces/sams/aggregations/apex-versions.js

@@ -0,0 +1,16 @@
+/* * */
+/**
+ * Builds a pipeline that enumerates all distinct `latest_apex_version`
+ * values present in SAM documents (ignores per-analysis versions).
+ *
+ * @param matchAnd - Optional array of $match conditions (ANDed).
+ * @returns Aggregation pipeline for MongoDB.
+ */
+export function samsApexVersionsAggregationPipeline({ matchAnd, }) {
+    return [
+        ...(matchAnd.length > 0 ? [{ $match: { $and: matchAnd } }] : []),
+        { $group: { _id: '$latest_apex_version' } },
+        { $match: { _id: { $nin: [null, ''] } } },
+        { $sort: { _id: -1 } },
+    ];
+}

package/dist/interfaces/sams/aggregations/batch-list.d.ts

@@ -0,0 +1,44 @@
+import { type AggregationPipeline } from '../../../common/aggregation-pipeline.js';
+import { type Sam, type SamTimelineSummary } from '@tmlmobilidade/types';
+/**
+ * `timeline_summary` on SAM list responses: months with `key`, `month`, `count`,
+ * `successful_count`, `failed_count`, plus optional `undated` (computed from `analysis`).
+ */
+export type SamsBatchListTimelineSummary = SamTimelineSummary;
+/**
+ * Builds a pipeline to return all matching SAMs for list view (no skip/limit).
+ * Excludes `analysis` from list fields; `timeline_summary` is computed from `analysis`.
+ *
+ * @param matchAnd - An array of $match conditions (ANDed).
+ * @returns Aggregation pipeline for MongoDB.
+ */
+export declare function samsBatchAggregationPipeline({ matchAnd, }: {
+    matchAnd: Record<string, unknown>[];
+}): AggregationPipeline<Sam>;
+/**
+ * Same list row shape as {@link samsBatchAggregationPipeline} for explicit `_id`s (e.g. favorites).
+ */
+export declare function samsByIdsListViewAggregationPipeline({ agencyIds, ids, restrictByAgency, }: {
+    agencyIds?: string[];
+    ids: number[];
+    restrictByAgency: boolean;
+}): AggregationPipeline<Sam>;
+/**
+ * Full SAM by id: all fields preserved; `timeline_summary` is recomputed from `analysis`.
+ */
+export declare function samsByIdAggregationPipeline(id: number): AggregationPipeline<Sam>;
+/**
+ * Returns stored timeline summary rows for explicit SAM `_id`s.
+ * Used for fast SAM list timeline hydration.
+ */
+export declare function samsByIdsTimelineSummaryAggregationPipeline({ agencyIds, ids, restrictByAgency, }: {
+    agencyIds?: string[];
+    ids: number[];
+    restrictByAgency: boolean;
+}): AggregationPipeline<Sam>;
+/**
+ * Lightweight SAM list rows without timeline data (used for fast initial list loading).
+ */
+export declare function samsBatchBaseAggregationPipeline({ matchAnd, }: {
+    matchAnd: Record<string, unknown>[];
+}): AggregationPipeline<Sam>;

package/dist/interfaces/sams/aggregations/batch-list.js

@@ -0,0 +1,217 @@
+/* * */
+import { samsAnalysisTimelineRowsExpr, samsDetailSnapExpr, samsListViewCarryFieldsExpr, samsTimelineSummaryFromBucketsExpr, } from './batch-timeline-from-analysis.js';
+/**
+ * List view: derive `timeline_summary` from embedded `analysis` (same shape as
+ * {@link samsTimelineSummaryFromBucketsExpr}: month + counts per bucket).
+ */
+function samsListFacetMergeTimelineStages() {
+    return [
+        {
+            $addFields: {
+                __carry: samsListViewCarryFieldsExpr(),
+                __rowCount: { $size: { $ifNull: ['$analysis', []] } },
+            },
+        },
+        {
+            $facet: {
+                emptyAnalysis: [
+                    { $match: { __rowCount: 0 } },
+                    {
+                        $replaceRoot: {
+                            newRoot: {
+                                $mergeObjects: [
+                                    '$__carry',
+                                    { timeline_summary: { months: [], undated: null } },
+                                ],
+                            },
+                        },
+                    },
+                ],
+                fromAnalysis: [
+                    { $match: { __rowCount: { $gt: 0 } } },
+                    { $addFields: { __rows: samsAnalysisTimelineRowsExpr() } },
+                    { $unwind: '$__rows' },
+                    {
+                        $group: {
+                            _id: { m: '$__rows.monthKey', sam: '$__carry._id' },
+                            __carry: { $first: '$__carry' },
+                            f: { $sum: '$__rows.failed' },
+                            s: { $sum: '$__rows.successful' },
+                        },
+                    },
+                    {
+                        $group: {
+                            _id: '$_id.sam',
+                            __carry: { $first: '$__carry' },
+                            buckets: { $push: { f: '$f', m: '$_id.m', s: '$s' } },
+                        },
+                    },
+                    { $addFields: { timeline_summary: samsTimelineSummaryFromBucketsExpr() } },
+                    {
+                        $replaceRoot: {
+                            newRoot: {
+                                $mergeObjects: [
+                                    '$__carry',
+                                    { timeline_summary: '$timeline_summary' },
+                                ],
+                            },
+                        },
+                    },
+                ],
+            },
+        },
+        {
+            $project: {
+                merged: { $concatArrays: ['$emptyAnalysis', '$fromAnalysis'] },
+            },
+        },
+        { $unwind: '$merged' },
+        { $replaceRoot: { newRoot: '$merged' } },
+        { $sort: { created_at: -1 } },
+    ];
+}
+function samsDetailFacetMergeTimelineStages() {
+    return [
+        {
+            $addFields: {
+                __rowCount: { $size: { $ifNull: ['$analysis', []] } },
+                __snap: samsDetailSnapExpr(),
+            },
+        },
+        {
+            $facet: {
+                emptyAnalysis: [
+                    { $match: { __rowCount: 0 } },
+                    {
+                        $replaceRoot: {
+                            newRoot: {
+                                $mergeObjects: [
+                                    '$__snap',
+                                    { timeline_summary: { months: [], undated: null } },
+                                ],
+                            },
+                        },
+                    },
+                ],
+                fromAnalysis: [
+                    { $match: { __rowCount: { $gt: 0 } } },
+                    { $addFields: { __rows: samsAnalysisTimelineRowsExpr() } },
+                    { $unwind: '$__rows' },
+                    {
+                        $group: {
+                            _id: { m: '$__rows.monthKey', sam: '$__snap._id' },
+                            __snap: { $first: '$__snap' },
+                            analysis: { $first: '$analysis' },
+                            f: { $sum: '$__rows.failed' },
+                            s: { $sum: '$__rows.successful' },
+                        },
+                    },
+                    {
+                        $group: {
+                            _id: '$_id.sam',
+                            __snap: { $first: '$__snap' },
+                            analysis: { $first: '$analysis' },
+                            buckets: { $push: { f: '$f', m: '$_id.m', s: '$s' } },
+                        },
+                    },
+                    { $addFields: { timeline_summary: samsTimelineSummaryFromBucketsExpr() } },
+                    {
+                        $replaceRoot: {
+                            newRoot: {
+                                $mergeObjects: [
+                                    '$__snap',
+                                    { timeline_summary: '$timeline_summary' },
+                                    { __analysis: '$analysis' },
+                                ],
+                            },
+                        },
+                    },
+                ],
+            },
+        },
+        {
+            $project: {
+                merged: { $concatArrays: ['$emptyAnalysis', '$fromAnalysis'] },
+            },
+        },
+        { $unwind: '$merged' },
+        { $replaceRoot: { newRoot: '$merged' } },
+    ];
+}
+/**
+ * Builds a pipeline to return all matching SAMs for list view (no skip/limit).
+ * Excludes `analysis` from list fields; `timeline_summary` is computed from `analysis`.
+ *
+ * @param matchAnd - An array of $match conditions (ANDed).
+ * @returns Aggregation pipeline for MongoDB.
+ */
+export function samsBatchAggregationPipeline({ matchAnd, }) {
+    return [
+        ...(matchAnd.length > 0 ? [{ $match: { $and: matchAnd } }] : []),
+        { $sort: { created_at: -1 } },
+        ...samsListFacetMergeTimelineStages(),
+    ];
+}
+/**
+ * Same list row shape as {@link samsBatchAggregationPipeline} for explicit `_id`s (e.g. favorites).
+ */
+export function samsByIdsListViewAggregationPipeline({ agencyIds, ids, restrictByAgency, }) {
+    const matchAnd = [{ _id: { $in: ids } }];
+    if (restrictByAgency && agencyIds?.length)
+        matchAnd.push({ agency_id: { $in: agencyIds } });
+    return [
+        { $match: { $and: matchAnd } },
+        { $sort: { created_at: -1 } },
+        ...samsListFacetMergeTimelineStages(),
+    ];
+}
+/**
+ * Full SAM by id: all fields preserved; `timeline_summary` is recomputed from `analysis`.
+ */
+export function samsByIdAggregationPipeline(id) {
+    return [
+        { $match: { _id: id } },
+        ...samsDetailFacetMergeTimelineStages(),
+    ];
+}
+/**
+ * Returns stored timeline summary rows for explicit SAM `_id`s.
+ * Used for fast SAM list timeline hydration.
+ */
+export function samsByIdsTimelineSummaryAggregationPipeline({ agencyIds, ids, restrictByAgency, }) {
+    const matchAnd = [{ _id: { $in: ids } }];
+    if (restrictByAgency && agencyIds?.length)
+        matchAnd.push({ agency_id: { $in: agencyIds } });
+    return [
+        { $match: { $and: matchAnd } },
+        {
+            $project: {
+                _id: 1,
+                timeline_summary: { $ifNull: ['$timeline_summary', { months: [] }] },
+            },
+        },
+    ];
+}
+/**
+ * Lightweight SAM list rows without timeline data (used for fast initial list loading).
+ */
+function samsListBaseProjectionStages() {
+    return [
+        {
+            $project: {
+                analysis: 0,
+                timeline_summary: 0,
+            },
+        },
+        { $sort: { created_at: -1 } },
+    ];
+}
+/**
+ * Lightweight SAM list rows without timeline data (used for fast initial list loading).
+ */
+export function samsBatchBaseAggregationPipeline({ matchAnd, }) {
+    return [
+        ...(matchAnd.length > 0 ? [{ $match: { $and: matchAnd } }] : []),
+        ...samsListBaseProjectionStages(),
+    ];
+}

package/dist/interfaces/sams/aggregations/batch-timeline-from-analysis.d.ts

@@ -0,0 +1,7 @@
+/** One row per analysis × month (or one undated row). Success = both transaction ids non-null. */
+export declare function samsAnalysisTimelineRowsExpr(): Record<string, unknown>;
+/** Build `timeline_summary` from grouped `buckets: { m, s, f }[]`. */
+export declare function samsTimelineSummaryFromBucketsExpr(): Record<string, unknown>;
+export declare function samsListViewCarryFieldsExpr(): Record<string, unknown>;
+/** Full SAM snapshot for detail merge (excludes temp fields added later in the same stage). */
+export declare function samsDetailSnapExpr(): Record<string, unknown>;

package/dist/interfaces/sams/aggregations/batch-timeline-from-analysis.js

@@ -0,0 +1,217 @@
+/* * */
+/* eslint-disable perfectionist/sort-objects -- MongoDB aggregation readability */
+const LISBON_TZ = 'Europe/Lisbon';
+/** One row per analysis × month (or one undated row). Success = both transaction ids non-null. */
+export function samsAnalysisTimelineRowsExpr() {
+    return {
+        $reduce: {
+            initialValue: [],
+            in: {
+                $let: {
+                    vars: {
+                        acc: '$$value',
+                        success: {
+                            $and: [
+                                { $ne: ['$$this.first_transaction_id', null] },
+                                { $ne: ['$$this.last_transaction_id', null] },
+                            ],
+                        },
+                    },
+                    in: {
+                        // One binding per $let: MongoDB may evaluate same `vars` object in an order
+                        // where `d0`/`d1` run before `startMs`/`endMs`, causing "undefined variable".
+                        $let: {
+                            vars: {
+                                startMs: { $ifNull: ['$$this.start_time', '$$this.end_time'] },
+                            },
+                            in: {
+                                $let: {
+                                    vars: {
+                                        endMs: { $ifNull: ['$$this.end_time', '$$this.start_time'] },
+                                    },
+                                    in: {
+                                        $let: {
+                                            vars: {
+                                                failN: { $cond: ['$$success', 0, 1] },
+                                                succN: { $cond: ['$$success', 1, 0] },
+                                            },
+                                            in: {
+                                                $cond: [
+                                                    {
+                                                        $or: [
+                                                            { $eq: ['$$startMs', null] },
+                                                            { $eq: ['$$endMs', null] },
+                                                        ],
+                                                    },
+                                                    {
+                                                        $concatArrays: [
+                                                            '$$acc',
+                                                            [{
+                                                                    failed: '$$failN',
+                                                                    monthKey: null,
+                                                                    successful: '$$succN',
+                                                                }],
+                                                        ],
+                                                    },
+                                                    {
+                                                        $let: {
+                                                            vars: {
+                                                                month0: {
+                                                                    $dateTrunc: {
+                                                                        date: {
+                                                                            $toDate: {
+                                                                                $min: ['$$startMs', '$$endMs'],
+                                                                            },
+                                                                        },
+                                                                        unit: 'month',
+                                                                        timezone: LISBON_TZ,
+                                                                    },
+                                                                },
+                                                                monthLast: {
+                                                                    $dateTrunc: {
+                                                                        date: {
+                                                                            $toDate: {
+                                                                                $max: ['$$startMs', '$$endMs'],
+                                                                            },
+                                                                        },
+                                                                        unit: 'month',
+                                                                        timezone: LISBON_TZ,
+                                                                    },
+                                                                },
+                                                            },
+                                                            in: {
+                                                                $concatArrays: [
+                                                                    '$$acc',
+                                                                    {
+                                                                        $map: {
+                                                                            as: 'idx',
+                                                                            in: {
+                                                                                $let: {
+                                                                                    vars: {
+                                                                                        monthStart: {
+                                                                                            $dateAdd: {
+                                                                                                amount: '$$idx',
+                                                                                                startDate: '$$month0',
+                                                                                                timezone: LISBON_TZ,
+                                                                                                unit: 'month',
+                                                                                            },
+                                                                                        },
+                                                                                    },
+                                                                                    in: {
+                                                                                        failed: '$$failN',
+                                                                                        monthKey: {
+                                                                                            $dateToString: {
+                                                                                                date: '$$monthStart',
+                                                                                                format: '%Y-%m',
+                                                                                                timezone: LISBON_TZ,
+                                                                                            },
+                                                                                        },
+                                                                                        successful: '$$succN',
+                                                                                    },
+                                                                                },
+                                                                            },
+                                                                            input: {
+                                                                                $range: [
+                                                                                    0,
+                                                                                    {
+                                                                                        $max: [
+                                                                                            1,
+                                                                                            {
+                                                                                                $add: [
+                                                                                                    {
+                                                                                                        $dateDiff: {
+                                                                                                            endDate: '$$monthLast',
+                                                                                                            startDate: '$$month0',
+                                                                                                            timezone: LISBON_TZ,
+                                                                                                            unit: 'month',
+                                                                                                        },
+                                                                                                    },
+                                                                                                    1,
+                                                                                                ],
+                                                                                            },
+                                                                                        ],
+                                                                                    },
+                                                                                ],
+                                                                            },
+                                                                        },
+                                                                    },
+                                                                ],
+                                                            },
+                                                        },
+                                                    },
+                                                ],
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+            input: { $ifNull: ['$analysis', []] },
+        },
+    };
+}
+/** Build `timeline_summary` from grouped `buckets: { m, s, f }[]`. */
+export function samsTimelineSummaryFromBucketsExpr() {
+    return {
+        months: {
+            $map: {
+                as: 'x',
+                in: {
+                    failed_count: '$$x.f',
+                    month: '$$x.m',
+                    successful_count: '$$x.s',
+                },
+                input: {
+                    $sortArray: {
+                        input: {
+                            $filter: {
+                                as: 'b',
+                                cond: { $ne: ['$$b.m', null] },
+                                input: '$buckets',
+                            },
+                        },
+                        sortBy: { m: 1 },
+                    },
+                },
+            },
+        },
+    };
+}
+export function samsListViewCarryFieldsExpr() {
+    return {
+        _id: '$_id',
+        agency_id: '$agency_id',
+        created_at: '$created_at',
+        latest_apex_version: '$latest_apex_version',
+        remarks: '$remarks',
+        seen_first_at: { $ifNull: ['$seen_first_at', null] },
+        seen_last_at: { $ifNull: ['$seen_last_at', null] },
+        system_status: '$system_status',
+        transactions_expected: '$transactions_expected',
+        transactions_found: '$transactions_found',
+        transactions_missing: '$transactions_missing',
+    };
+}
+/** Full SAM snapshot for detail merge (excludes temp fields added later in the same stage). */
+export function samsDetailSnapExpr() {
+    return {
+        _id: '$_id',
+        agency_id: '$agency_id',
+        analysis: '$analysis',
+        created_at: '$created_at',
+        latest_apex_version: '$latest_apex_version',
+        remarks: '$remarks',
+        seen_first_at: '$seen_first_at',
+        seen_last_at: '$seen_last_at',
+        system_status: '$system_status',
+        timeline_summary: '$timeline_summary',
+        transactions_expected: '$transactions_expected',
+        transactions_found: '$transactions_found',
+        transactions_missing: '$transactions_missing',
+        updated_at: '$updated_at',
+    };
+}
+/* eslint-enable perfectionist/sort-objects */

package/dist/interfaces/sams/aggregations/export-analysis.d.ts

@@ -0,0 +1,28 @@
+import { type AggregationPipeline } from '../../../common/aggregation-pipeline.js';
+import { type Sam } from '@tmlmobilidade/types';
+/**
+ * Optional per-analysis filters after `$unwind` (e.g. export file `start_time` / `end_time`).
+ */
+export interface SamsAnalysisExportAnalysisFilter {
+    /** If set, keep rows where `analysis.end_time` is less than or equal to this timestamp. */
+    end_time?: number;
+    /** If set, keep rows where `analysis.start_time` is greater than or equal to this timestamp. */
+    start_time?: number;
+}
+/**
+ * Builds a pipeline that returns one document per analysis record (no SAM pagination),
+ * for CSV / file export. SAM documents are restricted by optional {@link samIds} and/or
+ * {@link matchAnd} (ANDed together). Callers must pass at least one non-empty constraint;
+ * otherwise the pipeline would not filter SAMs before unwind.
+ * Then `analysis` is unwound and optionally narrowed by {@link SamsAnalysisExportAnalysisFilter}.
+ *
+ * @param samIds - Optional SAM `_id` values to include. When omitted or empty, no `_id` filter is applied.
+ * @param matchAnd - Optional list conditions ANDed with each other (and with `samIds` when set).
+ * @param analysisFilter - Optional filters on the unwound `analysis` subdocument.
+ * @returns Aggregation pipeline for MongoDB.
+ */
+export declare function samsAnalysisExportAggregationPipeline({ analysisFilter, matchAnd, samIds }: {
+    analysisFilter?: SamsAnalysisExportAnalysisFilter;
+    matchAnd?: Record<string, unknown>[];
+    samIds?: number[];
+}): AggregationPipeline<Sam>;

package/dist/interfaces/sams/aggregations/export-analysis.js

@@ -0,0 +1,57 @@
+/* * */
+/**
+ * Builds a pipeline that returns one document per analysis record (no SAM pagination),
+ * for CSV / file export. SAM documents are restricted by optional {@link samIds} and/or
+ * {@link matchAnd} (ANDed together). Callers must pass at least one non-empty constraint;
+ * otherwise the pipeline would not filter SAMs before unwind.
+ * Then `analysis` is unwound and optionally narrowed by {@link SamsAnalysisExportAnalysisFilter}.
+ *
+ * @param samIds - Optional SAM `_id` values to include. When omitted or empty, no `_id` filter is applied.
+ * @param matchAnd - Optional list conditions ANDed with each other (and with `samIds` when set).
+ * @param analysisFilter - Optional filters on the unwound `analysis` subdocument.
+ * @returns Aggregation pipeline for MongoDB.
+ */
+export function samsAnalysisExportAggregationPipeline({ analysisFilter, matchAnd, samIds }) {
+    const analysisConditions = [];
+    if (analysisFilter?.end_time != null) {
+        analysisConditions.push({ 'analysis.end_time': { $lte: analysisFilter.end_time } });
+    }
+    if (analysisFilter?.start_time != null) {
+        analysisConditions.push({ 'analysis.start_time': { $gte: analysisFilter.start_time } });
+    }
+    const docMatchConditions = [];
+    if (samIds != null && samIds.length > 0) {
+        docMatchConditions.push({ _id: { $in: samIds } });
+    }
+    if (matchAnd != null && matchAnd.length > 0) {
+        docMatchConditions.push(...matchAnd);
+    }
+    const docMatchStage = docMatchConditions.length === 0
+        ? undefined
+        : docMatchConditions.length === 1
+            ? { $match: docMatchConditions[0] }
+            : { $match: { $and: docMatchConditions } };
+    return [
+        ...(docMatchStage ? [docMatchStage] : []),
+        { $sort: { created_at: -1 } },
+        { $unwind: { path: '$analysis', preserveNullAndEmptyArrays: false } },
+        ...(analysisConditions.length > 0 ? [{ $match: { $and: analysisConditions } }] : []),
+        { $sort: { '_id': 1, 'analysis.start_time': -1 } },
+        {
+            $project: {
+                _id: 0,
+                agency_id: 1,
+                analysis: 1,
+                created_at: 1,
+                latest_apex_version: 1,
+                remarks: 1,
+                seen_first_at: 1,
+                seen_last_at: 1,
+                system_status: 1,
+                transactions_expected: 1,
+                transactions_found: 1,
+                transactions_missing: 1,
+            },
+        },
+    ];
+}

package/dist/interfaces/sams/aggregations/index.d.ts

@@ -0,0 +1,3 @@
+export * from './apex-versions.js';
+export * from './batch-list.js';
+export * from './export-analysis.js';

package/dist/interfaces/sams/aggregations/index.js

@@ -0,0 +1,3 @@
+export * from './apex-versions.js';
+export * from './batch-list.js';
+export * from './export-analysis.js';

package/dist/interfaces/sams/build-sams-match.d.ts

@@ -0,0 +1,7 @@
+import { type GetSamsBatchQuery } from '@tmlmobilidade/types';
+/**
+ * Builds `$match` AND clauses for SAM list / export from a parsed batch query (same semantics as the controller list).
+ */
+export declare function buildSamsMatch(parsedQuery: GetSamsBatchQuery, options?: {
+    includeApexVersionFilter?: boolean;
+}): Record<string, unknown>[];

package/dist/interfaces/sams/build-sams-match.js

@@ -0,0 +1,87 @@
+/* * */
+import { parseSamsDeviceSearch, parseSamsVehicleSearch } from './regex-search.js';
+import { PermissionCatalog } from '@tmlmobilidade/types';
+/* * */
+/**
+ * Escapes a regex string.
+ */
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Reserved query fields that are not used in the aggregation pipeline.
+ */
+const RESERVED_QUERY_FIELDS = new Set(['agency_ids', 'search']);
+const RANGE_QUERY_FIELDS = {
+    seen_first_at: { field: 'seen_first_at', operator: '$gte' },
+    seen_last_at: { field: 'seen_last_at', operator: '$lte' },
+};
+/**
+ * Builds `$match` AND clauses for SAM list / export from a parsed batch query (same semantics as the controller list).
+ */
+export function buildSamsMatch(parsedQuery, options = {}) {
+    const { includeApexVersionFilter = true } = options;
+    const matchAnd = [];
+    const agencyIdsForMatch = parsedQuery.agency_ids.filter(id => id !== PermissionCatalog.ALLOW_ALL_FLAG);
+    if (agencyIdsForMatch.length > 0) {
+        matchAnd.push({ agency_id: { $in: agencyIdsForMatch } });
+    }
+    const searchRaw = parsedQuery.search?.trim() ?? '';
+    if (searchRaw.length > 0) {
+        const vehicleIds = parseSamsVehicleSearch(searchRaw);
+        if (vehicleIds.length > 0) {
+            matchAnd.push({
+                $or: [
+                    { vehicle_id: { $in: vehicleIds } },
+                    { 'analysis.vehicle_id': { $in: vehicleIds } },
+                ],
+            });
+        }
+        else {
+            const deviceIds = parseSamsDeviceSearch(searchRaw);
+            if (deviceIds.length > 0) {
+                matchAnd.push({
+                    $or: [
+                        { device_id: { $in: deviceIds } },
+                        { 'analysis.device_id': { $in: deviceIds } },
+                    ],
+                });
+            }
+            else {
+                const escaped = escapeRegex(searchRaw);
+                matchAnd.push({
+                    $or: [
+                        { $expr: { $regexMatch: { input: { $toString: '$_id' }, options: 'i', regex: escaped } } },
+                        { agency_id: { $options: 'i', $regex: escaped } },
+                        { 'analysis.first_transaction_id': { $options: 'i', $regex: escaped } },
+                        { 'analysis.last_transaction_id': { $options: 'i', $regex: escaped } },
+                    ],
+                });
+            }
+        }
+    }
+    for (const [key, value] of Object.entries(parsedQuery)) {
+        if (RESERVED_QUERY_FIELDS.has(key) || value === undefined || value === null || value === '')
+            continue;
+        if (!includeApexVersionFilter && key === 'latest_apex_version')
+            continue;
+        if (key in RANGE_QUERY_FIELDS) {
+            const rangeKey = key;
+            const rangeConfig = RANGE_QUERY_FIELDS[rangeKey];
+            matchAnd.push({ [rangeConfig.field]: { [rangeConfig.operator]: value } });
+            continue;
+        }
+        if (Array.isArray(value)) {
+            if (value.length > 0) {
+                if (key === 'latest_apex_version') {
+                    matchAnd.push({ latest_apex_version: { $in: value } });
+                    continue;
+                }
+                matchAnd.push({ [key]: { $in: value } });
+            }
+            continue;
+        }
+        matchAnd.push({ [key]: value });
+    }
+    return matchAnd;
+}

package/dist/interfaces/sams/index.d.ts

@@ -1 +1,4 @@
+export * from './aggregations/index.js';
+export * from './build-sams-match.js';
+export * from './regex-search.js';
 export * from './sams.js';

package/dist/interfaces/sams/index.js

@@ -1 +1,4 @@
+export * from './aggregations/index.js';
+export * from './build-sams-match.js';
+export * from './regex-search.js';
 export * from './sams.js';

package/dist/interfaces/sams/regex-search.d.ts

@@ -0,0 +1,18 @@
+export declare const SAMS_VEHICLE_SEARCH_REGEX: RegExp;
+export declare const SAMS_DEVICE_SEARCH_REGEX: RegExp;
+/**
+ * Parses a sams vehicle search string (e.g., "v:123,456").
+ * Returns a deduplicated array of vehicle IDs as numbers.
+ * Returns an empty array if the pattern does not match.
+ *
+ * @param searchRaw - The raw vehicle search string
+ */
+export declare function parseSamsVehicleSearch(searchRaw: string): number[];
+/**
+ * Parses a sams device search string (e.g., "d:DEVICE1,DEVICE2").
+ * Returns a deduplicated array of device IDs as strings.
+ * Returns an empty array if the pattern does not match.
+ *
+ * @param searchRaw - The raw device search string
+ */
+export declare function parseSamsDeviceSearch(searchRaw: string): string[];

package/dist/interfaces/sams/regex-search.js

@@ -0,0 +1,53 @@
+/* * */
+// Regex to match vehicle searches in the format: "v:123,456,789"
+export const SAMS_VEHICLE_SEARCH_REGEX = /^v:(?<vehicleIds>\d+(?:\s*,\s*\d+)*)$/i;
+// Regex to match device searches in the format: "d:A1,B2,C3"
+export const SAMS_DEVICE_SEARCH_REGEX = /^d:(?<deviceIds>[^,\s]+(?:\s*,\s*[^,\s]+)*)$/i;
+/**
+ * Parses a sams vehicle search string (e.g., "v:123,456").
+ * Returns a deduplicated array of vehicle IDs as numbers.
+ * Returns an empty array if the pattern does not match.
+ *
+ * @param searchRaw - The raw vehicle search string
+ */
+export function parseSamsVehicleSearch(searchRaw) {
+    // Remove any leading/trailing whitespace
+    const normalizedSearch = searchRaw.trim();
+    // Execute regex to extract vehicleIds group
+    const regexMatch = SAMS_VEHICLE_SEARCH_REGEX.exec(normalizedSearch);
+    // If there is no match or vehicleIds group, return []
+    if (!regexMatch?.groups?.vehicleIds)
+        return [];
+    // Split by comma, trim whitespace, convert to numbers, and filter invalid numbers
+    // Use Set to remove duplicates
+    return [
+        ...new Set(regexMatch.groups.vehicleIds
+            .split(',')
+            .map(item => Number(item.trim()))
+            .filter(item => Number.isInteger(item))),
+    ];
+}
+/**
+ * Parses a sams device search string (e.g., "d:DEVICE1,DEVICE2").
+ * Returns a deduplicated array of device IDs as strings.
+ * Returns an empty array if the pattern does not match.
+ *
+ * @param searchRaw - The raw device search string
+ */
+export function parseSamsDeviceSearch(searchRaw) {
+    // Remove any leading/trailing whitespace
+    const normalizedSearch = searchRaw.trim();
+    // Execute regex to extract deviceIds group
+    const regexMatch = SAMS_DEVICE_SEARCH_REGEX.exec(normalizedSearch);
+    // If there is no match or deviceIds group, return []
+    if (!regexMatch?.groups?.deviceIds)
+        return [];
+    // Split by comma, trim whitespace, filter out empty values
+    // Use Set to remove duplicates
+    return [
+        ...new Set(regexMatch.groups.deviceIds
+            .split(',')
+            .map(item => item.trim())
+            .filter(Boolean)),
+    ];
+}

package/dist/interfaces/sams/sams.js

@@ -22,7 +22,12 @@ class SamsClass extends MongoCollectionClass {
         return [
             { background: true, key: { created_at: 1 } },
             { background: true, key: { agency_id: 1 } },
+            { background: true, key: { agency_id: 1, created_at: -1 } },
+            { background: true, key: { latest_apex_version: 1 } },
+            { background: true, key: { created_at: -1, latest_apex_version: 1 } },
             { background: true, key: { mac_sam_serial_number: 1 } },
+            { background: true, key: { seen_first_at: 1 } },
+            { background: true, key: { seen_last_at: 1 } },
         ];
     }
     getCollectionName() {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tmlmobilidade/interfaces",
-	"version": "20260513.1602.22",
+	"version": "20260514.1347.54",
 	"author": {
 		"email": "iso@tmlmobilidade.pt",
 		"name": "TML-ISO"