@leemour/max-cli 0.15.0 → 0.17.0

package/dist/client.js

@@ -1,5 +1,6 @@
 import { CliError } from "@leemour/cli-core";
-import { namesFrom, SETTING_FLAGS, toChat, toContact, toFolder, toGroupCard, toGroupMember, toMessage, toProfile, toReactions, toSession, } from "./domain/map.js";
+import { delayMs } from "./config.js";
+import { namesFrom, POLL_CLOSED, pollSettings, SETTING_FLAGS, toChat, toContact, toFolder, toGroupCard, toGroupMember, toMessage, toPoll, toProfile, toReactions, toSession, } from "./domain/map.js";
 import { heldWindows } from "./export.js";
 import { wireClient } from "./generated/client.generated.js";
 import { parseMarkdown } from "./markdown.js";
@@ -71,10 +72,12 @@ export class MaxClient {
             if (!firstName)
                 throw new CliError("validation_error", "MAX needs a first name, and the profile has none — pass --first-name");
             const lastName = change.lastName ?? current.lastName;
+            const photoToken = change.photo === undefined ? undefined : await this.#profilePhoto(change.photo);
             const answer = await this.#wire.account.update({
                 firstName,
                 ...(lastName === undefined ? {} : { lastName }),
                 ...(change.description === undefined ? {} : { description: change.description }),
+                ...(photoToken === undefined ? {} : { photoToken, avatarType: "USER_AVATAR" }),
             });
             return toProfile(record(answer.profile) ?? {});
         }),
@@ -272,12 +275,13 @@ export class MaxClient {
                 throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot read a link");
             const wire = wireLink(link);
             await this.#connectOnce();
-            return toGroupCard(record((await this.#wire.chats.linkInfo({ link: wire })).chat) ?? {});
+            const answer = await this.#wire.chats.linkInfo({ link: wire }).catch(deadLink(link));
+            return toGroupCard(record(answer.chat) ?? {});
         },
         join: (link) => {
             const wire = wireLink(link);
             return this.#changeChat(null, "join", async () => {
-                const chat = toGroupCard(record((await this.#wire.chats.join({ link: wire })).chat) ?? {});
+                const chat = toGroupCard(record((await this.#wire.chats.join({ link: wire }).catch(deadLink(link))).chat) ?? {});
                 return { chatId: chat.id, result: chat };
             });
         },
@@ -320,13 +324,13 @@ export class MaxClient {
          * Not retried, unlike a message: a second attempt with a new `cid` is a second group, and
          * whether MAX deduplicates a creation by `cid` is not measured.
          */
-        create: async (title, people = []) => {
+        create: async (title, people = [], { channel = false } = {}) => {
             const userIds = await this.#personIds(people);
             return this.#changeChat(null, "create", async () => {
                 const answer = await this.#wire.messages.send({
                     message: {
                         cid: this.#nextCid(),
-                        attaches: [{ _type: "CONTROL", event: "new", chatType: "CHAT", title, userIds }],
+                        attaches: [{ _type: "CONTROL", event: "new", chatType: channel ? "CHANNEL" : "CHAT", title, userIds }],
                     },
                     notify: true,
                 });
@@ -384,23 +388,6 @@ export class MaxClient {
             }),
             remove: (reference, person) => this.#updateMembers(reference, [person], "admins.remove", { operation: "remove", type: "ADMIN" }),
         },
-        requests: {
-            /** Each with the age of their account, read like a member's — the answer's `{contact}` is the same shape. */
-            list: async (reference) => {
-                if (this.#offline)
-                    throw new CliError("validation_error", "`--offline` reads what was recorded; join requests never are");
-                const chatId = await this.chats.resolve(reference);
-                await this.#connectOnce();
-                const answer = await this.#wire.chats.members({ chatId, type: "JOIN_REQUEST", count: JOIN_REQUESTS });
-                return asArray(answer.members).map(toGroupMember);
-            },
-            accept: (reference, people) => this.#updateMembers(reference, people, "requests.accept", {
-                operation: "add",
-                type: "JOIN_REQUEST",
-                showHistory: true,
-            }),
-            decline: (reference, people) => this.#updateMembers(reference, people, "requests.decline", { operation: "remove", type: "JOIN_REQUEST" }),
-        },
         update: async (reference, { title, description }) => {
             if (title === undefined && description === undefined) {
                 throw new CliError("validation_error", "nothing to change — give --title, --description or both");
@@ -501,8 +488,13 @@ export class MaxClient {
                 throw new CliError("not_found", "MAX has nobody under that number");
             return this.#remember(toContact(contact));
         },
-        add: (reference) => this.#contactAction("contact-add", "ADD", reference),
-        remove: (reference) => this.#contactAction("contact-remove", "REMOVE", reference),
+        add: (reference) => this.#contactAction("contact-add", { action: "ADD" }, reference),
+        remove: (reference) => this.#contactAction("contact-remove", { action: "REMOVE" }, reference),
+        /** They can no longer write to you. Works for somebody who is not a contact too (measured). */
+        block: (reference) => this.#contactAction("contact-block", { action: "BLOCK" }, reference),
+        unblock: (reference) => this.#contactAction("contact-unblock", { action: "UNBLOCK" }, reference),
+        /** A name of your own for them, kept beside the one they chose; they do not see it. */
+        rename: (reference, firstName, lastName) => this.#contactAction("contact-rename", { action: "UPDATE", firstName, ...(lastName === undefined ? {} : { lastName }) }, reference),
         /** Uploads phone numbers to MAX — other people's — under the names they were saved with. */
         import: (entries) => this.#change("contact-import", async () => {
             if (entries.length === 0)
@@ -769,9 +761,14 @@ export class MaxClient {
          */
         moment: (reference, flag = "--before") => {
             const wanted = reference.trim();
-            const time = /^\d+$/.test(wanted) ? timeOfMessageId(wanted) : Date.parse(wanted);
+            const ago = delayMs(wanted);
+            const time = /^\d+$/.test(wanted)
+                ? timeOfMessageId(wanted)
+                : ago === undefined
+                    ? Date.parse(wanted)
+                    : Date.now() - ago;
             if (time === undefined || Number.isNaN(time)) {
-                throw new CliError("validation_error", `${flag} takes a message id or an ISO 8601 time, not "${wanted}"`);
+                throw new CliError("validation_error", `${flag} takes a message id, an ISO 8601 time or 30m, 2h, 1d ago — not "${wanted}"`);
             }
             return time;
         },
@@ -1002,6 +999,160 @@ export class MaxClient {
             }
         },
     };
+    /**
+     * **Polls: vote, take a vote back, close one's own, create one.** Every one of them is a write
+     * somebody else can see, so it passes the send guard and the journal under the kind of what it is:
+     * a vote is a `reaction`, closing is an `edit` of the owner's message, a new poll is a `message`.
+     * A vote is never retried — nothing measured makes a blind repeat safe.
+     *
+     * The shapes were measured in Saved messages on 2026-09-27 (`pnpm probe:polls`, `FIND-247`). The
+     * checks before sending are the web client's, so what it would refuse never reaches MAX.
+     */
+    polls = {
+        vote: async (chatId, messageId, answerIds) => {
+            if (this.#offline)
+                throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot vote");
+            this.#guard({ chatId, kind: "reaction" }, messageId);
+            try {
+                await this.#connectOnce();
+                const { attach, poll } = await this.#poll(chatId, messageId);
+                const voted = poll.answers.some((answer) => answer.mine);
+                if (answerIds.length === 0 && !voted) {
+                    throw new CliError("validation_error", `you have not voted in the poll of message ${messageId}`);
+                }
+                if (answerIds.length === 0 && !poll.revote) {
+                    throw new CliError("validation_error", `the poll of message ${messageId} does not let a vote be taken back`);
+                }
+                if (answerIds.length > 0 && voted && !poll.revote) {
+                    throw new CliError("validation_error", `you have voted in the poll of message ${messageId}, and it does not let a vote change`);
+                }
+                if (answerIds.length > 1 && !poll.multiple) {
+                    throw new CliError("validation_error", `the poll of message ${messageId} takes one answer, not ${answerIds.length}`);
+                }
+                const unknown = answerIds.find((id) => !poll.answers.some((answer) => answer.id === id));
+                if (unknown !== undefined) {
+                    throw new CliError("validation_error", `the poll of message ${messageId} has no answer ${unknown} — its answers are ${poll.answers.map((answer) => answer.id).join(", ")}`);
+                }
+                const answer = await this.#wire.messages.pollVote({
+                    chatId,
+                    messageId,
+                    pollId: poll.id,
+                    answersIds: answerIds.map(Number),
+                });
+                this.#cache?.messages.invalidate(chatId);
+                this.#sends?.record({ chatId, kind: "reaction", outcome: "sent", messageId });
+                const state = record(answer.state);
+                return { chatId, messageId, poll: (state && toPoll({ ...attach, state })) ?? poll };
+            }
+            catch (error) {
+                this.#sends?.record({
+                    chatId,
+                    kind: "reaction",
+                    outcome: "failed",
+                    messageId,
+                    errorCode: asCliError(error).code,
+                });
+                throw error;
+            }
+        },
+        /** Closes the owner's own poll: the web client edits the message with the `closed` bit raised. */
+        close: async (chatId, messageId) => {
+            if (this.#offline)
+                throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot close a poll");
+            this.#guard({ chatId, kind: "edit" }, messageId);
+            try {
+                await this.#connectOnce();
+                const { attach, poll, outgoing } = await this.#poll(chatId, messageId);
+                if (!outgoing)
+                    throw new CliError("validation_error", `the poll of message ${messageId} is not yours to close`);
+                // What the web client sends back: the answers' text only, no ids and no votes.
+                const closed = {
+                    _type: "POLL",
+                    pollId: attach.pollId,
+                    title: attach.title,
+                    answers: asArray(attach.answers).map((each) => ({ text: each.text })),
+                    settings: (typeof attach.settings === "number" ? attach.settings : 0) | POLL_CLOSED,
+                };
+                const answer = await this.#wire.messages.edit({ chatId, messageId, attachments: [closed] });
+                this.#cache?.messages.invalidate(chatId);
+                this.#sends?.record({ chatId, kind: "edit", outcome: "sent", messageId });
+                const after = asArray(record(answer.message)?.attaches).find((each) => each._type === "POLL");
+                return { chatId, messageId, poll: (after && toPoll(after)) ?? { ...poll, closed: true } };
+            }
+            catch (error) {
+                this.#sends?.record({ chatId, kind: "edit", outcome: "failed", messageId, errorCode: asCliError(error).code });
+                throw error;
+            }
+        },
+        /**
+         * A new message whose one attachment is the poll — so it goes through `#deliver`, with its `cid`
+         * and its one retry, like any message.
+         */
+        create: async (chatId, question, answers, options = {}) => {
+            if (this.#offline)
+                throw new CliError("validation_error", "`--offline` reads what was recorded; it cannot create a poll");
+            if (question.trim() === "")
+                throw new CliError("validation_error", "a poll needs a question");
+            if (answers.length < 2 || answers.some((answer) => answer.trim() === "")) {
+                throw new CliError("validation_error", "a poll needs at least two answers, none of them empty");
+            }
+            try {
+                this.#sends?.check({ chatId, kind: "message", ...(options.cid === undefined ? {} : { cid: options.cid }) });
+            }
+            catch (error) {
+                this.#sends?.record({ chatId, kind: "message", outcome: "refused", errorCode: asCliError(error).code });
+                throw error;
+            }
+            const cid = options.cid ?? this.#nextCid();
+            const attach = {
+                _type: "POLL",
+                title: question,
+                answers: answers.map((text) => ({ text })),
+                settings: pollSettings(options),
+            };
+            try {
+                const sent = await this.#deliver(chatId, "", cid, {
+                    ...options,
+                    attaches: [attach],
+                    repeat: `max polls create ${chatId} …`,
+                });
+                this.#sends?.record({
+                    chatId,
+                    kind: "message",
+                    outcome: "sent",
+                    messageId: sent.id,
+                    cid,
+                    length: question.length,
+                });
+                return sent;
+            }
+            catch (error) {
+                const failure = asCliError(error);
+                this.#sends?.record({
+                    chatId,
+                    kind: "message",
+                    outcome: failure.code === "outcome_unknown" ? "outcome_unknown" : "failed",
+                    cid,
+                    errorCode: failure.code,
+                });
+                throw error;
+            }
+        },
+    };
+    /** The poll of one message, whole as MAX sends it and read, or a refusal that says why there is none. */
+    async #poll(chatId, messageId) {
+        const raw = await this.#rawMessage(chatId, messageId);
+        const attach = asArray(raw.attaches).find((each) => each._type === "POLL");
+        if (!attach)
+            throw new CliError("validation_error", `message ${messageId} carries no poll`);
+        const poll = toPoll(attach);
+        if (!poll)
+            throw new CliError("validation_error", `the poll of message ${messageId} is a newer kind this version cannot read`);
+        if (poll.closed)
+            throw new CliError("validation_error", `the poll of message ${messageId} is closed`);
+        const lookup = { names: namesFrom(this.#session().contacts), ...viewer(this.#store) };
+        return { attach, poll, outgoing: toMessage(raw, chatId, lookup).outgoing === true };
+    }
     folders = {
         list: async () => (await this.#folders()).map(toFolder),
         create: (title, chats = []) => this.#change("folder-create", async () => {
@@ -1218,7 +1369,7 @@ export class MaxClient {
     async #deliver(chatId, text, cid, options) {
         await this.#connectOnce();
         const session = this.#session();
-        const attaches = [];
+        const attaches = [...(options.attaches ?? [])];
         for (const file of options.files ?? [])
             attaches.push(await this.#upload(file));
         const { text: plain, markup } = options.markdown ? parseMarkdown(text) : { text, markup: [] };
@@ -1453,6 +1604,10 @@ export class MaxClient {
                     `the keyring is probably out of reach (cron, ssh: set XDG_RUNTIME_DIR); ` +
                     `\`max ${asFirstWord(profile)}doctor\` shows it. Log in again only if the token was removed`);
             }
+            if (this.#store.isBot()) {
+                throw new CliError("authentication_error", `profile "${profile}" is a bot — its commands are \`max ${asFirstWord(profile)}bot …\`; ` +
+                    `\`max ${asFirstWord(profile)}session start\` would add a personal account to it`);
+            }
             // The fix has to carry the profile, or it logs the wrong one in: a name nobody has logged
             // in under is the ordinary shape of this failure now that the first word is the profile.
             throw new CliError("authentication_error", `no session for profile "${profile}" — run \`max ${asFirstWord(profile)}session start\``);
@@ -1856,6 +2011,15 @@ export class MaxClient {
      * Uploads one file and answers what the message attaches (measured 2026-09-24). An upload is never
      * retried: a failure here happens before `MSG_SEND`, so nothing was sent.
      */
+    async #profilePhoto(path) {
+        if (!isImage(path))
+            throw new CliError("validation_error", `${path} is not an image MAX takes as a photo`);
+        const bytes = await readUpload(path);
+        const { url } = await this.#wire.uploads.photo({ count: 1, type: 0, uploaderType: 0, profile: true });
+        if (typeof url !== "string")
+            throw new CliError("provider_error", "MAX gave no address to upload the photo to");
+        return uploadPhoto(url, path, bytes);
+    }
     async #upload({ path, bytes, kind, voice }) {
         const request = { count: 1, type: 0, uploaderType: 0, profile: false };
         if (kind === "photo") {
@@ -2081,7 +2245,7 @@ export class MaxClient {
                 throw new CliError("validation_error", "without a local store a person is named by id — `max contacts lookup` finds one");
             }
             const id = isId(reference) ? reference.trim() : pickPerson(reference, cache).id;
-            const answer = await this.#wire.contacts.update({ contactId: id, action: wire });
+            const answer = await this.#wire.contacts.update({ contactId: id, ...wire });
             const contact = record(answer.contact);
             if (contact)
                 return this.#remember(toContact(contact));
@@ -2112,20 +2276,25 @@ export class MaxClient {
         return this.#login;
     }
 }
-/** PyMax `AdminPermission`; the sum is what MAX takes. */
+/**
+ * PyMax `AdminPermission`; the sum is what MAX takes. `read` and `link` measured 2026-09-27 by
+ * switching them in the app for a bot and reading its `permissions` back (`MAX-61`): «Read messages»
+ * sets 1 and 32 together — the Bot API calls them `read_all_messages` and `write` — and «Update chat
+ * link» 128. A bot without `read` sees no message of the group.
+ */
 export const ADMIN_RIGHTS = {
+    read: 1 | 32,
     members: 2,
     admins: 4,
     info: 8,
     pin: 16,
+    link: 128,
     post: 256,
     edit: 512,
     delete: 1024,
 };
-/** PyMax asks for this many; paging join requests is not known. */
 /** The most chats `max serve` holds from pushes before it logs in again instead. */
 const LIVE_CHATS = 10_000;
-const JOIN_REQUESTS = 100;
 /** PyMax's page, the one measured. */
 const MEMBERS_PAGE = 50;
 const MEMBERS_READ = 5000;
@@ -2316,6 +2485,13 @@ const asRefusal = (error) => {
     }
     return new CliError("provider_error", error.message, { operation: String(error.opcode) });
 };
+/** A link that was reset, or never led anywhere, is `not.found` from MAX (measured 2026-09-28). */
+const deadLink = (link) => (error) => {
+    const failure = asCliError(error);
+    if (failure.details.maxError !== "not.found")
+        throw failure;
+    throw new CliError("not_found", `${link.trim()} leads nowhere — the link was reset, or never worked`);
+};
 const LIMIT_WORDS = ["limit.violate", "rate_limit", "rate limit", "too many", "слишком много"];
 /** Before any request: a login inside the pause is one more attempt MAX counts (`MAX-38`). */
 export const refuseWhilePaused = (state) => {