wavvon-sdk

Write programs that talk to a Wavvon hub: bots, apps with slash commands and buttons, event consumers, mini-app hosts, and receivers for outgoing webhooks.

A program on Wavvon is a client like any other: an Ed25519 keypair, the same challenge-response login, the same permissions. There is no bot account. What makes a program an app is a role carrying apps.register. The design this package implements is sdk.md (tier 1).

• Python 3.11 or later, asyncio, fully typed (py.typed, checked with mypy --strict).
• Depends on httpx, websockets and cryptography, plus attrs, python-dateutil and typing-extensions for the generated REST models.
• Apache-2.0, so a closed-source program can use it.

Install

pip install wavvon-sdk

The import package is wavvon.

Quick start

import asyncio, os
import uvicorn  # any ASGI server; or call the handler from your own framework
from wavvon import WavvonClient, create_dispatch_handler, to_asgi


async def main() -> None:
    async with WavvonClient(
        "https://hub.example",
        seed=os.environ["WAVVON_SEED"],  # 32-byte Ed25519 seed, hex. Never sent anywhere.
        invite_code=os.environ.get("WAVVON_INVITE"),  # only needed the first time, on an invite-only hub
    ) as client:
        info = await client.info()
        app = to_asgi(
            create_dispatch_handler(
                hub_public_key=info["public_key"],
                on_slash_command=lambda inv: {"reply": {"body": f"you said: {inv['args_raw']}"}},
            )
        )

        await client.set_app_profile({"name": "Echo", "webhook_url": "https://bot.example/hook"})
        await client.set_app_commands([{"name": "echo", "description": "Repeat after me"}])

        events = client.connect()  # after set_app_profile, see below
        events.on("message", lambda e: print(e["message"].get("sender"), e["message"].get("content")))
        events.on("unknown", lambda e: print("new frame type:", e["raw_type"]))

        await uvicorn.Server(uvicorn.Config(app, port=8080)).serve()


asyncio.run(main())

A fuller one is examples/echo_bot.py.

Every REST route is a generated function under wavvon.rest.api; pass client.rest and unwrap with ok(), which raises HubError on a refusal:

from wavvon import ok
from wavvon.rest.api.channels import list_channels

channels = ok(await list_channels.asyncio_detailed(client=client.rest))

What is in it

create_dispatch_handler returns a plain async (method, headers, body) -> WebhookResponse function, so it fits any framework; to_asgi wraps it for uvicorn, hypercorn, Starlette or FastAPI.

Capabilities each feature needs

Hubs say what they support in GET /info capabilities. The SDK checks those strings and never compares version numbers. A feature the hub does not advertise raises UnsupportedByHubError.

Login, REST, the socket and polling need no capability.

Behaviour you can rely on

• A transient failure is never an answer. 429, 5xx, timeouts and dropped connections are retried with capped exponential backoff and jitter. If the budget runs out you get HubUnavailableError, not an empty list or a 404. Set RetryOptions(max_attempts=math.inf) to wait forever.
• Sessions renew themselves. A 401 triggers one fresh login and a retry. client.on_state_change and events.on_state_change show when it is happening.
• Unknown is delivered. A socket frame or dispatch type this version does not model reaches you as {"type": "unknown", "raw_type": ..., "raw": ...}.
• Missed events are replayed. The event stream remembers the last hub_event seq and asks the hub to resume from it after every reconnect. If the gap is older than the hub keeps (72 hours) you get replay_unavailable. Register the app profile before connect(): the hub only pushes and replays events on a socket opened by a registered app.
• The seed stays with you. No call sends a seed or private key anywhere.

Conformance

Every signed byte sequence is checked against the shared wire vectors in Wavvon-server (crates/identity/wire-vectors.json): the auth challenge, the Ed25519 dispatch signature, and the outgoing-webhook HKDF + HMAC. CI reads them from Wavvon-server at commit eb11d75657ee8362dd42a7982fc5b13a3dcc4e68.

The REST client was generated from Wavvon-docs at the commit in src/wavvon/rest/SPEC_COMMIT.

Licence

Apache-2.0. See LICENSE and NOTICE.