@helyx/bot 0.4.11 → 0.4.13

package/dist/guilds.d.ts

@@ -2,5 +2,24 @@ import { type DatabasePool, type GuildShardOwnership } from "@helyx/database";
 import type { ModuleDefinition } from "@helyx/sdk";
 import { type Client } from "discord.js";
 import type { InteractionLogger } from "./interactions.js";
-export declare function installGuildTracking(client: Client, database: DatabasePool, modules: readonly ModuleDefinition[], logger: InteractionLogger, enabledByDefaultModuleIds?: ReadonlySet<string>, ownership?: GuildShardOwnership): (readyClient: Client<true>) => Promise<void>;
+export interface GuildReconciliationHealth {
+    status: "pending" | "running" | "healthy" | "failed" | "stopped";
+    lastStartedAt?: string;
+    lastSucceededAt?: string;
+    durationMs?: number;
+    examinedRows: number;
+    refreshedGuilds: number;
+    removedGuilds: number;
+    rejectedFences: number;
+    unavailableGuilds: number;
+    failureReasonCode?: string | undefined;
+    nextScheduledAt?: string | undefined;
+}
+export interface GuildTrackingPreparation {
+    (readyClient: Client<true>): Promise<void>;
+    reconcile(reason: "ready" | "resume" | "periodic"): Promise<void>;
+    health(): GuildReconciliationHealth;
+    stop(): void;
+}
+export declare function installGuildTracking(client: Client, database: DatabasePool, modules: readonly ModuleDefinition[], logger: InteractionLogger, enabledByDefaultModuleIds?: ReadonlySet<string>, ownership?: GuildShardOwnership, reconciliationIntervalMs?: number, shardCount?: number): GuildTrackingPreparation;
 //# sourceMappingURL=guilds.d.ts.map

package/dist/guilds.js

@@ -1,7 +1,24 @@
 import { InstallationRepository, } from "@helyx/database";
 import { Events } from "discord.js";
-export function installGuildTracking(client, database, modules, logger, enabledByDefaultModuleIds = new Set(), ownership) {
+const RECONCILIATION_PAGE_SIZE = 250;
+const DEFAULT_RECONCILIATION_INTERVAL_MS = 15 * 60 * 1_000;
+export function installGuildTracking(client, database, modules, logger, enabledByDefaultModuleIds = new Set(), ownership, reconciliationIntervalMs = DEFAULT_RECONCILIATION_INTERVAL_MS, shardCount) {
+    if (!Number.isSafeInteger(reconciliationIntervalMs) ||
+        reconciliationIntervalMs < 60_000)
+        throw new Error("Guild reconciliation interval must be at least one minute");
     const repository = new InstallationRepository(database);
+    let prepared = false;
+    let stopped = false;
+    let reconciliation;
+    let timer;
+    let health = {
+        status: "pending",
+        examinedRows: 0,
+        refreshedGuilds: 0,
+        removedGuilds: 0,
+        rejectedFences: 0,
+        unavailableGuilds: 0,
+    };
     async function syncGuild(guild) {
         const record = await repository.syncGuild({
             guildId: guild.id,
@@ -39,10 +56,16 @@ export function installGuildTracking(client, database, modules, logger, enabledB
     client.on(Events.GuildDelete, (guild) => {
         void repository
             .markGuildRemoved(guild.id, ownership)
+            .then((changed) => {
+            logger.info({
+                event: "guild.removed",
+                outcome: changed ? "changed" : "rejected_or_duplicate",
+            }, "Discord guild removal observation persisted");
+        })
             .catch((error) => {
             logger.error({
                 event: "guild.remove_failed",
-                guildId: guild.id,
+                reasonCode: "database_write_failed",
                 error: safeError(error),
             }, "Guild removal tracking failed");
         });
@@ -50,14 +73,131 @@ export function installGuildTracking(client, database, modules, logger, enabledB
     client.on(Events.GuildUnavailable, (guild) => {
         logger.warn({ event: "guild.unavailable", guildId: guild.id }, "Discord guild is temporarily unavailable; installation remains active");
     });
-    return async (readyClient) => {
-        for (const guild of readyClient.guilds.cache.values())
-            await syncGuild(guild);
-        logger.info({
-            event: "guilds.synchronised",
-            guildCount: readyClient.guilds.cache.size,
-        }, "Discord guild installations synchronised");
+    async function runReconciliation(reason) {
+        if (stopped || !prepared || !client.isReady())
+            return;
+        if (reconciliation)
+            return reconciliation;
+        reconciliation = (async () => {
+            const startedAt = Date.now();
+            health = {
+                ...health,
+                status: "running",
+                lastStartedAt: new Date(startedAt).toISOString(),
+                failureReasonCode: undefined,
+                nextScheduledAt: undefined,
+            };
+            let examinedRows = 0;
+            let refreshedGuilds = 0;
+            let removedGuilds = 0;
+            let rejectedFences = 0;
+            const observedGuildIds = new Set(client.guilds.cache.keys());
+            const unavailableGuilds = [...client.guilds.cache.values()].filter((guild) => !guild.available).length;
+            try {
+                for (const guild of client.guilds.cache.values()) {
+                    if (stopped)
+                        return;
+                    await syncGuild(guild);
+                    refreshedGuilds += 1;
+                }
+                let cursor;
+                do {
+                    if (stopped || !client.isReady())
+                        return;
+                    const page = await repository.listActiveGuildIdsForOwnership({
+                        ...(ownership ? { ownership } : {}),
+                        ...(ownership && shardCount !== undefined ? { shardCount } : {}),
+                        ...(cursor ? { cursor } : {}),
+                        limit: RECONCILIATION_PAGE_SIZE,
+                    });
+                    examinedRows += page.guildIds.length;
+                    if (ownership)
+                        await repository.adoptGuildsForReconciliation({
+                            guildIds: page.guildIds,
+                            ownership,
+                            shardCount: shardCount,
+                        });
+                    const absent = page.guildIds.filter((guildId) => !observedGuildIds.has(guildId));
+                    const result = await repository.markGuildsRemovedForReconciliation({
+                        guildIds: absent,
+                        ...(ownership ? { ownership } : {}),
+                    });
+                    removedGuilds += result.changed;
+                    rejectedFences += result.rejectedFence;
+                    cursor = page.nextCursor;
+                } while (cursor);
+                const completedAt = Date.now();
+                health = {
+                    status: "healthy",
+                    lastStartedAt: new Date(startedAt).toISOString(),
+                    lastSucceededAt: new Date(completedAt).toISOString(),
+                    durationMs: completedAt - startedAt,
+                    examinedRows,
+                    refreshedGuilds,
+                    removedGuilds,
+                    rejectedFences,
+                    unavailableGuilds,
+                    nextScheduledAt: new Date(completedAt + reconciliationIntervalMs).toISOString(),
+                };
+                logger.info({
+                    event: "guild.reconciliation_completed",
+                    reason,
+                    durationMs: health.durationMs,
+                    examinedRows,
+                    refreshedGuilds,
+                    removedGuilds,
+                    rejectedFences,
+                    unavailableGuilds,
+                }, "Discord guild presence reconciliation completed");
+            }
+            catch (error) {
+                health = {
+                    status: "failed",
+                    lastStartedAt: new Date(startedAt).toISOString(),
+                    durationMs: Date.now() - startedAt,
+                    examinedRows,
+                    refreshedGuilds,
+                    removedGuilds,
+                    rejectedFences,
+                    unavailableGuilds,
+                    failureReasonCode: "reconciliation_failed",
+                    nextScheduledAt: new Date(Date.now() + reconciliationIntervalMs).toISOString(),
+                };
+                logger.error({
+                    event: "guild.reconciliation_failed",
+                    reason,
+                    reasonCode: health.failureReasonCode,
+                    error: safeError(error),
+                }, "Discord guild presence reconciliation failed");
+            }
+        })().finally(() => {
+            reconciliation = undefined;
+        });
+        return reconciliation;
+    }
+    const prepare = async (readyClient) => {
+        if (stopped || !readyClient.isReady())
+            return;
+        prepared = true;
+        await runReconciliation("ready");
+        if (!timer) {
+            timer = setInterval(() => void runReconciliation("periodic"), reconciliationIntervalMs);
+            timer.unref();
+        }
+    };
+    client.on(Events.ShardResume, () => {
+        void runReconciliation("resume");
+    });
+    prepare.reconcile = runReconciliation;
+    prepare.health = () => ({ ...health });
+    prepare.stop = () => {
+        stopped = true;
+        if (timer)
+            clearInterval(timer);
+        timer = undefined;
+        health = { ...health, status: "stopped", nextScheduledAt: undefined };
     };
+    return prepare;
 }
 function safeError(error) {
     const value = error instanceof Error ? error : new Error(String(error));

package/dist/index.js

@@ -1,6 +1,6 @@
 import { parseBotEnvironment } from "@helyx/config";
 import { safeError, ServiceRegistry } from "@helyx/core";
-import { checkDatabaseConnection, createDatabasePool, InteractionSessionRepository, RateLimitRepository, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
+import { checkDatabaseConnection, createDatabasePool, AuditRepository, InteractionSessionRepository, RateLimitRepository, runCoreMigrations, runConfiguredModuleMigrations, VerificationSetupRepository, } from "@helyx/database";
 import { createRuntime } from "@helyx/framework";
 import { createPlatformServices, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
 import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
@@ -18,9 +18,10 @@ import { loadConfiguredModulePackages, platformServiceOptions, } from "./modules
 import { resolveModulePackageSpecifiers } from "./module-configuration.js";
 import { createPermissionsModule } from "./permissions-module.js";
 import { createManagementModule } from "./management-module.js";
-import { DiscordMessageDeliveryService, DiscordMemberEnforcementService, DiscordMemberRoleService, DiscordResourceInspection, installModuleEvents, } from "./events.js";
+import { DiscordMessageDeliveryService, DiscordMemberEnforcementService, DiscordMemberRoleService, DiscordVerificationMemberService, DiscordVerificationSetupService, DiscordResourceInspection, installModuleEvents, } from "./events.js";
 import { DiscordModuleLoggingService } from "./module-logging.js";
 import { BotControlService, createBotControlServer, DiscordGuildResourceDirectory, } from "./control-server.js";
+import { HttpVerificationService } from "./verification-service.js";
 import { startShardSupervisor } from "./shard-supervisor.js";
 import { parseShardWorkerLaunchContract, startShardWorker, } from "./shard-worker.js";
 import { createDeveloperOperationsModule } from "./developer-operations-module.js";
@@ -87,15 +88,17 @@ async function startUnshardedBot(processEnvironment) {
             verifiedMigrationCount: migrationResult.verified.length,
         }, "Core database ready");
         const cleanupExpiredCoreRecords = async () => {
-            const [sessions, rateLimits] = await Promise.all([
+            const [sessions, rateLimits, verificationAudit] = await Promise.all([
                 new InteractionSessionRepository(database).deleteExpired(),
                 new RateLimitRepository(database).deleteExpired(),
+                new AuditRepository(database).deleteModuleEventsOlderThanMonths("helyx.verification", 12),
             ]);
-            if (sessions > 0 || rateLimits > 0) {
+            if (sessions > 0 || rateLimits > 0 || verificationAudit > 0) {
                 bootstrapLogger.info({
                     event: "database.retention_cleaned",
                     interactionSessions: sessions,
                     rateLimitWindows: rateLimits,
+                    verificationAuditEvents: verificationAudit,
                 }, "Expired core records removed");
             }
         };
@@ -243,6 +246,18 @@ async function startUnshardedBot(processEnvironment) {
         })) {
             platformServices.set(name, service);
         }
+        if (environment.HELYX_VERIFICATION_ENABLED &&
+            environment.HELYX_VERIFICATION_URL &&
+            environment.HELYX_VERIFICATION_INTERNAL_SECRET) {
+            platformServices.set(HELYX_SERVICE_NAMES.verification, new HttpVerificationService({
+                baseUrl: environment.HELYX_VERIFICATION_URL,
+                internalSecret: environment.HELYX_VERIFICATION_INTERNAL_SECRET,
+                installationId: environment.HELYX_VERIFICATION_INSTALLATION_ID,
+                publicSigningKeys: environment.HELYX_VERIFICATION_SIGNING_PUBLIC_KEYS,
+            }));
+            platformServices.set(HELYX_SERVICE_NAMES.verificationMembers, new DiscordVerificationMemberService(client));
+            platformServices.set(HELYX_SERVICE_NAMES.verificationSetup, new DiscordVerificationSetupService(client, new VerificationSetupRepository(database)));
+        }
         const numericWriteBehind = createLocalNumericWriteBehind(platformServices, publicModules);
         platformServices.set(HELYX_SERVICE_NAMES.numericWriteBehind, numericWriteBehind);
         platformServices.set(HELYX_SERVICE_NAMES.resourceAuthorization, new CoreResourceAuthorizationService(platformServices.get(HELYX_SERVICE_NAMES.permissions)));
@@ -266,7 +281,7 @@ async function startUnshardedBot(processEnvironment) {
             ...(cloudManagementModule ? [cloudManagementModule.manifest.id] : []),
             ...(operationsModule ? [operationsModule.manifest.id] : []),
         ]);
-        const prepareGuilds = installGuildTracking(client, database, publicModules, bootstrapLogger, enabledCoreModuleIds);
+        const prepareGuilds = installGuildTracking(client, database, publicModules, bootstrapLogger, enabledCoreModuleIds, undefined, environment.HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS * 1_000);
         const commandsReady = installInteractions(client, modules, {
             ...(environment.DISCORD_INTERNAL_GUILD_ID
                 ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
@@ -298,6 +313,7 @@ async function startUnshardedBot(processEnvironment) {
             if (shuttingDown)
                 return;
             shuttingDown = true;
+            prepareGuilds.stop();
             process.off("SIGINT", onSigint);
             process.off("SIGTERM", onSigterm);
             if (retentionCleanupTimer)

package/dist/interactions.js

@@ -294,6 +294,7 @@ function addCommandOption(builder, option) {
     const channelTypes = {
         guild_text: ChannelType.GuildText,
         guild_announcement: ChannelType.GuildAnnouncement,
+        guild_category: ChannelType.GuildCategory,
     };
     builder.addChannelOption((optionBuilder) => {
         optionBuilder
@@ -376,6 +377,7 @@ function createContext(interaction, services) {
                 ...(ephemeral ? { flags: MessageFlags.Ephemeral } : {}),
             });
         },
+        deleteReplyAfter: (milliseconds) => scheduleReplyDeletion(interaction, milliseconds),
         reply: (response) => replyToInteraction(interaction, response),
         ...(interaction.isMessageComponent()
             ? {
@@ -490,6 +492,7 @@ function createModalContext(interaction, services) {
                 ...(ephemeral ? { flags: MessageFlags.Ephemeral } : {}),
             });
         },
+        deleteReplyAfter: (milliseconds) => scheduleReplyDeletion(interaction, milliseconds),
         reply: (response) => replyToInteraction(interaction, response),
         ...(updateResponse ? { updateResponse } : {}),
         getField: (customId) => interaction.fields.getTextInputValue(customId),
@@ -517,6 +520,16 @@ function createModalContext(interaction, services) {
         addChannelMessageReaction: (channelId, messageId, emojiIdentifier) => addChannelMessageReaction(interaction.client, channelId, messageId, emojiIdentifier),
     };
 }
+function scheduleReplyDeletion(interaction, milliseconds) {
+    if (!Number.isInteger(milliseconds) ||
+        milliseconds < 1_000 ||
+        milliseconds > 900_000)
+        throw new Error("Reply deletion delay must be between 1 second and 15 minutes");
+    const timer = setTimeout(() => {
+        void interaction.deleteReply().catch(() => undefined);
+    }, milliseconds);
+    timer.unref();
+}
 function createSelectContext(interaction, services) {
     return {
         ...createContext(interaction, services),
@@ -739,9 +752,7 @@ function toSelectRows(response) {
                 .setPlaceholder(select.placeholder)
                 .setMinValues(select.minValues ?? 1)
                 .setMaxValues(select.maxValues ?? 1)
-                .setChannelTypes(...select.channelTypes.map((type) => type === "guild_announcement"
-                ? ChannelType.GuildAnnouncement
-                : ChannelType.GuildText))));
+                .setChannelTypes(...select.channelTypes.map(discordChannelType))));
             continue;
         }
         if (select.type === "discord-role") {
@@ -881,9 +892,7 @@ export function toModal(definition) {
                 .setRequired(field.required ?? false)
                 .setMinValues(field.minValues ?? (field.required ? 1 : 0))
                 .setMaxValues(field.maxValues ?? 1)
-                .setChannelTypes(...field.channelTypes.map((type) => type === "guild_announcement"
-                ? ChannelType.GuildAnnouncement
-                : ChannelType.GuildText));
+                .setChannelTypes(...field.channelTypes.map(discordChannelType));
             if (field.placeholder !== undefined)
                 input.setPlaceholder(field.placeholder);
             if (field.defaultValues?.length)
@@ -894,6 +903,13 @@ export function toModal(definition) {
     }
     return modal;
 }
+function discordChannelType(type) {
+    if (type === "guild_announcement")
+        return ChannelType.GuildAnnouncement;
+    if (type === "guild_category")
+        return ChannelType.GuildCategory;
+    return ChannelType.GuildText;
+}
 async function sendFailure(interaction) {
     if (interaction.isAutocomplete()) {
         await interaction.respond([]).catch(() => undefined);

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";
+        type: "guild_text" | "guild_announcement" | "guild_category";
     }[];
     roles: readonly {
         id: string;