@bernierllc/chat-integration-slack

Slack workspace integration for in-app chat with bidirectional messaging and slash commands. Provides comprehensive integration between Slack workspaces and in-app chat systems with NeverHub service discovery.

🚀 Quick Testing

Ready to test with your Slack workspace? See TESTING.md for step-by-step instructions.

# Set environment variables and run demo
export SLACK_BOT_TOKEN=xoxb-your-token
export SLACK_SIGNING_SECRET=your-secret
npm run demo

Installation

npm install @bernierllc/chat-integration-slack

Peer Dependencies

This package requires the following peer dependencies for full functionality:

npm install @slack/bolt @slack/web-api

📚 Documentation

• SLACK_SETUP.md - Complete Slack app setup guide
• TESTING.md - Testing instructions and demo guide
• .env.example - Environment variables reference

Usage

Basic Setup

import { SlackIntegration, createSlackConfig } from '@bernierllc/chat-integration-slack';

// Create configuration
const config = await createSlackConfig();

// Initialize Slack integration
const slack = new SlackIntegration(config);
await slack.initialize();

// Check status
const status = slack.getStatus();
console.log('Slack integration enabled:', status.enabled);
console.log('NeverHub connected:', status.neverhubConnected);

Configuration

Configure via environment variables or configuration file:

import { defaultSlackConfig } from '@bernierllc/chat-integration-slack';

const customConfig = {
  ...defaultSlackConfig,
  slack: {
    botToken: 'xoxb-your-bot-token',
    signingSecret: 'your-signing-secret',
    appToken: 'xapp-your-app-token' // For Socket Mode
  },
  messaging: {
    bidirectional: true,
    formatMessages: true,
    bridgeReactions: true,
    bridgeThreads: true,
    maxMessageLength: 4000
  }
};

const slack = new SlackIntegration(customConfig);

Environment Variables

# Required
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret

# Optional
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_CLIENT_ID=your-client-id
SLACK_CLIENT_SECRET=your-client-secret
SLACK_SOCKET_MODE=true
SLACK_CHANNELS=#general,#dev
SLACK_COMMANDS_ENABLED=true
NEVERHUB_ENABLED=true

API Reference

SlackIntegration

Main integration class for Slack workspace connectivity.

Constructor

new SlackIntegration(config: SlackIntegrationConfig)

Methods

// Initialize the integration
await slack.initialize(): Promise<void>

// Check if integration is enabled
slack.isEnabled(): boolean

// Get integration status
slack.getStatus(): { enabled: boolean; neverhubConnected: boolean }

// Get current configuration
slack.getConfig(): SlackIntegrationConfig

Configuration Types

interface SlackIntegrationConfig {
  enabled: boolean;
  slack: {
    botToken: string;
    signingSecret: string;
    appToken?: string;
    clientId?: string;
    clientSecret?: string;
  };
  connection: {
    socketMode: boolean;
    port?: number;
    endpoint?: string;
  };
  messaging: {
    bidirectional: boolean;
    formatMessages: boolean;
    bridgeReactions: boolean;
    bridgeThreads: boolean;
    maxMessageLength: number;
  };
  // ... additional configuration options
}

Integration Status

Logger Integration

• Status: Optional
• Implementation: Uses custom logger with environment-based conditional logging
• Pattern: Graceful degradation when logger not available
• Configuration: Controlled via NODE_ENV environment variable

NeverHub Integration

• Status: Planned
• Implementation: Dynamic import with graceful degradation
• Pattern: Service discovery for slash command routing and message bridging
• Graceful Degradation: Works without NeverHub, logs warning when unavailable
• Configuration: Controlled via NEVERHUB_ENABLED environment variable

Integration Documentation

• Logger Integration: Uses custom logger that respects test environment
• NeverHub Integration: Dynamic loading with error handling and fallback behavior
• Graceful Degradation: All integrations are optional and fail gracefully

Configuration

Slack Workspace Setup

1. Create a Slack App in your workspace
2. Add required OAuth scopes: chat:write, channels:read, users:read, commands
3. Install the app to your workspace
4. Copy the Bot User OAuth Token and Signing Secret

Socket Mode Setup (Recommended)

const config = {
  slack: {
    botToken: process.env.SLACK_BOT_TOKEN,
    signingSecret: process.env.SLACK_SIGNING_SECRET,
    appToken: process.env.SLACK_APP_TOKEN // Required for Socket Mode
  },
  connection: {
    socketMode: true // Enables real-time events
  }
};

HTTP Mode Setup

const config = {
  connection: {
    socketMode: false,
    port: 3000,
    endpoint: '/slack/events'
  }
};

Examples

Basic Integration

import { SlackIntegration, createSlackConfig } from '@bernierllc/chat-integration-slack';

async function setupSlackIntegration() {
  try {
    // Load configuration from environment
    const config = await createSlackConfig();
    
    // Create integration instance
    const slack = new SlackIntegration(config);
    
    // Initialize (sets up NeverHub if available)
    await slack.initialize();
    
    console.log('✅ Slack integration ready!');
    console.log('Status:', slack.getStatus());
    
  } catch (error) {
    console.error('❌ Failed to initialize Slack integration:', error);
  }
}

setupSlackIntegration();

Custom Configuration

import { SlackIntegration, SlackConfigSchema } from '@bernierllc/chat-integration-slack';

const customConfig = {
  enabled: true,
  slack: {
    botToken: 'xoxb-your-token',
    signingSecret: 'your-secret',
  },
  messaging: {
    bidirectional: true,
    formatMessages: true,
    bridgeReactions: false, // Disable reaction bridging
    bridgeThreads: true,
    maxMessageLength: 2000 // Shorter messages
  },
  slashCommands: {
    enabled: true,
    autoRegister: true,
    responseStyle: 'ephemeral',
    timeout: 30000
  },
  neverhub: {
    enabled: true,
    serviceName: 'my-slack-integration'
  }
};

// Validate configuration
const validatedConfig = SlackConfigSchema.parse(customConfig);
const slack = new SlackIntegration(validatedConfig);

Development

Building

npm run build

Testing

npm test
npm run test:coverage

Linting

npm run lint

License

Copyright (c) 2025 Bernier LLC. All rights reserved.