Initial commit: OpenClaw Mattermost Extension
This commit is contained in:
@@ -0,0 +1,562 @@
|
||||
# Migration Guide
|
||||
|
||||
Guide for migrating from the stock Mattermost extension to the Enhanced Mattermost Extension.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Before You Begin](#before-you-begin)
|
||||
- [Configuration Migration](#configuration-migration)
|
||||
- [Breaking Changes](#breaking-changes)
|
||||
- [Feature Upgrades](#feature-upgrades)
|
||||
- [Code Migration](#code-migration)
|
||||
- [Verification](#verification)
|
||||
- [Rollback Plan](#rollback-plan)
|
||||
|
||||
## Overview
|
||||
|
||||
The Enhanced Mattermost Extension is a drop-in replacement for the stock extension with additional features and improved security. Most existing configurations will work without changes, but there are some differences to be aware of.
|
||||
|
||||
### Key Differences
|
||||
|
||||
| Aspect | Stock Extension | Enhanced Extension |
|
||||
|--------|--------------|-------------------|
|
||||
| Package name | `@modelcontextprotocol/mattermost` | `@lumbridgecorp/openclaw-mattermost` |
|
||||
| Token support | Bot token only | Bot token + PAT |
|
||||
| Message operations | Send only | Send, edit, delete |
|
||||
| File operations | None | Download with security |
|
||||
| Interactive components | None | Buttons and selects |
|
||||
| Security audit | None | Built-in |
|
||||
| Error handling | Basic | Structured with retry |
|
||||
| Configuration | Simple | Extended but backward compatible |
|
||||
|
||||
## Before You Begin
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. **Backup your configuration** before making any changes
|
||||
2. **Review current usage** of Mattermost features in your code
|
||||
3. **Check Node.js version** - requires Node.js 22+ (up from 18+)
|
||||
4. **Plan for downtime** during the migration window
|
||||
|
||||
### Compatibility Check
|
||||
|
||||
Run this check to see if your current configuration is compatible:
|
||||
|
||||
```bash
|
||||
# Install the enhanced extension alongside your current one
|
||||
npm install @lumbridgecorp/openclaw-mattermost
|
||||
|
||||
# Run the security audit to check configuration
|
||||
npx openclaw doctor --channel=mattermost
|
||||
```
|
||||
|
||||
## Configuration Migration
|
||||
|
||||
### Simple Migration (No Code Changes)
|
||||
|
||||
If you're using basic features, simply update your package.json:
|
||||
|
||||
```diff
|
||||
{
|
||||
"dependencies": {
|
||||
- "@modelcontextprotocol/mattermost": "^0.x.x"
|
||||
+ "@lumbridgecorp/openclaw-mattermost": "^1.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Your existing configuration will continue to work:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"mattermost": {
|
||||
"baseUrl": "https://chat.example.com",
|
||||
"botToken": "${MATTERMOST_BOT_TOKEN}",
|
||||
"team": "myteam"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Enhanced Configuration (Recommended)
|
||||
|
||||
Take advantage of new security features by updating your configuration:
|
||||
|
||||
#### Before (Stock Extension)
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"mattermost": {
|
||||
"url": "https://chat.example.com",
|
||||
"token": "${MATTERMOST_TOKEN}",
|
||||
"team": "engineering"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### After (Enhanced Extension)
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"mattermost": {
|
||||
"baseUrl": "https://chat.example.com",
|
||||
"botToken": "${MATTERMOST_BOT_TOKEN}",
|
||||
"dmPolicy": "pairing",
|
||||
"allowFrom": ["user1-id", "user2-id"],
|
||||
"groupPolicy": "allowlist",
|
||||
"groupAllowFrom": ["user1-id", "user2-id"],
|
||||
"interactions": {
|
||||
"callbackBaseUrl": "https://bot.example.com/callbacks",
|
||||
"allowedSourceIps": ["10.0.0.0/8"]
|
||||
},
|
||||
"actions": {
|
||||
"reactions": true,
|
||||
"downloadFile": true,
|
||||
"delete": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Multi-Account Configuration
|
||||
|
||||
The enhanced extension supports multiple Mattermost accounts:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"mattermost": {
|
||||
"accounts": {
|
||||
"production": {
|
||||
"baseUrl": "https://chat.company.com",
|
||||
"botToken": "${PROD_BOT_TOKEN}",
|
||||
"dmPolicy": "allowlist"
|
||||
},
|
||||
"staging": {
|
||||
"baseUrl": "https://chat-staging.company.com",
|
||||
"botToken": "${STAGING_BOT_TOKEN}",
|
||||
"dmPolicy": "open"
|
||||
}
|
||||
},
|
||||
"defaultAccount": "production"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
### 1. Import Path Changes
|
||||
|
||||
**Before:**
|
||||
```typescript
|
||||
import { sendMessage } from '@modelcontextprotocol/mattermost';
|
||||
```
|
||||
|
||||
**After:**
|
||||
```typescript
|
||||
import { sendMessage } from '@lumbridgecorp/openclaw-mattermost';
|
||||
```
|
||||
|
||||
### 2. Configuration Property Names
|
||||
|
||||
Some property names have changed for clarity:
|
||||
|
||||
| Old Name | New Name | Notes |
|
||||
|----------|----------|-------|
|
||||
| `url` | `baseUrl` | Both work, `baseUrl` preferred |
|
||||
| `token` | `botToken` | Both work, `botToken` preferred |
|
||||
|
||||
### 3. Environment Variable Names
|
||||
|
||||
If you used the stock extension's environment variables:
|
||||
|
||||
| Old Variable | New Variable | Notes |
|
||||
|--------------|--------------|-------|
|
||||
| `MATTERMOST_URL` | `MATTERMOST_URL` | No change |
|
||||
| `MATTERMOST_TOKEN` | `MATTERMOST_BOT_TOKEN` | Recommended change |
|
||||
| - | `MATTERMOST_PAT` | New optional PAT variable |
|
||||
|
||||
Both old and new variable names are supported for backward compatibility.
|
||||
|
||||
### 4. Type Changes
|
||||
|
||||
Some TypeScript types have been renamed or extended:
|
||||
|
||||
**Before:**
|
||||
```typescript
|
||||
import { MattermostConfig } from '@modelcontextprotocol/mattermost';
|
||||
```
|
||||
|
||||
**After:**
|
||||
```typescript
|
||||
import { MattermostAccountConfig, MattermostConfig } from '@lumbridgecorp/openclaw-mattermost';
|
||||
```
|
||||
|
||||
## Feature Upgrades
|
||||
|
||||
### Adding PAT Support
|
||||
|
||||
**Step 1:** Create a Personal Access Token in Mattermost
|
||||
|
||||
1. Log in to Mattermost as the bot owner
|
||||
2. Go to Account Settings > Security > Personal Access Tokens
|
||||
3. Create a new token
|
||||
|
||||
**Step 2:** Add PAT to your configuration
|
||||
|
||||
```bash
|
||||
export MATTERMOST_PAT="your-pat-here"
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"mattermost": {
|
||||
"baseUrl": "https://chat.example.com",
|
||||
"botToken": "${MATTERMOST_BOT_TOKEN}",
|
||||
"pat": "${MATTERMOST_PAT}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Enabling Interactive Components
|
||||
|
||||
Add interaction configuration to enable buttons and selects:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"mattermost": {
|
||||
"baseUrl": "https://chat.example.com",
|
||||
"botToken": "${MATTERMOST_BOT_TOKEN}",
|
||||
"interactions": {
|
||||
"callbackBaseUrl": "https://your-bot.example.com/callbacks",
|
||||
"allowedSourceIps": ["10.0.0.0/8"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Enabling File Downloads
|
||||
|
||||
File downloads are enabled by default but can be controlled:
|
||||
|
||||
```json
|
||||
{
|
||||
"channels": {
|
||||
"mattermost": {
|
||||
"actions": {
|
||||
"downloadFile": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Code Migration
|
||||
|
||||
### Sending Messages (No Change Required)
|
||||
|
||||
```typescript
|
||||
// Both versions work the same
|
||||
import { sendMessage } from '@lumbridgecorp/openclaw-mattermost';
|
||||
|
||||
await sendMessage({
|
||||
cfg: openclawConfig,
|
||||
channelId: 'channel123',
|
||||
message: 'Hello World'
|
||||
});
|
||||
```
|
||||
|
||||
### Adding Reactions
|
||||
|
||||
**Before:** Limited or no support
|
||||
|
||||
**After:** Full support with type safety
|
||||
|
||||
```typescript
|
||||
import { addReaction } from '@lumbridgecorp/openclaw-mattermost';
|
||||
|
||||
await addReaction({
|
||||
cfg: openclawConfig,
|
||||
postId: 'post123',
|
||||
emoji: 'thumbsup'
|
||||
});
|
||||
```
|
||||
|
||||
### Editing Messages (New Feature)
|
||||
|
||||
```typescript
|
||||
import { editMessage } from '@lumbridgecorp/openclaw-mattermost';
|
||||
|
||||
const result = await editMessage({
|
||||
cfg: openclawConfig,
|
||||
postId: 'post123',
|
||||
channelId: 'channel123',
|
||||
message: 'Updated content'
|
||||
});
|
||||
|
||||
if (!result.ok) {
|
||||
console.error('Edit failed:', result.error);
|
||||
}
|
||||
```
|
||||
|
||||
### Interactive Messages (New Feature)
|
||||
|
||||
```typescript
|
||||
const message = `
|
||||
Please confirm:
|
||||
[[mattermost_buttons: Yes:confirm:primary, No:cancel:danger]]
|
||||
`;
|
||||
|
||||
await sendMessage({ cfg: openclawConfig, channelId: 'channel123', message });
|
||||
```
|
||||
|
||||
### File Downloads (New Feature)
|
||||
|
||||
```typescript
|
||||
import { downloadFile } from '@lumbridgecorp/openclaw-mattermost';
|
||||
|
||||
const result = await downloadFile({
|
||||
cfg: openclawConfig,
|
||||
fileId: 'file123',
|
||||
destinationPath: '/tmp/download.pdf',
|
||||
maxSize: 50 * 1024 * 1024
|
||||
});
|
||||
|
||||
if (result.ok) {
|
||||
console.log('Downloaded:', result.filePath);
|
||||
}
|
||||
```
|
||||
|
||||
### Error Handling Improvements
|
||||
|
||||
**Before:** Basic error handling
|
||||
|
||||
```typescript
|
||||
try {
|
||||
await sendMessage({ cfg, channelId, message });
|
||||
} catch (error) {
|
||||
console.error('Failed:', error);
|
||||
}
|
||||
```
|
||||
|
||||
**After:** Structured error handling with retry
|
||||
|
||||
```typescript
|
||||
import { MattermostError, isRetryableError } from '@lumbridgecorp/openclaw-mattermost';
|
||||
|
||||
try {
|
||||
await sendMessage({ cfg, channelId, message });
|
||||
} catch (error) {
|
||||
if (error instanceof MattermostError) {
|
||||
console.error(`[${error.code}] ${error.userMessage}`);
|
||||
|
||||
if (error.retryable) {
|
||||
console.log(`Can retry after ${error.retryAfterMs}ms`);
|
||||
}
|
||||
|
||||
if (error.code === 'AUTHENTICATION_FAILED') {
|
||||
// Refresh token and retry
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
After migration, verify everything works:
|
||||
|
||||
### 1. Run the Security Audit
|
||||
|
||||
```typescript
|
||||
import { collectMattermostSecurityAuditFindings } from '@lumbridgecorp/openclaw-mattermost';
|
||||
|
||||
const findings = await collectMattermostSecurityAuditFindings({
|
||||
cfg: openclawConfig,
|
||||
accountId: 'default',
|
||||
account: resolvedAccount
|
||||
});
|
||||
|
||||
const critical = findings.filter(f => f.severity === 'critical');
|
||||
if (critical.length > 0) {
|
||||
console.error('Critical security issues found:', critical);
|
||||
process.exit(1);
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Test Basic Operations
|
||||
|
||||
```typescript
|
||||
// Test connection
|
||||
const me = await fetchMattermostMe(client);
|
||||
console.log('Connected as:', me.username);
|
||||
|
||||
// Test message sending
|
||||
const post = await sendMessage({ cfg, channelId: testChannel, message: 'Test' });
|
||||
console.log('Sent message:', post.id);
|
||||
|
||||
// Test message editing
|
||||
const editResult = await editMessage({
|
||||
cfg,
|
||||
postId: post.id,
|
||||
channelId: testChannel,
|
||||
message: 'Updated test'
|
||||
});
|
||||
console.log('Edit result:', editResult.ok);
|
||||
|
||||
// Test message deletion
|
||||
const deleteResult = await deleteMessage({
|
||||
cfg,
|
||||
postId: post.id,
|
||||
channelId: testChannel
|
||||
});
|
||||
console.log('Delete result:', deleteResult.ok);
|
||||
```
|
||||
|
||||
### 3. Checklist
|
||||
|
||||
- [ ] Messages send successfully
|
||||
- [ ] Messages can be edited
|
||||
- [ ] Messages can be deleted
|
||||
- [ ] Reactions can be added
|
||||
- [ ] Files can be downloaded (if enabled)
|
||||
- [ ] Interactive components render (if configured)
|
||||
- [ ] No critical security audit findings
|
||||
- [ ] Error handling works as expected
|
||||
- [ ] Rate limiting is handled gracefully
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If you need to rollback to the stock extension:
|
||||
|
||||
### Step 1: Revert Package
|
||||
|
||||
```bash
|
||||
npm uninstall @lumbridgecorp/openclaw-mattermost
|
||||
npm install @modelcontextprotocol/mattermost
|
||||
```
|
||||
|
||||
### Step 2: Revert Configuration
|
||||
|
||||
Remove any enhanced-specific configuration:
|
||||
|
||||
```diff
|
||||
{
|
||||
"channels": {
|
||||
"mattermost": {
|
||||
"url": "https://chat.example.com",
|
||||
- "baseUrl": "https://chat.example.com",
|
||||
- "botToken": "${MATTERMOST_BOT_TOKEN}",
|
||||
- "pat": "${MATTERMOST_PAT}",
|
||||
- "dmPolicy": "pairing",
|
||||
+ "token": "${MATTERMOST_TOKEN}",
|
||||
- "interactions": { ... },
|
||||
- "actions": { ... }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Revert Code Changes
|
||||
|
||||
Change imports back:
|
||||
|
||||
```diff
|
||||
- import { sendMessage } from '@lumbridgecorp/openclaw-mattermost';
|
||||
+ import { sendMessage } from '@modelcontextprotocol/mattermost';
|
||||
```
|
||||
|
||||
Remove any code using enhanced-only features:
|
||||
- Message editing
|
||||
- Message deletion
|
||||
- File downloads
|
||||
- Interactive components
|
||||
- Security audit calls
|
||||
|
||||
## Troubleshooting Migration Issues
|
||||
|
||||
### Issue: "Cannot find module"
|
||||
|
||||
**Solution:** Ensure the package is installed:
|
||||
|
||||
```bash
|
||||
npm install @lumbridgecorp/openclaw-mattermost
|
||||
```
|
||||
|
||||
### Issue: "Configuration validation failed"
|
||||
|
||||
**Solution:** Check for legacy configuration properties:
|
||||
|
||||
```typescript
|
||||
import { MattermostConfigSchema } from '@lumbridgecorp/openclaw-mattermost';
|
||||
|
||||
const result = MattermostConfigSchema.safeParse(yourConfig);
|
||||
if (!result.success) {
|
||||
console.error('Config errors:', result.error.errors);
|
||||
}
|
||||
```
|
||||
|
||||
### Issue: "Authentication failed"
|
||||
|
||||
**Solution:** Verify token format and permissions:
|
||||
|
||||
```bash
|
||||
# Test token with curl
|
||||
curl -H "Authorization: Bearer YOUR_TOKEN" \
|
||||
https://chat.example.com/api/v4/users/me
|
||||
```
|
||||
|
||||
### Issue: "Interactive components not working"
|
||||
|
||||
**Solution:** Check interaction callback configuration:
|
||||
|
||||
1. Verify `interactions.callbackBaseUrl` is HTTPS
|
||||
2. Ensure `allowedSourceIps` includes your Mattermost server
|
||||
3. Check that the callback endpoint is accessible
|
||||
4. Verify Mattermost can reach your callback URL
|
||||
|
||||
### Issue: "File download blocked"
|
||||
|
||||
**Solution:** Check file restrictions:
|
||||
|
||||
1. Verify file is not an executable type
|
||||
2. Check file size against `maxSize` limit
|
||||
3. Ensure bot has file access permissions
|
||||
4. Check MIME type is in allowlist
|
||||
|
||||
## Getting Help
|
||||
|
||||
If you encounter issues during migration:
|
||||
|
||||
1. **Check the security audit output** for configuration issues
|
||||
2. **Review the [API Reference](API.md)** for correct usage
|
||||
3. **Search [GitHub Issues](https://github.com/lumbridgecorp/openclaw-extentions-mattermost/issues)** for similar problems
|
||||
4. **Create a new issue** with:
|
||||
- Your migration step
|
||||
- Error messages
|
||||
- Configuration (with secrets redacted)
|
||||
- Expected vs actual behavior
|
||||
|
||||
## Migration Summary
|
||||
|
||||
| Task | Effort | Notes |
|
||||
|------|--------|-------|
|
||||
| Package update | 5 min | Simple npm/pnpm/yarn command |
|
||||
| Basic config migration | 10 min | Property name changes |
|
||||
| PAT setup (optional) | 15 min | Create token, update config |
|
||||
| Interactive components | 30 min | Add interaction config |
|
||||
| Code migration | 1-2 hours | Update imports, add features |
|
||||
| Testing | 30 min | Verify all operations work |
|
||||
| Security audit | 15 min | Fix any findings |
|
||||
|
||||
**Total estimated time: 2-4 hours** for a complete migration with all features.
|
||||
Reference in New Issue
Block a user