seyfert 0.1.0

package/lib/api/utils/constants.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEPRECATION_WARNING_PREFIX = exports.BurstHandlerMajorIdKey = exports.OverwrittenMimeTypes = exports.ALLOWED_SIZES = exports.ALLOWED_STICKER_EXTENSIONS = exports.ALLOWED_EXTENSIONS = exports.RESTEvents = exports.DefaultRestOptions = exports.DefaultUserAgent = void 0;
+const common_1 = require("../../common");
+exports.DefaultUserAgent = 'DiscordBot (https://seyfert.com)';
+exports.DefaultRestOptions = {
+    agent: null,
+    api: common_1.BASE_URL,
+    authPrefix: 'Bot',
+    headers: {},
+    invalidRequestWarningInterval: 0,
+    globalRequestsPerSecond: 50,
+    offset: 50,
+    rejectOnRateLimit: null,
+    retries: 3,
+    timeout: 15_000,
+    version: common_1.APIVersion,
+    hashSweepInterval: 14_400_000, // 4 Hours
+    hashLifetime: 86_400_000, // 24 Hours
+    handlerSweepInterval: 3_600_000, // 1 Hour
+    makeRequest(url, init) {
+        return fetch(url, init);
+    },
+};
+/**
+ * The events that the REST manager emits
+ */
+var RESTEvents;
+(function (RESTEvents) {
+    RESTEvents["Debug"] = "restDebug";
+    RESTEvents["HandlerSweep"] = "handlerSweep";
+    RESTEvents["HashSweep"] = "hashSweep";
+    RESTEvents["InvalidRequestWarning"] = "invalidRequestWarning";
+    RESTEvents["RateLimited"] = "rateLimited";
+    RESTEvents["Response"] = "response";
+})(RESTEvents || (exports.RESTEvents = RESTEvents = {}));
+exports.ALLOWED_EXTENSIONS = ['webp', 'png', 'jpg', 'jpeg', 'gif'];
+exports.ALLOWED_STICKER_EXTENSIONS = ['png', 'json', 'gif'];
+exports.ALLOWED_SIZES = [16, 32, 64, 128, 256, 512, 1_024, 2_048, 4_096];
+exports.OverwrittenMimeTypes = {
+    // https://github.com/discordjs/discord.js/issues/8557
+    'image/apng': 'image/png',
+};
+exports.BurstHandlerMajorIdKey = 'burst';
+/**
+ * Prefix for deprecation warnings.
+ *
+ * @internal
+ */
+exports.DEPRECATION_WARNING_PREFIX = 'DeprecationWarning';

package/lib/api/utils/types.d.ts

@@ -0,0 +1,335 @@
+/// <reference types="node" />
+/// <reference types="node" />
+/// <reference types="node" />
+import type { Readable } from 'node:stream';
+import type { ReadableStream } from 'node:stream/web';
+import type { Agent, BodyInit, Dispatcher, RequestInit, Response } from 'undici-types';
+import type { Collection } from '../../collection';
+import type { MakeRequired } from '../../common';
+import type { IHandler } from '../interfaces/Handler';
+export 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];
+}
+export interface RestEventsMap extends RestEvents {
+}
+/**
+ * Options to be passed when creating the REST instance
+ */
+export 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';
+    /**
+     * 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;
+    /**
+     * Token of app
+     */
+    token: string;
+    debug?: boolean;
+}
+export type RESTConstructorOptions = MakeRequired<Partial<RESTOptions>, 'token'>;
+/**
+ * Data emitted on `RESTEvents.RateLimited`
+ */
+export 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 scope of the rate limit that was hit.
+     *
+     * This can be `user` for rate limits that are per client, `global` for rate limits that affect all clients or `shared` for rate limits that
+     * are shared per resource.
+     */
+    scope: 'global' | 'shared' | 'user';
+    /**
+     * 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;
+}
+export type Awaitable<Value> = PromiseLike<Value> | Value;
+/**
+ * A function that determines whether the rate limit hit should throw an Error
+ */
+export type RateLimitQueueFilter = (rateLimitData: RateLimitData) => Awaitable<boolean>;
+export 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;
+}
+export interface ResponseLike extends Pick<Response, 'arrayBuffer' | 'bodyUsed' | 'headers' | 'json' | 'ok' | 'status' | 'statusText' | 'text'> {
+    body: Readable | ReadableStream | null;
+}
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export interface RequestHeaders {
+    Authorization?: string;
+    'User-Agent': string;
+    'X-Audit-Log-Reason'?: string;
+}
+/**
+ * Possible API methods to be used when doing requests
+ */
+export declare enum RequestMethod {
+    Delete = "DELETE",
+    Get = "GET",
+    Patch = "PATCH",
+    Post = "POST",
+    Put = "PUT"
+}
+export type RouteLike = `/${string}`;
+export type HandlerRequestData = Pick<InternalRequest, 'auth' | 'body' | 'files' | 'signal'>;

package/lib/api/utils/types.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RequestMethod = void 0;
+/**
+ * Possible API methods to be used when doing requests
+ */
+var RequestMethod;
+(function (RequestMethod) {
+    RequestMethod["Delete"] = "DELETE";
+    RequestMethod["Get"] = "GET";
+    RequestMethod["Patch"] = "PATCH";
+    RequestMethod["Post"] = "POST";
+    RequestMethod["Put"] = "PUT";
+})(RequestMethod || (exports.RequestMethod = RequestMethod = {}));

package/lib/api/utils/utils.d.ts

@@ -0,0 +1,52 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import type { Snowflake } from 'discord-api-types/v10';
+import { type ResponseLike } from './types.js';
+/**
+ * Creates and populates an URLSearchParams instance from an object, stripping
+ * out null and undefined values, while also coercing non-strings to strings.
+ *
+ * @param options - The options to use
+ * @returns A populated URLSearchParams instance
+ */
+export declare function makeURLSearchParams<OptionsType extends object>(options?: Readonly<OptionsType>): URLSearchParams;
+/**
+ * Converts the response to usable data
+ *
+ * @param res - The fetch response
+ */
+export declare function parseResponse(res: ResponseLike): Promise<unknown>;
+/**
+ * Check whether a request falls under a sublimit
+ *
+ * @param bucketRoute - The buckets route identifier
+ * @param body - The options provided as JSON data
+ * @param method - The HTTP method that will be used to make the request
+ * @returns Whether the request falls under a sublimit
+ */
+export declare function hasSublimit(bucketRoute: string, body?: unknown, method?: string): boolean;
+/**
+ * Check whether an error indicates that a retry can be attempted
+ *
+ * @param error - The error thrown by the network request
+ * @returns Whether the error indicates a retry should be attempted
+ */
+export declare function shouldRetry(error: Error | NodeJS.ErrnoException): boolean;
+/**
+ * Calculates the default avatar index for a given user id.
+ *
+ * @param userId - The user id to calculate the default avatar index for
+ */
+export declare function calculateUserDefaultAvatarIndex(userId: Snowflake): number;
+/**
+ * Sleeps for a given amount of time.
+ *
+ * @param ms - The amount of time (in milliseconds) to sleep for
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Verifies that a value is a buffer-like object.
+ *
+ * @param value - The value to check
+ */
+export declare function isBufferLike(value: unknown): value is ArrayBuffer | Buffer | Uint8Array | Uint8ClampedArray;

package/lib/api/utils/utils.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deprecationWarning = exports.isBufferLike = exports.sleep = exports.calculateUserDefaultAvatarIndex = exports.onRateLimit = exports.shouldRetry = exports.hasSublimit = exports.parseResponse = exports.makeURLSearchParams = void 0;
+const RateLimitError_js_1 = require("../errors/RateLimitError.js");
+const constants_js_1 = require("./constants.js");
+const types_js_1 = require("./types.js");
+function serializeSearchParam(value) {
+    switch (typeof value) {
+        case 'string':
+            return value;
+        case 'number':
+        case 'bigint':
+        case 'boolean':
+            return value.toString();
+        case 'object':
+            if (value === null)
+                return null;
+            if (value instanceof Date) {
+                return Number.isNaN(value.getTime()) ? null : value.toISOString();
+            }
+            // eslint-disable-next-line @typescript-eslint/no-base-to-string
+            if (typeof value.toString === 'function' && value.toString !== Object.prototype.toString)
+                return value.toString();
+            return null;
+        default:
+            return null;
+    }
+}
+/**
+ * Creates and populates an URLSearchParams instance from an object, stripping
+ * out null and undefined values, while also coercing non-strings to strings.
+ *
+ * @param options - The options to use
+ * @returns A populated URLSearchParams instance
+ */
+function makeURLSearchParams(options) {
+    const params = new URLSearchParams();
+    if (!options)
+        return params;
+    for (const [key, value] of Object.entries(options)) {
+        const serialized = serializeSearchParam(value);
+        if (serialized !== null)
+            params.append(key, serialized);
+    }
+    return params;
+}
+exports.makeURLSearchParams = makeURLSearchParams;
+/**
+ * Converts the response to usable data
+ *
+ * @param res - The fetch response
+ */
+async function parseResponse(res) {
+    if (res.headers.get('Content-Type')?.startsWith('application/json')) {
+        return res.json();
+    }
+    return res.arrayBuffer();
+}
+exports.parseResponse = parseResponse;
+/**
+ * Check whether a request falls under a sublimit
+ *
+ * @param bucketRoute - The buckets route identifier
+ * @param body - The options provided as JSON data
+ * @param method - The HTTP method that will be used to make the request
+ * @returns Whether the request falls under a sublimit
+ */
+function hasSublimit(bucketRoute, body, method) {
+    // TODO: Update for new sublimits
+    // Currently known sublimits:
+    // Editing channel `name` or `topic`
+    if (bucketRoute === '/channels/:id') {
+        if (typeof body !== 'object' || body === null)
+            return false;
+        // This should never be a POST body, but just in case
+        if (method !== types_js_1.RequestMethod.Patch)
+            return false;
+        const castedBody = body;
+        return ['name', 'topic'].some(key => Reflect.has(castedBody, key));
+    }
+    // If we are checking if a request has a sublimit on a route not checked above, sublimit all requests to avoid a flood of 429s
+    return true;
+}
+exports.hasSublimit = hasSublimit;
+/**
+ * Check whether an error indicates that a retry can be attempted
+ *
+ * @param error - The error thrown by the network request
+ * @returns Whether the error indicates a retry should be attempted
+ */
+function shouldRetry(error) {
+    // Retry for possible timed out requests
+    if (error.name === 'AbortError')
+        return true;
+    // Downlevel ECONNRESET to retry as it may be recoverable
+    return ('code' in error && error.code === 'ECONNRESET') || error.message.includes('ECONNRESET');
+}
+exports.shouldRetry = shouldRetry;
+/**
+ * Determines whether the request should be queued or whether a RateLimitError should be thrown
+ *
+ * @internal
+ */
+async function onRateLimit(manager, rateLimitData) {
+    if (!manager.options.rejectOnRateLimit)
+        return;
+    const shouldThrow = typeof manager.options.rejectOnRateLimit === 'function'
+        ? await manager.options.rejectOnRateLimit(rateLimitData)
+        : manager.options.rejectOnRateLimit.some(route => rateLimitData.route.startsWith(route.toLowerCase()));
+    if (shouldThrow) {
+        throw new RateLimitError_js_1.RateLimitError(rateLimitData);
+    }
+}
+exports.onRateLimit = onRateLimit;
+/**
+ * Calculates the default avatar index for a given user id.
+ *
+ * @param userId - The user id to calculate the default avatar index for
+ */
+function calculateUserDefaultAvatarIndex(userId) {
+    return Number(BigInt(userId) >> 22n) % 6;
+}
+exports.calculateUserDefaultAvatarIndex = calculateUserDefaultAvatarIndex;
+/**
+ * Sleeps for a given amount of time.
+ *
+ * @param ms - The amount of time (in milliseconds) to sleep for
+ */
+async function sleep(ms) {
+    return new Promise(resolve => {
+        setTimeout(() => resolve(), ms);
+    });
+}
+exports.sleep = sleep;
+/**
+ * Verifies that a value is a buffer-like object.
+ *
+ * @param value - The value to check
+ */
+function isBufferLike(value) {
+    return value instanceof ArrayBuffer || value instanceof Uint8Array || value instanceof Uint8ClampedArray;
+}
+exports.isBufferLike = isBufferLike;
+/**
+ * Irrespective environment warning.
+ *
+ * @remarks Only the message is needed. The deprecation prefix is handled already.
+ * @param message - A string the warning will emit with
+ * @internal
+ */
+function deprecationWarning(message) {
+    if (typeof globalThis.process === 'undefined') {
+        console.warn(`${constants_js_1.DEPRECATION_WARNING_PREFIX}: ${message}`);
+    }
+    else {
+        process.emitWarning(message, constants_js_1.DEPRECATION_WARNING_PREFIX);
+    }
+}
+exports.deprecationWarning = deprecationWarning;

package/lib/builders/ActionRow.d.ts

@@ -0,0 +1,40 @@
+import { type APIActionRowComponent, type APIActionRowComponentTypes, type APIMessageActionRowComponent, type RestOrArray } from '../common';
+import { BaseComponentBuilder } from './Base';
+import type { BuilderComponents, FixedComponents } from './types';
+/**
+ * Represents an Action Row component in a message.
+ * @template T - The type of components in the Action Row.
+ */
+export declare class ActionRow<T extends BuilderComponents> extends BaseComponentBuilder<APIActionRowComponent<APIActionRowComponentTypes>> {
+    /**
+     * Creates a new instance of the ActionRow class.
+     * @param data - Optional data to initialize the Action Row.
+     * @example
+     * const actionRow = new ActionRow<Button>({ components: [buttonRawJSON] });
+     */
+    constructor({ components, ...data }?: Partial<APIActionRowComponent<APIActionRowComponentTypes>>);
+    components: FixedComponents<T>[];
+    /**
+     * Adds one or more components to the Action Row.
+     * @param component - The component(s) to add.
+     * @returns The updated Action Row instance.
+     * @example
+     * actionRow.addComponents(buttonComponent);
+     * actionRow.addComponents(buttonComponent1, buttonComponent2);
+     * actionRow.addComponents([buttonComponent1, buttonComponent2]);
+     */
+    addComponents(...component: RestOrArray<FixedComponents<T>>): this;
+    /**
+     * Sets the components of the Action Row.
+     * @param component - The components to set.
+     * @returns The updated Action Row instance.
+     * @example
+     * actionRow.setComponents([buttonComponent1, buttonComponent2]);
+     */
+    setComponents(component: FixedComponents<T>[]): this;
+    /**
+     * Converts the Action Row to its JSON representation.
+     * @returns The JSON representation of the Action Row.
+     */
+    toJSON(): APIActionRowComponent<APIMessageActionRowComponent>;
+}