@helyx/bot 0.4.36 → 0.4.38

package/dist/management-module.js

@@ -17,6 +17,7 @@ const MODULE_NEXT_ID = "helyx.management.module.next";
 const SETTING_PREVIOUS_ID = "helyx.management.setting.previous";
 const SETTING_NEXT_ID = "helyx.management.setting.next";
 const VALUE_MODAL_ID = "helyx.management.value.modal";
+const OPEN_VALUE_MODAL_ID = "helyx.management.value.open";
 const VALUE_FIELD_ID = "value";
 const SESSION_PURPOSE = "modules.manage";
 const PAGE_SIZE = 25;
@@ -30,6 +31,7 @@ export function createManagementModule(configurableModules, resources) {
         .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]));
+    const preparedValueModals = new Map();
     return defineModule({
         manifest: {
             ...INTERNAL_MODULE_MANIFEST_FIELDS,
@@ -42,56 +44,58 @@ export function createManagementModule(configurableModules, resources) {
             framework: "^0.1.0",
             dependencies: [],
             permissions: [],
-            contributions: { commands: ["helyx"], events: [] },
+            contributions: { commands: ["helyx.modules"], events: [] },
         },
         defaultPermissions: {
             module: restrictedPolicy(),
             commands: { helyx: restrictedPolicy() },
         },
-        interactions: {
-            commands: [
-                {
-                    name: "helyx",
-                    description: "Manage Helyx modules and settings",
-                    acknowledgement: "deferred-ephemeral",
-                    registration: "global",
-                    contexts: ["guild"],
-                    integrationTypes: ["guild_install"],
-                    rateLimit: { scope: "user", limit: 30, windowSeconds: 60 },
-                    async execute(context) {
-                        if (!context.serverId)
-                            return;
-                        if (modules.length === 0) {
-                            await context.reply({
-                                ephemeral: true,
-                                componentsV2: {
-                                    accentColor: DANGER,
-                                    text: [
-                                        {
-                                            content: "## No feature modules installed\nInstall at least one official Helyx module before configuring this server.",
-                                        },
-                                    ],
-                                },
-                            });
-                            return;
-                        }
-                        await context.services
-                            .get(HELYX_SERVICE_NAMES.sessions)
-                            .create({
-                            guildId: context.serverId,
-                            userId: context.userId,
-                            purpose: SESSION_PURPOSE,
-                            state: { modulePage: 0 },
-                            expiresAt: sessionExpiry(),
-                            replace: true,
+        sharedCommands: [
+            {
+                family: "helyx",
+                path: "modules",
+                permissionId: "helyx",
+                description: "Manage Helyx modules and settings",
+                acknowledgement: "deferred-ephemeral",
+                rateLimit: { scope: "user", limit: 30, windowSeconds: 60 },
+                async execute(context) {
+                    if (!context.serverId) {
+                        await context.reply(serverOnlyResponse("manage modules"));
+                        return;
+                    }
+                    if (modules.length === 0) {
+                        await context.reply({
+                            ephemeral: true,
+                            componentsV2: {
+                                accentColor: DANGER,
+                                text: [
+                                    {
+                                        content: "## No feature modules installed\nInstall at least one official Helyx module before configuring this server.",
+                                    },
+                                ],
+                            },
                         });
-                        await context.reply(await modulePickerResponse(context, modules, 0));
-                    },
+                        return;
+                    }
+                    await context.services
+                        .get(HELYX_SERVICE_NAMES.sessions)
+                        .create({
+                        guildId: context.serverId,
+                        userId: context.userId,
+                        purpose: SESSION_PURPOSE,
+                        state: { modulePage: 0 },
+                        expiresAt: sessionExpiry(),
+                        replace: true,
+                    });
+                    await context.reply(await modulePickerResponse(context, modules, 0));
                 },
-            ],
+            },
+        ],
+        interactions: {
             selects: [
                 {
                     customId: MODULE_SELECT_ID,
+                    acknowledgement: "deferred-update",
                     async execute(context) {
                         const session = await getSession(context);
                         if (!session || !context.serverId)
@@ -116,6 +120,7 @@ export function createManagementModule(configurableModules, resources) {
                 },
                 {
                     customId: SETTING_SELECT_ID,
+                    acknowledgement: "deferred-update",
                     async execute(context) {
                         const session = await getSession(context);
                         if (!session)
@@ -125,7 +130,16 @@ export function createManagementModule(configurableModules, resources) {
                         const state = { ...session.state, selectedSettingKey: setting.key };
                         await updateSession(context, session, state);
                         if (setting.type === "string" || setting.type === "integer") {
-                            await context.showModal(settingModal(setting, draft(state)));
+                            const now = Date.now();
+                            for (const [key, prepared] of preparedValueModals) {
+                                if (prepared.expiresAt <= now)
+                                    preparedValueModals.delete(key);
+                            }
+                            preparedValueModals.set(preparedModalKey(context.serverId, context.userId), {
+                                definition: settingModal(setting, draft(state)),
+                                expiresAt: now + 2 * 60 * 1_000,
+                            });
+                            await respond(context, textSettingResponse(setting));
                             return;
                         }
                         await respond(context, settingValueResponse(setting));
@@ -133,6 +147,7 @@ export function createManagementModule(configurableModules, resources) {
                 },
                 {
                     customId: VALUE_SELECT_ID,
+                    acknowledgement: "deferred-update",
                     async execute(context) {
                         const session = await getSession(context);
                         if (!session)
@@ -150,8 +165,31 @@ export function createManagementModule(configurableModules, resources) {
             buttons: [
                 statusButton(ENABLE_ID, true),
                 statusButton(DISABLE_ID, false),
+                {
+                    customId: OPEN_VALUE_MODAL_ID,
+                    async execute(context) {
+                        const key = preparedModalKey(context.serverId, context.userId);
+                        const prepared = preparedValueModals.get(key);
+                        preparedValueModals.delete(key);
+                        if (!prepared || prepared.expiresAt <= Date.now()) {
+                            await context.reply({
+                                ephemeral: true,
+                                componentsV2: {
+                                    text: [
+                                        {
+                                            content: "This setting form expired. Choose the setting again.",
+                                        },
+                                    ],
+                                },
+                            });
+                            return;
+                        }
+                        await context.showModal(prepared.definition);
+                    },
+                },
                 {
                     customId: CONFIGURE_ID,
+                    acknowledgement: "deferred-update",
                     async execute(context) {
                         const session = await getSession(context);
                         if (!session)
@@ -166,6 +204,7 @@ export function createManagementModule(configurableModules, resources) {
                 },
                 {
                     customId: SAVE_ID,
+                    acknowledgement: "deferred-update",
                     async execute(context) {
                         const session = await getSession(context);
                         if (!session || !context.serverId)
@@ -235,6 +274,7 @@ export function createManagementModule(configurableModules, resources) {
                 },
                 {
                     customId: CLEAR_ID,
+                    acknowledgement: "deferred-update",
                     async execute(context) {
                         const session = await getSession(context);
                         if (!session)
@@ -256,6 +296,7 @@ export function createManagementModule(configurableModules, resources) {
                 },
                 {
                     customId: BACK_TO_MODULES_ID,
+                    acknowledgement: "deferred-update",
                     async execute(context) {
                         const session = await getSession(context);
                         if (!session)
@@ -266,6 +307,7 @@ export function createManagementModule(configurableModules, resources) {
                 },
                 {
                     customId: BACK_TO_MODULE_ID,
+                    acknowledgement: "deferred-update",
                     async execute(context) {
                         const session = await getSession(context);
                         if (!session)
@@ -275,6 +317,7 @@ export function createManagementModule(configurableModules, resources) {
                 },
                 {
                     customId: CANCEL_ID,
+                    acknowledgement: "deferred-update",
                     async execute(context) {
                         const session = await getSession(context);
                         if (!session)
@@ -303,6 +346,7 @@ export function createManagementModule(configurableModules, resources) {
             modals: [
                 {
                     customId: VALUE_MODAL_ID,
+                    acknowledgement: "deferred-ephemeral",
                     async execute(context) {
                         const session = await getSession(context);
                         if (!session)
@@ -332,6 +376,7 @@ export function createManagementModule(configurableModules, resources) {
     function statusButton(customId, enabled) {
         return {
             customId,
+            acknowledgement: "deferred-update",
             async execute(context) {
                 const session = await getSession(context);
                 if (!session || !context.serverId)
@@ -379,6 +424,7 @@ export function createManagementModule(configurableModules, resources) {
     function modulePageButton(customId, change) {
         return {
             customId,
+            acknowledgement: "deferred-update",
             async execute(context) {
                 const session = await getSession(context);
                 if (!session)
@@ -396,6 +442,7 @@ export function createManagementModule(configurableModules, resources) {
     function settingPageButton(customId, change) {
         return {
             customId,
+            acknowledgement: "deferred-update",
             async execute(context) {
                 const session = await getSession(context);
                 if (!session)
@@ -412,6 +459,18 @@ export function createManagementModule(configurableModules, resources) {
         };
     }
 }
+function serverOnlyResponse(action) {
+    return {
+        ephemeral: true,
+        componentsV2: {
+            text: [
+                {
+                    content: `This command needs a server. Open a server where Helyx is installed, then use \`/helyx modules\` there to ${action}.`,
+                },
+            ],
+        },
+    };
+}
 function restrictedPolicy() {
     return {
         everyone: false,
@@ -526,6 +585,20 @@ function configurationResponse(module, state) {
         ],
     };
 }
+function textSettingResponse(setting) {
+    return {
+        ephemeral: true,
+        componentsV2: {
+            accentColor: VIOLET,
+            text: [{ content: `## ${setting.label}\n${setting.description}` }],
+        },
+        buttons: [
+            button(OPEN_VALUE_MODAL_ID, "Enter value", "primary"),
+            button(CONFIGURE_ID, "Back to settings", "secondary"),
+            button(CANCEL_ID, "Cancel", "secondary"),
+        ],
+    };
+}
 function settingValueResponse(setting) {
     const clear = setting.required
         ? []
@@ -602,6 +675,9 @@ function settingValueResponse(setting) {
     }
     throw new Error("Selected setting requires a modal");
 }
+function preparedModalKey(serverId, userId) {
+    return `${serverId ?? "direct"}:${userId}`;
+}
 function settingModal(setting, values) {
     const current = values[setting.key];
     return {

package/dist/module-logging.d.ts

@@ -17,6 +17,7 @@ export declare class DiscordModuleLoggingService implements ModuleLoggingService
         idempotencyKey?: string;
     }): Promise<{
         delivered: boolean;
+        retryable?: boolean;
     }>;
 }
 //# sourceMappingURL=module-logging.d.ts.map

package/dist/module-logging.js

@@ -19,7 +19,7 @@ export class DiscordModuleLoggingService {
     async emit(input) {
         try {
             if (!this.#loggingInstalled)
-                return { delivered: false };
+                return { delivered: false, retryable: false };
             const source = this.#modules.get(input.moduleId);
             const event = source?.logging?.events.find(({ id }) => id === input.eventId);
             if (!source || !event) {
@@ -27,18 +27,18 @@ export class DiscordModuleLoggingService {
             }
             const installations = new InstallationRepository(this.database);
             if (!(await installations.isModuleEnabled(input.guildId, LOGGING_MODULE_ID))) {
-                return { delivered: false };
+                return { delivered: false, retryable: false };
             }
             const [configuration, policy] = await Promise.all([
                 new ModuleConfigurationRepository(this.database).get(input.guildId, LOGGING_MODULE_ID),
                 new ModuleLoggingPolicyRepository(this.database).get(input.guildId, input.moduleId, input.eventId),
             ]);
             if (!(policy?.enabled ?? event.defaultEnabled)) {
-                return { delivered: false };
+                return { delivered: false, retryable: false };
             }
             const channelId = configuration?.configuration.channelId;
             if (typeof channelId !== "string" || !/^\d{17,20}$/u.test(channelId)) {
-                return { delivered: false };
+                return { delivered: false, retryable: false };
             }
             const summary = normalizeText(input.summary, 500, "summary");
             const details = (input.details ?? []).map(({ label, value }) => ({
@@ -86,7 +86,7 @@ export class DiscordModuleLoggingService {
                 guildId: input.guildId,
                 error: safeError(error),
             }, "Module activity log delivery failed");
-            return { delivered: false };
+            return { delivered: false, retryable: true };
         }
     }
 }

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

@@ -0,0 +1,19 @@
+import { type InstallationService, type ModuleDefinition, type ServiceAccess } from "@helyx/sdk";
+export interface BotModuleStatusMutationResult {
+    moduleStatuses: Record<string, "enabled" | "disabled">;
+}
+export declare function mutateDashboardModuleStatus(input: {
+    change: {
+        guildId: string;
+        moduleId: string;
+        enabled: boolean;
+        actorUserId: string;
+        correlationId: string;
+    };
+    module: ModuleDefinition;
+    dashboardModuleIds: readonly string[];
+    installations: InstallationService;
+    services: ServiceAccess;
+    requireModuleAvailable(): Promise<void>;
+}): Promise<BotModuleStatusMutationResult>;
+//# sourceMappingURL=module-status-control.d.ts.map

package/dist/module-status-control.js

@@ -0,0 +1,69 @@
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { runNestedGuildBarriers } from "./numeric-barriers.js";
+export async function mutateDashboardModuleStatus(input) {
+    const { change, module } = input;
+    const scopes = Object.entries(module.records ?? {})
+        .filter(([, collection]) => (collection.incrementableFields?.length ?? 0) > 0)
+        .map(([collection]) => ({
+        moduleId: change.moduleId,
+        collection,
+        guildId: change.guildId,
+    }));
+    const writeBehind = scopes.length > 0 &&
+        input.services.has(HELYX_SERVICE_NAMES.numericWriteBehind)
+        ? input.services.get(HELYX_SERVICE_NAMES.numericWriteBehind)
+        : null;
+    if (writeBehind)
+        await input.requireModuleAvailable();
+    let mutationResult;
+    const setEnabled = async () => {
+        mutationResult = await input.installations.setModuleEnabled({
+            guildId: change.guildId,
+            moduleId: change.moduleId,
+            enabled: change.enabled,
+            context: {
+                actorUserId: change.actorUserId,
+                correlationId: change.correlationId,
+                source: "dashboard",
+            },
+        });
+        return mutationResult;
+    };
+    if (!writeBehind) {
+        await setEnabled();
+    }
+    else if (change.enabled) {
+        for (const scope of scopes) {
+            const suppression = await writeBehind.suppressGuild(scope);
+            await writeBehind.releaseGuild({
+                ...scope,
+                suppressionId: suppression.suppressionId,
+            });
+        }
+        await setEnabled();
+    }
+    else {
+        await runNestedGuildBarriers({
+            scopes,
+            writeBehind,
+            operation: setEnabled,
+        });
+        for (const scope of scopes)
+            await writeBehind.flushGuild(scope);
+        for (const scope of scopes)
+            await writeBehind.suppressGuild(scope);
+    }
+    if (!mutationResult)
+        throw new Error("Module status mutation completed without a result");
+    const dashboardModuleIds = new Set(input.dashboardModuleIds);
+    const transitionedIds = new Set([
+        change.moduleId,
+        ...mutationResult.transitionedModuleIds,
+    ]);
+    return {
+        moduleStatuses: Object.fromEntries([...transitionedIds]
+            .filter((moduleId) => dashboardModuleIds.has(moduleId))
+            .map((moduleId) => [moduleId, change.enabled ? "enabled" : "disabled"])),
+    };
+}
+//# sourceMappingURL=module-status-control.js.map

package/dist/modules.d.ts

@@ -12,11 +12,13 @@ export interface ConfiguredModulePackage extends LoadedDefinition {
 }
 export declare const secureRandomSelectionWorkerKeyName = "HELYX_INTERNAL_SECURE_RANDOM_SELECTION_KEY";
 interface PlatformServiceEnvironment extends Pick<BotEnvironment, "HELYX_DATA_ENCRYPTION_KEY"> {
+    DISCORD_CLIENT_ID?: string;
     HELYX_DASHBOARD_PUBLIC_URL?: string;
     HELYX_INTERNAL_SECURE_RANDOM_SELECTION_KEY?: string;
 }
 export declare function deriveSecureRandomSelectionKey(encodedDataEncryptionKey: string): Uint8Array;
 export declare function platformServiceOptions(environment: PlatformServiceEnvironment, modules: readonly ModuleDefinition[]): {
+    applicationId?: string;
     secureRandomSelectionKey?: Uint8Array;
     dashboardBaseUrl?: string;
 };

package/dist/modules.js

@@ -1,5 +1,5 @@
 import { orderModuleManifests, parseModuleManifest, } from "@helyx/module-manifest";
-import { NEXUS_COMMAND_SPECS, NEXUS_ROOT_MODULE_ID } from "@helyx/sdk";
+import { NEXUS_COMMAND_SPECS, NEXUS_ROOT_MODULE_ID, sharedCommandFamilySpec, sharedCommandPathSpec, } from "@helyx/sdk";
 import { createHmac } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
@@ -22,12 +22,16 @@ export function deriveSecureRandomSelectionKey(encodedDataEncryptionKey) {
         .digest();
 }
 export function platformServiceOptions(environment, modules) {
+    const application = environment.DISCORD_CLIENT_ID
+        ? { applicationId: environment.DISCORD_CLIENT_ID }
+        : {};
     const urls = environment.HELYX_DASHBOARD_PUBLIC_URL
         ? { dashboardBaseUrl: environment.HELYX_DASHBOARD_PUBLIC_URL }
         : {};
     const internalSelectionKey = environment.HELYX_INTERNAL_SECURE_RANDOM_SELECTION_KEY;
     if (internalSelectionKey) {
         return {
+            ...application,
             ...urls,
             secureRandomSelectionKey: decodeSecureRandomSelectionKey(internalSelectionKey, secureRandomSelectionWorkerKeyName),
         };
@@ -37,9 +41,10 @@ export function platformServiceOptions(environment, modules) {
         if (modules.some(({ manifest }) => manifest.id === giveawaysModuleId)) {
             throw new Error("HELYX_DATA_ENCRYPTION_KEY is required when Giveaways is loaded");
         }
-        return urls;
+        return { ...application, ...urls };
     }
     return {
+        ...application,
         ...urls,
         secureRandomSelectionKey: deriveSecureRandomSelectionKey(encodedKey),
     };
@@ -103,6 +108,20 @@ export function validateContributionParity(definition) {
         throw new Error("Module requests an unsupported or duplicate Discord capability");
     }
     const executableCommands = (definition.interactions?.commands ?? []).map(({ name }) => name);
+    const sharedCommandPaths = new Set();
+    for (const command of definition.sharedCommands ?? []) {
+        const family = sharedCommandFamilySpec(command.family);
+        const spec = sharedCommandPathSpec(command.family, command.path);
+        if (!family || !spec || spec.ownerModuleId !== definition.manifest.id) {
+            throw new Error(`Module ${definition.manifest.id} cannot contribute shared command ${command.family}.${command.path}`);
+        }
+        const contributionId = `${command.family}.${command.path}`;
+        if (sharedCommandPaths.has(contributionId)) {
+            throw new Error(`Duplicate shared command path for ${definition.manifest.id}: ${contributionId}`);
+        }
+        sharedCommandPaths.add(contributionId);
+    }
+    executableCommands.push(...sharedCommandPaths);
     const nexusCommandPaths = new Set();
     for (const command of definition.nexusCommands ?? []) {
         const spec = NEXUS_COMMAND_SPECS.find(({ path }) => path === command.path);

package/dist/nexus-commands.d.ts

@@ -1,13 +1,2 @@
-import { type CommandContribution, type ModuleDefinition } from "@helyx/sdk";
-export interface CommandRouteOwner {
-    moduleId: string;
-    moduleName: string;
-}
-export interface RegisteredCommand {
-    moduleId: string;
-    moduleName: string;
-    contribution: CommandContribution;
-    routeOwners?: ReadonlyMap<string, CommandRouteOwner>;
-}
-export declare function collectCommandRegistrations(modules: readonly ModuleDefinition[]): Map<string, RegisteredCommand>;
+export * from "./shared-commands.js";
 //# sourceMappingURL=nexus-commands.d.ts.map

package/dist/nexus-commands.js

@@ -1,100 +1,2 @@
-import { NEXUS_COMMAND_SPECS, NEXUS_ROOT_MODULE_ID, } from "@helyx/sdk";
-export function collectCommandRegistrations(modules) {
-    const registrations = modules.flatMap((module) => (module.interactions?.commands ?? []).map((contribution) => ({
-        moduleId: module.manifest.id,
-        moduleName: module.manifest.name,
-        contribution,
-    })));
-    const nexusContributions = modules.flatMap((module) => (module.nexusCommands ?? []).map((contribution) => ({
-        moduleId: module.manifest.id,
-        moduleName: module.manifest.name,
-        contribution,
-    })));
-    if (nexusContributions.length > 0) {
-        const roots = registrations.filter(({ contribution }) => contribution.name === "nexus");
-        if (roots.length !== 1 || roots[0].moduleId !== NEXUS_ROOT_MODULE_ID) {
-            throw new Error("Nexus Core must be the sole owner of /nexus");
-        }
-        const root = roots[0];
-        if (root.contribution.execute ||
-            root.contribution.options?.length ||
-            root.contribution.subcommands?.length ||
-            root.contribution.subcommandGroups?.length) {
-            throw new Error("Nexus Core /nexus must be composed from Nexus commands");
-        }
-        const composed = composeNexusCommand(root, nexusContributions);
-        registrations.splice(registrations.indexOf(root), 1, composed);
-    }
-    return uniqueRegistrations(registrations);
-}
-function composeNexusCommand(root, contributions) {
-    const byPath = new Map(contributions.map((item) => {
-        const spec = NEXUS_COMMAND_SPECS.find(({ path }) => path === item.contribution.path);
-        if (!spec || spec.ownerModuleId !== item.moduleId) {
-            throw new Error(`Module ${item.moduleId} cannot contribute Nexus command ${item.contribution.path}`);
-        }
-        return [item.contribution.path, item];
-    }));
-    if (byPath.size !== contributions.length) {
-        throw new Error("Duplicate Nexus command path");
-    }
-    const subcommands = [];
-    const groups = new Map();
-    const routeOwners = new Map();
-    for (const spec of NEXUS_COMMAND_SPECS) {
-        const item = byPath.get(spec.path);
-        if (!item)
-            continue;
-        routeOwners.set(spec.path, {
-            moduleId: item.moduleId,
-            moduleName: item.moduleName,
-        });
-        const [first, second] = spec.path.split(".");
-        const command = toSubcommand(item.contribution, second ?? first);
-        if (!second) {
-            subcommands.push(command);
-            continue;
-        }
-        const current = groups.get(first);
-        const group = current ?? {
-            name: first,
-            description: "groupDescription" in spec
-                ? spec.groupDescription
-                : `Manage Nexus ${first}`,
-            subcommands: [],
-        };
-        groups.set(first, {
-            ...group,
-            subcommands: [...group.subcommands, command],
-        });
-    }
-    return {
-        ...root,
-        contribution: {
-            ...root.contribution,
-            subcommands,
-            subcommandGroups: [...groups.values()],
-        },
-        routeOwners,
-    };
-}
-function toSubcommand(contribution, name) {
-    const subcommand = {
-        ...contribution,
-        name,
-        permissionId: `nexus.${contribution.path}`,
-    };
-    delete subcommand.path;
-    return subcommand;
-}
-function uniqueRegistrations(items) {
-    const result = new Map();
-    for (const item of items) {
-        const key = item.contribution.name;
-        if (result.has(key))
-            throw new Error(`Duplicate command name: ${key}`);
-        result.set(key, item);
-    }
-    return result;
-}
+export * from "./shared-commands.js";
 //# sourceMappingURL=nexus-commands.js.map