@openclaw/discord 2026.3.13 → 2026.5.1-beta.1

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()}`;
+}

package/src/internal/rest-scheduler.ts

@@ -0,0 +1,412 @@
+import { RateLimitError, readRetryAfter } from "./rest-errors.js";
+import { createBucketKey, createRouteKey, readHeaderNumber, readResetAt } from "./rest-routes.js";
+
+export type RequestQuery = Record<string, string | number | boolean>;
+type ScheduledRequest<TData> = {
+  method: string;
+  path: string;
+  data?: TData;
+  generation: number;
+  query?: RequestQuery;
+  routeKey: string;
+  retryCount: number;
+  resolve: (value?: unknown) => void;
+  reject: (reason?: unknown) => void;
+};
+
+type BucketState<TData> = {
+  active: number;
+  bucket?: string;
+  invalidRequests: number;
+  limit?: number;
+  pending: Array<ScheduledRequest<TData>>;
+  rateLimitHits: number;
+  remaining?: number;
+  resetAt: number;
+  routeKeys: Set<string>;
+};
+
+type RestSchedulerOptions = {
+  maxConcurrency: number;
+  maxRateLimitRetries: number;
+  maxQueueSize: number;
+};
+
+const INVALID_REQUEST_WINDOW_MS = 10 * 60_000;
+
+export class RestScheduler<TData> {
+  private activeWorkers = 0;
+  private buckets = new Map<string, BucketState<TData>>();
+  private drainTimer: NodeJS.Timeout | undefined;
+  private globalRateLimitUntil = 0;
+  private invalidRequestTimestamps: Array<{ at: number; status: number }> = [];
+  private queueGeneration = 0;
+  private queuedRequests = 0;
+  private routeBuckets = new Map<string, string>();
+
+  constructor(
+    private readonly options: RestSchedulerOptions,
+    private readonly executor: (request: ScheduledRequest<TData>) => Promise<unknown>,
+  ) {}
+
+  enqueue(params: {
+    method: string;
+    path: string;
+    data?: TData;
+    query?: RequestQuery;
+  }): Promise<unknown> {
+    if (this.queuedRequests >= this.options.maxQueueSize) {
+      throw new Error("Discord request queue is full");
+    }
+    const routeKey = createRouteKey(params.method, params.path);
+    const bucket = this.getBucket(this.routeBuckets.get(routeKey) ?? routeKey);
+    return new Promise((resolve, reject) => {
+      this.queuedRequests += 1;
+      bucket.pending.push({
+        ...params,
+        generation: this.queueGeneration,
+        routeKey,
+        retryCount: 0,
+        resolve,
+        reject,
+      });
+      this.drainQueues();
+    });
+  }
+
+  recordResponse(routeKey: string, path: string, response: Response, parsed: unknown): void {
+    this.updateRateLimitState(routeKey, path, response, parsed);
+    this.recordInvalidRequest(routeKey, path, response);
+  }
+
+  clearQueue(): void {
+    this.queueGeneration += 1;
+    if (this.drainTimer) {
+      clearTimeout(this.drainTimer);
+      this.drainTimer = undefined;
+    }
+    this.rejectPending(new Error("Discord request queue cleared"));
+  }
+
+  abortPending(): void {
+    this.queueGeneration += 1;
+    this.rejectPending(new DOMException("Aborted", "AbortError"));
+  }
+
+  get queueSize(): number {
+    return this.queuedRequests;
+  }
+
+  getMetrics() {
+    this.pruneInvalidRequests();
+    return {
+      globalRateLimitUntil: this.globalRateLimitUntil,
+      activeBuckets: this.buckets.size,
+      routeBucketMappings: this.routeBuckets.size,
+      buckets: Array.from(this.buckets.entries()).map(([key, bucket]) => ({
+        key,
+        active: bucket.active,
+        bucket: bucket.bucket,
+        invalidRequests: bucket.invalidRequests,
+        pending: bucket.pending.length,
+        rateLimitHits: bucket.rateLimitHits,
+        remaining: bucket.remaining,
+        resetAt: bucket.resetAt,
+        routeKeyCount: bucket.routeKeys.size,
+      })),
+      invalidRequestCount: this.invalidRequestTimestamps.length,
+      invalidRequestCountByStatus: this.invalidRequestTimestamps.reduce<Record<number, number>>(
+        (counts, entry) => {
+          counts[entry.status] = (counts[entry.status] ?? 0) + 1;
+          return counts;
+        },
+        {},
+      ),
+      queueSize: this.queueSize,
+      activeWorkers: this.activeWorkers,
+      maxConcurrentWorkers: this.maxConcurrentWorkers,
+    };
+  }
+
+  private get maxConcurrentWorkers(): number {
+    return Math.max(1, Math.floor(this.options.maxConcurrency));
+  }
+
+  private get maxRateLimitRetries(): number {
+    return Math.max(0, Math.floor(this.options.maxRateLimitRetries));
+  }
+
+  private getBucket(key: string): BucketState<TData> {
+    const existing = this.buckets.get(key);
+    if (existing) {
+      return existing;
+    }
+    const bucket: BucketState<TData> = {
+      active: 0,
+      invalidRequests: 0,
+      pending: [],
+      rateLimitHits: 0,
+      resetAt: 0,
+      routeKeys: new Set([key]),
+    };
+    this.buckets.set(key, bucket);
+    return bucket;
+  }
+
+  private hasBucketReference(key: string): boolean {
+    for (const bucketKey of this.routeBuckets.values()) {
+      if (bucketKey === key) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  private isBucketRateLimited(bucket: BucketState<TData>, now = Date.now()): boolean {
+    return bucket.remaining === 0 && bucket.resetAt > now;
+  }
+
+  private pruneRouteMapping(routeKey: string): void {
+    const bucketKey = this.routeBuckets.get(routeKey);
+    if (!bucketKey) {
+      return;
+    }
+    this.routeBuckets.delete(routeKey);
+    this.buckets.get(bucketKey)?.routeKeys.delete(routeKey);
+  }
+
+  private pruneIdleRouteMappings(
+    bucketKey: string,
+    bucket: BucketState<TData>,
+    now = Date.now(),
+  ): void {
+    if (bucket.active > 0 || bucket.pending.length > 0 || this.isBucketRateLimited(bucket, now)) {
+      return;
+    }
+    for (const routeKey of Array.from(bucket.routeKeys)) {
+      if (this.routeBuckets.get(routeKey) === bucketKey) {
+        this.pruneRouteMapping(routeKey);
+      }
+    }
+  }
+
+  private shouldPruneIdleBucket(key: string): boolean {
+    const mappedBucketKey = this.routeBuckets.get(key);
+    return mappedBucketKey !== key && !this.hasBucketReference(key);
+  }
+
+  private bindRouteToBucket(routeKey: string, bucketKey: string): BucketState<TData> {
+    const target = this.getBucket(bucketKey);
+    target.routeKeys.add(routeKey);
+    this.routeBuckets.set(routeKey, bucketKey);
+    const routeBucket = this.buckets.get(routeKey);
+    if (routeBucket && routeBucket !== target) {
+      target.pending.push(...routeBucket.pending);
+      routeBucket.pending = [];
+      if (routeBucket.active === 0) {
+        this.buckets.delete(routeKey);
+      }
+    }
+    return target;
+  }
+
+  private updateRateLimitState(
+    routeKey: string,
+    path: string,
+    response: Response,
+    parsed: unknown,
+  ): void {
+    const bucketHeader = response.headers.get("X-RateLimit-Bucket");
+    const bucket = bucketHeader
+      ? this.bindRouteToBucket(routeKey, createBucketKey(bucketHeader, path))
+      : this.getBucket(this.routeBuckets.get(routeKey) ?? routeKey);
+    bucket.bucket = bucketHeader ?? bucket.bucket;
+    const limit = readHeaderNumber(response.headers, "X-RateLimit-Limit");
+    if (limit !== undefined) {
+      bucket.limit = limit;
+    }
+    const remaining = readHeaderNumber(response.headers, "X-RateLimit-Remaining");
+    if (remaining !== undefined) {
+      bucket.remaining = remaining;
+    }
+    const resetAt = readResetAt(response);
+    if (resetAt !== undefined) {
+      bucket.resetAt = resetAt;
+    }
+    if (response.status !== 429) {
+      return;
+    }
+    bucket.rateLimitHits += 1;
+    const retryAfterMs = Math.max(0, readRetryAfter(parsed, response, 1) * 1000);
+    const retryAt = Date.now() + retryAfterMs;
+    if (response.headers.get("X-RateLimit-Global") === "true" || isGlobalRateLimit(parsed)) {
+      this.globalRateLimitUntil = Math.max(this.globalRateLimitUntil, retryAt);
+      return;
+    }
+    bucket.remaining = 0;
+    bucket.resetAt = Math.max(bucket.resetAt, retryAt);
+  }
+
+  private recordInvalidRequest(routeKey: string, path: string, response: Response): void {
+    if (response.status !== 401 && response.status !== 403 && response.status !== 429) {
+      return;
+    }
+    if (response.status === 429 && response.headers.get("X-RateLimit-Scope") === "shared") {
+      return;
+    }
+    const now = Date.now();
+    this.invalidRequestTimestamps.push({ at: now, status: response.status });
+    this.pruneInvalidRequests(now);
+    const bucketHeader = response.headers.get("X-RateLimit-Bucket");
+    const bucketKey = bucketHeader
+      ? createBucketKey(bucketHeader, path)
+      : (this.routeBuckets.get(routeKey) ?? routeKey);
+    const bucket = this.buckets.get(bucketKey);
+    if (bucket) {
+      bucket.invalidRequests += 1;
+    }
+  }
+
+  private pruneInvalidRequests(now = Date.now()): void {
+    const cutoff = now - INVALID_REQUEST_WINDOW_MS;
+    while (
+      this.invalidRequestTimestamps.length > 0 &&
+      (this.invalidRequestTimestamps[0]?.at ?? 0) <= cutoff
+    ) {
+      this.invalidRequestTimestamps.shift();
+    }
+  }
+
+  private getBucketWaitMs(bucket: BucketState<TData>, now: number): number {
+    if (bucket.remaining === 0 && bucket.resetAt > now) {
+      return bucket.resetAt - now;
+    }
+    if (bucket.remaining === 0 && bucket.resetAt <= now) {
+      bucket.remaining = bucket.limit;
+    }
+    return 0;
+  }
+
+  private scheduleDrain(delayMs = 0): void {
+    if (this.drainTimer) {
+      return;
+    }
+    this.drainTimer = setTimeout(
+      () => {
+        this.drainTimer = undefined;
+        this.drainQueues();
+      },
+      Math.max(0, delayMs),
+    );
+    this.drainTimer.unref?.();
+  }
+
+  private drainQueues(): void {
+    const now = Date.now();
+    if (this.globalRateLimitUntil > now) {
+      this.scheduleDrain(this.globalRateLimitUntil - now);
+      return;
+    }
+    let nextDelayMs = Number.POSITIVE_INFINITY;
+    for (const [key, bucket] of this.buckets) {
+      if (this.activeWorkers >= this.maxConcurrentWorkers) {
+        break;
+      }
+      if (bucket.pending.length === 0) {
+        if (bucket.active !== 0) {
+          continue;
+        }
+        if (this.isBucketRateLimited(bucket, now)) {
+          nextDelayMs = Math.min(nextDelayMs, bucket.resetAt - now);
+          continue;
+        }
+        this.pruneIdleRouteMappings(key, bucket, now);
+        if (this.shouldPruneIdleBucket(key)) {
+          this.buckets.delete(key);
+        }
+        continue;
+      }
+      if (bucket.active > 0) {
+        continue;
+      }
+      const waitMs = this.getBucketWaitMs(bucket, now);
+      if (waitMs > 0) {
+        nextDelayMs = Math.min(nextDelayMs, waitMs);
+        continue;
+      }
+      const queued = bucket.pending.shift();
+      if (!queued) {
+        continue;
+      }
+      if (bucket.remaining !== undefined && bucket.remaining > 0) {
+        bucket.remaining -= 1;
+      }
+      bucket.active += 1;
+      this.activeWorkers += 1;
+      void this.runQueuedRequest(queued, bucket);
+    }
+    if (Number.isFinite(nextDelayMs)) {
+      this.scheduleDrain(nextDelayMs);
+    }
+  }
+
+  private async runQueuedRequest(
+    queued: ScheduledRequest<TData>,
+    bucket: BucketState<TData>,
+  ): Promise<void> {
+    let requeued = false;
+    try {
+      queued.resolve(await this.executor(queued));
+    } catch (error) {
+      if (error instanceof RateLimitError && this.requeueRateLimitedRequest(queued)) {
+        requeued = true;
+        return;
+      }
+      queued.reject(error);
+    } finally {
+      bucket.active = Math.max(0, bucket.active - 1);
+      this.activeWorkers = Math.max(0, this.activeWorkers - 1);
+      if (!requeued) {
+        this.queuedRequests = Math.max(0, this.queuedRequests - 1);
+      }
+      if (bucket.active === 0 && bucket.pending.length === 0) {
+        for (const routeKey of bucket.routeKeys) {
+          if (this.routeBuckets.get(routeKey) === routeKey) {
+            this.routeBuckets.delete(routeKey);
+          }
+        }
+      }
+      this.drainQueues();
+    }
+  }
+
+  private requeueRateLimitedRequest(queued: ScheduledRequest<TData>): boolean {
+    if (
+      queued.generation !== this.queueGeneration ||
+      queued.retryCount >= this.maxRateLimitRetries
+    ) {
+      return false;
+    }
+    const bucketKey = this.routeBuckets.get(queued.routeKey) ?? queued.routeKey;
+    this.getBucket(bucketKey).pending.push({
+      ...queued,
+      retryCount: queued.retryCount + 1,
+    });
+    return true;
+  }
+
+  private rejectPending(error: Error | DOMException): void {
+    for (const bucket of this.buckets.values()) {
+      for (const queued of bucket.pending.splice(0)) {
+        queued.reject(error);
+        this.queuedRequests = Math.max(0, this.queuedRequests - 1);
+      }
+    }
+  }
+}
+
+function isGlobalRateLimit(parsed: unknown): boolean {
+  return parsed && typeof parsed === "object" && "global" in parsed
+    ? Boolean((parsed as { global?: unknown }).global)
+    : false;
+}