@tmlmobilidade/interfaces 20251007.1345.37-staging.0 → 20251008.1352.27-staging.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './src/aggregation-pipeline.js';
+export * from './src/enrich-user-refs.js';
 export * from './src/interfaces/index.js';
 export * from './src/mongo-collection.js';
 export * from './src/mongo-transaction.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 /* * */
 export * from './src/aggregation-pipeline.js';
+export * from './src/enrich-user-refs.js';
 export * from './src/interfaces/index.js';
 export * from './src/mongo-collection.js';
 export * from './src/mongo-transaction.js';

package/dist/src/enrich-user-refs.d.ts

@@ -0,0 +1,4 @@
+type AnyDoc = Record<string, any>;
+export declare function enrichUserRefs<T extends AnyDoc>(doc: T): Promise<T>;
+export declare function enrichUserRefsMany<T extends AnyDoc>(docs: T[]): Promise<T[]>;
+export {};

package/dist/src/enrich-user-refs.js

@@ -0,0 +1,75 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { users } from './interfaces/auth/users.js';
+import { UserDisplayFields } from '@tmlmobilidade/types';
+const isUserRefKey = (k) => k === 'created_by' || k === 'updated_by';
+const isEligibleId = (v) => typeof v === 'string' && v && v !== 'system';
+function collectUserIds(input, out) {
+    if (Array.isArray(input)) {
+        for (const item of input)
+            collectUserIds(item, out);
+        return;
+    }
+    if (input && typeof input === 'object') {
+        for (const [k, v] of Object.entries(input)) {
+            if (isUserRefKey(k) && isEligibleId(v))
+                out.add(v);
+            collectUserIds(v, out);
+        }
+    }
+}
+function replaceRefs(input, map) {
+    if (Array.isArray(input)) {
+        return input.map(item => replaceRefs(item, map));
+    }
+    if (input && typeof input === 'object') {
+        const obj = input;
+        const out = Array.isArray(obj) ? [] : {};
+        for (const [k, v] of Object.entries(obj)) {
+            if (isUserRefKey(k) && typeof v === 'string' && v !== 'system') {
+                const found = map.get(v);
+                out[k] = found ?? v; // fallback to original id if user not found
+            }
+            else {
+                out[k] = replaceRefs(v, map);
+            }
+        }
+        return out;
+    }
+    return input;
+}
+async function fetchUsersMap(ids) {
+    if (ids.size === 0)
+        return new Map();
+    const coll = await users.getCollection();
+    // Only fetch UserDisplay fields
+    const projection = Object.keys(UserDisplayFields).reduce((acc, field) => {
+        acc[field] = 1;
+        return acc;
+    }, {});
+    const result = await coll.find({ _id: { $in: Array.from(ids) } }, { projection }).toArray();
+    const map = new Map();
+    for (const u of result) {
+        map.set(u._id, {
+            _id: u._id,
+            avatar: u.avatar ?? undefined,
+            email: u.email,
+            first_name: u.first_name,
+            last_name: u.last_name,
+            phone: u.phone ?? undefined,
+        });
+    }
+    return map;
+}
+export async function enrichUserRefs(doc) {
+    const ids = new Set();
+    collectUserIds(doc, ids);
+    const map = await fetchUsersMap(ids);
+    return replaceRefs(doc, map);
+}
+export async function enrichUserRefsMany(docs) {
+    const ids = new Set();
+    for (const d of docs)
+        collectUserIds(d, ids);
+    const map = await fetchUsersMap(ids);
+    return docs.map(d => replaceRefs(d, map));
+}

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

@@ -2,7 +2,6 @@ import { MongoCollectionClass } from '../../mongo-collection.js';
 import { CreateUserDto, UpdateUserDto, User } from '@tmlmobilidade/types';
 import { Filter, FindOptions, IndexDescription, WithId } from 'mongodb';
 import { z } from 'zod';
-type NewType = string;
 declare class UsersClass extends MongoCollectionClass<User, CreateUserDto, UpdateUserDto> {
     private static _instance;
     protected createSchema: z.ZodSchema;
@@ -32,7 +31,7 @@ declare class UsersClass extends MongoCollectionClass<User, CreateUserDto, Updat
      * @param includePasswordHash - Whether to include the password hash in the result
      * @returns A promise that resolves to the matching user documents or null if not found
      */
-    findByOrganization(id: NewType, includePasswordHash?: boolean): Promise<{
+    findByOrganization(id: string, includePasswordHash?: boolean): Promise<{
         created_at: number & {
             __brand: "UnixTimestamp";
         };
@@ -41,15 +40,15 @@ declare class UsersClass extends MongoCollectionClass<User, CreateUserDto, Updat
         };
         created_by?: string | undefined | undefined;
         updated_by?: string | undefined | undefined;
-        phone?: string | null | undefined | undefined;
-        email: string;
-        permissions: import("@tmlmobilidade/types").Permission<unknown>[];
         avatar?: string | null | undefined | undefined;
         bio?: string | null | undefined | undefined;
+        email: string;
         email_verified?: import("@tmlmobilidade/types").UnixTimestamp | null | undefined;
         first_name: string;
         last_name: string;
         organization_id?: string | null | undefined | undefined;
+        permissions: import("@tmlmobilidade/types").Permission<unknown>[];
+        phone?: string | null | undefined | undefined;
         preferences?: Record<string, Record<string, string | number | boolean | string[] | number[]>> | null | undefined;
         role_ids: string[];
         session_ids: string[];
@@ -72,15 +71,15 @@ declare class UsersClass extends MongoCollectionClass<User, CreateUserDto, Updat
         };
         created_by?: string | undefined | undefined;
         updated_by?: string | undefined | undefined;
-        phone?: string | null | undefined | undefined;
-        email: string;
-        permissions: import("@tmlmobilidade/types").Permission<unknown>[];
         avatar?: string | null | undefined | undefined;
         bio?: string | null | undefined | undefined;
+        email: string;
         email_verified?: import("@tmlmobilidade/types").UnixTimestamp | null | undefined;
         first_name: string;
         last_name: string;
         organization_id?: string | null | undefined | undefined;
+        permissions: import("@tmlmobilidade/types").Permission<unknown>[];
+        phone?: string | null | undefined | undefined;
         preferences?: Record<string, Record<string, string | number | boolean | string[] | number[]>> | null | undefined;
         role_ids: string[];
         session_ids: string[];

package/dist/src/interfaces/auth/users.js

@@ -2,6 +2,7 @@
 import { MongoCollectionClass } from '../../mongo-collection.js';
 import { UpdateUserSchema, UserSchema } from '@tmlmobilidade/types';
 import { AsyncSingletonProxy } from '@tmlmobilidade/utils';
+/* * */
 class UsersClass extends MongoCollectionClass {
     static _instance;
     createSchema = UserSchema;

package/dist/src/interfaces/notifications/notifications.d.ts

@@ -13,6 +13,15 @@ declare class NotificationsClass extends MongoCollectionClass<Notification, Crea
     protected getCollectionName(): string;
     protected getCreateSchema(): z.ZodSchema;
     protected getEnvName(): string;
+    /**
+     * Collects all effective permissions of a user (direct + via roles),
+     * merging duplicates by (scope:action).
+     */
+    private collectUserPermissions;
+    /**
+     * Determines whether a user can receive email notifications for a topic.
+     */
+    private getNotificationPermission;
 }
 export declare const notifications: NotificationsClass;
 export {};

package/dist/src/interfaces/notifications/notifications.js

@@ -3,7 +3,8 @@ import { MongoCollectionClass } from '../../mongo-collection.js';
 import { sendNotificationEmail } from '@tmlmobilidade/emails';
 import { getAppConfig } from '@tmlmobilidade/lib';
 import { NotificationSchema, UpdateNotificationSchema } from '@tmlmobilidade/types';
-import { AsyncSingletonProxy } from '@tmlmobilidade/utils';
+import { AsyncSingletonProxy, mergeObjects } from '@tmlmobilidade/utils';
+import { roles } from '../auth/roles.js';
 import { users } from '../auth/users.js';
 /* * */
 class NotificationsClass extends MongoCollectionClass {
@@ -22,36 +23,49 @@ class NotificationsClass extends MongoCollectionClass {
         return NotificationsClass._instance;
     }
     async sendNotification(scope, topic, user, id, title, description) {
-        const usersWithTopic = await users.findMany({ 'permissions.action': topic });
+        // Fetch roles and users that have access to this topic
+        const rolesWithTopic = await roles.findMany({ 'permissions.action': topic });
+        const roleIdsWithTopic = rolesWithTopic.map(r => r._id);
+        const usersWithTopic = await users.findMany({
+            $or: [
+                { 'permissions.action': topic },
+                { role_ids: { $in: roleIdsWithTopic } },
+            ],
+        });
         if (usersWithTopic.length === 0)
             return;
-        const notification = {
+        // Base notification template
+        const baseNotification = {
             created_by: user?._id,
             is_read: false,
             payload: {
                 body: description,
-                href: `${getAppConfig(`${scope}`, 'frontend_url')}/${scope}/${id}`,
+                href: `${getAppConfig(scope, 'frontend_url')}/${scope}/${id}`,
                 icon: scope,
-                title: title,
+                title,
             },
             priority: 'normal',
-            scope: scope,
-            topic: topic,
+            scope,
+            topic,
             updated_by: user?._id,
         };
-        for (const user of usersWithTopic.filter(u => u._id !== notification.created_by)) {
-            const sendMail = user?.permissions.find(p => p.scope === 'notifications' && p.action === topic)?.resource ?? false;
-            const newNotification = { ...notification, user_id: user._id };
-            if (sendMail) {
+        // Iterate over eligible users (excluding creator)
+        for (const recipient of usersWithTopic.filter(u => u._id !== baseNotification.created_by)) {
+            const permissions = this.collectUserPermissions(recipient, rolesWithTopic);
+            const canReceiveEmail = this.getNotificationPermission(permissions, topic);
+            const newNotification = { ...baseNotification, user_id: recipient._id };
+            // Send email if permission allows
+            if (canReceiveEmail) {
                 await sendNotificationEmail({
                     props: {
-                        body: notification.payload.body,
-                        href: notification.payload.href || '',
-                        priority: notification.priority,
-                        scope: notification.scope,
-                        title: notification.payload.title,
-                        topic: notification.topic,
-                    }, to: user.email,
+                        body: baseNotification.payload.body,
+                        href: baseNotification.payload.href ?? '',
+                        priority: baseNotification.priority,
+                        scope: baseNotification.scope,
+                        title: baseNotification.payload.title,
+                        topic: baseNotification.topic,
+                    },
+                    to: recipient.email,
                 });
             }
             await notifications.insertOne(newNotification);
@@ -71,5 +85,29 @@ class NotificationsClass extends MongoCollectionClass {
     getEnvName() {
         return 'DATABASE_URI';
     }
+    /**
+     * Collects all effective permissions of a user (direct + via roles),
+     * merging duplicates by (scope:action).
+     */
+    collectUserPermissions(user, rolesWithTopic) {
+        const rolePermissions = rolesWithTopic
+            .filter(role => user.role_ids?.includes(role._id))
+            .flatMap(role => role.permissions ?? []);
+        const allPermissions = [...(user.permissions ?? []), ...rolePermissions];
+        const map = new Map();
+        for (const permission of allPermissions) {
+            const key = `${permission.scope}:${permission.action}`;
+            const existing = map.get(key);
+            map.set(key, existing ? mergeObjects(existing, permission) : permission);
+        }
+        return map;
+    }
+    /**
+     * Determines whether a user can receive email notifications for a topic.
+     */
+    getNotificationPermission(permissions, topic) {
+        const permission = permissions.get(`notifications:${topic}`);
+        return permission?.resource?.send_mail ?? false;
+    }
 }
 export const notifications = AsyncSingletonProxy(NotificationsClass);

package/dist/src/mongo-collection.d.ts

@@ -1,8 +1,8 @@
+import { AggregationPipeline } from './aggregation-pipeline.js';
 import { MongoConnector } from '@tmlmobilidade/connectors';
 import { type UnixTimestamp } from '@tmlmobilidade/types';
 import { AggregateOptions, AggregationCursor, Collection, DeleteOptions, DeleteResult, Document, Filter, FindOptions, IndexDescription, InsertManyResult, InsertOneOptions, InsertOneResult, MongoClientOptions, UpdateOptions, UpdateResult, WithId } from 'mongodb';
 import { z } from 'zod';
-import { AggregationPipeline } from './aggregation-pipeline.js';
 export declare abstract class MongoCollectionClass<T extends Document, TCreate, TUpdate> {
     protected createSchema: null | z.ZodSchema;
     protected mongoCollection: Collection<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tmlmobilidade/interfaces",
-	"version": "20251007.1345.37-staging.0",
+	"version": "20251008.1352.27-staging.0",
 	"author": "João de Vasconcelos & Jusi Monteiro",
 	"license": "AGPL-3.0-or-later",
 	"homepage": "https://github.com/tmlmobilidade/services#readme",
@@ -36,8 +36,8 @@
 		"lint:fix": "eslint --fix"
 	},
 	"dependencies": {
-		"@aws-sdk/client-s3": "3.899.0",
-		"@aws-sdk/s3-request-presigner": "3.899.0",
+		"@aws-sdk/client-s3": "3.901.0",
+		"@aws-sdk/s3-request-presigner": "3.901.0",
 		"@tmlmobilidade/connectors": "*",
 		"@tmlmobilidade/emails": "*",
 		"@tmlmobilidade/lib": "*",
@@ -54,7 +54,7 @@
 	"devDependencies": {
 		"@carrismetropolitana/eslint": "20250622.1204.50",
 		"@types/luxon": "3.7.1",
-		"@types/node": "24.6.1",
+		"@types/node": "24.7.0",
 		"resolve-tspaths": "0.8.23",
 		"rimraf": "6.0.1",
 		"typescript": "5.9.3"