simplex-chat 6.5.2__tar.gz → 7.1.0b6__tar.gz

{simplex_chat-6.5.2 → simplex_chat-7.1.0b6}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: simplex-chat
-Version: 6.5.2
+Version: 7.1.0b6
 Summary: SimpleX Chat Python library for chat bots
 Project-URL: Homepage, https://github.com/simplex-chat/simplex-chat/tree/stable/packages/simplex-chat-python
 Project-URL: Issues, https://github.com/simplex-chat/simplex-chat/issues

{simplex_chat-6.5.2 → simplex_chat-7.1.0b6}/examples/squaring_bot.py

@@ -26,7 +26,15 @@ bot = Bot(
     profile=BotProfile(display_name="Squaring bot"),
     db=SqliteDb(file_prefix="./squaring_bot"),
     welcome="Send me a number, I'll square it.",
-    commands=[BotCommand(keyword="help", label="Show help")],
+    commands=[
+        # `params=None` (default): the client SENDS `/help` immediately
+        # when the user taps it in the commands menu.
+        BotCommand(keyword="help", label="Show help"),
+        # `params="<number>"`: the client PASTES `/square <number>`
+        # into the input box and positions the cursor at the end. The
+        # user replaces `<number>` with the actual number and sends.
+        BotCommand(keyword="square", label="Square a number", params="<number>"),
+    ],
 )
 
 NUMBER_RE = re.compile(r"^-?\d+(\.\d+)?$")
@@ -48,5 +56,19 @@ async def help_cmd(msg: Message, _cmd: ParsedCommand) -> None:
     await msg.reply("Send a number, I'll square it.")
 
 
+@bot.on_command("square")
+async def square_cmd(msg: Message, cmd: ParsedCommand) -> None:
+    """Demonstrates the `params` flow: `cmd.args` is the trimmed text
+    AFTER `/square`. When the user tapped the menu entry above, the
+    client pasted `/square <number>` and the user replaced
+    `<number>` with the actual value before sending."""
+    try:
+        n = float(cmd.args)
+    except ValueError:
+        await msg.reply(f"Usage: /square <number> (got {cmd.args!r})")
+        return
+    await msg.reply(f"{n} * {n} = {n * n}")
+
+
 if __name__ == "__main__":
     bot.run()

{simplex_chat-6.5.2 → simplex_chat-7.1.0b6}/pyproject.toml

@@ -42,6 +42,10 @@ asyncio_mode = "auto"
 line-length = 100
 target-version = "py311"
 
+[tool.ruff.lint]
+# Generated by the Haskell codegen; regenerating is the only way to change them.
+exclude = ["src/simplex_chat/types/_*.py"]
+
 [tool.ruff.format]
 # `src/simplex_chat/types/*.py` are generated by the Haskell codegen
 # (bots/src/API/Docs/Generate/Python.hs). Re-formatting them locally

{simplex_chat-6.5.2 → simplex_chat-7.1.0b6}/src/simplex_chat/__init__.py

@@ -1,5 +1,6 @@
 """SimpleX Chat — Python client library for chat bots."""
 
+from . import util as util  # re-export the util namespace
 from ._version import __version__
 from .api import (
     ChatApi,
@@ -32,17 +33,16 @@ from .bot import (
     VideoMessage,
     VoiceMessage,
 )
-from .core import ChatAPIError, ChatInitError, CryptoArgs, MigrationConfirmation
-from . import util as util  # re-export the util namespace
+from .core import ChatAPIError, ChatError, ChatInitError, CryptoArgs, MigrationConfirmation
 
 __all__ = [
-    "__version__",
     "Bot",
     "BotCommand",
     "BotProfile",
     "ChatAPIError",
     "ChatApi",
     "ChatCommandError",
+    "ChatError",
     "ChatInitError",
     "ChatMessage",
     "Client",
@@ -68,5 +68,6 @@ __all__ = [
     "UnknownMessage",
     "VideoMessage",
     "VoiceMessage",
+    "__version__",
     "util",
 ]

{simplex_chat-6.5.2 → simplex_chat-7.1.0b6}/src/simplex_chat/__main__.py

@@ -26,7 +26,7 @@ def main(argv: list[str] | None = None) -> int:
         path = _native._resolve_libs_dir(args.backend)
         print(f"libsimplex installed at: {path}")
         return 0
-    except Exception as e:
+    except Exception as e:  # noqa: BLE001 - a CLI: report any failure, don't traceback
         print(f"install failed: {e}", file=sys.stderr)
         return 1
 

{simplex_chat-6.5.2 → simplex_chat-7.1.0b6}/src/simplex_chat/_native.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 
 import ctypes
 import errno
+import hashlib
 import os
 import platform
 import sys
@@ -16,9 +17,9 @@ import urllib.request
 import zipfile
 from ctypes import POINTER, c_char_p, c_int, c_uint8, c_void_p
 from pathlib import Path
-from typing import Literal
+from typing import Any, Literal
 
-from ._version import LIBS_VERSION
+from ._version import LIBS_RELEASE, LIBS_SHA256
 
 Backend = Literal["sqlite", "postgres"]
 
@@ -59,11 +60,14 @@ def _libname() -> str:
     return _LIBNAME[sys.platform]
 
 
-def _libs_url(backend: Backend) -> str:
+def _libs_asset(backend: Backend) -> str:
     suffix = "-postgres" if backend == "postgres" else ""
+    return f"simplex-chat-libs-{_platform_tag()}{suffix}.zip"
+
+
+def _libs_url(backend: Backend) -> str:
     return (
-        f"https://github.com/{_GITHUB_REPO}/releases/download/"
-        f"v{LIBS_VERSION}/simplex-chat-libs-{_platform_tag()}{suffix}.zip"
+        f"https://github.com/{_GITHUB_REPO}/releases/download/{LIBS_RELEASE}/{_libs_asset(backend)}"
     )
 
 
@@ -84,7 +88,7 @@ def _resolve_libs_dir(backend: Backend) -> Path:
             "postgres backend is only supported on linux-x86_64; "
             f"current platform is {_platform_tag()}"
         )
-    target = _cache_root() / f"v{LIBS_VERSION}" / backend
+    target = _cache_root() / LIBS_RELEASE / backend
     if not (target / _libname()).exists():
         _download(target, backend)
     return target
@@ -99,7 +103,7 @@ def _stream_to_file(url: str, dest: Path, *, timeout: float = 60.0) -> None:
     `timeout` is per-request; we don't touch `socket.setdefaulttimeout`
     so other socket users in the same process aren't affected.
     """
-    with urllib.request.urlopen(url, timeout=timeout) as resp:  # noqa: S310 - https://github.com/...
+    with urllib.request.urlopen(url, timeout=timeout) as resp:
         total = int(resp.headers.get("Content-Length") or 0)
         received = 0
         with dest.open("wb") as out:
@@ -112,7 +116,7 @@ def _stream_to_file(url: str, dest: Path, *, timeout: float = 60.0) -> None:
                 else:
                     msg = f"\r  download: {received >> 20} MiB"
                 print(msg, end="", file=sys.stderr, flush=True)
-        print("", file=sys.stderr, flush=True)  # newline after final progress line
+        print(file=sys.stderr, flush=True)  # newline after final progress line
 
 
 def _download(target: Path, backend: Backend) -> None:
@@ -125,16 +129,21 @@ def _download(target: Path, backend: Backend) -> None:
     what we need and proceed. NEVER rmtree the target: that creates a TOCTOU
     window where another process is reading/loading the file we're deleting.
     """
+    asset = _libs_asset(backend)
+    sha256 = LIBS_SHA256.get(asset)
+    if sha256 is None:
+        raise RuntimeError(f"no SHA-256 is pinned for {asset}")
     target.parent.mkdir(parents=True, exist_ok=True)
     url = _libs_url(backend)
     print(
-        f"Downloading libsimplex ({_platform_tag()}, {backend}) v{LIBS_VERSION} from {url} ...",
+        f"Downloading libsimplex ({_platform_tag()}, {backend}) {LIBS_RELEASE} from {url} ...",
         file=sys.stderr,
         flush=True,
     )
     with tempfile.TemporaryDirectory(dir=target.parent) as tmp:
         zip_path = Path(tmp) / "libs.zip"
         _stream_to_file(url, zip_path, timeout=60.0)
+        _verify_sha256(zip_path, sha256, url)
         with zipfile.ZipFile(zip_path) as zf:
             zf.extractall(tmp)
         # zip layout: <tmp>/libs/libsimplex.* + libHS*.*
@@ -158,6 +167,16 @@ def _download(target: Path, backend: Backend) -> None:
                 ) from e
 
 
+def _verify_sha256(file: Path, expected: str, url: str) -> None:
+    digest = hashlib.sha256()
+    with file.open("rb") as f:
+        while chunk := f.read(_DOWNLOAD_CHUNK):
+            digest.update(chunk)
+    actual = digest.hexdigest()
+    if actual != expected:
+        raise RuntimeError(f"SHA-256 of {url} is {actual}, expected {expected}")
+
+
 _lock = threading.Lock()
 _lib: ctypes.CDLL | None = None
 _libc: ctypes.CDLL | None = None
@@ -166,7 +185,8 @@ _backend: Backend | None = None
 
 def _load_libc() -> ctypes.CDLL:
     if sys.platform == "win32":
-        return ctypes.CDLL("msvcrt")
+        # libsimplex.dll allocates results with UCRT malloc; msvcrt free would corrupt the heap.
+        return ctypes.CDLL("ucrtbase")
     return ctypes.CDLL(None)  # libc on POSIX is the process's own symbol table
 
 
@@ -229,8 +249,8 @@ def lib_for(backend: Backend) -> ctypes.CDLL:
         if _lib is not None:
             if _backend != backend:
                 raise RuntimeError(
-                    f"libsimplex already loaded with backend={_backend!r}; "
-                    f"cannot switch to {backend!r} in the same process"
+                    f"libsimplex already loaded with backend={_backend}; "
+                    f"cannot switch to {backend} in the same process"
                 )
             return _lib
         libs_dir = _resolve_libs_dir(backend)
@@ -255,3 +275,19 @@ def lib() -> ctypes.CDLL:
     if _lib is None:
         raise RuntimeError("lib_for() must be called before lib()")
     return _lib
+
+
+QUEUE_SIZE_UNSUPPORTED = (
+    "loaded libsimplex does not export chat_migrate_init_queue; queue size needs a newer libsimplex"
+)
+
+
+def migrate_init_queue() -> Any:
+    """`chat_migrate_init_queue`, which older libsimplex releases do not export."""
+    try:
+        fn = lib().chat_migrate_init_queue
+    except AttributeError as e:
+        raise RuntimeError(QUEUE_SIZE_UNSUPPORTED) from e
+    fn.argtypes = [c_char_p, c_char_p, c_char_p, c_int, POINTER(c_void_p)]
+    fn.restype = c_void_p
+    return fn

simplex_chat-7.1.0b6/src/simplex_chat/_version.py

@@ -0,0 +1,16 @@
+"""Package version and the simplex-chat-libs release it loads.
+
+Written by scripts/ci/packages_release.py: the release PR bumps the version
+and pins new library releases with the SHA-256 of their assets.
+"""
+
+__version__ = "7.1.0b6"  # PEP 440 — read by hatchling for wheel metadata
+LIBS_RELEASE = "core-7.1.0.11"  # simplex-chat-libs release tag
+LIBS_SHA256 = {
+    "simplex-chat-libs-linux-aarch64.zip": "d66aa1b30b9fa20225dad8ef75a9c605961e1c0adde2ba0283e2fcac4e15d260",
+    "simplex-chat-libs-linux-x86_64-postgres.zip": "925b3166f969b12082ff8ee659e5f2a9933fe40120deb80c9aa3002a5ba6c803",
+    "simplex-chat-libs-linux-x86_64.zip": "dabad0824e8813ea4a084fbf37e1ba4cf6dcea9cd8ccadc521fec200f246208a",
+    "simplex-chat-libs-macos-aarch64.zip": "aa74608b149fff7508a47eaac4284dcc6d189c6ed8b7c18428df9158bc176a61",
+    "simplex-chat-libs-macos-x86_64.zip": "a0e21457e1077be7f71b46c1c27452945b2cee2b6c50efb0004412ce5b7042ec",
+    "simplex-chat-libs-windows-x86_64.zip": "c01dad574daa101a1cbfd31ddbf2b3d0d986a4a42f97d789d2f878b2050b2b4b",
+}

{simplex_chat-6.5.2 → simplex_chat-7.1.0b6}/src/simplex_chat/api.py

@@ -2,13 +2,15 @@
 
 from __future__ import annotations
 
+import asyncio
 import json
+from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass
 from typing import Any, Literal
 
 from . import _native, core, util
 from .core import MigrationConfirmation
-from .types import CC, CEvt, CR, T
+from .types import CC, CR, CEvt, T
 
 # Mirrors Node `ConnReqType` enum (api.ts:15-18) — the two possible outcomes
 # of `api_connect` / `api_connect_active_user` depending on the link kind.
@@ -39,7 +41,7 @@ def _db_to_migrate_args(db: Db) -> tuple[str, str, _native.Backend]:
     raise TypeError(f"Unknown db: {db!r}")
 
 
-class ChatCommandError(Exception):
+class ChatCommandError(core.ChatError):
     """A chat command returned an unexpected response type.
 
     `response` is the raw wire response; `response_type` exposes its `type`
@@ -65,17 +67,20 @@ class ChatApi:
     def __init__(self, ctrl: int):
         self._ctrl: int | None = ctrl
         self._started = False
+        self._recv_executor: ThreadPoolExecutor | None = None
 
     @classmethod
     async def init(
         cls,
         db: Db,
         confirm: MigrationConfirmation = MigrationConfirmation.YES_UP,
-    ) -> "ChatApi":
+        queue_size: int | None = None,
+    ) -> ChatApi:
         path_or_prefix, key_or_conn, backend = _db_to_migrate_args(db)
         # Trigger lazy lib load with the right backend BEFORE chat_migrate_init.
-        _native.lib_for(backend)
-        ctrl = await core.chat_migrate_init(path_or_prefix, key_or_conn, confirm)
+        # It may download ~100 MB, so it must not block the event loop.
+        await asyncio.to_thread(_native.lib_for, backend)
+        ctrl = await core.chat_migrate_init(path_or_prefix, key_or_conn, confirm, queue_size)
         return cls(ctrl)
 
     @property
@@ -96,8 +101,12 @@ class ChatApi:
         return self._started
 
     async def start_chat(self) -> None:
+        # serviceRequests is off: a bot answers its own address, it does not
+        # serve requests routed to it as a service.
         r = await self.send_chat_cmd(
-            CC.StartChat_cmd_string({"mainApp": True, "enableSndFiles": True})
+            CC.StartChat_cmd_string(
+                {"mainApp": True, "enableSndFiles": True, "serviceRequests": False}
+            )
         )
         if r.get("type") not in ("chatStarted", "chatRunning"):
             raise ChatCommandError("error starting chat", r)
@@ -110,6 +119,14 @@ class ChatApi:
         self._started = False
 
     async def close(self) -> None:
+        """Stop the chat and close its store; the store stays open if stopping fails."""
+        # a running controller keeps using the database connections that closing frees
+        await self.stop_chat()
+        if self._recv_executor is not None:
+            # Waits for a receive already in flight (up to wait_us) so the store
+            # never closes underneath one; run off-loop since shutdown blocks.
+            await asyncio.to_thread(self._recv_executor.shutdown, wait=True)
+            self._recv_executor = None
         await core.chat_close_store(self.ctrl)
         self._ctrl = None
         self._started = False
@@ -118,7 +135,14 @@ class ChatApi:
         return await core.chat_send_cmd(self.ctrl, cmd)
 
     async def recv_chat_event(self, wait_us: int = 500_000) -> CEvt.ChatEvent | None:
-        return await core.chat_recv_msg_wait(self.ctrl, wait_us)
+        ctrl = self.ctrl  # raises before touching the executor if close() was called
+        if self._recv_executor is None:
+            # A receive blocks for up to wait_us almost back to back, so it would
+            # otherwise pin one of the default executor's few worker threads.
+            self._recv_executor = ThreadPoolExecutor(
+                max_workers=1, thread_name_prefix="simplex-recv"
+            )
+        return await core.chat_recv_msg_wait(ctrl, wait_us, self._recv_executor)
 
     # ------------------------------------------------------------------ #
     # Address commands
@@ -142,12 +166,7 @@ class ChatApi:
                 return r["contactLink"]
             raise ChatCommandError("error loading user address", r)
         except core.ChatAPIError as e:
-            ce = e.chat_error
-            if (
-                ce is not None
-                and ce.get("type") == "errorStore"
-                and ce.get("storeError", {}).get("type") == "userContactLinkNotFound"
-            ):
+            if e.store_error_type == "userContactLinkNotFound":
                 return None
             raise
 
@@ -159,6 +178,8 @@ class ChatApi:
         )
         if r["type"] == "userProfileUpdated":
             return r["updateSummary"]
+        if r["type"] == "userProfileNoChange":
+            return {"updateSuccesses": 0, "updateFailures": 0, "changedContacts": []}
         raise ChatCommandError("error setting profile address", r)
 
     async def api_set_address_settings(self, user_id: int, settings: T.AddressSettings) -> None:
@@ -193,6 +214,7 @@ class ChatApi:
                     "sendRef": send_ref,
                     "composedMessages": messages,
                     "liveMessage": live_message,
+                    "signMessages": False,
                 }
             )
         )
@@ -236,6 +258,8 @@ class ChatApi:
         )
         if r["type"] == "chatItemUpdated":
             return r["chatItem"]["chatItem"]
+        if r["type"] == "chatItemNotChanged":
+            return r["chatItem"]["chatItem"]
         raise ChatCommandError("error updating chat item", r)
 
     async def api_delete_chat_items(
@@ -302,6 +326,8 @@ class ChatApi:
         )
         if r["type"] == "rcvFileAccepted":
             return r["chatItem"]
+        if r["type"] == "rcvFileAcceptedSndCancelled":
+            raise ChatCommandError("file cancelled by sender", r)
         raise ChatCommandError("error receiving file", r)
 
     async def api_cancel_file(self, file_id: int) -> None:
@@ -325,6 +351,23 @@ class ChatApi:
             return r["member"]
         raise ChatCommandError("error adding member", r)
 
+    async def api_add_member_via_group(
+        self, group_id: int, via_group_id: int, group_member_id: int, member_role: T.GroupMemberRole
+    ) -> T.GroupMember:
+        r = await self.send_chat_cmd(
+            CC.APIAddMemberViaGroup_cmd_string(
+                {
+                    "groupId": group_id,
+                    "viaGroupId": via_group_id,
+                    "groupMemberId": group_member_id,
+                    "memberRole": member_role,
+                }
+            )
+        )
+        if r["type"] == "sentGroupInvitationViaGroup":
+            return r["member"]
+        raise ChatCommandError("error adding member", r)
+
     async def api_join_group(self, group_id: int) -> T.GroupInfo:
         r = await self.send_chat_cmd(CC.APIJoinGroup_cmd_string({"groupId": group_id}))
         if r["type"] == "userAcceptedGroupSent":
@@ -466,7 +509,7 @@ class ChatApi:
     ) -> tuple[T.ConnectionPlan, T.CreatedConnLink]:
         r = await self.send_chat_cmd(
             CC.APIConnectPlan_cmd_string(
-                {"userId": user_id, "connectionLink": connection_link, "resolveKnown": False}
+                {"userId": user_id, "connectTarget": connection_link, "resolveMode": "unknown"}
             )
         )
         if r["type"] == "connectionPlan":
@@ -477,17 +520,18 @@ class ChatApi:
         self,
         user_id: int,
         incognito: bool,
-        prepared_link: T.CreatedConnLink | None = None,
+        prepared_link: T.CreatedConnLink,
     ) -> ConnReqType:
-        args: CC.APIConnect = {"userId": user_id, "incognito": incognito}
-        if prepared_link is not None:
-            args["preparedLink_"] = prepared_link
-        r = await self.send_chat_cmd(CC.APIConnect_cmd_string(args))
+        r = await self.send_chat_cmd(
+            CC.APIConnect_cmd_string(
+                {"userId": user_id, "incognito": incognito, "preparedLink_": prepared_link}
+            )
+        )
         return self._handle_connect_result(r)
 
     async def api_connect_active_user(self, conn_link: str) -> ConnReqType:
         r = await self.send_chat_cmd(
-            CC.Connect_cmd_string({"incognito": False, "connLink_": conn_link})
+            CC.Connect_cmd_string({"incognito": False, "connTarget_": conn_link})
         )
         return self._handle_connect_result(r)
 
@@ -509,8 +553,10 @@ class ChatApi:
         raise ChatCommandError("error accepting contact request", r)
 
     async def api_reject_contact_request(self, contact_req_id: int) -> None:
+        # notify is not rendered into the command string, so the core reads its
+        # own default of off; this only keeps the argument type satisfied.
         r = await self.send_chat_cmd(
-            CC.APIRejectContact_cmd_string({"contactReqId": contact_req_id})
+            CC.APIRejectContact_cmd_string({"contactReqId": contact_req_id, "notify": False})
         )
         if r["type"] != "contactRequestRejected":
             raise ChatCommandError("error rejecting contact request", r)
@@ -606,6 +652,28 @@ class ChatApi:
         if r["type"] != "cmdOk":
             raise ChatCommandError("error setting contact custom data", r)
 
+    async def api_merge_contact_custom_data(
+        self, contact: T.Contact, key: str, value: object | None
+    ) -> None:
+        """Set or drop one key of a contact's custom data, keeping the rest.
+
+        The set command replaces the whole column. `value=None` removes `key`.
+        """
+        await self.api_set_contact_custom_data(
+            contact["contactId"], util.merged_custom_data(contact.get("customData"), key, value)
+        )
+
+    async def api_merge_group_custom_data(
+        self, group: T.GroupInfo, key: str, value: object | None
+    ) -> None:
+        """Set or drop one key of a group's custom data, keeping the rest.
+
+        See `api_merge_contact_custom_data`.
+        """
+        await self.api_set_group_custom_data(
+            group["groupId"], util.merged_custom_data(group.get("customData"), key, value)
+        )
+
     async def api_set_auto_accept_member_contacts(self, user_id: int, on_off: bool) -> None:
         r = await self.send_chat_cmd(
             CC.APISetUserAutoAcceptMemberContacts_cmd_string({"userId": user_id, "onOff": on_off})
@@ -631,17 +699,12 @@ class ChatApi:
                 return r["user"]
             raise ChatCommandError("unexpected response", r)
         except core.ChatAPIError as e:
-            ce = e.chat_error
-            if (
-                ce is not None
-                and ce.get("type") == "error"
-                and ce.get("errorType", {}).get("type") == "noActiveUser"
-            ):
+            if e.error_type == "noActiveUser":
                 return None
             raise
 
     async def api_create_active_user(self, profile: T.Profile | None = None) -> T.User:
-        new_user: T.NewUser = {"pastTimestamp": False, "userChatRelay": False}
+        new_user: T.NewUser = {"pastTimestamp": False, "userChatRelay": False, "clientService": False}
         if profile is not None:
             new_user["profile"] = profile
         r = await self.send_chat_cmd(CC.CreateActiveUser_cmd_string({"newUser": new_user}))
@@ -718,3 +781,13 @@ class ChatApi:
         if r["type"] == "newMemberContactSentInv":
             return r["contact"]
         raise ChatCommandError("error sending member contact invitation", r)
+
+    async def api_accept_member_contact(self, contact_id: int) -> T.Contact:
+        """Accept a direct connection a group member opened with us.
+
+        The core rejects a second accept with "connection already started".
+        """
+        r = await self.send_chat_cmd(f"/_accept member contact @{contact_id}")
+        if r["type"] == "memberContactAccepted":
+            return r["contact"]
+        raise ChatCommandError("error accepting member contact", r)

{simplex_chat-6.5.2 → simplex_chat-7.1.0b6}/src/simplex_chat/bot.py

@@ -33,8 +33,38 @@ from .types import T
 
 @dataclass(slots=True)
 class BotCommand:
+    """One entry in the bot's advertised slash-command list (wire-side
+    `groupPreferences.commands` or profile `preferences.commands`).
+
+    `keyword` and `label` are required: `keyword` is what the user
+    types after `/`; `label` is the human-readable description shown
+    next to the keyword in the SimpleX client's commands menu.
+
+    `params` is an optional placeholder string that controls how the
+    client behaves when the user taps the command in the menu:
+
+      * `params=None` (default) — the client SENDS `/<keyword>`
+        immediately on tap; no input-box detour. Use this for
+        zero-argument commands (`/help`, `/ping`) where the action is
+        unambiguous.
+
+      * `params="<value>"` — the client PASTES `/<keyword> <params>`
+        into the input box and positions the cursor at the end. The
+        user edits the placeholder and sends. Use this for commands
+        that take a required argument (`/review <pr-url>`,
+        `/order <number>`) so the user sees the expected shape
+        without having to remember it.
+
+    Mirrors `CBCCommand` in the Haskell core
+    (`Simplex.Chat.Types.Preferences`) and the wire TypedDict
+    `ChatBotCommand_command`. Both SimpleX clients (Android/Kotlin
+    and iOS/Swift) implement the paste-vs-send branch on the
+    `params` field; see `CommandsMenuView.{kt,swift}` for the
+    reference UI behaviour.
+    """
     keyword: str
     label: str
+    params: str | None = None
 
 
 class Bot(Client):
@@ -60,6 +90,7 @@ class Bot(Client):
         welcome: str | T.MsgContent | None = None,
         commands: list[BotCommand] | None = None,
         confirm_migrations: MigrationConfirmation = MigrationConfirmation.YES_UP,
+        queue_size: int | None = None,
         create_address: bool = True,
         update_address: bool = True,
         update_profile: bool = True,
@@ -73,6 +104,7 @@ class Bot(Client):
             profile=profile,
             db=db,
             confirm_migrations=confirm_migrations,
+            queue_size=queue_size,
             update_profile=update_profile,
             log_contacts=log_contacts,
             log_network=log_network,
@@ -91,8 +123,8 @@ class Bot(Client):
 
     async def _post_start(self, user: T.User) -> None:
         """Bots sync address first, then embed the link in the profile."""
-        link = await self._sync_address(user)
-        await self._maybe_sync_profile(user, contact_link=link)
+        self._contact_link = await self._sync_address(user)
+        await self._maybe_sync_profile(user)
 
     async def _sync_address(self, user: T.User) -> str | None:
         """Address sync. Returns the public link if any, for embedding in the profile."""
@@ -145,10 +177,24 @@ class Bot(Client):
             "files": {"allow": "yes" if self._allow_files else "no"},
         }
         if self._commands:
-            prefs["commands"] = [
-                {"type": "command", "keyword": c.keyword, "label": c.label}
-                for c in self._commands
-            ]
+            cmds: list[T.ChatBotCommand] = []
+            for c in self._commands:
+                entry: T.ChatBotCommand_command = {
+                    "type": "command",
+                    "keyword": c.keyword,
+                    "label": c.label,
+                }
+                # `params` is `NotRequired[str]` on the wire; omit the
+                # key entirely when None so the Haskell parser sees
+                # `Nothing` rather than `Just ""`. The two have
+                # different client semantics: `Nothing` (`params=None`)
+                # triggers an immediate send on tap; `Just ""` would
+                # paste `/<keyword> ` (with a trailing space) into the
+                # input box, which is rarely what the operator wants.
+                if c.params is not None:
+                    entry["params"] = c.params
+                cmds.append(entry)
+            prefs["commands"] = cmds
         p["preferences"] = prefs
         p["peerType"] = "bot"
         return p