kryncord 0.1.0b1__tar.gz

kryncord-0.1.0b1/.gitignore

@@ -0,0 +1,58 @@
+# Ambientes virtuais
+.venv/
+venv/
+env/
+ENV/
+
+# Bytecode e caches
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.pytest_history/
+
+# Build
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+pip-wheel-metadata/
+
+# Editores
+.idea/
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json
+*.swp
+*.swo
+*~
+
+# Sistema
+.DS_Store
+Thumbs.db
+
+# Segredos — nunca commitar
+.env
+.env.*
+!.env.example
+*.token
+secrets.*
+config.local.*
+
+# Cobertura
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Fora do repositório — material local, não é parte da biblioteca
+# (o gitignore não aceita comentário no fim da linha: o `#` viraria
+# parte do padrão e nada seria ignorado)
+base/
+.freebuff/
+ideias/
+bot testes/

kryncord-0.1.0b1/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+Formato em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/),
+numeração em [SemVer](https://semver.org/lang/pt-BR/).
+
+## [Unreleased]
+
+## [0.1.0b1] — 2026-10-16
+
+Primeira versão beta pública. O núcleo está de pé — REST e Gateway
+próprios, sem dependência de `discord.py`.
+
+### Adicionado
+
+- `Client` e `Config` — ciclo de vida assíncrono, `async with` fecha a
+  conexão sozinho.
+- Camada REST própria (`client.api`) com rate limit, retries e multipart.
+- Camada Gateway: Identify, heartbeat, ACK, reconexão e retomada de
+  sessão.
+- Payloads entregues **interpretados**: `Message`, `Guild`, `Ready` e
+  companhia em vez de `dict`.
+- Roteamento de comandos, interações e responders.
+- Cache opcional por política (`CachePolicy`) com estatísticas de hit
+  rate.
+- Tipagem completa (`py.typed`) e `mypy --strict` no código inteiro.
+
+### Conhecido
+
+- O Discord não manda `guild_id` nos canais do `GUILD_CREATE` — a
+  biblioteca preenche a visão da guild por conta própria (verificado ao
+  vivo: 24/24 canais sem o campo).
+- `MESSAGE_CONTENT` é privileged: precisa ser ligado no portal do
+  Discord antes de pedir o intent.
+
+[Unreleased]: https://github.com/KrynCord/kryncord/compare/v0.1.0b1...HEAD
+[0.1.0b1]: https://github.com/KrynCord/kryncord/releases/tag/v0.1.0b1

kryncord-0.1.0b1/LICENSE

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

kryncord-0.1.0b1/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.5
+Name: kryncord
+Version: 0.1.0b1
+Summary: Async-first Discord API library for Python
+Project-URL: Homepage, https://github.com/KrynCord/kryncord
+Project-URL: Repository, https://github.com/KrynCord/kryncord
+Project-URL: Documentation, https://github.com/KrynCord/kryncord#readme
+Project-URL: Issues, https://github.com/KrynCord/kryncord/issues
+Project-URL: Changelog, https://github.com/KrynCord/kryncord/blob/main/CHANGELOG.md
+Author: kruldevb
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,async,bot,discord,gateway,rest
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+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: Topic :: Communications :: Chat
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: websockets<18,>=17.2
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# KrynCord
+
+Biblioteca assíncrona para criar bots Discord em Python, com implementação
+própria das camadas REST e Gateway.
+
+## Objetivos
+
+- API async-first
+- REST e Gateway independentes
+- Roteamento de comandos e interações
+- Cache opcional
+- Tipagem e validação
+- Testes e benchmarks
+- Sem dependência de discord.py ou forks
+
+## Instalação
+
+```bash
+pip install kryncord
+```
+
+Requer Python 3.11+.
+
+## Uso
+
+```python
+import asyncio
+import os
+
+from kryncord import Client, Config, Intents, Message
+
+
+async def main() -> None:
+    config = Config(token=os.environ["DISCORD_TOKEN"], intents=Intents.default())
+
+    async with Client(config) as client:
+
+        @client.on("message_create")
+        async def responde(message: Message) -> None:
+            if message.content == "!ping":
+                # `reply` aceita a própria mensagem — o canal sai de lá,
+                # e o `message_reference` é montado sozinho.
+                await client.api.messages.reply(message, "pong")
+
+        await client.start()
+        await asyncio.Event().wait()  # fica no ar
+
+
+asyncio.run(main())
+```
+
+O handler recebe o payload **já interpretado** — um `Message`, não um
+`dict`. `message.content` é `None` quando o Discord não mandou texto, e
+não `""`; `message.author` é `None` quando não veio autor. Campo ausente
+nunca é preenchido com default, porque ausente e default são coisas
+diferentes.
+
+O nome do evento aceita as duas formas — `"message_create"` e
+`"MESSAGE_CREATE"` chegam ao mesmo handler. E os métodos da API aceitam
+ID ou objeto: `send(123, ...)`, `send("123", ...)`,
+`send(channel, ...)` e `send(message, ...)` são o mesmo destino.
+
+O `api/` é alcançado por `client.api`, e não por `message.reply()` — os
+modelos são dados puros, sem referência a runtime. Ver
+[0007](docs/decisions/0007-api-layer.md) para o porquê.
+
+## Desenvolvimento
+
+```bash
+python -m pip install -e ".[dev]"
+pytest
+ruff check src tests
+ruff format --check src tests
+mypy src/kryncord
+```
+
+## Status
+
+**Fase 3 — Core.** O bot recebe payload tipado e consegue responder.
+`models/` traz `User`, `Message`, `Channel`, `Guild`, `Member`,
+`Attachment`, `Role`, `Ban`, `Webhook`, `ApplicationCommand`,
+`Interaction`, `Ready` e os `Partial*` para o que o Discord entrega
+incompletos de propósito. `events/` converte o payload e decide a
+política de execução — sequencial, exceção isolada, cancelamento
+propaga.
+
+`api/` é o vocabulário por recurso sobre a mecânica REST da Fase 1 —
+**70 métodos em 9 módulos** (`messages`, `channels`, `members`,
+`roles`, `webhooks`, `applications`, `interactions`, `guilds`,
+`users`) — e o `Client` liga as duas.
+
+`cache/` + `state/` dão ao bot memória local: `client.cache`, **ligada
+por padrão**, guarda guilds, channels, roles e users — `members` e
+`messages` são opt-in por serem os que crescem com o servidor. Remoção
+híbrida (eventos invalidam o que o gateway anuncia; LRU com teto guarda
+o que não tem evento de remoção) e o evento é aplicado **antes** dos
+handlers rodarem, senão todo handler leria o estado do evento
+anterior.
+
+1516 testes passando. `ruff check`, `ruff format --check` e `mypy` limpos.
+
+Fase 4 entrou em andamento pela metade dos registros de decisão —
+`0010`–`0024` fecham a superfície inteira (construtor, registry,
+contextos, rota, conversores, componentes, máquina de estados,
+middleware, sync, bootstrap, eventos, autocomplete, context menus,
+paridade com o discord.js e o bloco de componentes), e cada escolha
+passou por um conselho de 22 perfis com veredito e divergência
+registrados em `docs/decisions/`. Já em código: o `permissions.py` +
+as três `Options` no `Config`, o `commands/` inteiro (option,
+definition, validation, instance, registry, context, sync,
+autocomplete), a máquina de estados de interação com a superfície do
+discord.js (`update`, `defer_update`, `fetch_reply`, `launch_activity`,
+`await_responder`), os 17 predicados `is_*()` no modelo, o `responders/`
+inteiro (ids, patterns, router, converters, params, context, registry,
+decorators, dispatch) e o `components/` inteiro (buttons, selects,
+inputs, uploads, choices, rows, displays, modals, colors, validation)
+com os embeds e a normalização que serializa no `api/`. Falta
+`events/`, middleware como bloco próprio e o `bootstrap`.
+
+| Fase | Conteúdo | Status |
+|---|---|---|
+| 0 | Pacote, erros, fundação, toolchain, CI | ✅ |
+| 1 | REST: rotas, rate limits, buckets | ✅ |
+| 2 | Gateway: connect, identify, heartbeat, resume | ✅ |
+| 3 | Core: `Client`, `api/`, `models/`, dispatcher, `cache/`, `state/` | ✅ |
+| 4 | Interações: commands, responders, components | 🔶 api/ |
+| 5 | Benchmarks do cache | ⬜ |
+
+## Estrutura
+
+```text
+src/kryncord/       pacote público
+  client.py         fachada e ciclo de vida
+  config.py         Config, HTTPConfig, GatewayConfig (frozen)
+  intents.py        bits de intent + validação privileged
+  enums.py          opcodes, close codes, permissões
+  errors.py         hierarquia de exceções
+  logging.py        namespace kryncord + redact()
+  lifecycle.py      tasks supervisionadas, encerramento limpo
+  <pacote>/         api, gateway, http, rest, interactions,
+                    responders, commands, components, events,
+                    models, builders, cache, state, discovery,
+                    voice, internal
+tests/unit/         testes sem rede
+tests/integration/  testes com transportes simulados
+docs/decisions/     registros de decisão de arquitetura
+ideias/             design da API de alto nível (referência)
+base/discord.js/    referência do discord.js (não é código do projeto)
+```
+
+Os pacotes de cada fase existem já com `__init__.py` documentando a
+responsabilidade. Os arquivos de módulo entram quando tiverem testes e
+uso claro — conforme o fim do `docs/internals/architecture.md`.
+
+## Verificação
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m ruff check src tests
+python -m ruff format --check src tests
+python -m mypy
+```
+
+## Decisões
+
+- [0001 — Transporte HTTP: httpx](docs/decisions/0001-http-transport.md)
+- [0002 — Transporte WebSocket: websockets](docs/decisions/0002-websocket-transport.md)
+- [0003 — Modelos de dados: dataclasses](docs/decisions/0003-data-models.md)
+- [0004 — Ordem de construção: REST → Gateway](docs/decisions/0004-build-order.md)
+- [0005 — Reconexão do Gateway: classificação de close code](docs/decisions/0005-gateway-reconnect.md)
+- [0006 — Eventos: payload tipado e política de dispatch](docs/decisions/0006-event-dispatch.md)
+- [0007 — Camada `api/`: vocabulário sobre a mecânica REST](docs/decisions/0007-api-layer.md)
+
+## Licença
+
+MIT

kryncord-0.1.0b1/README.md

@@ -0,0 +1,177 @@
+# KrynCord
+
+Biblioteca assíncrona para criar bots Discord em Python, com implementação
+própria das camadas REST e Gateway.
+
+## Objetivos
+
+- API async-first
+- REST e Gateway independentes
+- Roteamento de comandos e interações
+- Cache opcional
+- Tipagem e validação
+- Testes e benchmarks
+- Sem dependência de discord.py ou forks
+
+## Instalação
+
+```bash
+pip install kryncord
+```
+
+Requer Python 3.11+.
+
+## Uso
+
+```python
+import asyncio
+import os
+
+from kryncord import Client, Config, Intents, Message
+
+
+async def main() -> None:
+    config = Config(token=os.environ["DISCORD_TOKEN"], intents=Intents.default())
+
+    async with Client(config) as client:
+
+        @client.on("message_create")
+        async def responde(message: Message) -> None:
+            if message.content == "!ping":
+                # `reply` aceita a própria mensagem — o canal sai de lá,
+                # e o `message_reference` é montado sozinho.
+                await client.api.messages.reply(message, "pong")
+
+        await client.start()
+        await asyncio.Event().wait()  # fica no ar
+
+
+asyncio.run(main())
+```
+
+O handler recebe o payload **já interpretado** — um `Message`, não um
+`dict`. `message.content` é `None` quando o Discord não mandou texto, e
+não `""`; `message.author` é `None` quando não veio autor. Campo ausente
+nunca é preenchido com default, porque ausente e default são coisas
+diferentes.
+
+O nome do evento aceita as duas formas — `"message_create"` e
+`"MESSAGE_CREATE"` chegam ao mesmo handler. E os métodos da API aceitam
+ID ou objeto: `send(123, ...)`, `send("123", ...)`,
+`send(channel, ...)` e `send(message, ...)` são o mesmo destino.
+
+O `api/` é alcançado por `client.api`, e não por `message.reply()` — os
+modelos são dados puros, sem referência a runtime. Ver
+[0007](docs/decisions/0007-api-layer.md) para o porquê.
+
+## Desenvolvimento
+
+```bash
+python -m pip install -e ".[dev]"
+pytest
+ruff check src tests
+ruff format --check src tests
+mypy src/kryncord
+```
+
+## Status
+
+**Fase 3 — Core.** O bot recebe payload tipado e consegue responder.
+`models/` traz `User`, `Message`, `Channel`, `Guild`, `Member`,
+`Attachment`, `Role`, `Ban`, `Webhook`, `ApplicationCommand`,
+`Interaction`, `Ready` e os `Partial*` para o que o Discord entrega
+incompletos de propósito. `events/` converte o payload e decide a
+política de execução — sequencial, exceção isolada, cancelamento
+propaga.
+
+`api/` é o vocabulário por recurso sobre a mecânica REST da Fase 1 —
+**70 métodos em 9 módulos** (`messages`, `channels`, `members`,
+`roles`, `webhooks`, `applications`, `interactions`, `guilds`,
+`users`) — e o `Client` liga as duas.
+
+`cache/` + `state/` dão ao bot memória local: `client.cache`, **ligada
+por padrão**, guarda guilds, channels, roles e users — `members` e
+`messages` são opt-in por serem os que crescem com o servidor. Remoção
+híbrida (eventos invalidam o que o gateway anuncia; LRU com teto guarda
+o que não tem evento de remoção) e o evento é aplicado **antes** dos
+handlers rodarem, senão todo handler leria o estado do evento
+anterior.
+
+1516 testes passando. `ruff check`, `ruff format --check` e `mypy` limpos.
+
+Fase 4 entrou em andamento pela metade dos registros de decisão —
+`0010`–`0024` fecham a superfície inteira (construtor, registry,
+contextos, rota, conversores, componentes, máquina de estados,
+middleware, sync, bootstrap, eventos, autocomplete, context menus,
+paridade com o discord.js e o bloco de componentes), e cada escolha
+passou por um conselho de 22 perfis com veredito e divergência
+registrados em `docs/decisions/`. Já em código: o `permissions.py` +
+as três `Options` no `Config`, o `commands/` inteiro (option,
+definition, validation, instance, registry, context, sync,
+autocomplete), a máquina de estados de interação com a superfície do
+discord.js (`update`, `defer_update`, `fetch_reply`, `launch_activity`,
+`await_responder`), os 17 predicados `is_*()` no modelo, o `responders/`
+inteiro (ids, patterns, router, converters, params, context, registry,
+decorators, dispatch) e o `components/` inteiro (buttons, selects,
+inputs, uploads, choices, rows, displays, modals, colors, validation)
+com os embeds e a normalização que serializa no `api/`. Falta
+`events/`, middleware como bloco próprio e o `bootstrap`.
+
+| Fase | Conteúdo | Status |
+|---|---|---|
+| 0 | Pacote, erros, fundação, toolchain, CI | ✅ |
+| 1 | REST: rotas, rate limits, buckets | ✅ |
+| 2 | Gateway: connect, identify, heartbeat, resume | ✅ |
+| 3 | Core: `Client`, `api/`, `models/`, dispatcher, `cache/`, `state/` | ✅ |
+| 4 | Interações: commands, responders, components | 🔶 api/ |
+| 5 | Benchmarks do cache | ⬜ |
+
+## Estrutura
+
+```text
+src/kryncord/       pacote público
+  client.py         fachada e ciclo de vida
+  config.py         Config, HTTPConfig, GatewayConfig (frozen)
+  intents.py        bits de intent + validação privileged
+  enums.py          opcodes, close codes, permissões
+  errors.py         hierarquia de exceções
+  logging.py        namespace kryncord + redact()
+  lifecycle.py      tasks supervisionadas, encerramento limpo
+  <pacote>/         api, gateway, http, rest, interactions,
+                    responders, commands, components, events,
+                    models, builders, cache, state, discovery,
+                    voice, internal
+tests/unit/         testes sem rede
+tests/integration/  testes com transportes simulados
+docs/decisions/     registros de decisão de arquitetura
+ideias/             design da API de alto nível (referência)
+base/discord.js/    referência do discord.js (não é código do projeto)
+```
+
+Os pacotes de cada fase existem já com `__init__.py` documentando a
+responsabilidade. Os arquivos de módulo entram quando tiverem testes e
+uso claro — conforme o fim do `docs/internals/architecture.md`.
+
+## Verificação
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m ruff check src tests
+python -m ruff format --check src tests
+python -m mypy
+```
+
+## Decisões
+
+- [0001 — Transporte HTTP: httpx](docs/decisions/0001-http-transport.md)
+- [0002 — Transporte WebSocket: websockets](docs/decisions/0002-websocket-transport.md)
+- [0003 — Modelos de dados: dataclasses](docs/decisions/0003-data-models.md)
+- [0004 — Ordem de construção: REST → Gateway](docs/decisions/0004-build-order.md)
+- [0005 — Reconexão do Gateway: classificação de close code](docs/decisions/0005-gateway-reconnect.md)
+- [0006 — Eventos: payload tipado e política de dispatch](docs/decisions/0006-event-dispatch.md)
+- [0007 — Camada `api/`: vocabulário sobre a mecânica REST](docs/decisions/0007-api-layer.md)
+
+## Licença
+
+MIT

kryncord-0.1.0b1/docs/README.md

@@ -0,0 +1,38 @@
+# Documentação
+
+O que cada pasta é, e quando você abre cada uma.
+
+| Pasta | Abra quando… |
+|---|---|
+| [`api/`](api/) | Quiser saber como a superfície pública se comporta — as regras de negócio, não o código. |
+| [`decisions/`](decisions/) | Quiser saber **por que** o código é assim. ADRs numerados, um por escolha. |
+| [`guides/`](guides/) | Quiser executar um procedimento passo a passo. |
+| [`internals/`](internals/) | Quiser ver o desenho das camadas e o plano original. |
+| [`reference/`](reference/) | Quiser o material externo que serviu de inspiração. |
+
+## Ordem de leitura para quem chega agora
+
+1. [`internals/initial-decisions.md`](internals/initial-decisions.md) — as
+   dez decisões que definem o projeto, em onze linhas.
+2. [`internals/architecture.md`](internals/architecture.md) — o desenho
+   completo: camadas, módulos e limites.
+3. [`decisions/`](decisions/) — na ordem dos números. Cada ADR explica o
+   que foi considerado, o que foi escolhido e o que foi descartado. Um
+   ADR **não é atualizado** quando a decisão muda: nasce um novo com
+   número maior, e o antigo fica como registro.
+
+## Duas distinções que a documentação inteira repete
+
+**Ausente ≠ default.** Campo que o Discord não mandou chega `None`, e
+nunca é preenchido com um valor de convenção. `""` e `None` não são a
+mesma coisa, e um canal sem `rate_limit_per_user` não é um canal com
+`rate_limit_per_user = 0`.
+
+**REST ≠ Gateway.** São camadas independentes: dá para usar `client.api`
+sem abrir o socket, e o Gateway fica vivo mesmo se o REST falhar.
+
+## Publicar
+
+O passo a passo de publicação — incluindo TestPyPI, Trusted Publishing e
+por que `pip install --pre` é obrigatório para beta — está em
+[`guides/publication.md`](guides/publication.md).