markanm 0.1.0a1__tar.gz

markanm-0.1.0a1/LICENSE

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

markanm-0.1.0a1/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: markanm
+Version: 0.1.0a1
+Summary: Official Python SDK for MarkanM Chat Bot Platform & REST API (v0.1.0-alpha)
+Author-email: MarkanM Developer Team <developers@markanm.com>
+License: MIT License
+        
+        Copyright (c) 2026 MarkanM Developer Team
+        
+        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.
+        
+Project-URL: Homepage, https://chat.markanm.com/developers
+Project-URL: Documentation, https://chat.markanm.com/developers/docs
+Project-URL: Repository, https://github.com/markanm/markanm-python-sdk
+Keywords: markanm,bot,chat,sdk,api,oauth,webhooks
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Dynamic: license-file
+
+# MarkanM Official Python SDK (`markanm 0.1.0a1`)
+
+Official Python library (v0.1.0-alpha) for building developer bots, automation, and AI agents on **MarkanM Chat** (`https://chat.markanm.com`).
+
+---
+
+## ⚠️ Alpha Release Notice
+
+This is **v0.1.0-alpha** (`markanm 0.1.0a1`). It is intended for testing against the MarkanM Bot API v1.
+
+---
+
+## 🚀 Installation
+
+Install via `pip`:
+
+```bash
+pip install markanm
+```
+
+---
+
+## ⚡ Quick Start
+
+### 1. Simple Hello Bot (`hello_bot.py`)
+
+```python
+import os
+from markanm import Bot
+
+bot = Bot(os.environ["MARKANM_BOT_TOKEN"])
+
+@bot.command("hello")
+async def hello(ctx):
+    await ctx.reply("Hello 👋 Welcome to MarkanM!")
+
+@bot.command("start")
+async def start(ctx):
+    await ctx.reply("🚀 Bot activated and ready!")
+
+if __name__ == "__main__":
+    bot.run_polling()
+```
+
+---
+
+### 2. Event Listeners
+
+```python
+@bot.on("message.created")
+async def on_message(event):
+    print(f"New message received: {event.payload}")
+
+@bot.on("member.joined")
+def on_member_joined(event):
+    print(f"User joined room: {event.payload.get('user')}")
+```
+
+---
+
+### 3. AI Assistant Bot (`ai_bot.py`)
+
+```python
+import os
+from markanm import Bot
+from markanm.ai import AI
+
+bot = Bot(os.environ["MARKANM_BOT_TOKEN"])
+ai = AI(provider="openai", api_key=os.environ["OPENAI_API_KEY"])
+
+@bot.command("ask")
+async def ask(ctx):
+    prompt = " ".join(ctx.args)
+    if not prompt:
+        await ctx.reply("Usage: /ask <question>")
+        return
+
+    answer = await ai.generate(prompt)
+    await ctx.reply(answer)
+
+bot.run_polling()
+```
+
+---
+
+### 4. Webhook Verification (Flask / FastAPI)
+
+```python
+from markanm import WebhookHandler, MarkanMWebhookError
+
+handler = WebhookHandler(secret="whsec_YOUR_SECRET", timestamp_tolerance=300)
+
+try:
+    # Verifies HMAC-SHA256 signature header and 300s timestamp tolerance
+    event = handler.process_event(request_body_text, request_headers.get("X-MarkanM-Signature"))
+    print(f"Event verified: {event.id} ({event.type})")
+except MarkanMWebhookError as err:
+    print(f"Webhook error: {err}")
+```
+
+---
+
+## 🧪 Testing
+
+Run tests with `pytest`:
+
+```bash
+pytest sdk/python/tests/
+```
+
+---
+
+## 📚 API Reference
+For complete API endpoints and permission scope guidelines, visit:
+**https://chat.markanm.com/developers/docs**

markanm-0.1.0a1/README.md

@@ -0,0 +1,115 @@
+# MarkanM Official Python SDK (`markanm 0.1.0a1`)
+
+Official Python library (v0.1.0-alpha) for building developer bots, automation, and AI agents on **MarkanM Chat** (`https://chat.markanm.com`).
+
+---
+
+## ⚠️ Alpha Release Notice
+
+This is **v0.1.0-alpha** (`markanm 0.1.0a1`). It is intended for testing against the MarkanM Bot API v1.
+
+---
+
+## 🚀 Installation
+
+Install via `pip`:
+
+```bash
+pip install markanm
+```
+
+---
+
+## ⚡ Quick Start
+
+### 1. Simple Hello Bot (`hello_bot.py`)
+
+```python
+import os
+from markanm import Bot
+
+bot = Bot(os.environ["MARKANM_BOT_TOKEN"])
+
+@bot.command("hello")
+async def hello(ctx):
+    await ctx.reply("Hello 👋 Welcome to MarkanM!")
+
+@bot.command("start")
+async def start(ctx):
+    await ctx.reply("🚀 Bot activated and ready!")
+
+if __name__ == "__main__":
+    bot.run_polling()
+```
+
+---
+
+### 2. Event Listeners
+
+```python
+@bot.on("message.created")
+async def on_message(event):
+    print(f"New message received: {event.payload}")
+
+@bot.on("member.joined")
+def on_member_joined(event):
+    print(f"User joined room: {event.payload.get('user')}")
+```
+
+---
+
+### 3. AI Assistant Bot (`ai_bot.py`)
+
+```python
+import os
+from markanm import Bot
+from markanm.ai import AI
+
+bot = Bot(os.environ["MARKANM_BOT_TOKEN"])
+ai = AI(provider="openai", api_key=os.environ["OPENAI_API_KEY"])
+
+@bot.command("ask")
+async def ask(ctx):
+    prompt = " ".join(ctx.args)
+    if not prompt:
+        await ctx.reply("Usage: /ask <question>")
+        return
+
+    answer = await ai.generate(prompt)
+    await ctx.reply(answer)
+
+bot.run_polling()
+```
+
+---
+
+### 4. Webhook Verification (Flask / FastAPI)
+
+```python
+from markanm import WebhookHandler, MarkanMWebhookError
+
+handler = WebhookHandler(secret="whsec_YOUR_SECRET", timestamp_tolerance=300)
+
+try:
+    # Verifies HMAC-SHA256 signature header and 300s timestamp tolerance
+    event = handler.process_event(request_body_text, request_headers.get("X-MarkanM-Signature"))
+    print(f"Event verified: {event.id} ({event.type})")
+except MarkanMWebhookError as err:
+    print(f"Webhook error: {err}")
+```
+
+---
+
+## 🧪 Testing
+
+Run tests with `pytest`:
+
+```bash
+pytest sdk/python/tests/
+```
+
+---
+
+## 📚 API Reference
+For complete API endpoints and permission scope guidelines, visit:
+**https://chat.markanm.com/developers/docs**

markanm-0.1.0a1/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "markanm"
+version = "0.1.0a1"
+description = "Official Python SDK for MarkanM Chat Bot Platform & REST API (v0.1.0-alpha)"
+readme = "README.md"
+authors = [
+  { name = "MarkanM Developer Team", email = "developers@markanm.com" }
+]
+license = { file = "LICENSE" }
+requires-python = ">=3.8"
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Communications :: Chat",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+keywords = ["markanm", "bot", "chat", "sdk", "api", "oauth", "webhooks"]
+dependencies = [
+  "httpx>=0.24.0"
+]
+
+[project.urls]
+Homepage = "https://chat.markanm.com/developers"
+Documentation = "https://chat.markanm.com/developers/docs"
+Repository = "https://github.com/markanm/markanm-python-sdk"

markanm-0.1.0a1/setup.cfg

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

markanm-0.1.0a1/setup.py

@@ -0,0 +1,8 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="markanm",
+    version="0.1.0a1",
+    packages=find_packages(where="src"),
+    package_dir={"": "src"},
+)

markanm-0.1.0a1/src/markanm/__init__.py

@@ -0,0 +1,41 @@
+"""
+MarkanM Official Python SDK (v0.1.0-alpha)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Official Python library for building developer bots, automation, and AI agents on MarkanM Chat.
+"""
+
+__version__ = "0.1.0a1"
+__author__ = "MarkanM Developer Team"
+
+from .bot import Bot
+from .context import CommandContext
+from .events import Event
+from .webhook import WebhookHandler
+from .ai import AI
+from .exceptions import (
+    MarkanMError,
+    MarkanMAPIError,
+    MarkanMAuthError,
+    MarkanMPermissionError,
+    MarkanMNotFoundError,
+    MarkanMRateLimitError,
+    MarkanMWebhookError,
+    MarkanMValidationError
+)
+
+__all__ = [
+    "Bot",
+    "CommandContext",
+    "Event",
+    "WebhookHandler",
+    "AI",
+    "MarkanMError",
+    "MarkanMAPIError",
+    "MarkanMAuthError",
+    "MarkanMPermissionError",
+    "MarkanMNotFoundError",
+    "MarkanMRateLimitError",
+    "MarkanMWebhookError",
+    "MarkanMValidationError"
+]

markanm-0.1.0a1/src/markanm/ai.py

@@ -0,0 +1,73 @@
+import json
+import asyncio
+from typing import Optional
+from .exceptions import MarkanMError, _mask_sensitive
+
+try:
+    import httpx
+    HAS_HTTPX = True
+except ImportError:
+    HAS_HTTPX = False
+    import urllib.request
+    import urllib.error
+
+class AI:
+    """
+    AI Integration Layer for MarkanM Developer Bots.
+    Allows developers to integrate OpenAI or custom HTTP AI model endpoints using their own credentials.
+    """
+    def __init__(self, provider: str = "openai", api_key: str = "", model: str = "gpt-3.5-turbo", base_url: Optional[str] = None):
+        self.provider = provider.lower().strip()
+        self.api_key = api_key
+        self.model = model
+        self.base_url = base_url or "https://api.openai.com/v1"
+
+    async def generate(self, prompt: str, system_prompt: str = "You are a helpful MarkanM Bot assistant.") -> str:
+        """
+        Generate text response from configured AI provider
+        """
+        if not prompt or not isinstance(prompt, str):
+            raise MarkanMError("Prompt must be a non-empty string")
+
+        if self.provider == "openai":
+            if not self.api_key:
+                raise MarkanMError("OpenAI API Key is required for OpenAI AI provider")
+
+            headers = {
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json"
+            }
+            payload = {
+                "model": self.model,
+                "messages": [
+                    {"role": "system", "content": system_prompt},
+                    {"role": "user", "content": prompt}
+                ]
+            }
+
+            if HAS_HTTPX:
+                async with httpx.AsyncClient(timeout=15.0) as client:
+                    try:
+                        res = await client.post(f"{self.base_url.rstrip('/')}/chat/completions", json=payload, headers=headers)
+                        if res.is_success:
+                            data = res.json()
+                            return data["choices"][0]["message"]["content"].strip()
+                        else:
+                            raise MarkanMError(f"AI Provider HTTP {res.status_code}: {res.text}")
+                    except Exception as exc:
+                        raise MarkanMError(f"AI Provider request failed: {_mask_sensitive(str(exc))}")
+            else:
+                def _sync_ai_request():
+                    req_data = json.dumps(payload).encode("utf-8")
+                    req = urllib.request.Request(f"{self.base_url.rstrip('/')}/chat/completions", data=req_data, headers=headers, method="POST")
+                    try:
+                        with urllib.request.urlopen(req, timeout=15) as resp:
+                            res_text = resp.read().decode("utf-8")
+                            data = json.loads(res_text)
+                            return data["choices"][0]["message"]["content"].strip()
+                    except Exception as exc:
+                        raise MarkanMError(f"AI Provider request failed: {_mask_sensitive(str(exc))}")
+
+                return await asyncio.to_thread(_sync_ai_request)
+
+        raise MarkanMError(f"Unsupported AI provider '{self.provider}'. Supported providers: 'openai'")

markanm-0.1.0a1/src/markanm/bot.py

@@ -0,0 +1,188 @@
+import asyncio
+import inspect
+import signal
+import sys
+from typing import Callable, Dict, List, Any, Optional
+from .client import APIClient
+from .context import CommandContext
+from .events import Event
+from .webhook import WebhookHandler
+from .exceptions import MarkanMError, _mask_sensitive
+
+class Bot:
+    """
+    Official MarkanM Bot Client (v0.1.0-alpha)
+    """
+    def __init__(
+        self,
+        token: str,
+        base_url: str = "https://chat.markanm.com/api/bot/v1",
+        timeout: float = 10.0,
+        webhook_secret: Optional[str] = None
+    ):
+        if not token or not isinstance(token, str):
+            raise MarkanMError("Bot token must be a non-empty string starting with 'mkbot_...'")
+
+        self.token = token
+        self.client = APIClient(token=token, base_url=base_url, timeout=timeout)
+        self.webhook_secret = webhook_secret
+        self.commands: Dict[str, Callable] = {}
+        self.listeners: Dict[str, List[Callable]] = {}
+        self._is_running = False
+
+    def command(self, name: str):
+        """
+        Decorator to register a bot command handler.
+        Usage:
+            @bot.command("hello")
+            async def hello_handler(ctx):
+                await ctx.reply("Hello 👋")
+        """
+        clean_name = name.lstrip("/").strip().lower()
+        def decorator(func: Callable):
+            self.commands[clean_name] = func
+            return func
+        return decorator
+
+    def on(self, event_type: str):
+        """
+        Decorator to register an event listener. Supports multiple listeners per event.
+        Usage:
+            @bot.on("message.created")
+            async def on_message(evt):
+                print(evt.type)
+        """
+        clean_type = event_type.strip()
+        def decorator(func: Callable):
+            if clean_type not in self.listeners:
+                self.listeners[clean_type] = []
+            self.listeners[clean_type].append(func)
+            return func
+        return decorator
+
+    async def get_me() -> Dict[str, Any]:
+        """Fetch bot's profile"""
+        return await self.client.get("/me")
+
+    async def get_room(self, room_id: str) -> Dict[str, Any]:
+        """Fetch room details"""
+        return await self.client.get(f"/rooms/{room_id}")
+
+    async def get_room_members(self, room_id: str) -> Dict[str, Any]:
+        """Fetch room members"""
+        return await self.client.get(f"/rooms/{room_id}/members")
+
+    async def send_message(self, room_id: str, text: str, card: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        """Send a text or interactive card message to a room"""
+        payload = {"text": text}
+        if card:
+            payload["card"] = card
+            payload["type"] = "card"
+        return await self.client.post(f"/rooms/{room_id}/messages", json_data=payload)
+
+    async def reply(self, message_id: str, text: str) -> Dict[str, Any]:
+        """Reply directly to a message"""
+        return await self.client.post(f"/messages/{message_id}/reply", json_data={"text": text})
+
+    async def react(self, message_id: str, emoji: str = "👍") -> Dict[str, Any]:
+        """Toggle emoji reaction on a message"""
+        return await self.client.post(f"/messages/{message_id}/react", json_data={"emoji": emoji})
+
+    async def delete_message(self, message_id: str) -> Dict[str, Any]:
+        """Delete a message"""
+        return await self.client.delete(f"/messages/{message_id}")
+
+    async def dispatch_event(self, event: Event):
+        """
+        Dispatch incoming Event to registered event listeners & command handlers
+        """
+        evt_type = event.type
+
+        # 1. Execute general event listeners
+        if evt_type in self.listeners:
+            for listener in self.listeners[evt_type]:
+                await self._invoke_handler(listener, event)
+
+        # 2. Execute command handler if event is 'command.received'
+        if evt_type == "command.received" or (isinstance(event.payload, dict) and "command" in event.payload):
+            cmd_payload = event.payload if isinstance(event.payload, dict) else {}
+            cmd_name = str(cmd_payload.get("command", "")).lstrip("/").strip().lower()
+
+            if cmd_name in self.commands:
+                ctx = CommandContext(self, cmd_payload)
+                handler = self.commands[cmd_name]
+                await self._invoke_handler(handler, ctx)
+
+    async def _invoke_handler(self, handler: Callable, arg: Any):
+        """Helper to invoke sync or async handler safely"""
+        try:
+            if inspect.iscoroutinefunction(handler):
+                await handler(arg)
+            else:
+                loop = asyncio.get_running_loop()
+                await loop.run_in_executor(None, handler, arg)
+        except Exception as exc:
+            safe_msg = _mask_sensitive(str(exc))
+            print(f"⚠️ Error executing handler {handler.__name__}: {safe_msg}")
+
+    def verify_webhook(self, payload_body: str, signature_header: str, secret: Optional[str] = None) -> bool:
+        """
+        Verify incoming webhook signature
+        """
+        sec = secret or self.webhook_secret
+        if not sec:
+            raise MarkanMError("Webhook secret must be specified to verify signatures")
+        handler = WebhookHandler(secret=sec)
+        return handler.verify(payload_body, signature_header)
+
+    async def handle_webhook(self, payload_body: str, signature_header: str, secret: Optional[str] = None) -> Event:
+        """
+        Verify signature, parse Event, and dispatch to handlers
+        """
+        sec = secret or self.webhook_secret
+        if not sec:
+            raise MarkanMError("Webhook secret must be specified to process webhooks")
+
+        wh_handler = WebhookHandler(secret=sec)
+        event = wh_handler.process_event(payload_body, signature_header)
+        await self.dispatch_event(event)
+        return event
+
+    def run_polling(self, interval: float = 2.0):
+        """
+        Run development polling event loop
+        """
+        print(f"🤖 MarkanM Bot running in development polling mode (interval: {interval}s)...")
+        self._is_running = True
+        loop = asyncio.get_event_loop()
+
+        try:
+            loop.run_until_complete(self._polling_loop(interval))
+        except (KeyboardInterrupt, SystemExit):
+            print("\n🛑 Shutting down MarkanM Bot...")
+        finally:
+            self._is_running = False
+
+    def run(self, mode: str = "polling", interval: float = 2.0):
+        """
+        Main entry point (alias for run_polling in alpha)
+        """
+        if mode == "polling":
+            self.run_polling(interval=interval)
+        else:
+            raise MarkanMError(f"Unsupported run mode '{mode}'. For webhooks, use framework Integration or bot.handle_webhook()")
+
+    async def _polling_loop(self, interval: float):
+        while self._is_running:
+            try:
+                res = await self.client.post("/polling")
+                events_data = res.get("events", [])
+                for evt_raw in events_data:
+                    event = Event(evt_raw)
+                    await self.dispatch_event(event)
+            except MarkanMError as err:
+                print(f"⚠️ MarkanM Polling Error: {err.message}")
+            except Exception as exc:
+                print(f"⚠️ Unexpected Polling Error: {_mask_sensitive(str(exc))}")
+
+            await asyncio.sleep(interval)

markanm-0.1.0a1/src/markanm/client.py

@@ -0,0 +1,128 @@
+import json
+import asyncio
+from typing import Dict, Any, Optional
+from .exceptions import (
+    MarkanMAPIError,
+    MarkanMAuthError,
+    MarkanMPermissionError,
+    MarkanMNotFoundError,
+    MarkanMRateLimitError,
+    MarkanMError
+)
+
+try:
+    import httpx
+    HAS_HTTPX = True
+except ImportError:
+    HAS_HTTPX = False
+    import urllib.request
+    import urllib.error
+
+class APIClient:
+    """
+    Async HTTP Client for MarkanM Bot API v1.
+    Uses httpx when installed, with automatic fallback to urllib.request.
+    """
+    def __init__(self, token: str, base_url: str = "https://chat.markanm.com/api/bot/v1", timeout: float = 10.0):
+        self.token = token
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _get_headers(self) -> Dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.token}",
+            "Content-Type": "application/json",
+            "User-Agent": "markanm-python-sdk/0.1.0a1"
+        }
+
+    async def request(
+        self,
+        method: str,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+        json_data: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        url = f"{self.base_url}/{endpoint.lstrip('/')}"
+        
+        if params:
+            from urllib.parse import urlencode
+            url += f"?{urlencode(params)}"
+
+        if HAS_HTTPX:
+            async with httpx.AsyncClient(timeout=self.timeout) as client:
+                try:
+                    response = await client.request(
+                        method=method.upper(),
+                        url=url,
+                        headers=self._get_headers(),
+                        json=json_data
+                    )
+                    status_code = response.status_code
+                    response_text = response.text
+                    request_id = response.headers.get("X-MarkanM-Request-ID")
+                    try:
+                        res_json = response.json()
+                    except Exception:
+                        res_json = {}
+                except httpx.TimeoutException:
+                    raise MarkanMError(f"HTTP Request to {url} timed out after {self.timeout}s")
+                except httpx.RequestError as exc:
+                    raise MarkanMError(f"Network error communicating with MarkanM API: {str(exc)}")
+        else:
+            # Fallback to urllib.request in executor thread
+            def _sync_urllib_request():
+                data_bytes = json.dumps(json_data).encode("utf-8") if json_data else None
+                req = urllib.request.Request(url, data=data_bytes, headers=self._get_headers(), method=method.upper())
+                try:
+                    with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                        body_bytes = resp.read()
+                        headers_dict = dict(resp.info())
+                        return resp.status, body_bytes.decode("utf-8"), headers_dict
+                except urllib.error.HTTPError as err:
+                    body_bytes = err.read()
+                    headers_dict = dict(err.headers)
+                    return err.code, body_bytes.decode("utf-8"), headers_dict
+                except Exception as exc:
+                    raise MarkanMError(f"Network error: {str(exc)}")
+
+            status_code, response_text, resp_headers = await asyncio.to_thread(_sync_urllib_request)
+            request_id = resp_headers.get("X-MarkanM-Request-ID") or resp_headers.get("x-markanm-request-id")
+            try:
+                res_json = json.loads(response_text)
+            except Exception:
+                res_json = {}
+
+        if 200 <= status_code < 300:
+            return res_json
+
+        # Parse API Error Payload
+        error_data = res_json.get("error", {})
+        if isinstance(error_data, dict):
+            err_code = error_data.get("code", "api_error")
+            err_msg = error_data.get("message", response_text or "API Error")
+        else:
+            err_code = "api_error"
+            err_msg = str(error_data) or response_text
+
+        if status_code == 401:
+            raise MarkanMAuthError(status_code, err_code, err_msg, request_id)
+        elif status_code == 403:
+            raise MarkanMPermissionError(status_code, err_code, err_msg, request_id)
+        elif status_code == 404:
+            raise MarkanMNotFoundError(status_code, err_code, err_msg, request_id)
+        elif status_code == 429:
+            raise MarkanMRateLimitError(status_code, err_code, err_msg, 60, request_id)
+        else:
+            raise MarkanMAPIError(status_code, err_code, err_msg, request_id)
+
+    async def get(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return await self.request("GET", endpoint, params=params)
+
+    async def post(self, endpoint: str, json_data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return await self.request("POST", endpoint, json_data=json_data)
+
+    async def patch(self, endpoint: str, json_data: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        return await self.request("PATCH", endpoint, json_data=json_data)
+
+    async def delete(self, endpoint: str) -> Dict[str, Any]:
+        return await self.request("DELETE", endpoint)

markanm-0.1.0a1/src/markanm/context.py

@@ -0,0 +1,54 @@
+from typing import Dict, Any, List
+
+class UserContext:
+    def __init__(self, data: Dict[str, Any]):
+        self.id = data.get("id")
+        self.username = data.get("username", "")
+        self.display_name = data.get("display_name", "")
+        self.avatar_url = data.get("avatar_url", "")
+
+class RoomContext:
+    def __init__(self, data: Dict[str, Any]):
+        self.id = data.get("id")
+        self.name = data.get("name", "")
+
+class MessageContext:
+    def __init__(self, data: Dict[str, Any]):
+        self.id = data.get("id")
+        self.text = data.get("text", "") or data.get("content", "")
+        self.type = data.get("type", "text")
+
+class CommandContext:
+    """
+    Context passed to command handlers: @bot.command("name")
+    """
+    def __init__(self, bot, payload: Dict[str, Any]):
+        self.bot = bot
+        self.raw_data = payload or {}
+        self.command = payload.get("command", "").lstrip("/")
+        
+        # Parse command arguments
+        raw_text = payload.get("text") or payload.get("message", {}).get("text", "")
+        self.text = raw_text
+        if "args" in payload and isinstance(payload["args"], list):
+            self.args = payload["args"]
+        else:
+            parts = raw_text.split()
+            self.args = parts[1:] if len(parts) > 1 else []
+
+        self.user = UserContext(payload.get("user") or {})
+        self.room = RoomContext(payload.get("room") or {"id": payload.get("conversation_id") or payload.get("room_id")})
+        self.message = MessageContext(payload.get("message") or {})
+
+    @property
+    def room_id(self):
+        return self.room.id
+
+    async def reply(self, content: str):
+        """Reply to room context"""
+        if not self.room_id:
+            raise ValueError("Cannot reply: missing room ID in context")
+        return await self.bot.send_message(self.room_id, content)
+
+    def __repr__(self) -> str:
+        return f"<CommandContext command='{self.command}' args={self.args} room_id={self.room_id}>"

markanm-0.1.0a1/src/markanm/events.py

@@ -0,0 +1,30 @@
+from typing import Dict, Any, Optional
+
+class Event:
+    """
+    MarkanM Platform Event Model
+    """
+    def __init__(self, data: Dict[str, Any]):
+        self.raw_data = data or {}
+        self.id = data.get("event_id") or data.get("id", "")
+        self.type = data.get("event_type") or data.get("event", "")
+        self.timestamp = data.get("timestamp") or data.get("created_at", "")
+        self.payload = data.get("payload") if "payload" in data else data
+
+    @property
+    def event_id(self) -> str:
+        """Alias for backward compatibility"""
+        return self.id
+
+    @property
+    def event_type(self) -> str:
+        """Alias for backward compatibility"""
+        return self.type
+
+    @property
+    def created_at(self) -> str:
+        """Alias for timestamp"""
+        return str(self.timestamp)
+
+    def __repr__(self) -> str:
+        return f"<MarkanM Event type='{self.type}' id='{self.id}'>"

markanm-0.1.0a1/src/markanm/exceptions.py

@@ -0,0 +1,53 @@
+import re
+
+def _mask_sensitive(text: str) -> str:
+    """Mask sensitive tokens or keys in strings"""
+    if not isinstance(text, str):
+        return str(text)
+    text = re.sub(r'mkbot_[a-zA-Z0-9_-]+', 'mkbot_***MASKED***', text)
+    text = re.sub(r'mkm_sec_[a-zA-Z0-9_-]+', 'mkm_sec_***MASKED***', text)
+    text = re.sub(r'whsec_[a-zA-Z0-9_-]+', 'whsec_***MASKED***', text)
+    return text
+
+class MarkanMError(Exception):
+    """Base exception class for all MarkanM SDK errors"""
+    def __init__(self, message: str = "An error occurred with MarkanM SDK"):
+        self.message = _mask_sensitive(message)
+        super().__init__(self.message)
+
+class MarkanMAPIError(MarkanMError):
+    """Raised when MarkanM Bot API returns an HTTP error status"""
+    def __init__(self, status_code: int, error_code: str, message: str, request_id: str = None):
+        self.status_code = status_code
+        self.error_code = error_code
+        self.request_id = request_id
+        msg = f"HTTP {status_code} [{error_code}]: {message}"
+        if request_id:
+            msg += f" (Request-ID: {request_id})"
+        super().__init__(msg)
+
+class MarkanMAuthError(MarkanMAPIError):
+    """Raised on HTTP 401 Unauthorized errors"""
+    pass
+
+class MarkanMPermissionError(MarkanMAPIError):
+    """Raised on HTTP 403 Forbidden scope errors"""
+    pass
+
+class MarkanMNotFoundError(MarkanMAPIError):
+    """Raised on HTTP 404 Not Found errors"""
+    pass
+
+class MarkanMRateLimitError(MarkanMAPIError):
+    """Raised on HTTP 429 Rate Limit Exceeded errors"""
+    def __init__(self, status_code: int, error_code: str, message: str, retry_after: int = 60, request_id: str = None):
+        self.retry_after = retry_after
+        super().__init__(status_code, error_code, f"{message} (Retry after {retry_after}s)", request_id)
+
+class MarkanMWebhookError(MarkanMError):
+    """Raised on HMAC signature or timestamp verification failure"""
+    pass
+
+class MarkanMValidationError(MarkanMError):
+    """Raised on SDK validation failure"""
+    pass

markanm-0.1.0a1/src/markanm/webhook.py

@@ -0,0 +1,78 @@
+import hmac
+import hashlib
+import time
+import json
+from typing import Dict, Any, Tuple
+from .events import Event
+from .exceptions import MarkanMWebhookError
+
+class WebhookHandler:
+    """
+    HMAC-SHA256 Webhook Verification & Parsing Helper
+    """
+    def __init__(self, secret: str, timestamp_tolerance: int = 300):
+        self.secret = secret
+        self.timestamp_tolerance = timestamp_tolerance
+
+    def parse_header(self, signature_header: str) -> Tuple[int, str]:
+        """
+        Parse X-MarkanM-Signature header: "t=1788000000,v1=abcdef..."
+        """
+        if not signature_header or not isinstance(signature_header, str):
+            raise MarkanMWebhookError("Missing or invalid X-MarkanM-Signature header")
+
+        t_val = None
+        v1_val = None
+
+        for part in signature_header.split(","):
+            part = part.strip()
+            if "=" in part:
+                k, v = part.split("=", 1)
+                if k.strip() == "t":
+                    try:
+                        t_val = int(v.strip())
+                    except ValueError:
+                        raise MarkanMWebhookError("Invalid timestamp in signature header")
+                elif k.strip() == "v1":
+                    v1_val = v.strip()
+
+        if t_val is None or not v1_val:
+            raise MarkanMWebhookError("Malformed X-MarkanM-Signature header. Expected format: 't=TIMESTAMP,v1=SIGNATURE'")
+
+        return t_val, v1_val
+
+    def verify(self, payload_body: str, signature_header: str) -> bool:
+        """
+        Verify HMAC-SHA256 signature and timestamp freshness
+        """
+        t_val, expected_sig = self.parse_header(signature_header)
+
+        # Check timestamp tolerance for replay protection
+        current_time = int(time.time())
+        if abs(current_time - t_val) > self.timestamp_tolerance:
+            raise MarkanMWebhookError(f"Webhook timestamp expired or out of tolerance window ({abs(current_time - t_val)}s > {self.timestamp_tolerance}s)")
+
+        # Compute HMAC signature
+        signed_payload = f"{t_val}.{payload_body}".encode("utf-8")
+        computed_sig = hmac.new(
+            self.secret.encode("utf-8"),
+            signed_payload,
+            hashlib.sha256
+        ).hexdigest()
+
+        if not hmac.compare_digest(computed_sig, expected_sig):
+            raise MarkanMWebhookError("Invalid HMAC-SHA256 webhook signature")
+
+        return True
+
+    def process_event(self, payload_body: str, signature_header: str) -> Event:
+        """
+        Verify signature and parse into typed Event model
+        """
+        self.verify(payload_body, signature_header)
+        try:
+            data = json.loads(payload_body)
+        except json.JSONDecodeError as exc:
+            raise MarkanMWebhookError(f"Invalid JSON payload in webhook body: {str(exc)}")
+
+        return Event(data)

markanm-0.1.0a1/src/markanm.egg-info/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: markanm
+Version: 0.1.0a1
+Summary: Official Python SDK for MarkanM Chat Bot Platform & REST API (v0.1.0-alpha)
+Author-email: MarkanM Developer Team <developers@markanm.com>
+License: MIT License
+        
+        Copyright (c) 2026 MarkanM Developer Team
+        
+        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.
+        
+Project-URL: Homepage, https://chat.markanm.com/developers
+Project-URL: Documentation, https://chat.markanm.com/developers/docs
+Project-URL: Repository, https://github.com/markanm/markanm-python-sdk
+Keywords: markanm,bot,chat,sdk,api,oauth,webhooks
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.24.0
+Dynamic: license-file
+
+# MarkanM Official Python SDK (`markanm 0.1.0a1`)
+
+Official Python library (v0.1.0-alpha) for building developer bots, automation, and AI agents on **MarkanM Chat** (`https://chat.markanm.com`).
+
+---
+
+## ⚠️ Alpha Release Notice
+
+This is **v0.1.0-alpha** (`markanm 0.1.0a1`). It is intended for testing against the MarkanM Bot API v1.
+
+---
+
+## 🚀 Installation
+
+Install via `pip`:
+
+```bash
+pip install markanm
+```
+
+---
+
+## ⚡ Quick Start
+
+### 1. Simple Hello Bot (`hello_bot.py`)
+
+```python
+import os
+from markanm import Bot
+
+bot = Bot(os.environ["MARKANM_BOT_TOKEN"])
+
+@bot.command("hello")
+async def hello(ctx):
+    await ctx.reply("Hello 👋 Welcome to MarkanM!")
+
+@bot.command("start")
+async def start(ctx):
+    await ctx.reply("🚀 Bot activated and ready!")
+
+if __name__ == "__main__":
+    bot.run_polling()
+```
+
+---
+
+### 2. Event Listeners
+
+```python
+@bot.on("message.created")
+async def on_message(event):
+    print(f"New message received: {event.payload}")
+
+@bot.on("member.joined")
+def on_member_joined(event):
+    print(f"User joined room: {event.payload.get('user')}")
+```
+
+---
+
+### 3. AI Assistant Bot (`ai_bot.py`)
+
+```python
+import os
+from markanm import Bot
+from markanm.ai import AI
+
+bot = Bot(os.environ["MARKANM_BOT_TOKEN"])
+ai = AI(provider="openai", api_key=os.environ["OPENAI_API_KEY"])
+
+@bot.command("ask")
+async def ask(ctx):
+    prompt = " ".join(ctx.args)
+    if not prompt:
+        await ctx.reply("Usage: /ask <question>")
+        return
+
+    answer = await ai.generate(prompt)
+    await ctx.reply(answer)
+
+bot.run_polling()
+```
+
+---
+
+### 4. Webhook Verification (Flask / FastAPI)
+
+```python
+from markanm import WebhookHandler, MarkanMWebhookError
+
+handler = WebhookHandler(secret="whsec_YOUR_SECRET", timestamp_tolerance=300)
+
+try:
+    # Verifies HMAC-SHA256 signature header and 300s timestamp tolerance
+    event = handler.process_event(request_body_text, request_headers.get("X-MarkanM-Signature"))
+    print(f"Event verified: {event.id} ({event.type})")
+except MarkanMWebhookError as err:
+    print(f"Webhook error: {err}")
+```
+
+---
+
+## 🧪 Testing
+
+Run tests with `pytest`:
+
+```bash
+pytest sdk/python/tests/
+```
+
+---
+
+## 📚 API Reference
+For complete API endpoints and permission scope guidelines, visit:
+**https://chat.markanm.com/developers/docs**

markanm-0.1.0a1/src/markanm.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+src/markanm/__init__.py
+src/markanm/ai.py
+src/markanm/bot.py
+src/markanm/client.py
+src/markanm/context.py
+src/markanm/events.py
+src/markanm/exceptions.py
+src/markanm/webhook.py
+src/markanm.egg-info/PKG-INFO
+src/markanm.egg-info/SOURCES.txt
+src/markanm.egg-info/dependency_links.txt
+src/markanm.egg-info/requires.txt
+src/markanm.egg-info/top_level.txt
+tests/test_ai.py
+tests/test_bot.py
+tests/test_context.py
+tests/test_events.py
+tests/test_webhook.py

markanm-0.1.0a1/src/markanm.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

markanm-0.1.0a1/src/markanm.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.24.0

markanm-0.1.0a1/src/markanm.egg-info/top_level.txt

@@ -0,0 +1 @@
+markanm

markanm-0.1.0a1/tests/test_ai.py

@@ -0,0 +1,14 @@
+import asyncio
+from markanm.ai import AI
+from markanm.exceptions import MarkanMError
+
+async def test_unsupported_ai_provider():
+    ai = AI(provider="unsupported_provider", api_key="test_key")
+    caught = False
+    try:
+        await ai.generate("Hello")
+    except MarkanMError as exc:
+        caught = True
+        assert "Unsupported AI provider" in str(exc)
+    
+    assert caught is True, "Expected MarkanMError for unsupported AI provider"

markanm-0.1.0a1/tests/test_bot.py

@@ -0,0 +1,39 @@
+import asyncio
+from markanm.bot import Bot
+from markanm.events import Event
+
+async def test_bot_command_and_event_dispatching():
+    bot = Bot("mkbot_test_token_123456789")
+
+    executed_command = False
+    executed_listener = False
+
+    @bot.command("start")
+    async def handle_start(ctx):
+        nonlocal executed_command
+        executed_command = True
+        assert ctx.command == "start"
+
+    @bot.on("message.created")
+    def handle_msg(evt):
+        nonlocal executed_listener
+        executed_listener = True
+        assert evt.type == "message.created"
+
+    # Dispatch command event
+    cmd_event = Event({
+        "event_id": "evt_cmd",
+        "event_type": "command.received",
+        "payload": {"command": "/start", "user": {"username": "alex"}, "room": {"id": 10}}
+    })
+    await bot.dispatch_event(cmd_event)
+    assert executed_command is True
+
+    # Dispatch message event
+    msg_event = Event({
+        "event_id": "evt_msg",
+        "event_type": "message.created",
+        "payload": {"text": "hello"}
+    })
+    await bot.dispatch_event(msg_event)
+    assert executed_listener is True

markanm-0.1.0a1/tests/test_context.py

@@ -0,0 +1,15 @@
+from markanm.context import CommandContext
+
+def test_command_context_parsing():
+    payload = {
+        "command": "/ask",
+        "text": "/ask What is Python?",
+        "user": {"id": 1, "username": "alex", "display_name": "Alex"},
+        "room": {"id": 42, "name": "General Room"}
+    }
+    ctx = CommandContext(None, payload)
+    assert ctx.command == "ask"
+    assert ctx.args == ["What", "is", "Python?"]
+    assert ctx.user.username == "alex"
+    assert ctx.room.id == 42
+    assert ctx.room_id == 42

markanm-0.1.0a1/tests/test_events.py

@@ -0,0 +1,16 @@
+from markanm.events import Event
+
+def test_event_properties():
+    raw_data = {
+        "event_id": "evt_12345",
+        "event_type": "message.created",
+        "timestamp": 1788000000,
+        "payload": {"text": "hello"}
+    }
+    evt = Event(raw_data)
+    assert evt.id == "evt_12345"
+    assert evt.event_id == "evt_12345"
+    assert evt.type == "message.created"
+    assert evt.event_type == "message.created"
+    assert evt.payload == {"text": "hello"}
+    assert repr(evt) == "<MarkanM Event type='message.created' id='evt_12345'>"

markanm-0.1.0a1/tests/test_webhook.py

@@ -0,0 +1,42 @@
+import hmac
+import hashlib
+import time
+from markanm.webhook import WebhookHandler
+from markanm.exceptions import MarkanMWebhookError
+
+def test_webhook_verification():
+    secret = "whsec_test_secret_12345"
+    handler = WebhookHandler(secret=secret, timestamp_tolerance=300)
+
+    timestamp = int(time.time())
+    body = '{"event_id":"evt_1","event_type":"message.created"}'
+    signed_payload = f"{timestamp}.{body}".encode("utf-8")
+    sig = hmac.new(secret.encode("utf-8"), signed_payload, hashlib.sha256).hexdigest()
+    header = f"t={timestamp},v1={sig}"
+
+    # Valid signature check
+    assert handler.verify(body, header) is True
+
+    # Process event check
+    event = handler.process_event(body, header)
+    assert event.id == "evt_1"
+    assert event.type == "message.created"
+
+def test_expired_webhook():
+    secret = "whsec_test_secret_12345"
+    handler = WebhookHandler(secret=secret, timestamp_tolerance=10)
+
+    expired_timestamp = int(time.time()) - 500 # 500 seconds old
+    body = '{"event_id":"evt_1"}'
+    signed_payload = f"{expired_timestamp}.{body}".encode("utf-8")
+    sig = hmac.new(secret.encode("utf-8"), signed_payload, hashlib.sha256).hexdigest()
+    header = f"t={expired_timestamp},v1={sig}"
+
+    caught = False
+    try:
+        handler.verify(body, header)
+    except MarkanMWebhookError as exc:
+        caught = True
+        assert "timestamp expired" in str(exc)
+
+    assert caught is True, "Expected MarkanMWebhookError for expired timestamp"