meocord 4.2.1 → 4.2.3

package/dist/esm/common/response/response-state.js

@@ -5,8 +5,8 @@ import { UserError } from '../errors.js';
 import { textFor } from '../meocord-text.js';
 import { logFailedSend } from './send-failure.js';
 import { describeInteraction } from '../../util/interaction.util.js';
-import { getInstallContext } from './install-context.js';
-import { resolveFlags, flagNames, hasEphemeral, hasComponentsV2 } from './flags.js';
+import { isBotInstalled, getInstallContext } from './install-context.js';
+import { resolveFlags, droppedFlagsWarning, hasEphemeral, hasComponentsV2 } from './flags.js';
 import { rewriteAttachmentUrls, keptAttachmentNames } from './attachments.js';
 import { renderEmbed, isTooLarge, REFUSED_AS_TOO_LARGE, withoutFiles, renderContainer, attachmentsOf, withSendableFiles, presenterFor, presentedMessage, TEXT_LIMITS, defaultPresenter, DEFAULT_ATTACHMENT_SIZE_LIMIT } from './presenter.js';
 import { sameEmbed, withoutRenderedViews, lockComponents, countComponents, V2_COMPONENT_LIMIT, EMBED_LIMIT } from './components.js';
@@ -16,6 +16,16 @@ import { themeForInteraction } from '../../core/theme-scope.js';
 import { LOADING_DRAW_TIMEOUT_MS } from '../../core/theme-resolvers.js';
 import { shared } from '../../util/shared-state.util.js';
 
+function _class_private_field_loose_base(receiver, privateKey) {
+    if (!Object.prototype.hasOwnProperty.call(receiver, privateKey)) {
+        throw new TypeError("attempted to use private field on non-instance");
+    }
+    return receiver;
+}
+var id = 0;
+function _class_private_field_loose_key(name) {
+    return "__private_" + id++ + "_" + name;
+}
 const ALREADY_ACKNOWLEDGED = 40060;
 /** Discord's code for an interaction it no longer knows, such as one past its three seconds unacknowledged. */ const UNKNOWN_INTERACTION = 10062;
 const TOKEN_EXPIRED = new Set([
@@ -113,6 +123,7 @@ const messageLocks = shared('messageLocks', ()=>new Map());
 function toJson(value) {
     return typeof value?.toJSON === 'function' ? value.toJSON() : value;
 }
+var _location = /*#__PURE__*/ _class_private_field_loose_key("_location");
 /** The response state behind `respond()`, with what `@Defer` and the testing helpers use besides. */ class InteractionResponse {
     get state() {
         this.sync();
@@ -151,7 +162,7 @@ function toJson(value) {
     flagsFor(step, requested, v2 = this.v2) {
         const { flags, dropped } = resolveFlags(step, requested, v2);
         if (dropped && development()) {
-            logger.warn(`Dropped flags ${flagNames(dropped).join(', ')}, which a ${step} cannot take.`);
+            logger.warn(droppedFlagsWarning(step, dropped));
         }
         return flags;
     }
@@ -414,15 +425,15 @@ function toJson(value) {
         });
     }
     /**
-   * Undoes `@Defer`'s acknowledgement after a guard denied the call silently: a command's deferred
-   * reply is deleted while nothing was sent into it; a component's invisible acknowledgement needs
-   * nothing. Never throws.
+   * Ends a call a guard denied silently. A component still unanswered is acknowledged invisibly, with or without
+   * `@Defer`, since Discord tells the user an unanswered call failed; so is a command `@Defer`'s 'auto' timer was
+   * waiting on, whose deferred reply is then deleted, as `@Defer`'s is while nothing was sent into it. Never throws.
    */ abandon() {
         const waiting = this.timer !== undefined;
         this.cancelScheduled();
         return this.queued(async ()=>{
-            // Denied before the 'auto' timer: acknowledged here, since Discord tells the user an unanswered call failed
-            if (waiting) await this.acknowledgeUnanswered({
+            // A command's acknowledgement shows "thinking…", so one is made only for the timer that would have made it
+            if (waiting || !answersWithOwnMessage(this.interaction)) await this.acknowledgeUnanswered({
                 ephemeral: true
             });
             this.sync();
@@ -675,7 +686,7 @@ function toJson(value) {
         } catch (error) {
             const message = this.message;
             const expired = Date.now() - this.interaction.createdTimestamp >= TOKEN_EXPIRED_AFTER_MS;
-            if (!TOKEN_EXPIRED.has(errorCode(error)) || !expired || !this.location.botInstalled || !message) throw error;
+            if (!TOKEN_EXPIRED.has(errorCode(error)) || !expired || !isBotInstalled(this.interaction) || !message) throw error;
             this.lastMessage = await this.call('message.edit', sent, ()=>message.edit(sent));
         }
         this.phase = 'replied';
@@ -987,6 +998,10 @@ function toJson(value) {
         } : body;
     }
     constructor(interaction){
+        Object.defineProperty(this, _location, {
+            writable: true,
+            value: void 0
+        });
         this.interaction = interaction;
         this.phase = 'unanswered';
         /** The answer steps asked for, run one after another; `pending` counts those not yet settled. */ this.queue = Promise.resolve();
@@ -1004,7 +1019,14 @@ function toJson(value) {
         this.suppressNotifications = false;
         // Set by @Defer's first step, so an error can name what acknowledged the interaction
         this.underDefer = false;
-        this.location = getInstallContext(interaction);
+        Object.defineProperty(this, 'location', {
+            get: ()=>{
+                var _class_private_field_loose_base1, _location1;
+                return (_class_private_field_loose_base1 = _class_private_field_loose_base(this, _location))[_location1 = _location] ?? (_class_private_field_loose_base1[_location1] = getInstallContext(interaction));
+            },
+            enumerable: true,
+            configurable: true
+        });
         const message = 'message' in interaction ? interaction.message : undefined;
         this.v2 = Boolean(message?.flags?.has(MessageFlags.IsComponentsV2));
     }

package/dist/esm/common/sharded-cooldown-store.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { CooldownStore, withRelease, MemoryCooldownStore, forgetRecorded, recordedOf } from './cooldown-store.js';
+import { CooldownStore, singleVerdict, withRelease, MemoryCooldownStore, forgetRecorded, recordedOf } from './cooldown-store.js';
 import { isShardMessage } from '../core/shard-messages.js';
 import { managerGone } from '../util/sharding-mode.util.js';
 import { isShardProcess } from '../util/shard-process.util.js';
@@ -60,16 +60,12 @@ import { isShardProcess } from '../util/shard-process.util.js';
    * @param limit - The calls allowed, and the window they are counted over.
    * @returns Whether this call was recorded, and if not, how long until one can be.
    */ async consume(key, limit) {
-        const { allowed, retryAfterMs } = await this.consumeMany([
+        return singleVerdict(await this.consumeMany([
             {
                 key,
                 limit
             }
-        ]);
-        return {
-            allowed,
-            retryAfterMs
-        };
+        ]));
     }
     /**
    * Records a call against every entry if all allow it, in one message to the manager.
@@ -108,11 +104,17 @@ import { isShardProcess } from '../util/shard-process.util.js';
             this.pending.set(id, {
                 resolve: (verdict, recorded)=>{
                     settle();
-                    // The manager's undo is the calls it recorded, sent back to it
-                    const release = async ()=>channel.send({
+                    // The manager's undo is the calls it recorded, sent back once: it finds a call by key and time, so a second
+                    // undo would take another call recorded in the same millisecond
+                    let released = false;
+                    const release = async ()=>{
+                        if (released) return;
+                        released = true;
+                        channel.send({
                             meocord: 'cooldown-release',
                             recorded: recorded ?? []
                         });
+                    };
                     resolve(!peek && verdict.allowed && recorded ? withRelease(verdict, release) : verdict);
                 },
                 reject: (error)=>(settle(), reject(error))

package/dist/esm/common/theme.js

@@ -2,6 +2,7 @@ import { warnDeprecated } from './deprecation.js';
 import { Logger } from './logger.js';
 import { useTheme, setLegacyThemeLayer } from '../core/theme-scope.js';
 import { themeProblems } from '../core/theme-validation.js';
+import { shared } from '../util/shared-state.util.js';
 
 /** The theme role each static stands for; `errorColor` is a fault in the bot, `danger`. */ const ROLES = {
     primaryColor: 'primary',
@@ -11,7 +12,8 @@ import { themeProblems } from '../core/theme-validation.js';
     warningColor: 'warning'
 };
 const logger = new Logger('Theme');
-const assigned = {};
+// One per process for this meocord version, so a static set through one build keeps those set through the other
+const assigned = shared('legacyThemeColors', ()=>({}));
 /** Reads a role of the theme where it is read, warning once a run for each static read. */ function read(name) {
     warnDeprecated(logger, `Theme.${name}`, `useTheme().colors.${ROLES[name]}`);
     return useTheme().colors[ROLES[name]];

package/dist/esm/common/translator.js

@@ -69,17 +69,36 @@ import { sharedName } from '../util/shared-state.util.js';
 }
 const DISCORD_LOCALES = new Set(Object.values(Locale));
 const languageOf = (locale)=>locale.split('-')[0];
-/** A message by its dotted key, or undefined when the catalog lacks it or the key names a group. */ function lookup(catalog, key) {
+const PLURAL_CATEGORIES = new Set([
+    'zero',
+    'one',
+    'two',
+    'few',
+    'many',
+    'other'
+]);
+/** A plural's shape: a non-empty object whose every key is a plural category, as the types read one; any other is a group. */ const isPluralShape = (value)=>typeof value === 'object' && value !== null && Object.keys(value).length > 0 && Object.keys(value).every((key)=>PLURAL_CATEGORIES.has(key));
+/** The value at a dotted key's path, or undefined where the path ends early. */ function valueAt(catalog, key) {
     let current = catalog;
     for (const part of key.split('.')){
         if (typeof current !== 'object' || current === null) return undefined;
         current = current[part];
     }
+    return current;
+}
+/**
+ * A message by its dotted key, or undefined when the catalog lacks it or the key names a group. `reference`, the
+ * default catalog for a translation, decides where it has a group that an object is that group, so a translation that
+ * keeps only a group's `other` message isn't read as a plural. Where it has a message, or lacks the key, the object's
+ * own keys decide, so a translation may give a plural for a message its language needs one for. A plural without an
+ * `other` form reads as missing, so a translation that left it out falls back to the next catalog.
+ */ function lookup(catalog, key, reference = catalog) {
+    const current = valueAt(catalog, key);
     if (typeof current === 'string') return current;
-    if (typeof current === 'object' && current !== null && typeof current.other === 'string') {
-        return current;
-    }
-    return undefined;
+    if (!isPluralShape(current) || typeof current.other !== 'string') return undefined;
+    const shape = reference === catalog ? current : valueAt(reference, key);
+    const group = typeof shape === 'object' && shape !== null && !isPluralShape(shape);
+    return group ? undefined : current;
 }
 const plurals = new Map();
 /** The form of a found message to use: a plain message itself, or a plural's form for `count` in its locale's rules. */ function pluralForm({ message, locale }, count) {
@@ -143,7 +162,7 @@ class CatalogTranslator extends Translator {
     }
     translate(requested, key, params = {}) {
         for (const locale of this[LOCALE_CHAIN](requested)){
-            const message = lookup(this.catalogs[locale], key);
+            const message = lookup(this.catalogs[locale], key, this.catalogs[this.defaultLocale]);
             if (message === undefined) continue;
             // An empty translation, as tools export an untranslated string, counts as missing: Discord refuses an empty reply
             const text = pluralForm({
@@ -179,7 +198,7 @@ class CatalogTranslator extends Translator {
         const localized = {};
         for (const locale of this.locales){
             if (locale === this.defaultLocale) continue;
-            const message = lookup(this.catalogs[locale], key);
+            const message = lookup(this.catalogs[locale], key, this.catalogs[this.defaultLocale]);
             // A translation with a {param} is left out, as Discord would show it as written, and so is an empty one
             if (typeof message === 'string' && message !== '' && placeholderNames(message).length === 0) {
                 localized[locale] = fillPlaceholders(message, (_name, whole)=>whole);
@@ -278,4 +297,4 @@ class CatalogTranslator extends Translator {
     return new CatalogTranslator(defaultLocale, locales);
 }
 
-export { CATALOGS, LOCALE_CHAIN, Translator, createTranslator, defineCatalog, fillPlaceholders, languageOf, lookup, missingTranslatorError, placeholderNames, pluralForm };
+export { CATALOGS, LOCALE_CHAIN, Translator, createTranslator, defineCatalog, fillPlaceholders, isPluralShape, languageOf, lookup, missingTranslatorError, placeholderNames, pluralForm };

package/dist/esm/core/autocomplete-routes.js

@@ -0,0 +1,26 @@
+import { getAutocompleteHandlers } from '../decorator/controller.decorator.js';
+import { focusedOptionName, resolveCommandPaths } from '../util/interaction.util.js';
+
+/**
+ * Every `@Autocomplete` handler of the given controllers, read from their metadata, with the handlers of one option
+ * before those of a whole command, so an option's handler wins over its command's whatever order they are declared in.
+ */ function buildAutocompleteRoutes(controllers) {
+    const routes = controllers.flatMap((controllerClass)=>getAutocompleteHandlers(controllerClass.prototype).map((meta)=>({
+                controllerClass,
+                meta
+            })));
+    return routes.sort((a, b)=>Number(Boolean(b.meta.optionName)) - Number(Boolean(a.meta.optionName)));
+}
+/**
+ * The handler an autocomplete reaches, as dispatch routes it: its full command path, then its command's name, and at
+ * each the first handler whose option is the focused one, or that names none.
+ */ function matchAutocompleteRoute(routes, interaction) {
+    const focused = focusedOptionName(interaction);
+    for (const path of resolveCommandPaths(interaction)){
+        const route = routes.find(({ meta })=>meta.commandPath === path && (meta.optionName === undefined || meta.optionName === focused));
+        if (route) return route;
+    }
+    return undefined;
+}
+
+export { buildAutocompleteRoutes, matchAutocompleteRoute };

package/dist/esm/core/command-conflicts.js

@@ -1,6 +1,7 @@
 import { ApplicationCommandType, ApplicationCommandOptionType } from 'discord.js';
 import { Logger } from '../common/logger.js';
-import { getAutocompleteHandlers, getCommandMap, getDeclaredRoutes, getHandlerRoutes, getMessageHandlers, getReactionHandlers } from '../decorator/controller.decorator.js';
+import { getAutocompleteHandlers, getCommandMap, getDeclaredRoutes, ownEventHandlers, eventRoute, getHandlerRoutes, getMessageHandlers, getReactionHandlers } from '../decorator/controller.decorator.js';
+import { getEventHandlers } from '../decorator/event.decorator.js';
 import { serialise, registrationKey, SENT_AS, commandNameOf } from './command-registration.js';
 import { buildComponentRoutes, findComponentRouteConflicts } from './component-routes.js';
 import { CommandType } from '../enum/controller.enum.js';
@@ -246,9 +247,9 @@ const quoted = (names)=>names.length < 2 ? names.map((name)=>`"${name}"`).join('
 }
 /**
  * Warns about a handler a subclass re-declares on other routes while it still answers the ones it inherits, for
- * `@Command`, `@MessageHandler`, `@ReactionHandler` and `@Autocomplete` alike. The next major version (5.0) drops
- * the inherited routes. Every class a listed controller extends is checked, a base that is not listed included, for
- * the methods the controller still inherits through it.
+ * `@Command`, `@MessageHandler`, `@ReactionHandler`, `@Autocomplete`, `@On` and `@Once` alike. The next major version
+ * (5.0) drops the inherited routes. Every class a listed controller extends is checked, a base that is not listed
+ * included, for the methods the controller still inherits through it.
  */ function warnInheritedRoutes(controllerClasses) {
     // A set, so a class two listed controllers extend is named once, for the routes either of them still answers
     const problems = new Set();
@@ -257,11 +258,18 @@ const quoted = (names)=>names.length < 2 ? names.map((name)=>`"${name}"`).join('
         // nothing of them from above it, so a class above is not named for them
         const cut = new Set();
         for(let prototype = controllerClass.prototype; prototype && prototype !== Object.prototype; prototype = Object.getPrototypeOf(prototype)){
-            const declared = getDeclaredRoutes(prototype);
             const base = Object.getPrototypeOf(prototype);
-            if (declared.length === 0 || !base) continue;
+            if (!base) continue;
+            const declared = [
+                ...getDeclaredRoutes(prototype),
+                ...ownEventHandlers(prototype).map(eventRoute)
+            ];
+            if (declared.length === 0) continue;
             if (Reflect.getOwnMetadata(META.replacesInheritedRoutes, prototype)) for (const route of declared)cut.add(route.method);
-            const inherited = getHandlerRoutes(base).filter((route)=>!cut.has(route.method));
+            const inherited = [
+                ...getHandlerRoutes(base),
+                ...getEventHandlers(base).map(eventRoute)
+            ].filter((route)=>!cut.has(route.method));
             for (const method of new Set(declared.map((route)=>route.method))){
                 const own = [
                     ...new Set(declared.filter((route)=>route.method === method).map((route)=>route.label))

package/dist/esm/core/command-registration.js

@@ -61,6 +61,7 @@ import { CommandType } from '../enum/controller.enum.js';
                 if (existing === undefined) {
                     const name = typeof body.name === 'string' ? body.name : commandName;
                     unlocalizable.push(...localizationProblems(name, body));
+                    const builderName = builderClass?.name;
                     byKey.set(key, {
                         builderClass: builderClass ?? builder,
                         command: {
@@ -68,6 +69,9 @@ import { CommandType } from '../enum/controller.enum.js';
                             body,
                             ...guilds && {
                                 guilds
+                            },
+                            ...typeof builderName === 'string' && builderName && {
+                                builder: builderName
                             }
                         }
                     });
@@ -105,6 +109,14 @@ const scopeKey = (scope)=>scope === 'global' ? 'global' : `guild-${scope.guild}`
 }
 /** Whether a command is an activity's primary entry point, which Discord takes only globally. */ const isEntryPoint = (command)=>command.body.type === ApplicationCommandType.PrimaryEntryPoint;
 /** What a blank guild to register every command to says, as an unset variable gives one. */ const BLANK_GUILD = 'No commands were registered: the guild to register to is blank. Give a guild id, or leave it out to register where commands.* says.';
+/**
+ * Names every command whose builder lists guilds but no guild id, each with its builder, and says the run registers
+ * none of them yet still succeeds.
+ */ function blankGuildsWarning(commands) {
+    const one = commands.length === 1;
+    const lines = commands.map((command)=>`  ${command.builder ? `${command.builder}: ` : ''}"${command.name}"`);
+    return `${commands.length} ${one ? 'command is' : 'commands are'} not registered: ${one ? 'its builder lists' : 'their builders list'} ` + 'no guild ids, as when the variable holding them is unset.\n' + `${lines.join('\n')}\n` + 'Set the guild ids; a builder without guilds registers where commands.* says. `meocord register` still exits 0 for ' + 'these; the next major version (5.0) exits 1.';
+}
 /**
  * Where each command is sent: one bulk update per scope. A scope's update replaces everything the application has
  * there, so the default scope is included even when it ends up empty, unless `commands.guilds` lists no guild id.
@@ -148,6 +160,7 @@ const scopeKey = (scope)=>scope === 'global' ? 'global' : `guild-${scope.guild}`
         guild
     });
     const unregistered = [];
+    const blankGuilds = [];
     for (const command of commands){
         if (isEntryPoint(command)) {
             if (command.guilds) {
@@ -157,7 +170,7 @@ const scopeKey = (scope)=>scope === 'global' ? 'global' : `guild-${scope.guild}`
         } else if (command.guilds) {
             const own = ids(command.guilds);
             // Falling back to the default scope could publish a staff-only command everywhere.
-            if (own.length === 0) logger.warn(`Command "${command.name}" lists no guild ids in its builder, so it is not registered.`);
+            if (own.length === 0) blankGuilds.push(command);
             for (const guild of own)add({
                 guild
             }, command);
@@ -171,6 +184,7 @@ const scopeKey = (scope)=>scope === 'global' ? 'global' : `guild-${scope.guild}`
             }, command);
         }
     }
+    if (blankGuilds.length > 0) logger.warn(blankGuildsWarning(blankGuilds));
     if (nowhere) {
         const outcome = unregistered.length === 0 ? targets.has('global') ? 'only the entry point command is registered globally' : 'nothing is registered globally' : `${unregistered.join(', ')} ${unregistered.length === 1 ? 'is' : 'are'} not registered, rather than registered globally`;
         logger.warn(`commands.guilds lists no guild id, as an unset environment variable leaves it, so ${outcome}. ` + `Set the guild ids, or remove commands.guilds to register globally.`);

package/dist/esm/core/cooldown-runner.js

@@ -1,18 +1,17 @@
 import 'reflect-metadata';
 import { BaseInteraction, Message } from 'discord.js';
-import { CooldownStoreError, CooldownError } from '../common/errors.js';
+import { CooldownError, CooldownStoreError } from '../common/errors.js';
 import { CooldownStore, MemoryCooldownStore } from '../common/cooldown-store.js';
 import { Logger } from '../common/logger.js';
-import { perHandler, sourcePrototype, stageClasses } from './guard-runner.js';
+import { perHandler, methodStages, sourcePrototype, stageClasses } from './guard-runner.js';
 import { META } from '../util/metadata-keys.js';
 
-/** The cooldowns on a handler: each class's, base first, then the method's. */ const handlerCooldowns = perHandler((prototype, methodName)=>{
-    const source = sourcePrototype(prototype, methodName);
-    if (!source) return [];
+/** The cooldowns on a handler: each class's, base first, then the method's and its overrides', base first. */ const handlerCooldowns = perHandler((prototype, methodName)=>{
+    if (!sourcePrototype(prototype, methodName)) return [];
     return [
         // Base first, as guards run
         ...stageClasses(prototype, methodName).flatMap((cls)=>Reflect.getOwnMetadata(META.classCooldowns, cls) ?? []),
-        ...Reflect.getOwnMetadata(META.methodCooldowns, source, methodName) ?? []
+        ...methodCooldowns(prototype, methodName)
     ];
 });
 /** The counted cooldowns of each list {@link handlerCooldowns} gives, which is the same for a handler. */ const countedCooldowns = new WeakMap();
@@ -53,9 +52,8 @@ import { META } from '../util/metadata-keys.js';
     }
     return counted;
 }
-/** The cooldowns declared on a method itself. */ function methodCooldowns(prototype, methodName) {
-    const source = sourcePrototype(prototype, methodName);
-    return source ? Reflect.getOwnMetadata(META.methodCooldowns, source, methodName) ?? [] : [];
+/** The cooldowns declared on a method itself and on the methods it overrides, base first. */ function methodCooldowns(prototype, methodName) {
+    return methodStages(prototype, methodName, META.methodCooldowns);
 }
 /** Who and where a call came from: an interaction's or a message's user, server and channel. */ function caller(first) {
     if (first instanceof BaseInteraction) return {

package/dist/esm/core/defer.js

@@ -1,15 +1,12 @@
 import 'reflect-metadata';
-import { perHandler, sourcePrototype } from './guard-runner.js';
+import { perHandler, nearestMethodStage } from './guard-runner.js';
 import { getMessageHandlers, getReactionHandlers, getAutocompleteHandlers } from '../decorator/controller.decorator.js';
 import { getEventHandlers } from '../decorator/event.decorator.js';
 import { META } from '../util/metadata-keys.js';
 
 /** How long `@Defer({ mode: 'auto' })` waits for an answer by default. */ const AUTO_DEFER_AFTER_MS = 1500;
 /** The latest `'auto'` acknowledges, counted from the interaction's creation: Discord allows three seconds. */ const AUTO_DEFER_LIMIT_MS = 2500;
-/** The `@Defer` options of a handler, read where the handler is declared. */ const handlerDefer = perHandler((prototype, methodName)=>{
-    const source = sourcePrototype(prototype, methodName);
-    return source ? Reflect.getOwnMetadata(META.deferOptions, source, methodName) : undefined;
-});
+/** The `@Defer` options of a handler: its own, or else those of the nearest method it overrides that has them. */ const handlerDefer = perHandler((prototype, methodName)=>nearestMethodStage(prototype, methodName, META.deferOptions));
 /** The kind of non-interaction handler a method is, if any: `@Defer` cannot apply to one. */ function nonInteractionHandler(prototype, methodName) {
     if (getMessageHandlers(prototype).some((handler)=>handler.method === methodName)) return 'message';
     if (getReactionHandlers(prototype).some((handler)=>handler.method === methodName)) return 'reaction';