@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/internal/rest.ts

@@ -0,0 +1,322 @@
+import { randomBytes } from "node:crypto";
+import { inspect } from "node:util";
+import { serializeRequestBody } from "./rest-body.js";
+import {
+  DiscordError,
+  RateLimitError,
+  readDiscordCode,
+  readDiscordMessage,
+  readRetryAfter,
+} from "./rest-errors.js";
+import { appendQuery, createRouteKey } from "./rest-routes.js";
+import {
+  RestScheduler,
+  type RequestPriority as RestRequestPriority,
+  type RequestQuery,
+} from "./rest-scheduler.js";
+import { isDiscordRateLimitBody } from "./schemas.js";
+
+export { DiscordError, RateLimitError } from "./rest-errors.js";
+
+export type RuntimeProfile = "serverless" | "persistent";
+export type RequestPriority = RestRequestPriority;
+export type RequestSchedulerOptions = {
+  lanes?: Partial<
+    Record<RequestPriority, { maxQueueSize?: number; staleAfterMs?: number; weight?: number }>
+  >;
+  maxConcurrency?: number;
+  maxRateLimitRetries?: number;
+};
+
+export type RequestClientOptions = {
+  tokenHeader?: "Bot" | "Bearer";
+  baseUrl?: string;
+  apiVersion?: number;
+  userAgent?: string;
+  timeout?: number;
+  queueRequests?: boolean;
+  maxQueueSize?: number;
+  runtimeProfile?: RuntimeProfile;
+  scheduler?: RequestSchedulerOptions;
+  fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+};
+
+export type RequestData = {
+  body?: unknown;
+  multipartStyle?: "message" | "form";
+  rawBody?: boolean;
+  headers?: Record<string, string>;
+};
+
+export type QueuedRequest = {
+  method: string;
+  path: string;
+  data?: RequestData;
+  query?: RequestQuery;
+  resolve: (value?: unknown) => void;
+  reject: (reason?: unknown) => void;
+  routeKey: string;
+};
+
+const defaultOptions = {
+  tokenHeader: "Bot" as const,
+  baseUrl: "https://discord.com/api",
+  apiVersion: 10,
+  userAgent: "Klaw Discord",
+  timeout: 15_000,
+  queueRequests: true,
+  maxQueueSize: 1000,
+  runtimeProfile: "persistent" as RuntimeProfile,
+};
+
+const DEFAULT_MAX_CONCURRENT_WORKERS = 4;
+const defaultLaneOptions: Record<RestRequestPriority, { staleAfterMs?: number; weight: number }> = {
+  critical: { weight: 6 },
+  standard: { weight: 3 },
+  background: { staleAfterMs: 20_000, weight: 1 },
+};
+
+function coerceResponseBody(raw: string): unknown {
+  if (!raw) {
+    return undefined;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+}
+
+function escapeMultipartQuotedValue(value: string): string {
+  return value.replace(/["\r\n]/g, (ch) => (ch === '"' ? "%22" : ch === "\r" ? "%0D" : "%0A"));
+}
+
+async function formDataToMultipartBody(body: FormData, headers: Headers): Promise<BodyInit> {
+  const boundary = `----klaw-discord-${randomBytes(12).toString("hex")}`;
+  headers.set("Content-Type", `multipart/form-data; boundary=${boundary}`);
+  const chunks: Buffer[] = [];
+  const push = (value: string | Buffer) => {
+    chunks.push(typeof value === "string" ? Buffer.from(value) : value);
+  };
+  for (const [key, value] of body.entries()) {
+    push(`--${boundary}\r\n`);
+    const escapedKey = escapeMultipartQuotedValue(key);
+    if (typeof value === "string") {
+      push(`Content-Disposition: form-data; name="${escapedKey}"\r\n\r\n`);
+      push(value);
+      push("\r\n");
+      continue;
+    }
+    const filename = (value as Blob & { name?: unknown }).name;
+    const escapedFilename = escapeMultipartQuotedValue(
+      typeof filename === "string" && filename.length > 0 ? filename : "blob",
+    );
+    push(`Content-Disposition: form-data; name="${escapedKey}"; filename="${escapedFilename}"\r\n`);
+    if (value.type) {
+      push(`Content-Type: ${value.type}\r\n`);
+    }
+    push("\r\n");
+    push(Buffer.from(await value.arrayBuffer()));
+    push("\r\n");
+  }
+  push(`--${boundary}--\r\n`);
+  return Buffer.concat(chunks) as unknown as BodyInit;
+}
+
+async function normalizeFetchBody(
+  body: BodyInit | undefined,
+  headers: Headers,
+): Promise<BodyInit | undefined> {
+  if (body instanceof FormData) {
+    return await formDataToMultipartBody(body, headers);
+  }
+  return body;
+}
+
+export class RequestClient {
+  readonly options: RequestClientOptions;
+  protected token: string;
+  protected customFetch: RequestClientOptions["fetch"];
+  protected requestControllers = new Set<AbortController>();
+  private scheduler: RestScheduler<RequestData>;
+
+  constructor(token: string, options?: RequestClientOptions) {
+    this.token = token.replace(/^Bot\s+/i, "");
+    this.customFetch = options?.fetch;
+    this.options = { ...defaultOptions, ...options };
+    this.scheduler = new RestScheduler<RequestData>(
+      {
+        lanes: normalizeSchedulerLanes(
+          this.options.maxQueueSize ?? defaultOptions.maxQueueSize,
+          this.options.scheduler?.lanes,
+        ),
+        maxConcurrency: this.options.scheduler?.maxConcurrency ?? DEFAULT_MAX_CONCURRENT_WORKERS,
+        maxQueueSize: this.options.maxQueueSize ?? defaultOptions.maxQueueSize,
+        maxRateLimitRetries: this.options.scheduler?.maxRateLimitRetries ?? 3,
+      },
+      async (request) =>
+        await this.executeRequest(
+          request.method,
+          request.path,
+          { data: request.data, query: request.query },
+          request.routeKey,
+        ),
+    );
+  }
+
+  async get(path: string, query?: QueuedRequest["query"]): Promise<unknown> {
+    return await this.request("GET", path, { query });
+  }
+
+  async post(path: string, data?: RequestData, query?: QueuedRequest["query"]): Promise<unknown> {
+    return await this.request("POST", path, { data, query });
+  }
+
+  async patch(path: string, data?: RequestData, query?: QueuedRequest["query"]): Promise<unknown> {
+    return await this.request("PATCH", path, { data, query });
+  }
+
+  async put(path: string, data?: RequestData, query?: QueuedRequest["query"]): Promise<unknown> {
+    return await this.request("PUT", path, { data, query });
+  }
+
+  async delete(path: string, data?: RequestData, query?: QueuedRequest["query"]): Promise<unknown> {
+    return await this.request("DELETE", path, { data, query });
+  }
+
+  protected async request(
+    method: string,
+    path: string,
+    params: { data?: RequestData; query?: QueuedRequest["query"] },
+  ): Promise<unknown> {
+    const routeKey = createRouteKey(method, path);
+    if (!this.options.queueRequests) {
+      return await this.executeRequest(method, path, params, routeKey);
+    }
+    return await this.scheduler.enqueue({
+      method,
+      path,
+      priority: getRequestPriority(method, path),
+      ...params,
+    });
+  }
+
+  protected async executeRequest(
+    method: string,
+    path: string,
+    params: { data?: RequestData; query?: QueuedRequest["query"] },
+    routeKey = createRouteKey(method, path),
+  ): Promise<unknown> {
+    const url = `${this.options.baseUrl}/v${this.options.apiVersion}${appendQuery(path, params.query)}`;
+    const headers = new Headers({
+      "User-Agent": this.options.userAgent ?? defaultOptions.userAgent,
+    });
+    if (this.token !== "webhook") {
+      headers.set("Authorization", `${this.options.tokenHeader ?? "Bot"} ${this.token}`);
+    }
+    const body = serializeRequestBody(params.data, headers);
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.options.timeout ?? 15_000);
+    timeout.unref?.();
+    this.requestControllers.add(controller);
+    try {
+      const response = await (this.customFetch ?? fetch)(url, {
+        method,
+        headers,
+        body: await normalizeFetchBody(body, headers),
+        signal: controller.signal,
+      });
+      const text = await response.text();
+      const parsed = coerceResponseBody(text);
+      this.scheduler.recordResponse(routeKey, path, response, parsed);
+      if (response.status === 204) {
+        return undefined;
+      }
+      if (response.status === 429) {
+        const rateLimitBody = isDiscordRateLimitBody(parsed) ? parsed : undefined;
+        throw new RateLimitError(response, {
+          message: readDiscordMessage(rateLimitBody, "Rate limited"),
+          retry_after: readRetryAfter(rateLimitBody, response, 1),
+          code: readDiscordCode(rateLimitBody),
+          global: Boolean(rateLimitBody?.global),
+        });
+      }
+      if (!response.ok) {
+        throw new DiscordError(response, parsed);
+      }
+      return parsed;
+    } catch (error) {
+      if (error instanceof DOMException && error.name === "AbortError") {
+        throw error;
+      }
+      if (error instanceof Error) {
+        throw error;
+      }
+      throw new Error(`Discord request failed: ${inspect(error)}`, { cause: error });
+    } finally {
+      clearTimeout(timeout);
+      this.requestControllers.delete(controller);
+    }
+  }
+
+  clearQueue(): void {
+    this.scheduler.clearQueue();
+  }
+
+  get queueSize(): number {
+    return this.scheduler.queueSize;
+  }
+
+  getSchedulerMetrics() {
+    return this.scheduler.getMetrics();
+  }
+
+  abortAllRequests(): void {
+    this.scheduler.abortPending();
+    for (const controller of this.requestControllers) {
+      controller.abort();
+    }
+    this.requestControllers.clear();
+  }
+}
+
+function normalizeSchedulerLanes(
+  maxQueueSize: number,
+  lanes?: RequestSchedulerOptions["lanes"],
+): Record<RestRequestPriority, { maxQueueSize: number; staleAfterMs?: number; weight: number }> {
+  const fallbackMaxQueueSize = Math.max(1, Math.floor(maxQueueSize));
+  return {
+    critical: normalizeSchedulerLane("critical", fallbackMaxQueueSize, lanes?.critical),
+    standard: normalizeSchedulerLane("standard", fallbackMaxQueueSize, lanes?.standard),
+    background: normalizeSchedulerLane("background", fallbackMaxQueueSize, lanes?.background),
+  };
+}
+
+function normalizeSchedulerLane(
+  lane: RestRequestPriority,
+  maxQueueSize: number,
+  options?: { maxQueueSize?: number; staleAfterMs?: number; weight?: number },
+): { maxQueueSize: number; staleAfterMs?: number; weight: number } {
+  const defaults = defaultLaneOptions[lane];
+  return {
+    maxQueueSize:
+      options?.maxQueueSize !== undefined
+        ? Math.max(1, Math.floor(options.maxQueueSize))
+        : maxQueueSize,
+    staleAfterMs:
+      options?.staleAfterMs !== undefined
+        ? Math.max(0, Math.floor(options.staleAfterMs))
+        : defaults.staleAfterMs,
+    weight:
+      options?.weight !== undefined ? Math.max(1, Math.floor(options.weight)) : defaults.weight,
+  };
+}
+
+function getRequestPriority(method: string, path: string): RestRequestPriority {
+  const normalizedMethod = method.toUpperCase();
+  const normalizedPath = path.toLowerCase();
+  if (/^\/interactions\/\d+\/[^/]+\/callback$/.test(normalizedPath)) {
+    return "critical";
+  }
+  return normalizedMethod === "GET" ? "background" : "standard";
+}

package/src/internal/schemas.ts

@@ -0,0 +1,36 @@
+import { Type } from "typebox";
+import { Check } from "typebox/value";
+
+const discordInteractionPayloadSchema = Type.Object(
+  {
+    id: Type.String({ minLength: 1 }),
+    token: Type.String({ minLength: 1 }),
+    type: Type.Number(),
+  },
+  { additionalProperties: true },
+);
+
+const discordRateLimitBodySchema = Type.Object(
+  {
+    message: Type.Optional(Type.String()),
+    retry_after: Type.Optional(Type.Union([Type.Number(), Type.String()])),
+    global: Type.Optional(Type.Boolean()),
+    code: Type.Optional(Type.Union([Type.Number(), Type.String()])),
+  },
+  { additionalProperties: true },
+);
+
+export function assertDiscordInteractionPayload(value: unknown): void {
+  if (!Check(discordInteractionPayloadSchema, value)) {
+    throw new Error("Invalid Discord interaction payload");
+  }
+}
+
+export function isDiscordRateLimitBody(value: unknown): value is {
+  message?: string;
+  retry_after?: number | string;
+  global?: boolean;
+  code?: number | string;
+} {
+  return Check(discordRateLimitBodySchema, value);
+}

package/src/internal/structures.test.ts

@@ -0,0 +1,43 @@
+import { ChannelType } from "discord-api-types/v10";
+import { describe, expect, it } from "vitest";
+import { channelFactory, type StructureClient } from "./structures.js";
+
+const client: StructureClient = {
+  rest: {} as StructureClient["rest"],
+  async fetchUser() {
+    throw new Error("not used");
+  },
+};
+
+describe("channelFactory", () => {
+  it("maps Discord API thread owner and parent fields to camelCase aliases", () => {
+    const channel = channelFactory(client, {
+      id: "thread-1",
+      type: ChannelType.PublicThread,
+      guild_id: "guild-1",
+      name: "support",
+      owner_id: "owner-1",
+      parent_id: "parent-1",
+      last_message_id: null,
+      rate_limit_per_user: 0,
+      thread_metadata: {
+        archived: false,
+        auto_archive_duration: 60,
+        locked: false,
+        archive_timestamp: new Date(0).toISOString(),
+      },
+      message_count: 1,
+      member_count: 1,
+      total_message_sent: 1,
+    });
+
+    expect(channel.parentId).toBe("parent-1");
+    expect(channel.ownerId).toBe("owner-1");
+    expect(
+      channel.rawData && "parent_id" in channel.rawData ? channel.rawData.parent_id : undefined,
+    ).toBe("parent-1");
+    expect(
+      channel.rawData && "owner_id" in channel.rawData ? channel.rawData.owner_id : undefined,
+    ).toBe("owner-1");
+  });
+});

package/src/internal/structures.ts

@@ -0,0 +1,280 @@
+import {
+  type APIChannel,
+  type APIEmbed,
+  type APIGuild,
+  type APIGuildMember,
+  type APIMessage,
+  type APIRole,
+  type APIUser,
+  type MessageType,
+} from "discord-api-types/v10";
+import {
+  createChannelMessage,
+  createUserDmChannel,
+  deleteChannelMessage,
+  editChannelMessage,
+  getChannelMessage,
+  pinChannelMessage,
+  unpinChannelMessage,
+} from "./api.js";
+import { serializePayload, type MessagePayload } from "./payload.js";
+import type { RequestClient } from "./rest.js";
+
+type RawOrId<T> = T | string | { id: string; channelId?: string };
+export type StructureClient = {
+  rest: RequestClient;
+  fetchUser(id: string): Promise<User>;
+};
+
+export class Base {
+  constructor(protected client: StructureClient) {}
+}
+
+export class User<IsPartial extends boolean = false> extends Base {
+  protected rawDataValue: APIUser | null;
+  readonly id: string;
+
+  constructor(client: StructureClient, rawDataOrId: IsPartial extends true ? string : APIUser) {
+    super(client);
+    this.rawDataValue = typeof rawDataOrId === "string" ? null : rawDataOrId;
+    this.id = typeof rawDataOrId === "string" ? rawDataOrId : rawDataOrId.id;
+  }
+
+  get rawData(): Readonly<APIUser> {
+    if (!this.rawDataValue) {
+      throw new Error("Partial Discord user has no raw data");
+    }
+    return this.rawDataValue;
+  }
+  get partial(): IsPartial {
+    return (this.rawDataValue === null) as IsPartial;
+  }
+  get username() {
+    return this.rawDataValue?.username ?? "";
+  }
+  get globalName() {
+    return this.rawDataValue?.global_name;
+  }
+  get discriminator() {
+    return this.rawDataValue?.discriminator;
+  }
+  get bot() {
+    return this.rawDataValue?.bot;
+  }
+  get avatar() {
+    return this.rawDataValue?.avatar;
+  }
+  get avatarUrl() {
+    return this.avatar ? `https://cdn.discordapp.com/avatars/${this.id}/${this.avatar}.png` : null;
+  }
+  override toString(): string {
+    return `<@${this.id}>`;
+  }
+  async fetch(): Promise<User> {
+    return this.client.fetchUser(this.id);
+  }
+  async createDm() {
+    return await createUserDmChannel(this.client.rest, this.id);
+  }
+  async send(data: MessagePayload): Promise<Message> {
+    const dm = await this.createDm();
+    const message = await createChannelMessage(this.client.rest, dm.id, {
+      body: serializePayload(data),
+    });
+    return new Message(this.client, message);
+  }
+}
+
+export class Role<IsPartial extends boolean = false> extends Base {
+  protected rawDataValue: APIRole | null;
+  readonly id: string;
+  constructor(client: StructureClient, rawDataOrId: IsPartial extends true ? string : APIRole) {
+    super(client);
+    this.rawDataValue = typeof rawDataOrId === "string" ? null : rawDataOrId;
+    this.id = typeof rawDataOrId === "string" ? rawDataOrId : rawDataOrId.id;
+  }
+  get name() {
+    return this.rawDataValue?.name ?? "";
+  }
+}
+
+export class Guild<IsPartial extends boolean = false> extends Base {
+  protected rawDataValue: APIGuild | null;
+  readonly id: string;
+  constructor(client: StructureClient, rawDataOrId: IsPartial extends true ? string : APIGuild) {
+    super(client);
+    this.rawDataValue = typeof rawDataOrId === "string" ? null : rawDataOrId;
+    this.id = typeof rawDataOrId === "string" ? rawDataOrId : rawDataOrId.id;
+  }
+  get name() {
+    return this.rawDataValue?.name ?? "";
+  }
+}
+
+export class GuildMember extends Base {
+  constructor(
+    client: StructureClient,
+    public rawData: APIGuildMember,
+  ) {
+    super(client);
+  }
+  get user() {
+    return this.rawData.user ? new User(this.client, this.rawData.user) : null;
+  }
+  get roles() {
+    return (this.rawData.roles ?? []) as Array<string | Role>;
+  }
+  get nickname() {
+    return this.rawData.nick ?? undefined;
+  }
+}
+
+export class Message<IsPartial extends boolean = false> extends Base {
+  protected rawDataValue: APIMessage | null;
+  readonly id: string;
+  readonly channelId: string;
+
+  constructor(client: StructureClient, rawDataOrIds: RawOrId<APIMessage>) {
+    super(client);
+    this.rawDataValue =
+      typeof rawDataOrIds === "string" || !("author" in rawDataOrIds) ? null : rawDataOrIds;
+    this.id = typeof rawDataOrIds === "string" ? rawDataOrIds : rawDataOrIds.id;
+    this.channelId =
+      typeof rawDataOrIds === "string"
+        ? ""
+        : "channel_id" in rawDataOrIds
+          ? rawDataOrIds.channel_id
+          : (rawDataOrIds.channelId ?? "");
+  }
+
+  get rawData(): Readonly<APIMessage> {
+    if (!this.rawDataValue) {
+      throw new Error("Partial Discord message has no raw data");
+    }
+    return this.rawDataValue;
+  }
+  get partial(): IsPartial {
+    return (this.rawDataValue === null) as IsPartial;
+  }
+  get message(): Message<IsPartial> {
+    return this;
+  }
+  get channel_id() {
+    return this.channelId;
+  }
+  get guild_id() {
+    return (this.rawDataValue as { guild_id?: string } | null)?.guild_id;
+  }
+  get guild() {
+    return this.guild_id ? new Guild<true>(this.client, this.guild_id) : null;
+  }
+  get webhookId() {
+    return this.webhook_id;
+  }
+  get webhook_id() {
+    return (this.rawDataValue as { webhook_id?: string | null } | null)?.webhook_id ?? null;
+  }
+  get member() {
+    const member = (this.rawDataValue as { member?: APIGuildMember } | null)?.member;
+    return member ? new GuildMember(this.client, member) : null;
+  }
+  get rawMember() {
+    return (this.rawDataValue as { member?: APIGuildMember } | null)?.member;
+  }
+  get content() {
+    return this.rawDataValue?.content ?? "";
+  }
+  get author() {
+    return this.rawDataValue?.author ? new User(this.client, this.rawDataValue.author) : null;
+  }
+  get embeds(): APIEmbed[] {
+    return this.rawDataValue?.embeds ?? [];
+  }
+  get attachments() {
+    return this.rawDataValue?.attachments ?? [];
+  }
+  get stickers() {
+    return this.rawDataValue?.sticker_items ?? [];
+  }
+  get mentionedUsers() {
+    return (this.rawDataValue?.mentions ?? []).map((user) => new User(this.client, user));
+  }
+  get mentionedRoles() {
+    return this.rawDataValue?.mention_roles ?? [];
+  }
+  get mentionedEveryone() {
+    return this.rawDataValue?.mention_everyone ?? false;
+  }
+  get timestamp() {
+    return this.rawDataValue?.timestamp;
+  }
+  get type(): MessageType | undefined {
+    return this.rawDataValue?.type;
+  }
+  get messageReference() {
+    return this.rawDataValue?.message_reference;
+  }
+  get referencedMessage() {
+    return this.rawDataValue?.referenced_message
+      ? new Message(this.client, this.rawDataValue.referenced_message)
+      : null;
+  }
+  get thread() {
+    return this.rawDataValue?.thread ? channelFactory(this.client, this.rawDataValue.thread) : null;
+  }
+  async fetch(): Promise<Message> {
+    const raw = await getChannelMessage(this.client.rest, this.channelId, this.id);
+    return new Message(this.client, raw);
+  }
+  async delete(): Promise<void> {
+    await deleteChannelMessage(this.client.rest, this.channelId, this.id);
+  }
+  async edit(data: MessagePayload): Promise<Message> {
+    const raw = await editChannelMessage(this.client.rest, this.channelId, this.id, {
+      body: serializePayload(data),
+    });
+    return new Message(this.client, raw);
+  }
+  async reply(data: MessagePayload): Promise<Message> {
+    const raw = await createChannelMessage(this.client.rest, this.channelId, {
+      body: {
+        ...serializePayload(data),
+        message_reference: { message_id: this.id, fail_if_not_exists: false },
+      },
+    });
+    return new Message(this.client, raw);
+  }
+  async pin(): Promise<void> {
+    await pinChannelMessage(this.client.rest, this.channelId, this.id);
+  }
+  async unpin(): Promise<void> {
+    await unpinChannelMessage(this.client.rest, this.channelId, this.id);
+  }
+}
+
+export type DiscordChannel = APIChannel & {
+  rawData?: APIChannel;
+  guildId?: string;
+  guild?: Guild;
+  name?: string;
+  parentId?: string | null;
+  ownerId?: string | null;
+};
+
+export function channelFactory(
+  clientForTest: StructureClient,
+  channelData: APIChannel,
+  _partial?: boolean,
+): DiscordChannel {
+  return {
+    ...channelData,
+    rawData: channelData,
+    guildId: "guild_id" in channelData ? channelData.guild_id : undefined,
+    guild:
+      "guild_id" in channelData && typeof channelData.guild_id === "string"
+        ? new Guild<true>(clientForTest, channelData.guild_id)
+        : undefined,
+    parentId: "parent_id" in channelData ? channelData.parent_id : undefined,
+    ownerId: "owner_id" in channelData ? channelData.owner_id : undefined,
+  } as DiscordChannel;
+}