@akson/cortex-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

npm install @akson/cortex-slack

Quick Start

Basic Usage

import { SlackClient } from '@akson/cortex-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

# 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

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

const slack = createSlackClientFromEnv();

Usage Examples

Lead Notifications

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

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

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

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

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:

// In myarmy-intelligence
import { SlackClient } from '@akson/cortex-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

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

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

From MyArmy Intelligence

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

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

Testing

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

License

MIT