openclaw-mattermost-extension/docs/MIGRATION.md

# 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` | `@karti-ai/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 @karti-ai/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"
+   "@karti-ai/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 '@karti-ai/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 '@karti-ai/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 '@karti-ai/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 '@karti-ai/openclaw-mattermost';

await addReaction({
  cfg: openclawConfig,
  postId: 'post123',
  emoji: 'thumbsup'
});
```

### Editing Messages (New Feature)

```typescript
import { editMessage } from '@karti-ai/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 '@karti-ai/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 '@karti-ai/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 '@karti-ai/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 @karti-ai/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 '@karti-ai/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 @karti-ai/openclaw-mattermost
```

### Issue: "Configuration validation failed"

**Solution:** Check for legacy configuration properties:

```typescript
import { MattermostConfigSchema } from '@karti-ai/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/karti-ai/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.