@onmars/lunar-discord 0.1.0

package/src/__tests__/formatter.test.ts

@@ -0,0 +1,219 @@
+/**
+ * # Discord Formatter — Functional Specification
+ *
+ * ## splitMessage(text, maxLength=2000)
+ * Splits long text into Discord-safe chunks (default 2000 chars).
+ *
+ * ### Split strategy (ordered by preference):
+ * 1. **Paragraph break** (`\n\n`) — cleanest split, preserves structure
+ * 2. **Line break** (`\n`) — next best, preserves lines
+ * 3. **Space** (` `) — word-boundary split, no words cut in half
+ * 4. **Hard split** (exact char count) — last resort for single long tokens
+ *
+ * ### Invariants:
+ * - Every chunk ≤ maxLength
+ * - Concatenating all chunks exactly recreates the original text
+ * - Empty input → single-element array with empty string
+ * - Text at or under limit → single-element array (no unnecessary split)
+ */
+import { describe, expect, it } from 'bun:test'
+import { formatForDiscord, splitMessage } from '../formatter'
+
+// ═══════════════════════════════════════════════════════════════════
+// splitMessage — Discord message chunking
+// ═══════════════════════════════════════════════════════════════════
+
+describe('splitMessage', () => {
+  // --- No split needed ---
+
+  it('short text: returns single-element array', () => {
+    expect(splitMessage('Hello world')).toEqual(['Hello world'])
+  })
+
+  it('text exactly at limit: no split', () => {
+    const text = 'a'.repeat(2000)
+    const result = splitMessage(text)
+    expect(result).toHaveLength(1)
+    expect(result[0]).toBe(text)
+  })
+
+  it('empty string: returns [""]', () => {
+    expect(splitMessage('')).toEqual([''])
+  })
+
+  // --- Split strategies (in preference order) ---
+
+  it('strategy 1: splits at paragraph boundary (\\n\\n)', () => {
+    const para1 = 'a'.repeat(1500)
+    const para2 = 'b'.repeat(800)
+    const text = `${para1}\n\n${para2}`
+
+    const result = splitMessage(text)
+    expect(result.length).toBeGreaterThanOrEqual(2)
+    expect(result[0].trim()).toBe(para1)
+  })
+
+  it('strategy 2: splits at line boundary when no paragraph break', () => {
+    const line1 = 'a'.repeat(1500)
+    const line2 = 'b'.repeat(800)
+    const text = `${line1}\n${line2}`
+
+    const result = splitMessage(text)
+    expect(result.length).toBeGreaterThanOrEqual(2)
+  })
+
+  it('strategy 4: hard-splits continuous text with no break points', () => {
+    const text = 'a'.repeat(5000) // no spaces, no newlines
+
+    const result = splitMessage(text)
+    expect(result.length).toBeGreaterThanOrEqual(3)
+    for (const chunk of result) {
+      expect(chunk.length).toBeLessThanOrEqual(2000)
+    }
+  })
+
+  // --- Invariants ---
+
+  it('invariant: every chunk ≤ maxLength', () => {
+    const text = 'Hello world, this is a test message'
+    const result = splitMessage(text, 15) // very small limit
+
+    for (const chunk of result) {
+      expect(chunk.length).toBeLessThanOrEqual(15)
+    }
+  })
+
+  it('invariant: concatenated chunks == original text', () => {
+    const text = Array(100).fill('The quick brown fox jumps over the lazy dog.').join('\n')
+    const chunks = splitMessage(text)
+
+    expect(chunks.join('')).toBe(text)
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// formatForDiscord — markdown formatting (currently passthrough)
+// ═══════════════════════════════════════════════════════════════════
+
+describe('formatForDiscord', () => {
+  it('passes markdown text through unchanged', () => {
+    const text = '**bold** and *italic*'
+    expect(formatForDiscord(text)).toBe(text)
+  })
+
+  it('preserves code blocks', () => {
+    const text = '```js\nconsole.log("hello")\n```'
+    expect(formatForDiscord(text)).toBe(text)
+  })
+
+  it('preserves inline code', () => {
+    const text = 'Use `npm install` to install'
+    expect(formatForDiscord(text)).toBe(text)
+  })
+
+  it('handles empty string', () => {
+    expect(formatForDiscord('')).toBe('')
+  })
+
+  it('preserves multiline text', () => {
+    const text = 'Line 1\nLine 2\n\nParagraph 2'
+    expect(formatForDiscord(text)).toBe(text)
+  })
+
+  it('preserves Discord-specific formatting (mentions, channels)', () => {
+    const text = 'Hey <@123456> check <#789012>'
+    expect(formatForDiscord(text)).toBe(text)
+  })
+})
+
+// ═══════════════════════════════════════════════════════════════════
+// splitMessage — additional edge cases and strategies
+// ═══════════════════════════════════════════════════════════════════
+
+describe('splitMessage — additional cases', () => {
+  it('strategy 3: splits at space boundary when no newlines', () => {
+    // Build a string with words separated by spaces, exceeding the limit
+    const words = Array(300).fill('hello').join(' ') // ~1800 chars of words
+    const extra = Array(50).fill('world').join(' ') // ~300 more
+    const text = words + ' ' + extra
+
+    const result = splitMessage(text)
+    expect(result.length).toBeGreaterThanOrEqual(2)
+    for (const chunk of result) {
+      expect(chunk.length).toBeLessThanOrEqual(2000)
+    }
+    // Verify no words are split mid-word
+    const allText = result.join('')
+    expect(allText).toBe(text)
+  })
+
+  it('custom maxLength parameter is respected', () => {
+    const text = 'abcdefghij' // 10 chars
+    const result = splitMessage(text, 5)
+
+    for (const chunk of result) {
+      expect(chunk.length).toBeLessThanOrEqual(5)
+    }
+    expect(result.join('')).toBe(text)
+  })
+
+  it('single character per chunk at maxLength=1', () => {
+    const text = 'abc'
+    const result = splitMessage(text, 1)
+
+    expect(result).toEqual(['a', 'b', 'c'])
+  })
+
+  it('preserves content exactly for text at maxLength boundary', () => {
+    const text = 'x'.repeat(2000)
+    const result = splitMessage(text)
+    expect(result).toHaveLength(1)
+    expect(result[0]).toBe(text)
+  })
+
+  it('text exactly 1 char over limit splits into two', () => {
+    const text = 'x'.repeat(2001)
+    const result = splitMessage(text)
+    expect(result.length).toBeGreaterThanOrEqual(2)
+    expect(result.join('')).toBe(text)
+  })
+
+  it('prefers paragraph split over line split', () => {
+    // Build: ~1200 chars, then \n\n, then ~1200 chars, then \n, then ~200 chars
+    const part1 = 'a'.repeat(1200)
+    const part2 = 'b'.repeat(700)
+    const part3 = 'c'.repeat(200)
+    const text = `${part1}\n\n${part2}\n${part3}`
+
+    const result = splitMessage(text)
+    // First chunk should end at the paragraph break
+    expect(result[0]).toBe(part1 + '\n\n')
+    expect(result.join('')).toBe(text)
+  })
+
+  it('handles many consecutive newlines', () => {
+    const text = 'a'.repeat(1500) + '\n\n\n\n' + 'b'.repeat(1500)
+    const result = splitMessage(text)
+    expect(result.length).toBeGreaterThanOrEqual(2)
+    for (const chunk of result) {
+      expect(chunk.length).toBeLessThanOrEqual(2000)
+    }
+    expect(result.join('')).toBe(text)
+  })
+
+  it('handles text with only whitespace content', () => {
+    const text = '   '
+    const result = splitMessage(text)
+    expect(result).toEqual(['   '])
+  })
+
+  it('three chunks for very long text', () => {
+    const text = 'x'.repeat(5500) // should need at least 3 chunks
+    const result = splitMessage(text)
+    expect(result.length).toBeGreaterThanOrEqual(3)
+    for (const chunk of result) {
+      expect(chunk.length).toBeLessThanOrEqual(2000)
+    }
+    expect(result.join('')).toBe(text)
+  })
+})

package/src/adapter.ts

@@ -0,0 +1,254 @@
+import type { Attachment, Channel, IncomingMessage, OutgoingMessage } from '@onmars/lunar-core'
+import { log } from '@onmars/lunar-core'
+import { Client, type Message as DMessage, Events, GatewayIntentBits } from 'discord.js'
+import { formatForDiscord, splitMessage } from './formatter'
+
+export interface DiscordChannelOptions {
+  /** Adapter ID — unique per bot account (default: 'discord') */
+  id?: string
+  /** Discord bot token */
+  token: string
+  /** Guild ID to operate in */
+  guildId: string
+  /** Allowed user IDs (empty = allow all) */
+  allowedUsers?: string[]
+  /** Allowed channel IDs (empty = allow all in guild) */
+  allowedChannels?: string[]
+}
+
+export class DiscordChannel implements Channel {
+  readonly id: string
+  readonly name: string
+
+  private client: Client
+  private messageHandler?: (msg: IncomingMessage) => Promise<void>
+  private connected = false
+
+  constructor(private options: DiscordChannelOptions) {
+    this.id = options.id ?? 'discord'
+    this.name = options.id ?? 'discord'
+    this.client = new Client({
+      intents: [
+        GatewayIntentBits.Guilds,
+        GatewayIntentBits.GuildMessages,
+        GatewayIntentBits.MessageContent,
+        GatewayIntentBits.DirectMessages,
+      ],
+    })
+  }
+
+  async connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.client.once(Events.ClientReady, (c) => {
+        log.info({ user: c.user.tag, guilds: c.guilds.cache.size }, 'Discord connected')
+        this.connected = true
+        this.setupMessageListener()
+        this.setupLifecycleListeners()
+        resolve()
+      })
+
+      this.client.once(Events.Error, reject)
+      this.client.login(this.options.token).catch(reject)
+    })
+  }
+
+  async disconnect(): Promise<void> {
+    this.connected = false
+    this.client.destroy()
+    log.info('Discord disconnected')
+  }
+
+  isConnected(): boolean {
+    return this.connected
+  }
+
+  onMessage(handler: (msg: IncomingMessage) => Promise<void>): void {
+    this.messageHandler = handler
+  }
+
+  async send(target: string, content: OutgoingMessage): Promise<string | undefined> {
+    if (!this.connected) {
+      log.warn({ target }, 'Cannot send — Discord is disconnected')
+      return undefined
+    }
+
+    const channel = await this.client.channels.fetch(target)
+    if (!channel?.isTextBased() || !('send' in channel)) {
+      log.error({ target }, 'Cannot send to channel')
+      return undefined
+    }
+
+    const formatted = formatForDiscord(content.text)
+    const chunks = splitMessage(formatted)
+
+    // Prepare file attachments (audio, images, etc.)
+    const files =
+      content.attachments?.map((att) => ({
+        attachment:
+          att.data instanceof Buffer ? att.data : Buffer.from(att.data as string, 'base64'),
+        name: att.filename,
+        contentType: att.mimeType,
+      })) ?? []
+
+    let lastMessageId: string | undefined
+
+    for (let i = 0; i < chunks.length; i++) {
+      const isLastChunk = i === chunks.length - 1
+      const sent = await channel.send({
+        content: chunks[i],
+        reply:
+          content.replyTo && i === 0
+            ? { messageReference: content.replyTo, failIfNotExists: false }
+            : undefined,
+        // Attach files to the last text chunk so audio follows the complete message
+        files: isLastChunk && files.length > 0 ? files : undefined,
+      })
+      lastMessageId = sent.id
+    }
+
+    return lastMessageId
+  }
+
+  async sendTyping(target: string): Promise<void> {
+    if (!this.connected) return
+    try {
+      const channel = await this.client.channels.fetch(target)
+      if (channel?.isTextBased() && 'sendTyping' in channel) {
+        await channel.sendTyping()
+      }
+    } catch {
+      // Best effort
+    }
+  }
+
+  async edit(messageId: string, target: string, content: OutgoingMessage): Promise<void> {
+    if (!this.connected) return
+    const channel = await this.client.channels.fetch(target)
+    if (!channel?.isTextBased() || !('messages' in channel)) return
+
+    const msg = await channel.messages.fetch(messageId)
+    await msg.edit({ content: formatForDiscord(content.text) })
+  }
+
+  async delete(messageId: string, target: string): Promise<void> {
+    if (!this.connected) return
+    const channel = await this.client.channels.fetch(target)
+    if (!channel?.isTextBased() || !('messages' in channel)) return
+
+    const msg = await channel.messages.fetch(messageId)
+    await msg.delete()
+  }
+
+  async react(messageId: string, target: string, emoji: string): Promise<void> {
+    if (!this.connected) return
+    const channel = await this.client.channels.fetch(target)
+    if (!channel?.isTextBased() || !('messages' in channel)) return
+
+    const msg = await channel.messages.fetch(messageId)
+    await msg.react(emoji)
+  }
+
+  // --- Private ---
+
+  private setupLifecycleListeners(): void {
+    // Persistent error handler (replaces the once() from connect)
+    this.client.on(Events.Error, (err) => {
+      log.error({ err: err.message }, 'Discord client error')
+    })
+
+    this.client.on(Events.Warn, (msg) => {
+      log.warn({ msg }, 'Discord warning')
+    })
+
+    // Shard lifecycle — discord.js auto-reconnects, we track state
+    this.client.on(Events.ShardDisconnect, (event, shardId) => {
+      this.connected = false
+      log.warn(
+        { shardId, code: event.code, reason: event.reason },
+        'Discord disconnected — auto-reconnect pending',
+      )
+    })
+
+    this.client.on(Events.ShardReconnecting, (shardId) => {
+      log.info({ shardId }, 'Discord reconnecting...')
+    })
+
+    this.client.on(Events.ShardResume, (shardId, replayed) => {
+      this.connected = true
+      log.info({ shardId, replayed }, 'Discord reconnected (resumed)')
+    })
+
+    this.client.on(Events.ShardReady, (shardId) => {
+      this.connected = true
+      log.info({ shardId }, 'Discord shard ready')
+    })
+  }
+
+  private setupMessageListener(): void {
+    this.client.on(Events.MessageCreate, async (msg: DMessage) => {
+      // Ignore bots
+      if (msg.author.bot) return
+
+      // Guild check
+      if (msg.guildId !== this.options.guildId) return
+
+      // Channel allowlist
+      if (
+        this.options.allowedChannels?.length &&
+        !this.options.allowedChannels.includes(msg.channelId)
+      ) {
+        return
+      }
+
+      // User allowlist
+      if (this.options.allowedUsers?.length && !this.options.allowedUsers.includes(msg.author.id)) {
+        return
+      }
+
+      // Skip empty messages (unless attachments)
+      if (!msg.content.trim() && msg.attachments.size === 0) return
+
+      // Build IncomingMessage
+      const incoming: IncomingMessage = {
+        id: msg.id,
+        channelId: msg.channelId,
+        sender: {
+          id: msg.author.id,
+          name: msg.member?.displayName ?? msg.author.displayName,
+          username: msg.author.username,
+        },
+        text: msg.content,
+        attachments: this.parseAttachments(msg),
+        replyTo: msg.reference?.messageId,
+        raw: msg,
+        timestamp: msg.createdAt,
+      }
+
+      if (this.messageHandler) {
+        try {
+          await this.messageHandler(incoming)
+        } catch (err) {
+          log.error({ err, messageId: msg.id }, 'Error handling message')
+        }
+      }
+    })
+  }
+
+  private parseAttachments(msg: DMessage): Attachment[] {
+    return msg.attachments.map((att) => ({
+      type: this.inferAttachmentType(att.contentType),
+      url: att.url,
+      filename: att.name ?? undefined,
+      mimeType: att.contentType ?? undefined,
+      size: att.size,
+    }))
+  }
+
+  private inferAttachmentType(contentType?: string | null): Attachment['type'] {
+    if (!contentType) return 'file'
+    if (contentType.startsWith('image/')) return 'image'
+    if (contentType.startsWith('audio/')) return 'audio'
+    if (contentType.startsWith('video/')) return 'video'
+    return 'file'
+  }
+}

package/src/formatter.ts

@@ -0,0 +1,58 @@
+/** Max message length for Discord */
+const MAX_LENGTH = 2000
+
+/**
+ * Format text for Discord's markdown dialect.
+ * Handles code blocks, bold, italic, etc.
+ */
+export function formatForDiscord(text: string): string {
+  // Discord uses a subset of markdown — most standard markdown works.
+  // Main differences: no heading rendering, limited HTML.
+  // For now, pass through. Extend as needed.
+  return text
+}
+
+/**
+ * Split a long message into chunks that fit Discord's 2000 char limit.
+ * Tries to split at paragraph/line boundaries to avoid breaking formatting.
+ */
+export function splitMessage(text: string, maxLength = MAX_LENGTH): string[] {
+  if (text.length <= maxLength) return [text]
+
+  const chunks: string[] = []
+  let remaining = text
+
+  while (remaining.length > 0) {
+    if (remaining.length <= maxLength) {
+      chunks.push(remaining)
+      break
+    }
+
+    // Find best split point
+    let splitAt = maxLength
+
+    // Try to split at double newline (paragraph)
+    const paraBreak = remaining.lastIndexOf('\n\n', maxLength)
+    if (paraBreak > maxLength * 0.5) {
+      splitAt = paraBreak + 2
+    } else {
+      // Try single newline
+      const lineBreak = remaining.lastIndexOf('\n', maxLength)
+      if (lineBreak > maxLength * 0.5) {
+        splitAt = lineBreak + 1
+      } else {
+        // Try space
+        const spaceBreak = remaining.lastIndexOf(' ', maxLength)
+        if (spaceBreak > maxLength * 0.5) {
+          splitAt = spaceBreak + 1
+        }
+        // Else hard split at maxLength
+      }
+    }
+
+    chunks.push(remaining.slice(0, splitAt))
+    remaining = remaining.slice(splitAt)
+  }
+
+  return chunks
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { DiscordChannel } from './adapter'
+export { formatForDiscord, splitMessage } from './formatter'