@helyx/bot 0.4.37 → 0.4.39

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, AuditRepository, InteractionSessionRepository, RateLimitRepository, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
+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 { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
@@ -29,12 +29,19 @@ import { createDeveloperOperationsModule } from "./developer-operations-module.j
 import { shardHealthSnapshotSchema } from "./shard-contracts.js";
 import { createSupportModule } from "./support-module.js";
 import { createOAuthModule } from "./oauth-module.js";
+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 { GuildCommandWorker } from "./guild-command-worker.js";
+import { GuildCommandDiscordClient } from "./guild-command-discord-client.js";
+import { GuildCommandReadService } from "./guild-command-read-service.js";
+import { scheduleGuildCommandRelease } from "./guild-command-release.js";
 import { CoreResourceAuthorizationService } from "./resource-authorization.js";
+import { PostgresTriviaDataProvider } from "./trivia-data-provider.js";
 import { createLocalScheduledTaskRoute, createScheduledTaskRunner, schedulerOperationalHealth, } from "./scheduled-task-runner.js";
 import { createLocalNumericWriteBehind } from "./numeric-write-behind.js";
+import { discordRestOptions } from "./discord-rest.js";
 export { loadConfiguredModulePackages } from "./modules.js";
 export { resolveModulePackageSpecifiers } from "./module-configuration.js";
 export * from "./control-server.js";
@@ -128,17 +135,26 @@ async function startUnshardedBot(processEnvironment) {
             verifiedMigrationCount: migrationResult.verified.length,
         }, "Core database ready");
         const cleanupExpiredCoreRecords = async () => {
-            const [sessions, rateLimits, verificationAudit] = await Promise.all([
+            const [sessions, rateLimits, verificationAudit, commandRecords] = await Promise.all([
                 new InteractionSessionRepository(database).deleteExpired(),
                 new RateLimitRepository(database).deleteExpired(),
                 new AuditRepository(database).deleteModuleEventsOlderThanMonths("helyx.verification", 12),
+                new GuildCommandRepository(database).deleteExpired(12),
             ]);
-            if (sessions > 0 || rateLimits > 0 || verificationAudit > 0) {
+            const commandRecordCount = commandRecords.history +
+                commandRecords.idempotencyKeys +
+                commandRecords.creationLedger +
+                commandRecords.requests;
+            if (sessions > 0 ||
+                rateLimits > 0 ||
+                verificationAudit > 0 ||
+                commandRecordCount > 0) {
                 bootstrapLogger.info({
                     event: "database.retention_cleaned",
                     interactionSessions: sessions,
                     rateLimitWindows: rateLimits,
                     verificationAuditEvents: verificationAudit,
+                    commandRecords: commandRecordCount,
                 }, "Expired core records removed");
             }
         };
@@ -169,6 +185,7 @@ async function startUnshardedBot(processEnvironment) {
         }, "Module databases ready");
         const featureModules = modulePackages.map(({ definition }) => definition);
         const client = new Client({
+            rest: discordRestOptions,
             intents: gatewayIntentsForModules(featureModules, environment.HELYX_MESSAGE_CONTENT_ENABLED, environment.HELYX_GUILD_MEMBERS_ENABLED),
             partials: [Partials.Message, Partials.Channel, Partials.Reaction],
             allowedMentions: { parse: [] },
@@ -192,6 +209,7 @@ async function startUnshardedBot(processEnvironment) {
             })
             : undefined;
         const supportModule = createSupportModule(cloudConnector);
+        const privacyModule = createPrivacyModule();
         const oauthModule = environment.HELYX_OAUTH_ENABLED
             ? createOAuthModule()
             : undefined;
@@ -199,11 +217,13 @@ async function startUnshardedBot(processEnvironment) {
             managementModule,
             permissionsModule,
             supportModule,
+            privacyModule,
             ...(oauthModule ? [oauthModule] : []),
             ...(cloudManagementModule ? [cloudManagementModule] : []),
             ...featureModules,
         ];
         let scheduledTasks;
+        let guildCommandWorker;
         const unshardedSupervisorId = randomUUID();
         const deployedCommit = deploymentReference(processEnvironment);
         const operationsModule = environment.DISCORD_INTERNAL_GUILD_ID
@@ -216,11 +236,13 @@ async function startUnshardedBot(processEnvironment) {
                     managementModule,
                     permissionsModule,
                     supportModule,
+                    privacyModule,
                     ...(oauthModule ? [oauthModule] : []),
                     ...(cloudManagementModule ? [cloudManagementModule] : []),
                 ].map(({ manifest }) => manifest),
                 modules: featureModules.map(({ manifest }) => manifest),
                 processLabel: "unsharded bot process",
+                triviaData: new PostgresTriviaDataProvider(database),
                 health: {
                     getHealth: async () => {
                         let databaseHealthy = true;
@@ -333,11 +355,13 @@ async function startUnshardedBot(processEnvironment) {
             ...(cloudManagementModule ? [cloudManagementModule.manifest.id] : []),
             ...(operationsModule ? [operationsModule.manifest.id] : []),
         ]);
-        const prepareGuilds = installGuildTracking(client, database, publicModules, bootstrapLogger, enabledCoreModuleIds, undefined, environment.HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS * 1_000);
+        const prepareGuilds = installGuildTracking(client, database, publicModules, bootstrapLogger, enabledCoreModuleIds, undefined, environment.HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS * 1_000, undefined, environment.DISCORD_CLIENT_ID);
         const commandsReady = installInteractions(client, modules, {
+            globalCommandMode: environment.HELYX_GLOBAL_COMMAND_MODE,
             ...(environment.DISCORD_INTERNAL_GUILD_ID
                 ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
                 : {}),
+            synchroniseInternalGuild: !environment.HELYX_GUILD_COMMAND_WRITES_ENABLED,
             prepare: prepareGuilds,
             selfAuthorizingGuildModuleIds: new Set([
                 supportModule.manifest.id,
@@ -383,6 +407,13 @@ async function startUnshardedBot(processEnvironment) {
                 process.exitCode = 1;
                 bootstrapLogger.error({ event: "scheduler.stop_failed", error: safeError(error) }, "Scheduled task runner shutdown failed");
             });
+            await guildCommandWorker?.stop().catch((error) => {
+                process.exitCode = 1;
+                bootstrapLogger.error({
+                    event: "guild_commands.worker_stop_failed",
+                    error: safeError(error),
+                }, "Guild command worker shutdown failed");
+            });
             bootstrapLogger.info({ event: "bot.shutdown", reason }, "Bot shutdown requested");
             await cloudConnector.stop().catch((error) => {
                 process.exitCode = 1;
@@ -442,12 +473,51 @@ async function startUnshardedBot(processEnvironment) {
                 workerId: `unsharded:${unshardedSupervisorId}`,
             });
             scheduledTasks.start();
+            guildCommandWorker = new GuildCommandWorker({
+                database,
+                modules,
+                logger: bootstrapLogger,
+                workerId: `unsharded-command:${unshardedSupervisorId}`,
+                fencingToken: 1n,
+                ...(environment.DISCORD_INTERNAL_GUILD_ID
+                    ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
+                    : {}),
+                ...(environment.HELYX_GUILD_COMMAND_WRITES_ENABLED
+                    ? {
+                        discord: new GuildCommandDiscordClient({
+                            applicationId: environment.DISCORD_CLIENT_ID,
+                            token: environment.DISCORD_TOKEN,
+                            writeGuildIds: environment.HELYX_GUILD_COMMAND_WRITE_GUILD_IDS,
+                            writeAllGuilds: environment.HELYX_GUILD_COMMAND_WRITE_SCOPE === "all",
+                        }),
+                    }
+                    : {}),
+            });
+            guildCommandWorker.start();
+            if (environment.HELYX_GUILD_COMMAND_WRITES_ENABLED &&
+                environment.HELYX_GUILD_COMMAND_WRITE_SCOPE === "all") {
+                void scheduleGuildCommandRelease({
+                    database,
+                    applicationId: environment.DISCORD_CLIENT_ID,
+                    releaseId: environment.HELYX_GUILD_COMMAND_RELEASE_ID,
+                })
+                    .then((release) => {
+                    bootstrapLogger.info({ event: "guild_commands.release_scheduled", ...release }, "Guild command release rollout prepared");
+                })
+                    .catch((error) => {
+                    bootstrapLogger.error({
+                        event: "guild_commands.release_schedule_failed",
+                        error: safeError(error),
+                    }, "Guild command release rollout could not be prepared");
+                });
+            }
             await cloudConnector.start();
             if (environment.HELYX_BOT_CONTROL_SECRET) {
                 controlServer = await createBotControlServer({
                     service: controlService,
                     secret: environment.HELYX_BOT_CONTROL_SECRET,
                     logger: { level: environment.LOG_LEVEL },
+                    guildCommands: new GuildCommandReadService(database, environment.DISCORD_CLIENT_ID, () => guildCommandWorker?.getHealth(), environment.DISCORD_TOKEN, environment.HELYX_GUILD_COMMAND_WRITES_ENABLED, environment.HELYX_GUILD_COMMAND_WRITE_GUILD_IDS, environment.HELYX_GUILD_COMMAND_WRITE_SCOPE === "all", modules),
                 });
                 await controlServer.listen({
                     host: "::",
@@ -464,6 +534,7 @@ async function startUnshardedBot(processEnvironment) {
         }
         catch (error) {
             await scheduledTasks?.stop().catch(() => undefined);
+            await guildCommandWorker?.stop().catch(() => undefined);
             await cloudConnector.stop().catch(() => undefined);
             if (controlServer)
                 await controlServer.close().catch(() => undefined);

package/dist/interactions.d.ts

@@ -1,6 +1,9 @@
-import type { CommandContribution, MessageResponse, ModalDefinition, ModuleDefinition, ServiceAccess } from "@helyx/sdk";
-import { ModalBuilder, type ChatInputCommandInteraction, type Client, type InteractionReplyOptions, type InteractionUpdateOptions } from "discord.js";
+import type { CommandAutocompleteContext, CommandAuthorization, CommandContribution, MessageResponse, ModalDefinition, ModuleDefinition, ServiceAccess } from "@helyx/sdk";
+import { type GlobalCommandRegistrationMode } from "./command-registration-policy.js";
+import { ModalBuilder, type AutocompleteInteraction, type ChatInputCommandInteraction, type Client, type InteractionReplyOptions, type InteractionUpdateOptions } from "discord.js";
 export declare const GLOBAL_MODULE_UNAVAILABLE_MESSAGE = "This module is temporarily unavailable for all hosted servers.";
+export declare const AUTOCOMPLETE_RESPONSE_DEADLINE_MS = 2000;
+export declare const DISCORD_DNS_REFRESH_INTERVAL_MS = 30000;
 export interface InteractionLogger {
     info(fields: Record<string, unknown>, message: string): void;
     warn(fields: Record<string, unknown>, message: string): void;
@@ -10,10 +13,14 @@ export interface CommandRegistration {
     internalGuildId?: string;
     prepare?(client: Client<true>): Promise<void>;
     synchronise?: boolean;
+    synchroniseInternalGuild?: boolean;
+    globalCommandMode?: GlobalCommandRegistrationMode;
     selfAuthorizingGuildModuleIds?: ReadonlySet<string>;
 }
 export declare function installInteractions(client: Client, modules: readonly ModuleDefinition[], registration: CommandRegistration, logger: InteractionLogger, services: ServiceAccess): Promise<void>;
-export declare function buildApplicationCommandDefinitions(modules: readonly ModuleDefinition[], internalGuildId?: string): {
+export declare function warmDiscordRestConnection(client: Client<true>, logger: InteractionLogger): Promise<void>;
+export declare function startDiscordDnsRefresh(logger: InteractionLogger, lookup?: (hostname: string) => Promise<unknown>, intervalMilliseconds?: number): ReturnType<typeof setInterval>;
+export declare function buildApplicationCommandDefinitions(modules: readonly ModuleDefinition[], internalGuildId?: string, globalCommandMode?: GlobalCommandRegistrationMode): {
     global: ReturnType<typeof toCommandDefinition>[];
     guild: ReturnType<typeof toCommandDefinition>[];
 };
@@ -22,13 +29,17 @@ export declare function toCommandDefinition(registered: {
     contribution: CommandContribution;
 }): import("discord.js").RESTPostAPIChatInputApplicationCommandsJSONBody;
 export declare function uniqueMap<T>(items: readonly T[], keyOf: (item: T) => string, label: string): Map<string, T>;
+export declare function createAutocompleteResponseController(interaction: AutocompleteInteraction, logger: InteractionLogger): {
+    respond: CommandAutocompleteContext["respond"];
+    ensureResponded(): Promise<void>;
+};
 export declare function sendToChannel(client: Client, channelId: string, response: MessageResponse, deliveryId?: string): Promise<{
     messageId: string;
 }>;
 export declare function deleteChannelMessage(client: Client, channelId: string, messageId: string): Promise<void>;
 export declare function editChannelMessage(client: Client, channelId: string, messageId: string, response: MessageResponse): Promise<void>;
 export declare function addChannelMessageReaction(client: Client, channelId: string, messageId: string, emojiIdentifier: string): Promise<void>;
-export declare function authorizeCommand(interaction: ChatInputCommandInteraction, moduleId: string, commandId: string, rateLimit: CommandContribution["rateLimit"], services: ServiceAccess, selfAuthorizingGuildCommand: boolean, resourceScopedCommand?: boolean, requiredModuleName?: string): Promise<boolean>;
+export declare function authorizeCommand(interaction: ChatInputCommandInteraction, moduleId: string, commandId: string, rateLimit: CommandContribution["rateLimit"], services: ServiceAccess, selfAuthorizingGuildCommand: boolean, resourceScopedCommand?: boolean, requiredModuleName?: string, installationIndependentCommand?: boolean, authorization?: CommandAuthorization): Promise<boolean>;
 export declare function normalizeDiscordPermission(permission: string): string;
 export declare function toReplyOptions(response: MessageResponse): InteractionReplyOptions;
 export declare function toUpdateOptions(response: MessageResponse): InteractionUpdateOptions;