@discordjs/rest 2.1.1-dev.1699877033-8d04cbc20 → 2.1.1-dev.1699963438-4b88306dc

package/dist/index.d.mts

@@ -1,14 +1,380 @@
-import { R as ResponseLike, a as RawFile, I as InternalRequest, b as RateLimitData, c as RestEventsMap, H as HashData, d as IHandler, e as RESTOptions, f as RouteLike, g as RequestData } from './types-c3e7077b.js';
-export { A as APIRequest, m as HandlerRequestData, j as InvalidRequestWarningData, i as RateLimitQueueFilter, k as RequestHeaders, l as RequestMethod, h as RestEvents, n as RouteData } from './types-c3e7077b.js';
 import * as url from 'url';
 import { Snowflake } from 'discord-api-types/v10';
-import * as undici from 'undici';
-import { Dispatcher } from 'undici';
+import { Readable } from 'node:stream';
+import { ReadableStream } from 'node:stream/web';
 import { Collection } from '@discordjs/collection';
+import { Awaitable } from '@discordjs/util';
+import * as undici from 'undici';
+import { RequestInit, Dispatcher, Response, BodyInit, Agent } from 'undici';
 import { AsyncEventEmitter } from '@vladfrangu/async_event_emitter';
-import 'node:stream';
-import 'node:stream/web';
-import '@discordjs/util';
+
+interface IHandler {
+    /**
+     * The unique id of the handler
+     */
+    readonly id: string;
+    /**
+     * If the bucket is currently inactive (no pending requests)
+     */
+    get inactive(): boolean;
+    /**
+     * Queues a request to be sent
+     *
+     * @param routeId - The generalized api route with literal ids for major parameters
+     * @param url - The url to do the request on
+     * @param options - All the information needed to make a request
+     * @param requestData - Extra data from the user's request needed for errors and additional processing
+     */
+    queueRequest(routeId: RouteData, url: string, options: RequestInit, requestData: HandlerRequestData): Promise<ResponseLike>;
+}
+
+interface RestEvents {
+    handlerSweep: [sweptHandlers: Collection<string, IHandler>];
+    hashSweep: [sweptHashes: Collection<string, HashData>];
+    invalidRequestWarning: [invalidRequestInfo: InvalidRequestWarningData];
+    rateLimited: [rateLimitInfo: RateLimitData];
+    response: [request: APIRequest, response: ResponseLike];
+    restDebug: [info: string];
+}
+type RestEventsMap = {
+    [K in keyof RestEvents]: RestEvents[K];
+};
+/**
+ * Options to be passed when creating the REST instance
+ */
+interface RESTOptions {
+    /**
+     * The agent to set globally
+     */
+    agent: Dispatcher | null;
+    /**
+     * The base api path, without version
+     *
+     * @defaultValue `'https://discord.com/api'`
+     */
+    api: string;
+    /**
+     * The authorization prefix to use for requests, useful if you want to use
+     * bearer tokens
+     *
+     * @defaultValue `'Bot'`
+     */
+    authPrefix: 'Bearer' | 'Bot';
+    /**
+     * The cdn path
+     *
+     * @defaultValue `'https://cdn.discordapp.com'`
+     */
+    cdn: string;
+    /**
+     * How many requests to allow sending per second (Infinity for unlimited, 50 for the standard global limit used by Discord)
+     *
+     * @defaultValue `50`
+     */
+    globalRequestsPerSecond: number;
+    /**
+     * The amount of time in milliseconds that passes between each hash sweep. (defaults to 1h)
+     *
+     * @defaultValue `3_600_000`
+     */
+    handlerSweepInterval: number;
+    /**
+     * The maximum amount of time a hash can exist in milliseconds without being hit with a request (defaults to 24h)
+     *
+     * @defaultValue `86_400_000`
+     */
+    hashLifetime: number;
+    /**
+     * The amount of time in milliseconds that passes between each hash sweep. (defaults to 4h)
+     *
+     * @defaultValue `14_400_000`
+     */
+    hashSweepInterval: number;
+    /**
+     * Additional headers to send for all API requests
+     *
+     * @defaultValue `{}`
+     */
+    headers: Record<string, string>;
+    /**
+     * The number of invalid REST requests (those that return 401, 403, or 429) in a 10 minute window between emitted warnings (0 for no warnings).
+     * That is, if set to 500, warnings will be emitted at invalid request number 500, 1000, 1500, and so on.
+     *
+     * @defaultValue `0`
+     */
+    invalidRequestWarningInterval: number;
+    /**
+     * The method called to perform the actual HTTP request given a url and web `fetch` options
+     * For example, to use global fetch, simply provide `makeRequest: fetch`
+     */
+    makeRequest(url: string, init: RequestInit): Promise<ResponseLike>;
+    /**
+     * The extra offset to add to rate limits in milliseconds
+     *
+     * @defaultValue `50`
+     */
+    offset: number;
+    /**
+     * Determines how rate limiting and pre-emptive throttling should be handled.
+     * When an array of strings, each element is treated as a prefix for the request route
+     * (e.g. `/channels` to match any route starting with `/channels` such as `/channels/:id/messages`)
+     * for which to throw {@link RateLimitError}s. All other request routes will be queued normally
+     *
+     * @defaultValue `null`
+     */
+    rejectOnRateLimit: RateLimitQueueFilter | string[] | null;
+    /**
+     * The number of retries for errors with the 500 code, or errors
+     * that timeout
+     *
+     * @defaultValue `3`
+     */
+    retries: number;
+    /**
+     * The time to wait in milliseconds before a request is aborted
+     *
+     * @defaultValue `15_000`
+     */
+    timeout: number;
+    /**
+     * Extra information to add to the user agent
+     *
+     * @defaultValue DefaultUserAgentAppendix
+     */
+    userAgentAppendix: string;
+    /**
+     * The version of the API to use
+     *
+     * @defaultValue `'10'`
+     */
+    version: string;
+}
+/**
+ * Data emitted on `RESTEvents.RateLimited`
+ */
+interface RateLimitData {
+    /**
+     * Whether the rate limit that was reached was the global limit
+     */
+    global: boolean;
+    /**
+     * The bucket hash for this request
+     */
+    hash: string;
+    /**
+     * The amount of requests we can perform before locking requests
+     */
+    limit: number;
+    /**
+     * The major parameter of the route
+     *
+     * For example, in `/channels/x`, this will be `x`.
+     * If there is no major parameter (e.g: `/bot/gateway`) this will be `global`.
+     */
+    majorParameter: string;
+    /**
+     * The HTTP method being performed
+     */
+    method: string;
+    /**
+     * The time, in milliseconds, that will need to pass before this specific request can be retried
+     */
+    retryAfter: number;
+    /**
+     * The route being hit in this request
+     */
+    route: string;
+    /**
+     * The time, in milliseconds, that will need to pass before the sublimit lock for the route resets, and requests that fall under a sublimit
+     * can be retried
+     *
+     * This is only present on certain sublimits, and `0` otherwise
+     */
+    sublimitTimeout: number;
+    /**
+     * The time, in milliseconds, until the route's request-lock is reset
+     */
+    timeToReset: number;
+    /**
+     * The full URL for this request
+     */
+    url: string;
+}
+/**
+ * A function that determines whether the rate limit hit should throw an Error
+ */
+type RateLimitQueueFilter = (rateLimitData: RateLimitData) => Awaitable<boolean>;
+interface APIRequest {
+    /**
+     * The data that was used to form the body of this request
+     */
+    data: HandlerRequestData;
+    /**
+     * The HTTP method used in this request
+     */
+    method: string;
+    /**
+     * Additional HTTP options for this request
+     */
+    options: RequestInit;
+    /**
+     * The full path used to make the request
+     */
+    path: RouteLike;
+    /**
+     * The number of times this request has been attempted
+     */
+    retries: number;
+    /**
+     * The API route identifying the ratelimit for this request
+     */
+    route: string;
+}
+interface ResponseLike extends Pick<Response, 'arrayBuffer' | 'bodyUsed' | 'headers' | 'json' | 'ok' | 'status' | 'statusText' | 'text'> {
+    body: Readable | ReadableStream | null;
+}
+interface InvalidRequestWarningData {
+    /**
+     * Number of invalid requests that have been made in the window
+     */
+    count: number;
+    /**
+     * Time in milliseconds remaining before the count resets
+     */
+    remainingTime: number;
+}
+/**
+ * Represents a file to be added to the request
+ */
+interface RawFile {
+    /**
+     * Content-Type of the file
+     */
+    contentType?: string;
+    /**
+     * The actual data for the file
+     */
+    data: Buffer | Uint8Array | boolean | number | string;
+    /**
+     * An explicit key to use for key of the formdata field for this file.
+     * When not provided, the index of the file in the files array is used in the form `files[${index}]`.
+     * If you wish to alter the placeholder snowflake, you must provide this property in the same form (`files[${placeholder}]`)
+     */
+    key?: string;
+    /**
+     * The name of the file
+     */
+    name: string;
+}
+/**
+ * Represents possible data to be given to an endpoint
+ */
+interface RequestData {
+    /**
+     * Whether to append JSON data to form data instead of `payload_json` when sending files
+     */
+    appendToFormData?: boolean;
+    /**
+     * If this request needs the `Authorization` header
+     *
+     * @defaultValue `true`
+     */
+    auth?: boolean;
+    /**
+     * The authorization prefix to use for this request, useful if you use this with bearer tokens
+     *
+     * @defaultValue `'Bot'`
+     */
+    authPrefix?: 'Bearer' | 'Bot';
+    /**
+     * The body to send to this request.
+     * If providing as BodyInit, set `passThroughBody: true`
+     */
+    body?: BodyInit | unknown;
+    /**
+     * The {@link https://undici.nodejs.org/#/docs/api/Agent | Agent} to use for the request.
+     */
+    dispatcher?: Agent;
+    /**
+     * Files to be attached to this request
+     */
+    files?: RawFile[] | undefined;
+    /**
+     * Additional headers to add to this request
+     */
+    headers?: Record<string, string>;
+    /**
+     * Whether to pass-through the body property directly to `fetch()`.
+     * <warn>This only applies when files is NOT present</warn>
+     */
+    passThroughBody?: boolean;
+    /**
+     * Query string parameters to append to the called endpoint
+     */
+    query?: URLSearchParams;
+    /**
+     * Reason to show in the audit logs
+     */
+    reason?: string | undefined;
+    /**
+     * The signal to abort the queue entry or the REST call, where applicable
+     */
+    signal?: AbortSignal | undefined;
+    /**
+     * If this request should be versioned
+     *
+     * @defaultValue `true`
+     */
+    versioned?: boolean;
+}
+/**
+ * Possible headers for an API call
+ */
+interface RequestHeaders {
+    Authorization?: string;
+    'User-Agent': string;
+    'X-Audit-Log-Reason'?: string;
+}
+/**
+ * Possible API methods to be used when doing requests
+ */
+declare enum RequestMethod {
+    Delete = "DELETE",
+    Get = "GET",
+    Patch = "PATCH",
+    Post = "POST",
+    Put = "PUT"
+}
+type RouteLike = `/${string}`;
+/**
+ * Internal request options
+ *
+ * @internal
+ */
+interface InternalRequest extends RequestData {
+    fullRoute: RouteLike;
+    method: RequestMethod;
+}
+type HandlerRequestData = Pick<InternalRequest, 'auth' | 'body' | 'files' | 'signal'>;
+/**
+ * Parsed route data for an endpoint
+ *
+ * @internal
+ */
+interface RouteData {
+    bucketRoute: string;
+    majorParameter: string;
+    original: RouteLike;
+}
+/**
+ * Represents a hash and its associated fields
+ *
+ * @internal
+ */
+interface HashData {
+    lastAccess: number;
+    value: string;
+}
 
 declare const DefaultUserAgent: `DiscordBot (https://discord.js.org, ${string})`;
 /**
@@ -519,9 +885,9 @@ declare function parseResponse(res: ResponseLike): Promise<unknown>;
 declare function calculateUserDefaultAvatarIndex(userId: Snowflake): number;
 
 /**
- * The {@link https://github.com/discordjs/discord.js/blob/main/packages/rest/#readme | @discordjs/rest} version
+ * The {@link https://github.com/discordjs/discord.js/blob/main/packages/rest#readme | @discordjs/rest} version
  * that you are currently using.
  */
 declare const version: string;
 
-export { ALLOWED_EXTENSIONS, ALLOWED_SIZES, ALLOWED_STICKER_EXTENSIONS, BaseImageURLOptions, BurstHandlerMajorIdKey, CDN, DEPRECATION_WARNING_PREFIX, DefaultRestOptions, DefaultUserAgent, DefaultUserAgentAppendix, DiscordAPIError, DiscordErrorData, HTTPError, HashData, ImageExtension, ImageSize, ImageURLOptions, InternalRequest, MakeURLOptions, OAuthErrorData, OverwrittenMimeTypes, REST, RESTEvents, RESTOptions, RateLimitData, RateLimitError, RawFile, RequestBody, RequestData, ResponseLike, RestEventsMap, RouteLike, StickerExtension, calculateUserDefaultAvatarIndex, makeURLSearchParams, parseResponse, version };
+export { ALLOWED_EXTENSIONS, ALLOWED_SIZES, ALLOWED_STICKER_EXTENSIONS, APIRequest, BaseImageURLOptions, BurstHandlerMajorIdKey, CDN, DEPRECATION_WARNING_PREFIX, DefaultRestOptions, DefaultUserAgent, DefaultUserAgentAppendix, DiscordAPIError, DiscordErrorData, HTTPError, HandlerRequestData, HashData, ImageExtension, ImageSize, ImageURLOptions, InternalRequest, InvalidRequestWarningData, MakeURLOptions, OAuthErrorData, OverwrittenMimeTypes, REST, RESTEvents, RESTOptions, RateLimitData, RateLimitError, RateLimitQueueFilter, RawFile, RequestBody, RequestData, RequestHeaders, RequestMethod, ResponseLike, RestEvents, RestEventsMap, RouteData, RouteLike, StickerExtension, calculateUserDefaultAvatarIndex, makeURLSearchParams, parseResponse, version };