@moltflow/skills 1.0.0

package/SKILL.md

@@ -0,0 +1,512 @@
+---
+name: WhatsApp Automation & A2A
+description: "MoltFlow — complete WhatsApp automation platform: sessions, messaging, groups, labels, webhooks, AI (voice transcription, RAG, style profiles, reply generation), agent-to-agent protocol (JSON-RPC, encryption), review collection (14+ language sentiment analysis), auth, API keys, and Stripe billing."
+metadata: {"openclaw":{"emoji":"📱","homepage":"https://moltflow.com","requires":{"env":["MOLTFLOW_API_KEY"]},"primaryEnv":"MOLTFLOW_API_KEY"}}
+---
+
+# WhatsApp Automation & A2A
+
+MoltFlow provides a complete WhatsApp automation API with managed sessions, group monitoring, AI-powered replies, agent-to-agent communication, review collection, and Stripe billing.
+
+## When to use
+
+Use this skill when you need to:
+- Connect and manage WhatsApp sessions (QR pairing, start/stop)
+- Send text messages, list chats, read message history
+- Monitor groups for leads or keywords
+- Manage contact labels (WhatsApp Business sync)
+- Configure webhooks for real-time events
+- Transcribe voice messages (Whisper AI)
+- Manage RAG knowledge base (upload docs, semantic search)
+- Train style profiles and generate AI replies
+- Discover and message other AI agents (A2A JSON-RPC 2.0)
+- Manage encryption keys (X25519-AES256GCM)
+- Collect reviews via sentiment analysis (14+ languages)
+- Export testimonials (JSON/HTML)
+- Manage API keys, usage tracking, billing (Stripe)
+
+## Setup
+
+Env vars:
+- `MOLTFLOW_API_KEY` (required) — API key from moltflow.com dashboard
+- `MOLTFLOW_API_URL` (optional) — defaults to `https://api.moltflow.com`
+
+Authentication: `X-API-Key: $MOLTFLOW_API_KEY` header or `Authorization: Bearer $TOKEN` (JWT from login).
+
+Base URL: `https://api.moltflow.com/api/v2`
+
+---
+
+## 1. Sessions
+
+```bash
+# List all sessions
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/sessions
+
+# Create new session
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "Main Line"}' \
+  https://api.moltflow.com/api/v2/sessions
+
+# Get session details
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/sessions/{session_id}
+
+# Delete session
+curl -X DELETE -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/sessions/{session_id}
+```
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/sessions` | GET | List sessions |
+| `/sessions` | POST | Create session |
+| `/sessions/{id}` | GET | Get session details |
+| `/sessions/{id}` | DELETE | Delete session |
+
+## 2. Messages
+
+```bash
+# Send text message
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"session_id": "uuid", "chat_id": "1234567890@c.us", "message": "Hello!"}' \
+  https://api.moltflow.com/api/v2/messages/send
+
+# List chats for a session
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/messages/chats/{session_id}
+
+# Get chat messages
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/messages/chat/{session_id}/{chat_id}
+```
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/messages/send` | POST | Send text message |
+| `/messages/chats/{session_id}` | GET | List chats |
+| `/messages/chat/{session_id}/{chat_id}` | GET | Get messages in chat |
+| `/messages/{message_id}` | GET | Get single message |
+
+## 3. Groups
+
+```bash
+# List monitored groups
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/groups
+
+# List available WhatsApp groups
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/groups/available/{session_id}
+
+# Add group to monitor
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"session_id": "uuid", "wa_group_id": "123456@g.us", "monitor_mode": "first_message"}' \
+  https://api.moltflow.com/api/v2/groups
+
+# Update monitoring settings
+curl -X PATCH -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"monitor_mode": "keyword", "monitor_keywords": ["looking for", "need help"]}' \
+  https://api.moltflow.com/api/v2/groups/{group_id}
+```
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/groups` | GET | List monitored groups |
+| `/groups/available/{session_id}` | GET | List available WhatsApp groups |
+| `/groups` | POST | Add group to monitoring |
+| `/groups/{id}` | GET | Get group details |
+| `/groups/{id}` | PATCH | Update monitoring settings |
+| `/groups/{id}` | DELETE | Remove from monitoring |
+
+## 4. Labels
+
+```bash
+# Create label (color must be hex #RRGGBB)
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "VIP", "color": "#00FF00"}' \
+  https://api.moltflow.com/api/v2/labels
+
+# Sync label to WhatsApp Business
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  "https://api.moltflow.com/api/v2/labels/{label_id}/sync?session_id={session_id}"
+
+# Import labels from WhatsApp Business
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  "https://api.moltflow.com/api/v2/labels/sync-from-whatsapp?session_id={session_id}"
+```
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/labels` | GET | List labels |
+| `/labels` | POST | Create label |
+| `/labels/business-check` | GET | Check WhatsApp Business status |
+| `/labels/{id}` | GET / PATCH / DELETE | Get, update, delete label |
+| `/labels/{id}/sync` | POST | Sync to WhatsApp Business |
+| `/labels/sync-from-whatsapp` | POST | Import from WhatsApp |
+
+## 5. Webhooks
+
+```bash
+# Create webhook
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://your-server.com/webhook", "events": ["message.received", "lead.detected"]}' \
+  https://api.moltflow.com/api/v2/webhooks
+
+# Test webhook
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/webhooks/{webhook_id}/test
+```
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/webhooks` | GET | List webhooks |
+| `/webhooks` | POST | Create webhook |
+| `/webhooks/{id}` | GET / PATCH / DELETE | Get, update, delete |
+| `/webhooks/{id}/test` | POST | Send test payload |
+
+**Webhook events:** `message.received`, `message.sent`, `message.delivered`, `message.read`, `lead.detected`, `session.connected`, `session.disconnected`, `group.message`
+
+---
+
+## 6. AI — Voice Transcription
+
+```bash
+# Queue voice message for transcription
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -d '{"message_id": "uuid-of-voice-message"}' \
+  https://api.moltflow.com/api/v2/ai/voice/transcribe
+
+# Check transcription status
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/ai/voice/status/{task_id}
+
+# Get transcript
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/ai/messages/{message_id}/transcript
+```
+
+## 7. AI — Knowledge Base (RAG)
+
+```bash
+# Upload document (PDF or TXT, max 10MB)
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -F "file=@manual.pdf" \
+  https://api.moltflow.com/api/v2/ai/knowledge/ingest
+
+# Search knowledge base
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -d '{"query": "return policy", "top_k": 5}' \
+  https://api.moltflow.com/api/v2/ai/knowledge/search
+
+# List knowledge sources
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/ai/knowledge/sources
+
+# Delete knowledge source
+curl -X DELETE -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/ai/knowledge/{source_id}
+```
+
+## 8. AI — Style Profiles (Learn Mode)
+
+```bash
+# Train style profile from message history
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -d '{"contact_id": "optional-contact-jid"}' \
+  https://api.moltflow.com/api/v2/ai/style/train
+
+# Check training status
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/ai/style/status/{task_id}
+
+# Get / list / delete style profiles
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/ai/style/profiles
+```
+
+## 9. AI — Reply Generation
+
+```bash
+# Generate AI reply (uses RAG + style)
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -d '{"contact_id": "jid", "context": "customer question", "use_rag": true, "apply_style": true}' \
+  https://api.moltflow.com/api/v2/ai/ai/generate-reply
+
+# Preview AI reply (no usage tracking)
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  "https://api.moltflow.com/api/v2/ai/ai/preview?contact_id=jid&context=question&use_rag=true&apply_style=true"
+```
+
+### AI API Reference
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/ai/voice/transcribe` | POST | Queue voice transcription |
+| `/ai/voice/status/{task_id}` | GET | Check transcription status |
+| `/ai/messages/{id}/transcript` | GET | Get transcript |
+| `/ai/knowledge/ingest` | POST | Upload document (PDF/TXT) |
+| `/ai/knowledge/search` | POST | Semantic search |
+| `/ai/knowledge/sources` | GET | List knowledge sources |
+| `/ai/knowledge/{id}` | DELETE | Delete source |
+| `/ai/style/train` | POST | Train style profile |
+| `/ai/style/status/{task_id}` | GET | Training status |
+| `/ai/style/profile` | GET | Get style profile |
+| `/ai/style/profiles` | GET | List all profiles |
+| `/ai/style/profile/{id}` | DELETE | Delete profile |
+| `/ai/ai/generate-reply` | POST | Generate AI reply |
+| `/ai/ai/preview` | GET | Preview reply (no tracking) |
+
+---
+
+## 10. A2A — Agent-to-Agent Protocol
+
+**Requires Business plan.** Uses JSON-RPC 2.0 over HTTPS with X25519-AES256GCM encryption.
+
+### Bootstrap & encryption
+
+```bash
+# Get full configuration
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/agent/bootstrap
+
+# Get your public key (auto-generates if none)
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/agent/public-key
+
+# Rotate keypair
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/agent/rotate-keys
+```
+
+### Discover agents
+
+```bash
+# Resolve phone to MoltFlow agent
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/agents/resolve/+1234567890
+
+# List peers
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/agents/peers
+
+# Update trust level (discovered, verified, blocked)
+curl -X PATCH -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"trust_level": "verified"}' \
+  https://api.moltflow.com/api/v2/agents/peers/{peer_id}/trust
+```
+
+### Send A2A messages (JSON-RPC 2.0)
+
+```bash
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "method": "agent.message.send",
+    "params": {
+      "phone": "+1234567890",
+      "message": {"parts": [{"text": "Hello from my agent!"}]}
+    },
+    "id": "1"
+  }' \
+  https://api.moltflow.com/api/v2/a2a
+```
+
+### Content policy
+
+```bash
+# Get policy settings
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/a2a-policy/settings
+
+# Update policy
+curl -X PUT -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"block_api_keys": true, "block_credit_cards": true, "block_emails": false}' \
+  https://api.moltflow.com/api/v2/a2a-policy/settings
+
+# Test content against policy
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"content": "My API key is sk-abc123"}' \
+  https://api.moltflow.com/api/v2/a2a-policy/test
+```
+
+### A2A API Reference
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/agent/bootstrap` | GET | Full onboarding config |
+| `/agent/public-key` | GET | Get X25519 public key |
+| `/agent/rotate-keys` | POST | Rotate keypair |
+| `/agent/peer/{tenant_id}/public-key` | GET | Peer's public key |
+| `/agents/resolve/{phone}` | GET | Resolve phone to agent |
+| `/agents/peers` | GET | List discovered peers |
+| `/agents/peers/{id}/trust` | PATCH | Update trust level |
+| `/a2a` | POST | JSON-RPC 2.0 endpoint |
+| `/a2a-policy/settings` | GET/PUT | Get/update policy |
+| `/a2a-policy/rules` | POST | Add custom filter rule |
+| `/a2a-policy/test` | POST | Test content against policy |
+| `/a2a-policy/stats` | GET | Blocking statistics |
+
+**JSON-RPC methods:** `agent.message.send`, `group.getContext`, `agent.group.create`, `agent.group.invite`, `agent.group.list`, `webhook_manager`
+
+**Trust levels:** `discovered` → `verified` → `blocked`
+
+**Encryption:** X25519-AES256GCM, ECDH key exchange, HKDF-SHA256, 32-byte keys (base64)
+
+---
+
+## 11. Reviews — Sentiment Analysis & Testimonials
+
+```bash
+# Create review collector
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -d '{
+    "name": "Customer Feedback",
+    "session_id": "uuid-of-whatsapp-session",
+    "source_type": "groups",
+    "min_positive_words": 3,
+    "min_sentiment_score": 0.6,
+    "include_keywords": ["great", "excellent"],
+    "languages": []
+  }' \
+  https://api.moltflow.com/api/v2/reviews/collectors
+
+# Trigger manual scan
+curl -X POST -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/reviews/collectors/{id}/run
+
+# List reviews
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  "https://api.moltflow.com/api/v2/reviews?approved_only=false&limit=50"
+
+# Approve review
+curl -X PATCH -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  -d '{"is_approved": true}' \
+  https://api.moltflow.com/api/v2/reviews/{id}
+
+# Export testimonials as HTML
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  "https://api.moltflow.com/api/v2/reviews/testimonials/export?format=html"
+```
+
+### Reviews API Reference
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/reviews/collectors` | GET/POST | List/create collectors |
+| `/reviews/collectors/{id}` | GET/PATCH/DELETE | Manage collector |
+| `/reviews/collectors/{id}/run` | POST | Trigger scan |
+| `/reviews` | GET | List reviews |
+| `/reviews/stats` | GET | Review statistics |
+| `/reviews/{id}` | GET/PATCH/DELETE | Manage review |
+| `/reviews/testimonials/export` | GET | Export (format=json/html) |
+
+**Supported languages (14+):** English, Spanish, Portuguese, French, German, Italian, Dutch, Russian, Arabic, Hebrew, Chinese, Japanese, Korean, Hindi, Turkish
+
+**Collector fields:** `name`, `session_id`, `source_type` (all/groups/chats/selected), `min_positive_words` (1-10), `min_sentiment_score` (0.0-1.0), `include_keywords`, `exclude_keywords`, `languages`
+
+---
+
+## 12. Auth & API Keys
+
+```bash
+# Login
+curl -X POST -d '{"email": "user@example.com", "password": "..."}' \
+  https://api.moltflow.com/api/v2/auth/login
+
+# Get current user
+curl -H "Authorization: Bearer $TOKEN" \
+  https://api.moltflow.com/api/v2/auth/me
+
+# Create API key
+curl -X POST -H "Authorization: Bearer $TOKEN" \
+  -d '{"name": "Production Key", "expires_in_days": 90}' \
+  https://api.moltflow.com/api/v2/api-keys
+
+# Revoke key
+curl -X DELETE -H "Authorization: Bearer $TOKEN" \
+  https://api.moltflow.com/api/v2/api-keys/{id}
+
+# Rotate key
+curl -X POST -H "Authorization: Bearer $TOKEN" \
+  https://api.moltflow.com/api/v2/api-keys/{id}/rotate
+```
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/auth/login` | POST | Login (email/password), returns JWT |
+| `/auth/refresh` | POST | Refresh token |
+| `/auth/me` | GET | Current user + tenant |
+| `/auth/magic-link/request` | POST | Request magic link |
+| `/api-keys` | GET/POST | List/create API keys |
+| `/api-keys/{id}` | GET/DELETE | Get/revoke key |
+| `/api-keys/{id}/rotate` | POST | Rotate key |
+
+## 13. Usage & Billing
+
+```bash
+# Current period usage
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  https://api.moltflow.com/api/v2/usage/current
+
+# Daily breakdown
+curl -H "X-API-Key: $MOLTFLOW_API_KEY" \
+  "https://api.moltflow.com/api/v2/usage/daily?days=30"
+
+# List plans
+curl https://api.moltflow.com/api/v2/billing/plans
+
+# Create checkout session
+curl -X POST -H "Authorization: Bearer $TOKEN" \
+  -d '{"plan": "pro", "cycle": "monthly", "success_url": "https://...", "cancel_url": "https://..."}' \
+  https://api.moltflow.com/api/v2/billing/checkout
+
+# Billing portal
+curl -H "Authorization: Bearer $TOKEN" \
+  https://api.moltflow.com/api/v2/billing/portal
+```
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/usage/current` | GET | Current period usage + limits |
+| `/usage/history` | GET | Historical usage |
+| `/usage/daily` | GET | Daily breakdown |
+| `/billing/plans` | GET | Available plans |
+| `/billing/subscription` | GET | Current subscription |
+| `/billing/checkout` | POST | Stripe checkout session |
+| `/billing/portal` | GET | Stripe billing portal |
+| `/billing/cancel` | POST | Cancel subscription |
+
+---
+
+## Notes
+
+- All messages include anti-spam compliance (typing indicators, random delays)
+- Rate limits by plan: Free 10/min, Starter 60/min, Pro 300/min, Business 1000/min
+- Sessions require QR code pairing on first connect
+- Use E.164 phone format without `+` where required
+- AI features require Pro plan or above
+- A2A protocol requires Business plan
+- AI reply generation includes safety: input sanitization, intent verification, output filtering, PII/secrets detection
+- Content policy filters secrets (API keys, tokens) and PII (SSN, credit cards)
+- API keys use name + expires_in_days (no scopes param); raw key shown only once at creation
+- Respect WhatsApp opt-in, business hours, and opt-out requests
+
+<!-- FILEMAP:BEGIN -->
+```text
+[moltflow file map]|root: .
+|.:{SKILL.md,package.json}
+|scripts:{quickstart.py,a2a_client.py,discover_agent.py,send_message.py,admin.py,ai_config.py,reviews.py}
+```
+<!-- FILEMAP:END -->

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@moltflow/skills",
+  "version": "1.0.0",
+  "description": "MoltFlow — complete WhatsApp automation platform: sessions, messaging, groups, AI, A2A protocol, reviews, billing.",
+  "license": "MIT",
+  "private": false,
+  "files": [
+    "SKILL.md",
+    "scripts/"
+  ],
+  "keywords": [
+    "moltflow",
+    "whatsapp",
+    "openclaw",
+    "clawhub",
+    "automation",
+    "a2a",
+    "ai",
+    "reviews",
+    "crm"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/a2a_client.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""
+MoltFlow A2A - Agent Discovery and JSON-RPC Messaging
+"""
+import os
+import json
+import requests
+
+API_KEY = os.environ.get("MOLTFLOW_API_KEY")
+BASE_URL = os.environ.get("MOLTFLOW_API_URL", "https://api.moltflow.com")
+
+if not API_KEY:
+    print("Error: MOLTFLOW_API_KEY environment variable not set")
+    exit(1)
+
+headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}
+
+
+def bootstrap():
+    """Get full skill onboarding config."""
+    r = requests.get(f"{BASE_URL}/api/v2/agent/bootstrap", headers=headers)
+    r.raise_for_status()
+    return r.json()
+
+
+def get_public_key():
+    """Get your agent's X25519 public key."""
+    r = requests.get(f"{BASE_URL}/api/v2/agent/public-key", headers=headers)
+    r.raise_for_status()
+    return r.json()
+
+
+def resolve_phone(phone: str):
+    """Resolve a phone number to a MoltFlow agent."""
+    r = requests.get(f"{BASE_URL}/api/v2/agents/resolve/{phone}", headers=headers)
+    r.raise_for_status()
+    return r.json()
+
+
+def list_peers(trust_level: str = None):
+    """List discovered peer agents."""
+    params = {"trust_level": trust_level} if trust_level else {}
+    r = requests.get(f"{BASE_URL}/api/v2/agents/peers", headers=headers, params=params)
+    r.raise_for_status()
+    return r.json()
+
+
+def update_trust(peer_id: str, trust_level: str):
+    """Update peer trust level (discovered, verified, blocked)."""
+    r = requests.patch(
+        f"{BASE_URL}/api/v2/agents/peers/{peer_id}/trust",
+        headers=headers,
+        json={"trust_level": trust_level},
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def a2a_send_message(phone: str, text: str, request_id: str = "1"):
+    """Send a message via A2A JSON-RPC."""
+    r = requests.post(
+        f"{BASE_URL}/api/v2/a2a",
+        headers=headers,
+        json={
+            "jsonrpc": "2.0",
+            "method": "agent.message.send",
+            "params": {
+                "phone": phone,
+                "message": {"parts": [{"text": text}]},
+            },
+            "id": request_id,
+        },
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def a2a_group_context(group_id: str, request_id: str = "1"):
+    """Get group context via A2A JSON-RPC."""
+    r = requests.post(
+        f"{BASE_URL}/api/v2/a2a",
+        headers=headers,
+        json={
+            "jsonrpc": "2.0",
+            "method": "group.getContext",
+            "params": {"groupId": group_id},
+            "id": request_id,
+        },
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def get_policy():
+    """Get A2A content policy settings."""
+    r = requests.get(f"{BASE_URL}/api/v2/a2a-policy/settings", headers=headers)
+    r.raise_for_status()
+    return r.json()
+
+
+def test_content(content: str):
+    """Test content against policy (dry run)."""
+    r = requests.post(
+        f"{BASE_URL}/api/v2/a2a-policy/test",
+        headers=headers,
+        json={"content": content},
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+if __name__ == "__main__":
+    print("MoltFlow A2A Protocol")
+    print("=" * 40)
+
+    # Bootstrap
+    config = bootstrap()
+    print(f"\nTenant: {config['tenant_name']} (Plan: {config['plan']})")
+    print(f"Encryption: {'enabled' if config['encryption']['enabled'] else 'disabled'}")
+
+    # List peers
+    peers = list_peers()
+    print(f"\nDiscovered Peers: {peers['total']}")
+
+    for p in peers.get("peers", []):
+        print(f"  - {p.get('peer_name', 'Unknown')} ({p.get('peer_phone', 'N/A')}) - trust: {p['trust_level']}")

package/scripts/admin.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python3
+"""
+MoltFlow Admin - API Key Management and Usage
+"""
+import os
+import requests
+
+API_KEY = os.environ.get("MOLTFLOW_API_KEY")
+BASE_URL = os.environ.get("MOLTFLOW_API_URL", "https://api.moltflow.com")
+
+if not API_KEY:
+    print("Error: MOLTFLOW_API_KEY environment variable not set")
+    exit(1)
+
+headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}
+
+
+def get_current_user(token: str):
+    """Get current user info (requires JWT)."""
+    r = requests.get(
+        f"{BASE_URL}/api/v2/auth/me",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def list_api_keys(token: str):
+    """List API keys (requires JWT)."""
+    r = requests.get(
+        f"{BASE_URL}/api/v2/api-keys",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def create_api_key(token: str, name: str, description: str = None, expires_in_days: int = None):
+    """Create a new API key (requires JWT)."""
+    data = {"name": name}
+    if description:
+        data["description"] = description
+    if expires_in_days:
+        data["expires_in_days"] = expires_in_days
+    r = requests.post(
+        f"{BASE_URL}/api/v2/api-keys",
+        headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
+        json=data,
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def get_current_usage():
+    """Get current period usage stats."""
+    r = requests.get(f"{BASE_URL}/api/v2/usage/current", headers=headers)
+    r.raise_for_status()
+    return r.json()
+
+
+def get_usage_history(months: int = 6):
+    """Get usage history for past months."""
+    r = requests.get(
+        f"{BASE_URL}/api/v2/usage/history",
+        headers=headers,
+        params={"months": months},
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def get_daily_usage(days: int = 30):
+    """Get daily usage breakdown."""
+    r = requests.get(
+        f"{BASE_URL}/api/v2/usage/daily",
+        headers=headers,
+        params={"days": days},
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def get_subscription(token: str):
+    """Get current subscription (requires JWT)."""
+    r = requests.get(
+        f"{BASE_URL}/api/v2/billing/subscription",
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def get_plans():
+    """Get available subscription plans."""
+    r = requests.get(f"{BASE_URL}/api/v2/billing/plans")
+    r.raise_for_status()
+    return r.json()
+
+
+if __name__ == "__main__":
+    print("MoltFlow Admin Dashboard")
+    print("=" * 40)
+
+    usage = get_current_usage()
+    print(f"\nUsage This Month ({usage.get('period')}):")
+    print(f"  Messages Sent: {usage.get('messages_sent', 0)}")
+    print(f"  Messages Received: {usage.get('messages_received', 0)}")
+    print(f"  Total Messages: {usage.get('total_messages', 0)}")
+    print(f"  Leads Detected: {usage.get('leads_detected', 0)}")
+    print(f"  API Calls: {usage.get('api_calls', 0)}")
+    print(f"  Usage: {usage.get('usage_percentage', 0)}%")
+    print(f"  Limit: {usage.get('limit_messages', 0)} messages/month")
+
+    plans = get_plans()
+    print(f"\nAvailable Plans: {len(plans.get('plans', []))}")
+    for plan in plans.get("plans", []):
+        print(f"  - {plan.get('name', 'unknown')}")

package/scripts/ai_config.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""
+MoltFlow AI - Lead Detection and Auto-Responses
+"""
+import os
+import requests
+
+API_KEY = os.environ.get("MOLTFLOW_API_KEY")
+BASE_URL = os.environ.get("MOLTFLOW_API_URL", "https://api.moltflow.com")
+
+if not API_KEY:
+    print("Error: MOLTFLOW_API_KEY environment variable not set")
+    exit(1)
+
+headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}
+
+
+def get_ai_config():
+    """Get current AI configuration."""
+    r = requests.get(f"{BASE_URL}/api/v2/ai/config", headers=headers)
+    r.raise_for_status()
+    return r.json()
+
+
+def enable_ai(provider: str = "openai", model: str = "gpt-4o", system_prompt: str = None):
+    """Enable AI auto-responses."""
+    data = {"enabled": True, "provider": provider, "model": model}
+    if system_prompt:
+        data["system_prompt"] = system_prompt
+    r = requests.patch(f"{BASE_URL}/api/v2/ai/config", headers=headers, json=data)
+    r.raise_for_status()
+    return r.json()
+
+
+def get_leads(status: str = "new", limit: int = 50):
+    """Get detected leads."""
+    r = requests.get(
+        f"{BASE_URL}/api/v2/ai/leads",
+        headers=headers,
+        params={"status": status, "limit": limit},
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def add_knowledge_source(name: str, source_type: str, source: str):
+    """Add a knowledge source for RAG."""
+    r = requests.post(
+        f"{BASE_URL}/api/v2/ai/knowledge",
+        headers=headers,
+        json={"name": name, "type": source_type, "source": source},
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+if __name__ == "__main__":
+    print("MoltFlow AI Configuration")
+    print("=" * 40)
+    
+    config = get_ai_config()
+    print(f"\nAI Enabled: {config.get('enabled', False)}")
+    print(f"Provider: {config.get('provider', 'not set')}")
+    print(f"Model: {config.get('model', 'not set')}")
+    
+    leads = get_leads()
+    print(f"\nNew Leads: {len(leads.get('leads', []))}")

package/scripts/discover_agent.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""
+A2A Discovery Script
+Fetches and validates the agent.json card.
+"""
+import requests
+import sys
+import json
+import argparse
+from typing import Dict, Any
+
+def discover_agent(base_url: str) -> Dict[str, Any]:
+    """
+    Fetch the .well-known/agent.json from the base URL.
+    """
+    # Ensure URL doesn't end with slash to avoid double slashes
+    url = f"{base_url.rstrip('/')}/.well-known/agent.json"
+    
+    try:
+        response = requests.get(url, timeout=10)
+        response.raise_for_status()
+        
+        data = response.json()
+        
+        # Validation
+        if "supportedInterfaces" not in data:
+            print(f"WARNING: {url} response missing 'supportedInterfaces'.", file=sys.stderr)
+            
+        return data
+        
+    except requests.exceptions.RequestException as e:
+        # Return a structured error for the agent to parse
+        return {
+            "error": True,
+            "message": f"Discovery failed: {str(e)}",
+            "url": url
+        }
+    except json.JSONDecodeError:
+        return {
+            "error": True,
+            "message": "Invalid JSON response from endpoint",
+            "url": url
+        }
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Discover MoltFlow Agent capabilities.")
+    parser.add_argument("url", help="Base URL of the agent (e.g., https://api.waiflow.app)")
+    
+    args = parser.parse_args()
+    
+    card = discover_agent(args.url)
+    
+    # Output solely JSON for easy parsing by calling agent
+    print(json.dumps(card, indent=2))

package/scripts/quickstart.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""
+MoltFlow Quickstart - Send your first WhatsApp message
+"""
+import os
+import requests
+
+API_KEY = os.environ.get("MOLTFLOW_API_KEY")
+BASE_URL = os.environ.get("MOLTFLOW_API_URL", "https://api.moltflow.com")
+
+if not API_KEY:
+    print("Error: MOLTFLOW_API_KEY environment variable not set")
+    print("Get your API key at https://moltflow.com")
+    exit(1)
+
+headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}
+
+
+def list_sessions():
+    """List all WhatsApp sessions."""
+    r = requests.get(f"{BASE_URL}/api/v2/sessions", headers=headers)
+    r.raise_for_status()
+    return r.json()
+
+
+def send_message(session_id: str, chat_id: str, message: str):
+    """Send a text message."""
+    r = requests.post(
+        f"{BASE_URL}/api/v2/messages/send",
+        headers=headers,
+        json={"session_id": session_id, "chat_id": chat_id, "message": message},
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def list_groups():
+    """List monitored groups."""
+    r = requests.get(f"{BASE_URL}/api/v2/groups", headers=headers)
+    r.raise_for_status()
+    return r.json()
+
+
+def get_usage():
+    """Get current usage stats."""
+    r = requests.get(f"{BASE_URL}/api/v2/usage/current", headers=headers)
+    r.raise_for_status()
+    return r.json()
+
+
+if __name__ == "__main__":
+    print("MoltFlow Quickstart")
+    print("=" * 40)
+
+    # List sessions
+    sessions = list_sessions()
+    print(f"\nFound {len(sessions)} sessions")
+
+    for s in sessions:
+        print(f"  - {s['name']} ({s['id'][:8]}...) - {s['status']}")
+
+    # Show usage
+    usage = get_usage()
+    print(f"\nUsage: {usage['total_messages']}/{usage['limit_messages']} messages ({usage['usage_percentage']}%)")
+
+    print("\nTo send a message:")
+    print('  send_message("session-id", "1234567890@c.us", "Hello!")')

package/scripts/reviews.py

@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""
+MoltFlow Reviews - Review Collector Management
+"""
+import os
+import requests
+
+API_KEY = os.environ.get("MOLTFLOW_API_KEY")
+BASE_URL = os.environ.get("MOLTFLOW_API_URL", "https://api.moltflow.com")
+
+if not API_KEY:
+    print("Error: MOLTFLOW_API_KEY environment variable not set")
+    exit(1)
+
+headers = {"X-API-Key": API_KEY, "Content-Type": "application/json"}
+
+
+# ============================================================================
+# Collectors
+# ============================================================================
+
+def list_collectors(include_inactive: bool = False):
+    """List all review collectors."""
+    r = requests.get(
+        f"{BASE_URL}/api/v2/reviews/collectors",
+        headers=headers,
+        params={"include_inactive": include_inactive},
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def create_collector(
+    name: str,
+    session_id: str,
+    source_type: str = "all",
+    min_positive_words: int = 3,
+    min_sentiment_score: float = 0.6,
+    include_keywords: list = None,
+    exclude_keywords: list = None,
+    languages: list = None,
+    description: str = None,
+    selected_chat_ids: list = None,
+):
+    """Create a new review collector."""
+    data = {
+        "name": name,
+        "session_id": session_id,
+        "source_type": source_type,
+        "min_positive_words": min_positive_words,
+        "min_sentiment_score": min_sentiment_score,
+    }
+    if include_keywords:
+        data["include_keywords"] = include_keywords
+    if exclude_keywords:
+        data["exclude_keywords"] = exclude_keywords
+    if languages is not None:
+        data["languages"] = languages
+    if description:
+        data["description"] = description
+    if selected_chat_ids:
+        data["selected_chat_ids"] = selected_chat_ids
+    r = requests.post(
+        f"{BASE_URL}/api/v2/reviews/collectors",
+        headers=headers,
+        json=data,
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def get_collector(collector_id: str):
+    """Get a collector with stats."""
+    r = requests.get(
+        f"{BASE_URL}/api/v2/reviews/collectors/{collector_id}",
+        headers=headers,
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def update_collector(collector_id: str, **kwargs):
+    """Update a collector. Pass fields to update as keyword args."""
+    r = requests.patch(
+        f"{BASE_URL}/api/v2/reviews/collectors/{collector_id}",
+        headers=headers,
+        json=kwargs,
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def delete_collector(collector_id: str):
+    """Delete a collector and all its reviews."""
+    r = requests.delete(
+        f"{BASE_URL}/api/v2/reviews/collectors/{collector_id}",
+        headers=headers,
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def run_collector(collector_id: str):
+    """Trigger a manual scan for a collector."""
+    r = requests.post(
+        f"{BASE_URL}/api/v2/reviews/collectors/{collector_id}/run",
+        headers=headers,
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+# ============================================================================
+# Reviews
+# ============================================================================
+
+def list_reviews(
+    collector_id: str = None,
+    approved_only: bool = False,
+    include_hidden: bool = False,
+    limit: int = 50,
+    offset: int = 0,
+):
+    """List collected reviews."""
+    params = {
+        "approved_only": approved_only,
+        "include_hidden": include_hidden,
+        "limit": limit,
+        "offset": offset,
+    }
+    if collector_id:
+        params["collector_id"] = collector_id
+    r = requests.get(
+        f"{BASE_URL}/api/v2/reviews",
+        headers=headers,
+        params=params,
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def get_review(review_id: str):
+    """Get a single review."""
+    r = requests.get(
+        f"{BASE_URL}/api/v2/reviews/{review_id}",
+        headers=headers,
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def approve_review(review_id: str):
+    """Approve a review as a testimonial."""
+    r = requests.patch(
+        f"{BASE_URL}/api/v2/reviews/{review_id}",
+        headers=headers,
+        json={"is_approved": True},
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def hide_review(review_id: str):
+    """Hide a review from the list."""
+    r = requests.patch(
+        f"{BASE_URL}/api/v2/reviews/{review_id}",
+        headers=headers,
+        json={"is_hidden": True},
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def delete_review(review_id: str):
+    """Delete a review."""
+    r = requests.delete(
+        f"{BASE_URL}/api/v2/reviews/{review_id}",
+        headers=headers,
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def get_stats(collector_id: str = None):
+    """Get review statistics."""
+    params = {}
+    if collector_id:
+        params["collector_id"] = collector_id
+    r = requests.get(
+        f"{BASE_URL}/api/v2/reviews/stats",
+        headers=headers,
+        params=params,
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+def export_testimonials(format: str = "json"):
+    """Export approved reviews as testimonials (json or html)."""
+    r = requests.get(
+        f"{BASE_URL}/api/v2/reviews/testimonials/export",
+        headers=headers,
+        params={"format": format},
+    )
+    r.raise_for_status()
+    return r.json()
+
+
+if __name__ == "__main__":
+    print("MoltFlow Review Collector")
+    print("=" * 40)
+
+    collectors = list_collectors()
+    print(f"\nCollectors: {collectors.get('total', 0)}")
+    for c in collectors.get("collectors", []):
+        print(f"  - {c.get('name')} ({c.get('source_type')}) active={c.get('is_active')}")
+
+    stats = get_stats()
+    print(f"\nReview Stats:")
+    print(f"  Total: {stats.get('total', 0)}")
+    print(f"  Approved: {stats.get('approved', 0)}")
+    print(f"  Pending: {stats.get('pending', 0)}")
+    print(f"  Hidden: {stats.get('hidden', 0)}")
+    print(f"  Avg Score: {stats.get('avg_score', 0)}")

package/scripts/send_message.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""
+Send WhatsApp Message Helper
+Wrapper around A2A Client for the most common task.
+"""
+import argparse
+import sys
+import json
+from a2a_client import A2AClient
+
+def main():
+    parser = argparse.ArgumentParser(description="Send WhatsApp message via A2A.")
+    parser.add_argument("--url", required=True, help="Full A2A API URL")
+    parser.add_argument("--key", required=True, help="API Key")
+    parser.add_argument("--to", required=True, help="Target phone number (e.g. 1234567890)")
+    parser.add_argument("--text", required=True, help="Message text content")
+    
+    args = parser.parse_args()
+    
+    client = A2AClient(args.url, args.key)
+    
+    # Construct standard A2A message payload
+    params = {
+        "phone": args.to,
+        "text": args.text
+    }
+    
+    response = client.send_rpc("message/send", params)
+    
+    # Output result
+    print(json.dumps(response, indent=2))
+    
+    # Exit code based on success
+    if "error" in response:
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()