lunibee 0.3.0 → 0.3.2

package/dist/managers/member.d.ts

@@ -1,6 +1,7 @@
 import { REST } from "@lunibee/rest";
 import { GuildMember, type ResourceContext } from "@lunibee/structures";
 import { ResourceManager } from "./base.js";
+/** Fields that can change when editing a guild member (nickname, roles, voice state, timeout). */
 export interface MemberEditOptions {
     /** Audit-log reason. */
     reason?: string;
@@ -11,6 +12,7 @@ export interface MemberEditOptions {
     channel_id?: string | null;
     communication_disabled_until?: string | null;
 }
+/** Options for banning a member: audit-log `reason` and how many seconds of their messages to delete. */
 export interface BanOptions {
     reason?: string;
     deleteMessageSeconds?: number;
@@ -20,7 +22,7 @@ export declare class GuildMemberManager extends ResourceManager<string, GuildMem
     #private;
     readonly guildId: string;
     /** @param context Gives fetched members their actions (`member.kick()`...). */
-    constructor(guildId: string, rest: REST, context?: () => ResourceContext | undefined);
+    constructor(guildId: string, rest: REST, context?: () => ResourceContext | undefined, maxSize?: number);
     /** Finds members whose username or nickname starts with `query` (up to `limit`, 1-1000, default 1). */
     search(query: string, limit?: number): Promise<GuildMember[]>;
     /** Changes the bot's own nickname in this guild (`null` clears it). */

package/dist/managers/message.d.ts

@@ -8,16 +8,25 @@ export interface MessageCacheOptions {
     ttl?: number;
 }
 import { REST, type RESTFileAttachment } from "@lunibee/rest";
-import type { AllowedMentions, MessageCreateOptions, MessageEditOptions, MessageFile } from "@lunibee/types";
+import type { AllowedMentions, MessageCreateOptions, MessageEditOptions, MessageFile, MessageFileSource } from "@lunibee/types";
 import { Message, type ResourceContext } from "@lunibee/structures";
-export type { MessageCreateOptions, MessageEditOptions, MessageFile };
-/** Turns message files into REST uploads, encoding string data as UTF-8. */
-export declare function toAttachments(files: readonly MessageFile[]): RESTFileAttachment[];
+export type { MessageCreateOptions, MessageEditOptions, MessageFile, MessageFileSource, };
+/**
+ * Turns message files into REST uploads, encoding string data as UTF-8. A file
+ * with `toBuffer()` (such as a `CreateAttachment`) is read when the request is sent.
+ */
+export declare function toAttachments(files: readonly (MessageFile | MessageFileSource)[]): RESTFileAttachment[];
 /**
  * Splits `files` out of a message payload into a REST upload, encoding string
  * data as UTF-8. `allowedMentions` is the client's default, applied only when
  * the payload has no `allowed_mentions` of its own.
  */
+/**
+ * Refuses an `allowed_mentions` object Discord would answer with 400: a kind
+ * both in `parse` and listed by id, an unknown `parse` value, or non-string ids.
+ * @throws {TypeError} If the object is invalid.
+ */
+export declare function assertAllowedMentions(mentions: AllowedMentions): void;
 export declare function toRequest(options: MessageCreateOptions, allowedMentions?: AllowedMentions): Omit<MessageCreateOptions, "files"> | {
     body: Omit<MessageCreateOptions, "files">;
     files: RESTFileAttachment[];

package/dist/managers/thread.d.ts

@@ -1,6 +1,6 @@
 import { REST } from "@lunibee/rest";
 import { Channel, type ResourceContext } from "@lunibee/structures";
-import type { APIGuildMember, APIThreadMember, MessageCreateOptions } from "@lunibee/types";
+import type { AllowedMentions, APIGuildMember, APIThreadMember, MessageCreateOptions } from "@lunibee/types";
 /** Options shared by every way of starting a thread. */
 export interface ThreadCreateOptions {
     name: string;
@@ -26,8 +26,8 @@ export interface ArchivedThreads {
 /** Manages thread resources created from a parent channel. */
 export declare class ThreadManager {
     #private;
-    /** Creates a thread manager. @param rest REST transport. @param context Structure resource context. @param channelId Parent channel identifier. @throws {TypeError} If channelId is empty. */
-    constructor(rest: REST, context: ResourceContext, channelId: string);
+    /** Creates a thread manager. @param rest REST transport. @param context Structure resource context. @param channelId Parent channel identifier. @param allowedMentions Default `allowed_mentions` for a forum post's first message without its own. @throws {TypeError} If channelId is empty. */
+    constructor(rest: REST, context: ResourceContext, channelId: string, allowedMentions?: AllowedMentions);
     /** Creates a thread from a message. @param messageId Message identifier. @param options Thread creation options. @returns Created thread channel. @throws {Error} If REST rejects the request. */
     createFromMessage(messageId: string, options: {
         name: string;

package/dist/rest/decoder.d.ts

@@ -7,6 +7,8 @@ export interface DecodedError {
 }
 /** Turns a raw {@link Response} into a payload and the error metadata retries need. */
 export declare class ResponseDecoder {
+    /** Creates an empty instance. */
+    constructor();
     /** Reads a Discord response payload as JSON, text, or nothing for 204. */
     read(response: Response): Promise<unknown>;
     /** Extracts Discord's error metadata from a decoded payload. */

package/dist/rest/errors.d.ts

@@ -19,13 +19,25 @@ export type RESTErrorKind =
 /** 5xx: Discord failed to handle the request. */
  | "server"
 /** Any other 4xx. */
- | "client";
+ | "client"
+/** The rate-limit store failed or refused to coordinate; the request was not sent. */
+ | "coordination"
+/** A local queue limit was reached; the request was not sent. */
+ | "overloaded";
 /**
  * Replaces the token segment of webhook and interaction paths with `:token`,
  * so request paths can appear in errors, hooks and logs without leaking a
  * credential.
  */
 export declare function redactPath(path: string): string;
+/** Hides webhook and interaction tokens in free text. */
+export declare function redactText(text: string): string;
+/**
+ * A copy of a lower-level error that is safe to attach as a `cause`: the same
+ * name and code, with tokens removed from the message and stack. Runtimes put
+ * the request URL in network error messages, and the URL holds webhook tokens.
+ */
+export declare function sanitizeCause(error: unknown): unknown;
 /** Error thrown when Discord rejects a REST request. */
 export declare class RESTError extends Error {
     /** Failure category. */
@@ -55,7 +67,6 @@ export declare class RESTError extends Error {
 }
 /** Creates the cancellation error shared by every stage of the request pipeline. */
 export declare function abortError(path: string, reason: unknown): RESTError;
-/** Waits for a delay, rejecting early if the signal aborts. */
 export declare function sleep(delay: number, signal: AbortSignal | undefined, path: string): Promise<void>;
 /** Awaits a promise, rejecting early if the signal aborts. */
 export declare function abortable(promise: Promise<void>, signal: AbortSignal | undefined, path: string): Promise<void>;

package/dist/rest/headers.d.ts

@@ -0,0 +1,31 @@
+/** Which limit a 429 counts against, from `X-RateLimit-Scope`. */
+export type RateLimitScope = "user" | "global" | "shared";
+/** A response's rate-limit headers, each one validated on its own. */
+export interface RateLimitHeaders {
+    /** `X-RateLimit-Limit`: requests per window. */
+    limit?: number;
+    /** `X-RateLimit-Remaining`: requests left in the window. */
+    remaining?: number;
+    /** `X-RateLimit-Reset-After`, in ms from now. */
+    resetAfterMs?: number;
+    /** `X-RateLimit-Reset`, as epoch ms: identifies the window. */
+    resetAtMs?: number;
+    /** `X-RateLimit-Bucket`: the server's bucket hash. */
+    bucket?: string;
+    /** `X-RateLimit-Scope`, when it is one Discord documents. */
+    scope?: RateLimitScope;
+    /** `X-RateLimit-Global: true`. */
+    global: boolean;
+    /** `Retry-After`, in ms. */
+    retryAfterMs?: number;
+}
+/**
+ * A non-negative finite number from a header, or `undefined`.
+ *
+ * `Number(null)` and `Number("")` are 0, which would read a missing header as
+ * "nothing remaining" or "reset now"; a negative or non-numeric value is a
+ * broken proxy, not information.
+ */
+export declare function headerNumber(headers: Headers, name: string): number | undefined;
+/** Reads every rate-limit header of a response defensively. */
+export declare function parseRateLimitHeaders(headers: Headers): RateLimitHeaders;

package/dist/rest/identity.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Who a request's rate limits belong to.
+ *
+ * `bucket` prefixes the bucket key: Discord counts a bot's buckets per bot, so
+ * two bots sharing one Redis must not share counters. `global` is the scope of
+ * the global limit the request counts against, or `undefined` when it counts
+ * against none.
+ */
+export interface RequestIdentity {
+    bucket: string;
+    global?: string;
+}
+/**
+ * A stable, non-reversible fingerprint of a token, identical in every process.
+ * The token itself never enters a key, a label or a log line.
+ */
+export declare function tokenFingerprint(token: string): string;
+/**
+ * Classifies a request.
+ *
+ * - Interaction callbacks (`/interactions/:id/:token/…`) and token webhooks
+ *   (`/webhooks/:id/:token…`, which includes interaction follow-ups) are
+ *   limited per webhook, whoever sends them: their buckets are shared
+ *   (`"shared"`), so every bot and process agrees on one counter.
+ *   Interaction callbacks are not bound to any global limit; a token webhook
+ *   still counts against the sender's, conservatively, because a follow-up
+ *   cannot be told from a plain webhook by its path.
+ * - A request sent without a bot token is limited per caller (`"anon"`).
+ * - Everything else belongs to the bot that sends it.
+ */
+export declare function requestIdentity(path: string, fingerprint: string | undefined): RequestIdentity;

package/dist/rest/index.d.ts

@@ -1,11 +1,13 @@
 import { type RateLimitStore } from "./store.js";
 import { RESTError } from "./errors.js";
 import { type RESTQuery } from "./route.js";
+import { type CoordinationMode, type RESTTelemetry } from "./telemetry.js";
 import { HttpTransport } from "./transport.js";
 /** A file attachment sent as part of a multipart REST request. */
 export interface RESTFileAttachment {
     name: string;
-    data: Blob | Uint8Array | ArrayBuffer;
+    /** The bytes, or a promise of them (read just before the request is sent). */
+    data: Blob | Uint8Array | ArrayBuffer | PromiseLike<Blob | Uint8Array | ArrayBuffer>;
     contentType?: string;
 }
 /**
@@ -26,6 +28,12 @@ export interface RESTRequestOptions {
     reason?: string;
     /** Set `false` to omit the `Authorization` header for this request. Defaults to `true`. */
     auth?: boolean;
+    /**
+     * Longest, in ms, this request may wait before it is sent: queued behind
+     * its bucket, for a rate limit, or between retries. Past it the request
+     * fails with kind `"overloaded"`. Overrides the client's `maxQueueWait`.
+     */
+    maxQueueWait?: number;
 }
 /**
  * Discord.js-familiar request payload. Superset of {@link RESTRequestOptions} that also
@@ -38,6 +46,18 @@ export interface RequestData extends RESTRequestOptions {
     /** File attachments; presence upgrades the request to `multipart/form-data`. */
     files?: RESTFileAttachment[];
 }
+/**
+ * The single-object form of {@link REST.request}, matching `@discordjs/rest`:
+ * the route is `path` (or its Discord.js name, `fullRoute`).
+ */
+export interface RequestOptionsObject extends RequestData {
+    /** HTTP method. */
+    method: string;
+    /** API path, starting with `/`. */
+    path?: string;
+    /** Alias of `path`, as `@discordjs/rest` names it. */
+    fullRoute?: string;
+}
 /** Context passed to `RESTHooks.onRequest`. */
 export interface RESTRequestContext {
     method: string;
@@ -97,6 +117,26 @@ export interface RetryPolicy {
 }
 /** Creates the default conservative REST retry policy. @param maxRetries Maximum retries. @returns Retry policy that retries rate limits and idempotent transient failures. @throws {TypeError} If maxRetries is negative or not finite. */
 export declare function createRetryPolicy(maxRetries?: number): RetryPolicy;
+/** A REST client's state, for health checks and diagnostics endpoints. */
+export interface RESTDiagnostics {
+    /** How the store enforces limits right now. */
+    mode: CoordinationMode;
+    /** Requests waiting for a bucket slot. */
+    queued: number;
+    /** Requests started and not yet settled, queued ones included. */
+    inFlight: number;
+    /** Bucket keys holding a queue slot. */
+    buckets: number;
+    /** Whether `close()` was called. */
+    closed: boolean;
+    /**
+     * `401`, `403` and `429` responses (shared-scope 429s excepted) in the
+     * last ten minutes. Discord bans an IP for a while past 10,000.
+     */
+    invalidRequests: number;
+    /** Whether requests are refused because Discord rejected the token (see `stopOnInvalidToken`). */
+    tokenRejected: boolean;
+}
 /** Bun-native REST transport with Discord bucket-aware rate limiting, retries, and cancellation. */
 export declare class REST {
     #private;
@@ -107,6 +147,8 @@ export declare class REST {
         retries?: number;
         retryPolicy?: RetryPolicy;
         baseURL?: string;
+        /** Allow a cleartext `http://` base URL on a network you trust (a REST proxy). Default false. */
+        allowInsecureBaseURL?: boolean;
         hooks?: RESTHooks;
         store?: RateLimitStore;
         /** Replaces the HTTP stage, e.g. with a recording transport in tests. */
@@ -115,9 +157,48 @@ export declare class REST {
          * Lets requests on a bucket whose limit is known run concurrently, up
          * to its `remaining` allowance, instead of one at a time. Requires a
          * store with `reserve`. Requests on one bucket may then complete out
-         * of order (e.g. messages to one channel). Defaults to `false`.
+         * of order (e.g. messages to one channel). Defaults to `true`.
          */
         concurrentBuckets?: boolean;
+        /**
+         * The longest, in ms, that a rate-limit header from the server may
+         * make this client wait. A `Retry-After` beyond it fails the request
+         * with the 429 instead of sleeping, and stored limits are capped to it,
+         * so a proxy or an attacker cannot stall every request for hours.
+         * Default 600,000 (ten minutes).
+         */
+        maxBackoff?: number;
+        /**
+         * Receives telemetry events (latency, 429s by scope, waits,
+         * reservations, retries, cancellations, queue depth). See
+         * `RESTMetrics` for a ready-made aggregator.
+         */
+        telemetry?: RESTTelemetry;
+        /** Most requests waiting for a bucket slot; more fail with kind `"overloaded"`. Default unlimited. */
+        maxQueued?: number;
+        /** Most requests waiting on one bucket; more fail with kind `"overloaded"`. Default unlimited. */
+        maxQueuedPerBucket?: number;
+        /**
+         * Requests per second this bot may send across all buckets,
+         * enforced before Discord answers with a global 429 (shared through
+         * the store, so it holds for every process). Default 50, Discord's
+         * global limit; set what Discord granted a large bot, or `false`
+         * to rely on 429s alone.
+         */
+        globalLimit?: number | false;
+        /**
+         * After a `401` on a bot route, refuse every later request with
+         * this token without sending it, until `setToken()`: repeated 401s
+         * count towards Discord's invalid-request ban. Default `true`.
+         */
+        stopOnInvalidToken?: boolean;
+        /**
+         * Longest, in ms, a request may wait before it is sent (queue,
+         * rate limits, pauses between retries); past it the request fails
+         * with kind `"overloaded"`. Default unlimited. Per request:
+         * `maxQueueWait` in the request options.
+         */
+        maxQueueWait?: number;
     });
     /** The rate-limit store backing this transport. */
     get store(): RateLimitStore;
@@ -125,6 +206,14 @@ export declare class REST {
     setHooks(hooks: RESTHooks): this;
     /** Sets the authentication token. @param token Discord bot token. @returns Nothing. @throws {TypeError} If token is empty. */
     setToken(token: string): void;
+    /** The client's current state. */
+    diagnostics(): RESTDiagnostics;
+    /**
+     * Stops the client: new requests are refused, requests still queued or
+     * waiting for a limit fail with kind `"aborted"`, and attempts already
+     * sent are allowed to finish. Resolves when nothing is in flight.
+     */
+    close(): Promise<void>;
     /** Executes an HTTP request with Discord bucket/global rate limits, retry handling, and AbortSignal support.
      * Accepts a JSON body, a FormData body (for file uploads), or undefined.
      * @param method HTTP method.
@@ -135,6 +224,7 @@ export declare class REST {
      * @returns Decoded response body.
      * @throws {RESTError} If Discord or transport rejects the request.
      */
+    request<T>(options: RequestOptionsObject): Promise<T>;
     request<T>(method: string, path: string, body?: unknown, options?: RequestData): Promise<T>;
     /** Sends a GET request. @param path API path. @param options Request options (`query`, `headers`, `signal`, …). @returns Decoded response. @throws {RESTError} When the request fails. */
     get<T>(path: string, options?: RequestData): Promise<T>;
@@ -175,12 +265,15 @@ export { Routes } from "./routes.js";
 export { RESTError, abortError, redactPath, type RESTErrorKind, } from "./errors.js";
 export { RESTErrorCode } from "./error-codes.js";
 export { createRouteKey, normalizeRoutePath, majorParameter, scopeBucket, serializeQuery, type RouteKey, type RESTQuery, } from "./route.js";
-export { RequestScheduler } from "./scheduler.js";
-export { RateLimiter } from "./limiter.js";
+export { RequestScheduler, type SchedulerOptions } from "./scheduler.js";
+export { RateLimiter, DEFAULT_MAX_BACKOFF_MS, type Grant, type ApplyResponseOptions, } from "./limiter.js";
+export { parseRateLimitHeaders, headerNumber, type RateLimitHeaders, type RateLimitScope, } from "./headers.js";
+export { requestIdentity, tokenFingerprint, type RequestIdentity, } from "./identity.js";
+export { RESTMetrics, type RESTMetricsSnapshot, type RESTTelemetry, type RESTTelemetryEvent, type CoordinationMode, } from "./telemetry.js";
 export { HttpTransport, TransportError, type TransportRequest, type FetchLike, } from "./transport.js";
 export { ResponseDecoder, type DecodedError } from "./decoder.js";
-export { type RateLimitStore, type BucketState, type Reservation, MemoryRateLimitStore, } from "./store.js";
-export { RedisRateLimitStore, type RedisRateLimitStoreOptions, type MinimalRedisClient, } from "./redis.js";
+export { type RateLimitStore, type BucketState, type BucketUpdate, type Reservation, type ReserveOptions, MemoryRateLimitStore, } from "./store.js";
+export { RedisRateLimitStore, fromBunRedis, type RedisRateLimitStoreOptions, type RedisFailurePolicy, type RedisStoreDiagnostics, type MinimalRedisClient, } from "./redis.js";
 export { WebhookClient, type WebhookClientOptions, type WebhookMessageOptions, } from "./webhook.js";
 /**
  * Discord.js-familiar alias for {@link RESTError}. `@discordjs/rest` throws `DiscordAPIError`