aiowapy 0.1.0__tar.gz

aiowapy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --group dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy src
+      - run: uv run pytest

aiowapy-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,19 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths: ["docs/**", "mkdocs.yml", "src/**"]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync --group docs
+      - run: uv run mkdocs gh-deploy --force

aiowapy-0.1.0/.github/workflows/workflow.yml

@@ -0,0 +1,34 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uvx twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/aiowapy
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

aiowapy-0.1.0/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.venv/
+venv/
+
+# Tooling caches
+.pytest_cache/
+.hypothesis/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+node_modules/
+
+# Secrets / runtime artifacts
+*.session
+*.session-journal
+*.session-wal
+*.session-shm
+.env
+.env.*
+!.env.example
+
+# Captured traffic (never commit)
+*.har
+*.har.gz
+*.pcap
+*.pcapng
+*.mitm
+keys.log
+/flows*
+
+# Local-only debugging tools (kept on disk, never committed)
+/tools/capture/
+
+# Local notes and design docs (never published)
+/notes/
+
+# Local scratch
+/tmp/
+scratch/
+
+# Built docs
+/site/

aiowapy-0.1.0/AGENTS.md

@@ -0,0 +1,22 @@
+# Agent notes
+
+## Code review
+
+When the user asks to review the changes, do not paste diffs into the chat.
+Run the review window from the repository root and wait for it to exit:
+
+```bash
+scripts/review.sh            # working tree against HEAD
+scripts/review.sh HEAD~3     # or any range git diff understands
+```
+
+The command opens neovim with the diff (old | new) and a notes buffer, blocks
+until the window closes, and prints the notes the user wrote, or
+`no review comments`. Comments are grouped by file and hunk anchor.
+
+Treat the printed notes as review feedback: fix the code, then re-run the
+review if the user asks for another round. Never invent notes the user did not
+write, and do not edit `REVIEW.md` yourself.
+
+The window needs kitty or a tmux session; the workspace lives in
+`/tmp/opencode/review/`.

aiowapy-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), versions follow
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — unreleased
+
+First public release. The protocol is implemented natively; live traffic is not yet
+validated against production WhatsApp.
+
+### Added
+
+- Noise XX handshake, WABinary codec, WebSocket transport, keepalive and reconnect.
+- QR pairing and phone-number pairing, prekey publication.
+- Signal: X3DH, double ratchet, session serialization, prekey and one-time prekey
+  sessions.
+- Sending: text, replies, reactions, edits, revokes; images, video, audio, voice notes,
+  documents, stickers.
+- Receiving: pairwise and sender-key decryption, automatic delivery receipts, retry
+  receipts in both directions.
+- Groups: info, create, participants, leave, sender keys with out-of-order handling.
+- Media: encrypted upload and download with hash verification.
+- App state: patch sync, MAC verification, LTHash, mute/pin/mark-read/push-name.
+- History sync: encrypted chunk download, unpacking, storage.
+- Storage in one `.session` file: chats, contacts, messages, reactions, LID mappings.
+- Filter router with `F` helpers, events, reconnect lifecycle.

aiowapy-0.1.0/LICENSE

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

aiowapy-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.5
+Name: aiowapy
+Version: 0.1.0
+Summary: Async WhatsApp Multi-Device client: Noise, Signal and WABinary implemented natively in Python
+Project-URL: Homepage, https://github.com/Yarfer800/aiowapy
+Project-URL: Documentation, https://yarfer800.github.io/aiowapy/
+Project-URL: Repository, https://github.com/Yarfer800/aiowapy
+Project-URL: Issues, https://github.com/Yarfer800/aiowapy/issues
+Project-URL: Changelog, https://github.com/Yarfer800/aiowapy/blob/main/CHANGELOG.md
+Author-email: Yarfer <yarfer@rs.me>
+License: MIT
+License-File: LICENSE
+Keywords: async,asyncio,bot,messaging,noise,signal,whatsapp,whatsapp-web
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: cryptography>=42
+Requires-Dist: protobuf>=5
+Requires-Dist: websockets>=15
+Description-Content-Type: text/markdown
+
+# aiowapy
+
+[![CI](https://github.com/Yarfer800/aiowapy/actions/workflows/ci.yml/badge.svg)](https://github.com/Yarfer800/aiowapy/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-yarfer800.github.io%2Faiowapy-green)](https://yarfer800.github.io/aiowapy/)
+[![PyPI](https://img.shields.io/pypi/v/aiowapy.svg)](https://pypi.org/project/aiowapy/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/aiowapy/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+An asynchronous WhatsApp Multi-Device client for Python: a native implementation of the
+protocol (Noise + Signal + WABinary), no official Cloud API involved.
+
+> ⚠️ **Unofficial client.** Using it violates WhatsApp's Terms of Service and the number
+> may be banned. Use a test number and proceed at your own risk.
+
+## Installation
+
+```bash
+pip install aiowapy
+```
+
+The distribution is called **aiowapy**, the import is **`aiowapy`**:
+
+```python
+from aiowapy import Client
+```
+
+Full documentation: **https://yarfer800.github.io/aiowapy/**
+
+## Quick start
+
+```python
+import asyncio
+
+from aiowapy import Client
+from aiowapy.events import MessageEvent
+from aiowapy.router import F
+
+
+async def main() -> None:
+    async with Client("bot.session") as client:
+        print("connected as", client.info.jid)
+
+        @client.router.message(F.text.startswith("/ping"))
+        async def ping(event: MessageEvent) -> None:
+            await client.send_text(event.chat_jid, "pong", quote=event.message_id)
+
+        await client.run()
+
+
+asyncio.run(main())
+```
+
+The first run needs linking: scan the QR code (`qr_callback`) or use
+`ClientSession.pair_with_phone_number` (see `examples/pair_code.py`). After that the
+session file keeps the keys and later runs only log in.
+
+## One session file, like Pyrogram
+
+`.session` is SQLite and holds everything: credentials, Signal sessions, prekeys,
+app state, **chats, contacts and messages**.
+
+```python
+history = await client.get_chat_history(chat_jid, limit=50)  # newest first
+older = await client.get_chat_history(chat_jid, limit=50, before_timestamp=history[-1].timestamp)
+
+chats = await client.get_chats()  # conversations, newest first
+users = await client.get_users()  # contacts we have seen
+chat = await client.get_chat(jid)  # Peer: .name, .push_name, .contact_name
+await client.set_contact_name(jid, "Mom")
+await client.download_stored(history[0])  # attachment of a stored message
+```
+
+Messages arrive from three places: live traffic, `history sync` chunks sent by the
+phone, and everything the bot sends. All of it lands in the same table, so
+`get_chat_history` returns a real conversation, not just what the process saw.
+
+## Sending
+
+```python
+await client.send_text(jid, "hello")
+await client.send_text(jid, "with a reply", quote=message_id)
+await client.send_image(jid, picture_bytes, caption="look")
+await client.send_document(jid, pdf_bytes, file_name="report.pdf", mime_type="application/pdf")
+await client.send_audio(jid, voice_bytes, voice_note=True)
+await client.send_reaction(jid, message_id, "\U0001f44d")
+await client.edit_message(jid, message_id, "fixed text")
+await client.revoke_message(jid, message_id)
+await client.send_text("120363000000000001@g.us", "hello group")  # groups just work
+```
+
+`send_*` returns `SendResult(message_id, sent, failed, acked)`: a message counts as
+delivered when at least one device accepted it; per-device failures are listed, not
+raised.
+
+## Receiving
+
+```python
+from aiowapy.router import F
+
+
+@client.router.message(F.text.contains("invoice") & F.chat("1203630@g.us"))
+async def handle(event: MessageEvent) -> None:
+    await client.mark_read(event)
+
+
+@client.router.message(F.media("image"))
+async def on_image(event: MessageEvent) -> None:
+    data = await client.download_media(event.media)
+```
+
+Events: `MessageEvent`, `ReactionEvent`, `EditEvent`, `RevokeEvent`, `HistorySyncEvent`,
+`ReceiptEvent`, `PresenceEvent`, `ChatStateEvent`, `ConnectedEvent`,
+`DisconnectedEvent`, `NotificationEvent`.
+
+Presence and typing:
+
+```python
+await client.send_presence(True)
+await client.subscribe_presence(jid)
+await client.send_typing(jid, composing=True)
+```
+
+## Groups
+
+```python
+info = await client.group_info(group_jid)
+group = await client.create_group("Team", [jid1, jid2])
+await client.update_group_participants(group, "add", [jid3])
+await client.leave_group(group)
+```
+
+A group message is encrypted once with a sender key; the key distribution message
+travels to every member device, exactly as the reference client does it.
+
+## App state
+
+Contacts, mutes, pins and read markers live in WhatsApp's app state. Keys arrive from
+the phone; after that:
+
+```python
+await client.sync_app_state()
+await client.mute_chat(jid, True)
+await client.pin_chat(jid, True)
+await client.mark_chat_read(jid, True)
+```
+
+## Coverage
+
+| Layer | Module |
+|---|---|
+| Noise handshake, framing | `aiowapy.protocol.noise`, `aiowapy.protocol.transport` |
+| Pairing (QR and code) | `aiowapy.protocol.pairing`, `aiowapy.protocol.pairing_code` |
+| WABinary codec | `aiowapy.protocol.wabinary` |
+| Signal (X3DH, double ratchet) | `aiowapy.crypto.session` |
+| Sending: text, media, groups | `aiowapy.messaging` |
+| Receiving and decryption | `aiowapy.messaging.receiving` |
+| Receipts, retry requests | `aiowapy.protocol.receipts`, `aiowapy.client` |
+| Presence and typing | `aiowapy.protocol.presence` |
+| Groups (sender keys) | `aiowapy.messaging.groups` |
+| Media upload and download | `aiowapy.messaging.media` |
+| App state sync | `aiowapy.messaging.appstate` |
+| History sync | `aiowapy.messaging.history` |
+| Chats, contacts, messages | `aiowapy.store` |
+| Reactions, replies, edits, revokes | `aiowapy.protocol.messages` |
+
+Not implemented: calls, channels (newsletters), statuses, polls and buttons,
+LID-based encryption (LID mappings are stored and exposed, but sessions still start
+on phone-number devices).
+
+## License
+
+MIT.

aiowapy-0.1.0/README.md

@@ -0,0 +1,172 @@
+# aiowapy
+
+[![CI](https://github.com/Yarfer800/aiowapy/actions/workflows/ci.yml/badge.svg)](https://github.com/Yarfer800/aiowapy/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-yarfer800.github.io%2Faiowapy-green)](https://yarfer800.github.io/aiowapy/)
+[![PyPI](https://img.shields.io/pypi/v/aiowapy.svg)](https://pypi.org/project/aiowapy/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/aiowapy/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+An asynchronous WhatsApp Multi-Device client for Python: a native implementation of the
+protocol (Noise + Signal + WABinary), no official Cloud API involved.
+
+> ⚠️ **Unofficial client.** Using it violates WhatsApp's Terms of Service and the number
+> may be banned. Use a test number and proceed at your own risk.
+
+## Installation
+
+```bash
+pip install aiowapy
+```
+
+The distribution is called **aiowapy**, the import is **`aiowapy`**:
+
+```python
+from aiowapy import Client
+```
+
+Full documentation: **https://yarfer800.github.io/aiowapy/**
+
+## Quick start
+
+```python
+import asyncio
+
+from aiowapy import Client
+from aiowapy.events import MessageEvent
+from aiowapy.router import F
+
+
+async def main() -> None:
+    async with Client("bot.session") as client:
+        print("connected as", client.info.jid)
+
+        @client.router.message(F.text.startswith("/ping"))
+        async def ping(event: MessageEvent) -> None:
+            await client.send_text(event.chat_jid, "pong", quote=event.message_id)
+
+        await client.run()
+
+
+asyncio.run(main())
+```
+
+The first run needs linking: scan the QR code (`qr_callback`) or use
+`ClientSession.pair_with_phone_number` (see `examples/pair_code.py`). After that the
+session file keeps the keys and later runs only log in.
+
+## One session file, like Pyrogram
+
+`.session` is SQLite and holds everything: credentials, Signal sessions, prekeys,
+app state, **chats, contacts and messages**.
+
+```python
+history = await client.get_chat_history(chat_jid, limit=50)  # newest first
+older = await client.get_chat_history(chat_jid, limit=50, before_timestamp=history[-1].timestamp)
+
+chats = await client.get_chats()  # conversations, newest first
+users = await client.get_users()  # contacts we have seen
+chat = await client.get_chat(jid)  # Peer: .name, .push_name, .contact_name
+await client.set_contact_name(jid, "Mom")
+await client.download_stored(history[0])  # attachment of a stored message
+```
+
+Messages arrive from three places: live traffic, `history sync` chunks sent by the
+phone, and everything the bot sends. All of it lands in the same table, so
+`get_chat_history` returns a real conversation, not just what the process saw.
+
+## Sending
+
+```python
+await client.send_text(jid, "hello")
+await client.send_text(jid, "with a reply", quote=message_id)
+await client.send_image(jid, picture_bytes, caption="look")
+await client.send_document(jid, pdf_bytes, file_name="report.pdf", mime_type="application/pdf")
+await client.send_audio(jid, voice_bytes, voice_note=True)
+await client.send_reaction(jid, message_id, "\U0001f44d")
+await client.edit_message(jid, message_id, "fixed text")
+await client.revoke_message(jid, message_id)
+await client.send_text("120363000000000001@g.us", "hello group")  # groups just work
+```
+
+`send_*` returns `SendResult(message_id, sent, failed, acked)`: a message counts as
+delivered when at least one device accepted it; per-device failures are listed, not
+raised.
+
+## Receiving
+
+```python
+from aiowapy.router import F
+
+
+@client.router.message(F.text.contains("invoice") & F.chat("1203630@g.us"))
+async def handle(event: MessageEvent) -> None:
+    await client.mark_read(event)
+
+
+@client.router.message(F.media("image"))
+async def on_image(event: MessageEvent) -> None:
+    data = await client.download_media(event.media)
+```
+
+Events: `MessageEvent`, `ReactionEvent`, `EditEvent`, `RevokeEvent`, `HistorySyncEvent`,
+`ReceiptEvent`, `PresenceEvent`, `ChatStateEvent`, `ConnectedEvent`,
+`DisconnectedEvent`, `NotificationEvent`.
+
+Presence and typing:
+
+```python
+await client.send_presence(True)
+await client.subscribe_presence(jid)
+await client.send_typing(jid, composing=True)
+```
+
+## Groups
+
+```python
+info = await client.group_info(group_jid)
+group = await client.create_group("Team", [jid1, jid2])
+await client.update_group_participants(group, "add", [jid3])
+await client.leave_group(group)
+```
+
+A group message is encrypted once with a sender key; the key distribution message
+travels to every member device, exactly as the reference client does it.
+
+## App state
+
+Contacts, mutes, pins and read markers live in WhatsApp's app state. Keys arrive from
+the phone; after that:
+
+```python
+await client.sync_app_state()
+await client.mute_chat(jid, True)
+await client.pin_chat(jid, True)
+await client.mark_chat_read(jid, True)
+```
+
+## Coverage
+
+| Layer | Module |
+|---|---|
+| Noise handshake, framing | `aiowapy.protocol.noise`, `aiowapy.protocol.transport` |
+| Pairing (QR and code) | `aiowapy.protocol.pairing`, `aiowapy.protocol.pairing_code` |
+| WABinary codec | `aiowapy.protocol.wabinary` |
+| Signal (X3DH, double ratchet) | `aiowapy.crypto.session` |
+| Sending: text, media, groups | `aiowapy.messaging` |
+| Receiving and decryption | `aiowapy.messaging.receiving` |
+| Receipts, retry requests | `aiowapy.protocol.receipts`, `aiowapy.client` |
+| Presence and typing | `aiowapy.protocol.presence` |
+| Groups (sender keys) | `aiowapy.messaging.groups` |
+| Media upload and download | `aiowapy.messaging.media` |
+| App state sync | `aiowapy.messaging.appstate` |
+| History sync | `aiowapy.messaging.history` |
+| Chats, contacts, messages | `aiowapy.store` |
+| Reactions, replies, edits, revokes | `aiowapy.protocol.messages` |
+
+Not implemented: calls, channels (newsletters), statuses, polls and buttons,
+LID-based encryption (LID mappings are stored and exposed, but sessions still start
+on phone-number devices).
+
+## License
+
+MIT.

aiowapy-0.1.0/docs/api/client.md

@@ -0,0 +1,11 @@
+# Client
+
+::: aiowapy.client
+    options:
+      members:
+        - Client
+        - ClientInfo
+        - ClientError
+        - SendResult
+        - OutgoingMessage
+        - default_mime_type

aiowapy-0.1.0/docs/api/events.md

@@ -0,0 +1,3 @@
+# Events
+
+::: aiowapy.events

aiowapy-0.1.0/docs/api/models.md

@@ -0,0 +1,3 @@
+# Models
+
+::: aiowapy.models

aiowapy-0.1.0/docs/api/router.md

@@ -0,0 +1,3 @@
+# Router and filters
+
+::: aiowapy.router

aiowapy-0.1.0/docs/api/store.md

@@ -0,0 +1,3 @@
+# Store
+
+::: aiowapy.store

aiowapy-0.1.0/docs/appstate.md

@@ -0,0 +1,61 @@
+# App state
+
+Contacts, mutes, pins, archives and read markers are not messages: they live in a
+key-value store synchronized through patches. The phone owns the keys and shares them
+with linked devices; patches are encrypted with those keys, chained by an additive
+integrity hash.
+
+## Sync
+
+```python
+results = await client.sync_app_state()
+for result in results:
+    print(result.name, result.version, result.applied, result.skipped)
+```
+
+Each collection (`critical_block`, `critical_unblock_low`, `regular`, `regular_high`,
+`regular_low`) is fetched from the stored version, verified and applied. Unknown
+mutations are counted as `skipped` instead of failing the whole patch.
+
+What is verified:
+
+| Check | Detail |
+|---|---|
+| Value MAC | HMAC-SHA512 over operation, key id and ciphertext, truncated |
+| Index MAC | HMAC-SHA256 of the JSON index |
+| Patch MAC | snapshot MAC, value MACs, version and collection name |
+| Integrity | LTHash: 128-byte additive hash over `WhatsApp Patch Integrity` |
+
+Local copy:
+
+```python
+entries = await client.app_state_entries("regular_high")
+for index_json, value, timestamp in entries:
+    print(index_json, timestamp)
+```
+
+## Writing
+
+```python
+await client.mute_chat(jid, True)          # mute forever
+await client.pin_chat(jid, True)
+await client.mark_chat_read(jid, True)
+await client.set_push_name("bot")
+```
+
+Each call builds one patch, updates the integrity hash and pushes it. The reply is
+checked for a `type="error"` collection; a conflict raises `AppStateSyncError`.
+
+## Keys
+
+Keys arrive from the phone in a protocol message (`AppStateSyncKeyShare`). The library
+stores them, then runs a sync in the background:
+
+```python
+@client.router.on(NotificationEvent)
+async def notifications(event: NotificationEvent) -> None:
+    print(event.kind)
+```
+
+If a key is missing when a patch arrives, syncing that collection fails with
+`AppStateSyncError`; the local copy stays untouched.