@lobu/cli 3.0.5 → 3.0.7

package/dist/templates/TESTING.md.tmpl

@@ -0,0 +1,225 @@
+# Testing Your Lobu
+
+This bot provides HTTP APIs for testing and automation. These endpoints allow AI agents and developers to interact with your bot programmatically.
+
+## 1. Messaging API
+
+Send messages to your bot with optional file uploads.
+
+### Endpoint
+```
+POST http://localhost:{{GATEWAY_PORT}}/api/v1/agents/{agentId}/messages
+```
+
+### Authentication
+
+**Bearer Token in Header:**
+```
+Authorization: Bearer xoxb-your-bot-token
+```
+
+The bot token must be provided in the `Authorization` header, not in the request body.
+
+### Request Format
+
+#### JSON Request (Simple Message)
+```bash
+curl -X POST http://localhost:{{GATEWAY_PORT}}/api/v1/agents/{agentId}/messages \
+  -H "Authorization: Bearer xoxb-your-bot-token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "platform": "slack",
+    "channel": "general",
+    "content": "what is 2+2?"
+  }'
+```
+
+#### Multipart Request (With File Upload)
+```bash
+curl -X POST http://localhost:{{GATEWAY_PORT}}/api/v1/agents/{agentId}/messages \
+  -H "Authorization: Bearer xoxb-your-bot-token" \
+  -F "platform=slack" \
+  -F "channel=C12345678" \
+  -F "content=please review this file" \
+  -F "file=@/path/to/document.pdf"
+```
+
+### Parameters
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `platform` | Yes | Platform name (currently: "slack") |
+| `channel` | Yes | Channel ID (e.g., `C12345678`) or name (e.g., `general`, `#general`) |
+| `content` | Yes | Message text to send (use `@me` to mention the bot) |
+| `threadId` | No | Thread ID to reply to (for thread continuity) |
+| `files` | No | File attachments (multipart/form-data, up to 10 files) |
+
+### Response Format
+
+```json
+{
+  "success": true,
+  "channel": "C12345678",
+  "messageId": "1234567890.123456",
+  "threadId": "1234567890.123456",
+  "threadUrl": "https://app.slack.com/client/T12345/C12345678/thread/1234567890.123456"
+}
+```
+
+**Note about `threadId`:**
+- When posting a new message (no `threadId` parameter), `threadId` equals `messageId`
+- When replying to a thread (with `threadId` parameter), `threadId` is the original thread's ID
+
+### Bot Mentions
+
+Use the `@me` placeholder to mention the bot in a platform-agnostic way:
+
+```json
+{
+  "content": "@me what is 2+2?"
+}
+```
+
+The API automatically replaces `@me` with the correct bot mention for the platform:
+- **Slack**: `<@U12345>` 
+- **Discord** (future): `<@123456>`
+- **Telegram** (future): `@botname`
+
+If you don't want to mention the bot, simply omit `@me` from your message.
+
+### Example: Simple Text Message (with @me)
+
+```bash
+curl -X POST http://localhost:{{GATEWAY_PORT}}/api/v1/agents/{agentId}/messages \
+  -H "Authorization: Bearer xoxb-your-bot-token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "platform": "slack",
+    "channel": "general",
+    "content": "@me what is 2+2?"
+  }'
+```
+
+### Example: Without Bot Mention
+
+```bash
+curl -X POST http://localhost:{{GATEWAY_PORT}}/api/v1/agents/{agentId}/messages \
+  -H "Authorization: Bearer xoxb-your-bot-token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "platform": "slack",
+    "channel": "general",
+    "content": "just a regular message"
+  }'
+```
+
+### Example: Thread Reply
+
+```bash
+curl -X POST http://localhost:{{GATEWAY_PORT}}/api/v1/agents/{agentId}/messages \
+  -H "Authorization: Bearer xoxb-your-bot-token" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "platform": "slack",
+    "channel": "C12345678",
+    "content": "tell me more about that",
+    "threadId": "1234567890.123456"
+  }'
+```
+
+### Example: Single File Upload
+
+```bash
+curl -X POST http://localhost:{{GATEWAY_PORT}}/api/v1/agents/{agentId}/messages \
+  -H "Authorization: Bearer xoxb-your-bot-token" \
+  -F "platform=slack" \
+  -F "channel=dev-channel" \
+  -F "content=@me analyze this CSV" \
+  -F "files=@data.csv"
+```
+
+### Example: Multiple File Upload
+
+```bash
+curl -X POST http://localhost:{{GATEWAY_PORT}}/api/v1/agents/{agentId}/messages \
+  -H "Authorization: Bearer xoxb-your-bot-token" \
+  -F "platform=slack" \
+  -F "channel=dev-channel" \
+  -F "content=@me review these documents" \
+  -F "files=@document1.pdf" \
+  -F "files=@document2.pdf" \
+  -F "files=@spreadsheet.xlsx"
+```
+
+### Channel Name Resolution
+
+The API automatically resolves channel names to IDs:
+- `"general"` → `"C12345678"`
+- `"#general"` → `"C12345678"`
+- `"C12345678"` → `"C12345678"` (already an ID)
+
+### Error Handling
+
+```json
+{
+  "success": false,
+  "error": "Failed to send message",
+  "details": "Channel \"nonexistent\" not found"
+}
+```
+
+Common errors:
+- `400`: Missing required fields (`platform`, `channel`, or `message`)
+- `401`: Missing or invalid `Authorization` header
+- `404`: Platform not found
+- `500`: Platform API error (invalid token, channel not found, etc.)
+- `501`: Platform doesn't support `sendMessage`
+
+### Platform-Agnostic Design
+
+The messaging API is designed to work across multiple chat platforms:
+
+**Current Support:**
+- Slack (bot mentions: `<@U12345>`, uses `@me` placeholder)
+
+**Future Support:**
+- Discord (bot mentions: `<@123456>`, uses `@me` placeholder)
+- Telegram (bot mentions: `@botname`, uses `@me` placeholder)
+
+The `@me` placeholder ensures your code works across all platforms without modification.
+
+---
+
+## 2. Complete E2E Testing Example
+
+Testing a full conversation:
+
+```bash
+# Step 1: Send initial message
+RESPONSE=$(curl -s -X POST http://localhost:{{GATEWAY_PORT}}/api/v1/agents/{agentId}/messages \
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "platform": "slack",
+    "channel": "test-channel",
+    "content": "@me give me three options"
+  }')
+
+THREAD_ID=$(echo $RESPONSE | jq -r '.threadId')
+echo "Thread ID: $THREAD_ID"
+
+# Step 2: Verify bot response
+# (Check thread for follow-up message)
+```
+
+---
+
+## 4. Notes for AI Agents
+
+These APIs enable your AI agents to:
+- **Test connectivity**: Verify bot deployment is working
+- **E2E testing**: Automate full conversation flows
+- **CI/CD integration**: Run automated tests before deployment
+- **Development**: Quickly test bot behavior without manual Slack interaction
+
+The messaging endpoint is **platform-agnostic** by design. While Slack is currently supported, the same API structure will work for Discord, Teams, and other platforms in the future.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lobu/cli",
-  "version": "3.0.5",
+  "version": "3.0.7",
   "description": "CLI for deploying and managing AI agents on Lobu",
   "type": "module",
   "main": "dist/index.js",