amarwave 2.0.0__tar.gz

amarwave-2.0.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: amarwave
+Version: 2.0.0
+Summary: Real-time WebSocket client for AmarWave servers
+Author-email: AmarWave <mehedinaeem66@gmail.com>
+License: MIT
+Project-URL: Homepage, https://amarwave.com
+Project-URL: Repository, https://github.com/amarwave/amarwave-python
+Project-URL: Issues, https://github.com/amarwave/amarwave-python/issues
+Keywords: websocket,realtime,pubsub,amarwave,async
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=12.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# amarwave
+
+Official Python client for [AmarWave](https://amarwave.com) real-time messaging — async, typed, zero boilerplate.
+
+[![PyPI version](https://img.shields.io/pypi/v/amarwave)](https://pypi.org/project/amarwave/)
+[![Python](https://img.shields.io/pypi/pyversions/amarwave)](https://pypi.org/project/amarwave/)
+[![License](https://img.shields.io/pypi/l/amarwave)](LICENSE)
+
+---
+
+## Installation
+
+```bash
+pip install amarwave
+```
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+from amarwave import AmarWave
+
+async def main():
+    aw = AmarWave(
+        app_key    = "YOUR_APP_KEY",
+        app_secret = "YOUR_APP_SECRET",
+    )
+
+    ch = await aw.subscribe("public-chat")
+    ch.bind("message", lambda data: print(data["user"], data["text"]))
+
+    await ch.publish("message", {"user": "Ali", "text": "Hello!"})
+    await aw.listen()  # keep alive forever
+
+asyncio.run(main())
+```
+
+---
+
+## Configuration
+
+| Parameter             | Type  | Default          | Description                                    |
+|-----------------------|-------|------------------|------------------------------------------------|
+| `app_key`             | str   | —                | Your app key **(required)**                    |
+| `app_secret`          | str   | `""`             | App secret for HMAC channel auth               |
+| `cluster`             | str   | `"default"`      | `"default"` \| `"eu"` \| `"us"` \| `"ap1"` \| `"ap2"` |
+| `auth_endpoint`       | str   | `"/broadcasting/auth"` | Server auth URL for private/presence channels |
+| `auth_headers`        | dict  | `{}`             | Headers sent to the auth endpoint              |
+| `reconnect_delay`     | float | `1.0`            | Base reconnect delay in seconds                |
+| `max_reconnect_delay` | float | `30.0`           | Max reconnect delay in seconds                 |
+| `max_retries`         | int   | `5`              | Max reconnect attempts (0 = infinite)          |
+| `activity_timeout`    | float | `120.0`          | Seconds between keepalive pings                |
+| `pong_timeout`        | float | `30.0`           | Seconds to wait for pong before reconnecting   |
+
+### Clusters
+
+All clusters connect to `amarwave.com`. The `cluster` parameter is reserved for future regional routing.
+
+| Cluster   | WebSocket                  | API                        |
+|-----------|----------------------------|----------------------------|
+| `default` | `wss://amarwave.com`       | `https://amarwave.com`     |
+| `eu`      | `wss://amarwave.com`       | `https://amarwave.com`     |
+| `us`      | `wss://amarwave.com`       | `https://amarwave.com`     |
+| `ap1`     | `wss://amarwave.com`       | `https://amarwave.com`     |
+| `ap2`     | `wss://amarwave.com`       | `https://amarwave.com`     |
+
+```python
+aw = AmarWave(app_key="KEY", app_secret="SECRET", cluster="eu")
+```
+
+---
+
+## Channel API
+
+```python
+ch = await aw.subscribe("public-chat")
+
+ch.bind("message", handler)           # listen for event
+ch.bind_global(lambda e, d: ...)      # listen for all events on this channel
+ch.unbind("message", handler)         # remove listener
+await ch.publish("message", data)     # publish via HTTP API → bool
+await aw.publish("ch", "ev", data)    # top-level publish shortcut
+
+ch.name        # "public-chat"
+ch.subscribed  # True when server confirmed subscription
+```
+
+---
+
+## Connection Events
+
+```python
+aw.bind("connecting",   lambda _: print("Connecting…"))
+aw.bind("connected",    lambda _: print(f"Connected: {aw.socket_id}"))
+aw.bind("disconnected", lambda _: print("Disconnected"))
+aw.bind("error",        lambda e: print(f"Error: {e}"))
+```
+
+---
+
+## Private & Presence Channels
+
+```python
+# Client-side HMAC auth (app_secret required)
+aw = AmarWave(app_key="KEY", app_secret="SECRET")
+ch = await aw.subscribe("private-orders")    # auto-signed
+ch = await aw.subscribe("presence-room-1")  # auto-signed
+
+# Server-side auth (omit app_secret, provide auth_endpoint)
+aw = AmarWave(
+    app_key       = "KEY",
+    auth_endpoint = "https://yourapp.com/api/broadcasting/auth",
+    auth_headers  = {"Authorization": f"Bearer {token}"},
+)
+ch = await aw.subscribe("private-orders")
+```
+
+---
+
+## Django Integration
+
+```python
+import asyncio
+from amarwave import AmarWave
+
+# One-shot publish from a sync Django view
+def notify_user(user_id: int, message: str) -> bool:
+    async def _publish() -> bool:
+        aw = AmarWave(app_key="KEY", app_secret="SECRET")
+        return await aw.publish(f"private-user-{user_id}", "notification", {"message": message})
+    return asyncio.run(_publish())
+```
+
+---
+
+## FastAPI Integration
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from amarwave import AmarWave
+
+aw = AmarWave(app_key="KEY", app_secret="SECRET")
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    ch = await aw.subscribe("public-updates")
+    ch.bind("message", lambda d: print(d))
+    yield
+    await aw.disconnect()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.post("/notify")
+async def notify(message: str):
+    await aw.publish("public-updates", "message", {"text": message})
+    return {"ok": True}
+```
+
+---
+
+## Requirements
+
+- Python 3.10+
+- `websockets >= 12.0`
+- `httpx >= 0.27.0`
+
+---
+
+## License
+
+MIT © AmarWave

amarwave-2.0.0/README.md

@@ -0,0 +1,174 @@
+# amarwave
+
+Official Python client for [AmarWave](https://amarwave.com) real-time messaging — async, typed, zero boilerplate.
+
+[![PyPI version](https://img.shields.io/pypi/v/amarwave)](https://pypi.org/project/amarwave/)
+[![Python](https://img.shields.io/pypi/pyversions/amarwave)](https://pypi.org/project/amarwave/)
+[![License](https://img.shields.io/pypi/l/amarwave)](LICENSE)
+
+---
+
+## Installation
+
+```bash
+pip install amarwave
+```
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+from amarwave import AmarWave
+
+async def main():
+    aw = AmarWave(
+        app_key    = "YOUR_APP_KEY",
+        app_secret = "YOUR_APP_SECRET",
+    )
+
+    ch = await aw.subscribe("public-chat")
+    ch.bind("message", lambda data: print(data["user"], data["text"]))
+
+    await ch.publish("message", {"user": "Ali", "text": "Hello!"})
+    await aw.listen()  # keep alive forever
+
+asyncio.run(main())
+```
+
+---
+
+## Configuration
+
+| Parameter             | Type  | Default          | Description                                    |
+|-----------------------|-------|------------------|------------------------------------------------|
+| `app_key`             | str   | —                | Your app key **(required)**                    |
+| `app_secret`          | str   | `""`             | App secret for HMAC channel auth               |
+| `cluster`             | str   | `"default"`      | `"default"` \| `"eu"` \| `"us"` \| `"ap1"` \| `"ap2"` |
+| `auth_endpoint`       | str   | `"/broadcasting/auth"` | Server auth URL for private/presence channels |
+| `auth_headers`        | dict  | `{}`             | Headers sent to the auth endpoint              |
+| `reconnect_delay`     | float | `1.0`            | Base reconnect delay in seconds                |
+| `max_reconnect_delay` | float | `30.0`           | Max reconnect delay in seconds                 |
+| `max_retries`         | int   | `5`              | Max reconnect attempts (0 = infinite)          |
+| `activity_timeout`    | float | `120.0`          | Seconds between keepalive pings                |
+| `pong_timeout`        | float | `30.0`           | Seconds to wait for pong before reconnecting   |
+
+### Clusters
+
+All clusters connect to `amarwave.com`. The `cluster` parameter is reserved for future regional routing.
+
+| Cluster   | WebSocket                  | API                        |
+|-----------|----------------------------|----------------------------|
+| `default` | `wss://amarwave.com`       | `https://amarwave.com`     |
+| `eu`      | `wss://amarwave.com`       | `https://amarwave.com`     |
+| `us`      | `wss://amarwave.com`       | `https://amarwave.com`     |
+| `ap1`     | `wss://amarwave.com`       | `https://amarwave.com`     |
+| `ap2`     | `wss://amarwave.com`       | `https://amarwave.com`     |
+
+```python
+aw = AmarWave(app_key="KEY", app_secret="SECRET", cluster="eu")
+```
+
+---
+
+## Channel API
+
+```python
+ch = await aw.subscribe("public-chat")
+
+ch.bind("message", handler)           # listen for event
+ch.bind_global(lambda e, d: ...)      # listen for all events on this channel
+ch.unbind("message", handler)         # remove listener
+await ch.publish("message", data)     # publish via HTTP API → bool
+await aw.publish("ch", "ev", data)    # top-level publish shortcut
+
+ch.name        # "public-chat"
+ch.subscribed  # True when server confirmed subscription
+```
+
+---
+
+## Connection Events
+
+```python
+aw.bind("connecting",   lambda _: print("Connecting…"))
+aw.bind("connected",    lambda _: print(f"Connected: {aw.socket_id}"))
+aw.bind("disconnected", lambda _: print("Disconnected"))
+aw.bind("error",        lambda e: print(f"Error: {e}"))
+```
+
+---
+
+## Private & Presence Channels
+
+```python
+# Client-side HMAC auth (app_secret required)
+aw = AmarWave(app_key="KEY", app_secret="SECRET")
+ch = await aw.subscribe("private-orders")    # auto-signed
+ch = await aw.subscribe("presence-room-1")  # auto-signed
+
+# Server-side auth (omit app_secret, provide auth_endpoint)
+aw = AmarWave(
+    app_key       = "KEY",
+    auth_endpoint = "https://yourapp.com/api/broadcasting/auth",
+    auth_headers  = {"Authorization": f"Bearer {token}"},
+)
+ch = await aw.subscribe("private-orders")
+```
+
+---
+
+## Django Integration
+
+```python
+import asyncio
+from amarwave import AmarWave
+
+# One-shot publish from a sync Django view
+def notify_user(user_id: int, message: str) -> bool:
+    async def _publish() -> bool:
+        aw = AmarWave(app_key="KEY", app_secret="SECRET")
+        return await aw.publish(f"private-user-{user_id}", "notification", {"message": message})
+    return asyncio.run(_publish())
+```
+
+---
+
+## FastAPI Integration
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from amarwave import AmarWave
+
+aw = AmarWave(app_key="KEY", app_secret="SECRET")
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    ch = await aw.subscribe("public-updates")
+    ch.bind("message", lambda d: print(d))
+    yield
+    await aw.disconnect()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.post("/notify")
+async def notify(message: str):
+    await aw.publish("public-updates", "message", {"text": message})
+    return {"ok": True}
+```
+
+---
+
+## Requirements
+
+- Python 3.10+
+- `websockets >= 12.0`
+- `httpx >= 0.27.0`
+
+---
+
+## License
+
+MIT © AmarWave

amarwave-2.0.0/amarwave/__init__.py

@@ -0,0 +1,37 @@
+"""
+AmarWave Python Client v2.0.0
+Real-time WebSocket client for AmarWave servers.
+
+Example::
+
+    import asyncio
+    from amarwave import AmarWave
+
+    async def main():
+        aw = AmarWave(app_key="YOUR_KEY", app_secret="YOUR_SECRET")
+
+        ch = await aw.subscribe("public-chat")
+
+        ch.bind("message", lambda data: print(data["user"], data["text"]))
+
+        await ch.publish("message", {"user": "Ali", "text": "Hello!"})
+
+        await aw.listen()   # keep alive forever
+
+    asyncio.run(main())
+"""
+
+from .client  import AmarWave
+from .channel import Channel
+from .emitter import EventEmitter
+from .types   import ConnectionState, CLUSTERS
+
+__all__ = [
+    "AmarWave",
+    "Channel",
+    "EventEmitter",
+    "ConnectionState",
+    "CLUSTERS",
+]
+
+__version__ = "2.0.0"

amarwave-2.0.0/amarwave/channel.py

@@ -0,0 +1,63 @@
+"""
+AmarWave — Channel class.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+from .emitter import EventEmitter
+
+if TYPE_CHECKING:
+    from .client import AmarWave
+
+
+class Channel(EventEmitter):
+    """
+    Represents a subscription to a named AmarWave channel.
+
+    Obtained via ``aw.subscribe("channel-name")`` — never constructed directly.
+
+    Example::
+
+        ch = aw.subscribe("public-chat")
+        ch.bind("message", lambda data: print(data["text"]))
+        await ch.publish("message", {"user": "Ali", "text": "Hello!"})
+    """
+
+    def __init__(self, name: str, client: "AmarWave") -> None:
+        super().__init__()
+        self.name:       str       = name
+        self._aw:        AmarWave  = client
+        self.subscribed: bool      = False
+        self._queue:     list[dict[str, Any]] = []
+
+    # ── Publish ───────────────────────────────────────────────────────────────
+
+    async def publish(self, event: str, data: Any = None) -> bool:
+        """
+        Publish an event to this channel via HTTP API.
+
+        - Safe to call before subscribed — queued and flushed automatically.
+        - Returns ``True`` on success, ``False`` on failure.
+
+        Example::
+
+            await ch.publish("message", {"user": "Ali", "text": "Hello!"})
+        """
+        if not self.subscribed:
+            # Queue until subscription is confirmed
+            future: asyncio.Future[bool] = asyncio.get_event_loop().create_future()
+            self._queue.append({"event": event, "data": data, "future": future})
+            return await future
+
+        return await self._aw._http_publish(self.name, event, data)
+
+    async def _flush_queue(self) -> None:
+        """Called internally when subscription_succeeded arrives."""
+        items, self._queue = self._queue[:], []
+        for item in items:
+            result = await self._aw._http_publish(self.name, item["event"], item["data"])
+            future: asyncio.Future[bool] = item["future"]
+            if not future.done():
+                future.set_result(result)

amarwave-2.0.0/amarwave/client.py

@@ -0,0 +1,357 @@
+"""
+AmarWave — Main async client.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any
+from urllib.parse import urlencode
+
+import httpx
+import websockets
+from websockets.exceptions import ConnectionClosed
+
+from .channel import Channel
+from .crypto  import generate_uid, hmac_sha256
+from .emitter import EventEmitter
+from .types   import CLUSTERS, ConnectionState
+
+logger = logging.getLogger("amarwave")
+
+
+class AmarWave(EventEmitter):
+    """
+    AmarWave async real-time client.
+
+    Example::
+
+        import asyncio
+        from amarwave import AmarWave
+
+        async def main():
+            aw = AmarWave(app_key="KEY", app_secret="SECRET")
+
+            ch = await aw.subscribe("public-chat")
+            ch.bind("message", lambda d: print(d["user"], d["text"]))
+
+            await ch.publish("message", {"user": "Ali", "text": "Hello!"})
+            await aw.listen()   # keep alive forever
+
+        asyncio.run(main())
+    """
+
+    def __init__(
+        self,
+        *,
+        app_key:             str,
+        app_secret:          str   = "",
+        cluster:             str   = "default",
+        auth_endpoint:       str   = "/broadcasting/auth",
+        auth_headers:        dict[str, str] | None = None,
+        reconnect_delay:     float = 1.0,
+        max_reconnect_delay: float = 30.0,
+        max_retries:         int   = 5,
+        activity_timeout:    float = 120.0,
+        pong_timeout:        float = 30.0,
+    ) -> None:
+        super().__init__()
+
+        self.app_key    = app_key
+        self.app_secret = app_secret
+        self.cluster    = cluster
+
+        cluster_cfg    = CLUSTERS.get(cluster.lower(), CLUSTERS["default"])
+        # Use plain ws:// for local, wss:// for all cloud clusters
+        self._ws_base  = cluster_cfg["ws"] if cluster.lower() == "local" else cluster_cfg["wss"]
+        self._api_base = cluster_cfg["api"]
+
+        self.auth_endpoint = auth_endpoint
+        self.auth_headers  = auth_headers or {}
+
+        self.reconnect_delay     = reconnect_delay
+        self.max_reconnect_delay = max_reconnect_delay
+        self.max_retries         = max_retries
+        self.activity_timeout    = activity_timeout
+        self.pong_timeout        = pong_timeout
+
+        # Public state
+        self.socket_id: str | None   = None
+        self.state: ConnectionState  = "initialized"
+
+        # Internal
+        self._ws:        Any                 = None
+        self._channels:  dict[str, Channel]  = {}
+        self._retries:   int                 = 0
+        self._stop:      bool                = False
+        self._connected: asyncio.Event       = asyncio.Event()
+        self._recv_task: asyncio.Task | None = None
+
+    # ─── URLs ─────────────────────────────────────────────────────────────────
+
+    def _ws_url(self) -> str:
+        params = urlencode({"app_key": self.app_key})
+        return f"{self._ws_base}/ws?{params}"
+
+    def _api_url(self) -> str:
+        return f"{self._api_base}/api/v1/trigger"
+
+    # ─── Connect ──────────────────────────────────────────────────────────────
+
+    async def connect(self) -> None:
+        """Open the WebSocket connection (called automatically by subscribe)."""
+        self._stop = False
+        await self._open()
+
+    async def _open(self) -> None:
+        """Internal — open socket and start receive loop."""
+        self._set_state("connecting")
+        try:
+            self._ws = await websockets.connect(self._ws_url())
+            logger.info("[AmarWave] WebSocket opened → %s", self._ws_url())
+            self._recv_task = asyncio.create_task(self._recv_loop())
+        except Exception as e:
+            logger.warning("[AmarWave] Connect failed: %s", e)
+            self._emit("error", e)
+            await self._schedule_reconnect()
+
+    async def _recv_loop(self) -> None:
+        """Receive messages until the socket closes."""
+        try:
+            async for raw in self._ws:
+                await self._handle_raw(raw)
+        except ConnectionClosed as e:
+            logger.warning("[AmarWave] Connection closed: %s", e)
+        except Exception as e:
+            logger.warning("[AmarWave] Receive error: %s", e)
+        finally:
+            await self._on_close()
+
+    async def _handle_raw(self, raw: str) -> None:
+        try:
+            msg = json.loads(raw)
+        except json.JSONDecodeError:
+            return
+
+        # data field may be a JSON string itself
+        if isinstance(msg.get("data"), str):
+            try:
+                msg["data"] = json.loads(msg["data"])
+            except json.JSONDecodeError:
+                pass
+
+        await self._handle_message(msg)
+
+    async def _handle_message(self, msg: dict) -> None:
+        event   = msg.get("event", "")
+        channel = msg.get("channel", "")
+        data    = msg.get("data")
+
+        if event == "amarwave:connection_established":
+            self.socket_id = data.get("socket_id") if isinstance(data, dict) else None
+            self._retries  = 0
+            self._set_state("connected")
+            self._connected.set()
+            logger.info("[AmarWave] Connected — socket_id=%s", self.socket_id)
+            # Re-subscribe all channels (handles reconnect)
+            for ch in self._channels.values():
+                ch.subscribed = False
+                await self._do_subscribe(ch)
+
+        elif event == "amarwave:error":
+            msg_text = data.get("message", str(data)) if isinstance(data, dict) else str(data)
+            logger.error("[AmarWave] Server error: %s", msg_text)
+            self._emit("error", Exception(msg_text))
+
+        elif event == "amarwave:pong":
+            pass  # keepalive acknowledged
+
+        elif event == "amarwave_internal:subscription_succeeded":
+            ch = self._channels.get(channel)
+            if ch:
+                ch.subscribed = True
+                ch._emit("subscribed", data)
+                await ch._flush_queue()
+                logger.info("[AmarWave] Subscribed → %s", channel)
+
+        elif event == "amarwave_internal:subscription_error":
+            ch = self._channels.get(channel)
+            if ch:
+                ch._emit("error", data)
+                logger.warning("[AmarWave] Subscription error on %s: %s", channel, data)
+
+        else:
+            # Dispatch to channel listeners
+            if channel and channel in self._channels:
+                self._channels[channel]._emit(event, data)
+            # Also bubble to instance listeners
+            self._emit(event, {"channel": channel, "data": data})
+
+    async def _on_close(self) -> None:
+        self.socket_id = None
+        self._connected.clear()
+        for ch in self._channels.values():
+            ch.subscribed = False
+        self._set_state("disconnected")
+        if not self._stop:
+            await self._schedule_reconnect()
+
+    async def _schedule_reconnect(self) -> None:
+        if self.max_retries > 0 and self._retries >= self.max_retries:
+            logger.warning("[AmarWave] Max retries reached — giving up.")
+            return
+        delay = min(self.reconnect_delay * (2 ** self._retries), self.max_reconnect_delay)
+        self._retries += 1
+        logger.info("[AmarWave] Reconnecting in %.1fs (attempt %d)…", delay, self._retries)
+        await asyncio.sleep(delay)
+        if not self._stop:
+            await self._open()
+
+    # ─── Disconnect ───────────────────────────────────────────────────────────
+
+    async def disconnect(self) -> None:
+        """Close the connection. No auto-reconnect after this."""
+        self._stop = True
+        if self._recv_task:
+            self._recv_task.cancel()
+        if self._ws:
+            await self._ws.close()
+        self._set_state("disconnected")
+
+    # ─── Subscribe ────────────────────────────────────────────────────────────
+
+    async def subscribe(self, channel_name: str) -> Channel:
+        """
+        Subscribe to a channel. Auto-connects if needed.
+        Returns a Channel — safe to bind events and publish immediately.
+
+        Example::
+
+            ch = await aw.subscribe("public-chat")
+            ch.bind("message", lambda data: print(data))
+        """
+        if channel_name in self._channels:
+            return self._channels[channel_name]
+
+        ch = Channel(channel_name, self)
+        self._channels[channel_name] = ch
+
+        if self.state != "connected":
+            if self.state == "initialized":
+                asyncio.create_task(self._open())
+            await self._connected.wait()
+
+        await self._do_subscribe(ch)
+        return ch
+
+    async def unsubscribe(self, channel_name: str) -> None:
+        """Unsubscribe from a channel."""
+        if channel_name not in self._channels:
+            return
+        await self._raw_send({"event": "amarwave:unsubscribe", "data": {"channel": channel_name}})
+        del self._channels[channel_name]
+
+    def channel(self, channel_name: str) -> Channel | None:
+        """Get an existing subscribed channel by name."""
+        return self._channels.get(channel_name)
+
+    # ─── Publish ──────────────────────────────────────────────────────────────
+
+    async def publish(self, channel_name: str, event: str, data: Any = None) -> bool:
+        """
+        Top-level publish shortcut — no need to hold a channel reference.
+
+        Example::
+
+            await aw.publish("public-chat", "message", {"user": "Ali", "text": "Hi"})
+        """
+        return await self._http_publish(channel_name, event, data)
+
+    async def _http_publish(self, channel: str, event: str, data: Any) -> bool:
+        """Internal HTTP POST to /api/v1/trigger."""
+        body = {
+            "app_key":    self.app_key,
+            "app_secret": self.app_secret,
+            "channel":    channel,
+            "event":      event,
+            "data":       data,
+        }
+        try:
+            async with httpx.AsyncClient() as client:
+                res = await client.post(self._api_url(), json=body, timeout=10.0)
+            if res.status_code >= 400:
+                logger.warning("[AmarWave] Publish failed %d: %s", res.status_code, res.text)
+                return False
+            return True
+        except Exception as e:
+            logger.warning("[AmarWave] Publish error: %s", e)
+            return False
+
+    # ─── Subscribe helpers ────────────────────────────────────────────────────
+
+    async def _do_subscribe(self, ch: Channel) -> None:
+        name    = ch.name
+        payload: dict[str, Any] = {"event": "amarwave:subscribe", "data": {"channel": name}}
+
+        try:
+            if name.startswith("presence-"):
+                if self.app_secret:
+                    cd  = json.dumps({"user_id": generate_uid(), "user_info": {}})
+                    sig = hmac_sha256(self.app_secret, f"{self.socket_id}:{name}:{cd}")
+                    payload["data"]["auth"]         = f"{self.app_key}:{sig}"
+                    payload["data"]["channel_data"] = cd
+                else:
+                    await self._server_auth(ch, payload)
+
+            elif name.startswith("private-"):
+                if self.app_secret:
+                    sig = hmac_sha256(self.app_secret, f"{self.socket_id}:{name}")
+                    payload["data"]["auth"] = f"{self.app_key}:{sig}"
+                else:
+                    await self._server_auth(ch, payload)
+
+        except Exception as e:
+            ch._emit("error", str(e))
+            return
+
+        await self._raw_send(payload)
+
+    async def _server_auth(self, ch: Channel, payload: dict) -> None:
+        """Fetch auth token from server auth_endpoint."""
+        headers = {"Content-Type": "application/json", **self.auth_headers}
+        body    = {"socket_id": self.socket_id, "channel_name": ch.name}
+        async with httpx.AsyncClient() as client:
+            res = await client.post(self.auth_endpoint, json=body, headers=headers, timeout=10.0)
+        if res.status_code >= 400:
+            raise Exception(f"Auth failed: {res.status_code}")
+        payload["data"].update(res.json())
+
+    # ─── Keepalive ────────────────────────────────────────────────────────────
+
+    async def listen(self) -> None:
+        """
+        Block forever, keeping the connection alive with periodic pings.
+        Call this at the end of your main() to prevent the program from exiting.
+
+        Example::
+
+            await aw.listen()
+        """
+        while not self._stop:
+            await asyncio.sleep(self.activity_timeout)
+            if self._ws and self.state == "connected":
+                await self._raw_send({"event": "amarwave:ping", "data": {}})
+
+    # ─── Utilities ────────────────────────────────────────────────────────────
+
+    async def _raw_send(self, payload: dict) -> None:
+        if self._ws:
+            try:
+                await self._ws.send(json.dumps(payload))
+            except Exception as e:
+                logger.warning("[AmarWave] Send error: %s", e)
+
+    def _set_state(self, state: ConnectionState) -> None:
+        self.state = state
+        self._emit(state)

amarwave-2.0.0/amarwave/crypto.py

@@ -0,0 +1,24 @@
+"""
+AmarWave — HMAC-SHA256 signing utility.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import secrets
+import string
+
+
+def hmac_sha256(secret: str, message: str) -> str:
+    """Return HMAC-SHA256 of `message` signed with `secret` as lowercase hex."""
+    return hmac.new(
+        secret.encode(),
+        message.encode(),
+        hashlib.sha256,
+    ).hexdigest()
+
+
+def generate_uid(length: int = 16) -> str:
+    """Generate a random alphanumeric ID."""
+    alphabet = string.ascii_lowercase + string.digits
+    return "".join(secrets.choice(alphabet) for _ in range(length))

amarwave-2.0.0/amarwave/emitter.py

@@ -0,0 +1,68 @@
+"""
+AmarWave — EventEmitter base class.
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import Any
+
+from .types import EventCallback, GlobalCallback
+
+
+class EventEmitter:
+    """
+    Simple synchronous event emitter.
+    Used as the base class for both AmarWave and Channel.
+    """
+
+    def __init__(self) -> None:
+        self._listeners: dict[str, list[EventCallback]] = defaultdict(list)
+        self._globals:   list[GlobalCallback]           = []
+
+    # ── Bind / unbind ─────────────────────────────────────────────────────────
+
+    def bind(self, event: str, fn: EventCallback) -> "EventEmitter":
+        """Register a listener for `event`. Returns self for chaining."""
+        self._listeners[event].append(fn)
+        return self
+
+    def on(self, event: str, fn: EventCallback) -> "EventEmitter":
+        """Alias for bind()."""
+        return self.bind(event, fn)
+
+    def unbind(self, event: str, fn: EventCallback | None = None) -> "EventEmitter":
+        """
+        Remove a listener.
+        If `fn` is omitted, all listeners for `event` are removed.
+        """
+        if fn is None:
+            self._listeners.pop(event, None)
+        else:
+            self._listeners[event] = [f for f in self._listeners[event] if f is not fn]
+        return self
+
+    def off(self, event: str, fn: EventCallback | None = None) -> "EventEmitter":
+        """Alias for unbind()."""
+        return self.unbind(event, fn)
+
+    def bind_global(self, fn: GlobalCallback) -> "EventEmitter":
+        """Listen to every event emitted on this emitter."""
+        self._globals.append(fn)
+        return self
+
+    def unbind_global(self, fn: GlobalCallback | None = None) -> "EventEmitter":
+        """Remove a global listener (or all if fn is omitted)."""
+        if fn is None:
+            self._globals.clear()
+        else:
+            self._globals = [f for f in self._globals if f is not fn]
+        return self
+
+    # ── Emit ──────────────────────────────────────────────────────────────────
+
+    def _emit(self, event: str, data: Any = None) -> None:
+        """Fire all listeners for `event` with `data`."""
+        for fn in list(self._listeners.get(event, [])):
+            fn(data)
+        for fn in list(self._globals):
+            fn(event, data)

amarwave-2.0.0/amarwave/types.py

@@ -0,0 +1,37 @@
+"""
+AmarWave — Type definitions.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Literal
+
+# ── Connection state ──────────────────────────────────────────────────────────
+
+ConnectionState = Literal["initialized", "connecting", "connected", "disconnected"]
+
+# ── Callback types ────────────────────────────────────────────────────────────
+
+EventCallback = Callable[[Any], None]
+GlobalCallback = Callable[[str, Any], None]
+
+# ── Cluster map ───────────────────────────────────────────────────────────────
+
+ClusterName = Literal["default", "local", "eu", "us", "ap1", "ap2"]
+
+CLUSTERS: dict[str, dict[str, str]] = {
+    "default": {
+        "ws": "ws://amarwave.com",
+        "wss": "wss://amarwave.com",
+        "api": "https://amarwave.com",
+    },
+    "local": {
+        "ws": "ws://amarwave.com",
+        "wss": "wss://amarwave.com",
+        "api": "https://amarwave.com",
+    },
+    "eu": {"ws": "ws://amarwave.com", "wss": "wss://amarwave.com", "api": "https://amarwave.com"},
+    "us": {"ws": "ws://amarwave.com", "wss": "wss://amarwave.com", "api": "https://amarwave.com"},
+    "ap1": {"ws": "ws://amarwave.com", "wss": "wss://amarwave.com", "api": "https://amarwave.com"},
+    "ap2": {"ws": "ws://amarwave.com", "wss": "wss://amarwave.com", "api": "https://amarwave.com"},
+}

amarwave-2.0.0/amarwave.egg-info/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: amarwave
+Version: 2.0.0
+Summary: Real-time WebSocket client for AmarWave servers
+Author-email: AmarWave <mehedinaeem66@gmail.com>
+License: MIT
+Project-URL: Homepage, https://amarwave.com
+Project-URL: Repository, https://github.com/amarwave/amarwave-python
+Project-URL: Issues, https://github.com/amarwave/amarwave-python/issues
+Keywords: websocket,realtime,pubsub,amarwave,async
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: websockets>=12.0
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# amarwave
+
+Official Python client for [AmarWave](https://amarwave.com) real-time messaging — async, typed, zero boilerplate.
+
+[![PyPI version](https://img.shields.io/pypi/v/amarwave)](https://pypi.org/project/amarwave/)
+[![Python](https://img.shields.io/pypi/pyversions/amarwave)](https://pypi.org/project/amarwave/)
+[![License](https://img.shields.io/pypi/l/amarwave)](LICENSE)
+
+---
+
+## Installation
+
+```bash
+pip install amarwave
+```
+
+---
+
+## Quick Start
+
+```python
+import asyncio
+from amarwave import AmarWave
+
+async def main():
+    aw = AmarWave(
+        app_key    = "YOUR_APP_KEY",
+        app_secret = "YOUR_APP_SECRET",
+    )
+
+    ch = await aw.subscribe("public-chat")
+    ch.bind("message", lambda data: print(data["user"], data["text"]))
+
+    await ch.publish("message", {"user": "Ali", "text": "Hello!"})
+    await aw.listen()  # keep alive forever
+
+asyncio.run(main())
+```
+
+---
+
+## Configuration
+
+| Parameter             | Type  | Default          | Description                                    |
+|-----------------------|-------|------------------|------------------------------------------------|
+| `app_key`             | str   | —                | Your app key **(required)**                    |
+| `app_secret`          | str   | `""`             | App secret for HMAC channel auth               |
+| `cluster`             | str   | `"default"`      | `"default"` \| `"eu"` \| `"us"` \| `"ap1"` \| `"ap2"` |
+| `auth_endpoint`       | str   | `"/broadcasting/auth"` | Server auth URL for private/presence channels |
+| `auth_headers`        | dict  | `{}`             | Headers sent to the auth endpoint              |
+| `reconnect_delay`     | float | `1.0`            | Base reconnect delay in seconds                |
+| `max_reconnect_delay` | float | `30.0`           | Max reconnect delay in seconds                 |
+| `max_retries`         | int   | `5`              | Max reconnect attempts (0 = infinite)          |
+| `activity_timeout`    | float | `120.0`          | Seconds between keepalive pings                |
+| `pong_timeout`        | float | `30.0`           | Seconds to wait for pong before reconnecting   |
+
+### Clusters
+
+All clusters connect to `amarwave.com`. The `cluster` parameter is reserved for future regional routing.
+
+| Cluster   | WebSocket                  | API                        |
+|-----------|----------------------------|----------------------------|
+| `default` | `wss://amarwave.com`       | `https://amarwave.com`     |
+| `eu`      | `wss://amarwave.com`       | `https://amarwave.com`     |
+| `us`      | `wss://amarwave.com`       | `https://amarwave.com`     |
+| `ap1`     | `wss://amarwave.com`       | `https://amarwave.com`     |
+| `ap2`     | `wss://amarwave.com`       | `https://amarwave.com`     |
+
+```python
+aw = AmarWave(app_key="KEY", app_secret="SECRET", cluster="eu")
+```
+
+---
+
+## Channel API
+
+```python
+ch = await aw.subscribe("public-chat")
+
+ch.bind("message", handler)           # listen for event
+ch.bind_global(lambda e, d: ...)      # listen for all events on this channel
+ch.unbind("message", handler)         # remove listener
+await ch.publish("message", data)     # publish via HTTP API → bool
+await aw.publish("ch", "ev", data)    # top-level publish shortcut
+
+ch.name        # "public-chat"
+ch.subscribed  # True when server confirmed subscription
+```
+
+---
+
+## Connection Events
+
+```python
+aw.bind("connecting",   lambda _: print("Connecting…"))
+aw.bind("connected",    lambda _: print(f"Connected: {aw.socket_id}"))
+aw.bind("disconnected", lambda _: print("Disconnected"))
+aw.bind("error",        lambda e: print(f"Error: {e}"))
+```
+
+---
+
+## Private & Presence Channels
+
+```python
+# Client-side HMAC auth (app_secret required)
+aw = AmarWave(app_key="KEY", app_secret="SECRET")
+ch = await aw.subscribe("private-orders")    # auto-signed
+ch = await aw.subscribe("presence-room-1")  # auto-signed
+
+# Server-side auth (omit app_secret, provide auth_endpoint)
+aw = AmarWave(
+    app_key       = "KEY",
+    auth_endpoint = "https://yourapp.com/api/broadcasting/auth",
+    auth_headers  = {"Authorization": f"Bearer {token}"},
+)
+ch = await aw.subscribe("private-orders")
+```
+
+---
+
+## Django Integration
+
+```python
+import asyncio
+from amarwave import AmarWave
+
+# One-shot publish from a sync Django view
+def notify_user(user_id: int, message: str) -> bool:
+    async def _publish() -> bool:
+        aw = AmarWave(app_key="KEY", app_secret="SECRET")
+        return await aw.publish(f"private-user-{user_id}", "notification", {"message": message})
+    return asyncio.run(_publish())
+```
+
+---
+
+## FastAPI Integration
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from amarwave import AmarWave
+
+aw = AmarWave(app_key="KEY", app_secret="SECRET")
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    ch = await aw.subscribe("public-updates")
+    ch.bind("message", lambda d: print(d))
+    yield
+    await aw.disconnect()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.post("/notify")
+async def notify(message: str):
+    await aw.publish("public-updates", "message", {"text": message})
+    return {"ok": True}
+```
+
+---
+
+## Requirements
+
+- Python 3.10+
+- `websockets >= 12.0`
+- `httpx >= 0.27.0`
+
+---
+
+## License
+
+MIT © AmarWave

amarwave-2.0.0/amarwave.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+amarwave/__init__.py
+amarwave/channel.py
+amarwave/client.py
+amarwave/crypto.py
+amarwave/emitter.py
+amarwave/types.py
+amarwave.egg-info/PKG-INFO
+amarwave.egg-info/SOURCES.txt
+amarwave.egg-info/dependency_links.txt
+amarwave.egg-info/requires.txt
+amarwave.egg-info/top_level.txt

amarwave-2.0.0/amarwave.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

amarwave-2.0.0/amarwave.egg-info/requires.txt

@@ -0,0 +1,9 @@
+websockets>=12.0
+httpx>=0.27.0
+
+[dev]
+pytest>=8.0
+pytest-asyncio>=0.23
+black
+mypy
+ruff

amarwave-2.0.0/amarwave.egg-info/top_level.txt

@@ -0,0 +1 @@
+amarwave

amarwave-2.0.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires      = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name        = "amarwave"
+version     = "2.0.0"
+description = "Real-time WebSocket client for AmarWave servers"
+readme      = "README.md"
+license     = { text = "MIT" }
+authors     = [{ name = "AmarWave", email = "mehedinaeem66@gmail.com" }]
+keywords    = ["websocket", "realtime", "pubsub", "amarwave", "async"]
+
+requires-python = ">=3.10"
+
+dependencies = [
+    "websockets>=12.0",
+    "httpx>=0.27.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "black",
+    "mypy",
+    "ruff",
+]
+
+[project.urls]
+Homepage   = "https://amarwave.com"
+Repository = "https://github.com/amarwave/amarwave-python"
+Issues     = "https://github.com/amarwave/amarwave-python/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["amarwave*"]
+
+[tool.black]
+line-length = 100
+
+[tool.ruff]
+line-length = 100
+
+[tool.mypy]
+strict = true
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

amarwave-2.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+