snowtransfer 0.18.0 → 0.18.1

package/dist/RequestHandler.d.ts

@@ -0,0 +1,258 @@
+import { EventEmitter } from "node:events";
+import SM = require("./StateMachine");
+import type { HTTPMethod, RequestEventData, HandlerEvents } from "./Types";
+declare global {
+    var snowtransferDebugLogging: boolean;
+}
+/**
+ * @since 0.3.0
+ */
+export declare class DiscordAPIError extends Error {
+    method: string;
+    path: string;
+    code: number;
+    httpStatus: number;
+    request: RequestEventData;
+    response: Response;
+    constructor(error: {
+        message?: string;
+        code?: number;
+    }, request: RequestEventData, response: Response);
+}
+/**
+ * @since 0.17.0
+ */
+export interface Counter {
+    id: string;
+    /**
+     * Like new.
+     * @since 0.17.0
+     */
+    hasReset(): boolean;
+    /**
+     * Returns true only if the caller is allowed to call take() and then consume a function.
+     * @since 0.17.0
+     */
+    canTake(): boolean;
+    /**
+     * Take a use out of the counter
+     * @since 0.17.0
+     */
+    take(): boolean;
+    /** @since 0.17.0 */
+    timeUntilReset(): number;
+    /** @since 0.17.0 */
+    responseReceived(): void;
+    /** @since 0.17.0 */
+    applyCount(limit: number | null, remaining: number, resetAfter: number): void;
+}
+/**
+ * @since 0.17.0
+ */
+export declare class IntervalCounter implements Counter {
+    limit: number;
+    reset: number;
+    /**
+     * Remaining amount of executions during the current timeframe
+     */
+    remaining: number;
+    private firstRequestTime;
+    private resetAt;
+    readonly id: string;
+    /**
+     * Create a new base bucket
+     * @param limit Number of functions that may be executed during the timeframe set in reset
+     * @param reset Timeframe in milliseconds until the ratelimit resets after first
+     */
+    constructor(limit: number, reset: number);
+    private checkReset;
+    hasReset(): boolean;
+    canTake(): boolean;
+    take(): boolean;
+    timeUntilReset(): number;
+    responseReceived(): void;
+    applyCount(limit: number | null, remaining: number, resetAfter: number): void;
+}
+/**
+ * @since 0.17.0
+ */
+export declare class LeakyCounter implements Counter {
+    limit: number;
+    /**
+     * Remaining amount of executions during the current timeframe
+     */
+    remaining: number;
+    private resetAt;
+    readonly id: string;
+    /**
+     * Create a new base bucket
+     * @param limit Number of functions that may be executed until some are reset
+     */
+    constructor(limit: number);
+    private checkReset;
+    hasReset(): boolean;
+    canTake(): boolean;
+    take(): boolean;
+    timeUntilReset(): number;
+    responseReceived(): void;
+    applyCount(limit: number | null, remaining: number, resetAfter: number): void;
+}
+/**
+ * Bucket used for saving ratelimits
+ * @since 0.1.0
+ */
+export declare class Bucket {
+    /** Tracks the state this bucket is in (blocked, running, waiting, etc) and what operations are allowed. */
+    readonly sm: SM;
+    /** Wrapped functions which always resolve (not reject) after the original function has completed and resolved. The original function may manipulate rate limit buckets in that time before it resolves. */
+    readonly calls: Array<() => any>;
+    /** The backing counters of the bucket that determine how many functions can be consumed in a timeframe. */
+    readonly counters: Array<Counter>;
+    private pauseRequested;
+    /**
+     * Create a new bucket
+     */
+    constructor(counters: Array<Counter>);
+    /**
+     * Queue a function to be executed
+     * @since 0.12.0
+     * @param fn function to be executed
+     * @returns Result of the function if any
+     */
+    enqueue<T>(fn: (bkt: this) => Promise<T>): Promise<T>;
+    /**
+     * Pause the bucket from consuming more functions until resumed
+     * @since 0.16.0
+     */
+    pause(): void;
+    /**
+     * If the bucket is paused, resume it
+     * @since 0.16.0
+     */
+    resume(): void;
+    /**
+     * Clear the current queue of events to be sent
+     * @since 0.1.0
+     */
+    dropQueue(): void;
+}
+/**
+ * Ratelimiter used for handling the ratelimits imposed by the rest api
+ * @since 0.1.0
+ */
+export declare class Ratelimiter {
+    /**
+     * A Map of Buckets keyed by route keys that store rate limit info
+     */
+    readonly buckets: Map<string, Bucket>;
+    /**
+     * The bucket that limits how many requests per second you can make globally
+     */
+    readonly globalBucket: Bucket;
+    /**
+     * If you're being globally rate limited
+     */
+    get global(): boolean;
+    constructor();
+    /**
+     * Returns a key for saving ratelimits for routes
+     * (Taken from https://github.com/abalabahaha/eris/blob/master/lib/rest/RequestHandler.js) -> I luv u abal <3
+     * @since 0.1.0
+     * @param url url to reduce to a key something like /channels/266277541646434305/messages/266277541646434305/
+     * @param method method of the request, usual http methods like get, etc.
+     * @returns reduced url: /channels/266277541646434305/messages/:id/
+     */
+    routify(url: string, method: string): string;
+    /**
+     * Choose a bucket from the route and enqueue a rest call in it
+     * @since 0.1.0
+     * @param fn function to call once the ratelimit is ready
+     * @param url Endpoint of the request
+     * @param method Http method used by the request
+     */
+    queue<T>(fn: (bucket: Bucket) => Promise<T>, url: string, method: string): Promise<T>;
+    /**
+     * Set if this Ratelimiter is hitting a global ratelimit for `ms` duration
+     * @since 0.12.0
+     * @param ms How long in milliseconds this Ratelimiter is globally ratelimited for
+     */
+    setGlobal(ms: number): void;
+}
+export type RequestHandlerOptions = {
+    /** The base URL to use when making requests. Defaults to https://discord.com */
+    baseHost: string;
+    /** The base path of the base URL to use for the API. Defaults to /api/v${Constants.REST_API_VERSION} */
+    baseURL: string;
+    /** If rate limit buckets should be ignored */
+    bypassBuckets: boolean;
+    /** If failed requests that can be retried should be retried, up to retryLimit times. */
+    retryFailed: boolean;
+    /** How many times requests should be retried if they fail and can be retried. */
+    retryLimit: number;
+    headers: {
+        Authorization?: string;
+        "User-Agent": string;
+        [header: string]: string | undefined;
+    };
+    fetch: typeof globalThis.fetch;
+};
+/**
+ * Request Handler class
+ * @since 0.1.0
+ */
+export declare class RequestHandler extends EventEmitter<HandlerEvents> {
+    ratelimiter: Ratelimiter;
+    options: RequestHandlerOptions;
+    latency: number;
+    apiURL: string;
+    /**
+     * Create a new request handler
+     * @param ratelimiter ratelimiter to use for ratelimiting requests
+     * @param options options
+     */
+    constructor(ratelimiter: Ratelimiter, options?: {
+        token?: string;
+    } & Partial<Omit<RequestHandlerOptions, "headers">>);
+    /**
+     * Request a route from the discord api
+     * @since 0.1.0
+     * @param endpoint endpoint to request
+     * @param params URL query parameters to add on to the URL
+     * @param method http method to use
+     * @param dataType type of the data being sent
+     * @param data data to send, if any
+     * @param extraHeaders Any headers to send on top of the existing ones for this request
+     * @param retries How many retries should be performed for this request if it fails when possible and not a bad status code is returned
+     * @param rawResponse If the raw Response Object from fetch should be returned instead of trying to return a response.json() or undefined if no body
+     * @returns Result of the request
+     */
+    request(endpoint: string, params: Record<string, any> | undefined, method: HTTPMethod, dataType: "json", data?: any, extraHeaders?: Record<string, string>, retries?: number, rawResponse?: boolean): Promise<any>;
+    request(endpoint: string, params: Record<string, any> | undefined, method: HTTPMethod, dataType: "multipart", data?: FormData, extraHeaders?: Record<string, string>, retries?: number, rawResponse?: boolean): Promise<any>;
+    request(endpoint: string, params: Record<string, any> | undefined, method: HTTPMethod, dataType: "json" | "multipart", data?: any, extraHeaders?: Record<string, string>, retries?: number, rawResponse?: true): Promise<Response>;
+    /**
+     * Apply the received ratelimit headers to the ratelimit bucket
+     * @since 0.1.0
+     * @param bkt Ratelimit bucket to apply the headers to
+     * @param headers Http headers received from discord
+     */
+    private _applyRatelimitHeaders;
+    /**
+     * Execute a normal json request
+     * @since 0.1.0
+     * @param endpoint Endpoint to use
+     * @param params URL query parameters to add on to the URL
+     * @param data Data to send
+     * @returns Result of the request
+     */
+    private _request;
+    /**
+     * Execute a multipart/form-data request
+     * @since 0.1.0
+     * @param endpoint Endpoint to use
+     * @param params URL query parameters to add on to the URL
+     * @param method Http Method to use
+     * @param data data to send
+     * @returns Result of the request
+     */
+    private _multiPartRequest;
+}