doover-js 0.6.5 → 0.6.7

package/dist/client/request-options.d.ts

@@ -0,0 +1,23 @@
+import type { OfflineReadCacheOptions } from "./offline-cache";
+export declare const REQUEST_OPTIONS_SYMBOL: unique symbol;
+export interface DooverRequestOptions {
+    /**
+     * Restrict a call to these source ids on a `MultiplexClient`.
+     */
+    sources?: string[];
+    /**
+     * Offline cache behavior for this specific call. `false` opts out even when
+     * a stored channel policy would otherwise match.
+     */
+    cache?: OfflineReadCacheOptions | false;
+    [REQUEST_OPTIONS_SYMBOL]?: true;
+}
+export declare function requestOptions<T extends Omit<DooverRequestOptions, typeof REQUEST_OPTIONS_SYMBOL>>(options: T): T & {
+    [REQUEST_OPTIONS_SYMBOL]: true;
+};
+export declare function isDooverRequestOptions(value: unknown): value is DooverRequestOptions;
+export declare function splitRequestOptions(args: unknown[]): {
+    args: unknown[];
+    request?: DooverRequestOptions;
+};
+export declare function delegateRequestOptions(request?: DooverRequestOptions): DooverRequestOptions | undefined;

package/dist/client/request-options.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REQUEST_OPTIONS_SYMBOL = void 0;
+exports.requestOptions = requestOptions;
+exports.isDooverRequestOptions = isDooverRequestOptions;
+exports.splitRequestOptions = splitRequestOptions;
+exports.delegateRequestOptions = delegateRequestOptions;
+exports.REQUEST_OPTIONS_SYMBOL = Symbol.for("doover.requestOptions");
+function requestOptions(options) {
+    return { ...options, [exports.REQUEST_OPTIONS_SYMBOL]: true };
+}
+function isDooverRequestOptions(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const candidate = value;
+    return (candidate[exports.REQUEST_OPTIONS_SYMBOL] === true ||
+        Array.isArray(candidate.sources) ||
+        "cache" in candidate);
+}
+function splitRequestOptions(args) {
+    const last = args[args.length - 1];
+    if (!isDooverRequestOptions(last))
+        return { args };
+    return { args: args.slice(0, -1), request: last };
+}
+function delegateRequestOptions(request) {
+    if (!request?.sources)
+        return undefined;
+    return requestOptions({ sources: request.sources });
+}

package/dist/http/rest-client.js

@@ -138,7 +138,10 @@ class RestClient {
             return response.json();
         }
         if (contentType.includes("application/octet-stream") ||
-            contentType.includes("application/pdf")) {
+            contentType.includes("application/pdf") ||
+            contentType.startsWith("image/") ||
+            contentType.startsWith("video/") ||
+            contentType.startsWith("audio/")) {
             return response.blob();
         }
         const text = await response.text();

package/dist/index.d.ts

@@ -26,7 +26,11 @@ export type { ChannelHandlers } from "./gateway/gateway-client";
 export type { RpcStatsSnapshot } from "./client/stats";
 export { ALL_CAPABILITIES } from "./client/capabilities";
 export type { Capability } from "./client/capabilities";
-export { UnsupportedCapabilityError, AmbiguousWriteError } from "./client/errors";
+export { UnsupportedCapabilityError, AmbiguousWriteError, DooverOfflineError } from "./client/errors";
+export { OfflineDataClient, MemoryOfflineStorageAdapter, DEFAULT_OFFLINE_RETENTION_MS, } from "./client/offline-cache";
+export type { OfflineCacheMode, OfflineReadCacheOptions, OfflineChannelPolicy, OfflineCacheScope, OfflineCacheRecord, OfflineStorageAdapter, OfflineDataClientOptions, } from "./client/offline-cache";
+export { requestOptions, isDooverRequestOptions, splitRequestOptions, } from "./client/request-options";
+export type { DooverRequestOptions } from "./client/request-options";
 export type { DataClient, AgentScope, DataClientStatus, DataClientConnectionState, AgentsApiLike, AggregatesApiLike, AlarmsApiLike, ChannelsApiLike, ConnectionsApiLike, MessagesApiLike, NotificationsApiLike, PermissionsApiLike, ProcessorsApiLike, TurnApiLike, UsersApiLike, GatewayClientLike, RpcDispatcherLike, } from "./client/data-client";
 export type { SourceProvenance, SourceProvenanceViaRest, SourceProvenanceViaGateway, } from "./types/provenance";
 export { DooverAuth } from "./auth/doover-auth";

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateSnowflakeIdAtTime = exports.extractSnowflakeId = exports.addTimestampToMessage = exports.DV_AUDIT_CHANNEL = exports.getIdentifierFromPath = exports.DooverDataProvider = exports.DooverValidationError = exports.DooverGatewayError = exports.DooverApiError = exports.RestClient = exports.GatewayClient = exports.buildAuth = exports.DooverAuthError = exports.AuthProfile = exports.DooverTokenAuth = exports.CookieAuth = exports.DooverAuth = exports.AmbiguousWriteError = exports.UnsupportedCapabilityError = exports.ALL_CAPABILITIES = exports.DooverRpcError = exports.RpcDispatcher = exports.UsersApi = exports.TurnApi = exports.ProcessorsApi = exports.PermissionsApi = exports.OrganisationsApi = exports.NotificationsApi = exports.MessagesApi = exports.ConnectionsApi = exports.ChannelsApi = exports.AlarmsApi = exports.AggregatesApi = exports.AgentsApi = exports.DooverStatsCollector = exports.resetDooverClient = exports.peekDooverClient = exports.getDooverClient = exports.MultiplexClient = exports.LocalAgentClient = exports.DooverClient = void 0;
+exports.generateSnowflakeIdAtTime = exports.extractSnowflakeId = exports.addTimestampToMessage = exports.DV_AUDIT_CHANNEL = exports.getIdentifierFromPath = exports.DooverDataProvider = exports.DooverValidationError = exports.DooverGatewayError = exports.DooverApiError = exports.RestClient = exports.GatewayClient = exports.buildAuth = exports.DooverAuthError = exports.AuthProfile = exports.DooverTokenAuth = exports.CookieAuth = exports.DooverAuth = exports.splitRequestOptions = exports.isDooverRequestOptions = exports.requestOptions = exports.DEFAULT_OFFLINE_RETENTION_MS = exports.MemoryOfflineStorageAdapter = exports.OfflineDataClient = exports.DooverOfflineError = exports.AmbiguousWriteError = exports.UnsupportedCapabilityError = exports.ALL_CAPABILITIES = exports.DooverRpcError = exports.RpcDispatcher = exports.UsersApi = exports.TurnApi = exports.ProcessorsApi = exports.PermissionsApi = exports.OrganisationsApi = exports.NotificationsApi = exports.MessagesApi = exports.ConnectionsApi = exports.ChannelsApi = exports.AlarmsApi = exports.AggregatesApi = exports.AgentsApi = exports.DooverStatsCollector = exports.resetDooverClient = exports.peekDooverClient = exports.getDooverClient = exports.MultiplexClient = exports.LocalAgentClient = exports.DooverClient = void 0;
 var doover_client_1 = require("./client/doover-client");
 Object.defineProperty(exports, "DooverClient", { enumerable: true, get: function () { return doover_client_1.DooverClient; } });
 var local_agent_client_1 = require("./client/local-agent-client");
@@ -46,6 +46,15 @@ Object.defineProperty(exports, "ALL_CAPABILITIES", { enumerable: true, get: func
 var errors_2 = require("./client/errors");
 Object.defineProperty(exports, "UnsupportedCapabilityError", { enumerable: true, get: function () { return errors_2.UnsupportedCapabilityError; } });
 Object.defineProperty(exports, "AmbiguousWriteError", { enumerable: true, get: function () { return errors_2.AmbiguousWriteError; } });
+Object.defineProperty(exports, "DooverOfflineError", { enumerable: true, get: function () { return errors_2.DooverOfflineError; } });
+var offline_cache_1 = require("./client/offline-cache");
+Object.defineProperty(exports, "OfflineDataClient", { enumerable: true, get: function () { return offline_cache_1.OfflineDataClient; } });
+Object.defineProperty(exports, "MemoryOfflineStorageAdapter", { enumerable: true, get: function () { return offline_cache_1.MemoryOfflineStorageAdapter; } });
+Object.defineProperty(exports, "DEFAULT_OFFLINE_RETENTION_MS", { enumerable: true, get: function () { return offline_cache_1.DEFAULT_OFFLINE_RETENTION_MS; } });
+var request_options_1 = require("./client/request-options");
+Object.defineProperty(exports, "requestOptions", { enumerable: true, get: function () { return request_options_1.requestOptions; } });
+Object.defineProperty(exports, "isDooverRequestOptions", { enumerable: true, get: function () { return request_options_1.isDooverRequestOptions; } });
+Object.defineProperty(exports, "splitRequestOptions", { enumerable: true, get: function () { return request_options_1.splitRequestOptions; } });
 var doover_auth_1 = require("./auth/doover-auth");
 Object.defineProperty(exports, "DooverAuth", { enumerable: true, get: function () { return doover_auth_1.DooverAuth; } });
 var cookie_auth_1 = require("./auth/cookie-auth");

package/dist/react/index.d.ts

@@ -2,6 +2,8 @@ export { DooverProvider, useDooverClient } from "./context";
 export type { DooverProviderProps } from "./context";
 export type { DataClientStatus, DataClientConnectionState, AgentScope } from "../client/data-client";
 export { useClientStatus } from "./useClientStatus";
+export { useOfflineStatus, hasOfflineStatus } from "./useOfflineStatus";
+export type { OfflineStatusSnapshot, OfflineStatusClient } from "./useOfflineStatus";
 export { useConnectionState } from "./useConnectionState";
 export type { ConnectionState, ConnectionStatus } from "./useConnectionState";
 export { useAgentConnections, agentConnectionsQueryKey, } from "./useAgentConnections";

package/dist/react/index.js

@@ -1,11 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resetSharedQueryClient = exports.getSharedQueryClient = exports.useTurnCredentials = exports.useDeviceMap = exports.multiAgentChannelMessagesQueryKey = exports.useMultiAgentChannelMessages = exports.multiAgentAggregatesQueryKey = exports.useMultiAgentAggregates = exports.useSendRpc = exports.invocationLogsQueryKey = exports.useInvocationLogs = exports.channelMessageQueryKey = exports.useChannelMessage = exports.channelMessagesQueryKey = exports.useChannelMessages = exports.useUpdateMessage = exports.useUpdateAggregate = exports.useSendMessage = exports.useAgentChannel = exports.channelAggregateQueryKey = exports.useChannelAggregate = exports.useChannelSubscription = exports.agentConnectionsQueryKey = exports.useAgentConnections = exports.useConnectionState = exports.useClientStatus = exports.useDooverClient = exports.DooverProvider = void 0;
+exports.resetSharedQueryClient = exports.getSharedQueryClient = exports.useTurnCredentials = exports.useDeviceMap = exports.multiAgentChannelMessagesQueryKey = exports.useMultiAgentChannelMessages = exports.multiAgentAggregatesQueryKey = exports.useMultiAgentAggregates = exports.useSendRpc = exports.invocationLogsQueryKey = exports.useInvocationLogs = exports.channelMessageQueryKey = exports.useChannelMessage = exports.channelMessagesQueryKey = exports.useChannelMessages = exports.useUpdateMessage = exports.useUpdateAggregate = exports.useSendMessage = exports.useAgentChannel = exports.channelAggregateQueryKey = exports.useChannelAggregate = exports.useChannelSubscription = exports.agentConnectionsQueryKey = exports.useAgentConnections = exports.useConnectionState = exports.hasOfflineStatus = exports.useOfflineStatus = exports.useClientStatus = exports.useDooverClient = exports.DooverProvider = void 0;
 var context_1 = require("./context");
 Object.defineProperty(exports, "DooverProvider", { enumerable: true, get: function () { return context_1.DooverProvider; } });
 Object.defineProperty(exports, "useDooverClient", { enumerable: true, get: function () { return context_1.useDooverClient; } });
 var useClientStatus_1 = require("./useClientStatus");
 Object.defineProperty(exports, "useClientStatus", { enumerable: true, get: function () { return useClientStatus_1.useClientStatus; } });
+var useOfflineStatus_1 = require("./useOfflineStatus");
+Object.defineProperty(exports, "useOfflineStatus", { enumerable: true, get: function () { return useOfflineStatus_1.useOfflineStatus; } });
+Object.defineProperty(exports, "hasOfflineStatus", { enumerable: true, get: function () { return useOfflineStatus_1.hasOfflineStatus; } });
 var useConnectionState_1 = require("./useConnectionState");
 Object.defineProperty(exports, "useConnectionState", { enumerable: true, get: function () { return useConnectionState_1.useConnectionState; } });
 var useAgentConnections_1 = require("./useAgentConnections");

package/dist/react/useChannelAggregate.d.ts

@@ -1,6 +1,7 @@
 import { type UseQueryResult } from "@tanstack/react-query";
 import type { Aggregate } from "../types/common";
 import type { ChannelIdentifier } from "../types/viewer";
+import { type OfflineStatusSnapshot } from "./useOfflineStatus";
 export declare function channelAggregateQueryKey(agentId: string | undefined, channelName: string | undefined, sources?: string[]): readonly ["doover", "agent", string | undefined, "channel", string | undefined, "src", string];
 /**
  * Shape returned by `useChannelAggregate`. Shadows the react-query
@@ -23,6 +24,8 @@ export interface UseChannelAggregateResult<TData> extends Omit<UseQueryResult<Ag
      * years in the future).
      */
     last_updated: number | null | undefined;
+    /** Offline/cache status when the provided client supports offline caching. */
+    offline: OfflineStatusSnapshot;
 }
 export interface UseChannelAggregateOptions {
     /**

package/dist/react/useChannelAggregate.js

@@ -7,6 +7,7 @@ const react_query_1 = require("@tanstack/react-query");
 const errors_1 = require("../http/errors");
 const context_1 = require("./context");
 const useChannelSubscription_1 = require("./useChannelSubscription");
+const useOfflineStatus_1 = require("./useOfflineStatus");
 function channelAggregateQueryKey(agentId, channelName, sources) {
     const sourceDim = sources && sources.length ? [...sources].sort().join(",") : "*";
     return ["doover", "agent", agentId, "channel", channelName, "src", sourceDim];
@@ -24,6 +25,7 @@ function channelAggregateQueryKey(agentId, channelName, sources) {
  */
 function useChannelAggregate(identifier, options) {
     const client = (0, context_1.useDooverClient)();
+    const offline = (0, useOfflineStatus_1.useOfflineStatus)();
     const queryClient = (0, react_query_1.useQueryClient)();
     const { agentId, channelName } = identifier;
     const sources = options?.sources;
@@ -74,5 +76,6 @@ function useChannelAggregate(identifier, options) {
         data: aggregate?.data,
         attachments: aggregate?.attachments,
         last_updated: aggregate?.last_updated,
+        offline,
     };
 }

package/dist/react/useChannelMessages.d.ts

@@ -1,6 +1,7 @@
 import { type InfiniteData, type UseInfiniteQueryResult } from "@tanstack/react-query";
 import type { MessageStructure } from "../types/common";
 import type { ChannelIdentifier } from "../types/viewer";
+import { type OfflineStatusSnapshot } from "./useOfflineStatus";
 export declare function channelMessagesQueryKey(agentId: string | undefined, channelName: string | undefined, fields?: readonly string[], sources?: string[]): readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", "src", string] | readonly ["doover", "agent", string | undefined, "channel", string | undefined, "messages", "src", string, {
     readonly fields: string[];
 }];
@@ -49,6 +50,8 @@ export interface UseChannelMessagesResult<TData> extends Omit<UseInfiniteQueryRe
     messages: MessageStructure<TData>[];
     /** Raw react-query data (pages). */
     data: InfiniteData<Page<TData>> | undefined;
+    /** Offline/cache status when the provided client supports offline caching. */
+    offline: OfflineStatusSnapshot;
 }
 /**
  * Paginated infinite query over `DooverDataProvider.getMessages`, with live

package/dist/react/useChannelMessages.js

@@ -6,6 +6,7 @@ const react_1 = require("react");
 const react_query_1 = require("@tanstack/react-query");
 const context_1 = require("./context");
 const useChannelSubscription_1 = require("./useChannelSubscription");
+const useOfflineStatus_1 = require("./useOfflineStatus");
 function channelMessagesQueryKey(agentId, channelName, fields, sources) {
     // Source-dimension the key (multiplex source subsets cache independently);
     // "*" means "all/unspecified" for a plain DooverClient/LocalAgentClient.
@@ -28,6 +29,7 @@ function channelMessagesQueryKey(agentId, channelName, fields, sources) {
  */
 function useChannelMessages(identifier, options) {
     const client = (0, context_1.useDooverClient)();
+    const offline = (0, useOfflineStatus_1.useOfflineStatus)();
     const queryClient = (0, react_query_1.useQueryClient)();
     const { agentId, channelName } = identifier;
     const limit = options?.limit;
@@ -99,5 +101,5 @@ function useChannelMessages(identifier, options) {
         query.fetchNextPage();
     }, [autoPaginate, query.isFetching, query.hasNextPage, query.fetchNextPage]);
     const messages = (0, react_1.useMemo)(() => (query.data?.pages ?? []).flat(), [query.data]);
-    return { ...query, messages };
+    return { ...query, messages, offline };
 }

package/dist/react/useOfflineStatus.d.ts

@@ -0,0 +1,8 @@
+import type { OfflineStatusSnapshot } from "../client/offline-cache";
+export type { OfflineStatusSnapshot } from "../client/offline-cache";
+export interface OfflineStatusClient {
+    getOfflineStatus(): OfflineStatusSnapshot;
+    onOfflineStatusChange(listener: (status: OfflineStatusSnapshot) => void): () => void;
+}
+export declare function hasOfflineStatus(client: unknown): client is OfflineStatusClient;
+export declare function useOfflineStatus(): OfflineStatusSnapshot;

package/dist/react/useOfflineStatus.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasOfflineStatus = hasOfflineStatus;
+exports.useOfflineStatus = useOfflineStatus;
+const react_1 = require("react");
+const context_1 = require("./context");
+function hasOfflineStatus(client) {
+    return (!!client &&
+        typeof client === "object" &&
+        typeof client.getOfflineStatus === "function" &&
+        typeof client.onOfflineStatusChange === "function");
+}
+const UNAVAILABLE_OFFLINE_STATUS = {
+    online: true,
+    state: "online",
+    isOfflineFallback: false,
+    isExpired: false,
+    at: 0,
+};
+function useOfflineStatus() {
+    const client = (0, context_1.useDooverClient)();
+    return (0, react_1.useSyncExternalStore)((listener) => hasOfflineStatus(client)
+        ? client.onOfflineStatusChange(listener)
+        : () => undefined, () => hasOfflineStatus(client)
+        ? client.getOfflineStatus()
+        : UNAVAILABLE_OFFLINE_STATUS, () => UNAVAILABLE_OFFLINE_STATUS);
+}

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/types/common.d.ts

@@ -174,11 +174,17 @@ export type RpcStatus<TPending = undefined> = {
 } | {
     code: "success";
 };
+/** Who initiated an RPC (e.g. the logged-in user dispatching a ui_cmd). */
+export interface RpcActor {
+    id: string;
+    name: string;
+}
 /** Shape a consumer posts to initiate an RPC. */
 export interface RpcRequest<TRequest = object> {
     app_key?: string;
     method: string;
     request: TRequest;
+    actor?: RpcActor;
 }
 /** Shape of the message the server maintains as the RPC progresses. */
 export interface RpcMessageData<TRequest = object, TResponse = object, TPending = undefined> extends RpcRequest<TRequest> {

package/package.json

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