@helyx/bot 1.5.0 → 1.5.2

package/dist/index.js

@@ -1,7 +1,7 @@
 import { parseBotEnvironment } from "@helyx/config";
 import { StatusHeartbeatReporter } from "@helyx/status-client";
 import { safeError, ServiceRegistry } from "@helyx/core";
-import { checkDatabaseConnection, createDatabasePool, EckoOperationsRepository, inspectConfiguredModuleMigrations, inspectCoreMigrations, inspectCreatorOnboardingMigrations, runCreatorOnboardingMigrations, PremiumAllocationRepository, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
+import { checkDatabaseConnection, createDatabasePool, EckoOperationsRepository, InstallationRepository, inspectConfiguredModuleMigrations, inspectCoreMigrations, inspectCreatorOnboardingMigrations, runCreatorOnboardingMigrations, PremiumAllocationRepository, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
 import { createRuntime } from "@helyx/framework";
 import { assertRepositoryEngineSupported } from "@helyx/database/adapters";
 import { createPlatformServices, gamingStatisticsRecordOwner, achievementContributionRecordOwner, PostgresPrivacyProviderExecutor, PlatformMemberRoleGrantOwnershipService, PostgresMemberRoleGrantOwnershipStore, } from "@helyx/platform";
@@ -20,6 +20,7 @@ import { assertConfiguredModuleDatabaseCompatibility, loadConfiguredModulePackag
 import { resolveModulePackageSpecifiers } from "./module-configuration.js";
 import { createPermissionsModule } from "./permissions-module.js";
 import { createManagementModule } from "./management-module.js";
+import { createDiagnosticModule, createMysqlDiagnosticLock, createPostgresDiagnosticLock, } from "./diagnostic-command.js";
 import { DiscordMessageDeliveryService, DiscordMemberRoleService, DiscordVerificationMemberService, DiscordResourceInspection, installModuleEvents, } from "./events.js";
 import { DiscordModerationMemberEnforcementAdapter } from "./discord-member-enforcement-service.js";
 import { DiscordModuleLoggingService } from "./module-logging.js";
@@ -303,6 +304,30 @@ async function startUnshardedBot(processEnvironment) {
         });
         const permissionsModule = createPermissionsModule(featureModules);
         const managementModule = createManagementModule(featureModules, guildResources);
+        const diagnosticInstallations = mysql
+            ? new (await import("@helyx/database-mysql")).InstallationRepository(mysql.pool)
+            : new InstallationRepository(database);
+        const diagnosticModule = createDiagnosticModule({
+            client,
+            modules: featureModules,
+            runExclusive: mysql
+                ? createMysqlDiagnosticLock(mysql.pool)
+                : createPostgresDiagnosticLock(database),
+            assertGuildAvailable: async (guildId) => {
+                if (shuttingDown ||
+                    !(await diagnosticInstallations.getActiveGuild(guildId)))
+                    throw new Error("The server installation is not available");
+            },
+            listEnabledModules: (guildId) => diagnosticInstallations.listEnabledModules(guildId),
+            commandStatus: {
+                get: (guildId) => {
+                    return guildCommandReads.getStatus(guildId);
+                },
+                refresh: (input) => {
+                    return guildCommandReads.refreshStatus(input);
+                },
+            },
+        });
         const cloudManagementModule = environment.HELYX_CLOUD_CONNECT_ENABLED
             ? createCloudManagementModule({
                 connector: cloudConnector,
@@ -327,6 +352,7 @@ async function startUnshardedBot(processEnvironment) {
             : undefined;
         const publicModules = [
             managementModule,
+            diagnosticModule,
             permissionsModule,
             supportModule,
             privacyModule,
@@ -405,6 +431,7 @@ async function startUnshardedBot(processEnvironment) {
                 ...(deployedCommit ? { deploymentReference: deployedCommit } : {}),
                 coreFunctions: [
                     managementModule,
+                    diagnosticModule,
                     permissionsModule,
                     supportModule,
                     privacyModule,
@@ -534,6 +561,7 @@ async function startUnshardedBot(processEnvironment) {
         });
         const enabledCoreModuleIds = new Set([
             managementModule.manifest.id,
+            diagnosticModule.manifest.id,
             permissionsModule.manifest.id,
             supportModule.manifest.id,
             ...(premiumActivationModule ? [premiumActivationModule.manifest.id] : []),
@@ -555,6 +583,7 @@ async function startUnshardedBot(processEnvironment) {
             synchroniseInternalGuild: false,
             prepare: prepareGuilds,
             selfAuthorizingGuildModuleIds: new Set([
+                diagnosticModule.manifest.id,
                 supportModule.manifest.id,
                 ...(premiumActivationModule
                     ? [premiumActivationModule.manifest.id]

package/dist/shard-supervisor.js

@@ -13,6 +13,8 @@ import { CloudConnectorController, } from "./cloud-connector.js";
 import { createCloudManagementModule } from "./cloud-management-module.js";
 import { BotControlService, createBotControlServer, mapBotControlError, } from "./control-server.js";
 import { createManagementModule } from "./management-module.js";
+import { creatorInviteWorkerKeyName, deriveCreatorInviteKey, } from "./creator-invite-key.js";
+import { createDiagnosticModule } from "./diagnostic-command.js";
 import { buildApplicationCommandDefinitions } from "./interactions.js";
 import { resolveModulePackageSpecifiers } from "./module-configuration.js";
 import { deriveSecureRandomSelectionKey, loadConfiguredModulePackages, platformServiceOptions, secureRandomSelectionWorkerKeyName, } from "./modules.js";
@@ -217,6 +219,10 @@ export async function startShardSupervisor(environment, processEnvironment, work
         };
         const permissionsModule = createPermissionsModule(featureModules);
         const managementModule = createManagementModule(featureModules, unavailableResources);
+        // The supervisor registers metadata; guild checks and repairs run in workers.
+        const diagnosticModule = createDiagnosticModule({
+            modules: featureModules,
+        });
         const cloudManagementModule = environment.HELYX_CLOUD_CONNECT_ENABLED
             ? createCloudManagementModule({
                 connector: cloudConnector,
@@ -242,6 +248,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
             : undefined;
         const publicModules = [
             managementModule,
+            diagnosticModule,
             permissionsModule,
             supportModule,
             privacyModule,
@@ -265,6 +272,7 @@ export async function startShardSupervisor(environment, processEnvironment, work
                     : {}),
                 coreFunctions: [
                     managementModule,
+                    diagnosticModule,
                     permissionsModule,
                     supportModule,
                     privacyModule,
@@ -1709,6 +1717,9 @@ export function buildShardWorkerEnvironment(source, identity, restartCount) {
     const selectionKey = source.HELYX_DATA_ENCRYPTION_KEY
         ? Buffer.from(deriveSecureRandomSelectionKey(source.HELYX_DATA_ENCRYPTION_KEY)).toString("base64")
         : undefined;
+    const creatorInviteKey = source.HELYX_DATA_ENCRYPTION_KEY
+        ? deriveCreatorInviteKey(source.HELYX_DATA_ENCRYPTION_KEY).toString("base64")
+        : undefined;
     const hostedModerationCredential = source.HELYX_HOSTED_MODERATION_ENABLED === "true" &&
         source.HELYX_BOT_CONTROL_SECRET
         ? { HELYX_BOT_CONTROL_SECRET: source.HELYX_BOT_CONTROL_SECRET }
@@ -1719,6 +1730,9 @@ export function buildShardWorkerEnvironment(source, identity, restartCount) {
         ...(selectionKey
             ? { [secureRandomSelectionWorkerKeyName]: selectionKey }
             : {}),
+        ...(creatorInviteKey
+            ? { [creatorInviteWorkerKeyName]: creatorInviteKey }
+            : {}),
         SHARDING_MANAGER: "true",
         SHARDING_MANAGER_MODE: "process",
         SHARDS: String(identity.shardId),

package/dist/shard-worker.d.ts

@@ -23,6 +23,7 @@ export declare function startShardWorker(processEnvironment?: NodeJS.ProcessEnv,
 export declare function executeShardScheduledTaskRequest(identity: ShardIdentity, request: ShardScheduledTaskRequest, route: ScheduledTaskRoute, now?: number): Promise<ShardScheduledTaskResponse>;
 export declare function parseShardWorkerLaunchContract(value: string | undefined): ShardIdentity;
 export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.ProcessEnv, identity: ShardIdentity): {
+    HELYX_INTERNAL_CREATOR_INVITE_KEY?: string;
     HELYX_INTERNAL_SECURE_RANDOM_SELECTION_KEY?: string;
     HELYX_DATA_ENCRYPTION_KEY: undefined;
     HELYX_SHARD_WORKERS_PER_REPLICA: number;
@@ -102,6 +103,7 @@ export declare function shardWorkerCommandRegistration(input: {
     prepare: NonNullable<CommandRegistration["prepare"]>;
     operationsModuleId?: string;
     supportModuleId: string;
+    diagnosticModuleId?: string;
     premiumActivationModuleId?: string;
     oauthModuleId?: string;
 }): CommandRegistration;

package/dist/shard-worker.js

@@ -1,6 +1,6 @@
 import { parseBotEnvironment } from "@helyx/config";
 import { safeError, ServiceRegistry } from "@helyx/core";
-import { checkDatabaseConnection, createDatabasePool, PremiumAllocationRepository, } from "@helyx/database";
+import { checkDatabaseConnection, createDatabasePool, PremiumAllocationRepository, InstallationRepository, } from "@helyx/database";
 import { assertRepositoryEngineSupported } from "@helyx/database/adapters";
 import { REVIEWED_PREMIUM_MODULE_IDS } from "@helyx/module-manifest";
 import { createRuntime } from "@helyx/framework";
@@ -15,9 +15,12 @@ import { HttpVerificationService } from "./verification-service.js";
 import { DiscordMessageDeliveryService, DiscordMemberRoleService, DiscordVerificationMemberService, DiscordResourceInspection, installModuleEvents, } from "./events.js";
 import { DiscordModerationMemberEnforcementAdapter } from "./discord-member-enforcement-service.js";
 import { installCreatorInvitePlatform } from "./creator-onboarding-platform.js";
+import { creatorInviteWorkerKeyName, decodeCreatorInviteKey, } from "./creator-invite-key.js";
 import { installGuildTracking, } from "./guilds.js";
 import { installInteractions, } from "./interactions.js";
 import { createManagementModule } from "./management-module.js";
+import { createDiagnosticModule, createPostgresDiagnosticLock, } from "./diagnostic-command.js";
+import { GuildCommandReadService } from "./guild-command-read-service.js";
 import { DiscordModuleLoggingService } from "./module-logging.js";
 import { resolveModulePackageSpecifiers } from "./module-configuration.js";
 import { loadConfiguredModulePackages, platformServiceOptions, secureRandomSelectionWorkerKeyName, } from "./modules.js";
@@ -158,6 +161,35 @@ export async function startShardWorker(processEnvironment = process.env, identit
         const guildResources = new DiscordGuildResourceDirectory(client);
         const permissionsModule = createPermissionsModule(featureModules);
         const managementModule = createManagementModule(featureModules, guildResources);
+        const diagnosticInstallations = new InstallationRepository(database);
+        const diagnosticModule = createDiagnosticModule({
+            client,
+            modules: featureModules,
+            runExclusive: createPostgresDiagnosticLock(database),
+            assertGuildAvailable: async (guildId) => {
+                if (shuttingDown ||
+                    guildIdToShardId(guildId, identity.shardCount) !== identity.shardId)
+                    throw new Error("The server is no longer owned by this shard");
+                const installation = await diagnosticInstallations.getActiveGuild(guildId);
+                if (!installation ||
+                    installation.shardGeneration !== identity.generation ||
+                    installation.shardDeploymentOrder !==
+                        BigInt(identity.deploymentOrder ?? 1) ||
+                    installation.shardSupervisorId !== identity.supervisorId ||
+                    installation.shardId !== identity.shardId ||
+                    installation.shardFencingToken !== BigInt(identity.fencingToken))
+                    throw new Error("The server installation or shard ownership changed");
+            },
+            listEnabledModules: (guildId) => diagnosticInstallations.listEnabledModules(guildId),
+            commandStatus: {
+                get: (guildId) => {
+                    return guildCommandReads.getStatus(guildId);
+                },
+                refresh: (input) => {
+                    return guildCommandReads.refreshStatus(input);
+                },
+            },
+        });
         cloudProxy = new WorkerCloudConnectorProxy();
         const cloudManagementModule = environment.HELYX_CLOUD_CONNECT_ENABLED
             ? createCloudManagementModule({
@@ -184,6 +216,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
             : undefined;
         const publicModules = [
             managementModule,
+            diagnosticModule,
             permissionsModule,
             supportModule,
             privacyModule,
@@ -206,6 +239,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
                     : {}),
                 coreFunctions: [
                     managementModule,
+                    diagnosticModule,
                     permissionsModule,
                     supportModule,
                     privacyModule,
@@ -224,6 +258,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
             ...publicModules,
             ...(operationsModule ? [operationsModule] : []),
         ];
+        const guildCommandReads = new GuildCommandReadService(database, environment.DISCORD_CLIENT_ID, undefined, environment.DISCORD_TOKEN, environment.HELYX_GUILD_COMMAND_WRITES_ENABLED, environment.HELYX_GUILD_COMMAND_WRITE_GUILD_IDS, environment.HELYX_GUILD_COMMAND_WRITE_SCOPE === "all", modules);
         const platformServices = new Map();
         const serviceAccess = new ServiceRegistry(platformServices);
         const serviceOptions = platformServiceOptions(environment, publicModules);
@@ -284,6 +319,11 @@ export async function startShardWorker(processEnvironment = process.env, identit
                 services: serviceAccess,
                 modules: publicModules,
                 encryptionKey: environment.HELYX_DATA_ENCRYPTION_KEY,
+                ...(environment.HELYX_INTERNAL_CREATOR_INVITE_KEY
+                    ? {
+                        inviteEncryptionKey: environment.HELYX_INTERNAL_CREATOR_INVITE_KEY,
+                    }
+                    : {}),
                 ...(environment.HELYX_CLOUD_API_URL &&
                     environment.HELYX_OAUTH_INTERNAL_SECRET
                     ? {
@@ -328,6 +368,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
         runtime = createRuntime({ modules, logger, services: platformServices });
         const enabledCoreModuleIds = new Set([
             managementModule.manifest.id,
+            diagnosticModule.manifest.id,
             permissionsModule.manifest.id,
             supportModule.manifest.id,
             ...(premiumActivationModule ? [premiumActivationModule.manifest.id] : []),
@@ -359,6 +400,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
                 ? { operationsModuleId: operationsModule.manifest.id }
                 : {}),
             supportModuleId: supportModule.manifest.id,
+            diagnosticModuleId: diagnosticModule.manifest.id,
             ...(premiumActivationModule
                 ? { premiumActivationModuleId: premiumActivationModule.manifest.id }
                 : {}),
@@ -546,12 +588,18 @@ export function parseShardWorkerEnvironment(processEnvironment, identity) {
         environment.HELYX_SHARD_SCOPE !== identity.scope)
         throw new Error("Shard worker launch contract conflicts with configuration");
     const internalSelectionKey = processEnvironment[secureRandomSelectionWorkerKeyName];
+    const internalCreatorInviteKey = processEnvironment[creatorInviteWorkerKeyName];
+    if (internalCreatorInviteKey !== undefined)
+        decodeCreatorInviteKey(internalCreatorInviteKey);
     return {
         ...environment,
         HELYX_DATA_ENCRYPTION_KEY: undefined,
         ...(internalSelectionKey
             ? { HELYX_INTERNAL_SECURE_RANDOM_SELECTION_KEY: internalSelectionKey }
             : {}),
+        ...(internalCreatorInviteKey
+            ? { HELYX_INTERNAL_CREATOR_INVITE_KEY: internalCreatorInviteKey }
+            : {}),
     };
 }
 export function shardWorkerCommandRegistration(input) {
@@ -563,6 +611,7 @@ export function shardWorkerCommandRegistration(input) {
         synchronise: false,
         selfAuthorizingGuildModuleIds: new Set([
             input.supportModuleId,
+            ...(input.diagnosticModuleId ? [input.diagnosticModuleId] : []),
             ...(input.premiumActivationModuleId
                 ? [input.premiumActivationModuleId]
                 : []),

package/documentation/reference/environment.md

@@ -37,7 +37,7 @@ commented.
 
 Enable privileged intents in the Discord Developer Portal as well as the bot
 environment when required: Counting needs Message Content, Welcome and Access
-Control need Guild Members, and Levels needs both. Access Control's Password
+Control need Guild Members. Levels needs Guild Members, and Message Content only when using **Custom message types** rather than **All messages**. Access Control's Password
 Entry also needs Message Content. The corresponding variables are
 `HELYX_MESSAGE_CONTENT_ENABLED` and `HELYX_GUILD_MEMBERS_ENABLED`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -53,7 +53,7 @@
     "@helyx/config": ">=1.4.0 <2.0.0",
     "@helyx/control-protocol": ">=0.8.0 <0.9.0",
     "@helyx/core": ">=0.2.0 <0.3.0",
-    "@helyx/database": ">=2.4.0 <3.0.0",
+    "@helyx/database": ">=2.4.1 <3.0.0",
     "@helyx/database-contracts": ">=0.2.0 <0.3.0",
     "@helyx/framework": ">=0.2.0 <0.3.0",
     "@helyx/module-manifest": ">=0.13.0 <0.14.0",
@@ -70,7 +70,7 @@
     "zod": "4.4.3"
   },
   "optionalDependencies": {
-    "@helyx/database-mysql": ">=0.2.0 <0.3.0"
+    "@helyx/database-mysql": ">=0.2.1 <0.3.0"
   },
   "peerDependencies": {
     "@helyx/module-automod": ">=1.1.1 <2.0.0",