slack-live

Real-time updating Slack messages with progress tracking.


Features

- Real-time message updates - Create and update Slack messages programmatically
- Progress bars - 6 customizable ASCII progress bar styles
- State management - Track message states (pending, running, completed, failed, cancelled)
- Presets - Ready-to-use templates for status, progress, pipelines, and encoding jobs
- Block Kit support - Fluent builder for rich Slack layouts
- Rate limiting - Automatic retry with exponential backoff
- TypeScript - Full type safety with strict mode

Installation

``bash
npm install slack-live


or

pnpm add slack-live

or

yarn add slack-live
`

Quick Start

`typescript
import { SlackLive } from 'slack-live';

const slackLive = new SlackLive({
token: process.env.SLACK_BOT_TOKEN!,
defaultChannel: '#builds',
});

// Create a live message
const message = await slackLive.create('#builds', { text: 'Starting deployment...' });

// Update with progress
await message.setProgress(25);
await message.setText('Building Docker image...');

await message.setProgress(50);
await message.setText('Pushing to registry...');

await message.setProgress(75);
await message.setText('Deploying to production...');

// Complete the message
await message.complete('Deployment successful!');
`

API Reference

$3

`typescript
const client = new SlackLive({
token: string; // Slack Bot Token (required)
defaultChannel?: string; // Default channel for messages
defaultProgressStyle?: ProgressBarStyle; // Default progress bar style
retryOptions?: {
maxRetries?: number; // Max retry attempts (default: 3)
initialDelay?: number; // Initial delay in ms (default: 1000)
maxDelay?: number; // Max delay in ms (default: 30000)
backoffMultiplier?: number; // Backoff multiplier (default: 2)
};
});
`

#### Methods

- create(channel, options, callbacks?) - Create a new live message
- task(label, options?) - Create a task for workflow tracking
- sync(channel, state) - Sync multiple tasks declaratively
- getMessage(ts) - Get a message by timestamp
- getActiveMessages() - Get all non-finished messages
- getAllMessages() - Get all tracked messages

$3

`typescript
const message = await client.create('#builds', { text: 'Hello' });

// Update content
await message.setText('New text');
await message.setBlocks(blocks);
await message.update({ text: 'Updated', blocks: [...] });

// Progress tracking
await message.setProgress(50); // Shows: [████████░░░░░░░░] 50%

// State transitions
await message.complete('Done!'); // completed state
await message.fail('Error'); // failed state
await message.cancel('Stopped'); // cancelled state
`

$3

Higher-level abstraction for workflow steps:

`typescript
const task = client.task('Processing files', { channel: '#builds' });

await task.start();
await task.update({ progress: 25, status: 'Reading files...' });
await task.log('Processed file1.txt');
await task.log('Processed file2.txt');
await task.update({ progress: 75, status: 'Writing output...' });
await task.succeed('All files processed!');
`

$3

Declarative task synchronization:

`typescript
// Separate messages (one per task)
await client.sync('#builds', {
layout: 'separate',
tasks: [
{ id: 'build', label: 'Build', status: 'completed', progress: 100 },
{ id: 'test', label: 'Test', status: 'running', progress: 60 },
{ id: 'deploy', label: 'Deploy', status: 'pending' },
],
});

// Combined message (all tasks in one)
await client.sync('#builds', {
layout: 'combined',
tasks: [...],
});
`

$3

Ready-to-use message templates:

#### Status Preset

`typescript
await client.presets.status('#builds', {
title: 'Deployment',
status: 'running',
subtitle: 'Building Docker image...',
});
// Renders:
// 🔄 Deployment
// Building Docker image...
`

#### Progress Preset

`typescript
await client.presets.progress('#builds', {
title: 'Video Encoding',
progress: 45,
details: [
{ label: 'Format', value: 'H.264' },
{ label: 'ETA', value: '2m 30s' },
],
});
// Renders:
// 🔄 Video Encoding
// [███████░░░░░░░░░] 45%
//
// Format: H.264
// ETA: 2m 30s
`

#### Pipeline Preset

`typescript
await client.presets.pipeline('#builds', {
title: 'CI/CD Pipeline',
steps: [
{ name: 'Build', status: 'completed' },
{ name: 'Test', status: 'running', progress: 60 },
{ name: 'Deploy', status: 'pending' },
],
});
// Renders:
// CI/CD Pipeline
// ────────────────────
// ✅ Build
// 🔄 Test [██████░░░░] 60%
// ⏳ Deploy
`

#### Encoding Job Preset

`typescript
await client.presets.encodingJob('#builds', {
title: 'video.mp4',
jobId: '12345',
source: { duration: '1:30', resolution: '4K', size: '500MB' },
formats: [
{ name: '1080p', status: 'completed', size: '100MB', duration: '30s' },
{ name: '720p', status: 'running', progress: 65 },
{ name: '480p', status: 'pending' },
],
links: { manifest: 'https://example.com/manifest.json' },
});
`

$3

Each preset returns a specialized message class that preserves the config state and provides typed update methods:

`typescript
// Create an encoding job
const job = await client.presets.encodingJob('#builds', {
title: 'video.mp4',
formats: [
{ name: '1080p', status: 'pending' },
{ name: '720p', status: 'pending' },
],
});

// Update a specific format by name
await job.updateFormatByName('1080p', { status: 'running', progress: 25 });

// Update progress
await job.updateFormatByName('1080p', { progress: 75 });

// Complete the format
await job.updateFormatByName('1080p', {
status: 'completed',
size: '100MB',
duration: '30s',
});

// Complete job with links
await job.completeWithLinks({
manifest: 'https://cdn.example.com/manifest.m3u8',
});
`

Available preset message classes:

| Preset | Class | Key Methods |
| ------------- | -------------------- | --------------------------------------------------------------------------------- |
| status | StatusMessage | updatePreset(), complete(), fail() |
| progress | ProgressMessage | updatePreset(), setProgressValue(), complete() |
| pipeline | PipelineMessage | updatePreset(), updateStep(), updateStepByName() |
| encodingJob | EncodingJobMessage | updatePreset(), updateFormat(), updateFormatByName(), completeWithLinks() |

$3

Fluent builder for Slack Block Kit:

`typescript
import { BlockBuilder } from 'slack-live';

const blocks = new BlockBuilder()
.header('Deployment Status')
.divider()
.progressSection({ title: 'Building', progress: 75, status: 'running' })
.sectionWithFields([
{ label: 'Environment', value: 'Production' },
{ label: 'Version', value: 'v2.1.0' },
])
.context(['Last updated: just now'])
.build();

await message.setBlocks(blocks);
`

Progress Bar Styles

Six built-in styles:

| Style | Example |
| --------- | -------------------------- |
| blocks | [████████░░░░░░░░] 50% |
| equals | [========........] 50% |
| arrows | [>>>>>>>>--------] 50% |
| braille | ⣿⣿⣿⣿⣿⣿⣿⣿⣀⣀⣀⣀⣀⣀⣀⣀ 50% |
| minimal | 50% ━━━━━━━━━━────────── |
| emoji | 🟩🟩🟩🟩🟩⬜⬜⬜⬜⬜ 50% |

`typescript
await message.setProgress(50, { style: 'emoji', width: 10 });
`

Status Emojis

| State | Emoji |
| ----------- | ----- |
| pending | ⏳ |
| running | 🔄 |
| completed | ✅ |
| failed | ❌ |
| cancelled | ⚪ |

Lifecycle Callbacks

`typescript
await client.create(
'#builds',
{ text: 'Hello' },
{
onSent: (snapshot) => console.log('Message sent:', snapshot.ts),
onUpdated: (snapshot) => console.log('Message updated'),
onCompleted: (snapshot) => console.log('Message completed'),
onFailed: (snapshot, error) => console.log('Message failed:', error),
onCancelled: (snapshot) => console.log('Message cancelled'),
}
);
`

Slack App Setup

1. Create a new Slack App at api.slack.com/apps
2. Add the following Bot Token Scopes:
- chat:write - Send messages
- chat:write.public - Send to public channels without joining
3. Install the app to your workspace
4. Copy the Bot User OAuth Token (starts with xoxb-)

$3

`json
{
"display_information": {
"name": "Live Updates Bot",
"description": "Real-time progress updates"
},
"features": {
"bot_user": {
"display_name": "Live Updates",
"always_online": true
}
},
"oauth_config": {
"scopes": {
"bot": ["chat:write", "chat:write.public"]
}
}
}
``

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT - see LICENSE for details.

---

_{This library was built with the assistance of AI.}