seyfert 0.1.0

package/lib/api/errors/DiscordAPIError.js

@@ -0,0 +1,81 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiscordAPIError = void 0;
+function isErrorGroupWrapper(error) {
+    return Reflect.has(error, '_errors');
+}
+function isErrorResponse(error) {
+    return typeof Reflect.get(error, 'message') === 'string';
+}
+/**
+ * Represents an API error returned by Discord
+ */
+class DiscordAPIError extends Error {
+    rawError;
+    code;
+    status;
+    method;
+    url;
+    requestBody;
+    /**
+     * @param rawError - The error reported by Discord
+     * @param code - The error code reported by Discord
+     * @param status - The status code of the response
+     * @param method - The method of the request that erred
+     * @param url - The url of the request that erred
+     * @param bodyData - The unparsed data for the request that errored
+     */
+    constructor(rawError, code, status, method, url, bodyData) {
+        super(DiscordAPIError.getMessage(rawError));
+        this.rawError = rawError;
+        this.code = code;
+        this.status = status;
+        this.method = method;
+        this.url = url;
+        this.requestBody = { files: bodyData.files, json: bodyData.body };
+    }
+    /**
+     * The name of the error
+     */
+    get name() {
+        return `${DiscordAPIError.name}[${this.code}]`;
+    }
+    static getMessage(error) {
+        let flattened = '';
+        if ('code' in error) {
+            if (error.errors) {
+                flattened = [...this.flattenDiscordError(error.errors)].join('\n');
+            }
+            return error.message && flattened
+                ? `${error.message}\n${flattened}`
+                : error.message || flattened || 'Unknown Error';
+        }
+        return error.error_description ?? 'No Description';
+    }
+    static *flattenDiscordError(obj, key = '') {
+        if (isErrorResponse(obj)) {
+            return yield `${key.length ? `${key}[${obj.code}]` : `${obj.code}`}: ${obj.message}`.trim();
+        }
+        for (const [otherKey, val] of Object.entries(obj)) {
+            const nextKey = otherKey.startsWith('_')
+                ? key
+                : key
+                    ? Number.isNaN(Number(otherKey))
+                        ? `${key}.${otherKey}`
+                        : `${key}[${otherKey}]`
+                    : otherKey;
+            if (typeof val === 'string') {
+                yield val;
+            }
+            else if (isErrorGroupWrapper(val)) {
+                for (const error of val._errors) {
+                    yield* this.flattenDiscordError(error, nextKey);
+                }
+            }
+            else {
+                yield* this.flattenDiscordError(val, nextKey);
+            }
+        }
+    }
+}
+exports.DiscordAPIError = DiscordAPIError;

package/lib/api/errors/HTTPError.d.ts

@@ -0,0 +1,20 @@
+import type { InternalRequest } from '../utils/types.js';
+import type { RequestBody } from './DiscordAPIError.js';
+/**
+ * Represents a HTTP error
+ */
+export declare class HTTPError extends Error {
+    status: number;
+    method: string;
+    url: string;
+    requestBody: RequestBody;
+    name: string;
+    /**
+     * @param status - The status code of the response
+     * @param statusText - The status text of the response
+     * @param method - The method of the request that erred
+     * @param url - The url of the request that erred
+     * @param bodyData - The unparsed data for the request that errored
+     */
+    constructor(status: number, statusText: string, method: string, url: string, bodyData: Pick<InternalRequest, 'body' | 'files'>);
+}

package/lib/api/errors/HTTPError.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HTTPError = void 0;
+/**
+ * Represents a HTTP error
+ */
+class HTTPError extends Error {
+    status;
+    method;
+    url;
+    requestBody;
+    name = HTTPError.name;
+    /**
+     * @param status - The status code of the response
+     * @param statusText - The status text of the response
+     * @param method - The method of the request that erred
+     * @param url - The url of the request that erred
+     * @param bodyData - The unparsed data for the request that errored
+     */
+    constructor(status, statusText, method, url, bodyData) {
+        super(statusText);
+        this.status = status;
+        this.method = method;
+        this.url = url;
+        this.requestBody = { files: bodyData.files, json: bodyData.body };
+    }
+}
+exports.HTTPError = HTTPError;

package/lib/api/errors/RateLimitError.d.ts

@@ -0,0 +1,19 @@
+import type { RateLimitData } from '../utils/types.js';
+export declare class RateLimitError extends Error implements RateLimitData {
+    timeToReset: number;
+    limit: number;
+    method: string;
+    hash: string;
+    url: string;
+    route: string;
+    majorParameter: string;
+    global: boolean;
+    retryAfter: number;
+    sublimitTimeout: number;
+    scope: RateLimitData['scope'];
+    constructor({ timeToReset, limit, method, hash, url, route, majorParameter, global, retryAfter, sublimitTimeout, scope, }: RateLimitData);
+    /**
+     * The name of the error
+     */
+    get name(): string;
+}

package/lib/api/errors/RateLimitError.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitError = void 0;
+class RateLimitError extends Error {
+    timeToReset;
+    limit;
+    method;
+    hash;
+    url;
+    route;
+    majorParameter;
+    global;
+    retryAfter;
+    sublimitTimeout;
+    scope;
+    constructor({ timeToReset, limit, method, hash, url, route, majorParameter, global, retryAfter, sublimitTimeout, scope, }) {
+        super();
+        this.timeToReset = timeToReset;
+        this.limit = limit;
+        this.method = method;
+        this.hash = hash;
+        this.url = url;
+        this.route = route;
+        this.majorParameter = majorParameter;
+        this.global = global;
+        this.retryAfter = retryAfter;
+        this.sublimitTimeout = sublimitTimeout;
+        this.scope = scope;
+    }
+    /**
+     * The name of the error
+     */
+    get name() {
+        return `${RateLimitError.name}[${this.route}]`;
+    }
+}
+exports.RateLimitError = RateLimitError;

package/lib/api/handlers/BurstHandler.d.ts

@@ -0,0 +1,51 @@
+import type { RequestInit } from 'undici-types';
+import type { REST } from '../REST.js';
+import type { IHandler } from '../interfaces/Handler.js';
+import type { HandlerRequestData, ResponseLike, RouteData } from '../utils/types.js';
+/**
+ * The structure used to handle burst requests for a given bucket.
+ * Burst requests have no ratelimit handling but allow for pre- and post-processing
+ * of data in the same manner as sequentially queued requests.
+ *
+ * @remarks
+ * This queue may still emit a rate limit error if an unexpected 429 is hit
+ */
+export declare class BurstHandler implements IHandler {
+    private readonly manager;
+    private readonly hash;
+    private readonly majorParameter;
+    /**
+     * {@inheritdoc IHandler.id}
+     */
+    readonly id: string;
+    /**
+     * {@inheritDoc IHandler.inactive}
+     */
+    inactive: boolean;
+    /**
+     * @param manager - The request manager
+     * @param hash - The hash that this RequestHandler handles
+     * @param majorParameter - The major parameter for this handler
+     */
+    constructor(manager: REST, hash: string, majorParameter: string);
+    /**
+     * Emits a debug message
+     *
+     * @param message - The message to debug
+     */
+    private debug;
+    /**
+     * {@inheritDoc IHandler.queueRequest}
+     */
+    queueRequest(routeId: RouteData, url: string, options: RequestInit, requestData: HandlerRequestData): Promise<ResponseLike>;
+    /**
+     * The method that actually makes the request to the API, and updates info about the bucket accordingly
+     *
+     * @param routeId - The generalized API route with literal ids for major parameters
+     * @param url - The fully resolved URL to make the request to
+     * @param options - The fetch options needed to make the request
+     * @param requestData - Extra data from the user's request needed for errors and additional processing
+     * @param retries - The number of retries this request has already attempted (recursion)
+     */
+    private runRequest;
+}

package/lib/api/handlers/BurstHandler.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BurstHandler = void 0;
+const utils_js_1 = require("../utils/utils.js");
+const Shared_js_1 = require("./Shared.js");
+/**
+ * The structure used to handle burst requests for a given bucket.
+ * Burst requests have no ratelimit handling but allow for pre- and post-processing
+ * of data in the same manner as sequentially queued requests.
+ *
+ * @remarks
+ * This queue may still emit a rate limit error if an unexpected 429 is hit
+ */
+class BurstHandler {
+    manager;
+    hash;
+    majorParameter;
+    /**
+     * {@inheritdoc IHandler.id}
+     */
+    id;
+    /**
+     * {@inheritDoc IHandler.inactive}
+     */
+    inactive = false;
+    /**
+     * @param manager - The request manager
+     * @param hash - The hash that this RequestHandler handles
+     * @param majorParameter - The major parameter for this handler
+     */
+    constructor(manager, hash, majorParameter) {
+        this.manager = manager;
+        this.hash = hash;
+        this.majorParameter = majorParameter;
+        this.id = `${hash}:${majorParameter}`;
+    }
+    /**
+     * Emits a debug message
+     *
+     * @param message - The message to debug
+     */
+    debug(message) {
+        this.manager.debugger?.info(`#${this.id} ${message}`);
+    }
+    /**
+     * {@inheritDoc IHandler.queueRequest}
+     */
+    async queueRequest(routeId, url, options, requestData) {
+        return this.runRequest(routeId, url, options, requestData);
+    }
+    /**
+     * The method that actually makes the request to the API, and updates info about the bucket accordingly
+     *
+     * @param routeId - The generalized API route with literal ids for major parameters
+     * @param url - The fully resolved URL to make the request to
+     * @param options - The fetch options needed to make the request
+     * @param requestData - Extra data from the user's request needed for errors and additional processing
+     * @param retries - The number of retries this request has already attempted (recursion)
+     */
+    async runRequest(routeId, url, options, requestData, retries = 0) {
+        const method = options.method ?? 'get';
+        const res = await (0, Shared_js_1.makeNetworkRequest)(this.manager, routeId, url, options, requestData, retries);
+        // Retry requested
+        if (res === null) {
+            // eslint-disable-next-line no-param-reassign
+            return this.runRequest(routeId, url, options, requestData, ++retries);
+        }
+        const status = res.status;
+        let retryAfter = 0;
+        const retry = res.headers.get('Retry-After');
+        // Amount of time in milliseconds until we should retry if rate limited (globally or otherwise)
+        if (retry)
+            retryAfter = Number(retry) * 1_000 + this.manager.options.offset;
+        // Count the invalid requests
+        if (status === 401 || status === 403 || status === 429) {
+            (0, Shared_js_1.incrementInvalidCount)(this.manager);
+        }
+        if (status >= 200 && status < 300) {
+            return res;
+        }
+        if (status === 429) {
+            // Unexpected ratelimit
+            const isGlobal = res.headers.has('X-RateLimit-Global');
+            const scope = (res.headers.get('X-RateLimit-Scope') ?? 'user');
+            await (0, utils_js_1.onRateLimit)(this.manager, {
+                global: isGlobal,
+                method,
+                url,
+                route: routeId.bucketRoute,
+                majorParameter: this.majorParameter,
+                hash: this.hash,
+                limit: Number.POSITIVE_INFINITY,
+                timeToReset: retryAfter,
+                retryAfter,
+                sublimitTimeout: 0,
+                scope,
+            });
+            this.debug([
+                'Encountered unexpected 429 rate limit',
+                `  Global         : ${isGlobal}`,
+                `  Method         : ${method}`,
+                `  URL            : ${url}`,
+                `  Bucket         : ${routeId.bucketRoute}`,
+                `  Major parameter: ${routeId.majorParameter}`,
+                `  Hash           : ${this.hash}`,
+                `  Limit          : ${Number.POSITIVE_INFINITY}`,
+                `  Retry After    : ${retryAfter}ms`,
+                '  Sublimit       : None',
+                `  Scope          : ${scope}`,
+            ].join('\n'));
+            // We are bypassing all other limits, but an encountered limit should be respected (it's probably a non-punished rate limit anyways)
+            await (0, utils_js_1.sleep)(retryAfter);
+            // Since this is not a server side issue, the next request should pass, so we don't bump the retries counter
+            return this.runRequest(routeId, url, options, requestData, retries);
+        }
+        const handled = await (0, Shared_js_1.handleErrors)(this.manager, res, method, url, requestData, retries);
+        if (handled === null) {
+            // eslint-disable-next-line no-param-reassign
+            return this.runRequest(routeId, url, options, requestData, ++retries);
+        }
+        return handled;
+    }
+}
+exports.BurstHandler = BurstHandler;

package/lib/api/handlers/SequentialHandler.d.ts

@@ -0,0 +1,81 @@
+import type { RequestInit } from 'undici-types';
+import type { REST } from '../REST.js';
+import type { IHandler } from '../interfaces/Handler.js';
+import type { HandlerRequestData, ResponseLike, RouteData } from '../utils/types.js';
+/**
+ * The structure used to handle sequential requests for a given bucket
+ */
+export declare class SequentialHandler implements IHandler {
+    #private;
+    private readonly manager;
+    private readonly hash;
+    private readonly majorParameter;
+    /**
+     * {@inheritDoc IHandler.id}
+     */
+    readonly id: string;
+    /**
+     * The time this rate limit bucket will reset
+     */
+    private reset;
+    /**
+     * The remaining requests that can be made before we are rate limited
+     */
+    private remaining;
+    /**
+     * The total number of requests that can be made before we are rate limited
+     */
+    private limit;
+    /**
+     * @param manager - The request manager
+     * @param hash - The hash that this RequestHandler handles
+     * @param majorParameter - The major parameter for this handler
+     */
+    constructor(manager: REST, hash: string, majorParameter: string);
+    /**
+     * {@inheritDoc IHandler.inactive}
+     */
+    get inactive(): boolean;
+    /**
+     * If the rate limit bucket is currently limited by the global limit
+     */
+    private get globalLimited();
+    /**
+     * If the rate limit bucket is currently limited by its limit
+     */
+    private get localLimited();
+    /**
+     * If the rate limit bucket is currently limited
+     */
+    private get limited();
+    /**
+     * The time until queued requests can continue
+     */
+    private get timeToReset();
+    /**
+     * Emits a debug message
+     *
+     * @param message - The message to debug
+     */
+    private debug;
+    /**
+     * Delay all requests for the specified amount of time, handling global rate limits
+     *
+     * @param time - The amount of time to delay all requests for
+     */
+    private globalDelayFor;
+    /**
+     * {@inheritDoc IHandler.queueRequest}
+     */
+    queueRequest(routeId: RouteData, url: string, options: RequestInit, requestData: HandlerRequestData): Promise<ResponseLike>;
+    /**
+     * The method that actually makes the request to the api, and updates info about the bucket accordingly
+     *
+     * @param routeId - The generalized api route with literal ids for major parameters
+     * @param url - The fully resolved url to make the request to
+     * @param options - The fetch options needed to make the request
+     * @param requestData - Extra data from the user's request needed for errors and additional processing
+     * @param retries - The number of retries this request has already attempted (recursion)
+     */
+    private runRequest;
+}