doover-js 0.4.4 → 0.4.6

package/dist/test/doover-data-provider.test.js

@@ -39,10 +39,270 @@ const helpers_1 = require("./helpers");
         await (0, chai_1.expect)(provider.getMe()).to.eventually.deep.equal({ id: "u1" });
         await (0, chai_1.expect)(provider.getAgents()).to.eventually.deep.equal({ agents: [] });
         (0, chai_1.expect)(fetchMock.getCall(0).args[0]).to.equal("https://control.example.com/users/me");
-        (0, chai_1.expect)(fetchMock.getCall(1).args[0]).to.equal("https://control.example.com/agents");
+        (0, chai_1.expect)(fetchMock.getCall(1).args[0]).to.equal("https://control.example.com/agents/");
         (0, chai_1.expect)((fetchMock.getCall(0).args[1]?.headers).get("X-Doover-Sharing")).to.equal("internal");
         (0, chai_1.expect)((fetchMock.getCall(1).args[1]?.headers).get("X-Doover-Sharing")).to.equal(null);
     });
+    (0, mocha_1.it)("getAgents forwards include-archived/include-organisations/include-users query keys", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({ agents: [], organisations: [], users: [] }));
+        const provider = new doover_data_provider_1.DooverDataProvider({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+            webSocketImpl: helpers_1.MockWebSocket,
+        });
+        await provider.getAgents({
+            includeArchived: true,
+            includeOrganisations: true,
+            includeUsers: true,
+        });
+        const url = fetchMock.getCall(0).args[0];
+        (0, chai_1.expect)(url.startsWith("https://control.example.com/agents/?")).to.equal(true);
+        (0, chai_1.expect)(url).to.include("include-archived=true");
+        (0, chai_1.expect)(url).to.include("include-organisations=true");
+        (0, chai_1.expect)(url).to.include("include-users=true");
+    });
+    (0, mocha_1.it)("getAgents preserves raw organisations/users without merging by default", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({
+            agents: [
+                {
+                    id: "a1",
+                    name: "agent-1",
+                    display_name: "Agent 1",
+                    type: "device",
+                    organisation: "Org 1",
+                    group: "g",
+                    archived: false,
+                    fa_icon: "fa-solid fa-robot",
+                    fixed_location: { latitude: 1, longitude: 2 },
+                    extra_config: {},
+                },
+            ],
+            organisations: [{ id: "o1", name: "Org 1" }],
+            users: [{ id: "u1", username: "alice" }],
+        }));
+        const provider = new doover_data_provider_1.DooverDataProvider({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+            webSocketImpl: helpers_1.MockWebSocket,
+        });
+        const result = await provider.getAgents({
+            includeOrganisations: true,
+            includeUsers: true,
+        });
+        (0, chai_1.expect)(result.agents).to.have.lengthOf(1);
+        (0, chai_1.expect)(result.agents?.[0].id).to.equal("a1");
+        (0, chai_1.expect)(result.organisations).to.deep.equal([{ id: "o1", name: "Org 1" }]);
+        (0, chai_1.expect)(result.users).to.deep.equal([{ id: "u1", username: "alice" }]);
+        (0, chai_1.expect)(result.results).to.equal(undefined);
+        (0, chai_1.expect)(result.count).to.equal(undefined);
+    });
+    (0, mocha_1.it)("getAgents merges normalized organisations and users when mergeIncludedAsAgents is true", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({
+            agents: [
+                {
+                    id: "a1",
+                    name: "agent-1",
+                    display_name: "Agent 1",
+                    type: "device",
+                    organisation: "Org 1",
+                    group: "g",
+                    archived: false,
+                    fa_icon: "fa-solid fa-robot",
+                    fixed_location: { latitude: 1, longitude: 2 },
+                    extra_config: { foo: "bar" },
+                },
+            ],
+            organisations: [
+                {
+                    id: "o1",
+                    name: "Org One",
+                    archived: false,
+                    root_group: { name: "root" },
+                    extra_config: { level: "premium" },
+                },
+            ],
+            users: [
+                {
+                    id: "u1",
+                    username: "alice",
+                    email: "alice@example.com",
+                    first_name: "Alice",
+                    last_name: "Anderson",
+                    custom_data: { theme: "dark" },
+                },
+            ],
+        }));
+        const provider = new doover_data_provider_1.DooverDataProvider({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+            webSocketImpl: helpers_1.MockWebSocket,
+        });
+        const result = await provider.getAgents({
+            includeOrganisations: true,
+            includeUsers: true,
+            mergeIncludedAsAgents: true,
+        });
+        (0, chai_1.expect)(result.agents).to.have.lengthOf(3);
+        (0, chai_1.expect)(result.results).to.equal(result.agents);
+        (0, chai_1.expect)(result.count).to.equal(3);
+        const [agent, organisation, user] = result.agents;
+        (0, chai_1.expect)(agent.id).to.equal("a1");
+        (0, chai_1.expect)(agent.type).to.equal("device");
+        (0, chai_1.expect)(organisation).to.deep.equal({
+            id: "o1",
+            organisation: "Org One",
+            name: "Org One",
+            display_name: "Org One",
+            archived: false,
+            group: "root",
+            fa_icon: "fa-solid fa-building",
+            type: "organisation",
+            fixed_location: { latitude: 0, longitude: 0 },
+            extra_config: { level: "premium" },
+        });
+        (0, chai_1.expect)(user).to.deep.equal({
+            id: "u1",
+            organisation: "",
+            name: "alice",
+            display_name: "Alice Anderson",
+            archived: false,
+            group: "",
+            fa_icon: "fa-solid fa-user",
+            type: "user",
+            fixed_location: { latitude: 0, longitude: 0 },
+            extra_config: { theme: "dark" },
+        });
+    });
+    (0, mocha_1.it)("getAgents merge respects includeOrganisations/includeUsers flags", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({
+            agents: [
+                {
+                    id: "a1",
+                    name: "a1",
+                    display_name: "a1",
+                    type: "device",
+                    organisation: "o",
+                    group: "g",
+                    archived: false,
+                    fa_icon: "fa-solid fa-robot",
+                    fixed_location: { latitude: 0, longitude: 0 },
+                    extra_config: {},
+                },
+            ],
+            organisations: [{ id: "o1", name: "Org 1" }],
+            users: [{ id: "u1", username: "alice" }],
+        }));
+        const provider = new doover_data_provider_1.DooverDataProvider({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+            webSocketImpl: helpers_1.MockWebSocket,
+        });
+        const result = await provider.getAgents({
+            includeOrganisations: false,
+            includeUsers: true,
+            mergeIncludedAsAgents: true,
+        });
+        (0, chai_1.expect)(result.agents).to.have.lengthOf(2);
+        (0, chai_1.expect)(result.agents?.map((entry) => entry.type)).to.deep.equal([
+            "device",
+            "user",
+        ]);
+        (0, chai_1.expect)(result.count).to.equal(2);
+    });
+    (0, mocha_1.it)("getAgents user display_name falls back through full name, username, email, id", async () => {
+        let payload = {};
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)(payload));
+        const provider = new doover_data_provider_1.DooverDataProvider({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+            webSocketImpl: helpers_1.MockWebSocket,
+        });
+        payload = {
+            agents: [],
+            users: [
+                {
+                    id: "u-full",
+                    username: "alice",
+                    email: "alice@example.com",
+                    first_name: "Alice",
+                    last_name: "Anderson",
+                },
+                { id: "u-username", username: "bob", email: "bob@example.com" },
+                { id: "u-email", email: "carol@example.com" },
+                { id: "u-id-only" },
+            ],
+        };
+        const result = await provider.getAgents({
+            includeUsers: true,
+            mergeIncludedAsAgents: true,
+        });
+        const merged = result.agents ?? [];
+        (0, chai_1.expect)(merged.map((entry) => entry.display_name)).to.deep.equal([
+            "Alice Anderson",
+            "bob",
+            "carol@example.com",
+            "u-id-only",
+        ]);
+        (0, chai_1.expect)(merged.map((entry) => entry.name)).to.deep.equal([
+            "alice",
+            "bob",
+            "carol@example.com",
+            "u-id-only",
+        ]);
+    });
+    (0, mocha_1.it)("getAgents fills agent defaults when fa_icon, fixed_location, or extra_config are missing/null", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({
+            agents: [
+                {
+                    id: "a1",
+                    name: "a1",
+                    display_name: "a1",
+                    type: "device",
+                    organisation: "o",
+                    group: "g",
+                    archived: false,
+                    fa_icon: null,
+                    fixed_location: null,
+                    extra_config: null,
+                },
+                {
+                    id: "a2",
+                    name: "a2",
+                    display_name: "a2",
+                    type: "device",
+                    organisation: "o",
+                    group: "g",
+                    archived: false,
+                    // fa_icon, fixed_location, extra_config all missing
+                },
+            ],
+        }));
+        const provider = new doover_data_provider_1.DooverDataProvider({
+            dataRestUrl: "https://api.example.com",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://ws.example.com",
+            fetchImpl: fetchMock,
+            webSocketImpl: helpers_1.MockWebSocket,
+        });
+        const result = await provider.getAgents();
+        const [withNulls, withMissing] = result.agents ?? [];
+        (0, chai_1.expect)(withNulls.fa_icon).to.equal("fa-solid fa-robot");
+        (0, chai_1.expect)(withNulls.fixed_location).to.deep.equal({ latitude: 0, longitude: 0 });
+        (0, chai_1.expect)(withNulls.extra_config).to.deep.equal({});
+        (0, chai_1.expect)(withMissing.fa_icon).to.equal("fa-solid fa-robot");
+        (0, chai_1.expect)(withMissing.fixed_location).to.deep.equal({ latitude: 0, longitude: 0 });
+        (0, chai_1.expect)(withMissing.extra_config).to.deep.equal({});
+    });
     (0, mocha_1.it)("returns undefined for missing identifiers where expected", async () => {
         const fetchMock = (0, helpers_1.createFetchMock)();
         const provider = new doover_data_provider_1.DooverDataProvider({

package/dist/types/viewer.d.ts

@@ -12,7 +12,7 @@ export interface Agent {
     archived: boolean;
     group: string;
     fa_icon: string;
-    type: "device" | "dashboard";
+    type: "device" | "dashboard" | "organisation" | "user";
     fixed_location: {
         latitude: number;
         longitude: number;
@@ -26,6 +26,18 @@ export interface User {
     name?: string;
     [key: string]: unknown;
 }
+export interface GetAgentsOptions {
+    includeArchived?: boolean;
+    includeOrganisations?: boolean;
+    includeUsers?: boolean;
+    /**
+     * When `true`, normalized organisations and users are appended into the
+     * canonical `agents` list (and mirrored to `results` / `count`). Defaults
+     * to `false`, which preserves the legacy behaviour of returning only the
+     * raw `agents` array.
+     */
+    mergeIncludedAsAgents?: boolean;
+}
 export interface AgentsResponse {
     agents?: Agent[];
     results?: Agent[];
@@ -42,7 +54,7 @@ export interface SubscriptionDetails {
 }
 export interface ChannelsDataProvider<TIdentifier extends ChannelIdentifier = ChannelIdentifier> {
     getMe: () => Promise<User>;
-    getAgents: () => Promise<AgentsResponse>;
+    getAgents: (options?: GetAgentsOptions) => Promise<AgentsResponse>;
     getChannels: (identifier: TIdentifier, options?: {
         includeArchived?: boolean;
     }) => Promise<Channel[] | undefined>;

package/dist/viewer/doover-data-provider.d.ts

@@ -7,7 +7,7 @@ import type { DooverAuth } from "../auth/doover-auth";
 import { GatewayClient } from "../gateway/gateway-client";
 import { RestClient, type DooverClientConfig } from "../http/rest-client";
 import type { Aggregate, Channel, ConnectionDetails, JSONValue, MessageStructure, RpcRequest, RpcStatus } from "../types/common";
-import type { Agent, AgentsResponse, ChannelIdentifier, ChannelsDataProvider, SubscriptionDetails, User } from "../types/viewer";
+import type { Agent, AgentsResponse, ChannelIdentifier, ChannelsDataProvider, GetAgentsOptions, SubscriptionDetails, User } from "../types/viewer";
 interface SubscriptionEntry {
     messageCallback: (identifier: ChannelIdentifier, message: MessageStructure) => void;
     aggregateCallback: (identifier: ChannelIdentifier, aggregate: Aggregate) => void;
@@ -30,7 +30,7 @@ export declare class DooverDataProvider implements ChannelsDataProvider<ChannelI
     private readonly subscriptions;
     constructor(config: DooverClientConfig, auth?: DooverAuth);
     getMe(): Promise<User>;
-    getAgents(): Promise<AgentsResponse>;
+    getAgents(options?: GetAgentsOptions): Promise<AgentsResponse>;
     getChannels(identifier: ChannelIdentifier, options?: {
         includeArchived?: boolean;
     }): Promise<Channel[] | undefined>;
@@ -82,6 +82,11 @@ export declare class DooverDataProvider implements ChannelsDataProvider<ChannelI
         aggregatePath?: string;
     };
     getAgentInfo(agentId: string): Promise<Agent | undefined>;
+    private normalizeAgentEntry;
+    private normalizeOrganisationEntry;
+    private normalizeUserEntry;
+    private buildUserDisplayName;
+    private coerceExtraConfig;
     private requireChannel;
     private channelKey;
     private toIdentifier;

package/dist/viewer/doover-data-provider.js

@@ -18,6 +18,11 @@ function isRpcMessageData(data) {
         "method" in data &&
         "request" in data);
 }
+function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value));
+}
 class DooverDataProvider {
     constructor(config, auth) {
         this.config = config;
@@ -53,12 +58,52 @@ class DooverDataProvider {
     getMe() {
         return this.rest.get("/users/me", undefined, this.config.controlApiUrl);
     }
-    getAgents() {
-        return this.rest.request({
-            path: "/agents",
+    async getAgents(options) {
+        const query = {};
+        if (options?.includeArchived) {
+            query["include-archived"] = true;
+        }
+        if (options?.includeOrganisations) {
+            query["include-organisations"] = true;
+        }
+        if (options?.includeUsers) {
+            query["include-users"] = true;
+        }
+        const raw = await this.rest.request({
+            path: "/agents/",
             baseUrl: this.config.controlApiUrl,
             omitSharingHeader: true,
+            query: Object.keys(query).length > 0 ? query : undefined,
         });
+        const rawAgents = Array.isArray(raw.agents) ? raw.agents : [];
+        const normalizedAgents = rawAgents.map((agent) => this.normalizeAgentEntry(agent));
+        if (!options?.mergeIncludedAsAgents) {
+            return {
+                ...raw,
+                agents: normalizedAgents,
+            };
+        }
+        const merged = [...normalizedAgents];
+        if (options.includeOrganisations) {
+            const rawOrganisations = Array.isArray(raw.organisations)
+                ? raw.organisations
+                : [];
+            for (const org of rawOrganisations) {
+                merged.push(this.normalizeOrganisationEntry(org));
+            }
+        }
+        if (options.includeUsers) {
+            const rawUsers = Array.isArray(raw.users) ? raw.users : [];
+            for (const user of rawUsers) {
+                merged.push(this.normalizeUserEntry(user));
+            }
+        }
+        return {
+            ...raw,
+            agents: merged,
+            results: merged,
+            count: merged.length,
+        };
     }
     async getChannels(identifier, options) {
         if (!identifier.agentId) {
@@ -263,6 +308,106 @@ class DooverDataProvider {
             extra_config: {},
         });
     }
+    normalizeAgentEntry(rawAgent) {
+        const source = isPlainObject(rawAgent)
+            ? rawAgent
+            : {};
+        const fixedLocation = source.fixed_location;
+        const normalizedFixedLocation = isPlainObject(fixedLocation) &&
+            typeof fixedLocation.latitude === "number" &&
+            typeof fixedLocation.longitude === "number"
+            ? {
+                latitude: fixedLocation.latitude,
+                longitude: fixedLocation.longitude,
+            }
+            : { latitude: 0, longitude: 0 };
+        const faIcon = typeof source.fa_icon === "string" && source.fa_icon.length > 0
+            ? source.fa_icon
+            : "fa-solid fa-robot";
+        return {
+            ...source,
+            id: typeof source.id === "string" ? source.id : String(source.id ?? ""),
+            organisation: typeof source.organisation === "string" ? source.organisation : "",
+            name: typeof source.name === "string" ? source.name : "",
+            display_name: typeof source.display_name === "string" ? source.display_name : "",
+            archived: typeof source.archived === "boolean" ? source.archived : false,
+            group: typeof source.group === "string" ? source.group : "",
+            fa_icon: faIcon,
+            type: source.type === "device" ||
+                source.type === "dashboard" ||
+                source.type === "organisation" ||
+                source.type === "user"
+                ? source.type
+                : "device",
+            fixed_location: normalizedFixedLocation,
+            extra_config: this.coerceExtraConfig(source.extra_config),
+        };
+    }
+    normalizeOrganisationEntry(rawOrganisation) {
+        const source = isPlainObject(rawOrganisation)
+            ? rawOrganisation
+            : {};
+        const name = typeof source.name === "string" ? source.name : "";
+        const rootGroup = isPlainObject(source.root_group) ? source.root_group : null;
+        const groupName = rootGroup && typeof rootGroup.name === "string" ? rootGroup.name : "";
+        return {
+            id: typeof source.id === "string" ? source.id : String(source.id ?? ""),
+            organisation: name,
+            name,
+            display_name: name,
+            archived: typeof source.archived === "boolean" ? source.archived : false,
+            group: groupName,
+            fa_icon: "fa-solid fa-building",
+            type: "organisation",
+            fixed_location: { latitude: 0, longitude: 0 },
+            extra_config: this.coerceExtraConfig(source.extra_config),
+        };
+    }
+    normalizeUserEntry(rawUser) {
+        const source = isPlainObject(rawUser)
+            ? rawUser
+            : {};
+        const id = typeof source.id === "string" ? source.id : String(source.id ?? "");
+        const username = typeof source.username === "string" ? source.username : "";
+        const email = typeof source.email === "string" ? source.email : "";
+        const name = username !== "" ? username : email !== "" ? email : id;
+        return {
+            id,
+            organisation: "",
+            name,
+            display_name: this.buildUserDisplayName(source),
+            archived: false,
+            group: "",
+            fa_icon: "fa-solid fa-user",
+            type: "user",
+            fixed_location: { latitude: 0, longitude: 0 },
+            extra_config: this.coerceExtraConfig(source.custom_data),
+        };
+    }
+    buildUserDisplayName(rawUser) {
+        const source = isPlainObject(rawUser)
+            ? rawUser
+            : {};
+        const firstName = typeof source.first_name === "string" ? source.first_name.trim() : "";
+        const lastName = typeof source.last_name === "string" ? source.last_name.trim() : "";
+        const fullName = `${firstName} ${lastName}`.trim();
+        if (fullName !== "") {
+            return fullName;
+        }
+        if (typeof source.username === "string" && source.username !== "") {
+            return source.username;
+        }
+        if (typeof source.email === "string" && source.email !== "") {
+            return source.email;
+        }
+        if (typeof source.id === "string" && source.id !== "") {
+            return source.id;
+        }
+        return String(source.id ?? "");
+    }
+    coerceExtraConfig(value) {
+        return isPlainObject(value) ? value : {};
+    }
     requireChannel(identifier) {
         if (!identifier.agentId || !identifier.channelName) {
             throw new errors_1.DooverValidationError("Identifier must contain agentId and channelName");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doover-js",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "TypeScript client for Doover.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",