enya-agent 0.1.0

package/docs/content/channels/telegram.md

@@ -0,0 +1,182 @@
++++
+title = "Telegram"
+weight = 1
++++
+
+# Telegram Channel
+
+Deploy your Enact agent to Telegram.
+
+## Status
+
+| Feature | Status |
+|---------|--------|
+| Bot API Integration | ✅ Implemented |
+| Text Messages | ✅ Implemented |
+| Inline Keyboards | ✅ Implemented |
+| Media Support | ✅ Implemented |
+| Webhook Mode | ✅ Implemented |
+| Polling Mode | ✅ Implemented |
+| Group Chats | ✅ Implemented |
+
+## Setup
+
+### 1. Create a Bot
+
+1. Open Telegram and message [@BotFather](https://t.me/botfather)
+2. Send `/newbot`
+3. Follow prompts to name your bot
+4. Copy the bot token (looks like `123456:ABC-DEF...`)
+
+### 2. Configure Environment
+
+```bash
+# .env
+TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
+```
+
+### 3. Run Channel (Rust API)
+
+```rust
+use enact_channels::telegram::{TelegramChannel, TelegramConfig};
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    let config = TelegramConfig {
+        bot_token: std::env::var("TELEGRAM_BOT_TOKEN")?,
+        ..Default::default()
+    };
+
+    let channel = TelegramChannel::new(config)?;
+    channel.run().await?;
+
+    Ok(())
+}
+```
+
+## Configuration Options
+
+```rust
+pub struct TelegramConfig {
+    /// Bot API token from BotFather
+    pub bot_token: String,
+
+    /// Allowed user IDs (empty = allow all)
+    pub allowed_users: Vec<i64>,
+
+    /// Polling timeout in seconds
+    pub poll_timeout: u64,  // default: 30
+
+    /// Webhook URL (if using webhook mode)
+    pub webhook_url: Option<String>,
+}
+```
+
+## Features
+
+### Receiving Messages
+
+```rust
+let message = channel.receive().await?;
+
+match message.message_type {
+    MessageType::Text(text) => {
+        println!("Received: {}", text);
+    }
+    MessageType::Photo(photo) => {
+        println!("Photo: {}", photo.file_id);
+    }
+    MessageType::Callback(data) => {
+        println!("Callback: {}", data);
+    }
+}
+```
+
+### Sending Messages
+
+```rust
+// Simple text
+channel.send(OutgoingMessage {
+    chat_id: message.chat_id,
+    text: "Hello!".to_string(),
+    ..Default::default()
+}).await?;
+
+// With inline keyboard
+let keyboard = InlineKeyboard::new()
+    .row(vec![
+        ("Option A", "callback_a"),
+        ("Option B", "callback_b"),
+    ]);
+
+channel.send(OutgoingMessage {
+    chat_id: message.chat_id,
+    text: "Choose:".to_string(),
+    reply_markup: Some(keyboard.into()),
+    ..Default::default()
+}).await?;
+```
+
+## Webhook Mode
+
+For production, use webhooks instead of polling:
+
+```rust
+let config = TelegramConfig {
+    bot_token: std::env::var("TELEGRAM_BOT_TOKEN")?,
+    webhook_url: Some("https://your-domain.com/telegram/webhook".to_string()),
+    ..Default::default()
+};
+```
+
+**Requirements:**
+- Valid HTTPS domain
+- SSL certificate
+- Public accessibility
+
+## Security
+
+### User Allowlist
+
+Restrict who can use the bot:
+
+```rust
+let config = TelegramConfig {
+    allowed_users: vec![123456789, 987654321],
+    ..Default::default()
+};
+```
+
+### Rate Limiting
+
+Built-in rate limiting prevents abuse:
+
+```rust
+use enact_channels::security::RateLimiter;
+
+let limiter = RateLimiter::new(
+    10,                        // max messages
+    Duration::from_secs(60),   // per minute
+);
+```
+
+## Integration with Agents (🚧 Future)
+
+```yaml
+# agent.yaml
+name: telegram-assistant
+triggers:
+  - "channel:telegram"
+
+nodes:
+  respond:
+    type: llm
+    system_prompt: "You are a helpful Telegram bot."
+    edges:
+      _default: END
+```
+
+```bash
+# Deploy to Telegram
+enact deploy --channel telegram --agent agent.yaml
+```

package/docs/content/channels/webhook.md

@@ -0,0 +1,423 @@
++++
+title = "Generic Webhook Channel"
+weight = 9
++++
+
+# Generic Webhook Channel
+
+The `WebhookChannel` provides a generic HTTP webhook endpoint for receiving messages from any service that can send HTTP POST requests.
+
+## Overview
+
+The webhook channel enables:
+
+- **Custom integrations** with any HTTP-capable service
+- **Message queuing** for async processing
+- **Secret verification** for security
+- **Response storage** for reply tracking
+
+## Quick Start
+
+```rust
+use enact_channels::WebhookChannel;
+
+// Create webhook channel
+let webhook = WebhookChannel::new("/webhook/incoming");
+
+// Or with secret verification
+let webhook = WebhookChannel::new("/webhook/incoming")
+    .with_secret("my-secret-token");
+
+// Parse incoming payload
+let payload = serde_json::json!({
+    "from": "user@example.com",
+    "message": "Hello from webhook!"
+});
+
+let headers = std::collections::HashMap::new();
+
+if let Some(message) = webhook.parse_payload(&payload, &headers)? {
+    println!("From: {}", message.sender);
+    println!("Content: {}", message.content);
+    
+    // Queue for processing
+    webhook.queue_message(message).await;
+}
+```
+
+## Integration with Gateway
+
+```rust
+use enact_channels::WebhookChannel;
+use enact_gateway::{GatewayState, serve, GatewayConfig};
+use std::sync::Arc;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    // Create webhook channel
+    let webhook = Arc::new(
+        WebhookChannel::new("/webhook/custom")
+            .with_secret(std::env::var("WEBHOOK_SECRET")?)
+    );
+    
+    // Create gateway state with webhook responder
+    let state = GatewayState {
+        channels: vec![webhook.clone()],
+        ..Default::default()
+    };
+    
+    // Start gateway
+    let config = GatewayConfig {
+        port: 8080,
+        ..Default::default()
+    };
+    
+    serve(config, state).await
+}
+```
+
+## Payload Format
+
+### Standard Format
+
+```json
+{
+  "from": "user@example.com",
+  "message": "Hello, this is the message content",
+  "id": "optional-message-id",
+  "timestamp": 1704067200
+}
+```
+
+### Minimal Format
+
+```json
+{
+  "from": "service-name",
+  "message": "Message content"
+}
+```
+
+### With Extra Fields
+
+```json
+{
+  "from": "user@example.com",
+  "message": "Hello!",
+  "id": "msg-123",
+  "timestamp": 1704067200,
+  "custom_field": "value",
+  "metadata": {
+    "priority": "high"
+  }
+}
+```
+
+## Security
+
+### Secret Verification
+
+```rust
+use enact_channels::WebhookChannel;
+use std::collections::HashMap;
+
+let webhook = WebhookChannel::new("/webhook")
+    .with_secret("super-secret-token");
+
+// Incoming request must include Authorization header
+let mut headers = HashMap::new();
+headers.insert(
+    "Authorization".to_string(),
+    "Bearer super-secret-token".to_string()
+);
+
+// This will succeed
+let result = webhook.parse_payload(&payload, &headers
+);
+
+// Without header or wrong token
+let empty_headers = HashMap::new();
+let result = webhook.parse_payload(&payload, &empty_headers
+);
+// Returns error: "Invalid or missing authorization header"
+```
+
+### Custom Header Names
+
+```rust
+// Verify using custom header
+headers.insert(
+    "X-Webhook-Secret".to_string(),
+    "super-secret-token".to_string()
+);
+
+// The tool checks both:
+// - Authorization header
+// - X-Webhook-Secret header
+```
+
+## Message Processing
+
+### Async Queue
+
+```rust
+use enact_channels::WebhookChannel;
+
+let webhook = WebhookChannel::new("/webhook");
+
+// In your HTTP handler
+async fn handle_webhook(
+    webhook: Arc<WebhookChannel>,
+    payload: serde_json::Value,
+) -> anyhow::Result<()> {
+    let headers = extract_headers(&payload);
+    
+    if let Some(message) = webhook.parse_payload(&payload, &headers)? {
+        // Queue for async processing
+        webhook.queue_message(message).await;
+    }
+    
+    Ok(())
+}
+
+// Process queue in background
+async fn process_queue(webhook: Arc<WebhookChannel>) {
+    loop {
+        let messages = webhook.drain_messages().await;
+        
+        for message in messages {
+            // Process each message
+            process_message(message).await;
+        }
+        
+        tokio::time::sleep(Duration::from_secs(1)).await;
+    }
+}
+```
+
+### Response Storage
+
+```rust
+// Store a response for a message
+webhook.store_response("msg-123", "Processing complete").await;
+
+// Retrieve response later
+if let Some(response) = webhook.get_response("msg-123").await {
+    println!("Response: {}", response);
+}
+```
+
+## Complete Example
+
+```rust
+use enact_channels::{WebhookChannel, ChannelMessage};
+use axum::{
+    extract::State,
+    http::StatusCode,
+    routing::post,
+    Json, Router,
+};
+use std::sync::Arc;
+use std::collections::HashMap;
+
+struct AppState {
+    webhook: Arc<WebhookChannel>,
+}
+
+#[tokio::main]
+async fn main() {
+    let webhook = Arc::new(
+        WebhookChannel::new("/webhook/custom")
+            .with_secret("my-secret")
+    );
+    
+    let app = Router::new()
+        .route("/webhook/custom", post(webhook_handler))
+        .with_state(AppState { webhook: webhook.clone() });
+    
+    // Start message processor in background
+    tokio::spawn(process_messages(webhook));
+    
+    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080")
+        .await
+        .unwrap();
+    
+    axum::serve(listener, app).await.unwrap();
+}
+
+async fn webhook_handler(
+    State(state): State<AppState>,
+    headers: axum::http::HeaderMap,
+    Json(payload): Json<serde_json::Value>,
+) -> StatusCode {
+    // Convert headers to HashMap
+    let header_map: HashMap<String, String> = headers
+        .iter()
+        .filter_map(|(k, v)| {
+            v.to_str().ok().map(|v| (k.to_string(), v.to_string()))
+        })
+        .collect();
+    
+    // Parse payload
+    match state.webhook.parse_payload(&payload, &header_map) {
+        Ok(Some(message)) => {
+            // Queue for processing
+            state.webhook.queue_message(message).await;
+            StatusCode::OK
+        }
+        Ok(None) => {
+            // Empty message, ignore
+            StatusCode::OK
+        }
+        Err(e) => {
+            eprintln!("Webhook error: {}", e);
+            StatusCode::BAD_REQUEST
+        }
+    }
+}
+
+async fn process_messages(webhook: Arc<WebhookChannel>) {
+    loop {
+        let messages = webhook.drain_messages().await;
+        
+        for message in messages {
+            // Process the message
+            let response = process_message(&message).await;
+            
+            // Store response
+            webhook.store_response(&message.id, &response).await;
+        }
+        
+        tokio::time::sleep(tokio::time::Duration::from_secs(1)).await;
+    }
+}
+
+async fn process_message(message: &ChannelMessage) -> String {
+    // Your processing logic here
+    format!("Processed message from {}: {}", 
+        message.sender, 
+        message.content
+    )
+}
+```
+
+## Testing
+
+```bash
+# Test webhook endpoint
+curl -X POST http://localhost:8080/webhook/custom \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer my-secret" \
+  -d '{
+    "from": "test-user",
+    "message": "Hello from webhook!"
+  }'
+
+# Should return 200 OK
+```
+
+## Use Cases
+
+### Custom Service Integration
+
+```rust
+// Receive notifications from your backend
+let webhook = WebhookChannel::new("/webhook/notifications");
+
+// Backend sends:
+// {
+//   "from": "billing-service",
+//   "message": "Payment received: $99.00",
+//   "metadata": { "order_id": "12345" }
+// }
+```
+
+### Slack/Discord Webhooks
+
+```rust
+// Receive Slack outgoing webhooks
+let webhook = WebhookChannel::new("/webhook/slack")
+    .with_secret(slack_signing_secret);
+```
+
+### GitHub Webhooks
+
+```rust
+// Receive GitHub events
+let webhook = WebhookChannel::new("/webhook/github")
+    .with_secret(github_webhook_secret);
+
+// Process push events, PR updates, etc.
+```
+
+### Custom Chatbots
+
+```rust
+// Your own chat service
+let webhook = WebhookChannel::new("/webhook/chat");
+
+// Mobile app sends messages via webhook
+// Agent processes and responds
+```
+
+## Comparison with Platform Channels
+
+| Feature | Webhook | WhatsApp | Telegram | Teams |
+|---------|---------|----------|----------|-------|
+| **Setup** | Manual | Meta API | Bot API | Azure |
+| **Flexibility** | ✅ Any service | ❌ WhatsApp only | ❌ Telegram only | ❌ Teams only |
+| **Security** | Custom secret | Signature | Token | Signature |
+| **Complexity** | Low | Medium | Low | Medium |
+| **Use Case** | Custom integrations | Mobile chat | Mobile chat | Enterprise |
+
+## Configuration
+
+```yaml
+# config.yaml
+channels:
+  webhook:
+    enabled: true
+    endpoint: "/webhook/custom"
+    secret: "${WEBHOOK_SECRET}"
+    
+    # Optional: custom response handling
+    store_responses: true
+    max_queue_size: 1000
+```
+
+## Error Handling
+
+```rust
+match webhook.parse_payload(&payload, &headers) {
+    Ok(Some(message)) => {
+        // Process message
+    }
+    Ok(None) => {
+        // Empty or invalid message
+        println!("No message in payload");
+    }
+    Err(e) if e.to_string().contains("authorization") => {
+        // Secret verification failed
+        eprintln!("Unauthorized webhook request");
+    }
+    Err(e) => {
+        // Other error
+        eprintln!("Webhook error: {}", e);
+    }
+}
+```
+
+## Best Practices
+
+1. **Always use secrets** in production
+2. **Validate payloads** before processing
+3. **Queue messages** for async processing
+4. **Implement retries** for failed processing
+5. **Log webhook events** for debugging
+6. **Rate limit** endpoints to prevent abuse
+
+## Resources
+
+- [enact-channels crate](/docs/crates/enact-channels/)
+- [Axum web framework](https://github.com/tokio-rs/axum)
+- [Webhook security best practices](https://webhooks.fyi/)