@akson/cortex-slack/README.md

Unified Slack integration for Cortex ecosystem - webhooks, bot API, and notifications

# @akson/cortex-api-slack

Unified Slack integration for the MyArmy ecosystem. Provides centralized notification, alert, and reporting capabilities.

## Features

- 🔔 **Webhook Support** - Simple notifications via Incoming Webhooks
- 🤖 **Bot API** - Full-featured interactive messages and buttons
- 🚨 **Alert System** - Severity-based alerts with rich formatting
- 📊 **Reports** - Daily/weekly intelligence and market reports
- 🎯 **Lead Tracking** - Real-time lead notifications
- ⚠️ **Error Handling** - Centralized error notifications
- 📈 **Metrics** - Performance and threshold alerts

## Installation

```bash
npm install @akson/cortex-api-slack
```

## Quick Start

### Basic Usage

```typescript
import { SlackClient } from '@akson/cortex-api-slack';

const slack = new SlackClient({
  webhookUrl: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
  botToken: 'xoxb-your-bot-token',
  channels: {
    alerts: '#alerts',
    leads: '#leads',
    reports: '#reports'
  }
});

// Send a simple alert
await slack.sendAlert({
  severity: 'warning',
  message: 'High memory usage detected',
  details: {
    usage: '85%',
    threshold: '80%'
  }
});
```

### Environment Variables

```bash
# Webhook (for simple notifications)
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

# Bot Token (for full API access)
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_ID=your-app-id
SLACK_TEAM_ID=your-team-id
SLACK_TEAM_NAME=your-team-name

# Channel Configuration
SLACK_CHANNEL_ALERTS=#alerts
SLACK_CHANNEL_TASKS=#tasks
SLACK_CHANNEL_REPORTS=#reports
SLACK_CHANNEL_LEADS=#leads
SLACK_CHANNEL_ERRORS=#errors

# Enable/Disable
SLACK_ENABLED=true
```

### Create from Environment

```typescript
import { createSlackClientFromEnv } from '@akson/cortex-api-slack';

const slack = createSlackClientFromEnv();
```

## Usage Examples

### Lead Notifications

```typescript
await slack.sendLeadNotification({
  lead_id: 'LEAD-12345',
  phone: '+41791234567',
  products: ['Custom Badge', 'Unit Patch'],
  total_value: 249.90,
  source: 'WhatsApp',
  urgency: 'high',
  timestamp: new Date()
});
```

### Error Notifications

```typescript
await slack.sendErrorNotification({
  error: new Error('Database connection failed'),
  context: 'Lead Processing',
  severity: 'critical',
  stack: error.stack,
  metadata: {
    lead_id: 'LEAD-12345',
    retry_count: 3
  }
});
```

### Metric Alerts

```typescript
await slack.sendMetricAlert({
  metric: 'Conversion Rate',
  current_value: 1.2,
  threshold: 2.0,
  change_percentage: -40,
  trend: 'down',
  severity: 'warning',
  recommendation: 'Review landing page changes from last deployment'
});
```

### Task Management

```typescript
await slack.sendTaskReview({
  task: {
    id: 'TASK-001',
    title: 'Update SEO meta tags',
    description: 'Optimize meta descriptions for Swiss military keywords',
    type: 'seo',
    priority: 'high',
    confidence: 0.85,
    estimated_impact: 'High',
    created_at: new Date()
  },
  preview: {
    suggested_changes: [
      'Add "militär badge" to homepage title',
      'Update meta description with "funktionsabzeichen"'
    ]
  },
  action_required: 'Review and approve SEO changes'
});
```

### Daily Intelligence Report

```typescript
await slack.sendDailyIntelligenceReport({
  date: new Date(),
  sources_checked: 5,
  tasks_generated: 12,
  auto_executed: 8,
  manual_required: 4,
  swiss_market: {
    avg_position: 3.2,
    impressions: 15000,
    clicks: 450,
    ctr: 3.0
  },
  lead_funnel: {
    new_leads: 23,
    conversion_rate: 2.8,
    whatsapp_contacts: 15
  },
  alerts: [
    'Competitor bidding on brand keywords',
    'CTR drop on mobile devices'
  ],
  recommendations: [
    'Increase mobile page speed',
    'Add more Swiss German content'
  ]
});
```

## Integration with MyArmy Intelligence

This package is designed to work seamlessly with the MyArmy Intelligence system:

```typescript
// In myarmy-intelligence
import { SlackClient } from '@akson/cortex-api-slack';

const slack = new SlackClient({
  botToken: process.env.SLACK_BOT_TOKEN,
  channels: {
    alerts: '#intelligence-alerts',
    tasks: '#intelligence-tasks',
    reports: '#intelligence-reports'
  }
});

// Use for automated alerts
await slack.sendAlert({
  severity: 'critical',
  message: 'Brand bidding violation detected',
  details: {
    competitor: 'Competitor X',
    keyword: 'myarmy',
    position: 1
  }
});
```

## Migration Guide

### From Direct Webhook

```typescript
// Old way
await fetch(SLACK_WEBHOOK_URL, {
  method: 'POST',
  body: JSON.stringify({ text: 'Hello' })
});

// New way
import { SlackClient } from '@akson/cortex-api-slack';
const slack = new SlackClient({ webhookUrl: SLACK_WEBHOOK_URL });
await slack.sendWebhookMessage('Hello');
```

### From MyArmy Intelligence

```typescript
// Old way (custom implementation)
import { SlackNotifier } from './integrations/slack';

// New way
import { SlackClient } from '@akson/cortex-api-slack';
const slack = new SlackClient(config);
```

## Testing

```typescript
// Test connection
const isConnected = await slack.testConnection();
console.log('Slack connected:', isConnected);
```

## License

MIT