yapper-bot 0.1.0__tar.gz

yapper_bot-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.env
+pypi.tkn
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/

yapper_bot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yapperpy contributors
+
+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.

yapper_bot-0.1.0/PKG-INFO

@@ -0,0 +1,280 @@
+Metadata-Version: 2.5
+Name: yapper-bot
+Version: 0.1.0
+Summary: Python bot framework and typed client for the Yapper Bot API
+Project-URL: Homepage, https://www.yapper.website/developers
+Project-URL: Documentation, https://www.yapper.website/developers/api
+Project-URL: Source, https://github.com/yapperpy/yapperpy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,bot,chat,discord,sdk,yapper
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+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 :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# yapperpy
+
+A Python package for the [Yapper](https://www.yapper.website) Bot API: a full bot framework with a
+typed REST client, sync and async, and **no runtime dependencies**.
+
+```bash
+pip install yapper-bot
+```
+
+The distribution is `yapper-bot`; the import name is `yapperpy`.
+
+Requires Python 3.10 or newer.
+
+## A bot in ten lines
+
+```python
+import yapperpy
+
+bot = yapperpy.Bot()  # token from YAPPER_BOT_TOKEN
+
+
+@bot.command("ping", "Is the bot alive?")
+def ping(msg):
+    msg.reply("pong")
+
+
+bot.run()
+```
+
+The same bot with asyncio:
+
+```python
+import asyncio
+import yapperpy
+
+bot = yapperpy.AsyncBot()
+
+
+@bot.command("ping", "Is the bot alive?")
+async def ping(msg):
+    await msg.reply("pong")
+
+
+asyncio.run(bot.run())
+```
+
+A callback may be a plain function or a coroutine function: the async runtime awaits whatever it is
+gets, so one cog works in both.
+
+## What a bot can do
+
+| Call | What it does |
+| --- | --- |
+| `@bot.command(name, description)` | Registers a command. People type `/name` or `!name`. |
+| `@bot.on(event)` | Listens for an event: `message`, `command`, `member_join`, `member_leave`, `reaction_add`, `reaction_remove`, `voice_join`, `voice_leave`, `interaction`, `test`, `ready`, `error`. |
+| `@bot.button("vote:")` | Handles clicks on buttons whose `custom_id` starts with `vote:`. A regular expression works too. |
+| `msg.reply(text)` | Answers the message, quoting it. `msg.say(text)` posts in the same channel without a quote. |
+| `msg.args`, `msg.argv` | The rest of the command line, and the same split on spaces. |
+| `i.reply()`, `i.ephemeral()`, `i.update()`, `i.ack()` | Answers a button click: a new message, one only the clicker sees, an edit of the clicked message, or nothing visible. |
+| `bot.add_cog(Cog)` | Groups commands, listeners and buttons in one class. |
+| `bot.load_extensions("cogs")` | Loads every `.py` file in a folder. `bot.unload_extension` and `bot.reload_extension` work while the bot runs. |
+| `bot.send(channel_id, text)` | Posts a message. |
+
+## Cogs
+
+A cog is a class with commands, listeners and buttons in it:
+
+```python
+# cogs/fun.py
+import yapperpy
+
+
+class Fun(yapperpy.Cog):
+    @yapperpy.command("joke", "Tell a joke")
+    async def joke(self, msg):
+        await msg.reply("I know a UDP joke, but you might not get it")
+
+    @yapperpy.listener("member_join")
+    async def hello(self, ev):
+        print(ev.username, "joined")
+
+    def check(self, msg):  # optional: return False to skip this cog
+        return True
+```
+
+```python
+# bot.py
+import yapperpy
+
+bot = yapperpy.AsyncBot()
+bot.load_extensions("cogs")
+asyncio.run(bot.run())
+```
+
+## The API client
+
+The framework is built on a plain API client you can use on its own.
+
+```python
+import yapperpy
+
+with yapperpy.Yapper("yb_...") as client:
+    print(client.bot.get().username)
+    for server in client.servers.list():
+        print(server.name, server.member_count)
+    for channel in client.channels.list(type="text"):
+        print(channel.name)
+    message = client.messages.send(channel.id, "hello", embeds=[yapperpy.Embed().title("Hi")])
+    client.messages.react(channel.id, message.id, "👍")
+```
+
+Every call returns a typed model: `BotProfile`, `User`, `Server`, `Channel`, `Category`, `Message`,
+`Member`, `MemberDetail`, `Role`, `Ban`, `Reaction`, `Command`, `Event`, `VoiceChannel`, `Image`,
+`Embed`, `ActionRow`, `Button`, `Ok`.
+
+Namespaces: `client.bot`, `client.events`, `client.servers`, `client.channels`, `client.messages`,
+`client.interactions`, `client.voice`, `client.users`.
+
+Anything the API does that this package does not cover yet is one call away:
+
+```python
+client.api("GET", "/servers")  # returns plain JSON
+await async_client.api("GET", "/servers")
+```
+
+## Events
+
+The bot long-polls `GET /events` and hands each event to the right listeners. The payload of a
+message event is a `MessageContext`, which has every field of the message plus `reply`, `say` and
+`author_mention`. Other events give you a typed payload: `MemberJoinPayload`, `MemberLeavePayload`,
+`ReactionPayload`, `InteractionPayload`, `VoicePayload`, `TestPayload`.
+
+The last event id is kept in `bot.last_event_id`, so a bot that restarts can pick up where it left
+off. Events are kept by Yapper for one day.
+
+## Buttons and embeds
+
+```python
+import yapperpy
+
+
+@bot.command("vote", "Pizza or not")
+def vote(msg):
+    msg.reply(
+        "Pizza tonight?",
+        components=[
+            yapperpy.row(
+                yapperpy.btn("Yes", "vote:yes", "success", emoji="🍕"),
+                yapperpy.btn("No", "vote:no", "danger"),
+                yapperpy.link_button("Menu", "https://example.com/menu"),
+            )
+        ],
+    )
+
+
+@bot.button("vote:")
+def on_vote(interaction):
+    interaction.ephemeral("You voted " + interaction.custom_id[5:])
+```
+
+A Components V2 layout, where the components are the whole message:
+
+```python
+import yapperpy
+
+bot.send_layout(
+    channel_id,
+    [
+        yapperpy.container(
+            "## Game night",
+            yapperpy.section("**Minecraft**", accessory=yapperpy.btn("Vote", "poll:mc", "primary")),
+            yapperpy.separator(),
+            yapperpy.gallery("https://example.com/a.png"),
+            accent="blue",
+        )
+    ],
+)
+```
+
+## Errors
+
+```
+YapperError
+  YapperValidationError      400
+  YapperAuthError            401
+  YapperPermissionError      403
+  YapperNotFoundError        404
+  YapperConflictError        409
+  YapperRateLimitError       429   .retry_after
+  YapperServiceError         503   .retry_after
+  YapperServerError          other 5xx
+  YapperConnectionError      the network failed
+  YapperTimeoutError         the request timed out
+```
+
+A 429 or a 503 with a `Retry-After` header is waited out and retried automatically. A 429 without
+one is raised right away, because waiting does not help. A failing command goes to the `error`
+listeners, or is printed with a traceback when there are none.
+
+## Configuration
+
+| Setting | How |
+| --- | --- |
+| Token | `YAPPER_BOT_TOKEN`, or `Yapper("yb_...")` |
+| Base URL | `Yapper(base_url=...)`, for a test server |
+| Prefixes | `Bot(prefixes=("/", "!"))` |
+| Bot messages | `Bot(ignore_bots=False)` to answer other bots too |
+| Retries | `Yapper(retry=RetryPolicy(attempts=5))` |
+
+## Development
+
+```bash
+python -m venv .venv
+.venv\Scripts\python.exe -m pip install --editable ".[dev]"
+.venv\Scripts\python.exe -m pytest
+.venv\Scripts\python.exe -m mypy
+.venv\Scripts\python.exe -m ruff check .
+```
+
+`start.bat` sets up the environment and runs `examples/echo_bot.py`.
+
+## Publishing
+
+`publish.bat` builds the wheel and the source archive, checks the metadata and uploads them.
+
+```bat
+publish.bat                  :: upload to PyPI
+publish.bat test             :: upload to TestPyPI instead
+publish.bat --dry-run        :: build and check everything, do not upload
+```
+
+The token comes from a file called `pypi.tkn` in this folder. One line, the whole token:
+
+```
+pypi-AgEIcHlwaS5vcmMFAKEtoken1234567890abcdef
+```
+
+`pypi.tkn` is in `.gitignore` and is never uploaded. If you would rather not keep a file around,
+set the `PYPI_TOKEN` environment variable instead.
+
+The token needs the `pypi` scope for the project `yapper-bot`. The script refuses to upload a
+version that is already on the index, so bump `__version__` in `src/yapperpy/_version.py` first.
+
+## Links
+
+- API reference: https://www.yapper.website/developers/api
+- OpenAPI file: https://www.yapper.website/openapi.json
+- Developer guide: https://www.yapper.website/developers
+
+## License
+
+MIT

yapper_bot-0.1.0/PLAN.md

@@ -0,0 +1,264 @@
+# yapperpy - plan
+
+A Python package for the Yapper Bot API: a complete bot framework with a typed REST client,
+zero runtime dependencies, sync and async flavours sharing one core.
+
+Source of truth: https://www.yapper.website/developers/api and https://www.yapper.website/openapi.json
+(OpenAPI 3.1, 33 paths, 49 operations, 23 schemas). Reference SDK for behaviour parity:
+https://www.yapper.website/sdk/yapper.py
+
+## Decisions
+
+| Topic | Decision | Why |
+| --- | --- | --- |
+| Scope | Full bot framework: REST client + commands + events + cogs + extensions | A library, not a script; replaces the single-file SDK with something installable and typed |
+| Sync / async | Both, one shared core | Bot authors use either; the framework detects coroutine callbacks and awaits them in async mode |
+| Dependencies | Zero runtime dependencies (stdlib only) | `pip install yapper-bot` never breaks a user's environment; matches the official SDK's promise |
+| Distribution | `yapper-bot` | `yapper` is taken on PyPI by an unrelated Astro docstring parser, and PyPI rejects `yapperpy` and `py-yapper` as too similar to it |
+| Import name | `yapperpy` | The official SDK's file is literally `yapper.py`; no shadowing, no confusion |
+| Python | 3.10+ | `dataclass(slots=True)`, `X | Y` at runtime, `match` statements |
+| Models | stdlib dataclasses, explicit parsers | No validation dependency; unknown fields ignored for forward compatibility |
+
+## Layout
+
+```
+py-yapper/
+  pyproject.toml            hatchling, src layout, no runtime deps
+  README.md  LICENSE (MIT)  PLAN.md
+  start.bat                 runs the example bot (project requirement: runnable entry point)
+  examples/
+    echo_bot.py             minimal bot: command, listener, button, embed
+    async_bot.py            the same bot on the async runtime
+    cogs_bot.py             loads a folder of cogs
+    cogs/fun.py  cogs/moderation.py
+  src/yapperpy/
+    __init__.py             public exports
+    __main__.py             python -m yapperpy -> prints the bot profile of YAPPER_BOT_TOKEN
+    errors.py               exception hierarchy
+    enums.py                ChannelType, BotStatus, ButtonStyle, CallbackType, EventType
+    models.py               typed models for the 23 schemas
+    event_models.py         typed payloads for the 9 event types
+    endpoints.py            Request spec + 52 build_* functions (single source of truth)
+    retry.py                pure retry policy (status, headers, attempt) -> decision
+    client.py               Yapper - sync REST client
+    aio_client.py           AsyncYapper - async REST client
+    _core.py                request preparation and error mapping
+    _http/
+      __init__.py
+      base.py               URL building, header building, body encoding, response parsing
+      sync.py               SyncTransport: http.client, keep-alive, connection reuse
+      aio.py                AsyncTransport: asyncio.open_connection, keep-alive
+    registry.py             command, listener and button registries
+    commands.py             (folded into registry.py)
+    events.py               EventStream: long-poll loop with backoff (sync + async)
+    cogs.py                 Cog base class, CogManager, extension loading
+    context.py              MessageContext and InteractionContext
+    framework.py            the shared bot base: registration, dispatch helpers
+    bot.py                  Bot: sync runtime
+    aio_bot.py              AsyncBot: async runtime
+    components.py           button/row builders + Components V2 layout parts
+    embeds.py               Embed builder
+    py.typed
+  tests/
+    conftest.py             fake transports
+    test_models.py  test_endpoints.py  test_client.py  test_async.py
+    test_bot.py  test_components.py  test_transport.py
+```
+
+## Architecture
+
+Five layers. Each layer depends only on the ones above it in this list.
+
+**1. Core (pure, no I/O).**
+`endpoints.py` holds one `Request` spec per operation: method, path template, query params, JSON
+body, response model, parser. Every path, body key and response unwrap key exists exactly once,
+here. The request type is generic in the result (`Request[Message]`), so the client methods keep
+real return types instead of `Any`. `models.py` holds the dataclasses and their `from_dict`
+parsers. `retry.py` is a pure function of `(status, headers, body, attempt)` returning
+retry-or-raise plus a delay.
+
+**2. Transport.**
+Both transports implement the same interface: build a request, get a `RawResponse`
+(status, headers, body bytes). The sync one uses `http.client.HTTPSConnection` with keep-alive
+and reconnects on a dropped socket. The async one speaks HTTP/1.1 over `asyncio.open_connection`
+with keep-alive. Both are injectable, so tests need no network.
+
+**3. Clients.**
+`Yapper` and `AsyncYapper` expose the same namespaces and the same method names. The request
+building, parsing, error mapping and retry loop live in shared helpers; the sync and async
+classes differ only in `await` and `time.sleep` vs `asyncio.sleep`. Method bodies are one-line
+delegations to the shared endpoint builders, which keeps the public types honest
+(`async def send(...) -> Message` really returns a coroutine of `Message`, not `Any`).
+
+**4. Framework.**
+Command registry, listener registry, button registry, cog manager, extension loader, event
+stream. The registries are framework-agnostic data structures, shared by both runtimes.
+
+**5. Runtime.**
+`Bot` and `AsyncBot` wire the registries to a client and an event stream. A callback that
+returns a coroutine is awaited in async mode and called normally in sync mode, so a cog can be
+written once and used in either runtime.
+
+## Public API
+
+### Clients
+
+```python
+client = yapperpy.Yapper(token)  # or YAPPER_BOT_TOKEN env var
+client = yapperpy.AsyncYapper(token)
+client = yapperpy.Yapper(token, transport=my_transport)  # injection point for tests
+```
+
+Namespaces on both clients:
+
+| Namespace | Methods |
+| --- | --- |
+| `client.bot` | `get`, `update(display_name, bio)`, `set_avatar`, `remove_avatar`, `set_banner`, `remove_banner`, `set_status`, `commands`, `set_commands` |
+| `client.events` | `fetch(after, wait, max_age)`, `stream(...)` |
+| `client.servers` | `list`, `get`, `roles`, `members`, `member_pages`, `member`, `set_nickname`, `add_role`, `remove_role`, `kick`, `bans`, `ban`, `unban`, `timeout` |
+| `client.channels` | `list`, `get`, `create`, `edit`, `delete`, `categories`, `create_category`, `rename_category`, `delete_category` |
+| `client.messages` | `send`, `get`, `edit`, `delete`, `pin`, `unpin`, `react`, `unreact`, `reactions`, `bulk_delete`, `history`, `send_layout`, `edit_layout` |
+| `client.interactions` | `callback(id, token, type, ...)` |
+| `client.voice` | `state`, `move`, `disconnect` |
+| `client.users` | `get`, `dm` |
+
+Escape hatch for anything undocumented: `client.api("GET", "/servers")` / `await client.api(...)`.
+
+Every method returns a typed model: `BotProfile`, `User`, `Server`, `Channel`, `Category`,
+`Message`, `Member`, `MemberDetail`, `Role`, `Ban`, `Reaction`, `Command`, `Event`,
+`VoiceChannel`, `Image`, `Embed`, `ActionRow`, `Button`, `LayoutComponent`, `Ok`.
+
+### Bot framework
+
+```python
+bot = yapperpy.Bot()  # or yapperpy.AsyncBot()
+
+
+@bot.command("ping", "Is the bot alive?")
+def ping(msg):
+    msg.reply("pong")  # msg.args, msg.argv, msg.say(), msg.author_mention
+
+
+@bot.on("member_join")
+def welcome(ev):
+    print(ev.username, "joined")
+
+
+@bot.button("vote:")  # custom_ids starting with "vote:"
+def vote(i):
+    i.ephemeral("You picked " + i.custom_id[5:])
+
+
+bot.load_extensions("cogs")
+bot.run()
+```
+
+The async runtime is identical, with `async def` callbacks and `await bot.run()`.
+
+Features: slash commands registered with the API (`PUT /commands`), prefix commands
+(`/`, `!` by default, longest prefix wins), `command` / `args` / `argv` parsing, listeners for
+all 9 event types plus `ready` and `error`, button handlers matched by prefix or regex,
+interactions with `reply` / `ephemeral` / `update` / `ack`, cogs as classes or setup functions,
+extensions loaded from a module or a file path with hot reload, Components V2 layouts, embeds.
+
+## Error handling
+
+```
+YapperError
+  YapperValidationError      400
+  YapperAuthError            401
+  YapperPermissionError      403
+  YapperNotFoundError        404
+  YapperConflictError        409
+  YapperRateLimitError       429   .retry_after
+  YapperServiceError         503   .retry_after
+  YapperServerError          5xx
+  YapperConnectionError      network failure
+  YapperTimeoutError         request timed out
+```
+
+Every error carries `.status`, `.message` and the parsed body. Rate-limit and service errors
+carry `.retry_after` in seconds.
+
+Retry policy: a 429 or 503 with `Retry-After` waits that long and retries (jittered); a 429
+without `Retry-After` fails immediately, because waiting does not help; 502/504 retry with
+exponential backoff; connection failures before the request is sent retry with backoff; 4xx
+never retries. Retries are capped (3 attempts, 60 s ceiling) and configurable.
+
+## Models
+
+Dataclasses with `slots=True`, explicit `from_dict` parsers, unknown fields ignored.
+Two conveniences the API needs:
+
+- `User.avatar_url` and friends are computed from the path the API returns:
+  `files.yapper.website/<bucket>/<path>`, or `www.yapper.website<path>` for built-in images
+  that start with `/`. `None` when there is no picture.
+- `Channel.type` and `Channel.kind` are the same value; the model exposes one and aliases the other.
+- `GET /channels/{id}/messages` returns authors separately; they are attached to the messages.
+
+## Testing and verification
+
+- `pytest` for the suite (dev dependency only; the installed package stays dependency-free).
+- Model parsing: one test per schema, including null and missing fields.
+- Endpoint builders: one test per operation asserting method, path, query, body and unwrap key.
+- Transport end-to-end: a local `http.server` on a random port, exercised by both transports,
+  covering keep-alive, chunked responses, redirects, error statuses and large bodies.
+- Retry: a fake transport that returns 429/503/5xx in sequence; assert the delays and the
+  final exception, and that a 429 without `Retry-After` does not retry.
+- Framework: commands, prefixes, argv, cog add/remove, extension load/unload/reload,
+  button prefix and regex matching, interaction answers.
+- Bot runtime: drive a fake event stream and assert the right callbacks fire with the right
+  payloads, in both sync and async mode.
+- Static checks: `ruff check`, `ruff format --check`, `mypy --strict`.
+- Packaging: `python -m build` produces a wheel and an sdist; the wheel is installed into a
+  throwaway venv and imported to prove it works with no dependencies installed.
+
+## Milestones
+
+1. Scaffolding: `pyproject.toml`, src layout, `py.typed`, `LICENSE`, `start.bat`.
+2. Core: `errors`, `enums`, `models`, `event_models`, `endpoints`, `retry`.
+3. Transports: `_http/base`, `_http/sync`, `_http/aio`.
+4. Clients: `client`, `aio_client`, pagination helpers, `api()` escape hatch.
+5. Framework: `registry`, `events`, `cogs`, `components`, `embeds`, `context`, `framework`.
+6. Runtime: `bot`, `aio_bot`.
+7. Tests, examples, README, verification pass.
+
+All seven are done.
+
+## Status
+
+Built and verified on 21 October 2026.
+
+- 149 tests pass, against the source tree and against the installed wheel.
+- `mypy --strict` is clean over the 25 source files.
+- `ruff check` and `ruff format --check` are clean.
+- The wheel installs into an empty virtualenv with no third-party package beside it, and the
+  whole suite passes there too.
+- Every operation in the OpenAPI file has a builder and a client method: 52 builders cover the
+  49 documented operations, because two responses are split for convenience (channels and
+  categories come from one call) and two Components V2 helpers were added on top.
+
+Two design points changed while building:
+
+- The bot profile namespace is `client.bot`, not `client.me`, because `me` reads as a value
+  rather than a group of calls.
+- The request type is generic in the result (`Request[Message]`), so the public methods return
+  real models instead of `Any`. The cost is one type alias per list-shaped response.
+
+## Risks and mitigations
+
+- Hand-rolled async HTTP: mitigated by testing against a real local server, and by keeping the
+  async transport to the subset Yapper uses (Content-Length and chunked bodies, keep-alive).
+- Two clients drifting apart: mitigated by generating both from the same endpoint builders and
+  by a test that asserts the two clients expose identical method names and signatures.
+- Zero dependencies means no connection-pooling library: mitigated by implementing keep-alive
+  on top of `http.client` and `asyncio` streams, which is enough for a bot's request rate.
+- The API keeps events for one day only: the framework stores the last event id and can be told
+  to resume from a saved id after a restart.
+
+## Out of scope
+
+- OAuth2 "Login with Yapper" (a separate flow with its own client id and secret).
+- Channel webhooks (a different URL scheme and error format).
+- Bot hosting: that runs Node, so it cannot host this package.
+- A voice gateway: bots do not join calls; the API only reports and moves members.