hidesay-bot 0.2.0__tar.gz

hidesay_bot-0.2.0/.gitignore

@@ -0,0 +1,39 @@
+# environments
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+
+# python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# tools
+.cache/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.log
+
+# docs output
+docs/_build/
+
+# the tests that drive a real server live with the server, not here
+/tests/integration/
+
+# never commit these: bot keys, tokens, local storage
+*.asc
+!tests/fixtures/*.asc
+*.key
+*.db
+*.db-wal
+*.db-shm
+*.lock

hidesay_bot-0.2.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the version
+numbers follow [Semantic Versioning](https://semver.org/), with the rules in
+`docs/project/versioning.md`.
+
+## [0.2.0] - 2026-11-15
+
+First release as hidesay-bot. Versions 0.1.0 and 0.1.1 came out under the app's old name, as
+PGPCbot: this is the same library, and what changes for code written against it is under
+"Changed".
+
+### Added
+
+- `AsyncClient` and `Client`: all 22 operations of Bot API 1.0.0 (`openapi.json`), plus media
+  downloads, with typed models, client-side checks that match the server's, retries with
+  backoff and a stable `sendId`, waiting on `429`, and a client-side rate limiter.
+- `Bot` and `SyncBot`: handlers for messages, commands, buttons, edited and deleted messages,
+  and membership changes; filters, routers, middleware, error handlers, automatic answers to
+  button presses; startup and shutdown hooks; `request_stop()` from a handler or another thread.
+- `resolve()`, for `GET /resolve/{username}`: the handle somebody writes at a bot, turned into
+  an id. One pool of names covers people, groups and channels, so the answer says which it was
+  - `Resolved`, with `HandleKind`, a `ChatPeer` for a person or a `ChatCard` for a public group
+  or channel. A leading `@` and the case are taken off before the request goes out, and
+  `UsernameNotFoundError` (404 `username_not_found`) is what a free handle, a group with no
+  public name and a closed account all answer.
+- OpenPGP: making, loading, protecting and rotating the bot's key; automatic encryption and
+  signing in protected chats; decryption and signature checks on incoming messages, including
+  the compressed messages phones send; reading the app's internal message format; downloading
+  and decrypting attachments; pinning keys the first time they are seen.
+- Long polling and an ASGI webhook (FastAPI, Starlette, uvicorn) with "at least once"
+  delivery, a durable `SQLiteStorage` queue, and failed updates kept so they can be retried.
+- The `hidesay-bot` command line: `keygen`, `fingerprint`, `whoami`, `publish-key`, `webhook`.
+- The documentation website at <https://vntcore.github.io/hidesay-bot/>, built from the
+  docstrings and the pages in `docs/`.
+
+### Changed
+
+- The package is `hidesay-bot` on PyPI, it is imported as `hidesay_bot` and the command is
+  `hidesay-bot`.
+- The environment variables are `HIDESAY_BOT_TOKEN`, `HIDESAY_API`, `HIDESAY_BOT_KEY` and the
+  rest of the family, in place of `PGPCHAT_*`.
+- The default server is `https://api.hidesay.com`.
+- Webhook deliveries carry the secret in `X-Hidesay-Bot-Api-Secret-Token`, and a refused one is
+  answered with `WWW-Authenticate: Hidesay-Secret-Token`.
+- `PGPCbotError` is `HidesayBotError`, and the loggers are `hidesay_bot.*`.

hidesay_bot-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing
+
+## Setting up
+
+```bash
+python -m venv .venv
+. .venv/bin/activate                 # Windows: .venv\Scripts\activate
+pip install -e . --group dev         # needs pip 25.1 or newer
+```
+
+## Before you open a pull request
+
+```bash
+ruff check src tests examples scripts
+ruff format --check src tests examples scripts
+mypy
+pytest
+```
+
+`mypy` runs in `strict` mode on `src/hidesay_bot`. Any warning during the tests is an error
+(`filterwarnings = error`): if a test expects a warning, it has to say so.
+
+### Tests that need more
+
+- **Integration** (`-m integration`): the tests that drive a real Hidesay server need a copy
+  of the server to start one, so they live with it and not in this repository. The marker stays
+  declared here, for a working copy that has both.
+- **Interoperability** (`-m interop`): they check the SDK against PGPainless 1.7.6, the phones'
+  library. You need Java 21 or newer and `HIDESAY_BOT_PGPAINLESS_CP` set to a classpath with
+  pgpainless-core 1.7.6, Bouncy Castle 1.80 (bcprov, bcpg, bcutil), slf4j-api, jsr305 and
+  kotlin-stdlib. The CI job in `.github/workflows/ci.yml` shows how to download them.
+
+Without those variables these tests are skipped, they don't fail.
+
+## How the code is organised
+
+- `src/hidesay_bot/_spec.py` describes each API operation once. `client.py` has the two shells,
+  async and blocking, with the same methods. A new method goes in both:
+  `tests/test_parity.py` checks that the signatures match.
+- The client-side checks mirror the server's own rules, so a request that passes them is not
+  refused for that reason. When the server changes a rule, change it here too, with a
+  test.
+- Everything that touches OpenPGP goes through `src/hidesay_bot/crypto/_lib.py`. A change there
+  needs the interoperability tests with PGPainless, not only the unit tests.
+- Comments explain why, not what. Code, comments and documentation are in English; keep the
+  documentation simple, for readers whose first language is not English.
+
+## Documentation
+
+The API reference is generated from the docstrings, so a docstring is documentation. Write it
+in Google style with reStructuredText markup, like the ones already there: a summary line,
+then `Args:`, `Returns:`, `Raises:`, `Attributes:` and `Example:` sections as needed. Names in
+single backticks become links (`Bot.send_message`); code and values go in double backticks.
+`tests/test_docs.py` checks that everything public has a docstring, that every parameter is
+described and that the `>>>` examples still run.
+
+Build the site with Sphinx:
+
+```bash
+pip install -e . --group docs
+sphinx-build -W --keep-going -n -b html docs docs/_build/html
+```
+
+then open `docs/_build/html/index.html`. `-n` reports every link that does not resolve and
+`-W` turns warnings into errors, as in the CI. To read one page without a browser:
+`python -m pydoc hidesay_bot.Bot`.
+
+The guides are Markdown pages in `docs/`. The examples in the documentation must work with the
+real code: if you change an API, update the docstrings, the pages and the scripts in
+`examples/` that use it.
+
+`docs/openapi.json` is an exact copy of the document the server publishes for its Bot API. When
+the server's spec changes, copy it again and run `python scripts/openapi_pages.py`: it rewrites
+`docs/openapi-reference/operations.md`, and stops if an operation has no SDK method. The CI checks
+that the page is up to date.
+
+## Releases
+
+1. update `src/hidesay_bot/_version.py` and `CHANGELOG.md`;
+2. create a `vX.Y.Z` tag;
+3. the `release.yml` workflow builds and checks the packages. Publishing to PyPI needs a manual
+   approval of the `pypi` environment.

hidesay_bot-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hidesay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hidesay_bot-0.2.0/PKG-INFO

@@ -0,0 +1,273 @@
+Metadata-Version: 2.4
+Name: hidesay-bot
+Version: 0.2.0
+Summary: Bots for Hidesay: the whole Bot API, end-to-end encryption included.
+Project-URL: Homepage, https://hidesay.com
+Project-URL: Source, https://github.com/vntcore/hidesay-bot
+Project-URL: Documentation, https://vntcore.github.io/hidesay-bot/
+Project-URL: Issues, https://github.com/vntcore/hidesay-bot/issues
+Project-URL: Changelog, https://github.com/vntcore/hidesay-bot/blob/main/CHANGELOG.md
+Author: Hidesay
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,bot,bot-api,chatbot,end-to-end-encryption,hidesay,openpgp,webhook
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx2<3,>=2.13.1
+Requires-Dist: pysequoia<0.2,>=0.1.35
+Requires-Dist: rpgp-py<0.21,>=0.20
+Provides-Extra: http2
+Requires-Dist: httpx2[http2]<3,>=2.13.1; extra == 'http2'
+Provides-Extra: webhook
+Requires-Dist: uvicorn>=0.30; extra == 'webhook'
+Description-Content-Type: text/markdown
+
+# hidesay-bot
+
+[![ci](https://github.com/vntcore/hidesay-bot/actions/workflows/ci.yml/badge.svg)](https://github.com/vntcore/hidesay-bot/actions/workflows/ci.yml)
+
+A Python library for writing bots for [Hidesay](https://hidesay.com), a messenger whose
+private chats are end-to-end encrypted with OpenPGP. It covers the whole Bot API, and it
+handles the encryption for you.
+
+**Documentation: <https://vntcore.github.io/hidesay-bot/>** - the guides and the whole API reference.
+
+```python
+from hidesay_bot import Bot
+
+bot = Bot()  # reads the token from HIDESAY_BOT_TOKEN
+
+
+@bot.command("start", description="Say hello")
+async def start(message):
+    await message.reply("Hello! Send me anything and I will repeat it.")
+
+
+@bot.on_message()
+async def echo(message):
+    await message.reply(f"You said: {message.text}")
+
+
+bot.run()
+```
+
+If the bot has a published OpenPGP key, its private chats are end-to-end encrypted. The same
+code still works: messages reach your handlers already decrypted, and replies are encrypted
+for the people who should read them. You don't change anything in the handlers.
+
+## What it does
+
+- **Every operation of the Bot API**, with typed models, as async calls (`AsyncClient`)
+  and as blocking calls (`Client`).
+- **A high-level bot** with handlers for messages, commands (`/start` and `/start@yourbot`),
+  button presses, edited and deleted messages, and changes to the bot's membership. Filters you
+  can combine, routers to split a bot into modules, middleware, and one place to handle errors.
+- **Automatic OpenPGP**: incoming messages are decrypted and their signatures checked;
+  replies are encrypted for every member of the chat and signed. A message that should be
+  encrypted is never sent in clear. Tested with real keys and messages from the phones'
+  library (PGPainless 1.7.6).
+- **Long polling and webhooks** with "at least once" delivery done right: no update is lost
+  when a handler fails, no update is confirmed to the server before it is safe, and a SQLite
+  queue survives restarts.
+- **Safe retries**: every send has a `sendId`, so a retry after a timeout never writes the
+  message twice. After a `429` the client waits as long as the server asks. A client-side rate
+  limiter uses the same algorithm as the server.
+- **Security**: the token never shows up in logs, exceptions or `repr`. Secrets can come from
+  environment variables or from files (Docker and Kubernetes secrets too). The webhook checks
+  its secret in constant time.
+
+## Install
+
+You need Python 3.11 or newer (tested up to 3.14). The OpenPGP engines come as prebuilt
+wheels for Linux and macOS (x86-64 and arm64) and for Windows (x86-64), so there is nothing
+to compile; anywhere else pip builds them and you need a Rust toolchain.
+
+```bash
+pip install hidesay-bot
+```
+
+From a clone of the repository, `pip install .`, or `pip install -e .` to work on the code.
+
+Optional extras: `hidesay-bot[webhook]` adds uvicorn to serve the webhook, `hidesay-bot[http2]` adds
+HTTP/2 support. Check that it works:
+
+```bash
+python -c "import hidesay_bot; print(hidesay_bot.__version__)"
+hidesay-bot --version
+```
+
+## Your first bot
+
+1. Create the bot in the app: Settings → Account → My bots, or write to `@bot`. Copy the
+   token when you see it: it is shown only once.
+2. Put it in an environment variable, not in your code:
+
+   ```bash
+   export HIDESAY_BOT_TOKEN="pgpbot_..."          # PowerShell: $env:HIDESAY_BOT_TOKEN="pgpbot_..."
+   export HIDESAY_API="https://api.hidesay.com"   # only if your server is a different one
+   ```
+
+3. Check the token: `hidesay-bot whoami`.
+4. Save the example at the top of this page as `bot.py`, run `python bot.py`, and write to your
+   bot from the app. Stop it with Ctrl+C: it finishes the messages it is working on first.
+
+## Commands and buttons
+
+```python
+from hidesay_bot import Bot, Button, InlineKeyboard
+
+bot = Bot()
+
+
+@bot.command("weather", description="Forecast for a town")
+async def weather(message, command):
+    town = command.args or "Rome"
+    keyboard = InlineKeyboard.build(
+        [Button.callback("Hourly", f"hourly:{town}"), Button.callback("Another town", "ask")],
+        [Button.link("On the web", "https://example.org/weather")],
+    )
+    await message.reply(f"{town}: sun, sun, rain.", markup=keyboard)
+
+
+@bot.on_callback_query(prefix="hourly:")
+async def hourly(query):
+    await query.answer("Here is the hourly view")
+    await query.edit_message(f"{query.data[7:]}: 14° at 10, 18° at 14.", markup=None)
+
+
+bot.run()
+```
+
+Commands registered with a `description` go into the app's command menu with
+`await bot.sync_commands()`.
+
+## An end-to-end encrypted bot
+
+```bash
+hidesay-bot keygen --name Weather --username weatherbot --out bot-key.asc --passphrase-env BOT_KEY_PASSPHRASE
+```
+
+```python
+import os
+from hidesay_bot import Bot
+
+bot = Bot(
+    pgp_private_key="bot-key.asc",
+    pgp_passphrase=os.environ["BOT_KEY_PASSPHRASE"],
+    publish_key=True,   # on the first run, publish the key: private chats become encrypted
+)
+
+
+@bot.on_message()
+async def echo(message):
+    # already decrypted; message.verification says if the sender's signature is valid
+    await message.reply(f"Got it, privately: {message.text}")
+
+
+bot.run()
+```
+
+Publishing the key cannot be undone through the API: only the bot's owner can switch the bot
+back to readable chats, from the console in the app. Read [the cryptography page][crypto]
+before you go to production.
+
+## Webhook with FastAPI
+
+```python
+import os
+from fastapi import FastAPI
+from hidesay_bot import Bot, SQLiteStorage
+
+bot = Bot(storage=SQLiteStorage("bot.db"))
+
+
+@bot.on_message()
+async def echo(message):
+    await message.reply(message.text or "...")
+
+
+webhook = bot.create_webhook_app(
+    secret=os.environ["WEBHOOK_SECRET"],
+    url="https://example.org/hidesay",   # registered with the server at start-up
+)
+app = FastAPI(lifespan=bot.lifespan)
+app.add_route("/hidesay", webhook, methods=["POST"])
+```
+
+Run it with `uvicorn app:app`. With `SQLiteStorage` every update is saved before the server
+gets its answer, and handled right after: a crash loses nothing.
+
+## Without asyncio
+
+```python
+from hidesay_bot import SyncBot
+
+bot = SyncBot()
+
+
+@bot.command("start")
+def start(message):
+    message.reply("Hello!")
+
+
+bot.run()
+```
+
+`SyncBot` has the same methods as `Bot`, without `await`. Handlers run in a pool of threads.
+For a script that only needs to send one message:
+
+```python
+from hidesay_bot import Client
+
+with Client() as api:
+    api.send_message(7781, "Last night's backup finished fine.")
+```
+
+## Documentation
+
+The site is at <https://vntcore.github.io/hidesay-bot/>: the guides, and the API reference built from the
+docstrings. It follows `main`.
+
+The same reference without a browser: `help(hidesay_bot.Bot)` in Python, or
+`python -m pydoc hidesay_bot.Bot` in a terminal. The pages are Markdown in [`docs/`][docs], and
+from a clone you can build the site yourself:
+
+```bash
+pip install -e . --group docs
+sphinx-build -b html docs docs/_build/html
+```
+
+Good places to start: [quick start][quickstart], [cryptography][crypto],
+[API coverage][coverage], [research and decisions][research]. Ready-to-run examples are in
+[`examples/`][examples].
+
+## Security
+
+See [SECURITY.md][security] for the threat model and for how to report a vulnerability. In
+short: keep the token and the private key out of your code and out of repositories. If the
+token leaks, `await bot.revoke_token()` burns it at once.
+
+## License
+
+MIT. The dependencies have their own licenses: httpx2 (BSD-3-Clause), pysequoia (Apache-2.0,
+with Sequoia PGP under LGPL-2.0-or-later inside its wheels), rpgp-py (MIT).
+
+[docs]: https://github.com/vntcore/hidesay-bot/tree/main/docs
+[examples]: https://github.com/vntcore/hidesay-bot/tree/main/examples
+[quickstart]: https://github.com/vntcore/hidesay-bot/blob/main/docs/getting-started/quickstart.md
+[crypto]: https://github.com/vntcore/hidesay-bot/blob/main/docs/CRYPTOGRAPHY.md
+[coverage]: https://github.com/vntcore/hidesay-bot/blob/main/docs/API_COVERAGE.md
+[research]: https://github.com/vntcore/hidesay-bot/blob/main/docs/RESEARCH.md
+[security]: https://github.com/vntcore/hidesay-bot/blob/main/SECURITY.md