DigiSlack

An AI-powered SDK for Slack integration that simplifies interaction with Slack's API through natural language processing.

🚀 Features

• Natural Language Processing: Interact with Slack using plain English commands
• Smart Channel/User Detection: Automatically distinguishes between channels and users
• Error Handling: Helpful error messages with suggestions for fixing permission issues
• Customizable AI: Configure the AI system prompt to match your specific needs
• Rate Limiting: Built-in protection against Slack API rate limits
• Direct & Group Messages: Support for both direct messages and group conversations
• Status Updates: Update your Slack status with text, emoji, and expiration time
• TypeScript Support: Includes TypeScript type definitions for better development experience

📦 Installation

npm install digi-slack

⚙️ Setup

1. Environment Variables

Create a .env file in your project root:

# Required
SLACK_TOKEN=xoxb-your-slack-token
OPENROUTER_API_KEY=your-openrouter-api-key

# Optional
OPENROUTER_MODEL=openai/gpt-4-turbo

2. Slack App Configuration

Your Slack app needs the following OAuth scopes:

Required scopes:

• channels:read - To read channel information
• users:read - To read user information
• chat:write - To send messages

Optional but recommended scopes:

• im:write - To create direct message channels (required for DMs to new users)
• im:read - To read direct message channels
• mpim:write - To create group direct message channels (required for group DMs)
• users.profile:write - To update user status (required for status updates)
• files:write - To upload files
• channels:history - To read channel history
• groups:history - To read private channel history
• im:history - To read direct message history

To add these scopes:

1. Go to https://api.slack.com/apps
2. Select your Slack app
3. Navigate to "OAuth & Permissions"
4. Add the required scopes under "Bot Token Scopes"
5. Reinstall your app to update permissions

🔍 Basic Usage

import { DigiSlack } from 'digi-slack';

// Initialize the SDK with default settings (using environment variables)
const digiSlack = new DigiSlack();

// Process natural language requests
async function sendMessage() {
  try {
    const result = await digiSlack.processRequest(
      "Send a message to #general saying Hello team!"
    );
    console.log("Message sent:", result);
  } catch (error) {
    console.error("Error:", error.message);
  }
}

sendMessage();

🛠️ Customization Options

You can customize DigiSlack when initializing:

const digiSlack = new DigiSlack({
  // Override environment variables with direct values
  slackToken: 'your-slack-token',
  openrouterKey: 'your-openrouter-key',
  
  // Choose a different AI model
  openrouterModel: 'anthropic/claude-3-opus',
  
  // Customize the AI system prompt
  systemPrompt: 'Your custom system prompt for the AI'
});

Customizing the AI System Prompt

The system prompt controls how the AI interprets and responds to requests. You can:

// Get the default system prompt
const defaultPrompt = DigiSlack.getDefaultSystemPrompt();

// Extend it with your own instructions
const customPrompt = `${defaultPrompt}

Additional custom instructions:
- When sending messages to channels, always add "📢" at the beginning
- When sending direct messages to users, always add "📩" at the beginning
- Always confirm the action before executing it
`;

// Use your custom prompt
const digiSlack = new DigiSlack({
  systemPrompt: customPrompt
});

📝 Examples

Sending Messages

// To a channel
await digiSlack.processRequest("Send a message to #general saying Hello everyone!");

// To a specific user
await digiSlack.processRequest("Send a direct message to @john.doe saying Meeting at 3pm");

// To multiple users
await digiSlack.processRequest("Send a message to john.doe and jane.smith saying Project update");

Channel Operations

// List all channels
await digiSlack.processRequest("List all channels");

// Get channel info
await digiSlack.processRequest("Get information about the #random channel");

// Join a channel
await digiSlack.processRequest("Join the #project-updates channel");

User Operations

// List all users
await digiSlack.processRequest("List all users");

// Get user info
await digiSlack.processRequest("Get information about user @john.doe");

// Update status
await digiSlack.processRequest("Update my status to 'In a meeting' with a calendar emoji for 60 minutes");

Status Updates

// Update status with natural language
await digiSlack.processRequest("Set my status to 'Working remotely' with a house emoji");

// Update status with expiration
await digiSlack.processRequest("Update my status to 'On vacation' with a palm tree emoji until tomorrow");

// Clear status
await digiSlack.processRequest("Clear my status");

// Direct API access for status updates
await digiSlack.slackClient.updateStatus("In a meeting", "calendar", 60);

🔄 Direct API Access

For advanced usage, you can access the Slack client directly:

import { DigiSlack, SlackClient } from 'digi-slack';

// Using the client from DigiSlack instance
const digiSlack = new DigiSlack();
await digiSlack.slackClient.sendMessage("#general", "Hello from direct API!");

// Or create a standalone client
const slackClient = new SlackClient(process.env.SLACK_TOKEN);
await slackClient.sendDirectMessage("john.doe", "Hello!");

🧪 Testing

The package includes several test scripts:

# Run basic tests
npm test

# Test direct messaging functionality
npm run test-dm

# Interactive examples
npm run example        # Basic example
npm run interactive    # Advanced interactive CLI
npm run custom-example # Example with custom AI prompt

📚 Advanced Usage

Rate Limiting

Configure rate limiting to prevent hitting Slack API limits:

const digiSlack = new DigiSlack()
  .configureRateLimits({
    maxRequestsPerMinute: 30 // Default is 50
  });

Error Handling

DigiSlack provides helpful error messages, especially for permission issues:

try {
  await digiSlack.processRequest("Send a direct message to a new user");
} catch (error) {
  if (error.message.includes("Missing required Slack permission")) {
    console.log("Permission error - check your Slack app scopes");
  } else {
    console.error("Other error:", error.message);
  }
}

Channel vs User Disambiguation

DigiSlack intelligently determines whether a name refers to a channel or user:

• #random - Treated as a channel (has # prefix)
• @john - Treated as a user (has @ prefix)
• random channel - Treated as a channel (contains "channel")
• general - Common channel names are treated as channels
• send on random - Phrases like "on/in/to [name]" indicate channels

TypeScript Support

DigiSlack includes TypeScript type definitions for better development experience:

import { DigiSlack } from 'digi-slack';

// TypeScript will provide autocompletion and type checking
const digiSlack = new DigiSlack({
  slackToken: process.env.SLACK_BOT_TOKEN,
  openrouterKey: process.env.OPENROUTER_API_KEY
});

// Example with type checking
async function sendMessage(channel: string, message: string) {
  return await digiSlack.slackClient.sendMessage(channel, message);
}

For more details on TypeScript support, see TYPESCRIPT.md.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.