@internetderdinge/api 1.229.28 → 1.229.31

package/dist/src/admin/adminSearch.service.js

@@ -0,0 +1,763 @@
+import mongoose from "mongoose";
+import Device from "../devices/devices.model.js";
+import Organization from "../organizations/organizations.model.js";
+import { User } from "../users/users.model.js";
+import iotDevicesService from "../iotdevice/iotdevice.service.js";
+import { auth0 } from "../accounts/auth0.service.js";
+const IOT_DEVICES_CACHE_TTL_MS = 60000;
+let iotDevicesCache = null;
+const getCachedIotDevices = async () => {
+    const now = Date.now();
+    if (iotDevicesCache?.pending) {
+        return iotDevicesCache.pending;
+    }
+    if (iotDevicesCache &&
+        now - iotDevicesCache.loadedAt < IOT_DEVICES_CACHE_TTL_MS) {
+        return iotDevicesCache.devices;
+    }
+    const pending = Promise.resolve(iotDevicesService.getDeviceStatusList(undefined)).then((devices) => (Array.isArray(devices) ? devices : []));
+    iotDevicesCache = {
+        loadedAt: now,
+        devices: [],
+        pending,
+    };
+    try {
+        const devices = await pending;
+        iotDevicesCache = {
+            loadedAt: Date.now(),
+            devices,
+        };
+        return devices;
+    }
+    catch (error) {
+        iotDevicesCache = null;
+        throw error;
+    }
+};
+const toRegex = (search) => {
+    const escaped = search.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(escaped, "i");
+};
+const getNestedString = (source, path) => {
+    const value = path.split(".").reduce((current, part) => {
+        if (!current || typeof current !== "object") {
+            return undefined;
+        }
+        return current[part];
+    }, source);
+    return typeof value === "string" ? value : undefined;
+};
+const getFirstNestedString = (source, paths) => {
+    for (const path of paths) {
+        const value = getNestedString(source, path);
+        if (value) {
+            return value;
+        }
+    }
+    return undefined;
+};
+const userMetaEmailPaths = [
+    "email",
+    "data.email",
+    "user_metadata.email",
+    "app_metadata.email",
+    "auth0.email",
+    "auth0.data.email",
+    "auth0.user_metadata.email",
+    "auth0.app_metadata.email",
+];
+const scoreMatch = (search, candidates) => {
+    const query = search.trim().toLowerCase();
+    if (!query) {
+        return 0;
+    }
+    let score = 0;
+    for (const rawCandidate of candidates) {
+        const candidate = rawCandidate?.toLowerCase().trim();
+        if (!candidate) {
+            continue;
+        }
+        if (candidate === query) {
+            score = Math.max(score, 100);
+            continue;
+        }
+        if (candidate.startsWith(query)) {
+            score = Math.max(score, 70);
+            continue;
+        }
+        if (candidate.includes(query)) {
+            score = Math.max(score, 40);
+        }
+    }
+    return score;
+};
+const sortByScore = (items, limit) => {
+    return items.sort((a, b) => b.score - a.score).slice(0, limit);
+};
+const AUTH0_COUNT_PAGE_SIZE = 100;
+const MAX_AUTH0_COUNT_PAGES = 10;
+let cachedAuth0ManagementToken = null;
+let cachedAuth0ManagementTokenExpiresAt = null;
+const getAuth0ManagementDomainUrl = () => {
+    const raw = process.env.AUTH0_MANAGEMENT_DOMAIN;
+    if (!raw) {
+        return null;
+    }
+    const normalized = raw.startsWith("http://") || raw.startsWith("https://")
+        ? raw
+        : `https://${raw}`;
+    try {
+        const parsed = new URL(normalized);
+        return parsed.origin;
+    }
+    catch {
+        return normalized;
+    }
+};
+const getAuth0ManagementTokenDirect = async () => {
+    const now = Math.floor(Date.now() / 1000);
+    if (cachedAuth0ManagementToken &&
+        cachedAuth0ManagementTokenExpiresAt &&
+        now < cachedAuth0ManagementTokenExpiresAt - 60) {
+        return cachedAuth0ManagementToken;
+    }
+    const domainUrl = getAuth0ManagementDomainUrl();
+    const clientId = process.env.AUTH0_MANAGEMENT_CLIENT_ID;
+    const clientSecret = process.env.AUTH0_MANAGEMENT_CLIENT_SECRET;
+    const audience = process.env.AUTH0_MANAGEMENT_AUDIENCE;
+    if (!domainUrl || !clientId || !clientSecret || !audience) {
+        throw new Error("Missing Auth0 Management API credentials in environment.");
+    }
+    const response = await fetch(`${domainUrl}/oauth/token`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+        },
+        body: JSON.stringify({
+            grant_type: "client_credentials",
+            client_id: clientId,
+            client_secret: clientSecret,
+            audience,
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Auth0 token request failed (${response.status}).`);
+    }
+    const payload = (await response.json());
+    if (!payload.access_token) {
+        throw new Error("Auth0 token response did not include access_token.");
+    }
+    const expiresIn = payload.expires_in ?? 3600;
+    cachedAuth0ManagementToken = payload.access_token;
+    cachedAuth0ManagementTokenExpiresAt = now + expiresIn;
+    return cachedAuth0ManagementToken;
+};
+const getAuth0UsersTotalViaManagementApi = async () => {
+    const domainUrl = getAuth0ManagementDomainUrl();
+    if (!domainUrl) {
+        throw new Error("Missing AUTH0_MANAGEMENT_DOMAIN in environment.");
+    }
+    const token = await getAuth0ManagementTokenDirect();
+    const response = await fetch(`${domainUrl}/api/v2/users?page=0&per_page=1&include_totals=true`, {
+        method: "GET",
+        headers: {
+            authorization: `Bearer ${token}`,
+            "content-type": "application/json",
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Auth0 users total request failed (${response.status}).`);
+    }
+    const payload = (await response.json());
+    if (typeof payload.total !== "number" || !Number.isFinite(payload.total)) {
+        throw new Error("Auth0 users response did not include a valid total.");
+    }
+    return payload.total;
+};
+const getUsersFromAuth0Response = (auth0Response) => {
+    if (Array.isArray(auth0Response)) {
+        return auth0Response;
+    }
+    if (auth0Response &&
+        typeof auth0Response === "object" &&
+        Symbol.iterator in auth0Response) {
+        return Array.from(auth0Response);
+    }
+    if (Array.isArray(auth0Response?.data)) {
+        return auth0Response.data;
+    }
+    if (Array.isArray(auth0Response?.users)) {
+        return auth0Response.users;
+    }
+    if (Array.isArray(auth0Response?.items)) {
+        return auth0Response.items;
+    }
+    return [];
+};
+const getTotalFromAuth0Response = (auth0Response) => {
+    if (!auth0Response || typeof auth0Response !== "object") {
+        return undefined;
+    }
+    const maybeNumber = auth0Response.total;
+    if (typeof maybeNumber === "number" && Number.isFinite(maybeNumber)) {
+        return maybeNumber;
+    }
+    const data = auth0Response.data;
+    if (data && typeof data === "object") {
+        const nested = data.total;
+        if (typeof nested === "number" && Number.isFinite(nested)) {
+            return nested;
+        }
+    }
+    return undefined;
+};
+const getAuth0UsersTotal = async () => {
+    try {
+        return await getAuth0UsersTotalViaManagementApi();
+    }
+    catch (error) {
+        console.warn("Admin stats Auth0 total-users API failed, fallback to list", error);
+    }
+    try {
+        const seenUserIds = new Set();
+        let countByLength = 0;
+        for (let page = 0; page < MAX_AUTH0_COUNT_PAGES; page += 1) {
+            let response;
+            try {
+                response = await auth0.users.list({
+                    page,
+                    per_page: AUTH0_COUNT_PAGE_SIZE,
+                    include_totals: false,
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error
+                    ? error.message
+                    : typeof error === "string"
+                        ? error
+                        : "";
+                if (message.includes("invalid_paging")) {
+                    break;
+                }
+                throw error;
+            }
+            const users = getUsersFromAuth0Response(response);
+            countByLength += users.length;
+            for (const entry of users) {
+                const userId = typeof entry.user_id === "string"
+                    ? entry.user_id
+                    : typeof entry.id === "string"
+                        ? entry.id
+                        : undefined;
+                if (userId) {
+                    seenUserIds.add(userId);
+                }
+            }
+            if (users.length < AUTH0_COUNT_PAGE_SIZE) {
+                break;
+            }
+        }
+        return seenUserIds.size > 0 ? seenUserIds.size : countByLength;
+    }
+    catch (error) {
+        console.warn("Admin stats Auth0 total query failed", error);
+        return 0;
+    }
+};
+const normalizeEmail = (value) => {
+    return typeof value === "string" && value.trim()
+        ? value.trim().toLowerCase()
+        : undefined;
+};
+const normalizeNumber = (value) => {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim()) {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+};
+const normalizeDateString = (value) => {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (typeof value === "string" && value.trim()) {
+        return value;
+    }
+    return undefined;
+};
+const toRecord = (value) => {
+    return value && typeof value === "object"
+        ? value
+        : undefined;
+};
+const buildUserResult = (search, user) => {
+    const organizationData = user.organizationData;
+    const userMeta = user.meta;
+    const firstName = user.meta
+        ? user.meta.firstName
+        : undefined;
+    const lastName = user.meta
+        ? user.meta.lastName
+        : undefined;
+    const metadataEmail = getFirstNestedString(userMeta, userMetaEmailPaths);
+    return {
+        score: scoreMatch(search, [
+            user.name,
+            user.email,
+            metadataEmail,
+            firstName,
+            lastName,
+            organizationData?.name,
+        ]),
+        id: String(user._id),
+        name: user.name,
+        email: user.email || metadataEmail,
+        role: user.role,
+        organization: organizationData
+            ? {
+                id: String(organizationData._id),
+                name: organizationData.name,
+                kind: organizationData.kind,
+            }
+            : undefined,
+    };
+};
+const searchUsersInAuth0 = async (search, limit) => {
+    const trimmedSearch = search.trim();
+    const escaped = search.replace(/"/g, '\\"');
+    const auth0Query = [
+        `email:"${escaped}"`,
+        `user_metadata.email:"${escaped}"`,
+        `app_metadata.email:"${escaped}"`,
+        `email:*${escaped}*`,
+    ].join(" OR ");
+    try {
+        let auth0ListResponse = [];
+        try {
+            auth0ListResponse = await auth0.users.list({
+                search_engine: "v3",
+                q: auth0Query,
+                per_page: Math.min(limit * 2, 50),
+                page: 0,
+            });
+        }
+        catch (error) {
+            console.warn("Admin search Auth0 list query failed", error);
+        }
+        let auth0ExactEmailResponse = [];
+        if (trimmedSearch.includes("@")) {
+            try {
+                auth0ExactEmailResponse = await auth0.users.listUsersByEmail({
+                    email: trimmedSearch,
+                });
+            }
+            catch (error) {
+                console.warn("Admin search Auth0 exact-email query failed", error);
+            }
+        }
+        const auth0UsersById = new Map();
+        for (const entry of [
+            ...getUsersFromAuth0Response(auth0ListResponse),
+            ...getUsersFromAuth0Response(auth0ExactEmailResponse),
+        ]) {
+            const userId = typeof entry.user_id === "string"
+                ? entry.user_id
+                : typeof entry.id === "string"
+                    ? entry.id
+                    : undefined;
+            if (!userId) {
+                continue;
+            }
+            auth0UsersById.set(userId, entry);
+        }
+        const auth0Users = Array.from(auth0UsersById.values());
+        const auth0Ids = auth0Users
+            .map((entry) => typeof entry.user_id === "string" ? entry.user_id : undefined)
+            .filter((entry) => Boolean(entry));
+        const auth0Emails = auth0Users
+            .map((entry) => normalizeEmail(entry.email))
+            .filter((entry) => Boolean(entry));
+        if (!auth0Ids.length && !auth0Emails.length) {
+            return [];
+        }
+        const filterOr = [];
+        if (auth0Ids.length) {
+            filterOr.push({ owner: { $in: auth0Ids } });
+        }
+        if (auth0Emails.length) {
+            filterOr.push({ email: { $in: auth0Emails } }, { "meta.email": { $in: auth0Emails } }, { "meta.data.email": { $in: auth0Emails } });
+        }
+        const mongoUsersRaw = await User.find({ $or: filterOr })
+            .select("_id name email role organization owner meta")
+            .populate("organizationData", "_id name kind")
+            .limit(limit * 2)
+            .lean();
+        const mongoUsers = mongoUsersRaw.map((user) => buildUserResult(search, user));
+        const mappedOwners = new Set(mongoUsersRaw
+            .map((user) => typeof user.owner === "string" ? user.owner : undefined)
+            .filter((entry) => Boolean(entry)));
+        const mappedEmails = new Set();
+        for (const user of mongoUsersRaw) {
+            const topLevelEmail = normalizeEmail(user.email);
+            if (topLevelEmail) {
+                mappedEmails.add(topLevelEmail);
+            }
+            const meta = user.meta;
+            const metaEmail = normalizeEmail(getFirstNestedString(meta, userMetaEmailPaths));
+            if (metaEmail) {
+                mappedEmails.add(metaEmail);
+            }
+        }
+        const auth0OnlyUsers = auth0Users
+            .map((entry) => {
+            const userId = typeof entry.user_id === "string"
+                ? entry.user_id
+                : typeof entry.id === "string"
+                    ? entry.id
+                    : undefined;
+            if (!userId) {
+                return undefined;
+            }
+            const email = normalizeEmail(entry.email);
+            const userMetadata = entry.user_metadata;
+            const appMetadata = entry.app_metadata;
+            const metadataEmail = normalizeEmail(userMetadata?.email) ||
+                normalizeEmail(appMetadata?.email);
+            const finalEmail = email || metadataEmail;
+            if (mappedOwners.has(userId)) {
+                return undefined;
+            }
+            if (finalEmail && mappedEmails.has(finalEmail)) {
+                return undefined;
+            }
+            const name = (typeof entry.name === "string" && entry.name) ||
+                (typeof entry.nickname === "string" && entry.nickname) ||
+                finalEmail ||
+                userId;
+            return {
+                id: `auth0:${userId}`,
+                name,
+                email: finalEmail,
+                role: "auth0",
+                score: scoreMatch(search, [
+                    name,
+                    finalEmail,
+                    userId,
+                    normalizeEmail(userMetadata?.email),
+                    normalizeEmail(appMetadata?.email),
+                ]),
+            };
+        })
+            .filter((entry) => Boolean(entry));
+        return [...mongoUsers, ...auth0OnlyUsers];
+    }
+    catch (error) {
+        console.warn("Admin search Auth0 fallback failed", error);
+        return [];
+    }
+};
+export const searchAdminCollections = async ({ search, limit, }) => {
+    const startedAt = Date.now();
+    const hasSearch = search.trim().length > 0;
+    const regex = toRegex(search);
+    const objectId = mongoose.Types.ObjectId.isValid(search)
+        ? new mongoose.Types.ObjectId(search)
+        : undefined;
+    const organizationFilter = hasSearch
+        ? {
+            $or: [{ name: regex }, { kind: regex }, { "meta.name": regex }],
+        }
+        : {};
+    const userFilter = hasSearch
+        ? {
+            $or: [
+                { name: regex },
+                { email: regex },
+                { owner: regex },
+                { "meta.email": regex },
+                { "meta.data.email": regex },
+                { "meta.user_metadata.email": regex },
+                { "meta.app_metadata.email": regex },
+                { "meta.auth0.email": regex },
+                { "meta.auth0.data.email": regex },
+                { "meta.auth0.user_metadata.email": regex },
+                { "meta.auth0.app_metadata.email": regex },
+                { "meta.firstName": regex },
+                { "meta.lastName": regex },
+            ],
+        }
+        : {};
+    const deviceFilter = hasSearch
+        ? {
+            $or: [
+                { name: regex },
+                { deviceId: regex },
+                { kind: regex },
+                { "meta.name": regex },
+                { "meta.serialNumber": regex },
+                { "payment.id": regex },
+            ],
+        }
+        : {};
+    if (objectId) {
+        organizationFilter.$or.push({
+            _id: objectId,
+        });
+        userFilter.$or.push({ _id: objectId }, { organization: objectId });
+        deviceFilter.$or.push({ _id: objectId }, { organization: objectId }, { patient: objectId });
+    }
+    const [organizationsRaw, usersRaw, devicesRaw] = await Promise.all([
+        Organization.find(organizationFilter)
+            .select("_id name kind")
+            .limit(limit * 2)
+            .lean(),
+        User.find(userFilter)
+            .select("_id name email role organization meta")
+            .populate("organizationData", "_id name kind")
+            .limit(limit * 2)
+            .lean(),
+        Device.find(deviceFilter)
+            .select("_id name deviceId kind timezone eventDate payment organization patient meta createdAt updatedAt")
+            .populate("organization", "_id name kind")
+            .populate("patient", "_id name email meta")
+            .limit(limit * 2)
+            .lean(),
+    ]);
+    const iotStatusByDeviceId = new Map();
+    await Promise.all(devicesRaw.map(async (device) => {
+        const deviceId = typeof device.deviceId === "string" ? String(device.deviceId) : "";
+        if (!deviceId) {
+            return;
+        }
+        try {
+            const iotStatus = await iotDevicesService.getDeviceStatus(deviceId, device.kind);
+            const normalized = toRecord(iotStatus);
+            if (normalized) {
+                iotStatusByDeviceId.set(deviceId, normalized);
+            }
+        }
+        catch (error) {
+            console.warn(`Admin search iot status failed for ${deviceId}`, error);
+        }
+    }));
+    const organizations = sortByScore(organizationsRaw.map((organization) => ({
+        score: scoreMatch(search, [
+            organization.name,
+            organization.kind,
+        ]),
+        id: String(organization._id),
+        name: organization.name,
+        kind: organization.kind,
+    })), limit).map(({ score, ...entry }) => entry);
+    const mongoUsers = usersRaw.map((user) => buildUserResult(search, user));
+    const shouldSearchAuth0 = search.includes("@") || search.includes(".");
+    const auth0Users = shouldSearchAuth0
+        ? await searchUsersInAuth0(search, limit)
+        : [];
+    const mergedUsers = new Map();
+    for (const user of [...mongoUsers, ...auth0Users]) {
+        const existing = mergedUsers.get(user.id);
+        if (!existing || user.score > existing.score) {
+            mergedUsers.set(user.id, user);
+        }
+    }
+    const users = sortByScore(Array.from(mergedUsers.values()), limit).map(({ score, ...entry }) => entry);
+    const devices = sortByScore(devicesRaw.map((device) => {
+        const organizationData = device.organization;
+        const patientData = device.patient;
+        const deviceMeta = device.meta;
+        const iotStatus = toRecord(typeof device.deviceId === "string"
+            ? iotStatusByDeviceId.get(String(device.deviceId))
+            : undefined);
+        const patientMeta = patientData?.meta;
+        const patientName = patientData?.name
+            ? String(patientData.name)
+            : [patientMeta?.firstName, patientMeta?.lastName]
+                .filter(Boolean)
+                .join(" ");
+        const batteryLevel = normalizeNumber(iotStatus?.batLevel) ??
+            normalizeNumber(iotStatus?.batteryLevel) ??
+            normalizeNumber(iotStatus?.battery) ??
+            normalizeNumber(device.batLevel) ??
+            normalizeNumber(deviceMeta?.batLevel) ??
+            normalizeNumber(deviceMeta?.batteryLevel) ??
+            normalizeNumber(deviceMeta?.battery);
+        const batteryStatus = getFirstNestedString(iotStatus, [
+            "batteryStatus",
+            "battery.status",
+            "status.battery",
+        ]) ||
+            getFirstNestedString(deviceMeta, [
+                "batteryStatus",
+                "battery.status",
+                "status.battery",
+            ]) ||
+            (typeof batteryLevel === "number"
+                ? batteryLevel < 3450
+                    ? "empty"
+                    : batteryLevel < 3500
+                        ? "low"
+                        : "ok"
+                : undefined);
+        const lastReachableAgo = normalizeDateString(iotStatus?.lastReachableAgo) ||
+            normalizeDateString(iotStatus?.lastReachable) ||
+            normalizeDateString(device.lastReachableAgo) ||
+            getFirstNestedString(deviceMeta, [
+                "lastReachableAgo",
+                "reachability.last",
+            ]);
+        const serialNumber = getFirstNestedString(iotStatus, ["serialNumber", "serial", "sn"]) ||
+            getFirstNestedString(deviceMeta, ["serialNumber"]);
+        const signalStrength = normalizeNumber(iotStatus?.rssi) ??
+            normalizeNumber(iotStatus?.signalStrength) ??
+            normalizeNumber(iotStatus?.signal);
+        return {
+            score: scoreMatch(search, [
+                device.deviceId,
+                device.kind,
+                device.name,
+                serialNumber,
+                batteryStatus,
+                signalStrength !== undefined ? String(signalStrength) : undefined,
+                organizationData?.name,
+                patientName,
+            ]),
+            id: String(device._id),
+            name: device.name,
+            deviceId: device.deviceId,
+            kind: device.kind,
+            timezone: device.timezone,
+            eventDate: normalizeDateString(device.eventDate),
+            createdAt: normalizeDateString(device.createdAt),
+            updatedAt: normalizeDateString(device.updatedAt),
+            serialNumber,
+            paymentId: device.payment
+                ?.id,
+            batteryStatus,
+            batteryLevel,
+            signalStrength,
+            lastReachableAgo,
+            organization: organizationData
+                ? {
+                    id: String(organizationData._id),
+                    name: organizationData.name,
+                    kind: organizationData.kind,
+                }
+                : undefined,
+            patient: patientData
+                ? {
+                    id: String(patientData._id),
+                    name: patientName,
+                }
+                : undefined,
+        };
+    }), limit).map(({ score, ...entry }) => entry);
+    return {
+        query: search,
+        organizations,
+        users,
+        devices,
+        total: organizations.length + users.length + devices.length,
+        tookMs: Date.now() - startedAt,
+    };
+};
+export const getAdminStats = async () => {
+    const startedAt = Date.now();
+    const [users, auth0Users, devices, organizations] = await Promise.all([
+        User.countDocuments({}),
+        getAuth0UsersTotal(),
+        Device.countDocuments({}),
+        Organization.countDocuments({}),
+    ]);
+    return {
+        users,
+        auth0Users,
+        devices,
+        organizations,
+        total: users + auth0Users + devices + organizations,
+        tookMs: Date.now() - startedAt,
+    };
+};
+export const getAdminIotDevices = async (query) => {
+    const startedAt = Date.now();
+    const iotDevices = await getCachedIotDevices();
+    const updatedSinceMs = query.updatedSince
+        ? new Date(query.updatedSince).getTime()
+        : null;
+    const normalized = Array.isArray(iotDevices)
+        ? iotDevices
+            .map((entry) => toRecord(entry))
+            .filter((entry) => typeof entry === "object" && entry !== null)
+        : [];
+    const filtered = updatedSinceMs && Number.isFinite(updatedSinceMs)
+        ? normalized.filter((entry) => {
+            const updatedAtValue = entry.updatedAt ??
+                entry.lastSeenAt ??
+                entry.lastSeen ??
+                entry.createdAt;
+            if (typeof updatedAtValue !== "string" &&
+                typeof updatedAtValue !== "number") {
+                return true;
+            }
+            const timestamp = new Date(String(updatedAtValue)).getTime();
+            if (!Number.isFinite(timestamp)) {
+                return true;
+            }
+            return timestamp >= updatedSinceMs;
+        })
+        : normalized;
+    const total = filtered.length;
+    const page = Math.max(1, query.page);
+    const perPage = Math.max(1, Math.min(500, query.perPage));
+    const totalPages = Math.max(1, Math.ceil(total / perPage));
+    const pageIndex = Math.min(page, totalPages) - 1;
+    const start = pageIndex * perPage;
+    const end = start + perPage;
+    const results = filtered.slice(start, end);
+    return {
+        results,
+        page,
+        perPage,
+        totalPages,
+        total,
+        tookMs: Date.now() - startedAt,
+    };
+};
+export const getAdminDevices = async (query) => {
+    const startedAt = Date.now();
+    const updatedSinceMs = query.updatedSince
+        ? new Date(query.updatedSince).getTime()
+        : null;
+    const filter = {};
+    if (updatedSinceMs && Number.isFinite(updatedSinceMs)) {
+        filter.updatedAt = { $gte: new Date(updatedSinceMs) };
+    }
+    const page = Math.max(1, query.page);
+    const perPage = Math.max(1, Math.min(500, query.perPage));
+    const skip = (page - 1) * perPage;
+    const [devices, total] = await Promise.all([
+        Device.find(filter)
+            .sort({ updatedAt: -1 })
+            .skip(skip)
+            .limit(perPage)
+            .lean(),
+        Device.countDocuments(filter),
+    ]);
+    const results = Array.isArray(devices)
+        ? devices
+            .map((entry) => toRecord(entry))
+            .filter((entry) => typeof entry === "object" && entry !== null)
+        : [];
+    const totalPages = Math.max(1, Math.ceil(total / perPage));
+    return {
+        results,
+        page,
+        perPage,
+        totalPages,
+        total,
+        tookMs: Date.now() - startedAt,
+    };
+};