seyfert 4.4.1 → 4.6.0

package/lib/api/api.js

@@ -8,11 +8,32 @@ const bucket_1 = require("./bucket");
 const Router_1 = require("./Router");
 const shared_1 = require("./shared");
 const utils_2 = require("./utils/utils");
+// JavaScript timers use a signed 32-bit millisecond delay.
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const MAX_BUCKET_RESET_DELAY_MS = MAX_TIMER_DELAY_MS - 1;
+const MAX_SMART_BUCKET_RESET_AFTER_MS = Math.floor(MAX_TIMER_DELAY_MS / 1.5);
+function parseRateLimitCount(raw, minimum) {
+    if (raw === null)
+        return;
+    if (!/^\d+$/.test(raw))
+        return null;
+    const value = Number(raw);
+    return Number.isSafeInteger(value) && value >= minimum ? value : null;
+}
+function parseRateLimitDelay(value) {
+    if (value === null || (typeof value === 'string' && value.trim() === ''))
+        return;
+    const milliseconds = Number(value) * 1000;
+    return Number.isFinite(milliseconds) && milliseconds >= 0 ? milliseconds : undefined;
+}
 class ApiHandler {
     options;
     globalBlock = false;
     ratelimits = new Map();
     readyQueue = [];
+    bucketAliases = new Map();
+    globalBlocks = new Map();
+    globalTimers = new Map();
     cdn = Router_1.CDNRouter.createProxy();
     workerPromises;
     onRatelimit;
@@ -70,6 +91,14 @@ class ApiHandler {
         return (this._proxy_ ??= new Router_1.Router(this).createProxy());
     }
     globalUnblock() {
+        for (const timer of this.globalTimers.values())
+            clearTimeout(timer);
+        this.globalTimers.clear();
+        for (const queue of this.globalBlocks.values()) {
+            for (const callback of queue)
+                callback();
+        }
+        this.globalBlocks.clear();
         this.globalBlock = false;
         let cb;
         while ((cb = this.readyQueue.shift())) {
@@ -107,7 +136,11 @@ class ApiHandler {
             this.debugger?.warn('onFailRequest callback error', callbackError);
         }
     }
-    async request(method, url, { auth = true, ...request } = {}) {
+    async request(method, url, request = {}) {
+        const requestOptions = { ...request };
+        const { auth = true } = requestOptions;
+        let attempts = requestOptions._50xRetries ?? 0;
+        delete requestOptions._50xRetries;
         const originTrace = {};
         Error.captureStackTrace(originTrace, this.request);
         if (this.options.workerProxy) {
@@ -118,11 +151,12 @@ class ApiHandler {
                 type: 'WORKER_API_REQUEST',
                 workerId: this.workerData.workerId,
                 nonce,
-                requestOptions: { auth, ...request },
+                requestOptions: { auth, ...requestOptions },
             });
         }
-        const route = request.route || this.routefy(url, method);
-        let attempts = 0;
+        const route = requestOptions.route || this.routefy(url, method);
+        const provisionalRoute = requestOptions.route || `${method}:${route}`;
+        let bucketRoute = this.bucketAliases.get(provisionalRoute) ?? provisionalRoute;
         const callback = async (next, resolve, reject) => {
             const headers = {
                 'User-Agent': this.options.userAgent,
@@ -130,7 +164,7 @@ class ApiHandler {
             const { data, finalUrl } = this.parseRequest({
                 url,
                 headers,
-                request: { ...request, auth },
+                request: { ...requestOptions, auth },
             });
             let response;
             try {
@@ -152,77 +186,105 @@ class ApiHandler {
             }
             const now = Date.now();
             const headerNow = Date.parse(response.headers.get('date') ?? '');
-            this.setRatelimitsBucket(route, response);
-            this.setResetBucket(route, response, now, headerNow);
-            let result = await response.text();
+            bucketRoute = this.learnBucket(provisionalRoute, bucketRoute, url, response, requestOptions.route !== undefined);
+            this.setRatelimitsBucket(bucketRoute, response);
+            this.setResetBucket(bucketRoute, response, now, headerNow, route);
+            this.ratelimits.get(bucketRoute).process();
+            const needsObserverBody = (response.status < 300 && this.onSuccessRequest !== undefined) ||
+                (response.status === 429 && this.onRatelimit !== undefined);
+            const observerResponse = needsObserverBody ? response.clone() : response;
+            let result;
+            try {
+                result = await decodeResponse(response);
+            }
+            catch (error) {
+                await this.notifyFailRequest(method, finalUrl, error, response.status);
+                next();
+                reject(error);
+                return;
+            }
             if (response.status >= 300) {
+                const errorResult = normalizeErrorResult(result);
                 if (response.status === 429) {
-                    const result429 = await this.handle429(route, method, url, request, response, result, next, reject, now);
+                    const result429 = await this.handle429(bucketRoute, method, url, { ...requestOptions, auth }, observerResponse, typeof errorResult === 'string' ? errorResult : JSON.stringify(errorResult), next, reject, now);
                     if (result429 !== false)
                         return resolve(result429);
-                    await this.notifyFailRequest(method, finalUrl, result, response.status);
-                    return this.clearResetInterval(route);
+                    await this.notifyFailRequest(method, finalUrl, errorResult, response.status);
+                    return this.clearResetInterval(bucketRoute);
                 }
                 if ([502, 503].includes(response.status) && ++attempts < 4) {
-                    this.clearResetInterval(route);
-                    return this.handle50X(method, url, request, next);
+                    this.clearResetInterval(bucketRoute);
+                    return this.handle50X(method, url, requestOptions, attempts, next, resolve, reject);
                 }
-                this.clearResetInterval(route);
+                this.clearResetInterval(bucketRoute);
                 next();
-                if (result.length > 0) {
-                    if (response.headers.get('content-type')?.includes('application/json')) {
-                        try {
-                            result = JSON.parse(result);
-                        }
-                        catch (err) {
-                            this.debugger?.warn('SeyfertError parsing result error (', result, ')', err);
-                            await this.notifyFailRequest(method, finalUrl, err, response.status);
-                            reject(err);
-                            return;
-                        }
-                    }
-                }
-                const parsedError = this.parseError(method, route, response, result, originTrace);
+                const parsedError = this.parseError(method, route, response, errorResult, originTrace);
                 this.debugger?.warn(parsedError.message);
                 await this.notifyFailRequest(method, finalUrl, parsedError, response.status);
                 reject(parsedError);
                 return;
             }
-            if (result.length > 0) {
-                if (response.headers.get('content-type')?.includes('application/json')) {
-                    try {
-                        result = JSON.parse(result);
-                    }
-                    catch (err) {
-                        this.debugger?.warn('Failed parsing result (', result, ')', err);
-                        await this.notifyFailRequest(method, finalUrl, err, response.status);
-                        next();
-                        reject(err);
-                        return;
-                    }
-                }
-            }
-            await this.notifySuccessRequest(method, finalUrl, response);
+            await this.notifySuccessRequest(method, finalUrl, observerResponse);
             next();
-            return resolve(result || undefined);
+            return resolve(result);
         };
         return new Promise((resolve, reject) => {
-            if (this.globalBlock && auth) {
-                this.readyQueue.push(() => {
-                    if (!this.ratelimits.has(route)) {
-                        this.ratelimits.set(route, new bucket_1.Bucket(1));
-                    }
-                    this.ratelimits.get(route).push({ next: callback, resolve, reject }, request.unshift);
-                });
+            const dispatch = () => {
+                bucketRoute = this.bucketAliases.get(provisionalRoute) ?? bucketRoute;
+                if (!this.ratelimits.has(bucketRoute)) {
+                    this.ratelimits.set(bucketRoute, new bucket_1.Bucket(1));
+                }
+                this.ratelimits.get(bucketRoute).push({ next: callback, resolve, reject }, requestOptions.unshift);
+            };
+            const globalQueue = this.globalBlocks.get(this.globalRateLimitKey({ ...requestOptions, auth }));
+            if (globalQueue && !url.startsWith('/interactions/')) {
+                globalQueue.push(dispatch);
             }
             else {
-                if (!this.ratelimits.has(route)) {
-                    this.ratelimits.set(route, new bucket_1.Bucket(1));
-                }
-                this.ratelimits.get(route).push({ next: callback, resolve, reject }, request.unshift);
+                dispatch();
             }
         });
     }
+    learnBucket(provisionalRoute, currentRoute, url, response, hasRouteOverride) {
+        const hash = response.headers.get('x-ratelimit-bucket');
+        if (!hash || hasRouteOverride)
+            return currentRoute;
+        const learnedRoute = `${hash}:${majorParameter(url)}`;
+        this.bucketAliases.set(provisionalRoute, learnedRoute);
+        const currentBucket = this.ratelimits.get(currentRoute);
+        const learnedBucket = this.ratelimits.get(learnedRoute);
+        if (!learnedBucket) {
+            this.ratelimits.set(learnedRoute, currentBucket);
+            return learnedRoute;
+        }
+        if (learnedBucket !== currentBucket && currentBucket.queue.length) {
+            learnedBucket.queue.push(...currentBucket.queue.splice(0));
+        }
+        return learnedRoute;
+    }
+    globalRateLimitKey(request) {
+        if (request.auth === false)
+            return 'unauthenticated';
+        return `${this.options.type}:${request.token || this.options.token}`;
+    }
+    blockGlobal(request, retryAfter) {
+        const key = this.globalRateLimitKey(request);
+        if (!this.globalBlocks.has(key))
+            this.globalBlocks.set(key, []);
+        const previousTimer = this.globalTimers.get(key);
+        if (previousTimer)
+            clearTimeout(previousTimer);
+        this.globalBlock = true;
+        this.globalTimers.set(key, setTimeout(() => this.unblockGlobal(key), retryAfter || 1));
+    }
+    unblockGlobal(key) {
+        this.globalTimers.delete(key);
+        const queue = this.globalBlocks.get(key) ?? [];
+        this.globalBlocks.delete(key);
+        this.globalBlock = this.globalBlocks.size > 0;
+        for (const callback of queue)
+            callback();
+    }
     parseError(method, route, response, result, originTrace) {
         let errMessage = '';
         let code;
@@ -279,29 +341,50 @@ class ApiHandler {
         }
         return errors;
     }
-    async handle50X(method, url, request, next) {
+    async handle50X(method, url, request, attempts, next = () => { }, resolve, reject) {
+        const retryAttempt = typeof attempts === 'number' ? attempts : 0;
+        const callback = typeof attempts === 'function' ? attempts : next;
+        const requestOptions = {
+            ...request,
+            unshift: true,
+            ...(retryAttempt > 0 ? { _50xRetries: retryAttempt } : {}),
+        };
         const wait = Math.floor(Math.random() * 1900 + 100);
         this.debugger?.warn(`Handling a 50X status, retrying in ${wait}ms`);
-        next();
+        callback();
         await (0, common_1.delay)(wait);
-        return this.request(method, url, {
-            body: request.body,
-            auth: request.auth,
-            reason: request.reason,
-            route: request.route,
-            unshift: true,
+        return this.request(method, url, requestOptions)
+            .then(value => {
+            resolve?.(value);
+            return value;
+        })
+            .catch(error => {
+            reject?.(error);
         });
     }
     async handle429(route, method, url, request, response, result, next, reject, now) {
-        await this.onRatelimit?.(response, request);
         const bucket = this.ratelimits.get(route);
         let retryAfter;
-        const data = JSON.parse(result);
-        if (data.retry_after)
-            retryAfter = Math.ceil(data.retry_after * 1000);
-        retryAfter ??=
-            Number(response.headers.get('x-ratelimit-reset-after') || response.headers.get('retry-after')) * 1000;
-        if (Number.isNaN(retryAfter)) {
+        let data;
+        try {
+            const parsed = JSON.parse(result);
+            if (isPlainObject(parsed))
+                data = parsed;
+        }
+        catch { }
+        if (typeof data?.retry_after === 'number') {
+            const value = parseRateLimitDelay(data.retry_after);
+            if (value !== undefined && value <= MAX_TIMER_DELAY_MS)
+                retryAfter = Math.ceil(value);
+        }
+        for (const header of ['retry-after', 'x-ratelimit-reset-after']) {
+            if (retryAfter !== undefined)
+                break;
+            const value = parseRateLimitDelay(response.headers.get(header));
+            if (value !== undefined && value <= MAX_TIMER_DELAY_MS)
+                retryAfter = value;
+        }
+        if (retryAfter === undefined) {
             this.debugger?.warn(`${route} Could not extract retry_after from 429 response. ${result}`);
             next();
             reject(new common_1.SeyfertError('INVALID_RETRY_AFTER', {
@@ -317,71 +400,75 @@ class ApiHandler {
             }));
             return false;
         }
+        if (data?.global === true ||
+            response.headers.has('x-ratelimit-global') ||
+            response.headers.get('x-ratelimit-scope') === 'global') {
+            this.blockGlobal(request, retryAfter);
+        }
+        await this.onRatelimit?.(response, request);
         if (this.debugger) {
             const content = `${JSON.stringify(request)} `;
             this.debugger.info(`${response.headers.get('x-ratelimit-global') ? 'Global' : 'Unexpected'} 429: ${result.slice(0, 256)}\n${content} ${now} ${route} ${response.status}: ${bucket.remaining}/${bucket.limit} left | Reset ${retryAfter} (${bucket.reset - now}ms left) | Scope ${response.headers.get('x-ratelimit-scope')}`);
         }
-        if (retryAfter) {
+        if (retryAfter)
             await (0, common_1.delay)(retryAfter);
-            next();
-            return this.request(method, url, {
-                body: request.body,
-                auth: request.auth,
-                reason: request.reason,
-                route: request.route,
-                unshift: true,
-            });
-        }
-        next();
-        return this.request(method, url, {
-            body: request.body,
-            auth: request.auth,
-            reason: request.reason,
-            route: request.route,
+        const retry = this.request(method, url, {
+            ...request,
             unshift: true,
         });
+        next();
+        return retry.catch(reject);
     }
     clearResetInterval(route) {
         clearInterval(this.ratelimits.get(route).processingResetAfter);
         this.ratelimits.get(route).processingResetAfter = undefined;
         this.ratelimits.get(route).resetAfter = 0;
     }
-    setResetBucket(route, resp, now, headerNow) {
-        const retryAfter = Number(resp.headers.get('x-ratelimit-reset-after') || resp.headers.get('retry-after')) * 1000;
-        if (retryAfter >= 0) {
-            if (resp.headers.get('x-ratelimit-global')) {
-                this.globalBlock = true;
-                setTimeout(() => this.globalUnblock(), retryAfter || 1);
-            }
-            else {
-                this.ratelimits.get(route).reset = (retryAfter || 1) + now;
-            }
+    setResetBucket(route, resp, now, headerNow, normalizedRoute = route) {
+        const bucket = this.ratelimits.get(route);
+        const retryAfterHeader = resp.headers.get('x-ratelimit-reset-after') ?? resp.headers.get('retry-after');
+        const retryAfter = parseRateLimitDelay(retryAfterHeader);
+        if (retryAfter !== undefined) {
+            bucket.reset = Math.min(retryAfter || 1, MAX_BUCKET_RESET_DELAY_MS) + now;
         }
-        else if (resp.headers.get('x-ratelimit-reset')) {
-            let resetTime = +resp.headers.get('x-ratelimit-reset') * 1000;
-            if (route.endsWith('/reactions/:id') && +resp.headers.get('x-ratelimit-reset') * 1000 - headerNow === 1000) {
+        else {
+            const resetHeader = resp.headers.get('x-ratelimit-reset');
+            const parsedReset = parseRateLimitDelay(resetHeader);
+            if (parsedReset === undefined) {
+                if (retryAfterHeader === null && resetHeader === null)
+                    bucket.reset = now;
+                return;
+            }
+            let resetTime = parsedReset;
+            if (normalizedRoute.endsWith('/reactions/:id') && resetTime - headerNow === 1000) {
                 resetTime = now + 250;
             }
-            this.ratelimits.get(route).reset = Math.max(resetTime, now);
-        }
-        else {
-            this.ratelimits.get(route).reset = now;
+            bucket.reset = Math.min(Math.max(resetTime, now), now + MAX_BUCKET_RESET_DELAY_MS);
         }
     }
     setRatelimitsBucket(route, resp) {
-        if (resp.headers.has('x-ratelimit-limit')) {
-            this.ratelimits.get(route).limit = +resp.headers.get('x-ratelimit-limit');
+        const bucket = this.ratelimits.get(route);
+        const limit = parseRateLimitCount(resp.headers.get('x-ratelimit-limit'), 1);
+        const remaining = parseRateLimitCount(resp.headers.get('x-ratelimit-remaining'), 0);
+        if (limit !== null && limit !== undefined) {
+            bucket.limit = limit;
+            bucket.remaining = Math.min(bucket.remaining, limit);
+        }
+        if (remaining === undefined) {
+            bucket.remaining = Math.min(1, bucket.limit);
+        }
+        else if (remaining !== null) {
+            bucket.remaining = Math.min(remaining, bucket.limit);
         }
-        this.ratelimits.get(route).remaining =
-            resp.headers.get('x-ratelimit-remaining') === undefined ? 1 : +resp.headers.get('x-ratelimit-remaining');
         if (this.options.smartBucket) {
-            if (resp.headers.has('x-ratelimit-reset-after') &&
-                !this.ratelimits.get(route).resetAfter &&
-                Number(resp.headers.get('x-ratelimit-limit')) === Number(resp.headers.get('x-ratelimit-remaining')) + 1) {
-                this.ratelimits.get(route).resetAfter = +resp.headers.get('x-ratelimit-reset-after') * 1000;
+            if (typeof limit === 'number' && typeof remaining === 'number' && !bucket.resetAfter && limit === remaining + 1) {
+                const resetAfter = parseRateLimitDelay(resp.headers.get('x-ratelimit-reset-after'));
+                if (resetAfter !== undefined && resetAfter <= MAX_SMART_BUCKET_RESET_AFTER_MS) {
+                    bucket.resetAfter = resetAfter;
+                }
             }
-            if (this.ratelimits.get(route).resetAfter && !this.ratelimits.get(route).remaining) {
-                this.ratelimits.get(route).triggerResetAfter();
+            if (bucket.resetAfter && !bucket.remaining) {
+                bucket.triggerResetAfter();
             }
         }
     }
@@ -394,8 +481,12 @@ class ApiHandler {
         if (options.request.query) {
             const params = new URLSearchParams();
             for (const [key, value] of Object.entries(options.request.query)) {
+                if (value === null || value === undefined)
+                    continue;
                 if (Array.isArray(value)) {
                     for (const item of value) {
+                        if (item === null || item === undefined)
+                            continue;
                         params.append(key, String(item));
                     }
                 }
@@ -403,7 +494,9 @@ class ApiHandler {
                     params.append(key, String(value));
                 }
             }
-            finalUrl += `?${params}`;
+            const query = params.toString();
+            if (query)
+                finalUrl += `${finalUrl.includes('?') ? '&' : '?'}${query}`;
         }
         if (options.request.files?.length || options.request.appendToFormData) {
             const formData = new FormData();
@@ -471,3 +564,39 @@ class ApiHandler {
     }
 }
 exports.ApiHandler = ApiHandler;
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function normalizeErrorResult(result) {
+    if (typeof result === 'string' || isPlainObject(result))
+        return result;
+    return JSON.stringify(result) ?? String(result);
+}
+async function decodeResponse(response) {
+    const contentType = response.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase();
+    if (response.status < 300 && contentType && !contentType.startsWith('text/') && !isJsonContentType(contentType)) {
+        return response.arrayBuffer();
+    }
+    const text = await response.text();
+    if (!text.length)
+        return undefined;
+    return isJsonContentType(contentType) ? JSON.parse(text) : text;
+}
+function isJsonContentType(contentType) {
+    return contentType === 'application/json' || contentType?.endsWith('+json') === true;
+}
+function majorParameter(url) {
+    const channel = url.match(/^\/channels\/([^/]+)/)?.[1];
+    if (channel)
+        return `channels:${channel}`;
+    const guild = url.match(/^\/guilds\/([^/]+)/)?.[1];
+    if (guild)
+        return `guilds:${guild}`;
+    const webhook = url.match(/^\/webhooks\/([^/]+)(?:\/([^/?]+))?/)?.slice(1);
+    if (webhook?.[0])
+        return `webhooks:${webhook.filter(Boolean).join(':')}`;
+    return '';
+}

package/lib/api/bucket.js

@@ -35,7 +35,7 @@ class Bucket {
             this.processing = setTimeout(() => {
                 this.processing = false;
                 this.process(true);
-            }, this.resetAfter ? 0.5 : Math.max(0, (this.reset || 0) - now) + 1);
+            }, Math.max(0, (this.reset || 0) - now) + 1);
             return;
         }
         --this.remaining;
@@ -60,12 +60,18 @@ class Bucket {
         this.process();
     }
     triggerResetAfter() {
-        if (!this.processingResetAfter && this.resetAfter) {
-            this.processingResetAfter = setTimeout(() => {
-                this.remaining++;
-                this.processingResetAfter = undefined;
-            }, this.resetAfter * 1.5);
-        }
+        if (this.processingResetAfter || !this.resetAfter)
+            return;
+        this.processingResetAfter = setTimeout(() => {
+            this.remaining++;
+            this.processingResetAfter = undefined;
+            const resetTimer = this.processing;
+            if (!this.queue.length || !resetTimer || resetTimer === true)
+                return;
+            clearTimeout(resetTimer);
+            this.processing = false;
+            this.process(true);
+        }, this.resetAfter * 1.5);
     }
 }
 exports.Bucket = Bucket;

package/lib/api/shared.d.ts

@@ -3,6 +3,8 @@ export * from './api';
 export * from './utils/constants';
 export * from './utils/types';
 export { calculateUserDefaultAvatarIndex } from './utils/utils';
+/** JSON body accepted by the REST transport, including top-level bulk arrays. */
+export type ApiRequestBody = Record<string, any> | readonly unknown[];
 export interface ApiHandlerOptions {
     baseUrl?: string;
     domain?: string;
@@ -23,7 +25,7 @@ export interface RawFile {
     filename: string;
 }
 export interface ApiRequestOptions {
-    body?: Record<string, any>;
+    body?: ApiRequestBody;
     query?: Record<string, any>;
     files?: RawFile[];
     auth?: boolean;

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

@@ -1,4 +1,4 @@
-export declare const DefaultUserAgent: "DiscordBot (https://seyfert.dev, v4.4.0)";
+export declare const DefaultUserAgent: "DiscordBot (https://seyfert.dev, v4.6.0)";
 export declare const ALLOWED_EXTENSIONS: readonly ["webp", "png", "jpg", "jpeg", "gif"];
 export declare const ALLOWED_STICKER_EXTENSIONS: readonly ["png", "json", "gif"];
 export declare const ALLOWED_SIZES: readonly [16, 32, 64, 100, 128, 256, 512, 1024, 2048, 4096];

package/lib/api/utils/constants.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ALLOWED_TAG_BADGE_EXTENSIONS = exports.ALLOWED_SOUNDS_EXTENSIONS = exports.ALLOWED_SIZES = exports.ALLOWED_STICKER_EXTENSIONS = exports.ALLOWED_EXTENSIONS = exports.DefaultUserAgent = void 0;
-exports.DefaultUserAgent = 'DiscordBot (https://seyfert.dev, v4.4.0)';
+exports.DefaultUserAgent = 'DiscordBot (https://seyfert.dev, v4.6.0)';
 exports.ALLOWED_EXTENSIONS = ['webp', 'png', 'jpg', 'jpeg', 'gif'];
 exports.ALLOWED_STICKER_EXTENSIONS = ['png', 'json', 'gif'];
 exports.ALLOWED_SIZES = [16, 32, 64, 100, 128, 256, 512, 1_024, 2_048, 4_096];

package/lib/builders/Attachment.d.ts

@@ -1,7 +1,7 @@
 import type { RawFile, UsingClient } from '..';
 import { type ImageResolvable, type ObjectToLower } from '../common';
 import { Base } from '../structures/extra/Base';
-import type { APIAttachment, RESTAPIAttachment } from '../types';
+import { type APIAttachment, type RESTAPIAttachment } from '../types';
 export interface AttachmentResolvableMap {
     url: string;
     buffer: ReadableStream | Buffer | ArrayBuffer | Uint8Array | Uint8ClampedArray;
@@ -12,6 +12,7 @@ export type AttachmentDataType = keyof AttachmentResolvableMap;
 export interface AttachmentData {
     filename: string;
     description: string;
+    is_spoiler?: boolean;
     resolvable: AttachmentResolvable;
     type: AttachmentDataType;
 }
@@ -21,6 +22,10 @@ export declare class Attachment extends Base {
     data: APIAttachment;
     constructor(client: UsingClient, data: APIAttachment);
     toJSON(): APIAttachment;
+    /**
+     * Gets whether the attachment is a spoiler.
+     */
+    get spoiler(): boolean;
 }
 export declare class AttachmentBuilder {
     data: Partial<AttachmentData>;

package/lib/builders/Attachment.js

@@ -15,6 +15,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const utils_1 = require("../api/utils/utils");
 const common_1 = require("../common");
 const Base_1 = require("../structures/extra/Base");
+const types_1 = require("../types");
 class Attachment extends Base_1.Base {
     data;
     constructor(client, data) {
@@ -25,6 +26,12 @@ class Attachment extends Base_1.Base {
     toJSON() {
         return { ...this.data };
     }
+    /**
+     * Gets whether the attachment is a spoiler.
+     */
+    get spoiler() {
+        return Boolean((this.data.flags ?? 0) & types_1.AttachmentFlags.IsSpoiler) || this.data.filename.startsWith('SPOILER_');
+    }
 }
 exports.Attachment = Attachment;
 class AttachmentBuilder {
@@ -83,20 +90,17 @@ class AttachmentBuilder {
      * attachment.setSpoiler(true);
      */
     setSpoiler(spoiler) {
-        if (spoiler === this.spoiler)
-            return this;
-        if (!spoiler) {
+        this.data.is_spoiler = spoiler;
+        if (!spoiler && this.data.filename?.startsWith('SPOILER_')) {
             this.data.filename = this.data.filename.slice('SPOILER_'.length);
-            return this;
         }
-        this.data.filename = `SPOILER_${this.data.filename}`;
         return this;
     }
     /**
      * Gets whether the attachment is a spoiler.
      */
     get spoiler() {
-        return this.data.filename?.startsWith('SPOILER_') ?? false;
+        return this.data.is_spoiler ?? this.data.filename?.startsWith('SPOILER_') ?? false;
     }
     /**
      * Converts the Attachment instance to JSON.
@@ -116,10 +120,10 @@ function resolveAttachment(resolve) {
     if ('id' in resolve)
         return resolve;
     if (resolve instanceof AttachmentBuilder) {
-        const { filename, description } = resolve.toJSON();
-        return { filename, description };
+        const { filename, description, is_spoiler } = resolve.toJSON();
+        return { filename, description, is_spoiler };
     }
-    return { filename: resolve.filename, description: resolve.description };
+    return { filename: resolve.filename, description: resolve.description, is_spoiler: resolve.is_spoiler };
 }
 /**
  * Resolves a list of attachments to raw files.

package/lib/builders/CheckboxGroup.js

@@ -65,7 +65,7 @@ class CheckboxGroup extends Base_1.BaseComponentBuilder {
                     ...(0, common_1.createValidationMetadata)('number of options between 2 and 10', optionCount, {
                         component: 'CheckboxGroup',
                     }),
-                    detail: 'CheckboxGroup must have between 2 and 10 options.',
+                    detail: `CheckboxGroup has an invalid options length: expected number of options between 2 and 10, received ${optionCount}.`,
                 },
             });
         }