@hardlydifficult/chat 1.1.69 → 1.1.71

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/chat
 
-A TypeScript library for building chat bots with unified APIs for Discord and Slack, featuring threading, batching, streaming, commands, and cleanup.
+A unified API for Discord and Slack messaging with rich document support, threading, reactions, bulk operations, streaming, and command management.
 
 ## Installation
 
@@ -11,376 +11,672 @@ npm install @hardlydifficult/chat
 ## Quick Start
 
 ```typescript
-import { createChatClient } from '@hardlydifficult/chat';
+import { createChatClient } from "@hardlydifficult/chat";
+
+// Connect to Discord or Slack
+const client = createChatClient({ type: "discord" });
+// or { type: "slack" }
+
+const channel = await client.connect("channel-id");
+await channel.postMessage("Hello world!").addReactions(["👍", "👎"]);
+```
 
-// Create a Discord or Slack client based on platform
-const client = createChatClient('discord', {
+### Command-Based Bot Example
+
+```typescript
+import { CommandRegistry, CommandDispatcher, DiscordChatClient } from "@hardlydifficult/chat";
+
+const client = new DiscordChatClient({
   token: process.env.DISCORD_TOKEN!,
-  // or: 'slack', { token: process.env.SLACK_TOKEN! }
+  clientId: process.env.DISCORD_CLIENT_ID!,
 });
 
-// Listen for messages and respond
-client.onMessage((event) => {
-  event.channel.send('Hello, world!');
+const registry = new CommandRegistry();
+
+registry.register("ping", {
+  description: "Responds with pong",
+  execute: async ({ thread, abortController }) => {
+    const result = await ping(abortController.signal);
+    await thread.post(result);
+    thread.complete();
+  },
 });
 
-// Start listening
-await client.start();
+const dispatcher = new CommandDispatcher({ registry, channel });
+
+client.onMessage((msg) => dispatcher.handleMessage(msg));
+client.start();
 ```
 
-### Alternative Quick Start (with Message Operations)
+## Core Concepts
+
+### Message Operations
+
+Messages returned from `postMessage()` support chainable reaction and management operations.
 
 ```typescript
-import { createChatClient } from "@hardlydifficult/chat";
+const msg = await channel
+  .postMessage("Vote: 1, 2, or 3")
+  .addReactions(["1️⃣", "2️⃣", "3️⃣"])
+  .onReaction((event) => console.log(`${event.user.username} voted ${event.emoji}`));
 
-// Connect to Discord or Slack
-const client = createChatClient({ type: "discord" });
-// or { type: "slack" }
+await msg.update("Final count in thread...");
+await msg.delete({ cascadeReplies: false });
+```
 
-const channel = await client.connect("channel-id");
-await channel.postMessage("Hello world!").addReactions(["👍", "👎"]);
+#### Reply Messages
+
+Replies can be awaited like promises and support reactions before resolution.
+
+```typescript
+const reply = await msg.reply("Counting votes...");
+await reply.update("12 votes for pizza");
+await reply.addReactions(["🎉"]);
+await reply.waitForReactions();
 ```
 
-## Core Abstractions
+### Streaming Replies
 
-### Chat Clients
+Stream text into threads with automatic batching, chunking, and platform limit handling.
 
-The library provides platform-specific chat clients through a unified interface.
+```typescript
+const stream = thread.stream(1000, abortSignal);
+stream.append("Processing...\n");
+stream.append("Result: 42\n");
+await stream.stop();
+```
+
+#### Editable Stream
+
+Updates a single message in-place instead of creating new messages.
 
 ```typescript
-import { DiscordChatClient, SlackChatClient, createChatClient } from '@hardlydifficult/chat';
+const editableStream = thread.editableStream(2000);
+editableStream.append("Step 1...\n");
+editableStream.append("Step 2...\n");
+await editableStream.stop(); // posts one message, edits it twice
+```
 
-// Factory function for any supported platform
-const client = createChatClient('discord', { token: '...' });
+### Threads
 
-// Or instantiate directly
-const discordClient = new DiscordChatClient({ token: '...' });
-const slackClient = new SlackChatClient({ token: '...' });
+Create and manage conversational threads anchored to messages.
+
+```typescript
+const thread = await channel.createThread("Topic", "Session-1");
+await thread.post("How can I help?");
+thread.onReply(async (msg) => {
+  await thread.post(`You said: ${msg.content}`);
+});
+await thread.delete();
 ```
 
-Each client supports:
-- Message event handling via `onMessage()`
-- Reaction event handling via `onReaction()`
-- Platform-specific startup logic via `start()`
-- Graceful shutdown via `stop()`
+You can also create a thread from an existing message:
 
-### Channel and Message
+```typescript
+const msg = await channel.postMessage("Starting a discussion");
+const thread = await msg.startThread("Discussion Thread", 1440); // auto-archive in minutes
+```
 
-The `Channel` class abstracts messaging operations across platforms.
+Reconnect to an existing thread by ID (e.g., after a restart):
 
 ```typescript
-// Send a message and get a ReplyMessage reference
-const message = await channel.send('Hello');
-await message.react('👍');
-await message.reply('Thanks for the feedback!');
-await message.delete(); // Only the bot's message
-await channel.cleanup('all'); // Delete all bot messages in the channel
-```
-
-Messages are represented by the `Message` interface:
-
-```typescript
-interface Message {
-  id: string;
-  author: Member;
-  content: string;
-  timestamp: Date;
-  reactions: Reaction[];
-  thread?: Thread;
-  channel: Channel;
-  
-  reply(content: string): Promise<ReplyMessage>;
-  update(content: string): Promise<void>;
-  delete(): Promise<void>;
-  react(emoji: string): Promise<void>;
-  clearReactions(): Promise<void>;
-}
+const thread = channel.openThread(savedThreadId);
+await thread.post("I'm back!");
+thread.onReply(async (msg) => { /* ... */ });
+```
+
+### Batching Messages
+
+Group related messages with post-commit operations.
+
+```typescript
+const batch = await channel.beginBatch({ key: "report" });
+await batch.post("Line 1");
+await batch.post("Line 2");
+await batch.finish();
+
+await batch.deleteAll();
+await batch.keepLatest(5);
+```
+
+#### With Batch Helper
+
+Auto-finish batch even on errors.
+
+```typescript
+await channel.withBatch(async (batch) => {
+  await batch.post("First");
+  await batch.post("Second");
+  throw new Error("boom"); // batch.finish() called in finally
+});
 ```
 
-### Thread
+### Typing Indicators
 
-Threads provide an isolated messaging context with its own lifecycle.
+Show typing indicators for long-running work.
 
 ```typescript
-// Create and use a thread
-const thread = await channel.createThread('Discussions');
-await thread.send('Let us discuss this here.');
-await thread.sendStream('Streaming responses...');
-await thread.cleanup('bot'); // Remove only bot messages
+channel.beginTyping();
+try {
+  await longRunningTask();
+} finally {
+  channel.endTyping();
+}
+
+await channel.withTyping(() => processMessages());
+```
+
+For one-shot use, `sendTyping()` sends a single indicator without automatic refresh:
+
+```typescript
+await channel.sendTyping();
 ```
 
-## Message Batching
+> **Slack note:** Slack does not support bot typing indicators. Both methods are no-ops on Slack.
 
-Batching allows grouping multiple messages and managing them collectively.
+### Message Cleanup
+
+Convenience methods for bulk message management.
 
 ```typescript
-import { MessageBatch } from '@hardlydifficult/chat';
+// Keep newest 10, delete rest
+await channel.pruneMessages({ keep: 10 });
+
+// Fetch bot's recent messages
+const botMessages = await channel.getRecentBotMessages(50);
+```
 
-// Create a batch
-const batch = channel.batch();
-batch.add(channel.send('First'));
-batch.add(channel.send('Second'));
+#### Bulk Operations (Enhanced)
 
-// Finish and keep only the latest
-await batch.finish({ mode: 'keepLatest' });
+```typescript
+// Delete up to 100 recent messages
+const deletedCount = await channel.bulkDelete(50);
 
-// Or delete everything
-await batch.delete();
+// List and filter recent messages
+const botMessages = await channel.getMessages({ limit: 50, author: "me" });
+const sameMessages = await channel.getRecentBotMessages(50);
+
+// Keep latest 8 bot messages, delete older ones (opinionated cleanup helper)
+await channel.pruneMessages({ author: "me", limit: 50, keep: 8 });
+
+// Get all threads (active and archived) and delete them
+const threads = await channel.getThreads();
+for (const thread of threads) {
+  await thread.delete();
+}
 ```
 
-The `MessageBatch` class supports:
-- `add(promise)`: Add a pending message to the batch
-- `finish(options)`: Finalize batch with modes: `'keepAll'`, `'keepLatest'`, `'deleteAll'`
-- `delete()`: Delete all batched messages
-- `query()`: Get list of posted messages
+> **Slack note:** Slack has no bulk delete API — messages are deleted one-by-one. Some may fail if the bot lacks permission to delete others' messages. `getThreads()` scans recent channel history for messages with replies.
 
-## Streaming Replies
+### Member Matching
 
-The library supports real-time streaming with automatic message updates.
+Resolve users by mention, username, display name, or email.
 
 ```typescript
-// Use StreamingReply for automatic chunking
-const stream = channel.stream({ mode: 'thread' });
-stream.append('Hello, ');
-await stream.flush(); // Force immediate delivery
-stream.append('world!');
-await stream.finish(); // Finalize with message deletion or edit
+await channel.resolveMention("@nick"); // "<@U123>"
+await channel.resolveMention("Nick Mancuso"); // "<@U123>"
+await channel.resolveMention("nick@example.com"); // "<@U123>"
+
+const member = await channel.findMember("nick");
 ```
 
-The `EditableStreamReply` class allows in-place editing:
+### Message Tracker
+
+Track messages by key for later editing.
 
 ```typescript
-const stream = new EditableStreamReply(thread, { maxMessageLength: 2000 });
-stream.append('Initial ');
-await stream.flush();
-stream.append('content.');
-await stream.finish();
+const tracker = createMessageTracker((content) => channel.postMessage(content));
+tracker.post("status-worker-1", "🔴 Worker disconnected");
+// Later:
+tracker.edit("status-worker-1", "🟢 Worker reconnected");
 ```
 
-Both support:
-- `append(text)`: Add text to buffer
-- `flush()`: Send current buffer as message update
-- `finish()`: Finalize and cleanup
-- `abort()`: Cancel the stream mid-operation
+### Message Tracking
 
-## Commands
+Track and update messages by key.
 
-A regex-based command system with auto-parsing and context-aware routing.
+```typescript
+import { MessageTracker } from '@hardlydifficult/chat';
+
+const tracker = new MessageTracker();
+
+await tracker.post('greeting', channel.send('Hello!'));
+
+// Later, update it
+await tracker.update('greeting', async (msg) => msg.edit('Hello again!'));
+```
+
+## Command System
+
+The built-in command framework supports auto-parsed arguments, typing indicators, and message cleanup.
 
 ```typescript
-import { CommandDispatcher, CommandRegistry, Command } from '@hardlydifficult/chat';
+import { CommandRegistry, CommandDispatcher, setupJobLifecycle } from "@hardlydifficult/chat";
 
 const registry = new CommandRegistry();
 
-// Register a command with auto-parsed arguments
-registry.register({
-  name: 'ping',
-  pattern: /^ping(\s+help)?$/i,
-  handler: async ({ context, match }) => {
-    if (match[1]) {
-      return 'Usage: `ping` or `ping help`';
-    }
-    return 'Pong!';
-  }
+registry.register("tools", {
+  prefix: "merge",
+  description: "Merge pull requests",
+  args: { type: "rest", argName: "query" },
+  execute: async (ctx, args) => {
+    const { thread, abortController } = setupJobLifecycle({
+      originalMessage: ctx.incomingMessage,
+      thread: await ctx.startThread("Merge"),
+      abortController: new AbortController(),
+      ownerUsername: ctx.incomingMessage.author?.username!,
+    });
+
+    // Use abortController.signal to support cancellation
+    const result = await mergePRs(args.query, abortController.signal);
+    await thread.post(result);
+    thread.complete();
+  },
 });
 
-// Use dispatcher to route messages
-const dispatcher = new CommandDispatcher(registry);
-dispatcher.onMessage((event) => {
-  event.channel.typingIndicator.start();
-  return dispatcher.handle(event);
+const dispatcher = new CommandDispatcher({
+  channel,
+  registry,
+  state: { inFlightCommands: new Set() },
 });
+channel.onMessage((msg) => dispatcher.handleMessage(msg));
 ```
 
-### Command Types
+## Platform Config
 
-Commands are defined using:
+```typescript
+// Discord
+createChatClient({
+  type: "discord",
+  token: process.env.DISCORD_TOKEN,
+  guildId: process.env.DISCORD_GUILD_ID,
+});
+
+// Slack
+createChatClient({
+  type: "slack",
+  token: process.env.SLACK_BOT_TOKEN,
+  appToken: process.env.SLACK_APP_TOKEN,
+  socketMode: true,
+});
+```
+
+### Discord
 
 ```typescript
-interface Command {
-  name: string;
-  pattern: RegExp;
-  handler: (args: {
-    context: Context;
-    match: RegExpExecArray;
-    event: MessageEvent;
-  }) => Promise<string | void>;
-}
+import { DiscordChatClient } from '@hardlydifficult/chat/discord';
+
+const client = new DiscordChatClient({
+  token: 'your-bot-token',
+  clientId: 'your-client-id',
+});
+
+await client.start();
 ```
 
-Contexts include channel, user, and optional state:
+### Slack
 
 ```typescript
-interface Context {
-  channel: Channel;
-  user: Member;
-  state?: Map<string, any>;
-}
+import { SlackChatClient } from '@hardlydifficult/chat/slack';
+
+const client = new SlackChatClient({
+  token: process.env.SLACK_BOT_TOKEN!,
+  signingSecret: process.env.SLACK_SIGNING_SECRET!,
+});
+
+await client.start();
 ```
 
-### Job Lifecycle
+## Document Output
 
-Long-running commands support cancel/dismiss UI flows:
+Convert structured documents to platform-native rich text.
 
 ```typescript
-import { startJobLifecycle } from '@hardlydifficult/chat';
+import { Document, header, text, list, divider, context } from "@hardlydifficult/document-generator";
 
-await startJobLifecycle(thread, {
-  onCancel: async () => {
-    // Handle user-initiated cancellation
-  },
-  onDismiss: async () => {
-    // Add dismiss emoji for user to remove later
-  }
-});
+const doc = new Document()
+  .add(header("Status Report"))
+  .add(divider())
+  .add(text("All systems operational."))
+  .add(list(["API: ✅", "DB: ✅", "Cache: ✅"]))
+  .add(context("Generated at " + new Date().toISOString()));
+
+await channel.postMessage(doc);
 ```
 
-## Member Matching
+### Output Formatting
 
-Resolve users by mention, ID, or fuzzy match:
+Platform-specific message formatting utilities transform abstract document blocks.
+
+#### Discord Output
 
 ```typescript
-import { matchMember } from '@hardlydifficult/chat';
+import { formatDiscord } from '@hardlydifficult/chat/outputters';
 
-// Match a member by mention or name
-const member = await matchMember(
-  channel,
-  '@john', // or 'john', or '123456789'
-  { fuzzyThreshold: 0.7 }
-);
+const blocks = [
+  { type: 'header', text: 'Welcome' },
+  { type: 'code', language: 'ts', content: 'console.log("hi");' },
+];
 
-// Use aliases for more lenient matching
-const aliases = { 'johnny': 'john' };
-const member = await matchMember(channel, 'johnny', { aliases });
+const payload = formatDiscord(blocks); // Discord embed structure
 ```
 
-## Output Formatting
+#### Slack Output
 
-Convert abstract document blocks into platform-specific formats.
+```typescript
+import { formatSlack } from '@hardlydifficult/chat/outputters';
+
+const payload = formatSlack(blocks); // Slack Block Kit structure
+```
+
+## Typing
+
+All core types are exported for direct use.
 
 ```typescript
-import { formatDiscord, formatSlack } from '@hardlydifficult/chat';
+import type { Member, Message, Thread, MessageBatch } from "@hardlydifficult/chat";
+```
+
+## Types
+
+### Core Types
+
+| Type | Description |
+|--|--|
+| `Agent` | Bot identity (name, avatar, platform ID) |
+| `Command` | Command definition with handler and args |
+| `Context` | Execution context (message, args, reply) |
+| `State` | Persistent state for commands |
+| `ArgShape` | Argument parsing mode: `Text`, `Boolean`, `User`, `Channel`, `Role`, `Number` |
+| `Member` | Platform-agnostic user in a channel |
+| `MessageData` | Abstract message content (content, embeds, files, author, timestamp) |
+| `MessageEvent` | Incoming message event from platform |
+| `Document` | Abstract message block structure for formatting |
+
+### Platform-Specific Exports
+
+| Platform | Export |
+|--|--|
+| Discord | `DiscordChatClient`, `buildMessagePayload`, `fetchChannelMembers`, `getMessages`, `threadOperations` |
+| Slack | `SlackChatClient`, `buildMessageEvent`, `fetchChannelMembers`, `getMessages`, `getThreads`, `messageOperations`, `removeAllReactions` |
+| Core | `ChatClient`, `Channel`, `Thread`, `Message`, `ReplyMessage`, `StreamingReply`, `EditableStreamReply`, `CommandRegistry`, `CommandDispatcher`, `MessageTracker` |
+
+### Streaming Behavior
+
+| Feature | Discord | Slack |
+|---------|:-------:|:-----:|
+| Message editing | ✅ | ✅ |
+| Stream chunking | Automatic, 1000 chars | Automatic, 2000 chars |
+| Truncation | Oldest first | Oldest first |
+| Abort support | ✅ | ✅ |
+
+### Command Matching
+
+- Commands matched by longest-prefix-first
+- Alias conflicts are detected on registration
+- Owner-filtered commands can be restricted to specific user IDs
+
+## Features
+
+### Bot Identity
 
-const document = {
-  type: 'doc',
-  content: [
-    { type: 'text', text: 'Hello ' },
-    { type: 'bold', content: 'world' }
-  ]
-};
+After `connect()`, `client.me` exposes the authenticated bot user:
 
-const discordPayload = formatDiscord(document);
-const slackBlocks = formatSlack(document);
+```typescript
+const client = createChatClient({ type: "slack" });
+await client.connect(channelId);
+
+console.log(client.me?.id); // "U09B00R2R96"
+console.log(client.me?.username); // "sprint-bot"
+console.log(client.me?.mention); // "<@U09B00R2R96>"
 ```
 
-Supported block types include:
-- `text`, `bold`, `italic`, `code`, `pre`
-- `header`, `divider`, `section`, `button`
-- `mention` (platform-specific user/channel reference)
+### Incoming Messages
+
+Subscribe to new messages in a channel. The callback receives a full `Message` object — you can delete it, react to it, or reply in its thread.
+
+```typescript
+const unsubscribe = channel.onMessage((msg) => {
+  console.log(`${msg.author.username}: ${msg.content}`);
+
+  // Delete the user's command message
+  msg.delete();
+
+  // React to it
+  msg.addReactions(["white_check_mark"]);
+
+  // Reply in the message's thread
+  msg.reply("Got it!");
+});
+
+// Later: stop listening
+unsubscribe();
+```
+
+Messages from the bot itself are automatically filtered out.
+
+### Oversized Message Handling
 
-## Message Tracking
+Messages that exceed platform limits (Discord: 2000 chars, Slack: 4000 chars) are handled automatically:
 
-Track and update messages by key for efficient dynamic updates.
+- **`postMessage`**: Sends the full content as a `message.txt` file attachment instead of failing
+- **`update`**: Truncates with `…` (edits cannot attach files on either platform)
+
+No caller changes needed — the library handles this transparently.
+
+### File Attachments
+
+Send files as message attachments.
 
 ```typescript
-import { MessageTracker } from '@hardlydifficult/chat';
+channel.postMessage("Here's the scan report", {
+  files: [
+    { content: Buffer.from(markdownContent), name: "report.md" },
+    { content: "plain text content", name: "notes.txt" },
+  ],
+});
+```
+
+### File Uploads
 
-const tracker = new MessageTracker(channel);
-tracker.track('status', async () => channel.send('Updating...'));
-tracker.edit('status', async (message) => {
-  await message.update('Updated!');
+```typescript
+// Slack file upload
+await channel.send({
+  content: 'Here’s the file',
+  files: [{ filename: 'data.csv', content: '1,2,3' }],
+});
+
+// Discord file upload
+await channel.send({
+  content: 'File attached',
+  files: [{ filename: 'data.csv', content: Buffer.from('1,2,3') }],
 });
 ```
 
-## File Operations
+### Dismissable Messages
+
+Post a message that the specified user can dismiss by clicking the trash reaction.
+
+```typescript
+await channel.postDismissable("Build complete!", user.id);
+```
+
+### Declarative Reactions
 
-Post and update messages with file attachments.
+`setReactions` manages the full reaction state on a message. It diffs against the previous `setReactions` call, removing stale emojis and adding new ones, and replaces any existing reaction handler.
 
 ```typescript
-// Discord: attach files via buildMessagePayload
-import { buildMessagePayload } from '@hardlydifficult/chat/discord';
+const msg = await channel.postMessage("PR #42: open");
+
+// Set initial reactions
+msg.setReactions(["🟡"], (event) => handlePending(event));
+
+// Later: update to merged state — removes 🟡, adds 🟢, swaps handler
+msg.setReactions(["🟢"], (event) => handleMerged(event));
+```
+
+### Message Batches
+
+Group related posted messages so they can be retrieved and cleaned up together.
 
-const payload = buildMessagePayload({
-  content: 'Report',
-  files: [{ filename: 'report.pdf', data: buffer }]
+```typescript
+const batch = await channel.beginBatch({ key: "sprint-update" });
+
+for (const member of members) {
+  const msg = await batch.post(summary(member));
+  await msg.reply(detail(member));
+}
+
+await batch.post(callouts);
+await batch.finish();
+
+const recent = await channel.getBatches({
+  key: "sprint-update",
+  author: "me",
+  limit: 5,
 });
 
-await channel.send(payload);
+await recent[0].deleteAll({ cascadeReplies: true });
+```
 
-// Slack: use built-in file support
-await slackClient.postMessage({
-  channel: 'C123',
-  text: 'Report',
-  file: buffer,
-  filename: 'report.pdf'
+For safer lifecycle handling, use `withBatch` (auto-finishes in `finally`):
+
+```typescript
+await channel.withBatch({ key: "sprint-update" }, async (batch) => {
+  await batch.post("Part 1");
+  await batch.post("Part 2");
 });
 ```
 
-## Setup
+### Streaming Replies (Enhanced)
 
-### Discord
+Both `streamReply()`, `thread.stream()`, and `thread.editableStream()` accept an optional `AbortSignal` to automatically stop the stream on cancellation. After abort, `append()` becomes a no-op and `stop()` is called automatically.
 
-1. Create a bot at [Discord Developer Portal](https://discord.com/developers/applications)
-2. Enable **MESSAGE CONTENT INTENT** in bot settings
-3. Invite with `bot` and `applications.commands` scopes
-4. Set `DISCORD_TOKEN` environment variable
+```typescript
+const controller = new AbortController();
+const stream = thread.stream(2000, controller.signal);
 
-### Slack
+stream.append("working...\n");
+controller.abort(); // auto-stops, future appends are ignored
+console.log(stream.content); // "working...\n" — only pre-abort text
+```
 
-1. Create a Slack app at [Slack API](https://api.slack.com/apps)
-2. Add **Incoming Webhooks** and **Bot User Token** scopes
-3. Install to workspace and copy token
-4. Set `SLACK_TOKEN` environment variable
+### Connection Resilience
 
-## Platform Differences
+Both platforms auto-reconnect via their underlying libraries (discord.js and @slack/bolt). Register callbacks for observability.
 
-| Feature                     | Discord                            | Slack                              |
-|----------------------------|------------------------------------|------------------------------------|
-| Message Length Limit       | 2000 characters                    | 4000 characters                    |
-| Thread Support             | Text channel threads               | Conversations with replies         |
-| File Uploads               | Via `buildMessagePayload`          | Via `chat.postMessage`             |
-| Typing Indicators          | Supported via `typingIndicator`    | Supported via `chat.scheduledMsg`  |
-| Message History            | Requires **MESSAGE CONTENT INTENT**| Requires `history` scope           |
-| Mention Resolution         | By ID or username#discriminator    | By `@username` or user ID          |
-| Emoji Reactions            | Unicode or custom emoji (with ID)  | Custom emoji only by name          |
+```typescript
+const client = createChatClient({ type: "discord" });
 
-## Appendix
+client.onDisconnect((reason) => {
+  console.log("Disconnected:", reason);
+});
+
+client.onError((error) => {
+  console.error("Connection error:", error);
+});
+
+await client.disconnect(); // clean shutdown
+```
+
+Both callbacks return an unsubscribe function.
+
+### Reaction Management
+
+```typescript
+// Add and remove reactions
+await message.react('👍');
+await message.removeReaction('👍', userId);
+
+// Remove all bot reactions (Slack-specific)
+await slackChatClient.removeAllReactions(channelId, ts, botUserId);
+```
+
+### Member Matching
+
+Match users by ID, mention, or fuzzy alias.
+
+```typescript
+import { findMember } from '@hardlydifficult/chat/memberMatching';
+
+const member = findMember(guildMembers, '@alice'); // mentions
+const member = findMember(guildMembers, 'alice'); // fuzzy match
+```
+
+### Job Lifecycle (Threaded Commands)
+
+Long-running commands support cancel/dismiss flow.
+
+```typescript
+import { withCancelListener } from '@hardlydifficult/chat/commands/jobLifecycle';
+
+await withCancelListener(
+  thread,
+  async () => {
+    // Long-running job
+  },
+  { userId: message.author.id },
+);
+```
 
 ### Error Handling
 
-Platform-specific error codes are mapped to user-friendly messages:
+Map worker error codes to user-friendly messages.
 
 ```typescript
-import { isRecoverableError, getErrorFriendlyMessage } from '@hardlydifficult/chat';
+import { formatErrorMessage, isRecoverableError } from '@hardlydifficult/chat/commands';
 
-try {
-  await channel.send('Failed message');
-} catch (error) {
-  if (isRecoverableError(error)) {
-    // Retry with backoff
-  } else {
-    console.log(getErrorFriendlyMessage(error));
-  }
+if (isRecoverableError(error)) {
+  // Retry logic
 }
+
+const message = formatErrorMessage(error.code);
+```
+
+### Constants
+
+Platform message length limits.
+
+```typescript
+import { DISCORD_MAX_MESSAGE_LENGTH, SLACK_MAX_MESSAGE_LENGTH } from '@hardlydifficult/chat';
+
+console.log(DISCORD_MAX_MESSAGE_LENGTH); // 2000
+console.log(SLACK_MAX_MESSAGE_LENGTH);   // 4000
 ```
 
-Recoverable errors include:
-- Rate limits (`429 Too Many Requests`)
-- Network timeouts
-- Temporary unavailability
+## Platform Setup
 
-### Cleanup Modes
+### Discord
 
-The `cleanup` method supports:
+1. Create bot at [Discord Developer Portal](https://discord.com/developers/applications)
+2. Enable Gateway Intents: `GUILDS`, `GUILD_MEMBERS`, `GUILD_MESSAGES`, `GUILD_MESSAGE_REACTIONS`, `MESSAGE_CONTENT`
+3. Bot permissions: `Send Messages`, `Add Reactions`, `Read Message History`, `Manage Messages` (for bulk delete), `Create Public Threads`, `Send Messages in Threads`
+4. Set `DISCORD_TOKEN` and `DISCORD_GUILD_ID` env vars
 
-| Mode      | Behavior                                     |
-|-----------|----------------------------------------------|
-| `all`     | Delete all messages (bot + users)            |
-| `bot`     | Delete only bot-authored messages            |
-| `user`    | Delete only user-authored messages           |
-| `since`   | Delete messages newer than timestamp         |
+### Slack
 
-Example:
-```typescript
-await channel.cleanup({ mode: 'since', timestamp: new Date(Date.now() - 86400000) });
-```
+1. Create app at [Slack API](https://api.slack.com/apps)
+2. Enable Socket Mode, generate App Token
+3. Bot scopes: `chat:write`, `chat:write.public`, `reactions:write`, `reactions:read`, `channels:history`, `channels:read`, `files:write`, `users:read`
+4. Subscribe to events: `reaction_added`, `message.channels`
+5. Set `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN` env vars
+
+## Appendix
+
+### Platform Differences
+
+| Feature                | Discord                           | Slack                             |
+|------------------------|-----------------------------------|-----------------------------------|
+| Typing indicators      | ✅ Supported                      | ❌ No API support (no-op)         |
+| Message length limit   | 2000 characters                   | 4000 characters                   |
+| Thread creation        | Explicit thread channel           | Implicit via parent message ts    |
+| Bulk delete            | ✅ Up to 100 messages at once     | ❌ Must delete one-by-one         |
+| Emoji format           | Plain Unicode or `:name:`         | Colon-wrapped `:name:`            |
+| File uploads           | As attachments                    | Via `filesUploadV2` API           |
+
+### Message Limits
+
+| Platform | Max Message Length | Notes |
+|----------|--------------------|-------|
+| Discord  | 2000               | Embed-only messages may be larger |
+| Slack    | 4000               | Per block element; message may contain many |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/chat",
-  "version": "1.1.69",
+  "version": "1.1.71",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [