@open-mercato/channel-discord 0.6.8-develop.7090.1.4dbca7b350

package/src/modules/channel_discord/lib/discord-rest.ts

@@ -0,0 +1,393 @@
+/**
+ * Thin Discord REST API client. Same trade-off as the Gmail provider's
+ * `gmail-client.ts`: we call `fetch` directly (no `discord.js`) so the adapter
+ * ships zero heavyweight runtime dependencies and stays swappable in tests via
+ * `setDiscordRestClient(...)`.
+ *
+ * Only the endpoints the adapter actually uses are exposed:
+ *   - createMessage   → POST   /channels/{id}/messages
+ *   - editMessage     → PATCH  /channels/{id}/messages/{mid}
+ *   - deleteMessage   → DELETE /channels/{id}/messages/{mid}
+ *   - addReaction     → PUT    /channels/{id}/messages/{mid}/reactions/{emoji}/@me
+ *   - removeReaction  → DELETE /channels/{id}/messages/{mid}/reactions/{emoji}/@me
+ *   - listMessages    → GET    /channels/{id}/messages?before=
+ *   - getCurrentUser  → GET    /users/@me
+ *   - getGatewayBot   → GET    /gateway/bot
+ *   - registerGuildCommands → PUT /applications/{app}/guilds/{guild}/commands
+ *   - editOriginalInteractionResponse → PATCH /webhooks/{app}/{token}/messages/@original
+ *   - createInteractionFollowUp       → POST  /webhooks/{app}/{token}
+ */
+import { fetchWithTimeout, FetchTimeoutError } from '@open-mercato/shared/lib/http/fetchWithTimeout'
+
+export const DISCORD_API_BASE = 'https://discord.com/api/v10'
+
+export interface DiscordAuth {
+  botToken: string
+}
+
+export interface DiscordUser {
+  id: string
+  username: string
+  global_name?: string | null
+  bot?: boolean
+  discriminator?: string
+  avatar?: string | null
+}
+
+/**
+ * Open Mercato marker carried by a message object that was SYNTHESIZED from a
+ * Discord interaction rather than received from Discord. Discord never returns
+ * this key; it exists so `normalizeInboundDiscordMessage` can tell a hub
+ * consumer that the record came from a slash command or a component press
+ * instead of someone typing in the channel.
+ */
+export interface DiscordInteractionOrigin {
+  id: string
+  type: number
+  applicationId: string
+  commandName?: string
+  customId?: string
+}
+
+export interface DiscordMessageObject {
+  id: string
+  channel_id: string
+  guild_id?: string
+  content: string
+  author: DiscordUser
+  timestamp: string
+  attachments?: Array<{ id: string; url: string; filename: string; content_type?: string; size?: number }>
+  message_reference?: { message_id?: string; channel_id?: string; guild_id?: string }
+  /** Present only on interaction-derived messages — see `DiscordInteractionOrigin`. */
+  discord_interaction?: DiscordInteractionOrigin
+  [key: string]: unknown
+}
+
+export interface CreateMessageInput {
+  channelId: string
+  content: string
+  messageReferenceId?: string
+  allowedMentions?: Record<string, unknown>
+}
+
+/**
+ * Body of a message that replaces (or follows) a deferred interaction response.
+ *
+ * `ephemeral` maps to Discord's `flags: 64` — only the invoking user sees the
+ * message. It is the right default for an operational acknowledgement that would
+ * otherwise be noise for everyone else in the channel.
+ */
+export interface InteractionResponseInput {
+  content: string
+  ephemeral?: boolean
+}
+
+/** Discord message flag: visible only to the user who triggered the interaction. */
+export const DISCORD_MESSAGE_FLAG_EPHEMERAL = 64
+
+export interface GatewayBotResponse {
+  url: string
+  shards: number
+  session_start_limit?: { total: number; remaining: number; reset_after: number; max_concurrency: number }
+}
+
+export interface DiscordRestClient {
+  createMessage(auth: DiscordAuth, input: CreateMessageInput): Promise<DiscordMessageObject>
+  editMessage(auth: DiscordAuth, channelId: string, messageId: string, content: string): Promise<DiscordMessageObject>
+  deleteMessage(auth: DiscordAuth, channelId: string, messageId: string): Promise<void>
+  addReaction(auth: DiscordAuth, channelId: string, messageId: string, emoji: string): Promise<void>
+  removeReaction(auth: DiscordAuth, channelId: string, messageId: string, emoji: string): Promise<void>
+  listMessages(
+    auth: DiscordAuth,
+    channelId: string,
+    input: { before?: string; limit?: number },
+  ): Promise<DiscordMessageObject[]>
+  getCurrentUser(auth: DiscordAuth): Promise<DiscordUser>
+  getGatewayBot(auth: DiscordAuth): Promise<GatewayBotResponse>
+  registerGuildCommands(
+    auth: DiscordAuth,
+    applicationId: string,
+    guildId: string,
+    commands: Array<Record<string, unknown>>,
+  ): Promise<void>
+  /**
+   * Replace the "thinking…" placeholder a deferred interaction response left
+   * behind. This is the call that ends the pending state, so it is the one the
+   * dispatch worker makes first.
+   *
+   * Takes NO bot token: the interaction token in the URL is the credential, and
+   * Discord documents these webhook endpoints as requiring no authorization. The
+   * token is single-interaction and expires after 15 minutes.
+   */
+  editOriginalInteractionResponse(
+    applicationId: string,
+    interactionToken: string,
+    input: InteractionResponseInput,
+  ): Promise<void>
+  /**
+   * Post an ADDITIONAL message against the same interaction token. Used as the
+   * fallback when the original response can no longer be edited.
+   */
+  createInteractionFollowUp(
+    applicationId: string,
+    interactionToken: string,
+    input: InteractionResponseInput,
+  ): Promise<void>
+}
+
+export class DiscordApiError extends Error {
+  readonly status: number
+  readonly detail: string
+  constructor(message: string, status: number, detail: string) {
+    super(message)
+    this.name = 'DiscordApiError'
+    this.status = status
+    this.detail = detail
+  }
+}
+
+const DISCORD_MAX_RETRIES = 3
+const DISCORD_BACKOFF_BASE_MS = 500
+const DISCORD_BACKOFF_CAP_MS = 8_000
+const DISCORD_DEFAULT_REQUEST_TIMEOUT_MS = 15_000
+
+function resolveRequestTimeoutMs(): number {
+  const fromEnv = Number.parseInt(process.env.OM_CHANNEL_DISCORD_REQUEST_TIMEOUT_MS ?? '', 10)
+  return Number.isFinite(fromEnv) && fromEnv > 0 ? fromEnv : DISCORD_DEFAULT_REQUEST_TIMEOUT_MS
+}
+
+/**
+ * Discord emoji path encoding: unicode emoji is URL-encoded as-is; a custom
+ * emoji uses the `name:id` form. We pass through the caller's value and only
+ * `encodeURIComponent` it so both forms survive.
+ */
+function encodeEmoji(emoji: string): string {
+  return encodeURIComponent(emoji)
+}
+
+class FetchDiscordRestClient implements DiscordRestClient {
+  async createMessage(auth: DiscordAuth, input: CreateMessageInput): Promise<DiscordMessageObject> {
+    const body: Record<string, unknown> = {
+      content: input.content,
+      allowed_mentions: input.allowedMentions ?? { parse: [] },
+    }
+    if (input.messageReferenceId) {
+      body.message_reference = { message_id: input.messageReferenceId }
+    }
+    return this.request<DiscordMessageObject>(
+      auth,
+      'POST',
+      `/channels/${encodeURIComponent(input.channelId)}/messages`,
+      body,
+    )
+  }
+
+  async editMessage(
+    auth: DiscordAuth,
+    channelId: string,
+    messageId: string,
+    content: string,
+  ): Promise<DiscordMessageObject> {
+    return this.request<DiscordMessageObject>(
+      auth,
+      'PATCH',
+      `/channels/${encodeURIComponent(channelId)}/messages/${encodeURIComponent(messageId)}`,
+      { content },
+    )
+  }
+
+  async deleteMessage(auth: DiscordAuth, channelId: string, messageId: string): Promise<void> {
+    await this.request<void>(
+      auth,
+      'DELETE',
+      `/channels/${encodeURIComponent(channelId)}/messages/${encodeURIComponent(messageId)}`,
+    )
+  }
+
+  async addReaction(auth: DiscordAuth, channelId: string, messageId: string, emoji: string): Promise<void> {
+    await this.request<void>(
+      auth,
+      'PUT',
+      `/channels/${encodeURIComponent(channelId)}/messages/${encodeURIComponent(messageId)}/reactions/${encodeEmoji(emoji)}/@me`,
+    )
+  }
+
+  async removeReaction(auth: DiscordAuth, channelId: string, messageId: string, emoji: string): Promise<void> {
+    await this.request<void>(
+      auth,
+      'DELETE',
+      `/channels/${encodeURIComponent(channelId)}/messages/${encodeURIComponent(messageId)}/reactions/${encodeEmoji(emoji)}/@me`,
+    )
+  }
+
+  async listMessages(
+    auth: DiscordAuth,
+    channelId: string,
+    input: { before?: string; limit?: number },
+  ): Promise<DiscordMessageObject[]> {
+    const search = new URLSearchParams()
+    if (input.before) search.set('before', input.before)
+    search.set('limit', String(Math.min(Math.max(input.limit ?? 50, 1), 100)))
+    const query = search.toString()
+    return this.request<DiscordMessageObject[]>(
+      auth,
+      'GET',
+      `/channels/${encodeURIComponent(channelId)}/messages?${query}`,
+    )
+  }
+
+  async getCurrentUser(auth: DiscordAuth): Promise<DiscordUser> {
+    return this.request<DiscordUser>(auth, 'GET', '/users/@me')
+  }
+
+  async getGatewayBot(auth: DiscordAuth): Promise<GatewayBotResponse> {
+    return this.request<GatewayBotResponse>(auth, 'GET', '/gateway/bot')
+  }
+
+  async registerGuildCommands(
+    auth: DiscordAuth,
+    applicationId: string,
+    guildId: string,
+    commands: Array<Record<string, unknown>>,
+  ): Promise<void> {
+    await this.request<unknown>(
+      auth,
+      'PUT',
+      `/applications/${encodeURIComponent(applicationId)}/guilds/${encodeURIComponent(guildId)}/commands`,
+      commands,
+    )
+  }
+
+  async editOriginalInteractionResponse(
+    applicationId: string,
+    interactionToken: string,
+    input: InteractionResponseInput,
+  ): Promise<void> {
+    await this.request<unknown>(
+      null,
+      'PATCH',
+      `/webhooks/${encodeURIComponent(applicationId)}/${encodeURIComponent(interactionToken)}/messages/@original`,
+      interactionResponseBody(input),
+    )
+  }
+
+  async createInteractionFollowUp(
+    applicationId: string,
+    interactionToken: string,
+    input: InteractionResponseInput,
+  ): Promise<void> {
+    await this.request<unknown>(
+      null,
+      'POST',
+      `/webhooks/${encodeURIComponent(applicationId)}/${encodeURIComponent(interactionToken)}`,
+      interactionResponseBody(input),
+    )
+  }
+
+  private async request<T>(
+    auth: DiscordAuth | null,
+    method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE',
+    path: string,
+    body?: unknown,
+  ): Promise<T> {
+    const url = `${DISCORD_API_BASE}${path}`
+    // `auth === null` is the interaction-webhook family: the token in the path is
+    // the credential and Discord rejects nothing for the missing header, so
+    // sending the bot token there would leak it for no benefit.
+    const headers: Record<string, string> = auth ? { Authorization: `Bot ${auth.botToken}` } : {}
+    let payload: BodyInit | undefined
+    if (body !== undefined) {
+      headers['Content-Type'] = 'application/json'
+      payload = JSON.stringify(body)
+    }
+
+    let attempt = 0
+    let lastError: DiscordApiError | null = null
+    while (attempt <= DISCORD_MAX_RETRIES) {
+      let res: Response
+      try {
+        res = await fetchWithTimeout(url, { method, headers, body: payload, timeoutMs: resolveRequestTimeoutMs() })
+      } catch (err) {
+        const errName = (err as { name?: unknown } | null)?.name
+        const aborted = err instanceof FetchTimeoutError || errName === 'TimeoutError' || errName === 'AbortError'
+        if (!aborted) throw err
+        const timeoutError = new DiscordApiError(`Discord API ${method} ${path} timed out`, 599, 'request timed out')
+        if (attempt === DISCORD_MAX_RETRIES) throw timeoutError
+        lastError = timeoutError
+        await sleep(computeBackoff(attempt))
+        attempt += 1
+        continue
+      }
+
+      const text = await res.text()
+      if (res.ok) {
+        if (!text) return undefined as unknown as T
+        return JSON.parse(text) as T
+      }
+
+      const detail = parseErrorMessage(text) ?? `${res.status} ${res.statusText}`
+      const apiError = new DiscordApiError(`Discord API ${method} ${path} failed: ${detail}`, res.status, detail)
+      const transient = res.status === 429 || (res.status >= 500 && res.status < 600)
+      if (!transient || attempt === DISCORD_MAX_RETRIES) {
+        throw apiError
+      }
+      lastError = apiError
+      const waitMs = parseRetryAfter(res.headers.get('retry-after')) ?? computeBackoff(attempt)
+      await sleep(waitMs)
+      attempt += 1
+    }
+    throw lastError ?? new DiscordApiError(`Discord API ${method} ${path} exhausted retries`, 599, 'retries exhausted')
+  }
+}
+
+function interactionResponseBody(input: InteractionResponseInput): Record<string, unknown> {
+  return {
+    content: input.content,
+    // Interaction replies quote whatever the user typed, so mentions inside it
+    // must not become live pings — same guard `createMessage` applies.
+    allowed_mentions: { parse: [] },
+    ...(input.ephemeral ? { flags: DISCORD_MESSAGE_FLAG_EPHEMERAL } : {}),
+  }
+}
+
+function parseRetryAfter(value: string | null): number | null {
+  if (!value) return null
+  const asNumber = Number(value)
+  if (Number.isFinite(asNumber) && asNumber >= 0) {
+    return Math.min(asNumber * 1000, DISCORD_BACKOFF_CAP_MS)
+  }
+  return null
+}
+
+function computeBackoff(attempt: number): number {
+  const raw = DISCORD_BACKOFF_BASE_MS * Math.pow(2, attempt)
+  const jitter = Math.floor(Math.random() * 100)
+  return Math.min(raw + jitter, DISCORD_BACKOFF_CAP_MS)
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+function parseErrorMessage(text: string): string | null {
+  if (!text) return null
+  try {
+    const parsed = JSON.parse(text) as { message?: string; error?: string }
+    if (typeof parsed?.message === 'string') return parsed.message
+    if (typeof parsed?.error === 'string') return parsed.error
+  } catch {
+    /* fall through */
+  }
+  return text.length > 200 ? text.slice(0, 200) : text
+}
+
+let cachedClient: DiscordRestClient | null = null
+
+export function getDiscordRestClient(): DiscordRestClient {
+  if (!cachedClient) cachedClient = new FetchDiscordRestClient()
+  return cachedClient
+}
+
+export function setDiscordRestClient(client: DiscordRestClient | null): void {
+  cachedClient = client
+}

package/src/modules/channel_discord/lib/failure-reason.ts

@@ -0,0 +1,49 @@
+/**
+ * Turn an arbitrary thrown value into a one-line reason that is safe to persist
+ * and render.
+ *
+ * The AI auto-reply marker stores this on `channelState` and the settings page
+ * renders it, so the string leaves the log and enters the product. An upstream
+ * provider error is not a curated message: an HTTP client that echoes the failing
+ * URL, or an SDK that quotes the Authorization header, would put a live
+ * credential in a JSONB column and on an operator's screen. Redacting is cheap;
+ * discovering later that a bot token is sitting in `channel_state` is not.
+ *
+ * The patterns are deliberately broad-but-anchored — a false positive costs one
+ * unreadable fragment of a diagnostic, a false negative costs a leaked secret.
+ */
+const SECRET_PATTERNS: readonly RegExp[] = [
+  // `Authorization: Bot <token>` / `Bearer <token>`, however it is spelled.
+  /\b(?:Bot|Bearer|Basic|token|api[_-]?key|secret|password)\b\s*[:=]?\s*['"]?[A-Za-z0-9._~+/=-]{8,}['"]?/gi,
+  // Discord bot tokens and JWT-shaped values: three dot-separated base64url runs.
+  /\b[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{20,}\b/g,
+  // Provider API keys that announce themselves with a prefix.
+  /\b(?:sk|pk|rk)-[A-Za-z0-9_-]{16,}\b/g,
+  // Anything carried in a query string, which is where URLs hide credentials.
+  /([?&](?:access_token|token|key|api[_-]?key|secret|signature|sig)=)[^&\s]+/gi,
+]
+
+const REDACTED = '[redacted]'
+
+export function redactSecrets(text: string): string {
+  return SECRET_PATTERNS.reduce(
+    // Only the query-string pattern captures a group. `String.replace` passes the
+    // match offset in that slot for the patterns that do not, so the type check is
+    // load-bearing — without it a redacted value comes back stamped with a number.
+    (current, pattern) => current.replace(pattern, (_match, group: unknown) => (
+      typeof group === 'string' ? `${group}${REDACTED}` : REDACTED
+    )),
+    text,
+  )
+}
+
+/**
+ * A one-line, operator-readable reason naming the agent that failed — which is
+ * the first thing someone staring at a silent channel needs to know — with the
+ * upstream message redacted and its stack left behind.
+ */
+export function describeAgentFailure(agentId: string, err: unknown): string {
+  const raw = err instanceof Error ? err.message : String(err)
+  const firstLine = raw.split('\n', 1)[0]?.trim() || 'unknown error'
+  return `agent ${agentId}: ${redactSecrets(firstLine)}`
+}

package/src/modules/channel_discord/lib/gateway-bridge.ts

@@ -0,0 +1,79 @@
+import type { InboundMessage } from '@open-mercato/core/modules/communication_channels/lib/adapter'
+import type { InboundProcessorPayload } from '@open-mercato/core/modules/communication_channels/workers/inbound-processor'
+import type { ReactionInboundJob } from '@open-mercato/core/modules/communication_channels/lib/reaction-processor-types'
+import type { DiscordMessageObject } from './discord-rest'
+import { getDiscordChannelAdapter } from './adapter'
+import { isAuthoredByBot } from './normalize-inbound'
+import { DISCORD_CONVERSATION_PREFIX } from './normalize-inbound'
+
+export interface GatewayChannelScope {
+  channelId: string
+  channelType: string
+  tenantId: string
+  organizationId: string | null
+}
+
+/**
+ * Build the hub inbound-processor job for a `MESSAGE_CREATE` gateway event.
+ *
+ * Returns `null` when the message was authored by the bot itself — this is the
+ * feedback-loop guard the spec requires (the bot must never ingest + answer its
+ * own outbound messages). The hub then dedups by `(channel_id, external_message_id)`.
+ *
+ * The raw Discord object is wrapped as an `InboundMessage` so the existing
+ * `inbound-processor` worker calls `adapter.normalizeInbound` exactly as it does
+ * for the webhook path — no hub change.
+ */
+export function buildInboundMessageJob(input: {
+  message: DiscordMessageObject
+  channel: GatewayChannelScope
+  botUserId: string | undefined
+}): InboundProcessorPayload | null {
+  const { message, channel, botUserId } = input
+  if (isAuthoredByBot(message, botUserId)) return null
+
+  const raw: InboundMessage = {
+    raw: { discordMessage: message as unknown as Record<string, unknown> },
+    eventType: 'message',
+  }
+  return {
+    providerKey: 'discord',
+    channelId: channel.channelId,
+    channelType: channel.channelType,
+    raw,
+    scope: { tenantId: channel.tenantId, organizationId: channel.organizationId },
+  }
+}
+
+/**
+ * Build the hub reaction-processor job for a `MESSAGE_REACTION_ADD/REMOVE`
+ * gateway event. Returns `null` for reactions the bot itself added. The reaction
+ * is normalized through the adapter so it matches the webhook reaction path.
+ */
+export async function buildReactionJob(input: {
+  reaction: Record<string, unknown>
+  action: 'added' | 'removed'
+  channel: GatewayChannelScope
+  botUserId: string | undefined
+}): Promise<ReactionInboundJob | null> {
+  const { reaction, action, channel, botUserId } = input
+  const reactionUserId = typeof reaction.user_id === 'string' ? reaction.user_id : undefined
+  if (botUserId && reactionUserId === botUserId) return null
+
+  const event = await getDiscordChannelAdapter().normalizeInboundReaction({
+    raw: { discordReaction: { ...reaction, action } },
+    eventType: 'reaction',
+  })
+
+  return {
+    kind: 'inbound',
+    providerKey: 'discord',
+    channelId: channel.channelId,
+    channelType: channel.channelType,
+    event,
+    scope: { tenantId: channel.tenantId, organizationId: channel.organizationId },
+    attempt: 1,
+  }
+}
+
+export { DISCORD_CONVERSATION_PREFIX }

package/src/modules/channel_discord/lib/health.ts

@@ -0,0 +1,55 @@
+import type { IntegrationScope } from '@open-mercato/shared/modules/integrations/types'
+import { discordCredentialsSchema } from './credentials'
+import { DiscordApiError, getDiscordRestClient } from './discord-rest'
+
+export type HealthCheckStatus = 'healthy' | 'degraded' | 'unhealthy'
+
+export interface HealthCheckResult {
+  status: HealthCheckStatus
+  message?: string
+  details?: Record<string, unknown>
+}
+
+/**
+ * Liveness probe for the Discord integration. The hub resolves it by the service
+ * name declared in `integration.ts` (`channelDiscordHealthCheck`) and passes the
+ * tenant-scoped `IntegrationCredentials` blob (the bot token + ids).
+ *
+ * The bot token is enough for a real probe: we call `GET /users/@me`. A clean
+ * response is `healthy`; a `401` (revoked/invalid token) is `unhealthy` with an
+ * actionable reason; any other failure is `unhealthy`.
+ */
+export const channelDiscordHealthCheck = {
+  async check(
+    credentials: Record<string, unknown> | null,
+    _scope: IntegrationScope,
+  ): Promise<HealthCheckResult> {
+    const parsed = discordCredentialsSchema.safeParse(credentials ?? {})
+    if (!parsed.success) {
+      const first = parsed.error.issues[0]
+      return {
+        status: 'unhealthy',
+        message: `Discord credentials invalid: ${first?.message ?? 'unknown validation error'}`,
+        details: { reason: 'invalid_credentials' },
+      }
+    }
+    try {
+      const user = await getDiscordRestClient().getCurrentUser({ botToken: parsed.data.botToken })
+      return {
+        status: 'healthy',
+        message: 'Discord bot token valid',
+        details: { botUserId: user.id, botUsername: user.username },
+      }
+    } catch (error) {
+      const status = error instanceof DiscordApiError ? error.status : 0
+      const reason = status === 401 ? 'invalid_token' : 'discord_probe_failed'
+      const raw = error instanceof Error ? error.message : 'Discord probe failed'
+      const message = raw.replace(/^\[internal\]\s*/, '')
+      return {
+        status: 'unhealthy',
+        message: status === 401 ? 'Discord bot token rejected (401)' : `Discord probe failed: ${message}`,
+        details: { reason, status },
+      }
+    }
+  },
+}