@coremail/lunkr-openclaw 1.0.0

package/README.md

@@ -0,0 +1,221 @@
+# OpenClaw Lunkr Channel Plugin
+
+[![npm version](https://img.shields.io/npm/v/@coremail/lunkr.svg)](https://www.npmjs.com/package/@coremail/lunkr)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A channel plugin for [OpenClaw](https://github.com/openclaw/openclaw) that provides integration with [Lunkr](https://lunkr.cn), an enterprise collaboration platform from Coremail.
+
+## Overview
+
+This plugin enables OpenClaw AI agents to interact with Lunkr through:
+
+- **Direct Messages (DM)** - Private conversations between users
+- **Group Discussions** - Team collaboration channels
+- **Bot Discussions** - Dedicated groups where all messages trigger the AI agent
+
+## Requirements
+
+- **Node.js**: v22 or higher
+- **OpenClaw**: v2026.3 or higher
+- **Lunkr Account**: A valid Lunkr/Coremail account with API access
+
+## Installation
+
+### Via npm (Recommended)
+
+```bash
+npm install @coremail/lunkr
+```
+
+### Local Development
+
+```bash
+cd extensions/lunkr
+npm install
+npm run build
+```
+
+## Quick Reference
+
+| Command | Description |
+|---------|-------------|
+| `npm test` | Run tests |
+| `npm run build` | Compile TypeScript |
+| `npm run deploy:local` | Deploy to local OpenClaw |
+| `npm run pack` | Create release package |
+
+> See [DEVELOPMENT.md](./docs/DEVELOPMENT.md) for complete development guide.
+
+## Quick Start
+
+### 1. Login to Lunkr
+
+First, authenticate with your Lunkr account:
+
+```bash
+openclaw lunkr login --email your-email@example.com
+```
+
+You will be prompted for your password. The session will be stored securely in `~/.lunkr-mcp/config.json`.
+
+### 2. Enable the Channel
+
+Add Lunkr to your OpenClaw configuration:
+
+```yaml
+channels:
+  lunkr:
+    enabled: true
+    botName: "AI Assistant"
+    commandPrefix: "/bot"
+```
+
+### 3. Restart the Gateway
+
+```bash
+openclaw gateway restart
+```
+
+### 4. Start Chatting
+
+- **In Bot Discussions**: All messages automatically trigger the AI
+- **In normal groups/DMs**: Use `/bot <message>` to trigger the AI
+
+## Configuration
+
+### Basic Configuration
+
+```yaml
+channels:
+  lunkr:
+    enabled: true
+    botName: "Bot"
+    commandPrefix: "/bot"
+    dmPolicy: "allow"
+    groupPolicy: "allow"
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable/disable the channel |
+| `botName` | string | `"Bot"` | Display name for bot replies |
+| `commandPrefix` | string | `"/bot"` | Prefix to trigger bot in normal chats |
+| `dmPolicy` | string | `"allow"` | DM access policy: `allow`, `deny`, `whitelist` |
+| `allowFrom` | string[] | `[]` | Whitelisted user IDs for DM (when `dmPolicy: whitelist`) |
+| `groupPolicy` | string | `"allow"` | Group access policy: `allow`, `deny`, `whitelist` |
+| `groups` | string[] | `[]` | Whitelisted group IDs (when `groupPolicy: whitelist`) |
+| `botDiscussions` | object | `{}` | Bot discussion configurations |
+
+### Bot Discussions
+
+Bot Discussions are dedicated groups where all messages trigger the AI agent without needing a prefix:
+
+```yaml
+channels:
+  lunkr:
+    botDiscussions:
+      "discussion-id-123":
+        name: "AI Help Desk"
+        agentId: "support-agent"
+        creatorUid: "user-456"
+        createdAt: "2024-01-15T10:30:00Z"
+```
+
+### Multi-Agent Routing
+
+You can route different Bot Discussions to different AI agents:
+
+```yaml
+channels:
+  lunkr:
+    botDiscussions:
+      "sales-discussion":
+        name: "Sales Bot"
+        agentId: "sales-agent"
+        creatorUid: "admin"
+        createdAt: "2024-01-01T00:00:00Z"
+      "support-discussion":
+        name: "Support Bot"
+        agentId: "support-agent"
+        creatorUid: "admin"
+        createdAt: "2024-01-01T00:00:00Z"
+```
+
+## Security
+
+### DM Policies
+
+- **`allow`** (default): Accept DMs from all users
+- **`deny`**: Reject all DMs
+- **`whitelist`**: Only accept DMs from users in `allowFrom`
+
+### Group Policies
+
+- **`allow`** (default): Respond in all groups when mentioned
+- **`deny`**: Never respond in groups
+- **`whitelist`**: Only respond in groups listed in `groups`
+
+### Pairing
+
+Users can pair with the bot to be added to the whitelist:
+
+```bash
+# User sends a pairing code
+openclaw pairing approve lunkr <code>
+```
+
+## Troubleshooting
+
+### Login Fails
+
+1. Verify your email and password are correct
+2. Check if your Lunkr server is accessible
+3. Ensure your account has API access enabled
+
+### Bot Not Responding
+
+1. Check the gateway logs: `openclaw gateway logs`
+2. Verify the channel is enabled in configuration
+3. Ensure you're using the correct command prefix (`/bot` by default)
+4. For DMs, verify the `dmPolicy` allows messages from your user
+
+### Session Expired
+
+If you see authentication errors:
+
+```bash
+openclaw lunkr logout
+openclaw lunkr login --email your-email@example.com
+```
+
+### Connection Issues
+
+1. Check your network connectivity
+2. Verify the Lunkr server URL is correct
+3. Check if there's a firewall blocking WebSocket connections
+
+## Capabilities
+
+| Feature | Supported |
+|---------|-----------|
+| Direct Messages | Yes |
+| Group Messages | Yes |
+| Message Editing | Yes |
+| Message Replies | Yes |
+| Message Reactions | Yes |
+| Media Attachments | Yes |
+| Streaming Responses | Yes (blocked) |
+| Polls | No |
+| Threads | No |
+| Group Management | No |
+
+## License
+
+MIT License - See [LICENSE](LICENSE) for details.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/openclaw/openclaw/issues)
+- **Documentation**: [OpenClaw Docs](https://docs.openclaw.dev/channels/lunkr)