@helyx/bot 0.4.46 → 0.5.0

package/dist/discord-invites.d.ts

@@ -0,0 +1,24 @@
+import type { DiscordInviteInspectionService, DiscordInviteSnapshot, DiscordInviteUnavailable } from "@helyx/sdk";
+import { type Client } from "discord.js";
+export declare class DiscordInviteInspection implements DiscordInviteInspectionService {
+    #private;
+    private readonly client;
+    constructor(client: Client, fingerprintKey: Uint8Array);
+    continuityGeneration(input: {
+        guildId: string;
+    }): string;
+    invalidateContinuity(input: {
+        guildId: string;
+        reason: "event_queue_gap" | "gateway_session_gap" | "ownership_gap";
+    }): void;
+    fingerprintCode(input: {
+        guildId: string;
+        code: string;
+    }): Promise<{
+        sourceKey: string;
+    }>;
+    captureSnapshot(input: {
+        guildId: string;
+    }): Promise<DiscordInviteSnapshot | DiscordInviteUnavailable>;
+}
+//# sourceMappingURL=discord-invites.d.ts.map

package/dist/discord-invites.js

@@ -0,0 +1,91 @@
+import { PermissionFlagsBits } from "discord.js";
+import { createHmac, randomUUID } from "node:crypto";
+const VANITY_FEATURE = "VANITY_URL";
+export class DiscordInviteInspection {
+    client;
+    #processGeneration = randomUUID();
+    #guildGenerations = new Map();
+    #fingerprintKey;
+    constructor(client, fingerprintKey) {
+        this.client = client;
+        if (fingerprintKey.byteLength !== 32)
+            throw new Error("Discord invite fingerprint key must contain 32 bytes");
+        this.#fingerprintKey = Buffer.from(fingerprintKey);
+    }
+    continuityGeneration(input) {
+        const readyGeneration = this.client.readyTimestamp ?? 0;
+        const localGeneration = this.#guildGenerations.get(input.guildId) ?? 0;
+        return `${this.#processGeneration}:${readyGeneration}:${localGeneration}`;
+    }
+    invalidateContinuity(input) {
+        void input.reason;
+        this.#guildGenerations.set(input.guildId, (this.#guildGenerations.get(input.guildId) ?? 0) + 1);
+    }
+    fingerprintCode(input) {
+        const code = input.code.trim();
+        if (!/^\d{17,20}$/u.test(input.guildId))
+            return Promise.reject(new Error("Discord server ID is invalid"));
+        if (code.length < 1 || code.length > 128)
+            return Promise.reject(new Error("Discord invite code is invalid"));
+        return Promise.resolve({
+            sourceKey: this.#fingerprint(input.guildId, code),
+        });
+    }
+    async captureSnapshot(input) {
+        const guild = this.client.guilds.cache.get(input.guildId);
+        if (!guild)
+            return unavailable("discord_unavailable");
+        if (!hasManageGuild(guild))
+            return unavailable("missing_permission");
+        try {
+            const [invites, vanity] = await Promise.all([
+                guild.invites.fetch(),
+                guild.features.includes(VANITY_FEATURE)
+                    ? guild.fetchVanityData().catch(() => null)
+                    : Promise.resolve(null),
+            ]);
+            const observedAt = new Date();
+            return {
+                available: true,
+                observedAt,
+                continuityGeneration: this.continuityGeneration(input),
+                invites: [...invites.values()]
+                    .map((invite) => ({
+                    sourceKey: this.#fingerprint(guild.id, invite.code),
+                    channelId: invite.channelId,
+                    inviterUserId: invite.inviterId,
+                    createdAt: invite.createdAt,
+                    expiresAt: invite.expiresAt,
+                    maxUses: invite.maxUses ?? 0,
+                    uses: invite.uses ?? 0,
+                    temporary: invite.temporary ?? false,
+                }))
+                    .sort((left, right) => left.sourceKey.localeCompare(right.sourceKey)),
+                vanity: vanity?.code && typeof vanity.uses === "number"
+                    ? {
+                        sourceKey: this.#fingerprint(guild.id, vanity.code),
+                        uses: vanity.uses,
+                    }
+                    : null,
+            };
+        }
+        catch {
+            return unavailable("discord_unavailable");
+        }
+    }
+    #fingerprint(guildId, code) {
+        return createHmac("sha256", this.#fingerprintKey)
+            .update("helyx.discord-invite-source.v1\0", "utf8")
+            .update(guildId, "utf8")
+            .update("\0", "utf8")
+            .update(code, "utf8")
+            .digest("base64url");
+    }
+}
+function hasManageGuild(guild) {
+    return (guild.members.me?.permissions.has(PermissionFlagsBits.ManageGuild) ?? false);
+}
+function unavailable(code) {
+    return { available: false, code };
+}
+//# sourceMappingURL=discord-invites.js.map

package/dist/events.js

@@ -122,6 +122,28 @@ export function installModuleEvents(client, modules, logger, services) {
     const guildMessageQueue = guildMessageContributions.length > 0
         ? new BoundedGuildEventQueue(logger)
         : null;
+    const inviteInspection = memberAddContributions.some(({ moduleId }) => moduleId === "helyx.invite-tracking") &&
+        typeof services.has === "function" &&
+        services.has(HELYX_SERVICE_NAMES.discordInvites)
+        ? services.get(HELYX_SERVICE_NAMES.discordInvites)
+        : null;
+    if (inviteInspection) {
+        client.on(Events.ShardDisconnect, (_event, shardId) => {
+            for (const guild of client.guilds.cache.values())
+                if (guild.shardId === shardId)
+                    inviteInspection.invalidateContinuity({
+                        guildId: guild.id,
+                        reason: "gateway_session_gap",
+                    });
+        });
+        client.on(Events.Invalidated, () => {
+            for (const guildId of client.guilds.cache.keys())
+                inviteInspection.invalidateContinuity({
+                    guildId,
+                    reason: "gateway_session_gap",
+                });
+        });
+    }
     if (privilegedMessageContributions.length > 0) {
         client.on(Events.MessageCreate, (message) => {
             if (!message.guildId || !privilegedEligibilityQueue)
@@ -231,7 +253,12 @@ export function installModuleEvents(client, modules, logger, services) {
     }
     if (memberAddContributions.length > 0) {
         client.on(Events.GuildMemberAdd, (member) => {
-            queue.enqueue(member.guild.id, () => handleMemberAdd(member));
+            const accepted = queue.enqueue(member.guild.id, () => handleMemberAdd(member));
+            if (!accepted && inviteInspection)
+                inviteInspection.invalidateContinuity({
+                    guildId: member.guild.id,
+                    reason: "event_queue_gap",
+                });
         });
     }
     if (memberRemoveContributions.length > 0) {
@@ -487,9 +514,26 @@ export function installModuleEvents(client, modules, logger, services) {
         if (!member.joinedAt)
             throw new Error("Discord member join timestamp is unavailable");
         const installations = availabilityAwareInstallations(services);
+        const continuityGeneration = inviteInspection
+            ? inviteInspection.continuityGeneration({ guildId: member.guild.id })
+            : `runtime:${client.readyTimestamp ?? 0}`;
+        const occurrenceId = createHash("sha256")
+            .update("helyx.guild-member-add.v1\0", "utf8")
+            .update(member.guild.id, "utf8")
+            .update("\0", "utf8")
+            .update(member.id, "utf8")
+            .update("\0", "utf8")
+            .update(member.joinedAt.toISOString(), "utf8")
+            .digest("base64url");
         for (const { moduleId, contribution } of memberAddContributions) {
             try {
                 if (!(await installations.isModuleEnabled(member.guild.id, moduleId))) {
+                    if (moduleId === "helyx.invite-tracking" && inviteInspection) {
+                        inviteInspection.invalidateContinuity({
+                            guildId: member.guild.id,
+                            reason: "ownership_gap",
+                        });
+                    }
                     continue;
                 }
                 await contribution.execute({
@@ -500,6 +544,8 @@ export function installModuleEvents(client, modules, logger, services) {
                     memberIsBot: member.user.bot,
                     accountCreatedAt: member.user.createdAt,
                     joinedAt: member.joinedAt,
+                    occurrenceId,
+                    continuityGeneration,
                     services,
                     assignRole: (roleId) => assignMemberRole(member, roleId),
                     sendToChannel: (channelId, response) => sendToGuildChannel(member, channelId, response),
@@ -822,10 +868,11 @@ class BoundedGuildEventQueue {
     enqueue(guildId, run) {
         if (!this.#accepting || this.#pending.length >= 1_000) {
             this.logger.warn({ event: "module.event_dropped", reason: "queue_capacity" }, "Module gateway event queue rejected work");
-            return;
+            return false;
         }
         this.#pending.push({ guildId, run });
         this.#pump();
+        return true;
     }
     queueDepth() {
         return this.#pending.length;

package/dist/index.js

@@ -3,7 +3,7 @@ import { StatusHeartbeatReporter } from "@helyx/status-client";
 import { safeError, ServiceRegistry } from "@helyx/core";
 import { checkDatabaseConnection, createDatabasePool, AuditRepository, GuildCommandRepository, InteractionSessionRepository, RateLimitRepository, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
 import { createRuntime } from "@helyx/framework";
-import { createPlatformServices, gamingStatisticsRecordOwner, achievementContributionRecordOwner, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
+import { createPlatformServices, gamingStatisticsRecordOwner, achievementContributionRecordOwner, PostgresPrivacyProviderExecutor, PlatformMemberRoleGrantOwnershipService, PostgresMemberRoleGrantOwnershipStore, } from "@helyx/platform";
 import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
 import { Client, Events, GatewayIntentBits, Partials } from "discord.js";
 import pino from "pino";
@@ -33,6 +33,8 @@ import { createPrivacyModule } from "./privacy-module.js";
 import { HttpOAuthService } from "./oauth-service.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 { GuildCommandWorker } from "./guild-command-worker.js";
 import { GuildCommandDiscordClient } from "./guild-command-discord-client.js";
 import { GuildCommandReadService } from "./guild-command-read-service.js";
@@ -320,8 +322,9 @@ async function startUnshardedBot(processEnvironment) {
         ];
         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);
@@ -349,9 +352,14 @@ async function startUnshardedBot(processEnvironment) {
         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, bootstrapLogger));
         }

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
@@ -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,
     };
 }
@@ -1299,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.46",
+  "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",