@leemour/max-cli 0.4.0 → 0.6.0

package/dist/client.js

@@ -1,11 +1,14 @@
 import { CliError } from "@leemour/cli-core";
-import { namesFrom, toChat, toContact, toMessage, toProfile } from "./domain/map.js";
-import { timeOfMessageId, } from "./domain/models.js";
+import { namesFrom, toChat, toContact, toMessage, toProfile, toReactions } from "./domain/map.js";
 import { wireClient } from "./generated/client.generated.js";
+import { parseMarkdown } from "./markdown.js";
 import { asFirstWord } from "./profile.js";
 import { Connection, ProtocolError } from "./protocol/connection.js";
+import { isId, pickChat, pickPerson } from "./resolve.js";
 import { countsIn, idsOf } from "./runs/events.js";
-import { startSession } from "./session/handshake.js";
+import { LOGIN_CHATS, startSession } from "./session/handshake.js";
+import { tokenByQr } from "./session/login.js";
+import { WEB_USER_AGENT } from "./spec/identity.js";
 import { buildRequest, checkResponse } from "./spec/index.js";
 /**
  * **The only thing above this line that knows MAX exists.** Commands speak the domain model; the
@@ -26,23 +29,33 @@ export class MaxClient {
     #cache;
     #offline;
     #events;
+    #sends;
     #invoke = ((operation, request) => this.#send(operation, request));
     #wire = wireClient(this.#invoke);
     #login;
     #previousCid = 0;
     #people;
     #merged;
-    constructor({ store, timeoutMs, connection, warn, cache, offline = false, events }) {
+    constructor({ store, timeoutMs, connection, warn, cache, offline = false, events, sends }) {
         this.#store = store;
         this.#connection = connection ?? new Connection(timeoutMs === undefined ? {} : { timeoutMs });
         this.#warn = warn ?? ((message) => process.stderr.write(`${message}\n`));
         this.#cache = cache;
         this.#offline = offline;
         this.#events = events ?? (() => { });
+        this.#sends = sends;
     }
     account = {
         me: () => toProfile(record(this.#session().profile) ?? {}),
     };
+    /**
+     * Obtaining a token rather than using one. The token comes back to the caller, unstored and not yet
+     * tried: `adoptToken` logs in with it on a connection of its own before the keyring sees it, so
+     * a login that went wrong halfway cannot replace a working session.
+     */
+    login = {
+        byQr: (options) => this.#beforeLogin(() => tokenByQr(this.#wire, options)),
+    };
     chats = {
         /**
          * Chats come with the login; a limit trims rather than fetching more.
@@ -53,7 +66,7 @@ export class MaxClient {
          * exactly the chats a person recognises by name.
          */
         list: async (options = {}) => {
-            const { limit, offset = 0, kind } = options;
+            const { limit, offset = 0, kind, unread } = options;
             const query = checkedQuery(options.query);
             if (this.#offline) {
                 const recorded = this.#cache;
@@ -62,8 +75,8 @@ export class MaxClient {
                 const store = recorded;
                 if (store.chats.count() === 0)
                     this.#recorded(undefined, "chats");
-                const items = store.chats.page({ limit: limit ?? Number.MAX_SAFE_INTEGER, offset, query, kind });
-                return { items, hasMore: offset + items.length < store.chats.count({ query, kind }) };
+                const items = store.chats.page({ limit: limit ?? Number.MAX_SAFE_INTEGER, offset, query, kind, unread });
+                return { items, hasMore: offset + items.length < store.chats.count({ query, kind, unread }) };
             }
             await this.#connectOnce();
             const raw = asArray(this.#session().chats);
@@ -81,13 +94,13 @@ export class MaxClient {
             });
             const cache = this.#cache;
             if (!cache)
-                return paged(matching(chats, query, kind), limit, offset);
+                return paged(matching(chats, { query, kind, unread }), limit, offset);
             // Written first, then read back: the titles just resolved have to be in the store before it
             // is asked to order and page over them, and the delta this login carried is only a slice of
             // what it now holds.
             cache.chats.write(chats);
-            const items = cache.chats.page({ limit: limit ?? Number.MAX_SAFE_INTEGER, offset, query, kind });
-            return { items, hasMore: offset + items.length < cache.chats.count({ query, kind }) };
+            const items = cache.chats.page({ limit: limit ?? Number.MAX_SAFE_INTEGER, offset, query, kind, unread });
+            return { items, hasMore: offset + items.length < cache.chats.count({ query, kind, unread }) };
         },
         /**
          * Turns what the person typed into a chat id.
@@ -97,21 +110,23 @@ export class MaxClient {
          * conversation is not undoable, so the caller is shown the candidates and asked to be specific.
          */
         resolve: async (reference) => {
-            if (/^-?\d+$/.test(reference.trim()))
+            if (isId(reference))
                 return reference.trim();
-            const { items: chats } = await this.chats.list();
-            const wanted = reference.trim().toLowerCase();
-            const titled = chats.filter((chat) => chat.title !== null);
-            const exact = titled.filter((chat) => chat.title?.toLowerCase() === wanted);
-            const matches = exact.length > 0 ? exact : titled.filter((chat) => chat.title?.toLowerCase().includes(wanted));
-            if (matches.length === 1 && matches[0])
-                return matches[0].id;
-            if (matches.length === 0)
-                throw new CliError("not_found", `no chat matches "${reference}"`);
-            const candidates = matches.map((chat) => ({ id: chat.id, title: chat.title }));
-            const width = Math.max(...candidates.map(({ id }) => id.length));
-            const lines = candidates.map(({ id, title }) => `  ${id.padEnd(width)}  ${title}`).join("\n");
-            throw new CliError("validation_error", `"${reference}" matches ${matches.length} chats — name one by its id:\n${lines}`, { candidates });
+            return pickChat(reference, (await this.chats.list()).items).id;
+        },
+        /**
+         * One chat and who is in it, from the list the login just refreshed.
+         *
+         * ⚠ **An id is checked here, where `resolve` lets any number through** — for a read that is
+         * the difference between an answer and a card of nulls for a chat that does not exist.
+         */
+        show: async (reference) => {
+            const { items } = await this.chats.list();
+            const chat = isId(reference) ? items.find((one) => one.id === reference.trim()) : pickChat(reference, items);
+            if (!chat)
+                throw new CliError("not_found", `no chat ${reference.trim()} among this account's chats`);
+            const cache = this.#cache;
+            return { ...chat, members: chat.kind === "channel" || !cache ? null : cache.chats.members(chat.id) };
         },
     };
     contacts = {
@@ -157,6 +172,31 @@ export class MaxClient {
          * It is also the only thing that could ever prune somebody MAX has stopped returning, which is
          * the second reason it exists.
          */
+        /**
+         * One person and the chats we share, **whoever they are** — a group member is as findable as
+         * a contact. `NEED-105` decides who `list` lists, not who can be looked up.
+         *
+         * Only from the store: the shared chats are its `chat_members`, which nothing else holds.
+         */
+        show: async (reference) => {
+            const cache = this.#cache;
+            if (!cache) {
+                throw new CliError("configuration_error", `there is no local store for profile "${this.#store.profile}" to look people up in — the note above says why`);
+            }
+            if (this.#offline) {
+                if (cache.people.count() === 0)
+                    this.#recorded(undefined, "people");
+            }
+            else {
+                await this.#connectOnce();
+                await this.#peopleFor(asArray(this.#session().chats));
+            }
+            const person = pickPerson(reference, cache);
+            const chats = cache.people
+                .sharedChats(person.id)
+                .map(({ id, title, kind, lastMessageAt }) => ({ id, title, kind, lastMessageAt }));
+            return { ...person, chats };
+        },
         sync: async () => {
             if (this.#offline) {
                 throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot sync");
@@ -208,16 +248,33 @@ export class MaxClient {
          * it takes a moment and answers with what came before it — so `--before` is exact where a page
          * number over a live conversation would repeat and skip rows.
          *
+         * `after` reads the other way and **leaves the anchor out**, so the next page's hint does not
+         * repeat a row. MAX puts it in — measured 2026-09-23, `forward: n` with `backward: 0` starts
+         * with the message it was given — so one more is asked for and anything not later is dropped.
+         * `before` keeps the anchor, as it always has.
+         *
          * `hasMore` here is a claim about the copy we hold, never about the chat: a full page back is
          * the only evidence there is that another page exists.
          */
         list: async (chatId, options = {}) => {
             const limit = options.limit ?? 20;
+            const { before, after } = options;
+            if (after !== undefined) {
+                const found = this.#offline
+                    ? this.#recorded(this.#cache?.messages.window(chatId, after, 0, limit + 1), "messages")
+                    : await this.#history(chatId, { from: after, backward: 0, forward: limit + 1 });
+                const later = found.filter((message) => Date.parse(message.timestamp) > after);
+                return { items: later.slice(0, limit), hasMore: later.length > limit };
+            }
             if (this.#offline) {
-                const stored = this.#recorded(this.#cache?.messages.read(chatId, limit, ANY_AGE), "messages");
-                return { items: stored, hasMore: stored.length >= limit };
+                const cache = this.#cache;
+                const stored = before === undefined
+                    ? cache?.messages.read(chatId, limit, ANY_AGE)
+                    : cache?.messages.window(chatId, before, limit, 0);
+                const items = this.#recorded(stored, "messages");
+                return { items, hasMore: items.length >= limit };
             }
-            const messages = await this.#history(chatId, { from: options.before ?? Date.now(), backward: limit, forward: 0 });
+            const messages = await this.#history(chatId, { from: before ?? Date.now(), backward: limit, forward: 0 });
             return { items: messages, hasMore: messages.length >= limit };
         },
         /**
@@ -226,34 +283,77 @@ export class MaxClient {
          *
          * Measured 2026-09-22: from a message's own time, `backward: n` answers n messages ending with
          * it and `forward: n` the n after it. Its time comes from its id, so no stored copy is needed.
+         * Correction 2026-09-23: that holds with `backward` above zero; with `backward: 0`, `forward`
+         * starts with the message itself (`messages.list` with `after` depends on the difference).
          *
          * ⚠ **A message that is gone is refused, not replaced by its neighbour** — MAX answers with
          * whatever is nearest, and showing that as the message asked for would be a quiet lie.
          */
-        around: async (chatId, messageId, { before = 0, after = 0 } = {}) => {
+        around: async (chatId, messageId, { before = 0, after = 0, reactions = true } = {}) => {
             const time = timeOfMessageId(messageId);
             if (time === undefined)
                 throw new CliError("validation_error", `"${messageId}" is not a message id`);
             const found = this.#offline
                 ? (this.#cache?.messages.window(chatId, time, before + 1, after) ?? [])
-                : await this.#history(chatId, { from: time, backward: before + 1, forward: after });
+                : await this.#history(chatId, { from: time, backward: before + 1, forward: after }, { reactions });
             if (!found.some((message) => message.id === messageId)) {
                 throw new CliError("not_found", `no message ${messageId} in chat ${chatId} — deleted, or in another chat`);
             }
             return found.map((message) => (message.id === messageId ? { ...message, anchor: true } : message));
         },
         /**
-         * Turns what `--before` was given into a moment.
+         * **Where each attachment of one message can be downloaded from.** A photo and an audio carry
+         * their link; a file and a video carry only an id, and MAX answers the link for it (measured
+         * 2026-09-23). A video is taken as its largest MP4 — the streaming renditions are playlists,
+         * not a file. An attachment with no link to give is left out and named in `skipped`.
+         */
+        links: async (chatId, messageId) => {
+            if (this.#offline)
+                throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot download");
+            const [message] = await this.messages.around(chatId, messageId, { reactions: false });
+            if (!message)
+                throw new CliError("not_found", `no message ${messageId} in chat ${chatId}`);
+            const links = [];
+            const skipped = [];
+            for (const attachment of message.attachments) {
+                const { kind, name } = attachment;
+                if (attachment.fileId) {
+                    const answer = await this.#wire.attachments.file({ chatId, messageId, fileId: attachment.fileId });
+                    const url = typeof answer.url === "string" ? answer.url : undefined;
+                    if (url)
+                        links.push({ kind, url, ...(name ? { name } : {}), ...(answer.unsafe === true ? { unsafe: true } : {}) });
+                    else
+                        skipped.push(kind);
+                }
+                else if (attachment.videoId) {
+                    const answer = await this.#wire.attachments.video({ chatId, messageId, videoId: attachment.videoId });
+                    const url = largestMp4(answer);
+                    if (url)
+                        links.push({ kind, url });
+                    else
+                        skipped.push(kind);
+                }
+                else if (attachment.url && (kind === "photo" || kind === "audio")) {
+                    links.push({ kind, url: attachment.url });
+                }
+                else {
+                    skipped.push(kind);
+                }
+            }
+            return { links, skipped };
+        },
+        /**
+         * Turns what `--before` or `--after` was given into a moment.
          *
          * **ISO 8601 is a time; a bare integer is a message id**, and a message id carries its own time
          * (`timeOfMessageId`). Deciding between the two by length would be a trap that fires the first
          * time either changes size, so the rule is what the string looks like.
          */
-        before: (reference) => {
+        moment: (reference, flag = "--before") => {
             const wanted = reference.trim();
             const time = /^\d+$/.test(wanted) ? timeOfMessageId(wanted) : Date.parse(wanted);
             if (time === undefined || Number.isNaN(time)) {
-                throw new CliError("validation_error", `--before takes a message id or an ISO 8601 time, not "${wanted}"`);
+                throw new CliError("validation_error", `${flag} takes a message id or an ISO 8601 time, not "${wanted}"`);
             }
             return time;
         },
@@ -273,38 +373,170 @@ export class MaxClient {
         send: async (chatId, text, options = {}) => {
             if (this.#offline)
                 throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot send");
-            await this.#connectOnce();
-            const session = this.#session();
+            // Before connecting: a refused send never opens a socket when the chat was given as an id.
+            try {
+                this.#sends?.check(chatId);
+            }
+            catch (error) {
+                this.#sends?.record({ chatId, outcome: "refused", errorCode: asCliError(error).code });
+                throw error;
+            }
             const cid = options.cid ?? this.#nextCid();
-            const request = {
-                chatId,
-                message: { text, cid, elements: [], attaches: [] },
-                notify: options.notify ?? true,
-            };
-            let answer;
             try {
-                answer = await this.#wire.messages.send(request);
+                const sent = await this.#deliver(chatId, text, cid, options);
+                this.#sends?.record({ chatId, outcome: "sent", messageId: sent.id, cid, length: text.length });
+                return sent;
             }
             catch (error) {
                 const failure = asCliError(error);
-                if (failure.code !== "timeout" && failure.code !== "network_error")
-                    throw failure;
-                // No answer came back, so MAX may already have delivered it. Repeating the identical `cid`
-                // is what makes asking again safe rather than reckless.
-                try {
-                    answer = await this.#wire.messages.send(request);
-                }
-                catch {
-                    throw new CliError("outcome_unknown", `the message may or may not have been sent (${failure.message}) — ` +
-                        `\`max messages send <chat> <text> --cid ${cid}\` repeats the attempt without risking a second copy`, { cid });
-                }
+                this.#sends?.record({
+                    chatId,
+                    outcome: failure.code === "outcome_unknown" ? "outcome_unknown" : "failed",
+                    cid,
+                    length: text.length,
+                    errorCode: failure.code,
+                });
+                throw error;
             }
-            // What the cache holds for this chat is now one message short of the truth.
-            this.#cache?.messages.invalidate(chatId);
-            const sent = record(answer.message) ?? answer;
-            return toMessage(sent, chatId, { names: namesFrom(session.contacts), ...viewer(this.#store) });
+        },
+        /**
+         * Puts one emoji reaction on a message. Not retried: a reaction lost in transit costs a second
+         * command, and nothing about it is measured to make a blind repeat safe.
+         */
+        react: async (chatId, messageId, emoji) => {
+            if (this.#offline)
+                throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot react");
+            try {
+                this.#sends?.check(chatId, "reaction");
+            }
+            catch (error) {
+                this.#sends?.record({ chatId, kind: "reaction", outcome: "refused", errorCode: asCliError(error).code });
+                throw error;
+            }
+            try {
+                await this.#connectOnce();
+                const answer = await this.#wire.messages.react({
+                    chatId,
+                    messageId,
+                    reaction: { reactionType: "EMOJI", id: emoji },
+                });
+                this.#sends?.record({ chatId, kind: "reaction", outcome: "sent", messageId });
+                return toReactions(record(answer.reactionInfo) ?? {});
+            }
+            catch (error) {
+                this.#sends?.record({
+                    chatId,
+                    kind: "reaction",
+                    outcome: "failed",
+                    messageId,
+                    errorCode: asCliError(error).code,
+                });
+                throw error;
+            }
+        },
+    };
+    inbox = {
+        /**
+         * Other people's unread messages, as MAX counts them: for each chat with a count, its newest
+         * that many. Reading changes nothing — no `CHAT_MARK` — so the same messages come back until
+         * they are read somewhere else. That is right for a person and wrong for a scheduled run,
+         * which is what `since` is for.
+         */
+        unread: async ({ limit }) => {
+            const chats = (await this.chats.list()).items;
+            const waiting = byRecency(chats.filter((chat) => (chat.unreadCount ?? 0) > 0));
+            const { read, skipped } = capped(waiting);
+            const found = [];
+            for (const { id, title, kind, unreadCount } of read) {
+                const count = unreadCount ?? 0;
+                const wanted = Math.min(count, limit);
+                const { items } = await this.messages.list(id, { limit: wanted });
+                const theirs = items.slice(-wanted).filter((message) => message.outgoing !== true);
+                if (theirs.length > 0)
+                    found.push({ id, title, kind, unreadCount, messages: theirs, more: count > limit });
+            }
+            return { mode: "unread", chats: found, skipped, partial: !this.#cache && chats.length >= LOGIN_CHATS };
+        },
+        /**
+         * Other people's messages in every chat that changed after `since`.
+         *
+         * A chat changed if its last message is later than `since`; the chat list says so without a
+         * request, and with a store it covers every chat, not only the ones this login named. Each
+         * changed chat then costs one history read of its newest `limit` — the newest, because the
+         * reader wants what just arrived, and one request rather than paging forward to reach it.
+         *
+         * **Everything is cut at the chat list's newest message**, the snapshot this login took. The
+         * reads run one after another, so a chat read early can gain a message while a later one is
+         * read; had the saved point followed the later read, that message would sit behind it and
+         * never show. Anything newer than the snapshot waits for the next run and shows once there.
+         */
+        since: async ({ since, limit }) => {
+            const chats = (await this.chats.list()).items;
+            const changed = byRecency(chats.filter((chat) => chat.lastMessageAt !== null && Date.parse(chat.lastMessageAt) > since));
+            const cut = Math.max(since, ...changed.map((chat) => Date.parse(chat.lastMessageAt ?? "")));
+            const { read, skipped } = capped(changed);
+            let until = since;
+            const found = [];
+            for (const { id, title, kind, unreadCount } of read) {
+                const { items } = await this.messages.list(id, { limit });
+                const fresh = items.filter((message) => {
+                    const time = Date.parse(message.timestamp);
+                    return time > since && time <= cut;
+                });
+                for (const message of fresh)
+                    until = Math.max(until, Date.parse(message.timestamp));
+                const theirs = fresh.filter((message) => message.outgoing !== true);
+                if (theirs.length > 0)
+                    found.push({ id, title, kind, unreadCount, messages: theirs, more: fresh.length >= limit });
+            }
+            return {
+                mode: "new",
+                since: new Date(since).toISOString(),
+                until: new Date(until).toISOString(),
+                chats: found,
+                skipped,
+                partial: !this.#cache && chats.length >= LOGIN_CHATS && changed.length === chats.length,
+            };
         },
     };
+    async #deliver(chatId, text, cid, options) {
+        await this.#connectOnce();
+        const session = this.#session();
+        const { text: plain, markup } = options.markdown ? parseMarkdown(text) : { text, markup: [] };
+        const request = {
+            chatId,
+            message: {
+                text: plain,
+                cid,
+                elements: markup,
+                attaches: [],
+                ...(options.replyTo ? { link: { type: "REPLY", messageId: options.replyTo } } : {}),
+            },
+            notify: options.notify ?? true,
+        };
+        let answer;
+        try {
+            answer = await this.#wire.messages.send(request);
+        }
+        catch (error) {
+            const failure = asCliError(error);
+            if (failure.code !== "timeout" && failure.code !== "network_error")
+                throw failure;
+            // No answer came back, so MAX may already have delivered it. Repeating the identical `cid`
+            // is what makes asking again safe rather than reckless.
+            try {
+                answer = await this.#wire.messages.send(request);
+            }
+            catch {
+                throw new CliError("outcome_unknown", `the message may or may not have been sent (${failure.message}) — ` +
+                    `\`max messages send <chat> <text> --cid ${cid}\` repeats the attempt without risking a second copy`, { cid });
+            }
+        }
+        // What the cache holds for this chat is now one message short of the truth.
+        this.#cache?.messages.invalidate(chatId);
+        const sent = record(answer.message) ?? answer;
+        return toMessage(sent, chatId, { names: namesFrom(session.contacts), ...viewer(this.#store) });
+    }
     /**
      * Opens the connection and logs in with the stored token, or with one offered for trial.
      *
@@ -464,7 +696,7 @@ export class MaxClient {
      * public for the one command that must reach MAX to mean anything — starting a session.
      */
     /** `interactive: false` and never `CHAT_MARK`: reading history must not mark anything read (§19). */
-    async #history(chatId, window) {
+    async #history(chatId, window, { reactions = true } = {}) {
         await this.#connectOnce();
         const session = this.#session();
         const answer = await this.#wire.chats.history({
@@ -480,7 +712,24 @@ export class MaxClient {
         const lookup = { names: namesFrom(session.contacts), ...viewer(this.#store) };
         const messages = await this.#nameSenders(asArray(answer.messages).map((raw) => toMessage(raw, chatId, lookup)));
         this.#cache?.messages.write(chatId, messages);
-        return messages;
+        return reactions ? this.#withReactions(chatId, messages) : messages;
+    }
+    /** One request per page: history carries no reactions (measured 2026-09-23). */
+    async #withReactions(chatId, messages) {
+        if (messages.length === 0)
+            return messages;
+        try {
+            const answer = await this.#wire.messages.reactions({ chatId, messageIds: messages.map((message) => message.id) });
+            const byId = record(answer.messagesReactions) ?? {};
+            return messages.map((message) => {
+                const raw = record(byId[message.id]);
+                return { ...message, reactions: raw ? toReactions(raw) : { counts: [], mine: null, total: 0 } };
+            });
+        }
+        catch (error) {
+            this.#warn(`reactions are not shown: they could not be read (${reasonOf(error)})`);
+            return messages;
+        }
     }
     /**
      * **A group member who is not a contact arrives as a bare id** — the login names contacts only,
@@ -523,6 +772,17 @@ export class MaxClient {
             forwardedFrom: message.forwardedFrom && name(message.forwardedFrom),
         }));
     }
+    /** INIT with the profile's own device, which is the device MAX then issues the token to (bite 8). */
+    async #beforeLogin(flow) {
+        try {
+            await this.#connection.open();
+        }
+        catch (error) {
+            throw asCliError(error);
+        }
+        await this.#wire.session.init({ userAgent: WEB_USER_AGENT, deviceId: this.#store.readState().deviceId });
+        return await flow();
+    }
     async #connectOnce() {
         if (!this.#login)
             await this.connect();
@@ -669,6 +929,10 @@ export class MaxClient {
         return this.#login;
     }
 }
+const largestMp4 = (answer) => Object.entries(answer)
+    .map(([key, value]) => ({ height: /^MP4_(\d+)$/.exec(key)?.[1], value }))
+    .filter((entry) => entry.height !== undefined && typeof entry.value === "string")
+    .sort((a, b) => Number(b.height) - Number(a.height))[0]?.value;
 /**
  * **The shortest search the index can answer is three characters**, and below that it returns
  * nothing rather than complaining (measured 2026-09-22). An empty list reads as "no matches",
@@ -695,6 +959,29 @@ const checkedQuery = (query) => {
  * names itself rather than as a wrong answer.
  */
 const CONTACT_INFO_BATCH = 100;
+/**
+ * When a message was sent, read from its id: **`id >> 16` is the send time in milliseconds**, the
+ * low 16 bits a counter. Measured 2026-09-22 on three messages across two days, exact every time.
+ * `undefined` for anything that is not a message id.
+ */
+export const timeOfMessageId = (id) => {
+    if (!/^\d{10,20}$/.test(id))
+        return undefined;
+    const time = Number(BigInt(id) >> 16n);
+    return Number.isSafeInteger(time) && time > 0 ? time : undefined;
+};
+/**
+ * **At most this many history reads per `max inbox`.** The official client reads a chat's history
+ * when a person opens it; twenty in one burst is already more than a person does (§34). A personal
+ * account rarely has that many chats change between two checks, and the rest are named, not lost.
+ */
+const INBOX_CHATS = 20;
+/** Newest first — the chats a reader most likely came for are read before the cap. */
+const byRecency = (chats) => chats.toSorted((a, b) => Date.parse(b.lastMessageAt ?? "") - Date.parse(a.lastMessageAt ?? ""));
+const capped = (chats) => ({
+    read: chats.slice(0, INBOX_CHATS),
+    skipped: chats.slice(INBOX_CHATS).map(({ id, title, lastMessageAt }) => ({ id, title, lastMessageAt })),
+});
 const isPresent = (value) => value !== null && value !== undefined;
 const needsName = (message) => message.senderId !== null && message.senderName === null && message.outgoing !== true;
 const batched = (items, size) => {
@@ -717,9 +1004,10 @@ const batched = (items, size) => {
  * The alternative was to let a filter only work when a cache happened to exist, which makes the
  * answer depend on something the person never asked about.
  */
-const matching = (chats, query, kind) => {
+const matching = (chats, { query, kind, unread }) => {
     const needle = query?.toLocaleLowerCase();
     return chats.filter((chat) => (kind === undefined || chat.kind === kind) &&
+        (!unread || (chat.unreadCount ?? 0) > 0) &&
         (needle === undefined || (chat.title ?? "").toLocaleLowerCase().includes(needle)));
 };
 /** As `matching`, over the two columns `people_fts` indexes. */