OpenSpec Change: enterprise-discord-client

Change ID: enterprise-discord-client
Package: @suaveplan/discord-client
Category: universal
Target path: universal/social/discord-client
Status: IN PROGRESS
Date: 2026-04-24
Reference spec: /mnt/s/web/suaveplan/enterprise/discord-client.md

Summary

Deliver @suaveplan/discord-client on the genesis branch from scratch at enterprise quality. The package provides a generic Discord API client: Webhook-based message delivery (text, embeds, files), Bot REST API wrappers for channel messaging, guild info, member lookups, message reactions, thread management, Slash-command interaction responses, Component interaction acknowledgement, and a DiscordClient facade. Injectable fetch; no discord.js dependency. Genesis adds structured errors, Zod schemas, OTel instrumentation, retry with circuit breaker, rate-limit awareness (per-route bucket tracking), and AbortSignal cancellation.

Current-state audit (genesis)

The package does not exist on genesis yet — this is a fresh build.

Available workspace deps on genesis

Package	Role
`@suaveplan/error` (`workspace:^`)	`DiscordError`; `DISCORD.*` error codes
`@suaveplan/types` (`workspace:^`)	`LoggerLike`, `Clock`
`@suaveplan/retry` (`workspace:^`)	Retry + circuit breaker for API calls
`@suaveplan/crypto` (`workspace:^`)	Ed25519 interaction signature verification
`zod` (`catalog:forms`)	Schema validation
`@opentelemetry/api` (`catalog:observability`)	Spans + counters

Dev deps: vitest, @vitest/coverage-istanbul, fast-check (all catalog:testing).

Public API surface

`DiscordClient`

class DiscordClient {
  constructor(options: DiscordClientOptions)

  // Webhooks
  sendWebhook(webhookUrl: string, payload: WebhookPayload): Promise<DiscordMessage>
  executeWebhook(options: ExecuteWebhookOptions): Promise<DiscordMessage>

  // Messages
  sendMessage(channelId: string, payload: MessagePayload): Promise<DiscordMessage>
  editMessage(channelId: string, messageId: string, payload: MessagePayload): Promise<DiscordMessage>
  deleteMessage(channelId: string, messageId: string): Promise<void>
  addReaction(channelId: string, messageId: string, emoji: string): Promise<void>

  // Channels / Threads
  getChannel(channelId: string): Promise<DiscordChannel>
  createThread(channelId: string, messageId: string, options: ThreadOptions): Promise<DiscordChannel>

  // Guild / Members
  getGuild(guildId: string): Promise<DiscordGuild>
  getMember(guildId: string, userId: string): Promise<DiscordMember>
}

interface DiscordClientOptions {
  token: string
  applicationId?: string
  publicKey?: string      // Ed25519 public key for interaction verification
  retryOptions?: RetryOptions
  fetch?: typeof globalThis.fetch
  clock?: Clock
  logger?: LoggerLike
}

Embed builder

function createEmbed(): EmbedBuilder
interface EmbedBuilder {
  title(text: string): EmbedBuilder
  description(text: string): EmbedBuilder
  color(hex: number): EmbedBuilder
  field(name: string, value: string, inline?: boolean): EmbedBuilder
  footer(text: string, iconUrl?: string): EmbedBuilder
  thumbnail(url: string): EmbedBuilder
  image(url: string): EmbedBuilder
  timestamp(date?: Date): EmbedBuilder
  build(): DiscordEmbed
}

Interaction handling

function verifyDiscordInteraction(
  body: string,
  signature: string,
  timestamp: string,
  publicKey: string
): Promise<boolean>

function parseInteraction(body: unknown): DiscordInteraction

Error codes

type DiscordErrorCode =
  | 'DISCORD_AUTH_FAILED'
  | 'DISCORD_API_ERROR'
  | 'DISCORD_RATE_LIMITED'
  | 'DISCORD_SIGNATURE_INVALID'
  | 'DISCORD_CHANNEL_NOT_FOUND'
  | 'DISCORD_MESSAGE_NOT_FOUND'
  | 'DISCORD_ABORTED'

Genesis additions

DiscordError extends SuaveplanError with seven stable codes.
Zod schemas for MessagePayload, WebhookPayload, DiscordEmbed, DiscordMessage, DiscordInteraction, DiscordChannel, DiscordGuild, DiscordMember.
Per-route rate-limit bucket tracking — parses X-RateLimit-* response headers and enforces bucket-level backoff before the next request on the same route.
Ed25519 interaction verification — delegates to @suaveplan/crypto's ed25519.verify for interaction signature verification.
OTel instrumentation — span discord.api_call with attribute discord.endpoint; counter discord.api_total; histogram discord.api_duration_ms.
Property-based tests — Embed builder produces valid JSON for arbitrary chained calls; rate-limit bucket parser correctly handles all header combinations.

File layout

universal/social/discord-client/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    error-codes.ts
    constants/
      index.ts
    types/
      common.ts
      common.md
    core/
      discord-client/
        discord-client.ts
        discord-client.md
        discord-client.types.ts
        discord-client.test.ts
        index.ts
      api-caller/
        api-caller.ts
        api-caller.md
        api-caller.test.ts
        index.ts
      rate-limiter/
        rate-limiter.ts
        rate-limiter.md
        rate-limiter.test.ts
        index.ts
    embeds/
      embed-builder/
        embed-builder.ts
        embed-builder.md
        embed-builder.test.ts
        index.ts
    interactions/
      interaction-verifier/
        interaction-verifier.ts
        interaction-verifier.md
        interaction-verifier.test.ts
        index.ts
      interaction-parser/
        interaction-parser.ts
        interaction-parser.md
        interaction-parser.test.ts
        index.ts
    __benchmarks__/
      discord-client.bench.ts
  tests/
    integration.test.ts
    property.test.ts

Impact

Downstream consumers: @suaveplan/message-bridge, @suaveplan/notification-channel.

Workspace dep prerequisites: @suaveplan/error, @suaveplan/types, @suaveplan/retry, @suaveplan/crypto.

6.0 KiB Raw Permalink Blame History