@helyx/bot 0.1.0

package/dist/events.js

@@ -0,0 +1,142 @@
+import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
+import { Events, } from "discord.js";
+import { toReplyOptions } from "./interactions.js";
+export function installModuleEvents(client, modules, logger, services) {
+    const reactionContributions = modules.flatMap((module) => (module.events?.messageReactionAdd ?? []).map((contribution) => ({
+        moduleId: module.manifest.id,
+        contribution,
+    })));
+    const memberAddContributions = modules.flatMap((module) => (module.events?.guildMemberAdd ?? []).map((contribution) => ({
+        moduleId: module.manifest.id,
+        contribution,
+    })));
+    if (reactionContributions.length === 0 && memberAddContributions.length === 0)
+        return;
+    if (reactionContributions.length > 0) {
+        client.on(Events.MessageReactionAdd, (reaction, user) => {
+            void handleReaction(reaction, user);
+        });
+    }
+    if (memberAddContributions.length > 0) {
+        client.on(Events.GuildMemberAdd, (member) => {
+            void handleMemberAdd(member);
+        });
+    }
+    async function handleReaction(receivedReaction, receivedUser) {
+        try {
+            const user = receivedUser.partial
+                ? await receivedUser.fetch()
+                : receivedUser;
+            if (user.bot)
+                return;
+            const reaction = receivedReaction.partial
+                ? await receivedReaction.fetch()
+                : receivedReaction;
+            const message = reaction.message.partial
+                ? await reaction.message.fetch()
+                : reaction.message;
+            if (!message.guildId || !message.channelId)
+                return;
+            const installations = services.get(HELYX_SERVICE_NAMES.installations);
+            const member = await message.guild?.members.fetch(user.id);
+            const userRoleIds = member ? [...member.roles.cache.keys()] : [];
+            for (const { moduleId, contribution } of reactionContributions) {
+                if (!(await installations.isModuleEnabled(message.guildId, moduleId))) {
+                    continue;
+                }
+                try {
+                    await contribution.execute({
+                        serverId: message.guildId,
+                        channelId: message.channelId,
+                        messageId: message.id,
+                        userId: receivedUser.id,
+                        userRoleIds,
+                        emojiKey: reactionEmojiKey(reaction),
+                        services,
+                        removeAddedReaction: () => reaction.users.remove(user.id).then(() => undefined),
+                        removeUserReaction: async (emojiIdentifier) => {
+                            const refreshed = await message.fetch();
+                            const other = refreshed.reactions.cache.get(reactionCacheKey(emojiIdentifier));
+                            if (other)
+                                await other.users.remove(user.id);
+                        },
+                    });
+                }
+                catch (error) {
+                    logger.warn({
+                        event: "module.reaction_failed",
+                        moduleId,
+                        error: safeError(error),
+                        userId: receivedUser.id,
+                    }, "Module reaction event failed");
+                }
+            }
+        }
+        catch (error) {
+            logger.warn({
+                event: "module.reaction_failed",
+                error: safeError(error),
+                userId: receivedUser.id,
+            }, "Module reaction event failed");
+        }
+    }
+    async function handleMemberAdd(member) {
+        const installations = services.get(HELYX_SERVICE_NAMES.installations);
+        for (const { moduleId, contribution } of memberAddContributions) {
+            try {
+                if (!(await installations.isModuleEnabled(member.guild.id, moduleId))) {
+                    continue;
+                }
+                await contribution.execute({
+                    serverId: member.guild.id,
+                    serverName: member.guild.name,
+                    memberId: member.id,
+                    memberDisplayName: member.displayName,
+                    memberIsBot: member.user.bot,
+                    services,
+                    assignRole: (roleId) => assignMemberRole(member, roleId),
+                    sendToChannel: (channelId, response) => sendToGuildChannel(member, channelId, response),
+                });
+            }
+            catch (error) {
+                logger.warn({
+                    event: "module.member_add_failed",
+                    moduleId,
+                    error: safeError(error),
+                    memberId: member.id,
+                    guildId: member.guild.id,
+                }, "Module member-add event failed");
+            }
+        }
+    }
+}
+async function assignMemberRole(member, roleId) {
+    const role = await member.guild.roles.fetch(roleId);
+    if (!role || role.id === member.guild.id || role.managed || !role.editable) {
+        throw new Error("Configured welcome role cannot be assigned by Helyx");
+    }
+    await member.roles.add(role, "Helyx Welcome module");
+}
+async function sendToGuildChannel(member, channelId, response) {
+    const channel = await member.guild.channels.fetch(channelId);
+    if (!channel?.isSendable()) {
+        throw new Error("Configured welcome channel is not sendable");
+    }
+    const options = toReplyOptions({ ...response, ephemeral: false });
+    const message = await channel.send(options);
+    return { messageId: message.id };
+}
+export function reactionEmojiKey(reaction) {
+    return reaction.emoji.id
+        ? `custom:${reaction.emoji.id}`
+        : `unicode:${(reaction.emoji.name ?? "").normalize("NFKC")}`;
+}
+export function reactionCacheKey(emojiIdentifier) {
+    const custom = /^(?:[A-Za-z0-9_]{2,32}):(\d{17,20})$/u.exec(emojiIdentifier);
+    return custom?.[1] ?? emojiIdentifier;
+}
+function safeError(error) {
+    const value = error instanceof Error ? error : new Error(String(error));
+    return { name: value.name, message: value.message };
+}
+//# sourceMappingURL=events.js.map

package/dist/guilds.d.ts

@@ -0,0 +1,6 @@
+import { type DatabasePool } 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>): (readyClient: Client<true>) => Promise<void>;
+//# sourceMappingURL=guilds.d.ts.map

package/dist/guilds.js

@@ -0,0 +1,53 @@
+import { InstallationRepository } from "@helyx/database";
+import { Events } from "discord.js";
+export function installGuildTracking(client, database, modules, logger, enabledByDefaultModuleIds = new Set()) {
+    const repository = new InstallationRepository(database);
+    async function syncGuild(guild) {
+        await repository.syncGuild({
+            guildId: guild.id,
+            ownerUserId: guild.ownerId,
+            name: guild.name,
+        });
+        for (const module of modules) {
+            await repository.ensureModule({
+                guildId: guild.id,
+                moduleId: module.manifest.id,
+                moduleVersion: module.manifest.version,
+                configurationSchemaVersion: module.configuration?.schemaVersion ?? 1,
+                enabledBy: guild.ownerId,
+                enabledByDefault: enabledByDefaultModuleIds.has(module.manifest.id),
+            });
+        }
+    }
+    client.on(Events.GuildCreate, (guild) => {
+        void syncGuild(guild).catch((error) => {
+            logger.error({
+                event: "guild.sync_failed",
+                guildId: guild.id,
+                error: safeError(error),
+            }, "Guild installation sync failed");
+        });
+    });
+    client.on(Events.GuildDelete, (guild) => {
+        void repository.markGuildRemoved(guild.id).catch((error) => {
+            logger.error({
+                event: "guild.remove_failed",
+                guildId: guild.id,
+                error: safeError(error),
+            }, "Guild removal tracking failed");
+        });
+    });
+    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");
+    };
+}
+function safeError(error) {
+    const value = error instanceof Error ? error : new Error(String(error));
+    return { name: value.name, message: value.message };
+}
+//# sourceMappingURL=guilds.js.map

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { type ModuleDefinition } from "@helyx/sdk";
+import { GatewayIntentBits } from "discord.js";
+export { loadConfiguredModulePackages } from "./modules.js";
+export { resolveModulePackageSpecifiers } from "./module-configuration.js";
+export * from "./control-server.js";
+export interface BotHandle {
+    shutdown(reason?: string): Promise<void>;
+}
+export declare function startBot(processEnvironment?: NodeJS.ProcessEnv): Promise<BotHandle>;
+export declare function gatewayIntentsForModules(modules: readonly ModuleDefinition[]): GatewayIntentBits[];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,185 @@
+import { parseBotEnvironment } from "@helyx/config";
+import { safeError, ServiceRegistry } from "@helyx/core";
+import { checkDatabaseConnection, createDatabasePool, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
+import { createRuntime } from "@helyx/framework";
+import { createPlatformServices } from "@helyx/platform";
+import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
+import { Client, Events, GatewayIntentBits, Partials } from "discord.js";
+import pino from "pino";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { installInteractions } from "./interactions.js";
+import { installGuildTracking } from "./guilds.js";
+import { loadConfiguredModulePackages } from "./modules.js";
+import { resolveModulePackageSpecifiers } from "./module-configuration.js";
+import { createPermissionsModule } from "./permissions-module.js";
+import { createManagementModule } from "./management-module.js";
+import { installModuleEvents } from "./events.js";
+import { DiscordModuleLoggingService } from "./module-logging.js";
+import { BotControlService, createBotControlServer, DiscordGuildResourceDirectory, } from "./control-server.js";
+export { loadConfiguredModulePackages } from "./modules.js";
+export { resolveModulePackageSpecifiers } from "./module-configuration.js";
+export * from "./control-server.js";
+const bootstrapLogger = pino({ base: { component: "bot" } });
+export async function startBot(processEnvironment = process.env) {
+    const environment = parseBotEnvironment(processEnvironment);
+    bootstrapLogger.level = environment.LOG_LEVEL;
+    const database = createDatabasePool({
+        connectionString: environment.DATABASE_URL,
+        sslMode: environment.DATABASE_SSL,
+        applicationName: "helyx-bot",
+    });
+    let databaseClosed = false;
+    async function closeDatabase() {
+        if (databaseClosed)
+            return;
+        databaseClosed = true;
+        await database.end();
+    }
+    try {
+        await checkDatabaseConnection(database);
+        const migrationResult = await runCoreMigrations(database);
+        bootstrapLogger.info({
+            event: "database.ready",
+            appliedMigrations: migrationResult.applied,
+            verifiedMigrationCount: migrationResult.verified.length,
+        }, "Core database ready");
+        const moduleSpecifiers = await resolveModulePackageSpecifiers(environment.HELYX_MODULE_PACKAGES, undefined, undefined, environment.HELYX_MODULE_CATALOGUE_PATH);
+        const modulePackages = await loadConfiguredModulePackages(moduleSpecifiers);
+        const moduleMigrationResults = await runConfiguredModuleMigrations(database, modulePackages.map(({ definition, packageRoot }) => ({
+            moduleId: definition.manifest.id,
+            moduleVersion: definition.manifest.version,
+            migrationsDirectory: join(packageRoot, "migrations"),
+        })));
+        bootstrapLogger.info({
+            event: "database.modules_ready",
+            modules: moduleMigrationResults.map((result) => ({
+                moduleId: result.moduleId,
+                appliedMigrations: result.applied,
+                verifiedMigrationCount: result.verified.length,
+            })),
+        }, "Module databases ready");
+        const featureModules = modulePackages.map(({ definition }) => definition);
+        const client = new Client({
+            intents: gatewayIntentsForModules(featureModules),
+            partials: [Partials.Message, Partials.Channel, Partials.Reaction],
+            allowedMentions: { parse: [] },
+        });
+        const guildResources = new DiscordGuildResourceDirectory(client);
+        const permissionsModule = createPermissionsModule(featureModules);
+        const managementModule = createManagementModule(featureModules, guildResources);
+        const modules = [managementModule, permissionsModule, ...featureModules];
+        const platformServices = new Map(createPlatformServices(database, modules));
+        if (featureModules.some(({ manifest }) => manifest.id === "helyx.logging")) {
+            platformServices.set(HELYX_SERVICE_NAMES.moduleLogging, new DiscordModuleLoggingService(client, database, modules, bootstrapLogger));
+        }
+        const serviceAccess = new ServiceRegistry(platformServices);
+        const runtime = createRuntime({
+            modules,
+            logger: bootstrapLogger,
+            services: platformServices,
+        });
+        const prepareGuilds = installGuildTracking(client, database, modules, bootstrapLogger, new Set([managementModule.manifest.id, permissionsModule.manifest.id]));
+        const commandsReady = installInteractions(client, modules, {
+            ...(environment.DISCORD_INTERNAL_GUILD_ID
+                ? { internalGuildId: environment.DISCORD_INTERNAL_GUILD_ID }
+                : {}),
+            prepare: prepareGuilds,
+        }, bootstrapLogger, serviceAccess);
+        installModuleEvents(client, modules, bootstrapLogger, serviceAccess);
+        let controlServer;
+        let shuttingDown = false;
+        async function shutdown(reason = "programmatic") {
+            if (shuttingDown)
+                return;
+            shuttingDown = true;
+            process.off("SIGINT", onSigint);
+            process.off("SIGTERM", onSigterm);
+            bootstrapLogger.info({ event: "bot.shutdown", reason }, "Bot shutdown requested");
+            if (controlServer)
+                await controlServer.close().catch((error) => {
+                    process.exitCode = 1;
+                    bootstrapLogger.error({ event: "control.stop_failed", error: safeError(error) }, "Private bot control shutdown failed");
+                });
+            try {
+                await runtime.stop();
+            }
+            catch (error) {
+                process.exitCode = 1;
+                bootstrapLogger.error({ event: "runtime.stop_failed", error: safeError(error) }, "Runtime shutdown failed");
+            }
+            await client.destroy();
+            await closeDatabase();
+        }
+        client.once(Events.ClientReady, (readyClient) => {
+            bootstrapLogger.info({ event: "discord.ready", userId: readyClient.user.id }, "Discord client ready");
+        });
+        const onSigint = () => void shutdown("SIGINT");
+        const onSigterm = () => void shutdown("SIGTERM");
+        process.once("SIGINT", onSigint);
+        process.once("SIGTERM", onSigterm);
+        try {
+            await runtime.start();
+            await client.login(environment.DISCORD_TOKEN);
+            await commandsReady;
+            if (environment.HELYX_BOT_CONTROL_SECRET) {
+                controlServer = await createBotControlServer({
+                    service: new BotControlService(database, modules, guildResources, serviceAccess),
+                    secret: environment.HELYX_BOT_CONTROL_SECRET,
+                    logger: { level: environment.LOG_LEVEL },
+                });
+                await controlServer.listen({
+                    host: "::",
+                    port: environment.HELYX_BOT_CONTROL_PORT,
+                });
+                bootstrapLogger.info({
+                    event: "control.ready",
+                    port: environment.HELYX_BOT_CONTROL_PORT,
+                }, "Private bot control ready");
+            }
+            else {
+                bootstrapLogger.warn({ event: "control.disabled" }, "Private bot control is disabled; dashboard configuration is unavailable");
+            }
+        }
+        catch (error) {
+            if (controlServer)
+                await controlServer.close().catch(() => undefined);
+            try {
+                await runtime.stop();
+            }
+            catch (stopError) {
+                bootstrapLogger.error({ event: "runtime.cleanup_failed", error: safeError(stopError) }, "Runtime cleanup failed");
+            }
+            await client.destroy();
+            throw error;
+        }
+        return { shutdown };
+    }
+    catch (error) {
+        await closeDatabase().catch((closeError) => {
+            bootstrapLogger.error({ event: "database.close_failed", error: safeError(closeError) }, "Database pool cleanup failed");
+        });
+        throw error;
+    }
+}
+export function gatewayIntentsForModules(modules) {
+    const intents = [GatewayIntentBits.Guilds];
+    if (modules.some((module) => module.events?.messageReactionAdd?.length)) {
+        intents.push(GatewayIntentBits.GuildMessageReactions);
+    }
+    if (modules.some((module) => module.events?.guildMemberAdd?.length)) {
+        intents.push(GatewayIntentBits.GuildMembers);
+    }
+    return intents;
+}
+if (process.argv[1] &&
+    import.meta.url === pathToFileURL(process.argv[1]).href) {
+    try {
+        await startBot();
+    }
+    catch (error) {
+        bootstrapLogger.fatal({ event: "bot.start_failed", error: safeError(error) }, "Bot startup failed");
+        process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/interactions.d.ts

@@ -0,0 +1,26 @@
+import type { CommandContribution, MessageResponse, ModalDefinition, ModuleDefinition, ServiceAccess } from "@helyx/sdk";
+import { ModalBuilder, type Client, type InteractionReplyOptions, type InteractionUpdateOptions } from "discord.js";
+export interface InteractionLogger {
+    info(fields: Record<string, unknown>, message: string): void;
+    warn(fields: Record<string, unknown>, message: string): void;
+    error(fields: Record<string, unknown>, message: string): void;
+}
+export interface CommandRegistration {
+    internalGuildId?: string;
+    prepare?(client: Client<true>): Promise<void>;
+}
+export declare function installInteractions(client: Client, modules: readonly ModuleDefinition[], registration: CommandRegistration, logger: InteractionLogger, services: ServiceAccess): Promise<void>;
+export declare function resolveCommandExecutor(command: CommandContribution, subcommandName: string | null): CommandContribution["execute"];
+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 sendToChannel(client: Client, channelId: string, response: MessageResponse): Promise<{
+    messageId: string;
+}>;
+export declare function deleteChannelMessage(client: Client, channelId: string, messageId: string): Promise<void>;
+export declare function normalizeDiscordPermission(permission: string): string;
+export declare function toReplyOptions(response: MessageResponse): InteractionReplyOptions;
+export declare function toUpdateOptions(response: MessageResponse): InteractionUpdateOptions;
+export declare function toModal(definition: ModalDefinition): ModalBuilder;
+//# sourceMappingURL=interactions.d.ts.map