seyfert 4.2.1 → 4.2.2-dev-22071590650.0

package/README.md

@@ -49,6 +49,19 @@ npm i seyfert
 ## Contributing
 We are open to contributions, fork the repo and make your changes!
 
+## Typed errors
+
+Seyfert throws `SeyfertError` in validation/runtime checks and can include:
+
+- `code`: machine-readable identifier (`INVALID_EMOJI`, `INVALID_OPTIONS_LENGTH`, `MISSING_COMPONENT`, etc.)
+- `metadata`: structured context for diagnostics
+
+For validation errors, metadata follows this convention:
+
+- `expected`: expected value/shape
+- `received`: value actually received
+- `receivedType`: optional primitive/runtime type
+
 ## Useful links
 
 - [GitHub Repository](https://github.com/tiramisulabs/seyfert)

package/lib/api/api.d.ts

@@ -1,5 +1,5 @@
 import { type UUID } from 'node:crypto';
-import { type Awaitable, Logger } from '../common';
+import { type Awaitable, Logger, SeyfertError } from '../common';
 import type { WorkerSendApiRequest } from '../websocket/discord/worker';
 import { Bucket } from './bucket';
 import type { APIRoutes } from './Routes';
@@ -27,7 +27,9 @@ export declare class ApiHandler {
     protected sendMessage(_body: WorkerSendApiRequest): void;
     protected postMessage<T = unknown>(body: WorkerSendApiRequest): Promise<T>;
     request<T = unknown>(method: HttpMethods, url: `/${string}`, { auth, ...request }?: ApiRequestOptions): Promise<T>;
-    parseError(method: HttpMethods, route: `/${string}`, response: Response, result: string | Record<string, any>): Error;
+    parseError(method: HttpMethods, route: `/${string}`, response: Response, result: string | Record<string, any>, originTrace?: {
+        stack?: string;
+    }): SeyfertError;
     parseValidationError(data: Record<string, any>, path?: string, errors?: string[]): string[];
     handle50X(method: HttpMethods, url: `/${string}`, request: ApiRequestOptions, next: () => void): Promise<unknown>;
     handle429(route: string, method: HttpMethods, url: `/${string}`, request: ApiRequestOptions, response: Response, result: string, next: () => void, reject: (err: unknown) => void, now: number): Promise<unknown>;

package/lib/api/api.js

@@ -28,7 +28,9 @@ class ApiHandler {
             this.debug = true;
         const worker_threads = (0, common_1.lazyLoadPackage)('node:worker_threads');
         if (options.workerProxy && !worker_threads?.parentPort && !process.send)
-            throw new Error('Cannot use workerProxy without a parent.');
+            throw new common_1.SeyfertError('API_WORKER_PROXY_PARENT_REQUIRED', {
+                metadata: { detail: 'Cannot use workerProxy without a parent.' },
+            });
         if (options.workerProxy)
             this.workerPromises = new Map();
         if (worker_threads?.parentPort) {
@@ -79,7 +81,7 @@ class ApiHandler {
         return uuid;
     }
     sendMessage(_body) {
-        throw new Error('Function not implemented');
+        throw new common_1.SeyfertError('FUNCTION_NOT_IMPLEMENTED', { metadata: { detail: 'Function not implemented' } });
     }
     postMessage(body) {
         this.sendMessage(body);
@@ -88,6 +90,8 @@ class ApiHandler {
         });
     }
     async request(method, url, { auth = true, ...request } = {}) {
+        const originTrace = {};
+        Error.captureStackTrace(originTrace, this.request);
         if (this.options.workerProxy) {
             const nonce = this.randomUUID();
             return this.postMessage({
@@ -151,14 +155,14 @@ class ApiHandler {
                             result = JSON.parse(result);
                         }
                         catch (err) {
-                            this.debugger?.warn('Error parsing result error (', result, ')', err);
+                            this.debugger?.warn('SeyfertError parsing result error (', result, ')', err);
                             reject(err);
                             return;
                         }
                     }
                 }
-                const parsedError = this.parseError(method, route, response, result);
-                this.debugger?.warn(parsedError);
+                const parsedError = this.parseError(method, route, response, result, originTrace);
+                this.debugger?.warn(parsedError.message);
                 reject(parsedError);
                 return;
             }
@@ -168,7 +172,7 @@ class ApiHandler {
                         result = JSON.parse(result);
                     }
                     catch (err) {
-                        this.debugger?.warn('Error parsing result (', result, ')', err);
+                        this.debugger?.warn('Failed parsing result (', result, ')', err);
                         next();
                         reject(err);
                         return;
@@ -195,9 +199,20 @@ class ApiHandler {
             }
         });
     }
-    parseError(method, route, response, result) {
+    parseError(method, route, response, result, originTrace) {
         let errMessage = '';
+        let code;
+        const metadata = {
+            method,
+            route,
+            status: response.status,
+            statusText: response.statusText,
+        };
         if (typeof result === 'object') {
+            if (typeof result.code !== 'undefined') {
+                code = String(result.code);
+            }
+            metadata.response = result;
             errMessage += `${result.message ?? 'Unknown'} ${result.code ?? ''}\n[${response.status} ${response.statusText}] ${method} ${route}`;
             if ('errors' in result) {
                 const errors = this.parseValidationError(result.errors);
@@ -207,7 +222,25 @@ class ApiHandler {
         else {
             errMessage = `[${response.status} ${response.statusText}] ${method} ${route}`;
         }
-        return new Error(errMessage);
+        const error = new common_1.SeyfertError(`API_${response.statusText}_${code}`, {
+            metadata: {
+                ...metadata,
+                detail: errMessage,
+            },
+        });
+        const originStack = originTrace?.stack;
+        if (originStack) {
+            const originLines = originStack
+                .split('\n')
+                .slice(1)
+                .filter(line => !line.includes('node:internal') &&
+                !line.includes('/src/api/api.ts') &&
+                !line.includes('\\src\\api\\api.ts'));
+            if (originLines.length) {
+                error.stack = `${error.name}: ${error.message}\n${originLines.join('\n')}`;
+            }
+        }
+        return error;
     }
     parseValidationError(data, path = '', errors = []) {
         for (const key in data) {
@@ -237,7 +270,7 @@ class ApiHandler {
     }
     async handle429(route, method, url, request, response, result, next, reject, now) {
         await this.onRatelimit?.(response, request);
-        const content = `${JSON.stringify(request)} `;
+        const bucket = this.ratelimits.get(route);
         let retryAfter;
         const data = JSON.parse(result);
         if (data.retry_after)
@@ -247,10 +280,23 @@ class ApiHandler {
         if (Number.isNaN(retryAfter)) {
             this.debugger?.warn(`${route} Could not extract retry_after from 429 response. ${result}`);
             next();
-            reject(new Error('Could not extract retry_after from 429 response.'));
+            reject(new common_1.SeyfertError('INVALID_RETRY_AFTER', {
+                metadata: {
+                    ...{
+                        route,
+                        method,
+                        status: response.status,
+                        result,
+                    },
+                    detail: 'Could not extract retry_after from 429 response.',
+                },
+            }));
             return false;
         }
-        this.debugger?.info(`${response.headers.get('x-ratelimit-global') ? 'Global' : 'Unexpected'} 429: ${result.slice(0, 256)}\n${content} ${now} ${route} ${response.status}: ${this.ratelimits.get(route).remaining}/${this.ratelimits.get(route).limit} left | Reset ${retryAfter} (${this.ratelimits.get(route).reset - now}ms left) | Scope ${response.headers.get('x-ratelimit-scope')}`);
+        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) {
             await (0, common_1.delay)(retryAfter);
             next();

package/lib/builders/Attachment.d.ts

@@ -1,5 +1,5 @@
 import type { RawFile, UsingClient } from '..';
-import type { ImageResolvable, ObjectToLower } from '../common';
+import { type ImageResolvable, type ObjectToLower } from '../common';
 import { Base } from '../structures/extra/Base';
 import type { APIAttachment, RESTAPIAttachment } from '../types';
 export interface AttachmentResolvableMap {

package/lib/builders/Attachment.js

@@ -13,6 +13,7 @@ const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 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");
 class Attachment extends Base_1.Base {
     data;
@@ -159,13 +160,23 @@ async function resolveFiles(resources) {
 async function resolveAttachmentData(data, type) {
     if (data instanceof AttachmentBuilder) {
         if (!data.data.resolvable)
-            throw new Error('The attachment type has been expressed as attachment but cannot be resolved as one.');
+            throw new common_1.SeyfertError('INVALID_ATTACHMENT_TYPE', {
+                metadata: {
+                    ...(0, common_1.createValidationMetadata)('AttachmentBuilder with resolvable data', data.data.resolvable),
+                    detail: 'The attachment type has been expressed as attachment but cannot be resolved as one.',
+                },
+            });
         return { data: data.data.resolvable };
     }
     switch (type) {
         case 'url': {
             if (!/^https?:\/\//.test(data))
-                throw new Error(`The attachment type has been expressed as ${type.toUpperCase()} but cannot be resolved as one.`);
+                throw new common_1.SeyfertError('INVALID_ATTACHMENT_TYPE', {
+                    metadata: {
+                        ...(0, common_1.createValidationMetadata)('string URL starting with http:// or https://', data),
+                        detail: `The attachment type has been expressed as ${type.toUpperCase()} but cannot be resolved as one.`,
+                    },
+                });
             const res = await fetch(data);
             return {
                 data: Buffer.from(await res.arrayBuffer()),
@@ -176,7 +187,12 @@ async function resolveAttachmentData(data, type) {
             const file = node_path_1.default.resolve(data);
             const stats = await node_fs_1.promises.stat(file);
             if (!stats.isFile())
-                throw new Error(`The attachment type has been expressed as ${type.toUpperCase()} but cannot be resolved as one.`);
+                throw new common_1.SeyfertError('INVALID_ATTACHMENT_TYPE', {
+                    metadata: {
+                        ...(0, common_1.createValidationMetadata)('path to an existing file', file),
+                        detail: `The attachment type has been expressed as ${type.toUpperCase()} but cannot be resolved as one.`,
+                    },
+                });
             return { data: await node_fs_1.promises.readFile(file) };
         }
         case 'buffer': {
@@ -188,10 +204,20 @@ async function resolveAttachmentData(data, type) {
                     buffers.push(Buffer.from(resource));
                 return { data: Buffer.concat(buffers) };
             }
-            throw new Error(`The attachment type has been expressed as ${type.toUpperCase()} but cannot be resolved as one.`);
+            throw new common_1.SeyfertError('INVALID_ATTACHMENT_TYPE', {
+                metadata: {
+                    ...(0, common_1.createValidationMetadata)('Buffer | ArrayBuffer | AsyncIterable<ArrayBuffer>', data),
+                    detail: `The attachment type has been expressed as ${type.toUpperCase()} but cannot be resolved as one.`,
+                },
+            });
         }
         default: {
-            throw new Error(`The attachment type has been expressed as ${type} but cannot be resolved as one.`);
+            throw new common_1.SeyfertError('INVALID_ATTACHMENT_TYPE', {
+                metadata: {
+                    ...(0, common_1.createValidationMetadata)('url | path | buffer', type),
+                    detail: `The attachment type has been expressed as ${type} but cannot be resolved as one.`,
+                },
+            });
         }
     }
 }
@@ -215,7 +241,15 @@ async function resolveImage(image) {
         const { data: { type, resolvable }, } = image;
         if (type && resolvable)
             return resolveBase64((await resolveAttachmentData(resolvable, type)).data);
-        throw new Error(`The attachment type has been expressed as ${(type ?? 'Attachment').toUpperCase()} but cannot be resolved as one.`);
+        throw new common_1.SeyfertError('INVALID_ATTACHMENT_TYPE', {
+            metadata: {
+                ...(0, common_1.createValidationMetadata)('AttachmentBuilder with type and resolvable data', {
+                    type,
+                    resolvable,
+                }),
+                detail: `The attachment type has been expressed as ${(type ?? 'Attachment').toUpperCase()} but cannot be resolved as one.`,
+            },
+        });
     }
     if (image instanceof Attachment) {
         const response = await fetch(image.url);

package/lib/builders/Button.js

@@ -47,7 +47,12 @@ class Button extends Base_1.BaseComponentBuilder {
     setEmoji(emoji) {
         const resolve = (0, common_1.resolvePartialEmoji)(emoji);
         if (!resolve)
-            throw new Error('Invalid Emoji');
+            throw new common_1.SeyfertError('INVALID_EMOJI', {
+                metadata: {
+                    ...(0, common_1.createValidationMetadata)('EmojiResolvable', emoji, { component: 'Button' }),
+                    detail: 'Invalid Emoji',
+                },
+            });
         this.data.emoji =
             resolve;
         return this;

package/lib/builders/CheckboxGroup.d.ts

@@ -1,4 +1,4 @@
-import type { RestOrArray } from '../common';
+import { type RestOrArray } from '../common';
 import { type APICheckboxGroupComponent, type APICheckboxGroupOption } from '../types';
 import { BaseComponentBuilder, type OptionValuesLength } from './Base';
 export declare class CheckboxGroup extends BaseComponentBuilder<APICheckboxGroupComponent> {

package/lib/builders/CheckboxGroup.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CheckboxGroupOption = exports.CheckboxGroup = void 0;
+const common_1 = require("../common");
 const types_1 = require("../types");
 const Base_1 = require("./Base");
 class CheckboxGroup extends Base_1.BaseComponentBuilder {
@@ -59,7 +60,14 @@ class CheckboxGroup extends Base_1.BaseComponentBuilder {
         const options = [...this.#options.map(option => option.toJSON()), ...(this.data.options ?? [])];
         const optionCount = options.length;
         if (optionCount < 2 || optionCount > 10) {
-            throw new Error('RadioGroup must have between 2 and 10 options.');
+            throw new common_1.SeyfertError('INVALID_OPTIONS_LENGTH', {
+                metadata: {
+                    ...(0, common_1.createValidationMetadata)('number of options between 2 and 10', optionCount, {
+                        component: 'CheckboxGroup',
+                    }),
+                    detail: 'CheckboxGroup must have between 2 and 10 options.',
+                },
+            });
         }
         return {
             ...this.data,

package/lib/builders/Label.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Label = void 0;
+const common_1 = require("../common");
 const types_1 = require("../types");
 const _1 = require(".");
 const Base_1 = require("./Base");
@@ -25,7 +26,14 @@ class Label extends Base_1.BaseComponentBuilder {
     }
     toJSON() {
         if (!this.component)
-            throw new Error('Cannot convert to JSON without a component.');
+            throw new common_1.SeyfertError('MISSING_COMPONENT', {
+                metadata: {
+                    ...(0, common_1.createValidationMetadata)('component to be set before calling toJSON()', this.component, {
+                        component: 'Label',
+                    }),
+                    detail: 'Cannot convert to JSON without a component.',
+                },
+            });
         return {
             ...this.data,
             component: this.component.toJSON(),

package/lib/builders/Poll.js

@@ -40,7 +40,12 @@ class PollBuilder {
             return { text: data.text };
         const resolve = (0, common_1.resolvePartialEmoji)(data.emoji);
         if (!resolve)
-            throw new Error('Invalid Emoji');
+            throw new common_1.SeyfertError('INVALID_EMOJI', {
+                metadata: {
+                    ...(0, common_1.createValidationMetadata)('EmojiResolvable', data.emoji, { component: 'PollBuilder' }),
+                    detail: 'Invalid Emoji',
+                },
+            });
         return { text: data.text, emoji: resolve };
     }
 }

package/lib/builders/RadioGroup.d.ts

@@ -1,4 +1,4 @@
-import type { RestOrArray } from '../common';
+import { type RestOrArray } from '../common';
 import { type APIRadioGroupComponent, type APIRadioGroupOption } from '../types';
 import { BaseComponentBuilder } from './Base';
 export declare class RadioGroup extends BaseComponentBuilder<APIRadioGroupComponent> {

package/lib/builders/RadioGroup.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RadioGroupOption = exports.RadioGroup = void 0;
+const common_1 = require("../common");
 const types_1 = require("../types");
 const Base_1 = require("./Base");
 class RadioGroup extends Base_1.BaseComponentBuilder {
@@ -47,7 +48,14 @@ class RadioGroup extends Base_1.BaseComponentBuilder {
         const options = [...this.#options.map(option => option.data), ...(this.data.options ?? [])];
         const optionCount = options.length;
         if (optionCount < 2 || optionCount > 10) {
-            throw new Error('RadioGroup must have between 2 and 10 options.');
+            throw new common_1.SeyfertError('INVALID_OPTIONS_LENGTH', {
+                metadata: {
+                    ...(0, common_1.createValidationMetadata)('number of options between 2 and 10', optionCount, {
+                        component: 'RadioGroup',
+                    }),
+                    detail: 'RadioGroup must have between 2 and 10 options.',
+                },
+            });
         }
         return {
             ...this.data,

package/lib/builders/Section.d.ts

@@ -1,4 +1,4 @@
-import type { RestOrArray } from '../common';
+import { type RestOrArray } from '../common';
 import { type APISectionComponent } from '../types';
 import { type Button } from '.';
 import { BaseComponentBuilder } from './Base';

package/lib/builders/Section.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Section = void 0;
+const common_1 = require("../common");
 const types_1 = require("../types");
 const _1 = require(".");
 const Base_1 = require("./Base");
@@ -41,7 +42,14 @@ class Section extends Base_1.BaseComponentBuilder {
      */
     toJSON() {
         if (!this.accessory)
-            throw new Error('Cannot convert to JSON without an accessory.');
+            throw new common_1.SeyfertError('MISSING_ACCESSORY', {
+                metadata: {
+                    ...(0, common_1.createValidationMetadata)('accessory to be set before calling toJSON()', this.accessory, {
+                        component: 'Section',
+                    }),
+                    detail: 'Cannot convert to JSON without an accessory.',
+                },
+            });
         return {
             ...this.data,
             components: this.components.map(component => component.toJSON()),

package/lib/builders/SelectMenu.d.ts

@@ -1,4 +1,4 @@
-import type { EmojiResolvable, RestOrArray } from '../common';
+import { type EmojiResolvable, type RestOrArray } from '../common';
 import { type APIChannelSelectComponent, type APIMentionableSelectComponent, type APIRoleSelectComponent, type APISelectMenuComponent, type APISelectMenuOption, type APIStringSelectComponent, type APIUserSelectComponent, type ChannelType, SelectMenuDefaultValueType } from '../types';
 import { BaseComponentBuilder, type OptionValuesLength } from './Base';
 export type BuilderSelectMenus = RoleSelectMenu | UserSelectMenu | MentionableSelectMenu | ChannelSelectMenu | StringSelectMenu;

package/lib/builders/SelectMenu.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StringSelectOption = exports.StringSelectMenu = exports.ChannelSelectMenu = exports.MentionableSelectMenu = exports.RoleSelectMenu = exports.UserSelectMenu = exports.SelectMenu = void 0;
+const common_1 = require("../common");
 const utils_1 = require("../common/it/utils");
 const types_1 = require("../types");
 const Base_1 = require("./Base");
@@ -318,7 +319,12 @@ class StringSelectOption {
     setEmoji(emoji) {
         const resolve = (0, utils_1.resolvePartialEmoji)(emoji);
         if (!resolve)
-            throw new Error('Invalid Emoji');
+            throw new common_1.SeyfertError('INVALID_EMOJI', {
+                metadata: {
+                    ...(0, common_1.createValidationMetadata)('EmojiResolvable', emoji, { component: 'StringSelectOption' }),
+                    detail: 'Invalid Emoji',
+                },
+            });
         this.data.emoji = resolve;
         return this;
     }

package/lib/cache/adapters/workeradapter.js

@@ -36,7 +36,7 @@ class WorkerAdapter {
         return new Promise((res, rej) => {
             const timeout = setTimeout(() => {
                 this.promises.delete(nonce);
-                rej(new Error('Timeout cache request'));
+                rej(new common_1.SeyfertError('CACHE_TIMEOUT', { metadata: { ...{ nonce, method }, detail: 'Timeout cache request' } }));
             }, 60e3);
             this.promises.set(nonce, { resolve: res, timeout });
         });