@helyx/bot 0.4.44 → 0.5.0

package/dist/interactions.js

@@ -4,6 +4,7 @@ import { canUseCommand } from "@helyx/core";
 import { commandRegistrationPolicy, contributionRegistrationPolicy, } from "./command-registration-policy.js";
 import { ActionRowBuilder, ButtonBuilder, ButtonStyle, ChannelSelectMenuBuilder, EmbedBuilder, Events, GuildMember, ApplicationIntegrationType, ChannelType, InteractionContextType, LabelBuilder, MessageFlags, MentionableSelectMenuBuilder, ModalBuilder, RoleSelectMenuBuilder, Routes, StringSelectMenuBuilder, SlashCommandBuilder, TextInputBuilder, TextInputStyle, UserSelectMenuBuilder, TextDisplayBuilder, PermissionFlagsBits, escapeMarkdown, } from "discord.js";
 import { collectCommandRegistrations, } from "./shared-commands.js";
+import { resolveDirectCommandPath } from "./command-path-contract.js";
 const buttonStyles = {
     primary: ButtonStyle.Primary,
     secondary: ButtonStyle.Secondary,
@@ -108,10 +109,7 @@ export function installInteractions(client, modules, registration, logger, servi
                     if (!registered ||
                         !subcommand?.autocomplete ||
                         !ownerModuleId ||
-                        !(await authorizeAutocomplete(interaction, ownerModuleId, subcommand.permissionId ??
-                            [registered.contribution.name, groupName, subcommand.name]
-                                .filter(Boolean)
-                                .join("."), services, registration.selfAuthorizingGuildModuleIds?.has(ownerModuleId) ??
+                        !(await authorizeAutocomplete(interaction, ownerModuleId, resolveDirectCommandPath(registered.contribution, subcommand, groupName).permissionId, services, registration.selfAuthorizingGuildModuleIds?.has(ownerModuleId) ??
                             false, subcommand.authorization === "resource-scoped", isInstallationIndependentModule(modulesById, ownerModuleId), subcommand.authorization))) {
                         await response.respond([]);
                         return;
@@ -175,12 +173,7 @@ export function installInteractions(client, modules, registration, logger, servi
                         });
                         return;
                     }
-                    const commandId = subcommandName
-                        ? [command.name, groupName, subcommandName]
-                            .filter(Boolean)
-                            .join(".")
-                        : command.name;
-                    const permissionId = subcommand?.permissionId ?? command.permissionId ?? commandId;
+                    const { permissionId } = resolveDirectCommandPath(command, subcommand, groupName);
                     const owner = resolveCommandOwner(registered, subcommandName, groupName);
                     const ownerModuleId = owner?.moduleId ?? moduleId;
                     const installationIndependentCommand = isInstallationIndependentModule(modulesById, ownerModuleId);
@@ -515,6 +508,8 @@ function addCommandOption(builder, option) {
         guild_text: ChannelType.GuildText,
         guild_announcement: ChannelType.GuildAnnouncement,
         guild_category: ChannelType.GuildCategory,
+        guild_forum: ChannelType.GuildForum,
+        guild_media: ChannelType.GuildMedia,
     };
     builder.addChannelOption((optionBuilder) => {
         optionBuilder
@@ -1003,7 +998,7 @@ export function normalizeDiscordPermission(permission) {
     return permission.replaceAll(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
 }
 export function toReplyOptions(response) {
-    const allowedMentions = toAllowedUserMentions(response.allowedUserMentionIds);
+    const allowedMentions = toAllowedMentions(response.allowedUserMentionIds, response.allowedRoleMentionIds);
     const selectRows = toSelectRows(response);
     if (response.componentsV2) {
         if (response.content !== undefined) {
@@ -1053,27 +1048,37 @@ export function toReplyOptions(response) {
             ],
         };
     }
-    const embed = response.embed
-        ? new EmbedBuilder()
-            .setTitle(response.embed.title)
-            .setDescription(response.embed.description)
-            .setColor(response.embed.color ?? 0x7c3aed)
-        : undefined;
-    if (embed && response.embed?.footer)
-        embed.setFooter({ text: response.embed.footer });
-    if (embed && response.embed?.url)
-        embed.setURL(response.embed.url);
-    if (embed && response.embed?.author)
-        embed.setAuthor({
-            name: response.embed.author.name,
-            ...(response.embed.author.iconUrl
-                ? { iconURL: response.embed.author.iconUrl }
-                : {}),
-        });
-    if (embed && response.embed?.timestamp)
-        embed.setTimestamp(new Date(response.embed.timestamp));
-    if (embed && response.embed?.imageUrl)
-        embed.setImage(response.embed.imageUrl);
+    if (response.embed && response.embeds)
+        throw new Error("Message responses cannot use both embed and embeds");
+    const embeds = (response.embeds ?? (response.embed ? [response.embed] : [])).map((value) => {
+        const embed = new EmbedBuilder().setColor(value.color ?? 0x7c3aed);
+        if (value.title)
+            embed.setTitle(value.title);
+        if (value.description)
+            embed.setDescription(value.description);
+        if (value.footer)
+            embed.setFooter({
+                text: value.footer,
+                ...(value.footerIconUrl ? { iconURL: value.footerIconUrl } : {}),
+            });
+        if (value.url)
+            embed.setURL(value.url);
+        if (value.author)
+            embed.setAuthor({
+                name: value.author.name,
+                ...(value.author.url ? { url: value.author.url } : {}),
+                ...(value.author.iconUrl ? { iconURL: value.author.iconUrl } : {}),
+            });
+        if (value.timestamp)
+            embed.setTimestamp(new Date(value.timestamp));
+        if (value.imageUrl)
+            embed.setImage(value.imageUrl);
+        if (value.thumbnailUrl)
+            embed.setThumbnail(value.thumbnailUrl);
+        if (value.fields?.length)
+            embed.addFields(...value.fields);
+        return embed;
+    });
     const components = response.buttons?.length
         ? [
             new ActionRowBuilder().addComponents(response.buttons.map((button) => {
@@ -1096,15 +1101,20 @@ export function toReplyOptions(response) {
         : [];
     components.push(...selectRows);
     return {
-        ...(response.ephemeral || response.suppressEmbeds
+        ...(response.ephemeral ||
+            response.suppressEmbeds ||
+            response.suppressNotifications
             ? {
                 flags: (response.ephemeral ? MessageFlags.Ephemeral : 0) |
-                    (response.suppressEmbeds ? MessageFlags.SuppressEmbeds : 0),
+                    (response.suppressEmbeds ? MessageFlags.SuppressEmbeds : 0) |
+                    (response.suppressNotifications
+                        ? MessageFlags.SuppressNotifications
+                        : 0),
             }
             : {}),
         ...(allowedMentions ? { allowedMentions } : {}),
         ...(response.content === undefined ? {} : { content: response.content }),
-        ...(embed ? { embeds: [embed] } : {}),
+        ...(embeds.length > 0 ? { embeds } : {}),
         components,
     };
 }
@@ -1154,15 +1164,25 @@ export function toUpdateOptions(response) {
         ephemeral: false,
     });
 }
-function toAllowedUserMentions(userIds) {
-    if (userIds === undefined)
+function toAllowedMentions(userIds, roleIds) {
+    if (userIds === undefined && roleIds === undefined)
         return undefined;
-    if (userIds.length > 100 ||
-        new Set(userIds).size !== userIds.length ||
-        userIds.some((userId) => !/^\d{17,20}$/u.test(userId))) {
-        throw new Error("Allowed user mentions must be unique Discord snowflakes");
+    validateAllowedMentionIds(userIds, "user");
+    validateAllowedMentionIds(roleIds, "role");
+    return {
+        parse: [],
+        ...(userIds === undefined ? {} : { users: [...userIds] }),
+        ...(roleIds === undefined ? {} : { roles: [...roleIds] }),
+    };
+}
+function validateAllowedMentionIds(ids, label) {
+    if (ids === undefined)
+        return;
+    if (ids.length > 100 ||
+        new Set(ids).size !== ids.length ||
+        ids.some((id) => !/^\d{17,20}$/u.test(id))) {
+        throw new Error(`Allowed ${label} mentions must be unique Discord snowflakes`);
     }
-    return { parse: [], users: [...userIds] };
 }
 function toButtonEmoji(emojiIdentifier) {
     const custom = /^([A-Za-z0-9_]{2,32}):(\d{17,20})$/u.exec(emojiIdentifier);
@@ -1289,6 +1309,10 @@ function discordChannelType(type) {
         return ChannelType.GuildAnnouncement;
     if (type === "guild_category")
         return ChannelType.GuildCategory;
+    if (type === "guild_forum")
+        return ChannelType.GuildForum;
+    if (type === "guild_media")
+        return ChannelType.GuildMedia;
     return ChannelType.GuildText;
 }
 export function safeInteractionFailureMessage(error) {

package/dist/management-module.d.ts

@@ -2,7 +2,7 @@ import { type ModuleDefinition } from "@helyx/sdk";
 export interface ManagementGuildResources {
     channels: readonly {
         id: string;
-        type: "guild_text" | "guild_announcement" | "guild_category";
+        type: "guild_text" | "guild_announcement" | "guild_category" | "guild_forum" | "guild_media";
     }[];
     roles: readonly {
         id: string;

package/dist/modules.d.ts

@@ -20,8 +20,10 @@ export declare function deriveSecureRandomSelectionKey(encodedDataEncryptionKey:
 export declare function platformServiceOptions(environment: PlatformServiceEnvironment, modules: readonly ModuleDefinition[]): {
     applicationId?: string;
     secureRandomSelectionKey?: Uint8Array;
+    inviteFingerprintKey?: Uint8Array;
     dashboardBaseUrl?: string;
 };
+export declare function deriveInviteFingerprintKey(selectionKey: Uint8Array): Uint8Array;
 export declare function loadConfiguredModules(specifiers: readonly string[], importer?: ModuleImporter): Promise<ModuleDefinition[]>;
 export declare function loadConfiguredModulePackages(specifiers: readonly string[], importer?: ModuleImporter, resolvePackageJson?: PackageJsonResolver, readPackageJson?: PackageJsonReader): Promise<ConfiguredModulePackage[]>;
 export declare function validateContributionParity(definition: ModuleDefinition): void;

package/dist/modules.js

@@ -4,10 +4,13 @@ import { createHmac } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { dirname } from "node:path";
+import { assertCommandPathContract } from "./command-path-contract.js";
 const officialModulePackage = /^@helyx\/module-[a-z0-9][a-z0-9-]*$/u;
 const giveawaysModuleId = "helyx.giveaways";
+const inviteTrackingModuleId = "helyx.invite-tracking";
 export const secureRandomSelectionWorkerKeyName = "HELYX_INTERNAL_SECURE_RANDOM_SELECTION_KEY";
 const secureRandomSelectionKeyContext = "helyx.secure-random-selection.worker.v1";
+const inviteFingerprintKeyContext = "helyx.discord-invite-fingerprint.v1";
 function decodeSecureRandomSelectionKey(encodedKey, variableName) {
     const key = Buffer.from(encodedKey, "base64");
     if (key.byteLength !== 32) {
@@ -30,25 +33,38 @@ export function platformServiceOptions(environment, modules) {
         : {};
     const internalSelectionKey = environment.HELYX_INTERNAL_SECURE_RANDOM_SELECTION_KEY;
     if (internalSelectionKey) {
+        const selectionKey = decodeSecureRandomSelectionKey(internalSelectionKey, secureRandomSelectionWorkerKeyName);
         return {
             ...application,
             ...urls,
-            secureRandomSelectionKey: decodeSecureRandomSelectionKey(internalSelectionKey, secureRandomSelectionWorkerKeyName),
+            secureRandomSelectionKey: selectionKey,
+            inviteFingerprintKey: deriveInviteFingerprintKey(selectionKey),
         };
     }
     const encodedKey = environment.HELYX_DATA_ENCRYPTION_KEY;
     if (!encodedKey) {
-        if (modules.some(({ manifest }) => manifest.id === giveawaysModuleId)) {
-            throw new Error("HELYX_DATA_ENCRYPTION_KEY is required when Giveaways is loaded");
+        const keyRequired = modules.some(({ manifest }) => manifest.id === giveawaysModuleId ||
+            manifest.id === inviteTrackingModuleId);
+        if (keyRequired) {
+            throw new Error("HELYX_DATA_ENCRYPTION_KEY is required when Giveaways or Invite Tracking is loaded");
         }
         return { ...application, ...urls };
     }
+    const selectionKey = deriveSecureRandomSelectionKey(encodedKey);
     return {
         ...application,
         ...urls,
-        secureRandomSelectionKey: deriveSecureRandomSelectionKey(encodedKey),
+        secureRandomSelectionKey: selectionKey,
+        inviteFingerprintKey: deriveInviteFingerprintKey(selectionKey),
     };
 }
+export function deriveInviteFingerprintKey(selectionKey) {
+    if (selectionKey.byteLength !== 32)
+        throw new Error("Secure random selection key must contain exactly 32 bytes");
+    return createHmac("sha256", selectionKey)
+        .update(inviteFingerprintKeyContext, "utf8")
+        .digest();
+}
 function isModuleDefinition(value) {
     if (typeof value !== "object" || value === null)
         return false;
@@ -165,13 +181,20 @@ export function validateContributionParity(definition) {
         ...(definition.events?.guildEmojiUpdate ?? []),
     ].map(({ type }) => type);
     const executableLogs = (definition.logging?.events ?? []).map(({ id }) => id);
+    const executableSchedulableActions = [
+        ...new Set((definition.schedulableActions ?? []).map(({ id }) => id)),
+    ];
     const executableDashboardActions = (definition.dashboardActions ?? []).map(({ id }) => id);
     const executableManagedResources = (definition.managedResources ?? []).map(({ id }) => id);
     assertSameContributionIds(definition.manifest.contributions.commands, executableCommands, "commands");
     assertSameContributionIds(definition.manifest.contributions.events, executableEvents, "events");
     assertSameContributionIds(definition.manifest.contributions.logs ?? [], executableLogs, "logs");
+    assertSameContributionIds(definition.manifest.contributions.schedulableActions ?? [], executableSchedulableActions, "schedulable actions");
     assertSameContributionIds(definition.manifest.dashboard?.actions?.map(({ id }) => id) ?? [], executableDashboardActions, "dashboard actions");
     assertSameContributionIds(definition.manifest.dashboard?.resources?.map(({ id }) => id) ?? [], executableManagedResources, "dashboard resources");
+    if (definition.manifest.manifestVersion === "0.4") {
+        assertCommandPathContract(definition);
+    }
     validatePrivacyParity(definition);
 }
 function validatePrivacyParity(definition) {

package/dist/permissions-module.js

@@ -2,6 +2,7 @@ import { defineModule, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
 import { isCustomerSelectableModule } from "@helyx/module-manifest";
 import { PermissionFlagsBits } from "discord.js";
 import { canMutatePermissionPolicy, permissionMutationDenialMessage, } from "@helyx/core";
+import { collectCommandPermissionTargets } from "./command-path-contract.js";
 import { INTERNAL_MODULE_MANIFEST_FIELDS } from "./internal-module-manifest.js";
 const MODULE_SELECT_ID = "helyx.permissions.module";
 const TARGET_SELECT_ID = "helyx.permissions.target";
@@ -129,7 +130,8 @@ export function createPermissionsModule(configurableModules) {
                         if (!module || !target)
                             throw new Error("Permission target expired");
                         const commandId = target === "__module__" ? undefined : target;
-                        if (commandId && !commandTargets(module).includes(commandId)) {
+                        if (commandId &&
+                            !commandTargets(module).some(({ id }) => id === commandId)) {
                             throw new Error("Selected command is unavailable");
                         }
                         const current = await context.services
@@ -437,17 +439,12 @@ function restrictedPolicy() {
     };
 }
 function commandTargets(module) {
-    const targets = (module.interactions?.commands ?? []).flatMap((command) => {
-        const nested = [
-            ...(command.subcommands ?? []).map((subcommand) => `${command.name}.${subcommand.name}`),
-            ...(command.subcommandGroups ?? []).flatMap((group) => group.subcommands.map((subcommand) => `${command.name}.${group.name}.${subcommand.name}`)),
-        ];
-        if (nested.length > 0)
-            return nested;
-        return [command.name];
-    });
-    targets.push(...(module.sharedCommands ?? []).map((command) => command.permissionId ?? `${command.family}.${command.path}`), ...(module.nexusCommands ?? []).map((command) => `nexus.${command.path}`));
-    return [...new Set(targets)];
+    return [
+        ...new Map(collectCommandPermissionTargets(module).map(({ id, name }) => [
+            id,
+            { id, label: name },
+        ])).values(),
+    ];
 }
 function modulePickerResponse(modules, requestedPage) {
     const pages = pageCount(modules.length, MODULE_PAGE_SIZE);
@@ -483,7 +480,7 @@ function targetPickerResponse(module, targets, requestedPage) {
         ephemeral: true,
         embed: {
             title: `${module.manifest.name} permissions`,
-            description: "Choose the whole module or one command. Command policies override the module policy." +
+            description: "Choose the whole module, a command, or a declared command operation. Target policies override the module policy." +
                 (pages > 1 ? ` Page ${String(page + 1)} of ${String(pages)}.` : ""),
             color: VIOLET,
         },
@@ -495,11 +492,11 @@ function targetPickerResponse(module, targets, requestedPage) {
                     {
                         label: "Entire module",
                         value: "__module__",
-                        description: "Default policy for every command",
+                        description: "Default policy for every command and operation",
                     },
                     ...visible.map((target) => ({
-                        label: `/${target.replaceAll(".", " ")}`,
-                        value: target,
+                        label: target.label,
+                        value: target.id,
                     })),
                 ],
             },

package/dist/shard-contracts.js

@@ -4,7 +4,7 @@ export const SHARD_CONTRACT_VERSION = 1;
 // Guild dashboard state includes the bounded module catalogue as well as the
 // guild's Discord resources. Keep this aligned with the cloud-control message
 // ceiling so hosted and self-hosted transports accept the same valid state.
-export const SHARD_CONTROL_MAX_BYTES = 256 * 1_024;
+export const SHARD_CONTROL_MAX_BYTES = 768 * 1_024;
 export const SHARD_CONTROL_TIMEOUT_MS = 30_000;
 export const SHARD_HEALTH_STALE_MS = 30_000;
 export const SHARD_LEASE_HEARTBEAT_TIMEOUT_MS = 20_000;

package/dist/shard-worker.js

@@ -2,7 +2,7 @@ import { parseBotEnvironment } from "@helyx/config";
 import { safeError, ServiceRegistry } from "@helyx/core";
 import { checkDatabaseConnection, createDatabasePool } from "@helyx/database";
 import { createRuntime } from "@helyx/framework";
-import { createPlatformServices } from "@helyx/platform";
+import { createPlatformServices, PlatformMemberRoleGrantOwnershipService, PostgresMemberRoleGrantOwnershipStore, } from "@helyx/platform";
 import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
 import { Client, Events, Partials } from "discord.js";
 import { monitorEventLoopDelay } from "node:perf_hooks";
@@ -21,6 +21,8 @@ import { createPermissionsModule } from "./permissions-module.js";
 import { WorkerCloudConnectorProxy } from "./shard-cloud-proxy.js";
 import { DiscordOwnedMessageDeletionService } from "./discord-owned-message-service.js";
 import { DiscordGuildHealthInspection } from "./discord-guild-health.js";
+import { DiscordAnalyticsInspection } from "./discord-analytics.js";
+import { DiscordInviteInspection } from "./discord-invites.js";
 import { CoreResourceAuthorizationService } from "./resource-authorization.js";
 import { PostgresTriviaDataProvider } from "./trivia-data-provider.js";
 import { createDeveloperOperationsModule, WorkerShardHealthProvider, } from "./developer-operations-module.js";
@@ -181,8 +183,9 @@ export async function startShardWorker(processEnvironment = process.env, identit
         ];
         const platformServices = new Map();
         const serviceAccess = new ServiceRegistry(platformServices);
+        const serviceOptions = platformServiceOptions(environment, publicModules);
         for (const [name, service] of createPlatformServices(database, publicModules, {
-            ...platformServiceOptions(environment, publicModules),
+            ...serviceOptions,
             activationServices: serviceAccess,
         })) {
             platformServices.set(name, service);
@@ -213,9 +216,14 @@ export async function startShardWorker(processEnvironment = process.env, identit
         platformServices.set(HELYX_SERVICE_NAMES.discordMessages, new DiscordMessageDeliveryService(client));
         platformServices.set(HELYX_SERVICE_NAMES.discordOwnedMessages, new DiscordOwnedMessageDeletionService(client));
         platformServices.set(HELYX_SERVICE_NAMES.memberEnforcement, new DiscordMemberEnforcementService(client));
-        platformServices.set(HELYX_SERVICE_NAMES.memberRoles, new DiscordMemberRoleService(client));
+        const memberRoles = new DiscordMemberRoleService(client);
+        platformServices.set(HELYX_SERVICE_NAMES.memberRoles, memberRoles);
+        platformServices.set(HELYX_SERVICE_NAMES.memberRoleGrants, new PlatformMemberRoleGrantOwnershipService(new PostgresMemberRoleGrantOwnershipStore(database), memberRoles));
         platformServices.set(HELYX_SERVICE_NAMES.discordResources, new DiscordResourceInspection(client));
         platformServices.set(HELYX_SERVICE_NAMES.discordGuildHealth, new DiscordGuildHealthInspection(client, publicModules, serviceAccess));
+        platformServices.set(HELYX_SERVICE_NAMES.discordAnalytics, new DiscordAnalyticsInspection(client));
+        if (serviceOptions.inviteFingerprintKey)
+            platformServices.set(HELYX_SERVICE_NAMES.discordInvites, new DiscordInviteInspection(client, serviceOptions.inviteFingerprintKey));
         if (featureModules.some(({ manifest }) => manifest.id === "helyx.logging"))
             platformServices.set(HELYX_SERVICE_NAMES.moduleLogging, new DiscordModuleLoggingService(client, database, publicModules, logger));
         const scheduledTaskRoute = createLocalScheduledTaskRoute({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "0.4.44",
+  "version": "0.5.0",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -53,11 +53,11 @@
     "@helyx/config": ">=0.5.0 <0.6.0",
     "@helyx/control-protocol": ">=0.4.0 <0.5.0",
     "@helyx/core": ">=0.1.0 <0.2.0",
-    "@helyx/database": ">=0.9.0 <0.10.0",
+    "@helyx/database": ">=0.10.0",
     "@helyx/framework": ">=0.1.0 <0.2.0",
     "@helyx/module-manifest": ">=0.8.0 <0.9.0",
-    "@helyx/platform": ">=0.6.2 <0.7.0",
-    "@helyx/sdk": ">=0.9.0 <0.10.0",
+    "@helyx/platform": ">=0.7.0",
+    "@helyx/sdk": ">=0.10.0",
     "@helyx/status-client": ">=0.1.0 <0.2.0",
     "@helyx/verification-contracts": ">=0.3.0 <0.4.0",
     "discord.js": "14.27.0",