doover-js 0.6.4 → 0.6.6

package/dist/test/exports.test.js

@@ -47,6 +47,10 @@ const doover = __importStar(require("../index"));
         (0, chai_1.expect)(doover.ALL_CAPABILITIES).to.be.an("array");
         (0, chai_1.expect)(doover.UnsupportedCapabilityError).to.be.a("function");
         (0, chai_1.expect)(doover.AmbiguousWriteError).to.be.a("function");
+        (0, chai_1.expect)(doover.DooverOfflineError).to.be.a("function");
+        (0, chai_1.expect)(doover.OfflineDataClient).to.be.a("function");
+        (0, chai_1.expect)(doover.MemoryOfflineStorageAdapter).to.be.a("function");
+        (0, chai_1.expect)(doover.requestOptions).to.be.a("function");
     });
     (0, mocha_1.it)("type-only exports resolve (compile-time)", () => {
         // If any of these types are removed from the public index the import above
@@ -69,7 +73,7 @@ const doover = __importStar(require("../index"));
         (0, chai_1.expect)(true).to.equal(true); // keep mocha happy
     });
     (0, mocha_1.it)("exports the full Phase-1..4 surface", () => {
-        for (const name of ["ALL_CAPABILITIES", "UnsupportedCapabilityError", "AmbiguousWriteError", "LocalAgentClient", "MultiplexClient", "DooverClient"]) {
+        for (const name of ["ALL_CAPABILITIES", "UnsupportedCapabilityError", "AmbiguousWriteError", "DooverOfflineError", "LocalAgentClient", "MultiplexClient", "DooverClient", "OfflineDataClient", "MemoryOfflineStorageAdapter", "requestOptions"]) {
             (0, chai_1.expect)(doover[name], name).to.exist;
         }
     });

package/dist/test/offline-cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/offline-cache.test.js

@@ -0,0 +1,289 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+const mocha_1 = require("mocha");
+const doover_client_1 = require("../client/doover-client");
+const offline_cache_1 = require("../client/offline-cache");
+const request_options_1 = require("../client/request-options");
+const errors_1 = require("../client/errors");
+const snowflake_1 = require("../utils/snowflake");
+const helpers_1 = require("./helpers");
+function makeOnlineClient(fetchImpl) {
+    return new doover_client_1.DooverClient({
+        dataRestUrl: "https://api.example.com",
+        controlApiUrl: "https://control.example.com",
+        dataWssUrl: "wss://ws.example.com",
+        fetchImpl,
+        webSocketImpl: helpers_1.MockWebSocket,
+        disableBrowserLifecycleHooks: true,
+    });
+}
+(0, mocha_1.describe)("requestOptions", () => {
+    (0, mocha_1.it)("marks a request-options bag explicitly", () => {
+        const options = (0, request_options_1.requestOptions)({
+            sources: ["cloud"],
+            cache: { policy: "tag-values-history" },
+        });
+        (0, chai_1.expect)(options[request_options_1.REQUEST_OPTIONS_SYMBOL]).to.equal(true);
+        (0, chai_1.expect)(options.sources).to.deep.equal(["cloud"]);
+    });
+});
+(0, mocha_1.describe)("OfflineDataClient", () => {
+    (0, mocha_1.it)("caches reads covered by a stored channel policy and serves them offline", async () => {
+        let online = true;
+        const messageId = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-06-10T00:00:00Z"));
+        const fetchMock = (0, helpers_1.createFetchMock)((url) => {
+            if (url.includes("/agents/a1/channels/tag_values/messages")) {
+                return (0, helpers_1.createJsonResponse)([
+                    {
+                        id: messageId,
+                        data: { value: 42 },
+                        attachments: [],
+                        author_id: "u1",
+                        channel: { agent_id: "a1", name: "tag_values" },
+                    },
+                ]);
+            }
+            return (0, helpers_1.createJsonResponse)({ ok: true });
+        });
+        const storage = new offline_cache_1.MemoryOfflineStorageAdapter();
+        const client = new offline_cache_1.OfflineDataClient({
+            client: makeOnlineClient(fetchMock),
+            storage,
+            scope: { userId: "u1", organisationId: "org1", sourceId: "cloud" },
+            isOnline: () => online,
+        });
+        client.setChannelPolicy({
+            id: "tag-values-history",
+            channel: { agentId: "a1", channelName: "tag_values" },
+            messages: { mode: "latest", count: 100 },
+        });
+        const onlineMessages = await client.messages.listMessages({ agentId: "a1", channelName: "tag_values" }, { limit: 100, order: "asc" });
+        (0, chai_1.expect)(onlineMessages.map((message) => message.data)).to.deep.equal([{ value: 42 }]);
+        online = false;
+        const offlineMessages = await client.messages.listMessages({ agentId: "a1", channelName: "tag_values" }, { limit: 100, order: "asc" });
+        (0, chai_1.expect)(offlineMessages).to.deep.equal(onlineMessages);
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(1);
+    });
+    (0, mocha_1.it)("supports per-call cache opt-in for discovery reads", async () => {
+        let online = true;
+        const fetchMock = (0, helpers_1.createFetchMock)((url) => {
+            if (url.includes("/agents/")) {
+                return (0, helpers_1.createJsonResponse)({
+                    agents: [
+                        {
+                            id: "a1",
+                            organisation: "org1",
+                            name: "pump",
+                            display_name: "Pump",
+                            archived: false,
+                            group: "",
+                            type: "device",
+                            fixed_location: { latitude: 0, longitude: 0 },
+                            extra_config: {},
+                        },
+                    ],
+                    count: 1,
+                });
+            }
+            return (0, helpers_1.createJsonResponse)({ ok: true });
+        });
+        const client = new offline_cache_1.OfflineDataClient({
+            client: makeOnlineClient(fetchMock),
+            storage: new offline_cache_1.MemoryOfflineStorageAdapter(),
+            scope: { userId: "u1", organisationId: "org1", sourceId: "cloud" },
+            isOnline: () => online,
+        });
+        const onlineAgents = await client.agents.listAgents((0, request_options_1.requestOptions)({ cache: { mode: "read-through", policy: "agents" } }));
+        (0, chai_1.expect)((onlineAgents.agents ?? []).map((agent) => agent.id)).to.deep.equal(["a1"]);
+        online = false;
+        const offlineAgents = await client.agents.listAgents((0, request_options_1.requestOptions)({ cache: { mode: "read-through", policy: "agents" } }));
+        (0, chai_1.expect)(offlineAgents).to.deep.equal(onlineAgents);
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(1);
+    });
+    (0, mocha_1.it)("fails writes immediately while offline", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)();
+        const client = new offline_cache_1.OfflineDataClient({
+            client: makeOnlineClient(fetchMock),
+            storage: new offline_cache_1.MemoryOfflineStorageAdapter(),
+            scope: { userId: "u1", organisationId: "org1", sourceId: "cloud" },
+            isOnline: () => false,
+        });
+        let error;
+        try {
+            await client.messages.postMessage({ agentId: "a1", channelName: "commands" }, { data: { run: true } });
+        }
+        catch (err) {
+            error = err;
+        }
+        (0, chai_1.expect)(error).to.be.instanceOf(errors_1.DooverOfflineError);
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(0);
+    });
+    (0, mocha_1.it)("honours cache: false even when a stored policy exists", async () => {
+        let online = true;
+        const fetchMock = (0, helpers_1.createFetchMock)((url) => {
+            if (url.includes("/agents/a1/channels/tag_values/messages")) {
+                return (0, helpers_1.createJsonResponse)([
+                    {
+                        id: (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-06-10T00:00:00Z")),
+                        data: { value: 1 },
+                        attachments: [],
+                        author_id: "u1",
+                        channel: { agent_id: "a1", name: "tag_values" },
+                    },
+                ]);
+            }
+            return (0, helpers_1.createJsonResponse)({ ok: true });
+        });
+        const client = new offline_cache_1.OfflineDataClient({
+            client: makeOnlineClient(fetchMock),
+            storage: new offline_cache_1.MemoryOfflineStorageAdapter(),
+            scope: { userId: "u1", organisationId: "org1", sourceId: "cloud" },
+            isOnline: () => online,
+        });
+        client.setChannelPolicy({
+            id: "tag-values-history",
+            channel: { agentId: "a1", channelName: "tag_values" },
+            messages: { mode: "latest", count: 100 },
+        });
+        await client.messages.listMessages({ agentId: "a1", channelName: "tag_values" }, { limit: 100, order: "asc" }, (0, request_options_1.requestOptions)({ cache: false }));
+        online = false;
+        let error;
+        try {
+            await client.messages.listMessages({ agentId: "a1", channelName: "tag_values" }, { limit: 100, order: "asc" }, (0, request_options_1.requestOptions)({ cache: false }));
+        }
+        catch (err) {
+            error = err;
+        }
+        (0, chai_1.expect)(error).to.be.instanceOf(errors_1.DooverOfflineError);
+    });
+    (0, mocha_1.it)("tracks expired cached records and requires allowExpired to read them", async () => {
+        let online = true;
+        const fetchMock = (0, helpers_1.createFetchMock)((url) => {
+            if (url.includes("/agents/"))
+                return (0, helpers_1.createJsonResponse)({ agents: [], count: 0 });
+            return (0, helpers_1.createJsonResponse)({ ok: true });
+        });
+        const client = new offline_cache_1.OfflineDataClient({
+            client: makeOnlineClient(fetchMock),
+            storage: new offline_cache_1.MemoryOfflineStorageAdapter(),
+            scope: { userId: "u1", organisationId: "org1", sourceId: "cloud" },
+            isOnline: () => online,
+        });
+        await client.agents.listAgents((0, request_options_1.requestOptions)({ cache: { mode: "read-through", retentionMs: 1 } }));
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        online = false;
+        let error;
+        try {
+            await client.agents.listAgents((0, request_options_1.requestOptions)({ cache: { mode: "read-through" } }));
+        }
+        catch (err) {
+            error = err;
+        }
+        (0, chai_1.expect)(error).to.be.instanceOf(errors_1.DooverOfflineError);
+        (0, chai_1.expect)(client.getOfflineStatus().state).to.equal("cache-miss");
+        const expired = await client.agents.listAgents((0, request_options_1.requestOptions)({ cache: { mode: "read-through", allowExpired: true } }));
+        (0, chai_1.expect)(expired.agents).to.deep.equal([]);
+        (0, chai_1.expect)(client.getOfflineStatus().isExpired).to.equal(true);
+    });
+    (0, mocha_1.it)("persists gateway messages into latest-N cache according to channel policy", async () => {
+        let online = true;
+        const fetchMock = (0, helpers_1.createFetchMock)();
+        const client = new offline_cache_1.OfflineDataClient({
+            client: makeOnlineClient(fetchMock),
+            storage: new offline_cache_1.MemoryOfflineStorageAdapter(),
+            scope: { userId: "u1", organisationId: "org1", sourceId: "cloud" },
+            isOnline: () => online,
+        });
+        client.setChannelPolicy({
+            id: "camera-latest",
+            channel: { agentId: "a1", channelName: "camera" },
+            messages: { mode: "latest", count: 2 },
+        });
+        client.gateway.subscribeToChannel({ agent_id: "a1", name: "camera" }, {});
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        const ws = helpers_1.MockWebSocket.instances[helpers_1.MockWebSocket.instances.length - 1];
+        ws.open();
+        ws.receive({ op: 0, t: "Hello", d: {} });
+        ws.receive({
+            op: 0,
+            t: "Ready",
+            d: { session_id: "s1", session_token: "t1", subscriptions: [] },
+        });
+        for (const [idx, iso] of [
+            "2026-06-10T00:00:00Z",
+            "2026-06-10T00:01:00Z",
+            "2026-06-10T00:02:00Z",
+        ].entries()) {
+            ws.receive({
+                op: 0,
+                t: "MessageCreate",
+                d: {
+                    id: (0, snowflake_1.generateSnowflakeIdAtTime)(new Date(iso)),
+                    data: { idx },
+                    attachments: [],
+                    author_id: "u1",
+                    channel: { agent_id: "a1", name: "camera" },
+                },
+            });
+        }
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        online = false;
+        const messages = await client.messages.listMessages({ agentId: "a1", channelName: "camera" }, { limit: 10, order: "asc" });
+        (0, chai_1.expect)(messages.map((message) => message.data)).to.deep.equal([
+            { idx: 1 },
+            { idx: 2 },
+        ]);
+        (0, chai_1.expect)(client.getOfflineStatus().state).to.equal("cache-fallback");
+    });
+    (0, mocha_1.it)("notifies offline status listeners when cached data is used", async () => {
+        let online = true;
+        const fetchMock = (0, helpers_1.createFetchMock)((url) => {
+            if (url.includes("/agents/"))
+                return (0, helpers_1.createJsonResponse)({ agents: [], count: 0 });
+            return (0, helpers_1.createJsonResponse)({ ok: true });
+        });
+        const client = new offline_cache_1.OfflineDataClient({
+            client: makeOnlineClient(fetchMock),
+            storage: new offline_cache_1.MemoryOfflineStorageAdapter(),
+            scope: { userId: "u1", organisationId: "org1", sourceId: "cloud" },
+            isOnline: () => online,
+        });
+        const seen = [];
+        const off = client.onOfflineStatusChange((status) => seen.push(status.state));
+        await client.agents.listAgents((0, request_options_1.requestOptions)({ cache: { mode: "read-through" } }));
+        online = false;
+        await client.agents.listAgents((0, request_options_1.requestOptions)({ cache: { mode: "read-through" } }));
+        off();
+        (0, chai_1.expect)(seen).to.include("online");
+        (0, chai_1.expect)(seen).to.include("cache-fallback");
+    });
+    (0, mocha_1.it)("caches selected attachment blobs through the blob storage adapter", async () => {
+        let online = true;
+        const fetchMock = (0, helpers_1.createFetchMock)((url) => {
+            if (url.includes("/attachments/thumb1")) {
+                return (0, helpers_1.createBlobResponse)("thumbnail-bytes", {
+                    headers: { "content-type": "image/jpeg" },
+                });
+            }
+            return (0, helpers_1.createJsonResponse)({ ok: true });
+        });
+        const client = new offline_cache_1.OfflineDataClient({
+            client: makeOnlineClient(fetchMock),
+            storage: new offline_cache_1.MemoryOfflineStorageAdapter(),
+            scope: { userId: "u1", organisationId: "org1", sourceId: "cloud" },
+            isOnline: () => online,
+        });
+        client.setChannelPolicy({
+            id: "camera-thumbnails",
+            channel: { agentId: "a1", channelName: "camera" },
+            messageAttachments: { include: "metadata-and-selected-blobs" },
+        });
+        const onlineBlob = await client.messages.getMessageAttachment({ agentId: "a1", channelName: "camera" }, "m1", "thumb1");
+        (0, chai_1.expect)(await onlineBlob.text()).to.equal("thumbnail-bytes");
+        online = false;
+        const offlineBlob = await client.messages.getMessageAttachment({ agentId: "a1", channelName: "camera" }, "m1", "thumb1");
+        (0, chai_1.expect)(await offlineBlob.text()).to.equal("thumbnail-bytes");
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(1);
+    });
+});

package/dist/test/react-exports.test.js

@@ -39,6 +39,7 @@ const r = __importStar(require("../react"));
 (0, mocha_1.describe)("react exports", () => {
     (0, mocha_1.it)("exports useClientStatus and the key helpers", () => {
         (0, chai_1.expect)(r.useClientStatus).to.be.a("function");
+        (0, chai_1.expect)(r.useOfflineStatus).to.be.a("function");
         (0, chai_1.expect)(r.channelAggregateQueryKey).to.be.a("function");
         (0, chai_1.expect)(r.useConnectionState).to.be.a("function"); // still exported (soft-deprecated)
     });

package/dist/test/refine.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/refine.test.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+const mocha_1 = require("mocha");
+const refine_1 = require("../refine");
+const rest_client_1 = require("../http/rest-client");
+const helpers_1 = require("./helpers");
+(0, mocha_1.describe)("createRefineDataProvider", () => {
+    (0, mocha_1.it)("builds list requests with api_path, pagination, sorters, filters and organisation header", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)(() => (0, helpers_1.createJsonResponse)({ count: 1, results: [{ id: "1", name: "Device" }] }));
+        const rest = new rest_client_1.RestClient({
+            dataRestUrl: "https://data.example.com/api",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://data.example.com/gateway",
+            organisationId: "org-1",
+            fetchImpl: fetchMock,
+        });
+        const provider = (0, refine_1.createRefineDataProvider)(rest);
+        const result = await provider.getList({
+            resource: "devices",
+            pagination: { currentPage: 2, pageSize: 25 },
+            sorters: [{ field: "name", order: "desc" }],
+            filters: [
+                { field: "search", operator: "contains", value: "pump" },
+                { field: "archived", operator: "eq", value: false },
+            ],
+            meta: { api_path: "organisations/:organisationId/devices", organisationId: "org-2" },
+        });
+        (0, chai_1.expect)(result).to.deep.equal({
+            data: [{ id: "1", name: "Device" }],
+            total: 1,
+        });
+        (0, chai_1.expect)(fetchMock.callCount).to.equal(1);
+        const [url, init] = fetchMock.getCall(0).args;
+        (0, chai_1.expect)(url).to.equal("https://control.example.com/organisations/org-2/devices/?page=2&per_page=25&ordering=-name&search=pump&archived=false");
+        (0, chai_1.expect)((init?.headers).get("X-Doover-Organisation")).to.equal("org-1");
+        const explicit = await provider.getList({
+            resource: "devices",
+            meta: { organisation: "org-3" },
+        });
+        (0, chai_1.expect)(explicit.total).to.equal(1);
+        (0, chai_1.expect)((fetchMock.getCall(1).args[1]?.headers).get("X-Doover-Organisation")).to.equal("org-3");
+    });
+    (0, mocha_1.it)("renames object fields and sends JSON mutations through RestClient", async () => {
+        const fetchMock = (0, helpers_1.createFetchMock)((_url, init) => (0, helpers_1.createJsonResponse)(JSON.parse(String(init?.body))));
+        const rest = new rest_client_1.RestClient({
+            dataRestUrl: "https://data.example.com/api",
+            controlApiUrl: "https://control.example.com",
+            dataWssUrl: "wss://data.example.com/gateway",
+            fetchImpl: fetchMock,
+        });
+        const provider = (0, refine_1.createRefineDataProvider)(rest);
+        const result = await provider.update({
+            resource: "devices",
+            id: "device-1",
+            variables: { group: { id: "group-1", name: "Group" } },
+            meta: { renameFields: { group: "group_id" } },
+        });
+        (0, chai_1.expect)(result.data).to.deep.equal({
+            group: "group-1",
+            group_id: "group-1",
+        });
+    });
+});
+(0, mocha_1.describe)("getApiPath", () => {
+    (0, mocha_1.it)("falls back across api_path candidates", () => {
+        (0, chai_1.expect)((0, refine_1.getApiPath)("domains", {
+            api_path: ["organisations/:organisationId/domains", "organisations/domains"],
+        })).to.equal("organisations/domains");
+    });
+});

package/dist/types/viewer.d.ts

@@ -29,6 +29,43 @@ export interface User {
     __source?: SourceProvenance;
     [key: string]: unknown;
 }
+export interface Theme {
+    [key: string]: unknown;
+}
+export interface OrganisationDomain {
+    id: string;
+    hostname: string;
+    default: boolean;
+}
+export interface Organisation {
+    id: string;
+    name: string;
+    archived: boolean;
+    application_id: string;
+    domains: OrganisationDomain[];
+    root_group?: unknown;
+    retention_period?: number;
+    legacy_doover_api_key?: string | null;
+    llm_api_key?: string | null;
+    extra_config?: Record<string, unknown>;
+    theme?: Theme;
+    __source?: SourceProvenance;
+    [key: string]: unknown;
+}
+export interface CustomerSite {
+    id: string;
+    name: string;
+    application_id: string;
+    archived: boolean;
+    theme: Theme;
+}
+export interface PaginatedResponse<T> {
+    count: number;
+    results: T[];
+    next?: string | null;
+    previous?: string | null;
+    [key: string]: unknown;
+}
 export interface GetAgentsOptions {
     includeArchived?: boolean;
     includeOrganisations?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doover-js",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "TypeScript client for Doover.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,6 +16,10 @@
     "./react": {
       "types": "./dist/react/index.d.ts",
       "default": "./dist/react/index.js"
+    },
+    "./refine": {
+      "types": "./dist/refine/index.d.ts",
+      "default": "./dist/refine/index.js"
     }
   },
   "repository": {
@@ -42,10 +46,14 @@
   ],
   "license": "Apache-2.0",
   "peerDependencies": {
+    "@refinedev/core": "^5",
     "@tanstack/react-query": "^5",
     "react": "^18 || ^19"
   },
   "peerDependenciesMeta": {
+    "@refinedev/core": {
+      "optional": true
+    },
     "@tanstack/react-query": {
       "optional": true
     },