doover-js 0.7.0 → 0.7.1

package/dist/apis/messages-api.d.ts

@@ -3,6 +3,13 @@ import type { CreateMessageRequest, DataSeries, MessageStructure, UpdateMessageR
 import type { DooverRequestOptions } from "../client/request-options";
 export interface ListMessagesParams {
     before?: string;
+    /**
+     * Lower-bound cursor (exclusive). With `before` set (or defaulted) it merely
+     * floors the window. On its own — `after` set, `before` omitted — it pages
+     * *forward*: the server returns the `limit` **oldest** messages strictly
+     * newer than the cursor, oldest-first. This is the only way to walk history
+     * upward toward "now".
+     */
     after?: string;
     limit?: number;
     field_name?: string[];

package/dist/apis/messages-api.js

@@ -5,15 +5,31 @@ const snowflake_1 = require("../utils/snowflake");
 const _args_1 = require("./_args");
 function resolveListMessagesParams(params) {
     const order = params?.order ?? "desc";
+    const hasAfter = params?.after !== undefined;
+    const hasBefore = params?.before !== undefined;
+    // The server keys pagination on whichever bound is sent: `before` walks
+    // newest-first downward, `after` alone walks oldest-first upward (the N
+    // oldest messages strictly newer than the cursor). Sending `after` without
+    // `before` is the only way to page forward; sending both, or neither, keeps
+    // the newest-first behaviour (defaulting `before` to "now" when unbounded).
+    if (hasAfter && !hasBefore) {
+        const query = {
+            after: params.after,
+            limit: params?.limit ?? 10,
+        };
+        if (params?.field_name !== undefined)
+            query.field_name = params.field_name;
+        return { query, order, serverAscending: true };
+    }
     const query = {
         before: params?.before ?? (0, snowflake_1.generateSnowflakeIdAtTime)(new Date()),
         limit: params?.limit ?? 10,
     };
-    if (params?.after !== undefined)
+    if (hasAfter)
         query.after = params.after;
     if (params?.field_name !== undefined)
         query.field_name = params.field_name;
-    return { query, order };
+    return { query, order, serverAscending: false };
 }
 class MessagesApi {
     constructor(rest) {
@@ -24,10 +40,13 @@ class MessagesApi {
         return this._listMessages(agentId, channelName, options);
     }
     async _listMessages(agentId, channelName, params) {
-        const { query, order } = resolveListMessagesParams(params);
+        const { query, order, serverAscending } = resolveListMessagesParams(params);
         const response = await this.rest.get(`/agents/${agentId}/channels/${channelName}/messages`, query);
         const stamped = response.map(snowflake_1.addTimestampToMessage);
-        return order === "asc" ? [...stamped].reverse() : stamped;
+        // The server returns newest-first for `before` and oldest-first for a bare
+        // `after`; reverse only when that native order differs from what was asked.
+        const wantAscending = order === "asc";
+        return serverAscending === wantAscending ? stamped : [...stamped].reverse();
     }
     async postMessage(...args) {
         if (typeof args[0] === "string") {

package/dist/react/useChannelMessages.js

@@ -99,38 +99,68 @@ function useChannelMessages(identifier, options) {
         queryKey: key,
         enabled: !!agentId && !!channelName,
         staleTime: Infinity,
-        initialPageParam: (anchor ?? initialBefore),
-        getNextPageParam: (lastPage) => lastPage && lastPage.length > 0 ? lastPage[0]?.id : undefined,
+        initialPageParam: { before: anchor ?? initialBefore },
+        // Older (down): the next cursor is the oldest id currently held.
+        getNextPageParam: (lastPage) => lastPage && lastPage.length > 0
+            ? { before: lastPage[0]?.id }
+            : undefined,
+        // Newer (up): only for an anchored window — the live window already begins
+        // at "now", so it has nothing above to page into. `after` = newest id held;
+        // the server returns the oldest messages above it, walking up toward now.
+        // An empty page whose own cursor was already a forward `after` means the
+        // top is reached; an empty *initial* page (nothing below the anchor) still
+        // seeds the walk from the anchor, since messages may sit above it.
+        getPreviousPageParam: (firstPage, _all, firstPageParam) => {
+            if (!anchor)
+                return undefined;
+            if (firstPage && firstPage.length > 0) {
+                return { after: firstPage[firstPage.length - 1]?.id };
+            }
+            if (firstPageParam?.after !== undefined)
+                return undefined;
+            return { after: anchor };
+        },
         queryFn: async ({ pageParam }) => {
             if (!agentId || !channelName)
                 return [];
             const id = { agentId, channelName };
-            // Resolve `before` here rather than letting the API default it, so the
-            // range store records the exact bound the request proved.
-            const before = typeof pageParam === "string"
-                ? pageParam
-                : (0, snowflake_1.generateSnowflakeIdAtTime)(new Date());
+            const param = (pageParam ?? {});
             // Mirrors the API's own default; the store needs the limit actually applied
             const effectiveLimit = limit ?? DEFAULT_PAGE_LIMIT;
+            // Pass `{ sources }` as a trailing bag only when set — cast through
+            // `unknown` since the TypeScript overloads don't declare it.
+            const runList = (params) => sources
+                ? client.messages.listMessages(id, params, { sources })
+                : client.messages.listMessages(id, params);
+            // Forward (newer) page: `after` alone pages oldest-first upward. Bypasses
+            // the range store, which models before-anchored windows only.
+            if (param.after !== undefined && param.before === undefined) {
+                const page = await runList({
+                    after: param.after,
+                    ...(limit !== undefined ? { limit } : {}),
+                    ...(fields && fields.length > 0 ? { field_name: fields } : {}),
+                    order: "asc",
+                });
+                return page;
+            }
+            // Older page. Resolve `before` here rather than letting the API default
+            // it, so the range store records the exact bound the request proved.
+            const before = typeof param.before === "string"
+                ? param.before
+                : (0, snowflake_1.generateSnowflakeIdAtTime)(new Date());
             if (rangeCacheable) {
                 const cached = store.read(BigInt(before), effectiveLimit);
                 if (cached)
                     return cached;
             }
             const requestedAt = Date.now();
-            const params = {
+            const page = await runList({
                 before,
                 ...(limit !== undefined ? { limit } : {}),
                 ...(fields && fields.length > 0 ? { field_name: fields } : {}),
                 ...(after !== undefined ? { after } : {}),
                 order: "asc",
-            };
-            // Pass `{ sources }` as a trailing bag only when set — cast through
-            // `never` since the TypeScript overloads don't declare it.
-            const sourcesArg = sources ? { sources } : undefined;
-            const page = sourcesArg
-                ? await client.messages.listMessages(id, params, sourcesArg)
-                : await client.messages.listMessages(id, params);
+            });
             if (rangeCacheable) {
                 store.record({
                     before: BigInt(before),

package/dist/test/apis.test.js

@@ -229,6 +229,36 @@ function setupRest(responseFactory) {
         (0, chai_1.expect)(formData.get("json_payload")).to.equal(JSON.stringify({ data: { x: 1 } }));
         (0, chai_1.expect)(formData.get("attachment-0")).to.be.instanceOf(Blob);
     });
+    (0, mocha_1.it)("pages forward with a bare `after`: sends no `before`, keeps oldest-first", async () => {
+        const older = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-01T00:00:00Z"));
+        const newer = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date("2026-01-02T00:00:00Z"));
+        // The `after`-only route returns oldest-first natively (scan_index_forward).
+        const nativeAsc = [
+            { id: older, author_id: "u", channel: { agent_id: "a1", name: "c1" }, data: {}, attachments: [] },
+            { id: newer, author_id: "u", channel: { agent_id: "a1", name: "c1" }, data: {}, attachments: [] },
+        ];
+        let lastQuery;
+        const { rest } = setupRest((url) => {
+            if (url.endsWith("/messages") || url.includes("/messages?")) {
+                lastQuery = new URL(url).searchParams;
+                return (0, helpers_1.createJsonResponse)(nativeAsc);
+            }
+            return (0, helpers_1.createJsonResponse)([]);
+        });
+        const api = new messages_api_1.MessagesApi(rest);
+        // asc: server order already matches → no reversal, no `before` sent.
+        const asc = await api.listMessages("a1", "c1", { after: older, limit: 5, order: "asc" });
+        (0, chai_1.expect)(lastQuery?.get("after")).to.equal(older);
+        (0, chai_1.expect)(lastQuery?.has("before"), "bare `after` must not send `before`").to.equal(false);
+        (0, chai_1.expect)(asc.map((m) => m.id)).to.deep.equal([older, newer]);
+        // desc over the same forward route reverses the native ascending page.
+        const desc = await api.listMessages("a1", "c1", { after: older, limit: 5, order: "desc" });
+        (0, chai_1.expect)(desc.map((m) => m.id)).to.deep.equal([newer, older]);
+        // With `before` present, `after` is only a floor and both bounds are sent.
+        await api.listMessages("a1", "c1", { before: newer, after: older, limit: 5, order: "asc" });
+        (0, chai_1.expect)(lastQuery?.get("before")).to.equal(newer);
+        (0, chai_1.expect)(lastQuery?.get("after")).to.equal(older);
+    });
     (0, mocha_1.it)("covers aggregates and alarms methods", async () => {
         const { rest, fetchMock } = setupRest((url) => {
             if (url.includes("/attachments/")) {

package/dist/test/react-channel-messages-forward.test.d.ts

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

package/dist/test/react-channel-messages-forward.test.js

@@ -0,0 +1,139 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const chai_1 = require("chai");
+const mocha_1 = require("mocha");
+const react_1 = require("@testing-library/react");
+const react_query_1 = require("@tanstack/react-query");
+const sinon_1 = __importDefault(require("sinon"));
+const doover_client_1 = require("../client/doover-client");
+const react_2 = require("../react");
+const messageRangeStore_1 = require("../react/messageRangeStore");
+const snowflake_1 = require("../utils/snowflake");
+const helpers_1 = require("./helpers");
+const AGENT = "agent-1";
+const CHANNEL = "camera_1";
+const NOW = Date.now();
+/** `COUNT` messages, one per minute, ascending by id (index 0 = oldest). */
+const COUNT = 60;
+const ALL = Array.from({ length: COUNT }, (_, i) => {
+    const at = new Date(NOW - (COUNT - 1 - i) * 60000);
+    return {
+        id: (0, snowflake_1.generateSnowflakeIdAtTime)(at),
+        data: { i },
+        attachments: [],
+        author_id: "author",
+        channel: { agent_id: AGENT, name: CHANNEL },
+    };
+}).sort((a, b) => (BigInt(a.id) < BigInt(b.id) ? -1 : 1));
+/**
+ * Emulates the REST route's *native* ordering, which the SDK client then
+ * reverses per `order`: `before` returns the newest N below the cursor,
+ * newest-first; a bare `after` returns the oldest N above it, oldest-first.
+ */
+function serveNative(query) {
+    const before = query.get("before");
+    const after = query.get("after");
+    const limit = Number(query.get("limit") ?? "10");
+    if (before && !after) {
+        const below = ALL.filter((m) => BigInt(m.id) < BigInt(before));
+        return below.slice(Math.max(0, below.length - limit)).reverse(); // newest-first
+    }
+    if (after && !before) {
+        const above = ALL.filter((m) => BigInt(m.id) > BigInt(after));
+        return above.slice(0, limit); // oldest-first
+    }
+    // both bounds: newest-first within (after, before]
+    const within = ALL.filter((m) => BigInt(m.id) < BigInt(before) && BigInt(m.id) > BigInt(after));
+    return within.slice(Math.max(0, within.length - limit)).reverse();
+}
+function makeClient() {
+    const calls = [];
+    const fetchMock = sinon_1.default.stub().callsFake(async (input) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+        if (url.includes("/messages")) {
+            const q = new URL(url).searchParams;
+            calls.push(q);
+            return (0, helpers_1.createJsonResponse)(serveNative(q));
+        }
+        return (0, helpers_1.createJsonResponse)({});
+    });
+    const client = new doover_client_1.DooverClient({
+        dataRestUrl: "https://api.example.com",
+        controlApiUrl: "https://control.example.com",
+        dataWssUrl: "wss://ws.example.com",
+        fetchImpl: fetchMock,
+        webSocketImpl: helpers_1.MockWebSocket,
+        disableBrowserLifecycleHooks: true,
+    });
+    return { client, calls };
+}
+function wrapper(client, queryClient) {
+    return function Wrapper({ children }) {
+        return ((0, jsx_runtime_1.jsx)(react_query_1.QueryClientProvider, { client: queryClient, children: (0, jsx_runtime_1.jsx)(react_2.DooverProvider, { client: client, children: children }) }));
+    };
+}
+const newQueryClient = () => new react_query_1.QueryClient({ defaultOptions: { queries: { retry: false } } });
+const idAtIndex = (i) => ALL[i].id;
+const timeOfIndex = (i) => NOW - (COUNT - 1 - i) * 60000;
+/** A snowflake landing strictly between messages i and i+1 (30s after i). */
+const anchorAfter = (i) => (0, snowflake_1.generateSnowflakeIdAtTime)(new Date(timeOfIndex(i) + 30000));
+(0, mocha_1.describe)("useChannelMessages forward pagination", () => {
+    (0, mocha_1.beforeEach)(() => {
+        (0, helpers_1.installSessionStorageMock)();
+        (0, messageRangeStore_1.resetChannelRangeStores)();
+    });
+    (0, mocha_1.afterEach)(() => {
+        sinon_1.default.restore();
+    });
+    (0, mocha_1.it)("pages forward from an anchor into newer messages", async () => {
+        const { client } = makeClient();
+        const qc = newQueryClient();
+        // Anchor between index 29 and 30 — half the history is newer than it.
+        const anchor = anchorAfter(29);
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 10, anchor }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages).to.have.length(10));
+        // The anchored page is the 10 newest *below* the anchor: indices 20..29.
+        (0, chai_1.expect)(result.current.messages.every((m) => BigInt(m.id) < BigInt(anchor))).to.equal(true);
+        (0, chai_1.expect)(result.current.hasPreviousPage).to.equal(true);
+        await (0, react_1.act)(async () => {
+            await result.current.fetchPreviousPage();
+        });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages.some((m) => BigInt(m.id) > BigInt(anchor))).to.equal(true));
+        // Forward page brought in the messages immediately above the anchor (index 30+).
+        (0, chai_1.expect)(result.current.messages.map((m) => m.data).some((d) => d.i >= 30)).to.equal(true);
+    });
+    (0, mocha_1.it)("exposes no previous page for an unanchored (live) window", async () => {
+        const { client } = makeClient();
+        const qc = newQueryClient();
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 10 }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages).to.have.length(10));
+        (0, chai_1.expect)(result.current.hasPreviousPage).to.equal(false);
+    });
+    (0, mocha_1.it)("recovers messages above an anchor that has nothing below it, and terminates", async () => {
+        const { client } = makeClient();
+        const qc = newQueryClient();
+        // Anchor older than every message: the initial before=anchor page is empty.
+        const anchor = (0, snowflake_1.generateSnowflakeIdAtTime)(new Date(NOW - COUNT * 10 * 60000));
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useChannelMessages)({ agentId: AGENT, channelName: CHANNEL }, { limit: 10, anchor }), { wrapper: wrapper(client, qc) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.isLoading).to.equal(false));
+        (0, chai_1.expect)(result.current.messages).to.have.length(0);
+        // Empty below, but the walk still seeds from the anchor itself.
+        (0, chai_1.expect)(result.current.hasPreviousPage).to.equal(true);
+        // Drain forward until exhausted — must terminate, never loop.
+        for (let guard = 0; guard < 20 && result.current.hasPreviousPage; guard++) {
+            await (0, react_1.act)(async () => {
+                await result.current.fetchPreviousPage();
+            });
+        }
+        (0, chai_1.expect)(result.current.hasPreviousPage).to.equal(false);
+        // Every message above the anchor is recovered (order is the consumer's job).
+        const ids = result.current.messages.map((m) => m.id);
+        (0, chai_1.expect)(ids).to.have.length(COUNT);
+        (0, chai_1.expect)(ids).to.include(idAtIndex(0));
+        (0, chai_1.expect)(ids).to.include(idAtIndex(COUNT - 1));
+    });
+});

package/dist/test/react-multiagent-messages.test.d.ts

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

package/dist/test/react-multiagent-messages.test.js

@@ -0,0 +1,113 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const chai_1 = require("chai");
+const mocha_1 = require("mocha");
+const react_1 = require("@testing-library/react");
+const react_query_1 = require("@tanstack/react-query");
+const doover_client_1 = require("../client/doover-client");
+const react_2 = require("../react");
+const helpers_1 = require("./helpers");
+const sinon_1 = __importDefault(require("sinon"));
+/**
+ * Fetch mock for the multi-agent messages endpoint. `pagesByRound` supplies
+ * one canned response per call, in order, so a test can hand back
+ * `next_cursors` on early rounds and drain on the last one.
+ */
+function makeClient(pagesByRound) {
+    let round = 0;
+    const calls = [];
+    const fetchMock = sinon_1.default.stub().callsFake(async (input) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+        if (url.includes("/messages")) {
+            const parsed = new URL(url);
+            calls.push({
+                agent_id: parsed.searchParams.getAll("agent_id"),
+                agent_before: parsed.searchParams.getAll("agent_before"),
+            });
+            const page = pagesByRound[Math.min(round, pagesByRound.length - 1)];
+            round += 1;
+            return (0, helpers_1.createJsonResponse)(page);
+        }
+        return (0, helpers_1.createJsonResponse)({});
+    });
+    const client = new doover_client_1.DooverClient({
+        dataRestUrl: "https://api.example.com",
+        controlApiUrl: "https://control.example.com",
+        dataWssUrl: "wss://ws.example.com",
+        fetchImpl: fetchMock,
+        webSocketImpl: helpers_1.MockWebSocket,
+        disableBrowserLifecycleHooks: true,
+    });
+    return { client, calls };
+}
+function wrapper(client) {
+    const queryClient = new react_query_1.QueryClient({ defaultOptions: { queries: { retry: false } } });
+    return function Wrapper({ children }) {
+        return ((0, jsx_runtime_1.jsx)(react_query_1.QueryClientProvider, { client: queryClient, children: (0, jsx_runtime_1.jsx)(react_2.DooverProvider, { client: client, children: children }) }));
+    };
+}
+function msg(id, agentId) {
+    return { id, channel: { agent_id: agentId, name: "tag_values" }, data: {} };
+}
+(0, mocha_1.describe)("useMultiAgentChannelMessages autoPaginate", () => {
+    (0, mocha_1.beforeEach)(() => {
+        (0, helpers_1.installSessionStorageMock)();
+        helpers_1.MockWebSocket.reset();
+    });
+    (0, mocha_1.afterEach)(() => {
+        sinon_1.default.restore();
+    });
+    (0, mocha_1.it)("walks back per-agent via next_cursors until the window drains", async () => {
+        const { client, calls } = makeClient([
+            // round 1: a1 hit its limit (cursor returned), a2 drained already
+            { results: [msg("100", "a1"), msg("99", "a2")], next_cursors: { a1: "90" } },
+            // round 2: a1 drains
+            { results: [msg("89", "a1")], next_cursors: {} },
+        ]);
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useMultiAgentChannelMessages)("tag_values", ["a1", "a2"], {
+            after: "1",
+            agentMessageLimit: 2,
+            autoPaginate: true,
+            liveUpdates: false,
+        }), { wrapper: wrapper(client) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages).to.have.length(3));
+        (0, chai_1.expect)(result.current.hasNextPage).to.equal(false);
+        // Second request must resume ONLY a1, using its own cursor as agent_before.
+        (0, chai_1.expect)(calls).to.have.length(2);
+        (0, chai_1.expect)(calls[1].agent_id).to.deep.equal(["a1"]);
+        (0, chai_1.expect)(calls[1].agent_before).to.deep.equal(["90"]);
+    });
+    (0, mocha_1.it)("does not paginate when autoPaginate is off", async () => {
+        const { client, calls } = makeClient([
+            { results: [msg("100", "a1")], next_cursors: { a1: "90" } },
+        ]);
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useMultiAgentChannelMessages)("tag_values", ["a1"], {
+            agentMessageLimit: 1,
+            liveUpdates: false,
+        }), { wrapper: wrapper(client) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages).to.have.length(1));
+        // hasNextPage is exposed, but nothing auto-fetches the second page.
+        (0, chai_1.expect)(result.current.hasNextPage).to.equal(true);
+        (0, chai_1.expect)(calls).to.have.length(1);
+    });
+    (0, mocha_1.it)("dedupes messages that repeat across pages", async () => {
+        const { client } = makeClient([
+            { results: [msg("100", "a1")], next_cursors: { a1: "100" } },
+            // overlaps the previous page's id 100 (legacy-style re-return)
+            { results: [msg("100", "a1"), msg("90", "a1")], next_cursors: {} },
+        ]);
+        const { result } = (0, react_1.renderHook)(() => (0, react_2.useMultiAgentChannelMessages)("tag_values", ["a1"], {
+            after: "1",
+            agentMessageLimit: 1,
+            autoPaginate: true,
+            liveUpdates: false,
+        }), { wrapper: wrapper(client) });
+        await (0, react_1.waitFor)(() => (0, chai_1.expect)(result.current.messages).to.have.length(2));
+        (0, chai_1.expect)(result.current.hasNextPage).to.equal(false);
+        (0, chai_1.expect)(result.current.messages.map((m) => m.id)).to.deep.equal(["100", "90"]);
+    });
+});

package/package.json

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