commandless-relay 0.1.0__tar.gz

commandless_relay-0.1.0/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: commandless-relay
+Version: 0.1.0
+Summary: Python SDK for Commandless relay API
+Author: Commandless
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Provides-Extra: discord
+Requires-Dist: discord.py>=2.4.0; extra == "discord"
+
+# commandless-relay (Python)
+
+Official Python SDK for the Commandless relay API.
+
+This package gives Python bots a simple client and a ready-to-use `discord.py` adapter.
+
+## Install
+
+Core client:
+
+```bash
+pip install commandless-relay
+```
+
+With `discord.py` adapter support:
+
+```bash
+pip install "commandless-relay[discord]"
+```
+
+## Quickstart (`discord.py`)
+
+```python
+import os
+import discord
+from commandless_relay import RelayClient, use_discord_adapter
+
+TOKEN = os.getenv("BOT_TOKEN")
+API_KEY = os.getenv("COMMANDLESS_API_KEY")
+BASE_URL = os.getenv("COMMANDLESS_SERVICE_URL")
+
+intents = discord.Intents.default()
+intents.message_content = True
+intents.messages = True
+intents.guilds = True
+
+client = discord.Client(intents=intents)
+relay = RelayClient(api_key=API_KEY, base_url=BASE_URL)
+
+use_discord_adapter(client, relay, mention_required=True)
+
+@client.event
+async def on_ready():
+    print(f"Logged in as {client.user}")
+
+client.run(TOKEN)
+```
+
+## Environment variables
+
+- `BOT_TOKEN` - your Discord bot token
+- `COMMANDLESS_API_KEY` - API key created in Commandless dashboard
+- `COMMANDLESS_SERVICE_URL` - your Commandless backend URL
+- `COMMANDLESS_HMAC_SECRET` - optional HMAC secret
+
+## Included components
+
+- `RelayClient`
+  - `send_event(event)` -> Decision dict or `None`
+  - `register_bot(...)` -> botId (optional flow)
+  - `heartbeat()` (optional flow)
+- `use_discord_adapter(client, relay, mention_required=True, execute=None)`
+  - binds an `on_message` listener
+  - sends events to relay
+  - executes reply actions by default
+  - sends a clear message on billing rejection (402 / no subscription or credits)

commandless_relay-0.1.0/README.md

@@ -0,0 +1,66 @@
+# commandless-relay (Python)
+
+Official Python SDK for the Commandless relay API.
+
+This package gives Python bots a simple client and a ready-to-use `discord.py` adapter.
+
+## Install
+
+Core client:
+
+```bash
+pip install commandless-relay
+```
+
+With `discord.py` adapter support:
+
+```bash
+pip install "commandless-relay[discord]"
+```
+
+## Quickstart (`discord.py`)
+
+```python
+import os
+import discord
+from commandless_relay import RelayClient, use_discord_adapter
+
+TOKEN = os.getenv("BOT_TOKEN")
+API_KEY = os.getenv("COMMANDLESS_API_KEY")
+BASE_URL = os.getenv("COMMANDLESS_SERVICE_URL")
+
+intents = discord.Intents.default()
+intents.message_content = True
+intents.messages = True
+intents.guilds = True
+
+client = discord.Client(intents=intents)
+relay = RelayClient(api_key=API_KEY, base_url=BASE_URL)
+
+use_discord_adapter(client, relay, mention_required=True)
+
+@client.event
+async def on_ready():
+    print(f"Logged in as {client.user}")
+
+client.run(TOKEN)
+```
+
+## Environment variables
+
+- `BOT_TOKEN` - your Discord bot token
+- `COMMANDLESS_API_KEY` - API key created in Commandless dashboard
+- `COMMANDLESS_SERVICE_URL` - your Commandless backend URL
+- `COMMANDLESS_HMAC_SECRET` - optional HMAC secret
+
+## Included components
+
+- `RelayClient`
+  - `send_event(event)` -> Decision dict or `None`
+  - `register_bot(...)` -> botId (optional flow)
+  - `heartbeat()` (optional flow)
+- `use_discord_adapter(client, relay, mention_required=True, execute=None)`
+  - binds an `on_message` listener
+  - sends events to relay
+  - executes reply actions by default
+  - sends a clear message on billing rejection (402 / no subscription or credits)

commandless_relay-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "commandless-relay"
+version = "0.1.0"
+description = "Python SDK for Commandless relay API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [
+  { name = "Commandless" }
+]
+dependencies = [
+  "requests>=2.31.0"
+]
+
+[project.optional-dependencies]
+discord = ["discord.py>=2.4.0"]
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

commandless_relay-0.1.0/setup.cfg

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

commandless_relay-0.1.0/src/commandless_relay/__init__.py

@@ -0,0 +1,9 @@
+from .client import RelayClient, RelayError
+from .discord_adapter import DiscordAdapter, use_discord_adapter
+
+__all__ = [
+    "RelayClient",
+    "RelayError",
+    "DiscordAdapter",
+    "use_discord_adapter",
+]

commandless_relay-0.1.0/src/commandless_relay/client.py

@@ -0,0 +1,143 @@
+import base64
+import hashlib
+import hmac
+import json
+import time
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+import requests
+
+DEFAULT_BASE = "https://commandless-app-production.up.railway.app"
+
+
+@dataclass
+class RelayError(Exception):
+    status: int
+    message: str
+    raw_error: Optional[str] = None
+
+    def __str__(self) -> str:
+        return f"Commandless error ({self.status}): {self.message}"
+
+
+class RelayClient:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: Optional[str] = None,
+        hmac_secret: Optional[str] = None,
+        timeout_ms: int = 15000,
+        max_retries: int = 3,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        base = base_url or DEFAULT_BASE
+        if not base.startswith(("http://", "https://")):
+            base = f"https://{base}"
+        self.base_url = base.rstrip("/")
+        self.hmac_secret = hmac_secret
+        self.timeout = max(timeout_ms / 1000.0, 1)
+        self.max_retries = max_retries
+        self.bot_id: Optional[str] = None
+
+    def register_bot(
+        self,
+        platform: str = "discord",
+        name: Optional[str] = None,
+        client_id: Optional[str] = None,
+        bot_id: Optional[int] = None,
+    ) -> Optional[str]:
+        payload: Dict[str, Any] = {
+            "platform": platform,
+            "name": name,
+            "clientId": client_id,
+            "botId": bot_id,
+        }
+        res = self._post_json("/v1/relay/register", payload)
+        if res.get("ok") and isinstance(res.get("data"), dict) and res["data"].get("botId"):
+            self.bot_id = str(res["data"]["botId"])
+            return self.bot_id
+        return None
+
+    def heartbeat(self) -> Optional[Dict[str, Any]]:
+        res = self._post_json("/v1/relay/heartbeat", {"botId": self.bot_id})
+        if res.get("ok"):
+            return res.get("data")
+        return None
+
+    def send_event(self, event: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        payload = dict(event)
+        if self.bot_id and "botId" not in payload:
+            payload["botId"] = self.bot_id
+        idem = self._make_idempotency_key(payload)
+
+        last_error: Optional[RelayError] = None
+        for attempt in range(self.max_retries + 1):
+            res = self._post_json("/v1/relay/events", payload, idempotency_key=idem)
+            if res.get("ok"):
+                data = res.get("data") or {}
+                if isinstance(data, dict):
+                    return data.get("decision")
+                return None
+
+            status = int(res.get("status", 0))
+            err_text = str(res.get("error") or "unknown")
+            parsed_message = self._extract_error_message(err_text) or err_text
+            last_error = RelayError(status=status, message=parsed_message, raw_error=err_text)
+            time.sleep(0.2 * (attempt + 1))
+
+        if last_error:
+            raise last_error
+        raise RelayError(status=0, message="Unknown relay failure")
+
+    def _make_idempotency_key(self, event: Dict[str, Any]) -> str:
+        base = f"{event.get('type')}:{event.get('id')}:{int(int(event.get('timestamp', int(time.time() * 1000))) / 1000)}"
+        return base64.urlsafe_b64encode(base.encode("utf-8")).decode("utf-8").rstrip("=")
+
+    def _extract_error_message(self, text: str) -> Optional[str]:
+        try:
+            data = json.loads(text)
+            if isinstance(data, dict):
+                return str(data.get("message") or data.get("error") or "")
+        except Exception:
+            pass
+        return None
+
+    def _post_json(
+        self,
+        path: str,
+        body: Dict[str, Any],
+        idempotency_key: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        url = f"{self.base_url}{path}"
+        json_body = json.dumps(body, separators=(",", ":"))
+        headers = {
+            "content-type": "application/json",
+            "x-api-key": self.api_key,
+            "x-commandless-key": self.api_key,
+            "x-timestamp": str(int(time.time() * 1000)),
+        }
+        if idempotency_key:
+            headers["x-idempotency-key"] = idempotency_key
+        if self.hmac_secret:
+            signature = hmac.new(
+                self.hmac_secret.encode("utf-8"),
+                json_body.encode("utf-8"),
+                hashlib.sha256,
+            ).hexdigest()
+            headers["x-signature"] = signature
+
+        try:
+            response = requests.post(
+                url,
+                data=json_body,
+                headers=headers,
+                timeout=self.timeout,
+            )
+            if not response.ok:
+                return {"ok": False, "status": response.status_code, "error": response.text}
+            return {"ok": True, "status": response.status_code, "data": response.json()}
+        except Exception as exc:
+            return {"ok": False, "status": 0, "error": str(exc)}

commandless_relay-0.1.0/src/commandless_relay/discord_adapter.py

@@ -0,0 +1,113 @@
+import asyncio
+import time
+from typing import Any, Awaitable, Callable, Dict, Optional
+
+from .client import RelayClient, RelayError
+
+DecisionHandler = Callable[[Dict[str, Any], Any], Awaitable[None]]
+
+
+class DiscordAdapter:
+    def __init__(
+        self,
+        client: Any,
+        relay: RelayClient,
+        mention_required: bool = True,
+        execute: Optional[DecisionHandler] = None,
+    ) -> None:
+        self.client = client
+        self.relay = relay
+        self.mention_required = mention_required
+        self.execute = execute
+
+    def bind(self) -> None:
+        self.client.add_listener(self._on_message, "on_message")
+
+    async def _on_message(self, message: Any) -> None:
+        if not message or not getattr(message, "author", None):
+            return
+        if getattr(message.author, "bot", False):
+            return
+
+        mentioned = False
+        try:
+            mentioned = bool(self.client.user and self.client.user in message.mentions)
+        except Exception:
+            mentioned = False
+
+        is_reply_to_bot = False
+        try:
+            if getattr(message, "reference", None) and getattr(message.reference, "resolved", None):
+                ref = message.reference.resolved
+                if getattr(ref, "author", None) and self.client.user:
+                    is_reply_to_bot = ref.author.id == self.client.user.id
+        except Exception:
+            is_reply_to_bot = False
+
+        if self.mention_required and not mentioned and not is_reply_to_bot:
+            return
+
+        event = {
+            "type": "messageCreate",
+            "id": str(message.id),
+            "guildId": str(message.guild.id) if getattr(message, "guild", None) else None,
+            "channelId": str(message.channel.id),
+            "authorId": str(message.author.id),
+            "content": str(message.content or ""),
+            "timestamp": int((getattr(message, "created_at", None) or time.time()).timestamp() * 1000)
+            if getattr(message, "created_at", None)
+            else int(time.time() * 1000),
+            "botClientId": str(self.client.user.id) if getattr(self.client, "user", None) else None,
+            "isReplyToBot": is_reply_to_bot,
+            "referencedMessageId": str(message.reference.message_id) if getattr(message, "reference", None) and getattr(message.reference, "message_id", None) else None,
+        }
+
+        try:
+            async with message.channel.typing():
+                decision = await asyncio.to_thread(self.relay.send_event, event)
+
+            if not decision:
+                return
+
+            if self.execute:
+                await self.execute(decision, message)
+            else:
+                await self._default_execute(decision, message)
+        except RelayError as err:
+            msg = str(err)
+            if err.status == 402 or "SUBSCRIPTION_REQUIRED" in msg or "Payment Required" in msg:
+                try:
+                    await message.reply(
+                        "This bot's Commandless subscription is inactive or out of free credits. "
+                        "Please ask the bot owner to update billing."
+                    )
+                except Exception:
+                    pass
+        except Exception:
+            # Keep adapter resilient by default
+            pass
+
+    async def _default_execute(self, decision: Dict[str, Any], message: Any) -> None:
+        actions = decision.get("actions") or []
+        for action in actions:
+            if action.get("kind") == "reply":
+                content = action.get("content")
+                if content:
+                    await message.reply(str(content))
+                return
+
+
+def use_discord_adapter(
+    client: Any,
+    relay: RelayClient,
+    mention_required: bool = True,
+    execute: Optional[DecisionHandler] = None,
+) -> DiscordAdapter:
+    adapter = DiscordAdapter(
+        client=client,
+        relay=relay,
+        mention_required=mention_required,
+        execute=execute,
+    )
+    adapter.bind()
+    return adapter

commandless_relay-0.1.0/src/commandless_relay.egg-info/PKG-INFO

@@ -0,0 +1,78 @@
+Metadata-Version: 2.4
+Name: commandless-relay
+Version: 0.1.0
+Summary: Python SDK for Commandless relay API
+Author: Commandless
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.31.0
+Provides-Extra: discord
+Requires-Dist: discord.py>=2.4.0; extra == "discord"
+
+# commandless-relay (Python)
+
+Official Python SDK for the Commandless relay API.
+
+This package gives Python bots a simple client and a ready-to-use `discord.py` adapter.
+
+## Install
+
+Core client:
+
+```bash
+pip install commandless-relay
+```
+
+With `discord.py` adapter support:
+
+```bash
+pip install "commandless-relay[discord]"
+```
+
+## Quickstart (`discord.py`)
+
+```python
+import os
+import discord
+from commandless_relay import RelayClient, use_discord_adapter
+
+TOKEN = os.getenv("BOT_TOKEN")
+API_KEY = os.getenv("COMMANDLESS_API_KEY")
+BASE_URL = os.getenv("COMMANDLESS_SERVICE_URL")
+
+intents = discord.Intents.default()
+intents.message_content = True
+intents.messages = True
+intents.guilds = True
+
+client = discord.Client(intents=intents)
+relay = RelayClient(api_key=API_KEY, base_url=BASE_URL)
+
+use_discord_adapter(client, relay, mention_required=True)
+
+@client.event
+async def on_ready():
+    print(f"Logged in as {client.user}")
+
+client.run(TOKEN)
+```
+
+## Environment variables
+
+- `BOT_TOKEN` - your Discord bot token
+- `COMMANDLESS_API_KEY` - API key created in Commandless dashboard
+- `COMMANDLESS_SERVICE_URL` - your Commandless backend URL
+- `COMMANDLESS_HMAC_SECRET` - optional HMAC secret
+
+## Included components
+
+- `RelayClient`
+  - `send_event(event)` -> Decision dict or `None`
+  - `register_bot(...)` -> botId (optional flow)
+  - `heartbeat()` (optional flow)
+- `use_discord_adapter(client, relay, mention_required=True, execute=None)`
+  - binds an `on_message` listener
+  - sends events to relay
+  - executes reply actions by default
+  - sends a clear message on billing rejection (402 / no subscription or credits)

commandless_relay-0.1.0/src/commandless_relay.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+README.md
+pyproject.toml
+src/commandless_relay/__init__.py
+src/commandless_relay/client.py
+src/commandless_relay/discord_adapter.py
+src/commandless_relay.egg-info/PKG-INFO
+src/commandless_relay.egg-info/SOURCES.txt
+src/commandless_relay.egg-info/dependency_links.txt
+src/commandless_relay.egg-info/requires.txt
+src/commandless_relay.egg-info/top_level.txt

commandless_relay-0.1.0/src/commandless_relay.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

commandless_relay-0.1.0/src/commandless_relay.egg-info/requires.txt

@@ -0,0 +1,4 @@
+requests>=2.31.0
+
+[discord]
+discord.py>=2.4.0

commandless_relay-0.1.0/src/commandless_relay.egg-info/top_level.txt

@@ -0,0 +1 @@
+commandless_relay