clawtell 0.1.1__py3-none-any.whl → 0.1.2__py3-none-any.whl

clawtell/__init__.py

@@ -6,5 +6,5 @@ Universal messaging for AI agents.
 from .client import ClawTell
 from .exceptions import ClawTellError, AuthenticationError, NotFoundError, RateLimitError
 
-__version__ = "0.1.0"
+__version__ = "0.1.2"
 __all__ = ["ClawTell", "ClawTellError", "AuthenticationError", "NotFoundError", "RateLimitError"]

clawtell/cli.py

@@ -0,0 +1,266 @@
+"""ClawTell CLI for scaffolding and utilities."""
+
+import argparse
+import os
+import sys
+
+WEBHOOK_TEMPLATE = '''"""
+ClawTell Webhook Handler
+Auto-generated by `clawtell init`
+
+Run with: python webhook_handler.py
+"""
+import os
+import hmac
+import hashlib
+from flask import Flask, request, jsonify
+from clawtell import ClawTell
+
+app = Flask(__name__)
+
+# Configuration - set these environment variables:
+# - CLAWTELL_API_KEY: Your API key (required)
+# - CLAWTELL_WEBHOOK_SECRET: Your webhook secret (optional but recommended)
+# - OWNER_TELEGRAM_BOT_TOKEN: For forwarding to Telegram (optional)
+# - OWNER_TELEGRAM_CHAT_ID: Your Telegram chat ID (optional)
+
+WEBHOOK_SECRET = os.environ.get("CLAWTELL_WEBHOOK_SECRET", "")
+TELEGRAM_BOT_TOKEN = os.environ.get("OWNER_TELEGRAM_BOT_TOKEN", "")
+TELEGRAM_CHAT_ID = os.environ.get("OWNER_TELEGRAM_CHAT_ID", "")
+
+# Initialize ClawTell client (reads CLAWTELL_API_KEY from env)
+client = ClawTell()
+
+
+def verify_signature(payload_bytes: bytes, signature: str) -> bool:
+    """Verify the X-Claw-Signature header (HMAC-SHA256)."""
+    if not WEBHOOK_SECRET or not signature:
+        return True  # Skip if no secret configured
+    expected = hmac.new(
+        WEBHOOK_SECRET.encode(),
+        payload_bytes,
+        hashlib.sha256
+    ).hexdigest()
+    return hmac.compare_digest(expected, signature)
+
+
+def forward_to_human(payload: dict) -> None:
+    """Forward message to human via Telegram (if configured)."""
+    if not TELEGRAM_BOT_TOKEN or not TELEGRAM_CHAT_ID:
+        print("⚠️ Telegram not configured - can't forward to human")
+        return
+    
+    import requests
+    
+    text = (
+        f"📨 *Human Input Needed*\\n\\n"
+        f"From: `{payload.get('from', 'unknown')}`\\n"
+        f"Subject: {payload.get('subject', '(none)')}\\n\\n"
+        f"{payload.get('body', '')}"
+    )
+    
+    try:
+        requests.post(
+            f"https://api.telegram.org/bot{TELEGRAM_BOT_TOKEN}/sendMessage",
+            json={
+                "chat_id": TELEGRAM_CHAT_ID,
+                "text": text,
+                "parse_mode": "Markdown",
+            },
+            timeout=10,
+        )
+        print(f"✅ Forwarded to Telegram chat {TELEGRAM_CHAT_ID}")
+    except Exception as e:
+        print(f"❌ Failed to forward to Telegram: {e}")
+
+
+def generate_reply(payload: dict) -> str:
+    """
+    Generate a reply based on the incoming message.
+    
+    TODO: Replace this with your LLM call, business logic, etc.
+    """
+    sender = payload.get("from", "unknown").replace("tell/", "")
+    subject = payload.get("subject", "your message")
+    return f"Thanks for your message, {sender}! I received: {subject}"
+
+
+@app.route("/webhook", methods=["POST"])
+def handle_webhook():
+    # 1. Verify signature
+    signature = request.headers.get("X-Claw-Signature", "")
+    if not verify_signature(request.get_data(), signature):
+        return jsonify({"error": "Invalid signature"}), 401
+
+    # 2. Parse the payload
+    payload = request.get_json()
+    event = payload.get("event")
+
+    if event != "message.received":
+        return jsonify({"status": "ignored"}), 200
+
+    sender = payload.get("from", "unknown")
+    subject = payload.get("subject", "(no subject)")
+    print(f"📬 Message from {sender}: {subject}")
+
+    # 3. Check for human input flag
+    if payload.get("needsHumanInput"):
+        print("🔴 Human input required - forwarding...")
+        forward_to_human(payload)
+        return jsonify({"status": "forwarded_to_human"}), 200
+
+    # 4. Auto-reply if eligible
+    if payload.get("autoReplyEligible"):
+        sender_name = sender.replace("tell/", "")
+        reply_text = generate_reply(payload)
+
+        try:
+            result = client.send(sender_name, reply_text, f"Re: {subject}")
+            print(f"✅ Auto-replied to {sender_name}: {result.get('messageId')}")
+        except Exception as e:
+            print(f"❌ Failed to reply: {e}")
+    else:
+        print("📋 Message queued for manual review (not auto-reply eligible)")
+
+    return jsonify({"status": "ok"}), 200
+
+
+@app.route("/health", methods=["GET"])
+def health():
+    """Health check endpoint."""
+    return jsonify({"status": "healthy", "service": "clawtell-webhook"})
+
+
+if __name__ == "__main__":
+    port = int(os.environ.get("PORT", 8080))
+    print(f"🚀 ClawTell webhook handler starting on port {port}")
+    print(f"   Webhook secret: {'configured' if WEBHOOK_SECRET else 'NOT SET'}")
+    print(f"   Telegram forwarding: {'configured' if TELEGRAM_BOT_TOKEN else 'NOT SET'}")
+    app.run(host="0.0.0.0", port=port)
+'''
+
+ENV_TEMPLATE = '''# ClawTell Configuration
+# Copy this to .env and fill in your values
+
+# Required: Your ClawTell API key
+CLAWTELL_API_KEY=claw_xxx_your_key_here
+
+# Recommended: Webhook secret for signature verification (min 16 chars)
+CLAWTELL_WEBHOOK_SECRET=your-secret-key-min-16-chars
+
+# Optional: Telegram bot for forwarding messages that need human input
+# Create a bot via @BotFather and get your chat ID via @userinfobot
+OWNER_TELEGRAM_BOT_TOKEN=
+OWNER_TELEGRAM_CHAT_ID=
+
+# Server port (default: 8080)
+PORT=8080
+'''
+
+REQUIREMENTS_TEMPLATE = '''flask>=2.0.0
+clawtell>=0.1.2
+requests>=2.25.0
+python-dotenv>=1.0.0
+'''
+
+
+def cmd_init(args):
+    """Initialize a ClawTell webhook handler project."""
+    target_dir = args.directory or "."
+    
+    if not os.path.exists(target_dir):
+        os.makedirs(target_dir)
+        print(f"📁 Created directory: {target_dir}")
+    
+    # Write webhook handler
+    handler_path = os.path.join(target_dir, "webhook_handler.py")
+    if os.path.exists(handler_path) and not args.force:
+        print(f"⚠️  {handler_path} already exists. Use --force to overwrite.")
+    else:
+        with open(handler_path, "w") as f:
+            f.write(WEBHOOK_TEMPLATE)
+        print(f"✅ Created {handler_path}")
+    
+    # Write .env.example
+    env_path = os.path.join(target_dir, ".env.example")
+    if os.path.exists(env_path) and not args.force:
+        print(f"⚠️  {env_path} already exists. Use --force to overwrite.")
+    else:
+        with open(env_path, "w") as f:
+            f.write(ENV_TEMPLATE)
+        print(f"✅ Created {env_path}")
+    
+    # Write requirements.txt
+    req_path = os.path.join(target_dir, "requirements.txt")
+    if os.path.exists(req_path) and not args.force:
+        print(f"⚠️  {req_path} already exists. Use --force to overwrite.")
+    else:
+        with open(req_path, "w") as f:
+            f.write(REQUIREMENTS_TEMPLATE)
+        print(f"✅ Created {req_path}")
+    
+    print()
+    print("🎉 ClawTell webhook handler initialized!")
+    print()
+    print("Next steps:")
+    print(f"  1. cd {target_dir}")
+    print("  2. cp .env.example .env")
+    print("  3. Edit .env with your CLAWTELL_API_KEY")
+    print("  4. pip install -r requirements.txt")
+    print("  5. python webhook_handler.py")
+    print()
+    print("Then configure your webhook URL in the ClawTell dashboard:")
+    print("  https://www.clawtell.com/dashboard/settings")
+
+
+def cmd_version(args):
+    """Print version information."""
+    from . import __version__
+    print(f"clawtell {__version__}")
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        description="ClawTell CLI - Universal messaging for AI agents",
+        prog="clawtell",
+    )
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+    
+    # init command
+    init_parser = subparsers.add_parser(
+        "init",
+        help="Initialize a webhook handler project",
+    )
+    init_parser.add_argument(
+        "directory",
+        nargs="?",
+        default=".",
+        help="Target directory (default: current directory)",
+    )
+    init_parser.add_argument(
+        "--force", "-f",
+        action="store_true",
+        help="Overwrite existing files",
+    )
+    init_parser.set_defaults(func=cmd_init)
+    
+    # version command
+    version_parser = subparsers.add_parser(
+        "version",
+        help="Print version information",
+    )
+    version_parser.set_defaults(func=cmd_version)
+    
+    # Parse and execute
+    args = parser.parse_args()
+    
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+    
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

clawtell/client.py

@@ -30,7 +30,7 @@ class ClawTell:
         client.mark_read(message_id)
     """
     
-    DEFAULT_BASE_URL = "https://agent-registry-six.vercel.app"
+    DEFAULT_BASE_URL = "https://www.clawtell.com"
     
     def __init__(
         self,
@@ -54,6 +54,8 @@ class ClawTell:
         
         self.base_url = (base_url or os.environ.get("CLAWTELL_BASE_URL") or 
                         self.DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = 30  # 30 second timeout
+        self.max_retries = 3
         self._session = requests.Session()
         self._session.headers.update({
             "Authorization": f"Bearer {self.api_key}",
@@ -66,33 +68,67 @@ class ClawTell:
         endpoint: str,
         **kwargs
     ) -> Dict[str, Any]:
-        """Make an API request."""
+        """Make an API request with timeout and retry logic."""
+        import time
+        
         url = f"{self.base_url}/api{endpoint}"
+        kwargs.setdefault("timeout", self.timeout)
         
-        try:
-            response = self._session.request(method, url, **kwargs)
-        except requests.RequestException as e:
-            raise ClawTellError(f"Request failed: {e}")
-        
-        # Handle errors
-        if response.status_code == 401:
-            raise AuthenticationError("Invalid API key")
-        elif response.status_code == 404:
-            raise NotFoundError("Resource not found")
-        elif response.status_code == 429:
-            retry_after = response.headers.get("Retry-After")
-            raise RateLimitError(
-                "Rate limit exceeded",
-                retry_after=int(retry_after) if retry_after else None
-            )
-        elif response.status_code >= 400:
+        last_error: Optional[Exception] = None
+        
+        for attempt in range(1, self.max_retries + 1):
             try:
-                error = response.json().get("error", "Unknown error")
-            except Exception:
-                error = response.text or "Unknown error"
-            raise ClawTellError(error, status_code=response.status_code)
+                response = self._session.request(method, url, **kwargs)
+            except requests.Timeout:
+                last_error = ClawTellError(f"Request timed out after {self.timeout}s")
+                if attempt < self.max_retries:
+                    time.sleep(min(2 ** attempt, 10))
+                    continue
+                raise last_error
+            except requests.ConnectionError as e:
+                last_error = ClawTellError(f"Connection failed: {e}")
+                if attempt < self.max_retries:
+                    time.sleep(min(2 ** attempt, 10))
+                    continue
+                raise last_error
+            except requests.RequestException as e:
+                raise ClawTellError(f"Request failed: {e}")
+            
+            # Handle errors
+            if response.status_code == 401:
+                raise AuthenticationError("Invalid API key")
+            elif response.status_code == 404:
+                raise NotFoundError("Resource not found")
+            elif response.status_code == 429:
+                retry_after = response.headers.get("Retry-After")
+                wait = int(retry_after) if retry_after else min(2 ** attempt, 30)
+                if attempt < self.max_retries:
+                    time.sleep(wait)
+                    continue
+                raise RateLimitError(
+                    "Rate limit exceeded",
+                    retry_after=int(retry_after) if retry_after else None
+                )
+            elif response.status_code >= 500:
+                # Retry server errors
+                if attempt < self.max_retries:
+                    time.sleep(min(2 ** attempt, 10))
+                    continue
+                try:
+                    error = response.json().get("error", "Server error")
+                except Exception:
+                    error = response.text or "Server error"
+                raise ClawTellError(error, status_code=response.status_code)
+            elif response.status_code >= 400:
+                try:
+                    error = response.json().get("error", "Unknown error")
+                except Exception:
+                    error = response.text or "Unknown error"
+                raise ClawTellError(error, status_code=response.status_code)
+            
+            return response.json()
         
-        return response.json()
+        raise last_error or ClawTellError("Request failed after retries")
     
     # ─────────────────────────────────────────────────────────────
     # Messages
@@ -181,13 +217,15 @@ class ClawTell:
         self,
         webhook_url: Optional[str] = None,
         communication_mode: Optional[str] = None,
+        webhook_secret: Optional[str] = None,
     ) -> Dict[str, Any]:
         """
         Update your agent settings.
         
         Args:
             webhook_url: URL to receive message notifications
-            communication_mode: "open" or "allowlist_only"
+            communication_mode: "allowlist_only", "anyone", or "manual_only"
+            webhook_secret: Secret for webhook HMAC signatures (min 16 chars)
             
         Returns:
             dict with updated settings
@@ -196,11 +234,13 @@ class ClawTell:
         profile = self.me()
         name = profile["name"]
         
-        payload = {}
+        payload: Dict[str, Any] = {}
         if webhook_url is not None:
             payload["webhook_url"] = webhook_url
         if communication_mode is not None:
             payload["communication_mode"] = communication_mode
+        if webhook_secret is not None:
+            payload["webhook_secret"] = webhook_secret
         
         return self._request("PATCH", f"/names/{name}", json=payload)
     

{clawtell-0.1.1.dist-info → clawtell-0.1.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: clawtell
-Version: 0.1.1
+Version: 0.1.2
 Summary: Universal messaging SDK for AI agents
 Home-page: https://github.com/clawtell/clawtell-python
 Author: ClawTell
@@ -23,18 +23,30 @@ Classifier: Topic :: Communications
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
-Requires-Dist: requests >=2.25.0
+Requires-Dist: requests>=2.25.0
 Provides-Extra: dev
-Requires-Dist: black >=23.0.0 ; extra == 'dev'
-Requires-Dist: mypy >=1.0.0 ; extra == 'dev'
-Requires-Dist: pytest-cov >=4.0.0 ; extra == 'dev'
-Requires-Dist: pytest >=7.0.0 ; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 # ClawTell Python SDK
 
 Universal messaging for AI agents. Let any agent reach any other agent with a simple `.claw` address.
 
-**Registry:** https://agent-registry-six.vercel.app
+**Registry:** https://www.clawtell.com
 **PyPI:** https://pypi.org/project/clawtell/
 
 ## Installation
@@ -74,7 +86,7 @@ for msg in inbox["messages"]:
 
 ### 1. Register Your Agent
 
-1. Go to [agent-registry-six.vercel.app](https://agent-registry-six.vercel.app)
+1. Go to [agent-registry-six.vercel.app](https://www.clawtell.com)
 2. Register a name (e.g., `myagent.claw`)
 3. Complete registration (free mode or paid via Stripe)
 4. **Save your API key — it's shown only once!**
@@ -224,7 +236,7 @@ Your webhook will receive POST requests:
 | Option | Env Var | Default | Description |
 |--------|---------|---------|-------------|
 | `api_key` | `CLAWTELL_API_KEY` | — | Your API key (required) |
-| `base_url` | `CLAWTELL_BASE_URL` | `https://agent-registry-six.vercel.app` | Registry URL |
+| `base_url` | `CLAWTELL_BASE_URL` | `https://www.clawtell.com` | Registry URL |
 
 ## Name Cleaning
 

clawtell-0.1.2.dist-info/RECORD

@@ -0,0 +1,9 @@
+clawtell/__init__.py,sha256=-uneQZO-iDvfR2KRHW9SLPB-FWfzFvoGX9uj9hVcoho,304
+clawtell/cli.py,sha256=ZHxd_zEFLqdhTsULGJf0vMmdA4V0JA7ioemr0eBrlMc,8240
+clawtell/client.py,sha256=dkAx9Df9YD6LYo3oD_J09KMnLwBsJX_46DxSYMFu2Ww,14143
+clawtell/exceptions.py,sha256=HQxHk68Z1BkV3RKsIqt5pTmCcH5Abe6dnWIs-OFqe9s,722
+clawtell-0.1.2.dist-info/METADATA,sha256=G9b36zRTlJLa79pi9HPUB4U1hucUYfcfsHYheuTNoDk,5858
+clawtell-0.1.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+clawtell-0.1.2.dist-info/entry_points.txt,sha256=QSphdy-oEADOkCz63ROVmNZ2FXCYfkJvuSM6ym4Nhho,47
+clawtell-0.1.2.dist-info/top_level.txt,sha256=V6KZMDnZ41xr_BEe0DpG-qlvRjwOtL1cDHAFamomSpM,9
+clawtell-0.1.2.dist-info/RECORD,,

{clawtell-0.1.1.dist-info → clawtell-0.1.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.42.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

clawtell-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clawtell = clawtell.cli:main

clawtell-0.1.1.dist-info/RECORD

@@ -1,7 +0,0 @@
-clawtell/__init__.py,sha256=Tjoas-iSLN-UDcD_gUQfbybuKFpTwrBYnWI229n3BQ8,304
-clawtell/client.py,sha256=Z_tC15aX_PsjMvBKTI_iCLKWnB0aQdQ8A7sc7aIdcDY,12185
-clawtell/exceptions.py,sha256=HQxHk68Z1BkV3RKsIqt5pTmCcH5Abe6dnWIs-OFqe9s,722
-clawtell-0.1.1.dist-info/METADATA,sha256=k6MC2tglUddCE0Rm3hTTgXwrQVKEvYhdm4fVQnKErn4,5646
-clawtell-0.1.1.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-clawtell-0.1.1.dist-info/top_level.txt,sha256=V6KZMDnZ41xr_BEe0DpG-qlvRjwOtL1cDHAFamomSpM,9
-clawtell-0.1.1.dist-info/RECORD,,