suaveplan/openspec/archive/2026-05-18-add-discord-client/proposal.md

Add @suaveplan/discord-client

Package: @suaveplan/discord-client Status: PROPOSED Type: new-package

Why

Genesis needs a Discord transport for operations notifications, bot-driven workflows, and webhook-based delivery from server-side jobs. The upstream package at ../suaveplan/packages/universal/discord-client/ covers bot-token messaging plus webhook delivery, but it bakes in globalThis.fetch and Date.now, throws BaseError from a parallel error hierarchy, and ships no OpenTelemetry instruments. Migrating into genesis re-grounds it on SuaveplanError + defineCodes, makes fetch/clock injectable for deterministic testing, and wires OTel counters and histograms so every Discord request is observable from day one.

What changes

• ADDED: @suaveplan/discord-client package at packages/messaging/discord-client/.
• ADDED: DiscordBotClient — bot-token client with sendMessage, editMessage, deleteMessage, getChannel, getGuild, createReaction, getStoredMessage.
• ADDED: DiscordWebhook — webhook-URL delivery with send, sendText, sendEmbed returning DiscordDeliveryReport.
• ADDED: DISCORD_CODES frozen registry with 11 codes namespaced DISCORD.*.
• ADDED: DiscordClientError extends SuaveplanError<DiscordClientCode>.
• ADDED: executeDiscordRequest — shared HTTP funnel emitting discord_client.request.total (Counter) and discord_client.request.duration_ms (Histogram).
• ADDED: parseRetryAfterMs — header parser for Discord's three rate-limit headers.
• ADDED: Zod boundary schemas (DiscordBotConfigSchema, DiscordWebhookConfigSchema, DiscordMessageSchema).
• ADDED: FetchLike injectable contract on every public client.

Out of scope

• Gateway / WebSocket support — bot REST + webhooks only, matching upstream parity.
• File / attachment uploads — upstream does not implement them.
• Slash-command registration — separate concern, future change.

Source mapping

This change derives from ../suaveplan/enterprise/discord-client.md and the upstream implementation at ../suaveplan/packages/universal/discord-client/.

Requirement	Source lines	Notes
Generic Discord API client for webhooks, bot messaging, embeds	enterprise/discord-client.md L10-L13	one-line purpose verbatim
Zero browser/Node/React deps — runs in Bun, Node, browser	enterprise/discord-client.md L37	enforced via FetchLike injectable
Zod schemas for all public types	enterprise/discord-client.md L38	wired at every constructor + every send/sendMessage
Deterministic behaviour — injectable clock, no module-scope Date.now()	enterprise/discord-client.md L40	Clock injectable
OpenTelemetry instrumentation for all public entrypoints	enterprise/discord-client.md L41	counter + histogram in utils/http.ts
Structured errors with stable codes	enterprise/discord-client.md L42	DISCORD_CODES + DiscordClientError
AbortSignal everywhere async	enterprise/discord-client.md L43	AbortController per request
No mocks; real services via deterministic injectables	enterprise/discord-client.md L53	FetchLike, Clock stubs in tests
sideEffects: false	enterprise/discord-client.md L55	declared in package.json
workspace:* internal, Bun catalog external	enterprise/discord-client.md L56	enforced by tests/dep-graph.test.ts
TypeScript strict — no any, no ts-ignore	enterprise/discord-client.md L59	inherited from tsconfig.base.json
Public API stability — Zod boundary schemas	enterprise/discord-client.md L60	three schemas at every public boundary
Error hierarchy — extends @suaveplan/error	enterprise/discord-client.md L61	DiscordClientError extends SuaveplanError
Bot REST surface: send/edit/delete/getChannel/createReaction	upstream src/core/discord-bot-client/discord-bot-client.ts L75-L130	reimplemented fresh
Webhook surface: send, sendText, sendEmbed, threaded routing	upstream src/core/discord-webhook/discord-webhook.ts L81-L105	reimplemented fresh
Discord rate-limit header parsing (3 header variants)	upstream src/core/discord-bot-client/discord-bot-client.ts L26-L48	extracted to utils/rate-limit.ts
401/403/404/429/non-ok response → DISCORD code mapping	upstream src/core/discord-bot-client/discord-bot-client.ts L167-L215	concentrated in utils/http.ts
DiscordDeliveryReport for webhook responses	upstream src/types/discord-client.types.ts L86-L97	shape preserved

Requirements with no source line

Requirement	Justification
100% Istanbul coverage threshold	Genesis-wide policy, not package-specific
### DISCORD-NN — requirement heading format	OpenSpec conformance contract (openspec-conformance.ts regex)
**Verified by:** lines at draft time	Genesis OpenSpec migration skill mandate
Zod parse failure → DISCORD.INVALID_CONFIG vs DISCORD.CONFIG_MISSING split	Required so the registry's severity: fatal vs severity: error mapping is callable
OTel histogram alongside the counter	Genesis observability convention (matches @suaveplan/webhook-client)

Verification approach

• src/errors/discord-client-error.test.ts — covers DISCORD-01 (error-code registry).
• src/utils/rate-limit.test.ts — covers DISCORD-02 (rate-limit header parser).
• src/utils/http.test.ts — covers DISCORD-03 (response→error mapping), DISCORD-04 (timeout + abort), DISCORD-05 (OTel instrumentation with recording MeterProvider).
• src/core/bot-client/discord-bot-client.test.ts — covers DISCORD-06 (bot REST surface), DISCORD-07 (Zod config validation), DISCORD-08 (in-memory message cache).
• src/core/webhook/discord-webhook.test.ts — covers DISCORD-09 (webhook delivery + report), DISCORD-10 (webhook Zod boundary + URL host check).
• tests/dep-graph.test.ts — pins runtime dep set and sideEffects: false.

Migration impact

None — additive only. No consumer of @suaveplan/discord-client exists yet in genesis.