@helyx/bot 0.4.31 → 0.4.32

package/dist/discord-guild-health.js

@@ -0,0 +1,370 @@
+import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
+import { AuditLogEvent, GatewayIntentBits, } from "discord.js";
+import { isDeepStrictEqual } from "node:util";
+const unavailable = (code) => ({ available: false, code });
+const INTERNAL_HELYX_MODULE_IDS = new Set([
+    "helyx.cloud-connect",
+    "helyx.management",
+    "helyx.permissions",
+    "helyx.support",
+]);
+export function moduleCatalogueMatches(packagedManifest, executableManifest) {
+    return (packagedManifest !== null &&
+        isDeepStrictEqual(packagedManifest, executableManifest));
+}
+export function missingRequiredPermissions(grantedPermissions, requiredPermissions) {
+    const granted = new Set(grantedPermissions.map(normalizePermission));
+    if (granted.has(normalizePermission("Administrator")))
+        return [];
+    return requiredPermissions.filter((permission) => !granted.has(normalizePermission(permission)));
+}
+export function hasRequiredModuleConfiguration(exposesConfiguration, savedConfiguration) {
+    return !exposesConfiguration || savedConfiguration !== null;
+}
+export function isHealthInspectableModule(moduleId) {
+    return !INTERNAL_HELYX_MODULE_IDS.has(moduleId);
+}
+export class DiscordGuildHealthInspection {
+    client;
+    modules;
+    services;
+    constructor(client, modules = [], services) {
+        this.client = client;
+        this.modules = modules;
+        this.services = services;
+    }
+    inspectOverview(input) {
+        const guild = this.#guild(input.guildId);
+        const bot = guild.members.me;
+        if (!bot)
+            return Promise.resolve(unavailable("discord_unavailable"));
+        return Promise.resolve({
+            available: true,
+            guildId: guild.id,
+            name: guild.name,
+            ownerId: guild.ownerId,
+            createdAt: guild.createdAt,
+            memberCount: guild.memberCount,
+            verificationLevel: ["None", "Low", "Medium", "High", "VeryHigh"][Number(guild.verificationLevel)] ?? "Unknown",
+            explicitContentFilter: ["Disabled", "MembersWithoutRoles", "AllMembers"][Number(guild.explicitContentFilter)] ?? "Unknown",
+            defaultMessageNotifications: ["AllMessages", "OnlyMentions"][Number(guild.defaultMessageNotifications)] ?? "Unknown",
+            mfaLevel: Number(guild.mfaLevel) === 1 ? "Elevated" : "None",
+            premiumTier: Number(guild.premiumTier),
+            features: [...guild.features],
+            botPermissions: bot.permissions.toArray(),
+            channelCount: guild.channels.cache.size,
+            roleCount: guild.roles.cache.size,
+            emojiCount: guild.emojis.cache.size,
+            stickerCount: guild.stickers.cache.size,
+            rulesChannelId: guild.rulesChannelId,
+            publicUpdatesChannelId: guild.publicUpdatesChannelId,
+            safetyAlertsChannelId: guild.safetyAlertsChannelId,
+            invitesDisabledUntil: guild.incidentsData?.invitesDisabledUntil ?? null,
+            dmsDisabledUntil: guild.incidentsData?.dmsDisabledUntil ?? null,
+            botHighestRolePosition: bot.roles.highest.position,
+        });
+    }
+    listChannels(input) {
+        const guild = this.#guild(input.guildId);
+        const bot = guild.members.me;
+        if (!bot)
+            return Promise.resolve(unavailable("discord_unavailable"));
+        return Promise.resolve({
+            available: true,
+            items: guild.channels.cache.map((channel) => ({
+                channelId: channel.id,
+                name: channel.name,
+                type: String(channel.type),
+                parentId: "parentId" in channel ? (channel.parentId ?? null) : null,
+                ageRestricted: "nsfw" in channel && channel.nsfw === true,
+                everyonePermissions: channel.permissionsFor(guild.roles.everyone)?.toArray() ?? [],
+                botPermissions: channel.permissionsFor(bot)?.toArray() ?? [],
+                permissionsLocked: "permissionsLocked" in channel
+                    ? (channel.permissionsLocked ?? null)
+                    : null,
+            })),
+        });
+    }
+    listRoles(input) {
+        const guild = this.#guild(input.guildId);
+        return Promise.resolve({
+            available: true,
+            items: guild.roles.cache.map((role) => ({
+                roleId: role.id,
+                name: role.name,
+                position: role.position,
+                managed: role.managed,
+                memberCount: role.members.size,
+                permissions: role.permissions.toArray(),
+            })),
+        });
+    }
+    async listMembers(input) {
+        const guild = this.#guild(input.guildId);
+        try {
+            const limit = Math.min(1_000, Math.max(1, input.limit));
+            const members = await guild.members.list({
+                limit,
+                ...(input.after ? { after: input.after } : {}),
+            });
+            const items = members.map((member) => ({
+                userId: member.id,
+                bot: member.user.bot,
+                system: member.user.system === true,
+                createdAt: member.user.createdAt,
+                joinedAt: member.joinedAt,
+                timedOutUntil: member.communicationDisabledUntil,
+                publicFlags: member.user.flags?.toArray() ?? [],
+                roleIds: [...member.roles.cache.keys()],
+            }));
+            return {
+                available: true,
+                items,
+                ...(members.size === limit && members.last()
+                    ? { nextAfter: members.last().id }
+                    : {}),
+            };
+        }
+        catch (error) {
+            return this.#unavailable(error, "missing_intent");
+        }
+    }
+    async listInvites(input) {
+        try {
+            const guild = this.#guild(input.guildId);
+            const invites = await guild.invites.fetch();
+            return {
+                available: true,
+                items: invites.map((invite) => ({
+                    code: invite.code,
+                    channelId: invite.channelId,
+                    channelName: invite.channelId
+                        ? (guild.channels.cache.get(invite.channelId)?.name ?? null)
+                        : null,
+                    channelExists: invite.channelId !== null &&
+                        guild.channels.cache.has(invite.channelId),
+                    inviterUserId: invite.inviterId,
+                    createdAt: invite.createdAt,
+                    expiresAt: invite.expiresAt,
+                    maxUses: invite.maxUses ?? 0,
+                    uses: invite.uses ?? 0,
+                    temporary: invite.temporary ?? false,
+                })),
+            };
+        }
+        catch (error) {
+            return this.#unavailable(error, "missing_permission");
+        }
+    }
+    async listIntegrations(input) {
+        try {
+            const guild = this.#guild(input.guildId);
+            const integrations = await guild.fetchIntegrations();
+            return {
+                available: true,
+                items: integrations.map((integration) => ({
+                    integrationId: integration.id,
+                    name: integration.name,
+                    type: integration.type,
+                    enabled: integration.enabled ?? false,
+                    syncing: "syncing" in integration ? (integration.syncing ?? null) : null,
+                    roleId: "role" in integration ? (integration.role?.id ?? null) : null,
+                    roleExists: !("role" in integration) ||
+                        !integration.role?.id ||
+                        guild.roles.cache.has(integration.role.id),
+                })),
+            };
+        }
+        catch (error) {
+            return this.#unavailable(error, "missing_permission");
+        }
+    }
+    async listWebhooks(input) {
+        try {
+            const webhooks = await this.#guild(input.guildId).fetchWebhooks();
+            return {
+                available: true,
+                items: webhooks.map((webhook) => ({
+                    webhookId: webhook.id,
+                    name: webhook.name,
+                    channelId: webhook.channelId,
+                    ownerUserId: webhook.owner?.id ?? null,
+                    applicationId: webhook.applicationId,
+                    channelName: webhook.channelId
+                        ? (this.#guild(input.guildId).channels.cache.get(webhook.channelId)
+                            ?.name ?? null)
+                        : null,
+                })),
+            };
+        }
+        catch (error) {
+            return this.#unavailable(error, "missing_permission");
+        }
+    }
+    async listAutoModerationRules(input) {
+        try {
+            const rules = await this.#guild(input.guildId).autoModerationRules.fetch();
+            return {
+                available: true,
+                items: rules.map((rule) => ({
+                    ruleId: rule.id,
+                    name: rule.name,
+                    enabled: rule.enabled,
+                    triggerType: String(rule.triggerType),
+                    eventType: String(rule.eventType),
+                    actionCount: rule.actions.length,
+                })),
+            };
+        }
+        catch (error) {
+            return this.#unavailable(error, "missing_permission");
+        }
+    }
+    async inspectAuditSummary(input) {
+        try {
+            const audit = await this.#guild(input.guildId).fetchAuditLogs({
+                limit: 100,
+            });
+            const cutoff = Date.now() - 60 * 60 * 1_000;
+            const highImpact = new Set([
+                AuditLogEvent.MemberBanAdd,
+                AuditLogEvent.MemberKick,
+                AuditLogEvent.RoleCreate,
+                AuditLogEvent.RoleDelete,
+                AuditLogEvent.RoleUpdate,
+                AuditLogEvent.ChannelDelete,
+                AuditLogEvent.WebhookCreate,
+                AuditLogEvent.WebhookDelete,
+                AuditLogEvent.WebhookUpdate,
+            ]);
+            return {
+                available: true,
+                inspected: audit.entries.size,
+                highImpactActionsLastHour: audit.entries.filter((entry) => entry.createdTimestamp >= cutoff && highImpact.has(entry.action)).size,
+            };
+        }
+        catch (error) {
+            return this.#unavailable(error, "missing_permission");
+        }
+    }
+    async inspectHelyxModules(input) {
+        if (!this.services)
+            return unavailable("not_supported");
+        try {
+            const installations = this.services.get(HELYX_SERVICE_NAMES.installations);
+            const configurations = this.services.get(HELYX_SERVICE_NAMES.configuration);
+            const catalogue = this.services.has(HELYX_SERVICE_NAMES.moduleCatalogue)
+                ? this.services.get(HELYX_SERVICE_NAMES.moduleCatalogue)
+                : null;
+            const resources = this.services.has(HELYX_SERVICE_NAMES.discordResources)
+                ? this.services.get(HELYX_SERVICE_NAMES.discordResources)
+                : null;
+            const capabilities = resources
+                ? await resources.inspectRuntimeCapabilities()
+                : {
+                    guildMembers: this.client.options.intents.has(GatewayIntentBits.GuildMembers),
+                    messageContent: this.client.options.intents.has(GatewayIntentBits.MessageContent),
+                };
+            const overview = await this.inspectOverview(input);
+            if (!overview.available)
+                return overview;
+            const items = [];
+            const batchSize = Math.min(20, Math.max(1, input.batchSize ?? 20));
+            const inspectableModules = this.modules.filter((module) => isHealthInspectableModule(module.manifest.id));
+            for (let index = 0; index < inspectableModules.length; index += 1) {
+                const module = inspectableModules[index];
+                const state = await installations.getModuleState(input.guildId, module.manifest.id);
+                const configuration = await configurations.get(input.guildId, module.manifest.id);
+                let configurationValid = true;
+                let resourceValidationValid = null;
+                if (configuration && module.configuration)
+                    try {
+                        module.configuration.validate(configuration.value);
+                    }
+                    catch {
+                        configurationValid = false;
+                    }
+                if (state?.enabled &&
+                    configuration &&
+                    module.configuration?.validateUpdate)
+                    try {
+                        await module.configuration.validateUpdate({
+                            guildId: input.guildId,
+                            value: configuration.value,
+                            services: this.services,
+                        });
+                        resourceValidationValid = true;
+                    }
+                    catch {
+                        resourceValidationValid = false;
+                    }
+                let activationValid = null;
+                if (state?.enabled && module.validateActivation)
+                    try {
+                        await module.validateActivation({
+                            guildId: input.guildId,
+                            services: this.services,
+                        });
+                        activationValid = true;
+                    }
+                    catch {
+                        activationValid = false;
+                    }
+                const health = module.health
+                    ? await Promise.resolve(module.health()).catch(() => ({
+                        status: "unhealthy",
+                        message: "Module health check failed",
+                    }))
+                    : { status: "healthy", message: null };
+                const packaged = catalogue?.get(module.manifest.id) ?? null;
+                const requiredCapabilities = module.requiredDiscordCapabilities ?? [];
+                const missingCapabilities = requiredCapabilities.filter((capability) => (capability === "guild-members" && !capabilities.guildMembers) ||
+                    (capability === "message-content" && !capabilities.messageContent));
+                const missingPermissions = missingRequiredPermissions(overview.botPermissions, module.manifest.permissions);
+                items.push({
+                    moduleId: module.manifest.id,
+                    name: module.manifest.name,
+                    version: module.manifest.version,
+                    enabled: state?.enabled ?? false,
+                    configured: hasRequiredModuleConfiguration(module.configuration !== undefined, configuration),
+                    configurationValid,
+                    resourceValidationValid,
+                    activationValid,
+                    catalogueMatches: moduleCatalogueMatches(packaged, module.manifest),
+                    requiredCapabilities,
+                    missingCapabilities,
+                    missingPermissions,
+                    healthStatus: health.status,
+                    healthMessage: health.message ?? null,
+                    diagnosticsAvailable: module.health !== undefined,
+                });
+                if ((index + 1) % batchSize === 0)
+                    await Promise.resolve();
+            }
+            return { available: true, items };
+        }
+        catch {
+            return unavailable("not_supported");
+        }
+    }
+    #guild(guildId) {
+        const guild = this.client.guilds.cache.get(guildId);
+        if (!guild)
+            throw new Error("Discord server is not owned by this worker");
+        return guild;
+    }
+    #unavailable(error, fallback) {
+        if (typeof error === "object" && error !== null && "code" in error) {
+            const code = Number(error.code);
+            if (code === 50_001 || code === 50_013)
+                return unavailable(fallback);
+        }
+        throw error instanceof Error
+            ? error
+            : new Error("Discord guild inspection failed");
+    }
+}
+function normalizePermission(value) {
+    return value.replaceAll(/[^a-z0-9]/giu, "").toLowerCase();
+}
+//# sourceMappingURL=discord-guild-health.js.map

package/dist/events.d.ts

@@ -7,6 +7,7 @@ export interface ModuleEventHandle {
     queueDepth(): number;
 }
 export declare function reactionEmojiKey(reaction: MessageReaction | PartialMessageReaction): string;
+export declare function reactionEmojiIdentifier(reaction: MessageReaction | PartialMessageReaction): string;
 export declare function reactionCacheKey(emojiIdentifier: string): string;
 interface ApprovedRoleMutation {
     guildId: string;
@@ -20,6 +21,7 @@ export declare class DiscordMessageDeliveryService implements DiscordMessageServ
     constructor(client: Client);
     send(input: Parameters<DiscordMessageService["send"]>[0]): ReturnType<DiscordMessageService["send"]>;
     sendDirect(input: Parameters<DiscordMessageService["sendDirect"]>[0]): ReturnType<DiscordMessageService["sendDirect"]>;
+    fetchSource(input: Parameters<DiscordMessageService["fetchSource"]>[0]): ReturnType<DiscordMessageService["fetchSource"]>;
 }
 export declare class DiscordMemberEnforcementService implements MemberEnforcementService {
     #private;
@@ -110,6 +112,19 @@ export declare class DiscordResourceInspection implements DiscordResourceInspect
         avatarUrl?: string;
         isBot: boolean;
     }[]>;
+    listMembers(input: {
+        guildId: string;
+        after?: string;
+        limit: number;
+    }): Promise<{
+        items: readonly {
+            userId: string;
+            displayName: string;
+            avatarUrl?: string;
+            isBot: boolean;
+        }[];
+        nextCursor?: string;
+    }>;
     inspectRole(input: {
         guildId: string;
         roleId: string;