@helyx/bot 0.4.33 → 0.4.36

package/dist/events.js

@@ -3,6 +3,20 @@ import { ChannelType, Events, GatewayIntentBits, GuildMemberFlags, PermissionFla
 import { toReplyOptions } from "./interactions.js";
 import { createHash } from "node:crypto";
 import { classifyGuildMessage, unavailableGuildMessageClassification, } from "./message-classification.js";
+function availabilityAwareInstallations(services) {
+    const installations = services.get(HELYX_SERVICE_NAMES.installations);
+    const candidate = typeof services.has === "function" &&
+        services.has(HELYX_SERVICE_NAMES.moduleAvailability)
+        ? services.get(HELYX_SERVICE_NAMES.moduleAvailability)
+        : null;
+    const availability = typeof candidate?.isAvailable === "function" ? candidate : null;
+    return {
+        async isModuleEnabled(guildId, moduleId) {
+            return ((!availability || (await availability.isAvailable(moduleId))) &&
+                installations.isModuleEnabled(guildId, moduleId));
+        },
+    };
+}
 export function installModuleEvents(client, modules, logger, services) {
     const privilegedMessageContributions = modules.flatMap((module) => (module.events?.privilegedMessageCreate ?? []).map((contribution) => ({
         moduleId: module.manifest.id,
@@ -113,7 +127,7 @@ export function installModuleEvents(client, modules, logger, services) {
             if (!message.guildId || !privilegedEligibilityQueue)
                 return;
             privilegedEligibilityQueue.enqueue(message.guildId, async () => {
-                const installations = services.get(HELYX_SERVICE_NAMES.installations);
+                const installations = availabilityAwareInstallations(services);
                 const eligible = [];
                 for (const item of privilegedMessageContributions) {
                     try {
@@ -260,7 +274,7 @@ export function installModuleEvents(client, modules, logger, services) {
         });
     }
     async function handleResourceLifecycle(contributions, serverId, identifier, resourceId, eventName) {
-        const installations = services.get(HELYX_SERVICE_NAMES.installations);
+        const installations = availabilityAwareInstallations(services);
         for (const { moduleId, contribution } of contributions) {
             try {
                 if (!(await installations.isModuleEnabled(serverId, moduleId))) {
@@ -286,8 +300,11 @@ export function installModuleEvents(client, modules, logger, services) {
     async function handlePrivilegedMessageCreate(message, contributions) {
         if (!message.guildId || !message.channelId)
             return;
+        const installations = availabilityAwareInstallations(services);
         for (const { moduleId, contribution } of contributions) {
             try {
+                if (!(await installations.isModuleEnabled(message.guildId, moduleId)))
+                    continue;
                 await contribution.execute({
                     serverId: message.guildId,
                     channelId: message.channelId,
@@ -316,7 +333,7 @@ export function installModuleEvents(client, modules, logger, services) {
     async function handleGuildMessageCreate(message) {
         if (!message.guildId || !message.channelId)
             return;
-        const installations = services.get(HELYX_SERVICE_NAMES.installations);
+        const installations = availabilityAwareInstallations(services);
         const parentChannelId = message.channel.isThread()
             ? (message.channel.parentId ?? undefined)
             : undefined;
@@ -410,7 +427,7 @@ export function installModuleEvents(client, modules, logger, services) {
                 : reaction.message;
             if (!message.guildId || !message.channelId)
                 return;
-            const installations = services.get(HELYX_SERVICE_NAMES.installations);
+            const installations = availabilityAwareInstallations(services);
             const member = await message.guild?.members.fetch(user.id);
             const userRoleIds = member ? [...member.roles.cache.keys()] : [];
             const parentChannelId = messageParentChannelId(message);
@@ -467,7 +484,7 @@ export function installModuleEvents(client, modules, logger, services) {
     async function handleMemberAdd(member) {
         if (!member.joinedAt)
             throw new Error("Discord member join timestamp is unavailable");
-        const installations = services.get(HELYX_SERVICE_NAMES.installations);
+        const installations = availabilityAwareInstallations(services);
         for (const { moduleId, contribution } of memberAddContributions) {
             try {
                 if (!(await installations.isModuleEnabled(member.guild.id, moduleId))) {
@@ -498,7 +515,7 @@ export function installModuleEvents(client, modules, logger, services) {
         }
     }
     async function handleMemberRemove(member) {
-        const installations = services.get(HELYX_SERVICE_NAMES.installations);
+        const installations = availabilityAwareInstallations(services);
         for (const { moduleId, contribution } of memberRemoveContributions) {
             try {
                 if (!(await installations.isModuleEnabled(member.guild.id, moduleId))) {
@@ -536,7 +553,7 @@ export function installModuleEvents(client, modules, logger, services) {
                 : reaction.message;
             if (!message.guildId || !message.channelId)
                 return;
-            const installations = services.get(HELYX_SERVICE_NAMES.installations);
+            const installations = availabilityAwareInstallations(services);
             const parentChannelId = messageParentChannelId(message);
             for (const { moduleId, contribution } of reactionRemoveContributions) {
                 if (!(await installations.isModuleEnabled(message.guildId, moduleId))) {
@@ -580,7 +597,7 @@ export function installModuleEvents(client, modules, logger, services) {
             : receivedMessage;
         if (!message.guildId || !message.channelId)
             return;
-        const installations = services.get(HELYX_SERVICE_NAMES.installations);
+        const installations = availabilityAwareInstallations(services);
         for (const { moduleId, contribution } of reactionRemoveAllContributions) {
             try {
                 if (!(await installations.isModuleEnabled(message.guildId, moduleId)))
@@ -610,7 +627,7 @@ export function installModuleEvents(client, modules, logger, services) {
         const message = reaction.message;
         if (!message.guildId || !message.channelId)
             return;
-        const installations = services.get(HELYX_SERVICE_NAMES.installations);
+        const installations = availabilityAwareInstallations(services);
         for (const { moduleId, contribution } of reactionRemoveEmojiContributions) {
             try {
                 if (!(await installations.isModuleEnabled(message.guildId, moduleId)))
@@ -638,7 +655,7 @@ export function installModuleEvents(client, modules, logger, services) {
     async function handleMessageUpdate(receivedMessage) {
         if (!receivedMessage.guildId || !receivedMessage.channelId)
             return;
-        const installations = services.get(HELYX_SERVICE_NAMES.installations);
+        const installations = availabilityAwareInstallations(services);
         for (const { moduleId, contribution } of messageUpdateContributions) {
             try {
                 if (!(await installations.isModuleEnabled(receivedMessage.guildId, moduleId)))
@@ -672,7 +689,7 @@ export function installModuleEvents(client, modules, logger, services) {
     async function handleMessageDelete(message) {
         if (!message.guildId || !message.channelId)
             return;
-        const installations = services.get(HELYX_SERVICE_NAMES.installations);
+        const installations = availabilityAwareInstallations(services);
         for (const { moduleId, contribution } of messageDeleteContributions) {
             try {
                 if (!(await installations.isModuleEnabled(message.guildId, moduleId))) {
@@ -699,7 +716,7 @@ export function installModuleEvents(client, modules, logger, services) {
     async function handleMessageDeleteBulk(guildId, channelId, messageIds) {
         if (messageIds.length === 0)
             return;
-        const installations = services.get(HELYX_SERVICE_NAMES.installations);
+        const installations = availabilityAwareInstallations(services);
         const boundedIds = messageIds.slice(0, 100);
         for (const { moduleId, contribution } of messageDeleteBulkContributions) {
             try {
@@ -733,7 +750,7 @@ export function installModuleEvents(client, modules, logger, services) {
             voiceSessions.delete(key);
             const endedAt = new Date();
             const durationSeconds = Math.max(1, Math.floor((endedAt.getTime() - previous.startedAt.getTime()) / 1_000));
-            const installations = services.get(HELYX_SERVICE_NAMES.installations);
+            const installations = availabilityAwareInstallations(services);
             for (const { moduleId, contribution } of guildVoiceSessionContributions) {
                 try {
                     if (!(await installations.isModuleEnabled(previous.guildId, moduleId)))
@@ -813,13 +830,18 @@ class BoundedGuildEventQueue {
         this.#accepting = false;
         if (this.#active === 0 && this.#pending.length === 0)
             return;
-        await Promise.race([
-            new Promise((resolve) => this.#drainWaiters.add(resolve)),
+        const drain = new Promise((resolve) => this.#drainWaiters.add(resolve));
+        const drainedBeforeDeadline = await Promise.race([
+            drain.then(() => true),
             new Promise((resolve) => {
-                const timer = setTimeout(resolve, 5_000);
+                const timer = setTimeout(() => resolve(false), 5_000);
                 timer.unref();
             }),
         ]);
+        if (!drainedBeforeDeadline) {
+            this.logger.warn({ event: "module.event_stop_deadline_exceeded" }, "Module gateway event queue is still draining after its shutdown deadline");
+            await drain;
+        }
         this.#pending.length = 0;
     }
     #pump() {

package/dist/index.js

@@ -1,4 +1,5 @@
 import { parseBotEnvironment } from "@helyx/config";
+import { StatusHeartbeatReporter } from "@helyx/status-client";
 import { safeError, ServiceRegistry } from "@helyx/core";
 import { checkDatabaseConnection, createDatabasePool, AuditRepository, InteractionSessionRepository, RateLimitRepository, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
 import { createRuntime } from "@helyx/framework";
@@ -44,9 +45,45 @@ export async function startBot(processEnvironment = process.env) {
         return startShardWorker(processEnvironment, parseShardWorkerLaunchContract(processEnvironment.HELYX_SHARD_WORKER_CONTRACT));
     const environment = parseBotEnvironment(processEnvironment);
     bootstrapLogger.level = environment.LOG_LEVEL;
-    if (environment.HELYX_SHARD_MODE !== "off")
-        return startShardSupervisor(environment, processEnvironment, resolveBotWorkerEntryPoint());
-    return startUnshardedBot(processEnvironment);
+    const handle = environment.HELYX_SHARD_MODE !== "off"
+        ? await startShardSupervisor(environment, processEnvironment, resolveBotWorkerEntryPoint())
+        : await startUnshardedBot(processEnvironment);
+    if (!environment.HELYX_STATUS_ENABLED)
+        return handle;
+    const processStartedAt = new Date().toISOString();
+    const reporter = new StatusHeartbeatReporter({
+        producer: "bot",
+        baseUrl: environment.HELYX_STATUS_URL,
+        secret: environment.HELYX_STATUS_HEARTBEAT_SECRET,
+        accessClientId: environment.CF_ACCESS_CLIENT_ID,
+        accessClientSecret: environment.CF_ACCESS_CLIENT_SECRET,
+        intervalSeconds: environment.HELYX_STATUS_HEARTBEAT_INTERVAL_SECONDS,
+        services: () => [
+            {
+                key: "discord-bot",
+                state: "operational",
+                processStartedAt,
+                release: readBotVersion(),
+            },
+            {
+                key: "creator-connections",
+                state: environment.HELYX_OAUTH_ENABLED ? "operational" : "major_outage",
+                reasonCode: environment.HELYX_OAUTH_ENABLED ? null : "feature_disabled",
+                processStartedAt,
+                release: readBotVersion(),
+            },
+        ],
+        onError(error) {
+            bootstrapLogger.warn({ event: "status.heartbeat_failed", reason: error.message }, "Status heartbeat could not be delivered");
+        },
+    });
+    reporter.start();
+    return {
+        async shutdown(reason) {
+            await reporter.stop();
+            await handle.shutdown(reason);
+        },
+    };
 }
 export function resolveBotWorkerEntryPoint(entryUrl = import.meta.url) {
     return fileURLToPath(entryUrl);
@@ -254,6 +291,9 @@ async function startUnshardedBot(processEnvironment) {
         })) {
             platformServices.set(name, service);
         }
+        await serviceAccess
+            .get(HELYX_SERVICE_NAMES.moduleAvailability)
+            .refresh();
         if (environment.HELYX_VERIFICATION_ENABLED &&
             environment.HELYX_VERIFICATION_URL &&
             environment.HELYX_VERIFICATION_INTERNAL_SECRET) {

package/dist/interactions.d.ts

@@ -1,5 +1,6 @@
 import type { CommandContribution, MessageResponse, ModalDefinition, ModuleDefinition, ServiceAccess } from "@helyx/sdk";
 import { ModalBuilder, type ChatInputCommandInteraction, type Client, type InteractionReplyOptions, type InteractionUpdateOptions } from "discord.js";
+export declare const GLOBAL_MODULE_UNAVAILABLE_MESSAGE = "This module is temporarily unavailable for all hosted servers.";
 export interface InteractionLogger {
     info(fields: Record<string, unknown>, message: string): void;
     warn(fields: Record<string, unknown>, message: string): void;
@@ -16,7 +17,7 @@ export declare function buildApplicationCommandDefinitions(modules: readonly Mod
     global: ReturnType<typeof toCommandDefinition>[];
     guild: ReturnType<typeof toCommandDefinition>[];
 };
-export declare function resolveCommandExecutor(command: CommandContribution, subcommandName: string | null): CommandContribution["execute"];
+export declare function resolveCommandExecutor(command: CommandContribution, subcommandName: string | null, groupName?: string | null): CommandContribution["execute"];
 export declare function toCommandDefinition(registered: {
     contribution: CommandContribution;
 }): import("discord.js").RESTPostAPIChatInputApplicationCommandsJSONBody;
@@ -27,7 +28,7 @@ export declare function sendToChannel(client: Client, channelId: string, respons
 export declare function deleteChannelMessage(client: Client, channelId: string, messageId: string): Promise<void>;
 export declare function editChannelMessage(client: Client, channelId: string, messageId: string, response: MessageResponse): Promise<void>;
 export declare function addChannelMessageReaction(client: Client, channelId: string, messageId: string, emojiIdentifier: string): Promise<void>;
-export declare function authorizeCommand(interaction: ChatInputCommandInteraction, moduleId: string, commandId: string, rateLimit: CommandContribution["rateLimit"], services: ServiceAccess, selfAuthorizingGuildCommand: boolean, resourceScopedCommand?: boolean): Promise<boolean>;
+export declare function authorizeCommand(interaction: ChatInputCommandInteraction, moduleId: string, commandId: string, rateLimit: CommandContribution["rateLimit"], services: ServiceAccess, selfAuthorizingGuildCommand: boolean, resourceScopedCommand?: boolean, requiredModuleName?: string): Promise<boolean>;
 export declare function normalizeDiscordPermission(permission: string): string;
 export declare function toReplyOptions(response: MessageResponse): InteractionReplyOptions;
 export declare function toUpdateOptions(response: MessageResponse): InteractionUpdateOptions;

package/dist/interactions.js

@@ -1,6 +1,7 @@
 import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
 import { canUseCommand } from "@helyx/core";
 import { ActionRowBuilder, ButtonBuilder, ButtonStyle, ChannelSelectMenuBuilder, EmbedBuilder, Events, GuildMember, ApplicationIntegrationType, ChannelType, InteractionContextType, LabelBuilder, MessageFlags, MentionableSelectMenuBuilder, ModalBuilder, RoleSelectMenuBuilder, StringSelectMenuBuilder, SlashCommandBuilder, TextInputBuilder, TextInputStyle, UserSelectMenuBuilder, TextDisplayBuilder, PermissionFlagsBits, escapeMarkdown, } from "discord.js";
+import { collectCommandRegistrations, } from "./nexus-commands.js";
 const buttonStyles = {
     primary: ButtonStyle.Primary,
     secondary: ButtonStyle.Secondary,
@@ -8,11 +9,18 @@ const buttonStyles = {
     danger: ButtonStyle.Danger,
     link: ButtonStyle.Link,
 };
+export const GLOBAL_MODULE_UNAVAILABLE_MESSAGE = "This module is temporarily unavailable for all hosted servers.";
+async function moduleIsGloballyAvailable(services, moduleId) {
+    if (typeof services.has !== "function" ||
+        !services.has(HELYX_SERVICE_NAMES.moduleAvailability))
+        return true;
+    const availability = services.get(HELYX_SERVICE_NAMES.moduleAvailability);
+    return typeof availability?.isAvailable !== "function"
+        ? true
+        : availability.isAvailable(moduleId);
+}
 export function installInteractions(client, modules, registration, logger, services) {
-    const commands = uniqueMap(modules.flatMap((module) => (module.interactions?.commands ?? []).map((contribution) => ({
-        moduleId: module.manifest.id,
-        contribution,
-    }))), ({ contribution }) => contribution.name, "command name");
+    const commands = collectCommandRegistrations(modules);
     const globalCommands = [...commands.values()].filter(({ contribution }) => contribution.registration === "global");
     const guildCommands = [...commands.values()].filter(({ contribution }) => contribution.registration === "guild");
     if (guildCommands.length > 0 && !registration.internalGuildId) {
@@ -74,16 +82,20 @@ export function installInteractions(client, modules, registration, logger, servi
         try {
             if (interaction.isAutocomplete()) {
                 const registered = commands.get(interaction.commandName);
-                const subcommandName = registered?.contribution.subcommands?.length
+                const groupName = registered?.contribution.subcommandGroups?.length
+                    ? interaction.options.getSubcommandGroup(false)
+                    : null;
+                const subcommandName = hasNestedCommands(registered?.contribution)
                     ? interaction.options.getSubcommand(false)
                     : null;
-                const subcommand = subcommandName
-                    ? registered?.contribution.subcommands?.find(({ name }) => name === subcommandName)
-                    : undefined;
+                const subcommand = resolveCommandSubcommand(registered?.contribution, subcommandName, groupName);
+                const owner = resolveCommandOwner(registered, subcommandName, groupName);
                 if (!registered ||
                     !subcommand?.autocomplete ||
-                    !(await authorizeAutocomplete(interaction, registered.moduleId, subcommand.permissionId ??
-                        `${registered.contribution.name}.${subcommand.name}`, services, registration.selfAuthorizingGuildModuleIds?.has(registered.moduleId) ?? false, subcommand.authorization === "resource-scoped"))) {
+                    !(await authorizeAutocomplete(interaction, owner?.moduleId ?? registered.moduleId, subcommand.permissionId ??
+                        [registered.contribution.name, groupName, subcommand.name]
+                            .filter(Boolean)
+                            .join("."), services, registration.selfAuthorizingGuildModuleIds?.has(owner?.moduleId ?? registered.moduleId) ?? false, subcommand.authorization === "resource-scoped"))) {
                     await interaction.respond([]);
                     return;
                 }
@@ -91,24 +103,35 @@ export function installInteractions(client, modules, registration, logger, servi
             }
             else if (interaction.isChatInputCommand()) {
                 const registered = commands.get(interaction.commandName);
-                if (registered) {
+                if (!registered) {
+                    logger.warn({
+                        event: "interaction.stale_command",
+                        commandName: interaction.commandName,
+                    }, "Interaction used a command that is no longer loaded");
+                    await interaction.reply({
+                        content: "This command is no longer available. Refresh Discord and try again.",
+                        flags: MessageFlags.Ephemeral,
+                    });
+                    return;
+                }
+                {
                     const { contribution: command, moduleId } = registered;
-                    const subcommandName = command.subcommands?.length
+                    const groupName = command.subcommandGroups?.length
+                        ? interaction.options.getSubcommandGroup(false)
+                        : null;
+                    const subcommandName = hasNestedCommands(command)
                         ? interaction.options.getSubcommand(false)
                         : null;
-                    const subcommand = subcommandName
-                        ? command.subcommands?.find(({ name }) => name === subcommandName)
-                        : undefined;
-                    const execute = resolveCommandExecutor(command, subcommandName);
+                    const subcommand = resolveCommandSubcommand(command, subcommandName, groupName);
+                    const execute = resolveCommandExecutor(command, subcommandName, groupName);
                     if (!execute) {
                         logger.warn({
                             event: "interaction.stale_command",
                             commandName: command.name,
                             ...(subcommandName ? { subcommandName } : {}),
+                            ...(groupName ? { groupName } : {}),
                         }, "Interaction used an outdated command definition");
-                        const choices = (command.subcommands ?? [])
-                            .map(({ name }) => `\`/${command.name} ${name}\``)
-                            .join(" or ");
+                        const choices = commandChoices(command).join(" or ");
                         await interaction.reply({
                             content: choices
                                 ? `This command was recently updated. Refresh Discord, then use ${choices}.`
@@ -118,11 +141,19 @@ export function installInteractions(client, modules, registration, logger, servi
                         return;
                     }
                     const commandId = subcommandName
-                        ? `${command.name}.${subcommandName}`
+                        ? [command.name, groupName, subcommandName]
+                            .filter(Boolean)
+                            .join(".")
                         : command.name;
                     const permissionId = subcommand?.permissionId ?? command.permissionId ?? commandId;
-                    if (await authorizeCommand(interaction, moduleId, permissionId, subcommand?.rateLimit ?? command.rateLimit, services, registration.selfAuthorizingGuildModuleIds?.has(moduleId) ??
-                        false, subcommand?.authorization === "resource-scoped")) {
+                    const owner = resolveCommandOwner(registered, subcommandName, groupName);
+                    const ownerModuleId = owner?.moduleId ?? moduleId;
+                    const acknowledgement = subcommand?.acknowledgement ?? command.acknowledgement;
+                    if (acknowledgement === "deferred-ephemeral") {
+                        await interaction.deferReply({ flags: MessageFlags.Ephemeral });
+                    }
+                    if (await authorizeCommand(interaction, ownerModuleId, permissionId, subcommand?.rateLimit ?? command.rateLimit, services, registration.selfAuthorizingGuildModuleIds?.has(ownerModuleId) ??
+                        false, subcommand?.authorization === "resource-scoped", owner?.moduleName)) {
                         const context = createCommandContext(interaction, services);
                         await execute(context);
                     }
@@ -187,10 +218,7 @@ export function installInteractions(client, modules, registration, logger, servi
     return registrationReady;
 }
 export function buildApplicationCommandDefinitions(modules, internalGuildId) {
-    const commands = uniqueMap(modules.flatMap((module) => (module.interactions?.commands ?? []).map((contribution) => ({
-        moduleId: module.manifest.id,
-        contribution,
-    }))), ({ contribution }) => contribution.name, "command name");
+    const commands = collectCommandRegistrations(modules);
     const global = [...commands.values()]
         .filter(({ contribution }) => contribution.registration === "global")
         .map(toCommandDefinition);
@@ -201,11 +229,11 @@ export function buildApplicationCommandDefinitions(modules, internalGuildId) {
         throw new Error("DISCORD_INTERNAL_GUILD_ID is required when guild commands are loaded");
     return { global, guild };
 }
-export function resolveCommandExecutor(command, subcommandName) {
-    if (command.subcommands?.length) {
+export function resolveCommandExecutor(command, subcommandName, groupName = null) {
+    if (hasNestedCommands(command)) {
         if (!subcommandName)
             return undefined;
-        const subcommand = command.subcommands.find(({ name }) => name === subcommandName);
+        const subcommand = resolveCommandSubcommand(command, subcommandName, groupName);
         return subcommand ? (context) => subcommand.execute(context) : undefined;
     }
     return command.execute
@@ -214,11 +242,25 @@ export function resolveCommandExecutor(command, subcommandName) {
 }
 export function toCommandDefinition(registered) {
     const command = registered.contribution;
-    if (!!command.execute === !!command.subcommands?.length) {
-        throw new Error(`Command ${command.name} must define either execute or subcommands`);
+    const hasNested = Boolean(command.subcommands?.length || command.subcommandGroups?.length);
+    if (Number(command.execute !== undefined) + Number(hasNested) !== 1) {
+        throw new Error(`Command ${command.name} must define exactly one of execute, subcommands or subcommand groups`);
+    }
+    if (command.execute && !command.acknowledgement) {
+        throw new Error(`Command ${command.name} must declare acknowledgement`);
+    }
+    for (const subcommand of command.subcommands ?? []) {
+        if (!subcommand.acknowledgement && !command.acknowledgement)
+            throw new Error(`Command ${command.name}.${subcommand.name} must declare acknowledgement`);
+    }
+    for (const group of command.subcommandGroups ?? []) {
+        for (const subcommand of group.subcommands) {
+            if (!subcommand.acknowledgement && !command.acknowledgement)
+                throw new Error(`Command ${command.name}.${group.name}.${subcommand.name} must declare acknowledgement`);
+        }
     }
-    if (command.options?.length && command.subcommands?.length) {
-        throw new Error(`Command ${command.name} cannot define both direct options and subcommands`);
+    if (command.options?.length && hasNested) {
+        throw new Error(`Command ${command.name} cannot define both direct options and nested commands`);
     }
     const contextTypes = {
         guild: InteractionContextType.Guild,
@@ -248,8 +290,50 @@ export function toCommandDefinition(registered) {
             return subcommandBuilder;
         });
     }
+    for (const group of command.subcommandGroups ?? []) {
+        builder.addSubcommandGroup((groupBuilder) => {
+            groupBuilder.setName(group.name).setDescription(group.description);
+            for (const subcommand of group.subcommands) {
+                groupBuilder.addSubcommand((subcommandBuilder) => {
+                    subcommandBuilder
+                        .setName(subcommand.name)
+                        .setDescription(subcommand.description);
+                    for (const option of subcommand.options ?? []) {
+                        addCommandOption(subcommandBuilder, option);
+                    }
+                    return subcommandBuilder;
+                });
+            }
+            return groupBuilder;
+        });
+    }
     return builder.toJSON();
 }
+function hasNestedCommands(command) {
+    return Boolean(command?.subcommands?.length || command?.subcommandGroups?.length);
+}
+function resolveCommandSubcommand(command, subcommandName, groupName) {
+    if (!command || !subcommandName)
+        return undefined;
+    if (!groupName) {
+        return command.subcommands?.find(({ name }) => name === subcommandName);
+    }
+    return command.subcommandGroups
+        ?.find(({ name }) => name === groupName)
+        ?.subcommands.find(({ name }) => name === subcommandName);
+}
+function resolveCommandOwner(registered, subcommandName, groupName) {
+    if (!registered?.routeOwners || !subcommandName)
+        return undefined;
+    const path = groupName ? `${groupName}.${subcommandName}` : subcommandName;
+    return registered.routeOwners.get(path);
+}
+function commandChoices(command) {
+    return [
+        ...(command.subcommands ?? []).map(({ name }) => `\`/${command.name} ${name}\``),
+        ...(command.subcommandGroups ?? []).flatMap((group) => group.subcommands.map(({ name }) => `\`/${command.name} ${group.name} ${name}\``)),
+    ];
+}
 function addCommandOption(builder, option) {
     if (option.type === "string") {
         if (option.autocomplete && option.choices?.length)
@@ -610,14 +694,20 @@ export async function addChannelMessageReaction(client, channelId, messageId, em
     const message = await channel.messages.fetch(messageId);
     await message.react(emojiIdentifier);
 }
-async function authorizeComponent(interaction, moduleId, services) {
+async function authorizeComponent(interaction, moduleId, services, requiredModuleName) {
+    if (!(await moduleIsGloballyAvailable(services, moduleId))) {
+        await replyEphemeralText(interaction, GLOBAL_MODULE_UNAVAILABLE_MESSAGE);
+        return false;
+    }
     if (!interaction.guildId)
         return true;
     const installations = services.get(HELYX_SERVICE_NAMES.installations);
     if (await installations.isModuleEnabled(interaction.guildId, moduleId)) {
         return true;
     }
-    await replyEphemeralText(interaction, "This module is disabled in this server. Ask a server administrator to enable it with `/helyx` or in the Helyx dashboard.");
+    await replyEphemeralText(interaction, requiredModuleName
+        ? `This command needs ${requiredModuleName}. Ask a server administrator to enable it in the Helyx dashboard.`
+        : "This module is disabled in this server. Ask a server administrator to enable it with `/helyx` or in the Helyx dashboard.");
     return false;
 }
 async function replyEphemeralText(interaction, content) {
@@ -627,11 +717,11 @@ async function replyEphemeralText(interaction, content) {
     }
     await interaction.reply({ content, flags: MessageFlags.Ephemeral });
 }
-export async function authorizeCommand(interaction, moduleId, commandId, rateLimit, services, selfAuthorizingGuildCommand, resourceScopedCommand = false) {
+export async function authorizeCommand(interaction, moduleId, commandId, rateLimit, services, selfAuthorizingGuildCommand, resourceScopedCommand = false, requiredModuleName) {
     if (!interaction.guildId)
         return true;
     if (!selfAuthorizingGuildCommand) {
-        if (!(await authorizeComponent(interaction, moduleId, services)))
+        if (!(await authorizeComponent(interaction, moduleId, services, requiredModuleName)))
             return false;
         if (!resourceScopedCommand) {
             const permissions = services.get(HELYX_SERVICE_NAMES.permissions);
@@ -639,10 +729,7 @@ export async function authorizeCommand(interaction, moduleId, commandId, rateLim
             const actor = permissionActor(interaction);
             const guildAccess = await permissions.getGuildAccessPolicy?.(interaction.guildId);
             if (!canUseCommand(actor, policy, guildAccess)) {
-                await interaction.reply({
-                    content: "You do not have permission to use this command.",
-                    flags: MessageFlags.Ephemeral,
-                });
+                await replyEphemeralText(interaction, "You do not have permission to use this command.");
                 return false;
             }
         }
@@ -657,16 +744,15 @@ export async function authorizeCommand(interaction, moduleId, commandId, rateLim
             windowSeconds: rateLimit.windowSeconds,
         });
         if (!result.allowed) {
-            await interaction.reply({
-                content: `This command is temporarily rate limited. Try again <t:${Math.ceil(result.resetsAt.getTime() / 1_000)}:R>.`,
-                flags: MessageFlags.Ephemeral,
-            });
+            await replyEphemeralText(interaction, `This command is temporarily rate limited. Try again <t:${Math.ceil(result.resetsAt.getTime() / 1_000)}:R>.`);
             return false;
         }
     }
     return true;
 }
 async function authorizeAutocomplete(interaction, moduleId, commandId, services, selfAuthorizingGuildCommand, resourceScopedCommand) {
+    if (!(await moduleIsGloballyAvailable(services, moduleId)))
+        return false;
     if (!interaction.guildId || selfAuthorizingGuildCommand)
         return true;
     const installations = services.get(HELYX_SERVICE_NAMES.installations);
@@ -1023,6 +1109,7 @@ function interactionLogContext(interaction) {
         ...(interaction.isChatInputCommand()
             ? {
                 commandName: interaction.commandName,
+                subcommandGroupName: interaction.options.getSubcommandGroup(false) ?? undefined,
                 subcommandName: interaction.options.getSubcommand(false) ?? undefined,
             }
             : "customId" in interaction && typeof interaction.customId === "string"

package/dist/internal-module-manifest.d.ts

@@ -0,0 +1,13 @@
+export declare const INTERNAL_MODULE_MANIFEST_FIELDS: {
+    readonly manifestVersion: "0.3";
+    readonly moduleKind: "internal_dependency";
+    readonly customerSelectable: false;
+    readonly countsAsInstalledModule: false;
+    readonly healthExposure: "delegated";
+    readonly privacy: {
+        containsPersonalData: false;
+        providerVersion: number;
+        collections: never[];
+    };
+};
+//# sourceMappingURL=internal-module-manifest.d.ts.map

package/dist/internal-module-manifest.js

@@ -0,0 +1,14 @@
+const noOwnedPersonalData = {
+    containsPersonalData: false,
+    providerVersion: 1,
+    collections: [],
+};
+export const INTERNAL_MODULE_MANIFEST_FIELDS = {
+    manifestVersion: "0.3",
+    moduleKind: "internal_dependency",
+    customerSelectable: false,
+    countsAsInstalledModule: false,
+    healthExposure: "delegated",
+    privacy: noOwnedPersonalData,
+};
+//# sourceMappingURL=internal-module-manifest.js.map

package/dist/management-module.js

@@ -1,4 +1,6 @@
+import { isCustomerSelectableModule, } from "@helyx/module-manifest";
 import { defineModule, HELYX_SERVICE_NAMES, ModuleStateValidationError, } from "@helyx/sdk";
+import { INTERNAL_MODULE_MANIFEST_FIELDS } from "./internal-module-manifest.js";
 const MODULE_SELECT_ID = "helyx.management.module";
 const SETTING_SELECT_ID = "helyx.management.setting";
 const VALUE_SELECT_ID = "helyx.management.value";
@@ -24,11 +26,13 @@ const VIOLET = 0x7c3aed;
 const SUCCESS = 0x16a34a;
 const DANGER = 0xdc2626;
 export function createManagementModule(configurableModules, resources) {
-    const modules = [...configurableModules].sort((left, right) => left.manifest.name.localeCompare(right.manifest.name, "en-GB"));
+    const modules = configurableModules
+        .filter((module) => isCustomerSelectableModule(module.manifest))
+        .sort((left, right) => left.manifest.name.localeCompare(right.manifest.name, "en-GB"));
     const byId = new Map(modules.map((module) => [module.manifest.id, module]));
     return defineModule({
         manifest: {
-            manifestVersion: "0.1",
+            ...INTERNAL_MODULE_MANIFEST_FIELDS,
             releaseStatus: "live",
             id: "helyx.management",
             name: "Helyx management",
@@ -49,6 +53,7 @@ export function createManagementModule(configurableModules, resources) {
                 {
                     name: "helyx",
                     description: "Manage Helyx modules and settings",
+                    acknowledgement: "deferred-ephemeral",
                     registration: "global",
                     contexts: ["guild"],
                     integrationTypes: ["guild_install"],

package/dist/module-availability-control.d.ts

@@ -0,0 +1,24 @@
+import { type ModuleAvailabilityService, type ModuleAvailabilityState, type ModuleDefinition, type ServiceAccess } from "@helyx/sdk";
+export interface AvailabilityModuleDefinition {
+    id: string;
+    name: string;
+    version: string;
+    releaseStatus: "planned" | "testing" | "beta" | "live";
+}
+export interface AvailabilityModuleCatalogue {
+    catalogueDigest: string;
+    modules: AvailabilityModuleDefinition[];
+}
+export declare function availabilityCatalogueDefinitions(modules: readonly ModuleDefinition[]): AvailabilityModuleDefinition[];
+export declare function availabilityCatalogueSnapshot(definitions: readonly AvailabilityModuleDefinition[]): AvailabilityModuleCatalogue;
+export declare function availabilityCatalogue(definitions: readonly AvailabilityModuleDefinition[]): Promise<AvailabilityModuleCatalogue>;
+export declare function moduleAvailabilityService(services: ServiceAccess): ModuleAvailabilityService | undefined;
+export declare function moduleAvailabilityStates(services: ServiceAccess, moduleIds: readonly string[]): Promise<ModuleAvailabilityState[]>;
+export declare function dashboardModuleStatus(globallyDisabled: ReadonlySet<string>, moduleId: string, installation: {
+    enabled: boolean;
+} | undefined): "enabled" | "disabled" | "unavailable";
+export declare function disabledModuleSummary(states: readonly ModuleAvailabilityState[]): {
+    ids: string[];
+    set: ReadonlySet<string>;
+};
+//# sourceMappingURL=module-availability-control.d.ts.map