@lansenger-pm/openclaw-lansenger-channel 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lansenger OpenClaw Channel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.fr.md

@@ -0,0 +1,301 @@
+[English](README.md) | [简体中文](README.zhHans.md) | [繁体中文](README.zhHant.md) | [繁体中文香港](README.zhHantHK.md) | [Français](README.fr.md)
+
+# @lansenger/openclaw-lansenger-channel
+
+> 💠 Plugin de canal Lansenger (蓝信) pour OpenClaw — WebSocket en entrée, HTTP API en sortie.
+
+Connecte OpenClaw à Lansenger — une plateforme de messagerie d'entreprise — via une connexion longue WebSocket pour la réception de messages en temps réel et via l'API HTTP pour l'envoi de messages.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue)](https://www.typescriptlang.org/)
+
+## Fonctionnalités
+
+- **Messagerie en temps réel** via connexion longue WebSocket
+- **Support multi-bot** — lier plusieurs bots Lansenger à différents agents OpenClaw
+- **Support Markdown** utilisant le msgType `formatText` (par défaut)
+- **Fichiers/Images/Vocaux** via le msgType `text` avec upload de médias
+- **Cartes d'approbation** — workflow d'approbation interactif avec mises à jour de statut en place (en attente → approuvé/refusé)
+- **Détection de langue** — détection automatique de la langue de l'utilisateur pour des réponses localisées
+- **Routage des messages de groupe** — détection automatique et routage vers les API groupe/privé
+- **@Mentions** — support @tout et @utilisateurs spécifiques dans les chats de groupe
+- **Traitement des médias entrants** — téléchargement d'images/fichiers/vocaux, détection d'extension, chemins de fichiers pour l'agent
+- **Révocation de messages** — révoquer les messages précédemment envoyés
+- **Démarrage automatique** — la passerelle connecte automatiquement tous les comptes de bots configurés au démarrage
+- **Zéro modification du core** — mode plugin pur, `git diff HEAD` reste INTACT
+
+## Matrice de capacités des types de messages
+
+| msgType     | Markdown | @mention | Pièces jointes |
+|-------------|----------|----------|-----------------|
+| `text`      | ✗        | ✓        | ✓               |
+| `formatText`| ✓        | ✗        | ✗               |
+
+**Stratégie par défaut** : utiliser `formatText` en priorité pour les réponses Markdown. Revenir à `text` pour les pièces jointes.
+
+## Installation rapide
+
+### Via npm (recommandé)
+
+```bash
+npm install -g @lansenger/openclaw-lansenger-channel
+openclaw plugins enable lansenger
+```
+
+### Installation manuelle
+
+```bash
+cd ~/.openclaw/npm
+npm install @lansenger/openclaw-lansenger-channel
+openclaw plugins enable lansenger
+openclaw gateway restart
+```
+
+### Installation de développement (lien local)
+
+```bash
+cd /path/to/openclaw-lansenger-channel
+npm install
+openclaw plugins install --link
+openclaw plugins enable lansenger
+openclaw gateway restart
+```
+
+## Configuration
+
+### Variables d'environnement requises
+
+Ajoutez ces variables à `~/.openclaw/.env` ou à votre environnement :
+
+| Variable | Description | Exemple |
+|----------|-------------|---------|
+| `LANSENGER_APP_ID` | App ID du bot personnel | `your-appid` |
+| `LANSENGER_APP_SECRET` | App Secret du bot personnel | `57E718CA1CAC20F2...` |
+| `LANSENGER_API_GATEWAY_URL` | URL de la passerelle API Lansenger (remplacement) | `https://open.e.lanxin.cn/open/apigw` |
+
+### Obtenir les identifiants
+
+**Client Lansenger (desktop)** → **Contacts** → **Bots** → **Bots personnels** → cliquer sur l'icône **ℹ️**
+
+> ⚠️ **Le client mobile ne permet pas de voir les identifiants.** Utilisez uniquement le client desktop.
+
+### Configuration optionnelle
+
+```json
+{
+  "channels": {
+    "lansenger": {
+      "appId": "your-appid",
+      "appSecret": "your-secret",
+      "apiGatewayUrl": "https://open.e.lanxin.cn/open/apigw",
+      "homeChannel": "lansenger",
+      "enabled": true,
+      "allowFrom": ["your-appid"],
+      "dmSecurity": "allowlist",
+      "accounts": {
+        "your-appid": {
+          "appId": "your-appid",
+          "appSecret": "...",
+          "agentId": "main",
+          "apiGatewayUrl": "https://open.e.lanxin.cn/open/apigw"
+        }
+      }
+    }
+  }
+}
+```
+
+| Champ | Description | Valeur par défaut |
+|-------|-------------|-------------------|
+| `appId` | App ID du bot personnel | — |
+| `appSecret` | App Secret du bot personnel | — |
+| `apiGatewayUrl` | URL de la passerelle API | `https://open.e.lanxin.cn/open/apigw` |
+| `homeChannel` | Canal par défaut pour le routage de l'agent | `lansenger` |
+| `enabled` | Activer/désactiver le canal | `true` |
+| `allowFrom` | IDs d'utilisateurs autorisés en DM | `[]` |
+| `dmSecurity` | Politique DM : `allowlist`, `open`, `paired` | `allowlist` |
+| `accounts` | Configuration multi-bot | — |
+
+### Configuration multi-bot
+
+Chaque bot peut être lié à un agent OpenClaw différent :
+
+```json
+{
+  "channels": {
+    "lansenger": {
+      "accounts": {
+        "bot1-appid": {
+          "appId": "your-appid",
+          "appSecret": "...",
+          "agentId": "main-agent",
+          "apiGatewayUrl": "https://open.e.lanxin.cn/open/apigw"
+        },
+        "bot2-appid": {
+          "appId": "your-other-appid",
+          "appSecret": "...",
+          "agentId": "test-agent"
+        }
+      }
+    }
+  },
+  "bindings": [
+    { "match": { "channel": "lansenger", "accountId": "bot1-appid" }, "agentId": "main-agent" }
+  ]
+}
+```
+
+## Utilisation
+
+La passerelle démarre automatiquement tous les comptes configurés au démarrage. La méthode `lansenger.start` est disponible pour démarrer dynamiquement des comptes supplémentaires.
+
+### Démarrer la passerelle (dynamique)
+
+```bash
+openclaw gateway call lansenger.start
+```
+
+### Arrêter la passerelle
+
+```bash
+openclaw gateway call lansenger.stop
+```
+
+### Vérifier le statut
+
+```bash
+openclaw channels status
+# ou
+openclaw gateway call lansenger.status
+```
+
+### Lier un bot à un agent (dynamique)
+
+```bash
+openclaw gateway call lansenger.bind '{"botId":"your-appid","agentId":"main"}'
+```
+
+### Liste des liaisons
+
+```bash
+openclaw gateway call lansenger.bindings
+```
+
+### Délier un bot
+
+```bash
+openclaw gateway call lansenger.unbind '{"botId":"your-appid"}'
+```
+
+## Types de messages supportés
+
+| Type | Description | Méthode API | Direction |
+|------|-------------|-------------|-----------|
+| `text` | Texte brut avec @mentions et pièces jointes optionnelles | `sendText()` | Sortant |
+| `formatText` | Texte au format Markdown (par défaut) | `sendFormatText()` | Sortant |
+| `image` | Image avec légende optionnelle | `sendFile()` | Sortant |
+| `file` | Tout fichier joint | `sendFile()` | Sortant |
+| `video` | Vidéo jointe | `sendFile()` | Sortant |
+| `voice` | Message vocal | `sendFile()` | Sortant |
+| `linkCard` | Carte de prévisualisation de lien enrichi | `sendLinkCard()` | Sortant |
+| `i18nAppCard` | Réservé pour usage futur ; carte 5 langues | `sendI18nAppCard()` | Sortant |
+| `appCard` | Cartes d'approbation avec mises à jour de statut | `sendAppCard()` | Sortant |
+| `appArticles` | Carte multi-articles | `sendAppArticles()` | Sortant |
+| `position` | Message de localisation/position | — | Entrant uniquement |
+| `card` | Message de carte générique | — | Entrant uniquement |
+| `sticker` | Message sticker/emoji | — | Entrant uniquement |
+
+## Traitement des médias entrants
+
+Lorsque les utilisateurs envoient des images, vidéos, fichiers ou messages vocaux, le plugin :
+
+1. Télécharge tous les `mediaIds` via l'API média Lansenger
+2. Détecte l'extension de fichier depuis les en-têtes Content-Type/Content-Disposition (repli : octets magiques)
+3. Enregistre dans des fichiers temporaires et attache les chemins à `InboundEvent.mediaPaths[]`
+4. Ajoute un indice dans le texte de l'agent : « Fichiers joints sauvegardés localement — utilisez l'outil de lecture pour visualiser »
+
+## Flux d'approbation
+
+Le plugin supporte les cartes d'approbation :
+- Les demandes d'approbation sont envoyées via **appCard** avec `isDynamic=true`
+- Les mises à jour de statut (en attente → approuvé/refusé) mettent à jour la carte en place via **DynamicMsg**
+- La langue détectée automatiquement détermine la langue de la carte (chinois ou anglais)
+- **i18nAppCard** (5 langues) est réservé pour un usage futur et n'est pas utilisé pour l'approbation
+
+## Développement
+
+### Compilation
+
+```bash
+npm install
+npx tsc
+```
+
+### Tests
+
+```bash
+npx vitest run
+```
+
+### Vérification de types
+
+```bash
+npx tsc --noEmit
+```
+
+### Structure du projet
+
+```
+openclaw-lansenger-channel/
+├── src/
+│   ├── client.ts       # Client API Lansenger (WS, HTTP, médias)
+│   ├── channel.ts      # Plugin de canal OpenClaw
+│   ├── channel.test.ts # Tests du plugin de canal
+│   ├── runtime.ts      # Runtime passerelle (méthodes, handler entrant)
+│   └── bindings.ts     # Gestionnaire de liaisons multi-bot
+├── skills/
+│   └── lansenger-messaging/
+│       └── SKILL.md    # Stratégie de messagerie de l'agent
+├── dist/               # JavaScript compilé
+├── index.ts            # Point d'entrée du plugin
+├── setup-entry.ts      # Point d'entrée de l'assistant de configuration
+├── openclaw.plugin.json # Métadonnées du plugin & configuration GUI
+├── package.json
+└── tsconfig.json
+```
+
+## Dépannage
+
+### "Le client mobile ne permet pas de voir les identifiants"
+
+Utilisez uniquement le **client Lansenger (desktop)**. L'application mobile n'affiche pas les identifiants du bot.
+
+### "No binding for botId"
+
+Exécutez `lansenger.bind` pour lier le bot à un agent, ou configurez `agentId` dans la configuration du compte.
+
+### Déconnexions WebSocket
+
+Le plugin inclut une reconnexion automatique avec un backoff exponentiel (2s, 5s, 10s, 30s, 60s) et un heartbeat (ping toutes les 30s).
+
+### formatText vs text
+
+- Utilisez `formatText` pour les réponses Markdown (par défaut)
+- Utilisez `text` pour les @mentions ou pièces jointes
+- Pour les deux, envoyez deux messages distincts
+
+### Échec de mise à jour dynamique de carte
+
+Les mises à jour de statut d'approbation utilisent le format DynamicMsg appCard. La méthode `updateCardStatus()` gère cela automatiquement.
+
+## Licence
+
+MIT — voir [LICENSE](LICENSE).
+
+## Contribuer
+
+1. Fork le dépôt
+2. Créer une branche de fonctionnalité
+3. Effectuer vos modifications
+4. Exécuter les tests : `npx vitest run`
+5. Soumettre une pull request

package/README.md

@@ -0,0 +1,299 @@
+[English](README.md) | [简体中文](README.zhHans.md) | [繁体中文](README.zhHant.md) | [繁体中文香港](README.zhHantHK.md) | [Français](README.fr.md)
+
+# @lansenger/openclaw-lansenger-channel
+
+Lansenger (蓝信) channel plugin for OpenClaw — WebSocket inbound, HTTP API outbound.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-6.0-blue)](https://www.typescriptlang.org/)
+
+## Features
+
+- **Real-time messaging** via WebSocket long-connection
+- **Multi-bot support** — bind multiple Lansenger bots to different OpenClaw agents
+- **Markdown support** using `formatText` msgType (default)
+- **File/Image/Voice attachments** via `text` msgType with media upload
+- **Approval cards** — interactive approval workflow with in-place status updates (pending → approved/denied)
+- **Language detection** — auto-detect user language from messages for localized responses
+- **Group message routing** — auto-detect and route to group/private chat APIs
+- **@Mentions** — support @all and @specific users in group chats
+- **Inbound media processing** — download images/files/voice, detect extension, provide file paths to agent
+- **Message revocation** — revoke previously sent messages
+- **Auto-start** — gateway automatically connects all configured bot accounts on boot
+- **Zero core modification** — pure plugin mode, `git diff HEAD` stays PRISTINE
+
+## Message Type Capability Matrix
+
+| msgType     | Markdown | @mention | Attachments |
+|-------------|----------|----------|-------------|
+| `text`      | ✗        | ✓        | ✓           |
+| `formatText`| ✓        | ✗        | ✗           |
+
+**Default strategy**: Use `formatText` first for Markdown replies. Fall back to `text` for attachments.
+
+## Quick Install
+
+### Via npm (recommended)
+
+```bash
+npm install -g @lansenger/openclaw-lansenger-channel
+openclaw plugins enable lansenger
+```
+
+### Manual install
+
+```bash
+cd ~/.openclaw/npm
+npm install @lansenger/openclaw-lansenger-channel
+openclaw plugins enable lansenger
+openclaw gateway restart
+```
+
+### Development install (linked)
+
+```bash
+cd /path/to/openclaw-lansenger-channel
+npm install
+openclaw plugins install --link
+openclaw plugins enable lansenger
+openclaw gateway restart
+```
+
+## Configuration
+
+### Required Environment Variables
+
+Add these to `~/.openclaw/.env` or your environment:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `LANSENGER_APP_ID` | Personal bot App ID | `your-appid` |
+| `LANSENGER_APP_SECRET` | Personal bot App Secret | `57E718CA1CAC20F2...` |
+| `LANSENGER_API_GATEWAY_URL` | Lansenger API Gateway URL override | `https://open.e.lanxin.cn/open/apigw` |
+
+### Get Credentials
+
+**Lansenger Desktop** → **Contacts** → **Bots** → **Personal Bots** → click **ℹ️** icon
+
+> ⚠️ **Mobile client does NOT support viewing credentials.** Use the desktop client only.
+
+### Optional Configuration
+
+```json
+{
+  "channels": {
+    "lansenger": {
+      "appId": "your-appid",
+      "appSecret": "your-secret",
+      "apiGatewayUrl": "https://open.e.lanxin.cn/open/apigw",
+      "homeChannel": "lansenger",
+      "enabled": true,
+      "allowFrom": ["your-appid"],
+      "dmSecurity": "allowlist",
+      "accounts": {
+        "your-appid": {
+          "appId": "your-appid",
+          "appSecret": "...",
+          "agentId": "main",
+          "apiGatewayUrl": "https://open.e.lanxin.cn/open/apigw"
+        }
+      }
+    }
+  }
+}
+```
+
+| Field | Description | Default |
+|-------|-------------|---------|
+| `appId` | Personal bot App ID | — |
+| `appSecret` | Personal bot App Secret | — |
+| `apiGatewayUrl` | API Gateway URL | `https://open.e.lanxin.cn/open/apigw` |
+| `homeChannel` | Default channel for agent routing | `lansenger` |
+| `enabled` | Enable/disable the channel | `true` |
+| `allowFrom` | User IDs allowed to DM the bot | `[]` |
+| `dmSecurity` | DM policy: `allowlist`, `open`, `paired` | `allowlist` |
+| `accounts` | Multi-bot configuration | — |
+
+### Multi-Bot Configuration
+
+Each bot can be bound to a different OpenClaw agent:
+
+```json
+{
+  "channels": {
+    "lansenger": {
+      "accounts": {
+        "bot1-appid": {
+          "appId": "your-appid",
+          "appSecret": "...",
+          "agentId": "main-agent",
+          "apiGatewayUrl": "https://open.e.lanxin.cn/open/apigw"
+        },
+        "bot2-appid": {
+          "appId": "your-other-appid",
+          "appSecret": "...",
+          "agentId": "test-agent"
+        }
+      }
+    }
+  },
+  "bindings": [
+    { "match": { "channel": "lansenger", "accountId": "bot1-appid" }, "agentId": "main-agent" }
+  ]
+}
+```
+
+## Usage
+
+The gateway auto-starts all configured accounts on boot. The `lansenger.start` method is available for dynamic start of additional accounts.
+
+### Start the gateway (dynamic)
+
+```bash
+openclaw gateway call lansenger.start
+```
+
+### Stop the gateway
+
+```bash
+openclaw gateway call lansenger.stop
+```
+
+### Check status
+
+```bash
+openclaw channels status
+# or
+openclaw gateway call lansenger.status
+```
+
+### Bind a bot to an agent (dynamic)
+
+```bash
+openclaw gateway call lansenger.bind '{"botId":"your-appid","agentId":"main"}'
+```
+
+### List bindings
+
+```bash
+openclaw gateway call lansenger.bindings
+```
+
+### Unbind a bot
+
+```bash
+openclaw gateway call lansenger.unbind '{"botId":"your-appid"}'
+```
+
+## Supported Message Types
+
+| Type | Description | API Method | Direction |
+|------|-------------|------------|-----------|
+| `text` | Plain text with optional @mentions and attachments | `sendText()` | Outbound |
+| `formatText` | Markdown-formatted text (default) | `sendFormatText()` | Outbound |
+| `image` | Image with optional caption | `sendFile()` | Outbound |
+| `file` | Any file attachment | `sendFile()` | Outbound |
+| `video` | Video attachment | `sendFile()` | Outbound |
+| `voice` | Voice message | `sendFile()` | Outbound |
+| `linkCard` | Rich link preview card | `sendLinkCard()` | Outbound |
+| `i18nAppCard` | Reserved for future use; 5-language card | `sendI18nAppCard()` | Outbound |
+| `appCard` | Approval cards with status updates | `sendAppCard()` | Outbound |
+| `appArticles` | Multi-article card | `sendAppArticles()` | Outbound |
+| `position` | Location/position message | — | Inbound-only |
+| `card` | Generic card message | — | Inbound-only |
+| `sticker` | Sticker/emoji message | — | Inbound-only |
+
+## Inbound Media Handling
+
+When users send images, videos, files, or voice messages, the plugin:
+
+1. Downloads all `mediaIds` via the Lansenger media API
+2. Detects file extension from Content-Type/Content-Disposition headers (fallback: magic bytes)
+3. Saves to temp files and attaches paths to `InboundEvent.mediaPaths[]`
+4. Adds a hint in agent text: "Attached files saved locally — use the read tool to view"
+
+## Approval Workflow
+
+The plugin supports approval workflow cards:
+- Approval requests are sent as **appCard** with `isDynamic=true`
+- Status updates (pending → approved/denied) update the card in-place via **DynamicMsg**
+- Language detection: the card is sent in the user's detected language (Chinese or English)
+- **i18nAppCard** (5-language) is reserved for future use but not currently used for approval
+
+## Development
+
+### Build
+
+```bash
+npm install
+npx tsc
+```
+
+### Test
+
+```bash
+npx vitest run
+```
+
+### Typecheck
+
+```bash
+npx tsc --noEmit
+```
+
+### Project Structure
+
+```
+openclaw-lansenger-channel/
+├── src/
+│   ├── client.ts       # Lansenger API client (WS, HTTP, media)
+│   ├── channel.ts      # OpenClaw channel plugin
+│   ├── channel.test.ts # Channel plugin tests
+│   ├── runtime.ts      # Gateway runtime (methods, inbound handler)
+│   └── bindings.ts     # Multi-bot binding manager
+├── skills/
+│   └── lansenger-messaging/
+│       └── SKILL.md    # Agent messaging strategy
+├── dist/               # Compiled JavaScript
+├── index.ts            # Plugin entry point
+├── setup-entry.ts      # Setup wizard entry
+├── openclaw.plugin.json # Plugin metadata & GUI config
+├── package.json
+└── tsconfig.json
+```
+
+## Troubleshooting
+
+### "Mobile client does NOT support viewing credentials"
+
+Use the **Lansenger Desktop** client only. The mobile app does not display bot credentials.
+
+### "No binding for botId"
+
+Run `lansenger.bind` to bind the bot to an agent, or configure `agentId` in the account config.
+
+### WebSocket disconnects
+
+The plugin includes automatic reconnection with exponential backoff (2s, 5s, 10s, 30s, 60s) and heartbeat (ping every 30s).
+
+### formatText vs text
+
+- Use `formatText` for Markdown replies (default)
+- Use `text` for @mentions or attachments
+- For both, send two separate messages
+
+### Dynamic card update fails
+
+Approval status updates use the DynamicMsg appCard format. The `updateCardStatus()` method handles this automatically.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Run tests: `npx vitest run`
+5. Submit a pull request