@andreprado/agentkit 0.1.0-alpha.9 → 0.1.0

package/src/runtime/channels/discord.ts

@@ -0,0 +1,896 @@
+import type {
+  ChannelAdapter,
+  ChannelReplyTarget,
+  ChannelSendInput,
+  ChannelSendResult,
+  NormalizedChannelEvent,
+  RawWebhookEvent,
+  WebhookVerificationResult,
+} from "../channels";
+import { AgentKitError } from "../errors";
+
+const DISCORD_INTERACTION_PING = 1;
+const DISCORD_INTERACTION_APPLICATION_COMMAND = 2;
+const DISCORD_API_BASE_URL = "https://discord.com/api/v10";
+
+export const discordChannelAdapter: ChannelAdapter = {
+  type: "discord",
+  provider: "discord",
+  requiredSecrets: ["DISCORD_PUBLIC_KEY"],
+  async verifyWebhook(input): Promise<WebhookVerificationResult> {
+    return verifyDiscordWebhook(input);
+  },
+  getWebhookResponse(input) {
+    if (!isDiscordPingInteraction(input.rawBody)) {
+      return null;
+    }
+
+    return {
+      body: { type: 1 },
+    };
+  },
+  normalizeInbound(input) {
+    const body = parseJsonObject(input);
+    const interactionId = readString(body, "id");
+    const applicationId = readString(body, "application_id");
+    const interactionType = readNumber(body, "type");
+    const interactionToken = readString(body, "token");
+
+    if (interactionType === DISCORD_INTERACTION_PING) {
+      return [];
+    }
+
+    if (!interactionId) {
+      throw new AgentKitError("channel_payload_invalid", "Discord interaction payload is missing id.");
+    }
+
+    const identity = normalizeDiscordIdentity(body);
+    const base = {
+      type: "discord" as const,
+      provider: "discord" as const,
+      providerEventId: interactionId,
+      dedupeKey: `discord:${input.channelId}:${interactionId}`,
+      externalIdentity: identity,
+      receivedAt: input.receivedAt,
+      providerMetadata: {
+        interactionType,
+        ...(readString(body, "guild_id") ? { guildId: readString(body, "guild_id") } : {}),
+        ...(readString(body, "channel_id") ? { channelId: readString(body, "channel_id") } : {}),
+      },
+    };
+
+    if (interactionType !== DISCORD_INTERACTION_APPLICATION_COMMAND) {
+      return [
+        {
+          ...base,
+          kind: "unsupported",
+          unsupportedReason: `unsupported_interaction_type:${interactionType ?? "unknown"}`,
+        },
+      ];
+    }
+
+    if (!applicationId || !interactionToken) {
+      throw new AgentKitError(
+        "channel_payload_invalid",
+        "Discord application command payload is missing application_id or token.",
+      );
+    }
+
+    const data = readRecord(body, "data");
+    const commandName = readString(data, "name");
+    const content = normalizeDiscordCommandContent(data);
+    const replyTarget: ChannelReplyTarget = {
+      type: "discord_interaction",
+      applicationId,
+      interactionId,
+      interactionToken,
+    };
+
+    return [
+      {
+        ...base,
+        kind: "message",
+        replyTarget,
+        providerMetadata: {
+          ...base.providerMetadata,
+          ...(commandName ? { commandName } : {}),
+        },
+        message: {
+          role: "user",
+          contentType: "text",
+          content,
+          providerMessageId: interactionId,
+        },
+      },
+    ];
+  },
+  async sendMessage(input) {
+    return sendDiscordMessage(input);
+  },
+  getStatus(input) {
+    const channelMode = input.channel.type === "discord" && input.channel.mode === "bot" ? "bot" : "interactions";
+
+    if (channelMode === "bot") {
+      if (!input.secrets.DISCORD_BOT_TOKEN) {
+        return {
+          status: "needs_setup",
+          checkedAt: new Date().toISOString(),
+          message: "Secret DISCORD_BOT_TOKEN is missing.",
+        };
+      }
+
+      return {
+        status: "waiting_for_provider_event",
+        checkedAt: new Date().toISOString(),
+        message: "Invite the Discord bot to a server and enable Message Content Intent.",
+      };
+    }
+
+    if (!input.secrets.DISCORD_PUBLIC_KEY) {
+      return {
+        status: "needs_setup",
+        checkedAt: new Date().toISOString(),
+        message: "Secret DISCORD_PUBLIC_KEY is missing.",
+      };
+    }
+
+    return {
+      status: "waiting_for_provider_event",
+      checkedAt: new Date().toISOString(),
+      message: "Paste the AgentKit webhook URL into the Discord app Interactions Endpoint URL.",
+    };
+  },
+};
+
+export type DiscordFollowupMessageRequest = {
+  method: "POST";
+  url: string;
+  body: {
+    content: string;
+    allowed_mentions: {
+      parse: string[];
+    };
+  };
+  idempotencyKey: string;
+};
+
+export type DiscordBotMessageRequest = {
+  method: "POST";
+  url: string;
+  headers: {
+    Authorization: string;
+    "Content-Type": "application/json";
+  };
+  body: {
+    content: string;
+    allowed_mentions: {
+      parse: string[];
+    };
+    message_reference: {
+      message_id: string;
+      channel_id: string;
+    };
+  };
+  idempotencyKey: string;
+};
+
+export type DiscordGatewayMessageCreateInput = {
+  channelId: string;
+  receivedAt: string;
+  payload: Record<string, unknown>;
+  botUserId?: string;
+};
+
+type DiscordFetch = (url: string, init: RequestInit) => Promise<Response>;
+
+export function isDiscordPingInteraction(rawBody: string): boolean {
+  try {
+    const parsed = JSON.parse(rawBody) as unknown;
+    return isRecord(parsed) && parsed.type === DISCORD_INTERACTION_PING;
+  } catch {
+    return false;
+  }
+}
+
+export function buildDiscordFollowupMessageRequest(input: ChannelSendInput): DiscordFollowupMessageRequest {
+  return buildDiscordFollowupMessageRequestInternal(input, {
+    redactToken: true,
+  });
+}
+
+export function buildDiscordBotMessageRequest(input: ChannelSendInput): DiscordBotMessageRequest {
+  return buildDiscordBotMessageRequestInternal(input, {
+    redactToken: true,
+  });
+}
+
+export function normalizeDiscordGatewayMessageCreate(
+  input: DiscordGatewayMessageCreateInput,
+): NormalizedChannelEvent[] {
+  const payload = input.payload;
+  const messageId = readString(payload, "id");
+  const discordChannelId = readString(payload, "channel_id");
+  const author = readRecord(payload, "author");
+  const authorId = readString(author, "id");
+  const content = readGatewayMessageContent(payload);
+
+  if (!messageId || !discordChannelId) {
+    throw new AgentKitError("channel_payload_invalid", "Discord MESSAGE_CREATE payload is missing id or channel_id.");
+  }
+
+  if (readBoolean(author, "bot") || (input.botUserId && authorId === input.botUserId)) {
+    return [];
+  }
+
+  const identity = normalizeDiscordMessageIdentity(payload);
+  const base = {
+    type: "discord" as const,
+    provider: "discord" as const,
+    providerEventId: messageId,
+    dedupeKey: `discord:${input.channelId}:${messageId}`,
+    externalIdentity: identity,
+    receivedAt: input.receivedAt,
+    providerMetadata: {
+      gatewayEvent: "MESSAGE_CREATE",
+      ...(readString(payload, "guild_id") ? { guildId: readString(payload, "guild_id") } : {}),
+      channelId: discordChannelId,
+    },
+  };
+
+  if (!content) {
+    return [
+      {
+        ...base,
+        kind: "unsupported",
+        unsupportedReason: "missing_or_empty_message_content",
+      },
+    ];
+  }
+
+  return [
+    {
+      ...base,
+      kind: "message",
+      replyTarget: {
+        type: "discord_message",
+        channelId: discordChannelId,
+        messageId,
+      },
+      message: {
+        role: "user",
+        contentType: "text",
+        content,
+        providerMessageId: messageId,
+      },
+    },
+  ];
+}
+
+export async function sendDiscordMessage(
+  input: ChannelSendInput,
+  fetcher: DiscordFetch = fetch,
+): Promise<ChannelSendResult> {
+  if (input.replyTarget?.type === "discord_interaction") {
+    return sendDiscordInteractionFollowup(input, fetcher);
+  }
+
+  if (input.replyTarget?.type !== "discord_message") {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_send_failed",
+      message: "Discord sendMessage requires a Discord interaction or message reply target.",
+    };
+  }
+
+  if (input.secrets.AGENTKIT_CHANNEL_SEND_DRY_RUN === "1") {
+    try {
+      const request = buildDiscordBotMessageRequest(input);
+
+      return {
+        ok: true,
+        status: "stubbed",
+        providerRequestId: request.idempotencyKey,
+        providerMetadata: {
+          method: request.method,
+          url: request.url,
+          headers: request.headers,
+          body: request.body,
+        },
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        retryable: false,
+        code: "channel_send_failed",
+        message: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  let request: DiscordBotMessageRequest;
+  let actualRequest: DiscordBotMessageRequest;
+
+  try {
+    request = buildDiscordBotMessageRequest(input);
+    actualRequest = buildDiscordBotMessageRequestInternal(input, {
+      redactToken: false,
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: false,
+      code: error instanceof AgentKitError && error.code === "channel_secret_missing"
+        ? "channel_secret_missing"
+        : "channel_send_failed",
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  let response: Response;
+
+  try {
+    response = await fetcher(actualRequest.url, {
+      method: actualRequest.method,
+      headers: actualRequest.headers,
+      body: JSON.stringify(actualRequest.body),
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: true,
+      code: "channel_provider_unavailable",
+      message: `Discord bot message request failed before a response: ${redactDiscordToken(
+        error instanceof Error ? error.message : String(error),
+        input.secrets.DISCORD_BOT_TOKEN,
+      )}`,
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        headers: request.headers,
+        body: request.body,
+      },
+    };
+  }
+
+  const payload = await response.json().catch(() => null);
+  const messageId = isRecord(payload) ? readString(payload, "id") : undefined;
+
+  if (!response.ok) {
+    return {
+      ok: false,
+      retryable: response.status === 429 || response.status >= 500,
+      code: "channel_send_failed",
+      message: redactDiscordToken(readDiscordErrorMessage(payload, response.status), input.secrets.DISCORD_BOT_TOKEN),
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        headers: request.headers,
+        status: response.status,
+        body: redactDiscordValue(payload, input.secrets.DISCORD_BOT_TOKEN),
+      },
+    };
+  }
+
+  if (!messageId) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_send_failed",
+      message: "Discord bot message response did not return id.",
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        headers: request.headers,
+        status: response.status,
+        body: redactDiscordValue(payload, input.secrets.DISCORD_BOT_TOKEN),
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    status: "sent",
+    providerRequestId: request.idempotencyKey,
+    providerMessageId: messageId,
+    providerMetadata: {
+      method: request.method,
+      url: request.url,
+      headers: request.headers,
+      status: response.status,
+      body: redactDiscordValue(payload, input.secrets.DISCORD_BOT_TOKEN),
+    },
+  };
+}
+
+export async function sendDiscordInteractionFollowup(
+  input: ChannelSendInput,
+  fetcher: DiscordFetch = fetch,
+): Promise<ChannelSendResult> {
+  const replyTarget = input.replyTarget;
+
+  if (replyTarget?.type !== "discord_interaction") {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_send_failed",
+      message: "Discord follow-up send requires a Discord interaction reply target.",
+    };
+  }
+
+  if (input.secrets.AGENTKIT_CHANNEL_SEND_DRY_RUN === "1") {
+    const request = buildDiscordFollowupMessageRequest(input);
+
+    return {
+      ok: true,
+      status: "stubbed",
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  let request: DiscordFollowupMessageRequest;
+  let actualRequest: DiscordFollowupMessageRequest;
+
+  try {
+    request = buildDiscordFollowupMessageRequest(input);
+    actualRequest = buildDiscordFollowupMessageRequestInternal(input, {
+      redactToken: false,
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_send_failed",
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  let response: Response;
+
+  try {
+    response = await fetcher(actualRequest.url, {
+      method: actualRequest.method,
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(actualRequest.body),
+    });
+  } catch (error) {
+    return {
+      ok: false,
+      retryable: true,
+      code: "channel_provider_unavailable",
+      message: `Discord follow-up request failed before a response: ${redactDiscordToken(
+        error instanceof Error ? error.message : String(error),
+        replyTarget.interactionToken,
+      )}`,
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        body: request.body,
+      },
+    };
+  }
+
+  const payload = await response.json().catch(() => null);
+  const messageId = isRecord(payload) ? readString(payload, "id") : undefined;
+
+  if (!response.ok) {
+    return {
+      ok: false,
+      retryable: response.status === 429 || response.status >= 500,
+      code: "channel_send_failed",
+      message: redactDiscordToken(readDiscordErrorMessage(payload, response.status), replyTarget.interactionToken),
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        status: response.status,
+        body: redactDiscordValue(payload, replyTarget.interactionToken),
+      },
+    };
+  }
+
+  if (!messageId) {
+    return {
+      ok: false,
+      retryable: false,
+      code: "channel_send_failed",
+      message: "Discord follow-up response did not return id.",
+      providerRequestId: request.idempotencyKey,
+      providerMetadata: {
+        method: request.method,
+        url: request.url,
+        status: response.status,
+        body: redactDiscordValue(payload, replyTarget.interactionToken),
+      },
+    };
+  }
+
+  return {
+    ok: true,
+    status: "sent",
+    providerRequestId: request.idempotencyKey,
+    providerMessageId: messageId,
+    providerMetadata: {
+      method: request.method,
+      url: request.url,
+      status: response.status,
+      body: redactDiscordValue(payload, replyTarget.interactionToken),
+    },
+  };
+}
+
+async function verifyDiscordWebhook(input: {
+  headers: Headers;
+  rawBody: string;
+  secrets: Record<string, string>;
+}): Promise<WebhookVerificationResult> {
+  const publicKey = input.secrets.DISCORD_PUBLIC_KEY;
+
+  if (!publicKey) {
+    return {
+      ok: false,
+      code: "channel_secret_missing",
+      message: "Secret DISCORD_PUBLIC_KEY is not set for this channel.",
+    };
+  }
+
+  const signature = input.headers.get("x-signature-ed25519");
+  const timestamp = input.headers.get("x-signature-timestamp");
+
+  if (!signature || !timestamp) {
+    return {
+      ok: false,
+      code: "channel_signature_invalid",
+      message: "Discord signature headers are missing.",
+    };
+  }
+
+  const publicKeyBytes = hexToBytes(publicKey);
+  const signatureBytes = hexToBytes(signature);
+
+  if (!publicKeyBytes || publicKeyBytes.byteLength !== 32 || !signatureBytes || signatureBytes.byteLength !== 64) {
+    return {
+      ok: false,
+      code: "channel_signature_invalid",
+      message: "Discord public key or signature is not valid hex.",
+    };
+  }
+
+  let key: CryptoKey;
+
+  try {
+    key = await crypto.subtle.importKey(
+      "raw",
+      bytesToArrayBuffer(publicKeyBytes),
+      { name: "Ed25519" } as AlgorithmIdentifier,
+      false,
+      ["verify"],
+    );
+  } catch {
+    return {
+      ok: false,
+      code: "channel_signature_invalid",
+      message: "Discord public key could not be imported for Ed25519 verification.",
+    };
+  }
+
+  const signedBody = new TextEncoder().encode(`${timestamp}${input.rawBody}`);
+  const ok = await crypto.subtle.verify(
+    { name: "Ed25519" } as AlgorithmIdentifier,
+    key,
+    bytesToArrayBuffer(signatureBytes),
+    bytesToArrayBuffer(signedBody),
+  );
+
+  if (!ok) {
+    return {
+      ok: false,
+      code: "channel_signature_invalid",
+      message: "Discord request signature did not match.",
+    };
+  }
+
+  return { ok: true };
+}
+
+function buildDiscordFollowupMessageRequestInternal(
+  input: ChannelSendInput,
+  options: { redactToken: boolean },
+): DiscordFollowupMessageRequest {
+  const replyTarget = input.replyTarget;
+
+  if (replyTarget?.type !== "discord_interaction") {
+    throw new Error("Discord sendMessage requires a Discord interaction reply target.");
+  }
+
+  const token = options.redactToken ? "<redacted>" : replyTarget.interactionToken;
+  const baseUrl = input.secrets.AGENTKIT_DISCORD_API_BASE_URL ?? DISCORD_API_BASE_URL;
+  const url = new URL(
+    `/api/v10/webhooks/${encodeURIComponent(replyTarget.applicationId)}/${encodeURIComponent(token)}`,
+    normalizeDiscordApiBaseUrl(baseUrl),
+  );
+
+  return {
+    method: "POST",
+    url: url.href,
+    body: {
+      content: input.message.content,
+      allowed_mentions: {
+        parse: [],
+      },
+    },
+    idempotencyKey: `discord:${input.channelId}:${input.conversationId}:${replyTarget.interactionId}`,
+  };
+}
+
+function buildDiscordBotMessageRequestInternal(
+  input: ChannelSendInput,
+  options: { redactToken: boolean },
+): DiscordBotMessageRequest {
+  const replyTarget = input.replyTarget;
+
+  if (replyTarget?.type !== "discord_message") {
+    throw new Error("Discord bot sendMessage requires a Discord message reply target.");
+  }
+
+  const botToken = input.secrets.DISCORD_BOT_TOKEN;
+
+  if (!botToken) {
+    throw new AgentKitError("channel_secret_missing", "Secret DISCORD_BOT_TOKEN is not set for this channel.");
+  }
+
+  const baseUrl = input.secrets.AGENTKIT_DISCORD_API_BASE_URL ?? DISCORD_API_BASE_URL;
+  const url = new URL(
+    `/api/v10/channels/${encodeURIComponent(replyTarget.channelId)}/messages`,
+    normalizeDiscordApiBaseUrl(baseUrl),
+  );
+
+  return {
+    method: "POST",
+    url: url.href,
+    headers: {
+      Authorization: `Bot ${options.redactToken ? "<redacted>" : botToken}`,
+      "Content-Type": "application/json",
+    },
+    body: {
+      content: input.message.content,
+      allowed_mentions: {
+        parse: [],
+      },
+      message_reference: {
+        message_id: replyTarget.messageId,
+        channel_id: replyTarget.channelId,
+      },
+    },
+    idempotencyKey: `discord:${input.channelId}:${input.conversationId}:${replyTarget.messageId}`,
+  };
+}
+
+function normalizeDiscordApiBaseUrl(value: string): string {
+  const url = new URL(value);
+
+  if (url.pathname.endsWith("/api/v10")) {
+    url.pathname = url.pathname.slice(0, -"/api/v10".length) || "/";
+  }
+
+  return url.href;
+}
+
+function bytesToArrayBuffer(bytes: Uint8Array): ArrayBuffer {
+  const copy = new Uint8Array(bytes.byteLength);
+  copy.set(bytes);
+  return copy.buffer;
+}
+
+function normalizeDiscordIdentity(body: Record<string, unknown>) {
+  const guildId = readString(body, "guild_id") ?? "dm";
+  const channelId = readString(body, "channel_id") ?? "unknown";
+  const member = readRecord(body, "member");
+  const user = readRecord(member, "user");
+  const directUser = readRecord(body, "user");
+  const userId = readString(user, "id") ?? readString(directUser, "id") ?? "unknown";
+  const display =
+    readString(member, "nick") ??
+    readString(user, "global_name") ??
+    readString(user, "username") ??
+    readString(directUser, "global_name") ??
+    readString(directUser, "username");
+
+  return {
+    key: `discord:guild:${guildId}:channel:${channelId}:user:${userId}`,
+    ...(display ? { display } : {}),
+    redactedDisplay: `discord:guild:${redactId(guildId)}:channel:${redactId(channelId)}:user:${redactId(userId)}`,
+  };
+}
+
+function normalizeDiscordMessageIdentity(body: Record<string, unknown>) {
+  const guildId = readString(body, "guild_id") ?? "dm";
+  const channelId = readString(body, "channel_id") ?? "unknown";
+  const member = readRecord(body, "member");
+  const author = readRecord(body, "author");
+  const authorId = readString(author, "id") ?? "unknown";
+  const display =
+    readString(member, "nick") ??
+    readString(author, "global_name") ??
+    readString(author, "username");
+
+  return {
+    key: `discord:guild:${guildId}:channel:${channelId}:user:${authorId}`,
+    ...(display ? { display } : {}),
+    redactedDisplay: `discord:guild:${redactId(guildId)}:channel:${redactId(channelId)}:user:${redactId(authorId)}`,
+  };
+}
+
+function normalizeDiscordCommandContent(data: Record<string, unknown>): string {
+  const commandName = readString(data, "name") ?? "command";
+  const options = readArray(data, "options");
+  const renderedOptions = renderDiscordOptions(options);
+
+  if (renderedOptions.length === 1 && isPrimaryTextOption(renderedOptions[0]?.name)) {
+    return renderedOptions[0]?.value || `/${commandName}`;
+  }
+
+  if (renderedOptions.length === 0) {
+    return `/${commandName}`;
+  }
+
+  return [`/${commandName}`, ...renderedOptions.map((option) => `${option.name}: ${option.value}`)].join("\n");
+}
+
+function renderDiscordOptions(options: unknown[]): Array<{ name: string; value: string }> {
+  const rendered: Array<{ name: string; value: string }> = [];
+
+  for (const option of options) {
+    if (!isRecord(option)) {
+      continue;
+    }
+
+    const name = readString(option, "name") ?? "option";
+    const nested = readArray(option, "options");
+
+    if (nested.length > 0) {
+      for (const item of renderDiscordOptions(nested)) {
+        rendered.push({
+          name: `${name}.${item.name}`,
+          value: item.value,
+        });
+      }
+      continue;
+    }
+
+    const value = option.value;
+
+    if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+      rendered.push({
+        name,
+        value: String(value),
+      });
+    }
+  }
+
+  return rendered;
+}
+
+function isPrimaryTextOption(name: string | undefined): boolean {
+  return Boolean(name && ["message", "text", "prompt", "question", "query", "input"].includes(name));
+}
+
+function parseJsonObject(input: RawWebhookEvent): Record<string, unknown> {
+  try {
+    const parsed = JSON.parse(input.rawBody) as unknown;
+
+    if (isRecord(parsed)) {
+      return parsed;
+    }
+  } catch (error) {
+    throw new AgentKitError("channel_payload_invalid", "Discord interaction payload must be valid JSON.", {
+      cause: error,
+    });
+  }
+
+  throw new AgentKitError("channel_payload_invalid", "Discord interaction payload must be a JSON object.");
+}
+
+function readRecord(value: Record<string, unknown>, key: string): Record<string, unknown> {
+  const record = value[key];
+  return isRecord(record) ? record : {};
+}
+
+function readArray(value: Record<string, unknown>, key: string): unknown[] {
+  const field = value[key];
+  return Array.isArray(field) ? field : [];
+}
+
+function readString(value: Record<string, unknown>, key: string): string | undefined {
+  const field = value[key];
+  return typeof field === "string" && field.length > 0 ? field : undefined;
+}
+
+function readNumber(value: Record<string, unknown>, key: string): number | undefined {
+  const field = value[key];
+  return typeof field === "number" && Number.isFinite(field) ? field : undefined;
+}
+
+function readBoolean(value: Record<string, unknown>, key: string): boolean {
+  return value[key] === true;
+}
+
+function readGatewayMessageContent(value: Record<string, unknown>): string {
+  const content = readString(value, "content");
+  return content?.trim() ?? "";
+}
+
+function readDiscordErrorMessage(payload: unknown, status: number): string {
+  if (isRecord(payload)) {
+    const message = readString(payload, "message");
+
+    if (message) {
+      return message;
+    }
+  }
+
+  return `Discord follow-up request returned HTTP ${status}.`;
+}
+
+function redactDiscordToken(value: string, token: string | undefined): string {
+  return token ? value.replaceAll(token, "<redacted>") : value;
+}
+
+function redactDiscordValue(value: unknown, token: string | undefined): unknown {
+  if (typeof value === "string") {
+    return redactDiscordToken(value, token);
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => redactDiscordValue(item, token));
+  }
+
+  if (isRecord(value)) {
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, redactDiscordValue(item, token)]));
+  }
+
+  return value;
+}
+
+function redactId(value: string): string {
+  if (value === "unknown" || value === "dm") {
+    return value;
+  }
+
+  if (value.length <= 8) {
+    return "*".repeat(value.length);
+  }
+
+  return `${value.slice(0, 4)}******${value.slice(-4)}`;
+}
+
+function hexToBytes(value: string): Uint8Array | null {
+  const normalized = value.trim();
+
+  if (!/^[a-f0-9]+$/i.test(normalized) || normalized.length % 2 !== 0) {
+    return null;
+  }
+
+  const bytes = new Uint8Array(normalized.length / 2);
+
+  for (let index = 0; index < normalized.length; index += 2) {
+    bytes[index / 2] = Number.parseInt(normalized.slice(index, index + 2), 16);
+  }
+
+  return bytes;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}