@gakr-gakr/discord 0.1.0

package/src/internal/modal-fields.ts

@@ -0,0 +1,95 @@
+import { type APIRole, type APIUser } from "discord-api-types/v10";
+import { Role, User, type StructureClient } from "./structures.js";
+
+type ModalResolvedData = {
+  roles?: Record<string, { id: string; name?: string }>;
+  users?: Record<string, { id: string; username?: string; discriminator?: string }>;
+};
+
+export function extractModalFields(components: unknown[]): Record<string, string | string[]> {
+  const out: Record<string, string | string[]> = {};
+  for (const component of flattenModalComponents(components)) {
+    const raw = component as { custom_id?: unknown; value?: unknown; values?: unknown };
+    if (typeof raw.custom_id !== "string") {
+      continue;
+    }
+    if (Array.isArray(raw.values)) {
+      out[raw.custom_id] = raw.values.map(String);
+    } else if (
+      typeof raw.value === "string" ||
+      typeof raw.value === "number" ||
+      typeof raw.value === "boolean"
+    ) {
+      out[raw.custom_id] = String(raw.value);
+    }
+  }
+  return out;
+}
+
+function flattenModalComponents(components: unknown[]): unknown[] {
+  const out: unknown[] = [];
+  for (const entry of components) {
+    if (!entry || typeof entry !== "object") {
+      continue;
+    }
+    const component = entry as { component?: unknown; components?: unknown[] };
+    if (component.component && typeof component.component === "object") {
+      out.push(component.component);
+    }
+    if (Array.isArray(component.components)) {
+      out.push(...flattenModalComponents(component.components));
+    }
+    out.push(entry);
+  }
+  return out;
+}
+
+export class ModalFields {
+  constructor(
+    private values: Record<string, string | string[]>,
+    private resolved?: ModalResolvedData,
+    private client?: StructureClient,
+  ) {}
+
+  private value(id: string, required: boolean): string | string[] | undefined {
+    const value = this.values[id];
+    if (required && (value === undefined || (Array.isArray(value) && value.length === 0))) {
+      throw new Error(`Missing required modal field ${id}`);
+    }
+    return value;
+  }
+
+  getText(id: string, required = false): string | null {
+    const value = this.value(id, required);
+    return typeof value === "string" ? value : null;
+  }
+
+  getStringSelect(id: string, required = false): string[] {
+    const value = this.value(id, required);
+    if (Array.isArray(value)) {
+      return value;
+    }
+    return typeof value === "string" ? [value] : [];
+  }
+
+  getRoleSelect(id: string, required = false): Role[] {
+    const values = this.getStringSelect(id, required);
+    return values.map((roleId) => {
+      const raw = this.resolved?.roles?.[roleId];
+      return raw
+        ? new Role(this.client!, { id: roleId, name: raw.name ?? "" } as APIRole)
+        : new Role<true>(this.client!, roleId);
+    });
+  }
+
+  getUserSelect(id: string, required = false): User[] {
+    const values = this.getStringSelect(id, required);
+    return values.map((userId) => {
+      const raw = this.resolved?.users?.[userId];
+      return new User(this.client!, {
+        id: userId,
+        username: raw?.username ?? "",
+      } as APIUser);
+    });
+  }
+}

package/src/internal/payload.ts

@@ -0,0 +1,69 @@
+import { MessageFlags, type APIEmbed } from "discord-api-types/v10";
+import { Embed } from "./embeds.js";
+
+export type MessagePayloadFile = {
+  name: string;
+  data: Blob | Uint8Array | ArrayBuffer;
+  description?: string;
+  duration_secs?: number;
+  waveform?: string;
+};
+export type MessagePayloadObject = {
+  content?: string;
+  embeds?: Array<APIEmbed | Embed>;
+  components?: TopLevelComponents[];
+  allowedMentions?: unknown;
+  allowed_mentions?: unknown;
+  flags?: number;
+  tts?: boolean;
+  files?: MessagePayloadFile[];
+  poll?: unknown;
+  ephemeral?: boolean;
+  stickers?: [string, string, string] | [string, string] | [string];
+};
+export type MessagePayload = string | MessagePayloadObject;
+export type TopLevelComponents = {
+  isV2?: boolean;
+  serialize: () => unknown;
+};
+
+function clean<T extends Record<string, unknown>>(value: T): T {
+  return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined)) as T;
+}
+
+function serializeAnyComponent(component: { serialize: () => unknown }): unknown {
+  return component.serialize();
+}
+
+function payloadHasV2Components(payload: MessagePayloadObject): boolean {
+  return Boolean(payload.components?.some((component) => component.isV2));
+}
+
+function normalizePayloadFlags(payload: MessagePayloadObject): number | undefined {
+  const flags = payload.ephemeral ? (payload.flags ?? 0) | MessageFlags.Ephemeral : payload.flags;
+  if (!payloadHasV2Components(payload)) {
+    return flags;
+  }
+  if (payload.content || payload.embeds?.length) {
+    throw new Error("Discord Components V2 payloads cannot include content or embeds");
+  }
+  return (flags ?? 0) | MessageFlags.IsComponentsV2;
+}
+
+export function serializePayload(payload: MessagePayload) {
+  if (typeof payload === "string") {
+    return { content: payload };
+  }
+  const flags = normalizePayloadFlags(payload);
+  return clean({
+    content: payload.content,
+    embeds: payload.embeds?.map((entry) => ("serialize" in entry ? entry.serialize() : entry)),
+    components: payload.components?.map((entry) => serializeAnyComponent(entry)),
+    allowed_mentions: payload.allowed_mentions ?? payload.allowedMentions,
+    flags,
+    tts: payload.tts,
+    files: payload.files,
+    poll: payload.poll,
+    sticker_ids: payload.stickers,
+  });
+}

package/src/internal/rest-body.ts

@@ -0,0 +1,115 @@
+type RequestData = {
+  body?: unknown;
+  multipartStyle?: "message" | "form";
+  rawBody?: boolean;
+  headers?: Record<string, string>;
+};
+
+export function serializeRequestBody(
+  data: RequestData | undefined,
+  headers: Headers,
+): BodyInit | undefined {
+  if (data?.headers) {
+    for (const [key, value] of Object.entries(data.headers)) {
+      headers.set(key, value);
+    }
+  }
+  if (data?.body == null) {
+    return undefined;
+  }
+  if (typeof data.body === "object") {
+    const bodyObject = data.body as Record<string, unknown>;
+    const topLevelFiles = Array.isArray(bodyObject.files) ? bodyObject.files : undefined;
+    const nestedData =
+      bodyObject.data && typeof bodyObject.data === "object"
+        ? (bodyObject.data as Record<string, unknown>)
+        : undefined;
+    const nestedFiles =
+      nestedData && Array.isArray(nestedData.files) ? nestedData.files : undefined;
+    const files = topLevelFiles ?? nestedFiles;
+    const filesContainer = topLevelFiles ? bodyObject : nestedFiles ? nestedData : undefined;
+    if (files?.length && filesContainer) {
+      if (data.multipartStyle === "form") {
+        const formData = new FormData();
+        for (const [key, value] of Object.entries(filesContainer)) {
+          if (key === "files" || value === undefined || value === null) {
+            continue;
+          }
+          formData.append(key, typeof value === "string" ? value : JSON.stringify(value));
+        }
+        for (const file of files) {
+          const item = file as {
+            fieldName?: unknown;
+            name?: unknown;
+            data?: unknown;
+            contentType?: unknown;
+          };
+          const name = typeof item.name === "string" && item.name ? item.name : "file";
+          const blob =
+            item.data instanceof Blob
+              ? item.data
+              : new Blob([item.data as BlobPart], {
+                  type: typeof item.contentType === "string" ? item.contentType : undefined,
+                });
+          formData.append(
+            typeof item.fieldName === "string" && item.fieldName ? item.fieldName : "file",
+            blob,
+            name,
+          );
+        }
+        return formData;
+      }
+      const payloadJson = topLevelFiles
+        ? { ...bodyObject }
+        : { ...bodyObject, data: { ...nestedData } };
+      const payloadFilesContainer = topLevelFiles
+        ? (payloadJson as Record<string, unknown>)
+        : ((payloadJson as { data: Record<string, unknown> }).data ?? {});
+      const formData = new FormData();
+      const existingAttachments = Array.isArray(payloadFilesContainer.attachments)
+        ? [...payloadFilesContainer.attachments]
+        : [];
+      const uploaded = files.map((file, index) => {
+        const item = file as {
+          name?: unknown;
+          data?: unknown;
+          contentType?: unknown;
+          description?: unknown;
+          duration_secs?: unknown;
+          waveform?: unknown;
+        };
+        const name = typeof item.name === "string" && item.name ? item.name : `file-${index}`;
+        const blob =
+          item.data instanceof Blob
+            ? item.data
+            : new Blob([item.data as BlobPart], {
+                type: typeof item.contentType === "string" ? item.contentType : undefined,
+              });
+        const id = existingAttachments.length + index;
+        formData.append(`files[${id}]`, blob, name);
+        const attachment: Record<string, unknown> = {
+          id,
+          filename: name,
+        };
+        if (typeof item.description === "string") {
+          attachment.description = item.description;
+        }
+        if (typeof item.duration_secs === "number") {
+          attachment.duration_secs = item.duration_secs;
+        }
+        if (typeof item.waveform === "string") {
+          attachment.waveform = item.waveform;
+        }
+        return attachment;
+      });
+      payloadFilesContainer.attachments = [...existingAttachments, ...uploaded];
+      delete payloadFilesContainer.files;
+      formData.append("payload_json", JSON.stringify(payloadJson));
+      return formData;
+    }
+  }
+  if (!data.rawBody) {
+    headers.set("Content-Type", "application/json");
+  }
+  return data.rawBody ? (data.body as BodyInit) : JSON.stringify(data.body);
+}

package/src/internal/rest-errors.ts

@@ -0,0 +1,88 @@
+export function readDiscordCode(body: unknown): number | undefined {
+  const value =
+    body && typeof body === "object" && "code" in body
+      ? (body as { code?: unknown }).code
+      : undefined;
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string" && /^\d+$/.test(value)) {
+    return Number(value);
+  }
+  return undefined;
+}
+
+export function readDiscordMessage(body: unknown, fallback: string): string {
+  const value =
+    body && typeof body === "object" && "message" in body
+      ? (body as { message?: unknown }).message
+      : undefined;
+  return typeof value === "string" && value.trim() ? value : fallback;
+}
+
+function readRetryAfterHeader(value: string | null, now = Date.now()): number | undefined {
+  if (!value) {
+    return undefined;
+  }
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) {
+    return seconds;
+  }
+  const retryAt = Date.parse(value);
+  return Number.isFinite(retryAt) ? (retryAt - now) / 1000 : undefined;
+}
+
+function coerceRetryAfterSeconds(value: unknown): number | undefined {
+  if (typeof value !== "number" && typeof value !== "string") {
+    return undefined;
+  }
+  const seconds = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(seconds) && seconds >= 0 ? Math.max(0, seconds) : undefined;
+}
+
+export function readRetryAfter(body: unknown, response: Response, fallbackSeconds = 0): number {
+  const bodyValue =
+    body && typeof body === "object" && "retry_after" in body
+      ? (body as { retry_after?: unknown }).retry_after
+      : undefined;
+  return (
+    coerceRetryAfterSeconds(bodyValue) ??
+    coerceRetryAfterSeconds(readRetryAfterHeader(response.headers.get("Retry-After"))) ??
+    fallbackSeconds
+  );
+}
+
+export class DiscordError extends Error {
+  readonly status: number;
+  readonly statusCode: number;
+  readonly rawBody: unknown;
+  readonly rawError: unknown;
+  discordCode?: number;
+
+  constructor(response: Response, body: unknown) {
+    super(readDiscordMessage(body, `Discord API request failed (${response.status})`));
+    this.name = "DiscordError";
+    this.status = response.status;
+    this.statusCode = response.status;
+    this.rawBody = body;
+    this.rawError = body;
+    this.discordCode = readDiscordCode(body);
+  }
+}
+
+export class RateLimitError extends DiscordError {
+  readonly retryAfter: number;
+  readonly scope: string | null;
+  readonly bucket: string | null;
+
+  constructor(
+    response: Response,
+    body: { message: string; retry_after: number; global: boolean; code?: number | string },
+  ) {
+    super(response, body);
+    this.name = "RateLimitError";
+    this.retryAfter = readRetryAfter(body, response, 1);
+    this.scope = body.global ? "global" : response.headers.get("X-RateLimit-Scope");
+    this.bucket = response.headers.get("X-RateLimit-Bucket");
+  }
+}

package/src/internal/rest-routes.ts

@@ -0,0 +1,50 @@
+type QueryValue = string | number | boolean;
+
+export function createRouteKey(method: string, path: string): string {
+  return `${method.toUpperCase()} ${path.split("?")[0] ?? path}`;
+}
+
+function readTopLevelRouteKey(path: string): string {
+  const [pathname = path] = path.split("?");
+  const [first, id, token] = pathname.replace(/^\/+/, "").split("/");
+  if (!first || !id) {
+    return pathname;
+  }
+  if (first === "channels" || first === "guilds" || first === "webhooks") {
+    return first === "webhooks" && token ? `${first}/${id}/${token}` : `${first}/${id}`;
+  }
+  return first;
+}
+
+export function createBucketKey(bucket: string, path: string): string {
+  return `${bucket}:${readTopLevelRouteKey(path)}`;
+}
+
+export function readHeaderNumber(headers: Headers, name: string): number | undefined {
+  const value = headers.get(name);
+  if (!value) {
+    return undefined;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+export function readResetAt(response: Response): number | undefined {
+  const resetAfter = readHeaderNumber(response.headers, "X-RateLimit-Reset-After");
+  if (resetAfter !== undefined) {
+    return Date.now() + Math.max(0, resetAfter * 1000);
+  }
+  const reset = readHeaderNumber(response.headers, "X-RateLimit-Reset");
+  return reset !== undefined ? reset * 1000 : undefined;
+}
+
+export function appendQuery(path: string, query?: Record<string, QueryValue>): string {
+  if (!query || Object.keys(query).length === 0) {
+    return path;
+  }
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    search.set(key, String(value));
+  }
+  return `${path}?${search.toString()}`;
+}