seyfert 4.4.1 → 5.0.0

package/lib/client/plugins/api.js

@@ -0,0 +1,550 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPluginApi = createPluginApi;
+const errors_1 = require("./errors");
+const order_1 = require("./order");
+const registry_1 = require("./registry");
+const shared_1 = require("./shared");
+const reservedCacheResourceNames = new Set([
+    '__logger__',
+    '__proto__',
+    'adapter',
+    'bans',
+    'buildCache',
+    'bulkGet',
+    'bulkPatch',
+    'bulkSet',
+    'channels',
+    'constructor',
+    'emojis',
+    'flush',
+    'guilds',
+    'hasChannelsIntent',
+    'hasDirectMessages',
+    'hasGuildExpressionsIntent',
+    'hasGuildMembersIntent',
+    'hasGuildsIntent',
+    'hasIntent',
+    'hasModerationIntent',
+    'hasPresenceUpdates',
+    'hasRolesIntent',
+    'hasVoiceStates',
+    'intents',
+    'members',
+    'messages',
+    'onPacket',
+    'onPacketDefault',
+    'overwrites',
+    'pluginResourceNames',
+    'pluginResourcePacketHandlers',
+    'presences',
+    'prototype',
+    'roles',
+    'stageInstances',
+    'stickers',
+    'users',
+    'voiceStates',
+]);
+const noReservedPluginKeys = new Set();
+const handlerKinds = new Set(['command', 'component', 'modal', 'event']);
+function createPluginApi(record, registry, scope = 'register') {
+    const assertCanMutate = (phase) => {
+        if (scope !== 'teardown')
+            return;
+        throw (0, errors_1.createPluginConflictError)(record.plugin.name, phase, record.index, `Plugin "${record.plugin.name}" cannot mutate plugin contributions during teardown.`, record.plugin.instanceId);
+    };
+    const addEvent = (name, handler, opts) => {
+        assertCanMutate(`events.${String(name)}`);
+        const contribution = {
+            record,
+            name: String(name),
+            handler: handler,
+            scope,
+            active: true,
+            order: opts?.order,
+            sequence: (0, order_1.nextPluginContributionSequence)(registry),
+            once: opts?.once,
+        };
+        registry.events.push(contribution);
+        return once(() => (0, registry_1.removePluginEventContribution)(registry, contribution));
+    };
+    return {
+        has(req) {
+            return (0, registry_1.hasPluginRequirement)(registry, req);
+        },
+        events: {
+            on(name, handler, opts) {
+                return addEvent(name, handler, opts);
+            },
+            once(name, handler) {
+                return addEvent(name, handler, { once: true });
+            },
+            onAny(handler, opts) {
+                assertCanMutate('events.onAny');
+                const contribution = {
+                    record,
+                    handler,
+                    scope,
+                    active: true,
+                    order: opts?.order,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                };
+                registry.anyEvents.push(contribution);
+                return once(() => (0, registry_1.removePluginAnyEventContribution)(registry, contribution));
+            },
+            onError(handler, opts) {
+                assertCanMutate('events.onError');
+                const contribution = {
+                    record,
+                    handler,
+                    scope,
+                    active: true,
+                    order: opts?.order,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                };
+                registry.eventErrors.push(contribution);
+                return once(() => (0, registry_1.removePluginEventErrorContribution)(registry, contribution));
+            },
+        },
+        commands: {
+            add(...args) {
+                assertCanMutate('commands.add');
+                const [commands, opts] = splitContributionArgs(args, isCommandContributionOptions);
+                if (opts?.guilds?.length) {
+                    (0, registry_1.addPluginDiagnostic)(registry, record, {
+                        phase: 'commands.add',
+                        severity: 'info',
+                        code: 'command-guild-scope',
+                        message: `Plugin "${record.plugin.name}" registered a guild-scoped command contribution.`,
+                        data: { guilds: [...opts.guilds], commands: commands.length },
+                    });
+                }
+                registry.commands.push({
+                    record,
+                    commands,
+                    scope,
+                    override: opts?.override === true,
+                    guilds: opts?.guilds ? [...opts.guilds] : undefined,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+            },
+            remove(...names) {
+                assertCanMutate('commands.remove');
+                registry.commandRemovals.push({
+                    record,
+                    names,
+                    scope,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+            },
+            observe(observer, opts) {
+                assertCanMutate('commands.observe');
+                const contribution = {
+                    record,
+                    observer,
+                    scope,
+                    active: true,
+                    order: opts?.order,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                };
+                registry.commandObservers.push(contribution);
+                return once(() => (0, registry_1.removePluginCommandObserverContribution)(registry, contribution));
+            },
+            defaults(hooks, opts) {
+                assertCanMutate('commands.defaults');
+                registry.pluginDefaults.push({
+                    record,
+                    kind: 'commands',
+                    hooks: hooks,
+                    suppressDefault: opts?.suppressDefault,
+                    scope,
+                    order: opts?.order,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+            },
+        },
+        rest: {
+            observe(observer, opts) {
+                assertCanMutate('rest.observe');
+                const contribution = {
+                    record,
+                    observer,
+                    scope,
+                    active: true,
+                    order: opts?.order,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                };
+                registry.restObservers.push(contribution);
+                return once(() => (0, registry_1.removePluginRestObserverContribution)(registry, contribution));
+            },
+        },
+        hooks: {
+            on(name, handler, opts) {
+                assertCanMutate(`hooks.${name}`);
+                const contribution = {
+                    record,
+                    name,
+                    handler: handler,
+                    scope,
+                    active: true,
+                    order: opts?.order,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                };
+                registry.hooks.push(contribution);
+                return once(() => (0, registry_1.removePluginHookContribution)(registry, contribution));
+            },
+        },
+        handlers: {
+            construct(creator, opts) {
+                assertCanMutate('handlers.construct');
+                registry.handlerCreators.push({
+                    record,
+                    creator,
+                    scope,
+                    kinds: normalizeHandlerKinds(record, opts, false),
+                    order: opts?.order,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+            },
+            transform(transformer, opts) {
+                assertCanMutate('handlers.transform');
+                registry.handlerTransformers.push({
+                    record,
+                    transformer,
+                    scope,
+                    kinds: normalizeHandlerKinds(record, opts),
+                    order: opts?.order,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+            },
+        },
+        components: {
+            add(...args) {
+                assertCanMutate('components.add');
+                const [components, opts] = splitContributionArgs(args);
+                registry.components.push({
+                    record,
+                    components,
+                    scope,
+                    override: opts?.override === true,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+            },
+            remove(...customIds) {
+                assertCanMutate('components.remove');
+                registry.componentRemovals.push({
+                    record,
+                    customIds,
+                    scope,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+            },
+            defaults(hooks, opts) {
+                assertCanMutate('components.defaults');
+                registry.pluginDefaults.push({
+                    record,
+                    kind: 'components',
+                    hooks: hooks,
+                    suppressDefault: opts?.suppressDefault,
+                    scope,
+                    order: opts?.order,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+            },
+        },
+        modals: {
+            add(...args) {
+                assertCanMutate('modals.add');
+                const [modals, opts] = splitContributionArgs(args);
+                registry.modals.push({
+                    record,
+                    modals,
+                    scope,
+                    override: opts?.override === true,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+            },
+            remove(...customIds) {
+                assertCanMutate('modals.remove');
+                registry.modalRemovals.push({
+                    record,
+                    customIds,
+                    scope,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+            },
+            defaults(hooks, opts) {
+                assertCanMutate('modals.defaults');
+                registry.pluginDefaults.push({
+                    record,
+                    kind: 'modals',
+                    hooks: hooks,
+                    suppressDefault: opts?.suppressDefault,
+                    scope,
+                    order: opts?.order,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+            },
+        },
+        middlewares: {
+            add(name, middleware, opts) {
+                assertCanMutate(`middlewares.${name}`);
+                (0, registry_1.assertSafePluginResourceName)(record, `middlewares.${name}`, name, noReservedPluginKeys);
+                registry.middlewares.push({
+                    record,
+                    name,
+                    middleware,
+                    global: opts?.global === true,
+                    override: opts?.override === true,
+                    scope,
+                    order: opts?.order,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+                if (opts?.global) {
+                    (0, registry_1.addPluginOptionFragment)(registry, record, {
+                        globalMiddlewares: [name],
+                    }, scope);
+                }
+            },
+            remove(...names) {
+                assertCanMutate('middlewares.remove');
+                for (const name of names) {
+                    (0, registry_1.assertSafePluginResourceName)(record, `middlewares.${name}`, name, noReservedPluginKeys);
+                }
+                registry.middlewareRemovals.push({
+                    record,
+                    names,
+                    scope,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+            },
+        },
+        autocomplete: {
+            wrap(wrapper, opts) {
+                assertCanMutate('autocomplete.wrap');
+                registry.autocompleteWrappers.push({
+                    record,
+                    wrapper,
+                    scope,
+                    order: opts?.order,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+            },
+        },
+        gateway: {
+            addIntents(...intents) {
+                assertCanMutate('gateway.addIntents');
+                const resolvedIntents = [];
+                for (const intent of intents) {
+                    const resolved = (0, registry_1.resolveGatewayIntent)(intent);
+                    if (resolved === undefined) {
+                        (0, registry_1.addPluginDiagnostic)(registry, record, {
+                            phase: 'gateway.addIntents',
+                            severity: 'warn',
+                            code: 'unknown-intent-bits',
+                            message: `Gateway intent "${String(intent)}" is unknown.`,
+                            data: { intent },
+                        });
+                        continue;
+                    }
+                    const unknownBits = (0, registry_1.unknownGatewayIntentBits)(resolved);
+                    if (unknownBits) {
+                        (0, registry_1.addPluginDiagnostic)(registry, record, {
+                            phase: 'gateway.addIntents',
+                            severity: 'warn',
+                            code: 'unknown-intent-bits',
+                            message: `Gateway intent value "${resolved}" includes unknown bits "${unknownBits}".`,
+                            data: { intent: resolved, unknownBits },
+                        });
+                    }
+                    resolvedIntents.push(resolved);
+                }
+                if (resolvedIntents.length)
+                    registry.gatewayIntents.push({ record, intents: resolvedIntents, scope });
+            },
+            wrapSendPayload(wrapper, opts) {
+                assertCanMutate('gateway.wrapSendPayload');
+                registry.gatewaySendPayloadWrappers.push({
+                    record,
+                    wrapper,
+                    scope,
+                    order: opts?.order,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+            },
+            onDispatch(interceptor, opts) {
+                assertCanMutate('gateway.onDispatch');
+                const contribution = {
+                    record,
+                    interceptor,
+                    scope,
+                    order: opts?.order,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                };
+                registry.gatewayDispatchInterceptors.push(contribution);
+                return once(() => (0, registry_1.removePluginGatewayDispatchInterceptorContribution)(registry, contribution));
+            },
+        },
+        cache: {
+            resource(name, resource, opts) {
+                assertCanMutate('cache.resource');
+                (0, registry_1.assertSafePluginResourceName)(record, 'cache.resource', name, reservedCacheResourceNames);
+                const existing = registry.cacheResources.find(contribution => contribution.name === name);
+                if (existing) {
+                    throw (0, errors_1.createPluginConflictError)(record.plugin.name, 'cache.resource', record.index, `Cache resource "${name}" is already registered by plugin "${existing.record.identity}".`, record.plugin.instanceId);
+                }
+                if (opts?.intents?.length) {
+                    const resolvedIntents = [];
+                    for (const intent of opts.intents) {
+                        const resolved = (0, registry_1.resolveGatewayIntent)(intent);
+                        if (resolved === undefined) {
+                            (0, registry_1.addPluginDiagnostic)(registry, record, {
+                                phase: 'cache.resource',
+                                severity: 'warn',
+                                code: 'unknown-intent-bits',
+                                message: `Gateway intent "${String(intent)}" is unknown.`,
+                                data: { intent },
+                            });
+                            continue;
+                        }
+                        const unknownBits = (0, registry_1.unknownGatewayIntentBits)(resolved);
+                        if (unknownBits) {
+                            (0, registry_1.addPluginDiagnostic)(registry, record, {
+                                phase: 'cache.resource',
+                                severity: 'warn',
+                                code: 'unknown-intent-bits',
+                                message: `Gateway intent value "${resolved}" includes unknown bits "${unknownBits}".`,
+                                data: { intent: resolved, unknownBits },
+                            });
+                        }
+                        resolvedIntents.push(resolved);
+                    }
+                    if (resolvedIntents.length)
+                        registry.gatewayIntents.push({ record, intents: resolvedIntents, scope });
+                }
+                registry.cacheResources.push({
+                    record,
+                    name,
+                    resource,
+                    scope,
+                    onPacket: opts?.onPacket,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+            },
+        },
+        shared: {
+            set(name, factory, opts) {
+                assertCanMutate(`shared.${(0, shared_1.sharedName)(name)}`);
+                const key = (0, shared_1.sharedName)(name);
+                (0, registry_1.assertSafePluginResourceName)(record, `shared.${key}`, key, noReservedPluginKeys);
+                (0, shared_1.addPluginShared)(registry, record, key, factory, scope, opts);
+            },
+            remove(...names) {
+                assertCanMutate('shared.remove');
+                const keys = names.map(shared_1.sharedName);
+                for (const key of keys)
+                    (0, registry_1.assertSafePluginResourceName)(record, `shared.${key}`, key, noReservedPluginKeys);
+                (0, shared_1.removePluginShared)(registry, record, keys, scope);
+            },
+            has(name) {
+                return registry.shared.has((0, shared_1.sharedName)(name));
+            },
+        },
+        langs: {
+            contribute(locale, values, options) {
+                assertCanMutate('langs.contribute');
+                if (!isValidLangPrefix(options?.prefix)) {
+                    throw (0, errors_1.createPluginConflictError)(record.plugin.name, 'langs.contribute', record.index, 'langs.contribute locale prefix must contain at least one non-empty path segment.', record.plugin.instanceId);
+                }
+                registry.langs.push({
+                    record,
+                    locale,
+                    prefix: options.prefix,
+                    values,
+                    scope,
+                    sequence: (0, order_1.nextPluginContributionSequence)(registry),
+                });
+            },
+        },
+        reload() {
+            assertCanMutate('reload');
+            const client = registry.client;
+            if (!client) {
+                throw (0, errors_1.createPluginConflictError)(record.plugin.name, 'reload', record.index, `Plugin "${record.plugin.name}" cannot reload before the client is available.`, record.plugin.instanceId);
+            }
+            return client.reloadPluginContributions();
+        },
+        diagnostics: {
+            warn(message, options) {
+                (0, registry_1.addPluginDiagnostic)(registry, record, {
+                    phase: options?.phase ?? 'register',
+                    severity: 'warn',
+                    code: options?.code,
+                    message,
+                    data: options?.data,
+                });
+            },
+        },
+        options: {
+            set(fragment) {
+                assertCanMutate('options.set');
+                (0, registry_1.addPluginOptionFragment)(registry, record, fragment, scope);
+            },
+        },
+    };
+}
+function once(dispose) {
+    let disposed = false;
+    return () => {
+        if (disposed)
+            return;
+        disposed = true;
+        dispose();
+    };
+}
+function normalizeHandlerKinds(record, opts, allowEvent = true) {
+    if (!opts?.kinds)
+        return undefined;
+    for (const kind of opts.kinds) {
+        if (kind === 'event' && !allowEvent) {
+            throw (0, errors_1.createPluginConflictError)(record.plugin.name, 'handlers.kinds', record.index, 'Events have no construction step; use handlers.transform with kinds:["event"].', record.plugin.instanceId);
+        }
+        if (handlerKinds.has(kind))
+            continue;
+        throw (0, errors_1.createPluginConflictError)(record.plugin.name, 'handlers.kinds', record.index, `Handler kind "${String(kind)}" is invalid.`, record.plugin.instanceId);
+    }
+    return [...opts.kinds];
+}
+function isValidLangPrefix(prefix) {
+    if (!prefix)
+        return false;
+    return prefix.split('.').some(segment => segment.length > 0);
+}
+function splitContributionArgs(args, isOptions = isPlainContributionOptions) {
+    const last = args.at(-1);
+    if (isOptions(last))
+        return [args.slice(0, -1), last];
+    return [args, undefined];
+}
+function isPlainContributionOptions(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return false;
+    return Object.keys(value).every(key => key === 'override');
+}
+function isCommandContributionOptions(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return false;
+    return Object.entries(value).every(([key, option]) => {
+        if (key === 'override')
+            return typeof option === 'boolean';
+        if (key === 'guilds')
+            return Array.isArray(option) && option.every(guild => typeof guild === 'string');
+        return false;
+    });
+}

package/lib/client/plugins/errors.d.ts

@@ -0,0 +1,25 @@
+import { SeyfertError, type SeyfertErrorCode } from '../../common/it/error';
+export type SeyfertPluginErrorCode = 'PLUGIN_FAILED' | 'PLUGIN_TEARDOWN_FAILED';
+export declare class SeyfertPluginError extends SeyfertError {
+    readonly plugin: string;
+    readonly instanceId?: string;
+    readonly phase: string;
+    readonly index: number;
+    constructor(plugin: string, phase: string, index: number, cause: unknown, code?: SeyfertPluginErrorCode, instanceId?: string);
+}
+export declare class SeyfertPluginAggregateError extends SeyfertError {
+    name: string;
+    readonly errors: unknown[];
+    cause: unknown;
+    constructor(code: SeyfertPluginErrorCode, plugin: string, phase: string, index: number, errors: Iterable<unknown>, message?: string, cause?: unknown, instanceId?: string);
+    toJSON(): {
+        name: string;
+        message: string;
+        code: SeyfertErrorCode;
+        metadata: Record<string, unknown> | undefined;
+        cause: unknown;
+        errors: unknown[];
+    };
+}
+export declare function wrapPluginError(plugin: string, phase: string, index: number, cause: unknown, code?: SeyfertPluginErrorCode, instanceId?: string): SeyfertPluginError | SeyfertPluginAggregateError;
+export declare function createPluginConflictError(plugin: string, phase: string, index: number, detail: string, instanceId?: string): SeyfertPluginError | SeyfertPluginAggregateError;

package/lib/client/plugins/errors.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SeyfertPluginAggregateError = exports.SeyfertPluginError = void 0;
+exports.wrapPluginError = wrapPluginError;
+exports.createPluginConflictError = createPluginConflictError;
+const error_1 = require("../../common/it/error");
+class SeyfertPluginError extends error_1.SeyfertError {
+    plugin;
+    instanceId;
+    phase;
+    index;
+    constructor(plugin, phase, index, cause, code = 'PLUGIN_FAILED', instanceId) {
+        super(code, { metadata: pluginMetadata(plugin, phase, index, instanceId), cause });
+        this.name = 'SeyfertPluginError';
+        this.plugin = plugin;
+        this.instanceId = instanceId;
+        this.phase = phase;
+        this.index = index;
+        this.message = `Seyfert plugin "${formatPluginIdentity(plugin, instanceId)}" failed during ${phase} at index ${index}: ${formatPluginCause(cause)}`;
+        Error.captureStackTrace?.(this, SeyfertPluginError);
+    }
+}
+exports.SeyfertPluginError = SeyfertPluginError;
+class SeyfertPluginAggregateError extends error_1.SeyfertError {
+    name = 'SeyfertPluginAggregateError';
+    errors;
+    cause;
+    constructor(code, plugin, phase, index, errors, message, cause, instanceId) {
+        const collected = Array.from(errors);
+        const resolvedCause = cause ?? causeOf(collected[0]);
+        super(code, { metadata: pluginMetadata(plugin, phase, index, instanceId), cause: resolvedCause });
+        this.message = message ?? resolvePluginAggregateMessage(code);
+        this.errors = collected;
+        this.cause = resolvedCause;
+        Error.captureStackTrace?.(this, SeyfertPluginAggregateError);
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            metadata: this.metadata,
+            cause: this.cause,
+            errors: this.errors,
+        };
+    }
+}
+exports.SeyfertPluginAggregateError = SeyfertPluginAggregateError;
+function wrapPluginError(plugin, phase, index, cause, code, instanceId) {
+    if (cause instanceof SeyfertPluginError)
+        return cause;
+    if (cause instanceof SeyfertPluginAggregateError)
+        return cause;
+    return new SeyfertPluginError(plugin, phase, index, cause, code, instanceId);
+}
+function createPluginConflictError(plugin, phase, index, detail, instanceId) {
+    return wrapPluginError(plugin, phase, index, new Error(detail), undefined, instanceId);
+}
+function formatPluginCause(cause) {
+    if (cause instanceof Error)
+        return cause.message;
+    return String(cause);
+}
+function formatPluginIdentity(plugin, instanceId) {
+    return instanceId ? `${plugin}#${instanceId}` : plugin;
+}
+function pluginMetadata(plugin, phase, index, instanceId) {
+    if (instanceId)
+        return { plugin, instanceId, phase, index };
+    return { plugin, phase, index };
+}
+function causeOf(error) {
+    if (error && typeof error === 'object' && 'cause' in error)
+        return error.cause ?? error;
+    return error;
+}
+function resolvePluginAggregateMessage(code) {
+    return code === 'PLUGIN_TEARDOWN_FAILED' ? 'Seyfert plugin teardown failed.' : 'Seyfert plugin failed.';
+}

package/lib/client/plugins/order.d.ts

@@ -0,0 +1,10 @@
+import { type PluginOrderOpt } from './types';
+export interface PluginOrderedContribution {
+    order?: PluginOrderOpt;
+    sequence: number;
+}
+export interface PluginOrderSequence {
+    nextContributionSequence: number;
+}
+export declare function nextPluginContributionSequence(sequence: PluginOrderSequence): number;
+export declare function orderedPluginContributions<T extends PluginOrderedContribution>(contributions: readonly T[]): T[];