commsuite-bot 1.0.40__tar.gz

commsuite_bot-1.0.40/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: commsuite-bot
+Version: 1.0.40
+Summary: Standard-library Python client for the Commsuite Bot API
+Author: Aleksey Shvarts
+Project-URL: Homepage, https://github.com/AlekseyShvartsGD/commsuite
+Project-URL: Source, https://github.com/AlekseyShvartsGD/commsuite/tree/main/server/bot_api
+Project-URL: Releases, https://github.com/AlekseyShvartsGD/commsuite/releases
+Keywords: commsuite,bot,chat,api,messenger
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Commsuite Bot API
+
+Bots are real Commsuite accounts (`role = 'bot'`). They appear in People, can
+be added to groups, and cannot sign in with a password. Each bot has an API
+token that lets your own program act as that account.
+
+Create a bot in **Settings → Developer tools**, then open **API** on the bot
+card to copy its token. The same dialog contains a ready-to-run Python example.
+
+## Endpoints
+
+All requests use `Authorization: Bearer cmsb_…`.
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| GET | `/api/bot/me` | Bot identity |
+| GET | `/api/bot/updates?offset=0&timeout=30&limit=100` | Long-poll incoming messages |
+| POST | `/api/bot/sendMessage` | Send a message |
+
+`sendMessage` body:
+
+```json
+{ "conversationId": "…", "text": "hello", "replyTo": "optional-message-id" }
+```
+
+`updates` response:
+
+```json
+{
+  "updates": [
+    {
+      "updateId": 42,
+      "conversationId": "…",
+      "message": { "id": "…", "senderId": "…", "body": "hi", "…": "…" }
+    }
+  ]
+}
+```
+
+Pass the last `updateId` as `offset` on the next request; acknowledged updates
+are deleted. `timeout` keeps the request open while the bot is idle (maximum
+50 seconds). A paused bot rejects its token with `401`.
+
+A bot can also call the regular user API (`/api/conversations`,
+`/api/conversations/:id/messages`, …) with the same token.
+
+## Python
+
+```bash
+pip install commsuite-bot
+```
+
+```python
+from commsuite_bot import CommsuiteBot
+
+bot = CommsuiteBot("http://localhost:3000", "cmsb_…")
+
+def handle(update):
+    message = update["message"]
+    bot.send_message(update["conversationId"], "echo: " + message["body"])
+
+bot.run(handle)
+```
+
+The package is a single standard-library module, so it also works by copying
+`commsuite_bot.py` next to your script. See `example_echo_bot.py` for a complete
+echo bot. Only Python 3.8+ is required; there are no external dependencies.
+
+Publishing a new version (maintainers): `python -m build` then
+`twine upload dist/*` from this folder, with `TWINE_USERNAME=__token__` and
+`TWINE_PASSWORD` set to a PyPI API token.
+
+## Built-in replies and mini-apps
+
+Bots without an external program can still use keyword replies and one
+mini-app (JSON formatter, Base64, or UUID generator). Both are managed from the
+bot card in Developer tools. `send /help` to a bot to discover its commands.
+
+External programs receive updates for every message sent to the bot by a
+human account. Messages sent by other bots are not queued, which prevents
+runaway loops between automated accounts.

commsuite_bot-1.0.40/README.md

@@ -0,0 +1,81 @@
+# Commsuite Bot API
+
+Bots are real Commsuite accounts (`role = 'bot'`). They appear in People, can
+be added to groups, and cannot sign in with a password. Each bot has an API
+token that lets your own program act as that account.
+
+Create a bot in **Settings → Developer tools**, then open **API** on the bot
+card to copy its token. The same dialog contains a ready-to-run Python example.
+
+## Endpoints
+
+All requests use `Authorization: Bearer cmsb_…`.
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| GET | `/api/bot/me` | Bot identity |
+| GET | `/api/bot/updates?offset=0&timeout=30&limit=100` | Long-poll incoming messages |
+| POST | `/api/bot/sendMessage` | Send a message |
+
+`sendMessage` body:
+
+```json
+{ "conversationId": "…", "text": "hello", "replyTo": "optional-message-id" }
+```
+
+`updates` response:
+
+```json
+{
+  "updates": [
+    {
+      "updateId": 42,
+      "conversationId": "…",
+      "message": { "id": "…", "senderId": "…", "body": "hi", "…": "…" }
+    }
+  ]
+}
+```
+
+Pass the last `updateId` as `offset` on the next request; acknowledged updates
+are deleted. `timeout` keeps the request open while the bot is idle (maximum
+50 seconds). A paused bot rejects its token with `401`.
+
+A bot can also call the regular user API (`/api/conversations`,
+`/api/conversations/:id/messages`, …) with the same token.
+
+## Python
+
+```bash
+pip install commsuite-bot
+```
+
+```python
+from commsuite_bot import CommsuiteBot
+
+bot = CommsuiteBot("http://localhost:3000", "cmsb_…")
+
+def handle(update):
+    message = update["message"]
+    bot.send_message(update["conversationId"], "echo: " + message["body"])
+
+bot.run(handle)
+```
+
+The package is a single standard-library module, so it also works by copying
+`commsuite_bot.py` next to your script. See `example_echo_bot.py` for a complete
+echo bot. Only Python 3.8+ is required; there are no external dependencies.
+
+Publishing a new version (maintainers): `python -m build` then
+`twine upload dist/*` from this folder, with `TWINE_USERNAME=__token__` and
+`TWINE_PASSWORD` set to a PyPI API token.
+
+## Built-in replies and mini-apps
+
+Bots without an external program can still use keyword replies and one
+mini-app (JSON formatter, Base64, or UUID generator). Both are managed from the
+bot card in Developer tools. `send /help` to a bot to discover its commands.
+
+External programs receive updates for every message sent to the bot by a
+human account. Messages sent by other bots are not queued, which prevents
+runaway loops between automated accounts.

commsuite_bot-1.0.40/commsuite_bot.egg-info/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: commsuite-bot
+Version: 1.0.40
+Summary: Standard-library Python client for the Commsuite Bot API
+Author: Aleksey Shvarts
+Project-URL: Homepage, https://github.com/AlekseyShvartsGD/commsuite
+Project-URL: Source, https://github.com/AlekseyShvartsGD/commsuite/tree/main/server/bot_api
+Project-URL: Releases, https://github.com/AlekseyShvartsGD/commsuite/releases
+Keywords: commsuite,bot,chat,api,messenger
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# Commsuite Bot API
+
+Bots are real Commsuite accounts (`role = 'bot'`). They appear in People, can
+be added to groups, and cannot sign in with a password. Each bot has an API
+token that lets your own program act as that account.
+
+Create a bot in **Settings → Developer tools**, then open **API** on the bot
+card to copy its token. The same dialog contains a ready-to-run Python example.
+
+## Endpoints
+
+All requests use `Authorization: Bearer cmsb_…`.
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| GET | `/api/bot/me` | Bot identity |
+| GET | `/api/bot/updates?offset=0&timeout=30&limit=100` | Long-poll incoming messages |
+| POST | `/api/bot/sendMessage` | Send a message |
+
+`sendMessage` body:
+
+```json
+{ "conversationId": "…", "text": "hello", "replyTo": "optional-message-id" }
+```
+
+`updates` response:
+
+```json
+{
+  "updates": [
+    {
+      "updateId": 42,
+      "conversationId": "…",
+      "message": { "id": "…", "senderId": "…", "body": "hi", "…": "…" }
+    }
+  ]
+}
+```
+
+Pass the last `updateId` as `offset` on the next request; acknowledged updates
+are deleted. `timeout` keeps the request open while the bot is idle (maximum
+50 seconds). A paused bot rejects its token with `401`.
+
+A bot can also call the regular user API (`/api/conversations`,
+`/api/conversations/:id/messages`, …) with the same token.
+
+## Python
+
+```bash
+pip install commsuite-bot
+```
+
+```python
+from commsuite_bot import CommsuiteBot
+
+bot = CommsuiteBot("http://localhost:3000", "cmsb_…")
+
+def handle(update):
+    message = update["message"]
+    bot.send_message(update["conversationId"], "echo: " + message["body"])
+
+bot.run(handle)
+```
+
+The package is a single standard-library module, so it also works by copying
+`commsuite_bot.py` next to your script. See `example_echo_bot.py` for a complete
+echo bot. Only Python 3.8+ is required; there are no external dependencies.
+
+Publishing a new version (maintainers): `python -m build` then
+`twine upload dist/*` from this folder, with `TWINE_USERNAME=__token__` and
+`TWINE_PASSWORD` set to a PyPI API token.
+
+## Built-in replies and mini-apps
+
+Bots without an external program can still use keyword replies and one
+mini-app (JSON formatter, Base64, or UUID generator). Both are managed from the
+bot card in Developer tools. `send /help` to a bot to discover its commands.
+
+External programs receive updates for every message sent to the bot by a
+human account. Messages sent by other bots are not queued, which prevents
+runaway loops between automated accounts.

commsuite_bot-1.0.40/commsuite_bot.egg-info/SOURCES.txt

@@ -0,0 +1,7 @@
+README.md
+commsuite_bot.py
+pyproject.toml
+commsuite_bot.egg-info/PKG-INFO
+commsuite_bot.egg-info/SOURCES.txt
+commsuite_bot.egg-info/dependency_links.txt
+commsuite_bot.egg-info/top_level.txt

commsuite_bot-1.0.40/commsuite_bot.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

commsuite_bot-1.0.40/commsuite_bot.egg-info/top_level.txt

@@ -0,0 +1 @@
+commsuite_bot

commsuite_bot-1.0.40/commsuite_bot.py

@@ -0,0 +1,86 @@
+"""Tiny standard-library client for the Commsuite Bot API.
+
+Create a bot in Commsuite → Settings → Developer tools, open its API dialog,
+copy the token, and pass it here. No third-party packages are required.
+
+    from commsuite_bot import CommsuiteBot
+
+    bot = CommsuiteBot("http://localhost:3000", "cmsb_...")
+    print(bot.me())
+"""
+
+import json
+import urllib.error
+import urllib.request
+
+
+class CommsuiteError(RuntimeError):
+    def __init__(self, status, message):
+        super().__init__(f"{status}: {message}")
+        self.status = status
+        self.message = message
+
+
+class CommsuiteBot:
+    def __init__(self, base_url, token, request_timeout=60):
+        self.api_base = base_url.rstrip("/") + "/api"
+        self.token = token
+        self.request_timeout = request_timeout
+
+    def _request(self, method, path, data=None, timeout=None):
+        body = None if data is None else json.dumps(data).encode("utf-8")
+        request = urllib.request.Request(
+            self.api_base + path,
+            data=body,
+            method=method,
+            headers={
+                "Authorization": f"Bearer {self.token}",
+                "Content-Type": "application/json",
+            },
+        )
+        try:
+            with urllib.request.urlopen(
+                request, timeout=timeout or self.request_timeout
+            ) as response:
+                return json.load(response)
+        except urllib.error.HTTPError as error:
+            try:
+                payload = json.load(error)
+                message = payload.get("error", error.reason)
+            except Exception:
+                message = error.reason
+            raise CommsuiteError(error.code, message) from None
+
+    def me(self):
+        return self._request("GET", "/bot/me")
+
+    def get_updates(self, offset=0, timeout=30, limit=100):
+        """Long-polls for messages. Pass the last updateId back as offset."""
+        query = f"?offset={int(offset)}&timeout={int(timeout)}&limit={int(limit)}"
+        return self._request(
+            "GET", "/bot/updates" + query, timeout=timeout + 10
+        )["updates"]
+
+    def send_message(self, conversation_id, text, reply_to=None):
+        payload = {"conversationId": conversation_id, "text": text}
+        if reply_to:
+            payload["replyTo"] = reply_to
+        return self._request("POST", "/bot/sendMessage", payload)["message"]
+
+    # The regular API is available too, e.g. conversations() to discover id's.
+    def conversations(self):
+        return self._request("GET", "/conversations")["conversations"]
+
+    def messages(self, conversation_id, limit=50):
+        return self._request(
+            "GET", f"/conversations/{conversation_id}/messages?limit={int(limit)}"
+        )["messages"]
+
+    def run(self, handler, poll_timeout=30):
+        """Calls handler(update) forever, acknowledging each batch."""
+        offset = 0
+        while True:
+            updates = self.get_updates(offset=offset, timeout=poll_timeout)
+            for update in updates:
+                offset = update["updateId"]
+                handler(update)

commsuite_bot-1.0.40/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "commsuite-bot"
+version = "1.0.40"
+description = "Standard-library Python client for the Commsuite Bot API"
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [{ name = "Aleksey Shvarts" }]
+keywords = ["commsuite", "bot", "chat", "api", "messenger"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Topic :: Communications :: Chat",
+]
+
+[project.urls]
+Homepage = "https://github.com/AlekseyShvartsGD/commsuite"
+Source = "https://github.com/AlekseyShvartsGD/commsuite/tree/main/server/bot_api"
+Releases = "https://github.com/AlekseyShvartsGD/commsuite/releases"
+
+# Ship the single stdlib module; example_echo_bot.py stays in the repo only.
+[tool.setuptools]
+py-modules = ["commsuite_bot"]

commsuite_bot-1.0.40/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+