@hardlydifficult/chat 1.1.67 → 1.1.68

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/chat
 
-A unified API for Discord and Slack messaging with rich document support, threading, reactions, and bulk operations.
+A TypeScript library for building chat bots with unified APIs for Discord and Slack, featuring threading, batching, streaming, commands, and cleanup.
 
 ## Installation
 
@@ -10,6 +10,26 @@ npm install @hardlydifficult/chat
 
 ## Quick Start
 
+```typescript
+import { createChatClient } from '@hardlydifficult/chat';
+
+// Create a Discord or Slack client based on platform
+const client = createChatClient('discord', {
+  token: process.env.DISCORD_TOKEN!,
+  // or: 'slack', { token: process.env.SLACK_TOKEN! }
+});
+
+// Listen for messages and respond
+client.onMessage((event) => {
+  event.channel.send('Hello, world!');
+});
+
+// Start listening
+await client.start();
+```
+
+### Alternative Quick Start (with Message Operations)
+
 ```typescript
 import { createChatClient } from "@hardlydifficult/chat";
 
@@ -21,448 +41,346 @@ const channel = await client.connect("channel-id");
 await channel.postMessage("Hello world!").addReactions(["👍", "👎"]);
 ```
 
-## Core Concepts
+## Core Abstractions
 
-### Message Operations
+### Chat Clients
 
-Messages returned from `postMessage()` support chainable reaction and management operations.
+The library provides platform-specific chat clients through a unified interface.
 
 ```typescript
-const msg = await channel
-  .postMessage("Vote: 1, 2, or 3")
-  .addReactions(["1️⃣", "2️⃣", "3️⃣"])
-  .onReaction((event) => console.log(`${event.user.username} voted ${event.emoji}`));
-
-await msg.update("Final count in thread...");
-await msg.delete({ cascadeReplies: false });
-```
+import { DiscordChatClient, SlackChatClient, createChatClient } from '@hardlydifficult/chat';
 
-#### Reply Messages
+// Factory function for any supported platform
+const client = createChatClient('discord', { token: '...' });
 
-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();
+// Or instantiate directly
+const discordClient = new DiscordChatClient({ token: '...' });
+const slackClient = new SlackChatClient({ token: '...' });
 ```
 
-### Streaming Replies
-
-Stream text into threads with automatic batching, chunking, and platform limit handling.
+Each client supports:
+- Message event handling via `onMessage()`
+- Reaction event handling via `onReaction()`
+- Platform-specific startup logic via `start()`
+- Graceful shutdown via `stop()`
 
-```typescript
-const stream = thread.stream(1000, abortSignal);
-stream.append("Processing...\n");
-stream.append("Result: 42\n");
-await stream.stop();
-```
+### Channel and Message
 
-#### Editable Stream
-
-Updates a single message in-place instead of creating new messages.
+The `Channel` class abstracts messaging operations across platforms.
 
 ```typescript
-const editableStream = thread.editableStream(2000);
-editableStream.append("Step 1...\n");
-editableStream.append("Step 2...\n");
-await editableStream.stop(); // posts one message, edits it twice
+// 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
 ```
 
-### Threads
-
-Create and manage conversational threads anchored to messages.
+Messages are represented by the `Message` interface:
 
 ```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();
+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>;
+}
 ```
 
-### Batching Messages
+### Thread
 
-Group related messages with post-commit operations.
+Threads provide an isolated messaging context with its own lifecycle.
 
 ```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);
+// 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
 ```
 
-#### With Batch Helper
+## Message Batching
 
-Auto-finish batch even on errors.
+Batching allows grouping multiple messages and managing them collectively.
 
 ```typescript
-await channel.withBatch(async (batch) => {
-  await batch.post("First");
-  await batch.post("Second");
-  throw new Error("boom"); // batch.finish() called in finally
-});
-```
+import { MessageBatch } from '@hardlydifficult/chat';
 
-### Typing Indicators
+// Create a batch
+const batch = channel.batch();
+batch.add(channel.send('First'));
+batch.add(channel.send('Second'));
 
-Show typing indicators for long-running work.
+// Finish and keep only the latest
+await batch.finish({ mode: 'keepLatest' });
 
-```typescript
-channel.beginTyping();
-try {
-  await longRunningTask();
-} finally {
-  channel.endTyping();
-}
-
-await channel.withTyping(() => processMessages());
+// Or delete everything
+await batch.delete();
 ```
 
-### Message Cleanup
-
-Convenience methods for bulk message management.
+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
 
-```typescript
-// Keep newest 10, delete rest
-await channel.pruneMessages({ keep: 10 });
-
-// Fetch bot's recent messages
-const botMessages = await channel.getRecentBotMessages(50);
-```
-
-### Member Matching
+## Streaming Replies
 
-Resolve users by mention, username, display name, or email.
+The library supports real-time streaming with automatic message updates.
 
 ```typescript
-await channel.resolveMention("@nick"); // "<@U123>"
-await channel.resolveMention("Nick Mancuso"); // "<@U123>"
-await channel.resolveMention("nick@example.com"); // "<@U123>"
-
-const member = await channel.findMember("nick");
+// 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
 ```
 
-### Message Tracker
-
-Track messages by key for later editing.
+The `EditableStreamReply` class allows in-place editing:
 
 ```typescript
-const tracker = createMessageTracker((content) => channel.postMessage(content));
-tracker.post("status-worker-1", "🔴 Worker disconnected");
-// Later:
-tracker.edit("status-worker-1", "🟢 Worker reconnected");
+const stream = new EditableStreamReply(thread, { maxMessageLength: 2000 });
+stream.append('Initial ');
+await stream.flush();
+stream.append('content.');
+await stream.finish();
 ```
 
-## Command System
+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
+
+## Commands
 
-The built-in command framework supports auto-parsed arguments, typing indicators, and message cleanup.
+A regex-based command system with auto-parsing and context-aware routing.
 
 ```typescript
-import { CommandRegistry, CommandDispatcher, setupJobLifecycle } from "@hardlydifficult/chat";
+import { CommandDispatcher, CommandRegistry, Command } from '@hardlydifficult/chat';
 
 const registry = new CommandRegistry();
 
-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();
-  },
-});
-
-const dispatcher = new CommandDispatcher({
-  channel,
-  registry,
-  state: { inFlightCommands: new Set() },
-});
-channel.onMessage((msg) => dispatcher.handleMessage(msg));
-```
-
-## Platform Config
-
-```typescript
-// Discord
-createChatClient({
-  type: "discord",
-  token: process.env.DISCORD_TOKEN,
-  guildId: process.env.DISCORD_GUILD_ID,
+// 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!';
+  }
 });
 
-// Slack
-createChatClient({
-  type: "slack",
-  token: process.env.SLACK_BOT_TOKEN,
-  appToken: process.env.SLACK_APP_TOKEN,
-  socketMode: true,
+// Use dispatcher to route messages
+const dispatcher = new CommandDispatcher(registry);
+dispatcher.onMessage((event) => {
+  event.channel.typingIndicator.start();
+  return dispatcher.handle(event);
 });
 ```
 
-## Document Output
+### Command Types
 
-Convert structured documents to platform-native rich text.
+Commands are defined using:
 
 ```typescript
-import { Document, header, text, list, divider, context } from "@hardlydifficult/document-generator";
-
-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);
+interface Command {
+  name: string;
+  pattern: RegExp;
+  handler: (args: {
+    context: Context;
+    match: RegExpExecArray;
+    event: MessageEvent;
+  }) => Promise<string | void>;
+}
 ```
 
-## Typing
-
-All core types are exported for direct use.
+Contexts include channel, user, and optional state:
 
 ```typescript
-import type { Member, Message, Thread, MessageBatch } from "@hardlydifficult/chat";
+interface Context {
+  channel: Channel;
+  user: Member;
+  state?: Map<string, any>;
+}
 ```
 
-## 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           |
-
-### Additional Features from Current README
+### Job Lifecycle
 
-#### Bot Identity
-
-After `connect()`, `client.me` exposes the authenticated bot user:
+Long-running commands support cancel/dismiss UI flows:
 
 ```typescript
-const client = createChatClient({ type: "slack" });
-await client.connect(channelId);
+import { startJobLifecycle } from '@hardlydifficult/chat';
 
-console.log(client.me?.id); // "U09B00R2R96"
-console.log(client.me?.username); // "sprint-bot"
-console.log(client.me?.mention); // "<@U09B00R2R96>"
+await startJobLifecycle(thread, {
+  onCancel: async () => {
+    // Handle user-initiated cancellation
+  },
+  onDismiss: async () => {
+    // Add dismiss emoji for user to remove later
+  }
+});
 ```
 
-#### Incoming Messages
+## Member Matching
 
-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.
+Resolve users by mention, ID, or fuzzy match:
 
 ```typescript
-const unsubscribe = channel.onMessage((msg) => {
-  console.log(`${msg.author.username}: ${msg.content}`);
+import { matchMember } from '@hardlydifficult/chat';
 
-  // 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!");
-});
+// Match a member by mention or name
+const member = await matchMember(
+  channel,
+  '@john', // or 'john', or '123456789'
+  { fuzzyThreshold: 0.7 }
+);
 
-// Later: stop listening
-unsubscribe();
+// Use aliases for more lenient matching
+const aliases = { 'johnny': 'john' };
+const member = await matchMember(channel, 'johnny', { aliases });
 ```
 
-Messages from the bot itself are automatically filtered out.
-
-#### Oversized Message Handling
-
-Messages that exceed platform limits (Discord: 2000 chars, Slack: 4000 chars) are handled automatically:
-
-- **`postMessage`**: Sends the full content as a `message.txt` file attachment instead of failing
-- **`update`**: Truncates with `…` (edits cannot attach files on either platform)
+## Output Formatting
 
-No caller changes needed — the library handles this transparently.
-
-#### File Attachments
-
-Send files as message attachments.
+Convert abstract document blocks into platform-specific formats.
 
 ```typescript
-channel.postMessage("Here's the scan report", {
-  files: [
-    { content: Buffer.from(markdownContent), name: "report.md" },
-    { content: "plain text content", name: "notes.txt" },
-  ],
-});
+import { formatDiscord, formatSlack } from '@hardlydifficult/chat';
+
+const document = {
+  type: 'doc',
+  content: [
+    { type: 'text', text: 'Hello ' },
+    { type: 'bold', content: 'world' }
+  ]
+};
+
+const discordPayload = formatDiscord(document);
+const slackBlocks = formatSlack(document);
 ```
 
-#### Dismissable Messages
-
-Post a message that the specified user can dismiss by clicking the trash reaction.
-
-```typescript
-await channel.postDismissable("Build complete!", user.id);
-```
+Supported block types include:
+- `text`, `bold`, `italic`, `code`, `pre`
+- `header`, `divider`, `section`, `button`
+- `mention` (platform-specific user/channel reference)
 
-#### Declarative Reactions
+## Message Tracking
 
-`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.
+Track and update messages by key for efficient dynamic updates.
 
 ```typescript
-const msg = await channel.postMessage("PR #42: open");
+import { MessageTracker } from '@hardlydifficult/chat';
 
-// Set initial reactions
-msg.setReactions(["🟡"], (event) => handlePending(event));
-
-// Later: update to merged state — removes 🟡, adds 🟢, swaps handler
-msg.setReactions(["🟢"], (event) => handleMerged(event));
+const tracker = new MessageTracker(channel);
+tracker.track('status', async () => channel.send('Updating...'));
+tracker.edit('status', async (message) => {
+  await message.update('Updated!');
+});
 ```
 
-#### Message Batches
+## File Operations
 
-Group related posted messages so they can be retrieved and cleaned up together.
+Post and update messages with file attachments.
 
 ```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));
-}
+// Discord: attach files via buildMessagePayload
+import { buildMessagePayload } from '@hardlydifficult/chat/discord';
 
-await batch.post(callouts);
-await batch.finish();
-
-const recent = await channel.getBatches({
-  key: "sprint-update",
-  author: "me",
-  limit: 5,
+const payload = buildMessagePayload({
+  content: 'Report',
+  files: [{ filename: 'report.pdf', data: buffer }]
 });
 
-await recent[0].deleteAll({ cascadeReplies: true });
-```
-
-For safer lifecycle handling, use `withBatch` (auto-finishes in `finally`):
+await channel.send(payload);
 
-```typescript
-await channel.withBatch({ key: "sprint-update" }, async (batch) => {
-  await batch.post("Part 1");
-  await batch.post("Part 2");
+// Slack: use built-in file support
+await slackClient.postMessage({
+  channel: 'C123',
+  text: 'Report',
+  file: buffer,
+  filename: 'report.pdf'
 });
 ```
 
-#### Threads (Enhanced)
-
-You can also create a thread from an existing message:
-
-```typescript
-const msg = await channel.postMessage("Starting a discussion");
-const thread = await msg.startThread("Discussion Thread", 1440); // auto-archive in minutes
-```
-
-Reconnect to an existing thread by ID (e.g., after a restart):
-
-```typescript
-const thread = channel.openThread(savedThreadId);
-await thread.post("I'm back!");
-thread.onReply(async (msg) => { /* ... */ });
-```
+## 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
 
-#### Typing Indicator (Enhanced)
+## Platform Differences
 
-For one-shot use, `sendTyping()` sends a single indicator without automatic refresh:
+| 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
-await channel.sendTyping();
-```
+## Appendix
 
-> **Slack note:** Slack does not support bot typing indicators. Both methods are no-ops on Slack.
+### Error Handling
 
-#### Bulk Operations (Enhanced)
+Platform-specific error codes are mapped to user-friendly messages:
 
 ```typescript
-// Delete up to 100 recent messages
-const deletedCount = await channel.bulkDelete(50);
-
-// 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 });
+import { isRecoverableError, getErrorFriendlyMessage } from '@hardlydifficult/chat';
 
-// Get all threads (active and archived) and delete them
-const threads = await channel.getThreads();
-for (const thread of threads) {
-  await thread.delete();
+try {
+  await channel.send('Failed message');
+} catch (error) {
+  if (isRecoverableError(error)) {
+    // Retry with backoff
+  } else {
+    console.log(getErrorFriendlyMessage(error));
+  }
 }
 ```
 
-> **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.
-
-#### Connection Resilience
-
-Both platforms auto-reconnect via their underlying libraries (discord.js and @slack/bolt). Register callbacks for observability.
-
-```typescript
-const client = createChatClient({ type: "discord" });
-
-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.
+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
-
-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
+Example:
+```typescript
+await channel.cleanup({ mode: 'since', timestamp: new Date(Date.now() - 86400000) });
+```

package/package.json

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