@helyx/bot 1.3.1 → 1.5.0

package/dist/creator-onboarding-control.d.ts

@@ -0,0 +1,12 @@
+import { type CreatorOnboardingRequest, type CreatorOnboardingResponse, type InstallationService, type ModuleDefinition, type ServiceAccess } from "@helyx/sdk";
+import type { FastifyInstance } from "fastify";
+export declare function registerCreatorOnboardingControlRoute(server: FastifyInstance, service: {
+    creatorOnboarding?(input: CreatorOnboardingRequest): Promise<CreatorOnboardingResponse>;
+}): void;
+/** Execute the public creator flow behind the bot's existing module guards. */
+export declare function executeCreatorOnboarding(input: CreatorOnboardingRequest, dependencies: {
+    modules: ReadonlyMap<string, ModuleDefinition>;
+    installations: InstallationService;
+    services: ServiceAccess;
+}): Promise<CreatorOnboardingResponse>;
+//# sourceMappingURL=creator-onboarding-control.d.ts.map

package/dist/creator-onboarding-control.js

@@ -0,0 +1,65 @@
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { moduleAvailabilityService } from "./module-availability-control.js";
+import { canAccessModule } from "./premium-access.js";
+import { creatorOnboardingRequestSchema } from "@helyx/control-protocol";
+import { BotControlTransportError } from "./control-errors.js";
+export function registerCreatorOnboardingControlRoute(server, service) {
+    server.post("/v1/creator-onboarding", async (request) => {
+        if (!service.creatorOnboarding)
+            throw new BotControlTransportError(503, "Creator onboarding is unavailable");
+        return service.creatorOnboarding(creatorOnboardingRequestSchema.parse(request.body));
+    });
+}
+/** Execute the public creator flow behind the bot's existing module guards. */
+export async function executeCreatorOnboarding(input, dependencies) {
+    const { modules, installations, services } = dependencies;
+    const module = modules.get("helyx.creator-connections");
+    if (!module?.creatorOnboarding ||
+        (moduleAvailabilityService(services) &&
+            !(await moduleAvailabilityService(services).isAvailable(module.manifest.id))) ||
+        !(await installations.isModuleEnabled(input.guildId, module.manifest.id)) ||
+        !(await canAccessModule(services, input.guildId, module)))
+        return { available: false };
+    if (input.action === "inspect") {
+        const page = await module.creatorOnboarding.execute({ action: "page", guildId: input.guildId, reference: input.reference }, services);
+        if (!page.available ||
+            page.page?.configurationRevision !== input.configurationRevision ||
+            !services.has(HELYX_SERVICE_NAMES.creatorGuildJoin))
+            return { available: false };
+        const status = await services
+            .get(HELYX_SERVICE_NAMES.creatorGuildJoin)
+            .inspect({ guildId: input.guildId, memberUserId: input.memberUserId });
+        return {
+            available: true,
+            memberReadiness: status.memberReadiness,
+            joinOutcome: ["member_missing", "unavailable"].includes(status.memberReadiness)
+                ? "uncertain"
+                : "already_member",
+        };
+    }
+    if (input.action !== "join")
+        return module.creatorOnboarding.execute(input, services);
+    const page = await module.creatorOnboarding.execute({ action: "page", guildId: input.guildId, reference: input.reference }, services);
+    if (!page.available ||
+        page.page?.configurationRevision !== input.configurationRevision ||
+        !services.has(HELYX_SERVICE_NAMES.creatorGuildJoin))
+        return { available: false };
+    const joined = await services
+        .get(HELYX_SERVICE_NAMES.creatorGuildJoin)
+        .join({
+        guildId: input.guildId,
+        memberUserId: input.memberUserId,
+        sessionId: input.sessionId,
+        authorisationReference: input.authorisationReference,
+    });
+    let effects = { available: true };
+    if (input.withTwitch && ["joined", "already_member"].includes(joined.outcome))
+        effects = await module.creatorOnboarding.execute({ ...input, action: "deliver" }, services);
+    return {
+        ...effects,
+        available: true,
+        joinOutcome: joined.outcome,
+        memberReadiness: joined.memberReadiness,
+    };
+}
+//# sourceMappingURL=creator-onboarding-control.js.map

package/dist/creator-onboarding-platform.d.ts

@@ -0,0 +1,20 @@
+import { type DatabasePool } from "@helyx/database";
+import { type ModuleDefinition, type ServiceAccess } from "@helyx/sdk";
+import type { Client } from "discord.js";
+/** Independent of customer-module start/stop so disabled invites can still be revoked. */
+export declare function installCreatorInvitePlatform(input: {
+    client: Client;
+    database: DatabasePool;
+    services: ServiceAccess;
+    modules: readonly ModuleDefinition[];
+    encryptionKey: string | undefined;
+    oauthBroker?: {
+        baseUrl: string;
+        secret: string;
+    };
+    register(name: string, service: unknown): void;
+    warn(event: string): void;
+}): Promise<{
+    stop(): Promise<void>;
+} | undefined>;
+//# sourceMappingURL=creator-onboarding-platform.d.ts.map

package/dist/creator-onboarding-platform.js

@@ -0,0 +1,58 @@
+import { CreatorInviteRepository } from "@helyx/database";
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { DiscordCreatorInviteService } from "./creator-invite-service.js";
+import { DiscordCreatorGuildJoinService } from "./creator-guild-join-service.js";
+/** Independent of customer-module start/stop so disabled invites can still be revoked. */
+export async function installCreatorInvitePlatform(input) {
+    const module = input.modules.find((candidate) => candidate.manifest.id === "helyx.creator-connections");
+    const repository = new CreatorInviteRepository(input.database);
+    if (!module && !(await repository.isInstalled()))
+        return undefined;
+    if (!input.encryptionKey)
+        throw new Error("Hosted Creator Connections invites require HELYX_DATA_ENCRYPTION_KEY");
+    const service = new DiscordCreatorInviteService(input.client, repository, input.services, module, input.encryptionKey);
+    input.register(HELYX_SERVICE_NAMES.creatorInvites, service);
+    if (input.oauthBroker) {
+        const broker = input.oauthBroker;
+        input.register(HELYX_SERVICE_NAMES.creatorGuildJoin, new DiscordCreatorGuildJoinService(input.client, input.services, input.modules, repository, async (request) => {
+            const response = await fetch(new URL("/v1/internal/oauth/onboarding/credential", broker.baseUrl), {
+                method: "POST",
+                headers: {
+                    authorization: `Bearer ${broker.secret}`,
+                    "content-type": "application/json",
+                },
+                body: JSON.stringify(request),
+                signal: AbortSignal.timeout(10_000),
+            });
+            if (!response.ok)
+                throw new Error("creator_join_authorisation_unavailable");
+            const result = (await response.json());
+            if (typeof result.accessToken !== "string" ||
+                typeof result.applicationId !== "string")
+                throw new Error("creator_join_authorisation_invalid");
+            return {
+                accessToken: result.accessToken,
+                applicationId: result.applicationId,
+            };
+        }));
+    }
+    let pending;
+    const timer = setInterval(() => {
+        if (pending || !input.client.isReady())
+            return;
+        pending = service
+            .cleanupUnavailableInvites()
+            .catch(() => input.warn("creator_invites.cleanup_delayed"))
+            .finally(() => {
+            pending = undefined;
+        });
+    }, 30_000);
+    timer.unref();
+    return {
+        async stop() {
+            clearInterval(timer);
+            await pending;
+        },
+    };
+}
+//# sourceMappingURL=creator-onboarding-platform.js.map

package/dist/dashboard-action-control.d.ts

@@ -1,4 +1,4 @@
-import { type DatabasePool } from "@helyx/database";
+import type { InstallationRepository } from "@helyx/database";
 import { type DashboardActionContext, type DashboardActionInspection, type DashboardActionResult, type ModuleDefinition, type PermissionActor, type ServiceAccess } from "@helyx/sdk";
 export interface DashboardActionInput {
     guildId: string;
@@ -10,7 +10,7 @@ export interface DashboardActionInput {
 }
 export type DashboardActionPreviewInput = Omit<DashboardActionInput, "inspectionRevision">;
 export interface DashboardActionControl {
-    database: DatabasePool;
+    installations: Pick<InstallationRepository, "isModuleEnabled">;
     services: ServiceAccess;
     requireDashboardModule(moduleId: string): ModuleDefinition;
     requireModuleAccessible(guildId: string, moduleId: string): Promise<void>;

package/dist/dashboard-action-control.js

@@ -1,4 +1,3 @@
-import { InstallationRepository } from "@helyx/database";
 import {} from "@helyx/sdk";
 import { dashboardActionPermissionId } from "./control-permissions.js";
 import { requireDashboardFeatures } from "./dashboard-feature-control.js";
@@ -10,7 +9,7 @@ function prepareAction(input, control) {
 }
 async function requireEnabledAndAuthorized(input, control, module, permissionId, disabledMessage) {
     const [enabled] = await Promise.all([
-        new InstallationRepository(control.database).isModuleEnabled(input.guildId, input.moduleId),
+        control.installations.isModuleEnabled(input.guildId, input.moduleId),
         control.authorizeAction(input.guildId, module, input.actorUserId, permissionId),
     ]);
     if (!enabled)
@@ -25,7 +24,7 @@ function actionContext(input, control, module, permissionId) {
         revalidate: async () => {
             try {
                 await control.requireModuleAccessible(input.guildId, input.moduleId);
-                const enabled = await new InstallationRepository(control.database).isModuleEnabled(input.guildId, input.moduleId);
+                const enabled = await control.installations.isModuleEnabled(input.guildId, input.moduleId);
                 if (!enabled)
                     return false;
                 await control.authorizeAction(input.guildId, module, input.actorUserId, permissionId);

package/dist/database-bootstrap.d.ts

@@ -0,0 +1,36 @@
+import type { BotEnvironment } from "@helyx/config";
+import { resolveDatabaseAdapter } from "@helyx/database/adapters";
+import type { DatabaseAdapter, DatabaseSession } from "@helyx/database-contracts";
+import { type ConfiguredModulePackage } from "./modules.js";
+type MigrationResult = Awaited<ReturnType<DatabaseSession<unknown>["migrations"]["runCore"]>>;
+type MigrationInspection = Awaited<ReturnType<DatabaseSession<unknown>["migrations"]["inspectCore"]>>;
+export interface BotDatabaseStartupResult {
+    readonly core: MigrationResult;
+    readonly modules: readonly {
+        moduleId: string;
+        applied: readonly string[];
+        verified: readonly string[];
+    }[];
+}
+export interface BotDatabaseHandle<Repositories = Record<string, never>> {
+    readonly session: DatabaseSession<Repositories>;
+    readonly migrations: BotDatabaseStartupResult;
+    /** A read-only adapter query that also verifies the core migration ledger. */
+    healthCheck(): Promise<MigrationInspection>;
+    close(): Promise<void>;
+}
+export interface BotDatabaseBootstrapInput {
+    readonly environment: Pick<BotEnvironment, "DATABASE_ENGINE" | "DATABASE_URL" | "DATABASE_SSL" | "HELYX_RUNTIME_PROFILE">;
+    readonly modulePackages: readonly ConfiguredModulePackage[];
+    readonly applicationName?: string;
+}
+/**
+ * Engine-neutral database startup foundation. Bot repositories and platform
+ * services still need an engine-aware runtime before this can replace the
+ * PostgreSQL-only startup path.
+ */
+export declare function openBotDatabase(input: BotDatabaseBootstrapInput, resolveAdapter?: typeof resolveDatabaseAdapter): Promise<BotDatabaseHandle>;
+/** Connect with an explicit repository-bearing adapter and the same startup checks. */
+export declare function openBotDatabaseWithAdapter<Repositories>(input: BotDatabaseBootstrapInput, adapter: DatabaseAdapter<Repositories>): Promise<BotDatabaseHandle<Repositories>>;
+export {};
+//# sourceMappingURL=database-bootstrap.d.ts.map

package/dist/database-bootstrap.js

@@ -0,0 +1,101 @@
+import { resolveDatabaseAdapter } from "@helyx/database/adapters";
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+import { assertConfiguredModuleDatabaseCompatibility, } from "./modules.js";
+/**
+ * Engine-neutral database startup foundation. Bot repositories and platform
+ * services still need an engine-aware runtime before this can replace the
+ * PostgreSQL-only startup path.
+ */
+export async function openBotDatabase(input, resolveAdapter = resolveDatabaseAdapter) {
+    const prepared = await prepareBotDatabase(input);
+    const adapter = await resolveAdapter(prepared.engine);
+    return connectPreparedBotDatabase(input, prepared, adapter);
+}
+/** Connect with an explicit repository-bearing adapter and the same startup checks. */
+export async function openBotDatabaseWithAdapter(input, adapter) {
+    const prepared = await prepareBotDatabase(input);
+    return connectPreparedBotDatabase(input, prepared, adapter);
+}
+async function prepareBotDatabase(input) {
+    const { environment, modulePackages } = input;
+    const engine = environment.DATABASE_ENGINE;
+    if (engine !== "postgresql" && engine !== "mysql") {
+        throw new Error(`Unsupported bot DATABASE_ENGINE=${String(engine)}`);
+    }
+    if (engine === "mysql" &&
+        environment.HELYX_RUNTIME_PROFILE !== "self-hosted") {
+        throw new Error("Bot MySQL database startup requires HELYX_RUNTIME_PROFILE=self-hosted");
+    }
+    assertConfiguredModuleDatabaseCompatibility(modulePackages, engine);
+    const migrationSources = await Promise.all(modulePackages.map(async ({ definition, packageRoot }) => {
+        const manifest = definition.manifest;
+        const migrationsDirectory = join(packageRoot, engine === "mysql" ? "migrations-mysql" : "migrations");
+        if (engine === "mysql") {
+            const directory = await stat(migrationsDirectory).catch((error) => {
+                if (error.code === "ENOENT")
+                    return undefined;
+                throw error;
+            });
+            const postgresDirectory = await stat(join(packageRoot, "migrations")).catch((error) => {
+                if (error.code === "ENOENT")
+                    return undefined;
+                throw error;
+            });
+            if ((!directory || !directory.isDirectory()) &&
+                postgresDirectory?.isDirectory()) {
+                throw new Error(`Module ${manifest.id} is missing its MySQL migration directory: ${migrationsDirectory}`);
+            }
+        }
+        return {
+            moduleId: manifest.id,
+            moduleVersion: manifest.version,
+            migrationsDirectory,
+        };
+    }));
+    return { engine, migrationSources };
+}
+async function connectPreparedBotDatabase(input, prepared, adapter) {
+    const { environment } = input;
+    const { engine, migrationSources } = prepared;
+    if (adapter.engine !== engine) {
+        throw new Error(`Database adapter mismatch: requested ${engine}, received ${adapter.engine}`);
+    }
+    const session = await adapter.connect({
+        connectionString: environment.DATABASE_URL,
+        sslMode: environment.DATABASE_SSL,
+        applicationName: input.applicationName ?? "helyx-bot",
+    });
+    try {
+        if (session.identity.engine !== engine) {
+            throw new Error(`Database identity mismatch: requested ${engine}, received ${session.identity.engine}`);
+        }
+        const core = await session.migrations.runCore();
+        const modules = [];
+        for (const source of migrationSources) {
+            const result = await session.migrations.runModule(source);
+            modules.push({ moduleId: source.moduleId, ...result });
+        }
+        let closed = false;
+        return {
+            session,
+            migrations: { core, modules },
+            healthCheck() {
+                if (closed)
+                    return Promise.reject(new Error("Bot database is closed"));
+                return session.migrations.inspectCore();
+            },
+            async close() {
+                if (closed)
+                    return;
+                closed = true;
+                await session.close();
+            },
+        };
+    }
+    catch (error) {
+        await session.close().catch(() => undefined);
+        throw error;
+    }
+}
+//# sourceMappingURL=database-bootstrap.js.map

package/dist/developer-operations-module.d.ts

@@ -15,6 +15,7 @@ export interface DeveloperOperationsInput {
     approvedRoleIds: readonly string[];
     botVersion: string;
     deploymentReference?: string;
+    databaseEngine: "postgresql" | "mysql";
     coreFunctions: readonly DeveloperModuleSummary[];
     modules: readonly DeveloperModuleSummary[];
     processLabel: string;

package/dist/developer-operations-module.js

@@ -5,7 +5,6 @@ import { INTERNAL_MODULE_MANIFEST_FIELDS } from "./internal-module-manifest.js";
 const DEVELOPER_MODULE_ID = "helyx.developer-operations";
 const DEVELOPER_MODULE_NAME = "Helyx Developer Operations";
 const DEVELOPER_MODULE_VERSION = "0.3.0";
-const MAX_MODULE_LINES = 8;
 export function createDeveloperOperationsModule(input) {
     const approvedRoles = new Set(input.approvedRoleIds);
     return defineModule({
@@ -27,6 +26,7 @@ export function createDeveloperOperationsModule(input) {
             commands: Object.fromEntries([
                 "dev.shards",
                 "dev.bot",
+                "dev.modules",
                 "dev.proc",
                 "dev.trivia-data",
                 "dev.leave",
@@ -96,7 +96,7 @@ export function createDeveloperOperationsModule(input) {
                         {
                             name: "bot",
                             permissionId: "dev.bot",
-                            description: "Show the bot build and installed module versions",
+                            description: "Show the bot build and core function versions",
                             acknowledgement: "immediate-response",
                             authorization: "self-authorized",
                             async execute(context) {
@@ -110,13 +110,7 @@ export function createDeveloperOperationsModule(input) {
                                     },
                                     ...input.coreFunctions,
                                 ].sort((left, right) => left.id.localeCompare(right.id));
-                                const modules = [...input.modules].sort((left, right) => left.id.localeCompare(right.id));
-                                const visibleCoreFunctions = coreFunctions.slice(0, MAX_MODULE_LINES);
-                                const visibleModules = modules.slice(0, Math.max(0, MAX_MODULE_LINES - visibleCoreFunctions.length));
-                                const coreFunctionLines = visibleCoreFunctions.map((coreFunction) => `- ${safeInlineCode(coreFunction.name)} · ${safeInlineCode(coreFunction.id)} · ${safeInlineCode(coreFunction.version)}`);
-                                const moduleLines = visibleModules.map((module) => `- ${safeInlineCode(module.name)} · ${safeInlineCode(module.id)} · ${safeInlineCode(module.version)}`);
-                                const componentCount = coreFunctions.length + modules.length;
-                                const visibleComponentCount = visibleCoreFunctions.length + visibleModules.length;
+                                const coreFunctionLines = coreFunctions.map((coreFunction) => `- ${safeInlineCode(coreFunction.name)} · ${safeInlineCode(coreFunction.version)}`);
                                 await context.reply({
                                     ephemeral: true,
                                     componentsV2: {
@@ -127,19 +121,43 @@ export function createDeveloperOperationsModule(input) {
                                                     "## Bot information",
                                                     `Version: ${safeInlineCode(input.botVersion)}`,
                                                     `Build: ${safeInlineCode(input.deploymentReference ?? "not supplied")}`,
+                                                    `Database: ${safeInlineCode(input.databaseEngine === "mysql" ? "MySQL" : "PostgreSQL")}`,
                                                     `Runtime: ${input.processLabel}`,
                                                     `Core functions: ${coreFunctions.length}`,
-                                                    `Installed modules: ${modules.length}`,
+                                                    `Installed modules: ${input.modules.length} — see /dev modules`,
                                                     "",
                                                     "### Core functions",
                                                     ...coreFunctionLines,
+                                                ].join("\n"),
+                                            },
+                                        ],
+                                    },
+                                });
+                            },
+                        },
+                        {
+                            name: "modules",
+                            permissionId: "dev.modules",
+                            description: "List all installed feature modules and their versions",
+                            acknowledgement: "immediate-response",
+                            authorization: "self-authorized",
+                            async execute(context) {
+                                if (!(await authorizeDeveloperCommand(context)))
+                                    return;
+                                const modules = [...input.modules].sort((left, right) => left.id.localeCompare(right.id));
+                                await context.reply({
+                                    ephemeral: true,
+                                    componentsV2: {
+                                        accentColor: 0x2563eb,
+                                        text: [
+                                            {
+                                                content: [
+                                                    "## Installed modules",
+                                                    `Total: ${modules.length}`,
                                                     "",
-                                                    "### Modules",
-                                                    ...moduleLines,
-                                                    ...(componentCount > visibleComponentCount
-                                                        ? [
-                                                            `… showing ${visibleComponentCount} of ${componentCount} components`,
-                                                        ]
+                                                    ...modules.map((module) => `- ${safeInlineCode(module.name)} · ${safeInlineCode(module.version)}`),
+                                                    ...(modules.length === 0
+                                                        ? ["No feature modules installed."]
                                                         : []),
                                                 ].join("\n"),
                                             },

package/dist/discord-channel-audit.d.ts

@@ -0,0 +1,9 @@
+import type { Client } from "discord.js";
+import type { ChannelAuditInput, ChannelAuditModuleId, ChannelAuditReport } from "@helyx/sdk";
+/** Fresh guild roles/channels and the bot member only. Never reads messages or enumerates members. */
+export declare function inspectDiscordChannelAudit(client: Client, input: {
+    guildId: string;
+    moduleId: ChannelAuditModuleId;
+    assumptions: ChannelAuditInput;
+}): Promise<ChannelAuditReport>;
+//# sourceMappingURL=discord-channel-audit.d.ts.map

package/dist/discord-channel-audit.js

@@ -0,0 +1,195 @@
+import { PermissionFlagsBits } from "discord.js";
+import { channelAuditInputSchema, channelAuditReportSchema, } from "@helyx/control-protocol/channel-audit";
+import { buildChannelAuditReport, } from "./channel-audit-permissions.js";
+import { dangerousRolePermissions } from "./discord-role-safety.js";
+async function readBefore(read, deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw new Error("Channel audit read deadline reached");
+    let timer;
+    try {
+        return await Promise.race([
+            read(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error("Channel audit read deadline reached")), remaining);
+                timer.unref();
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/** Fresh guild roles/channels and the bot member only. Never reads messages or enumerates members. */
+export async function inspectDiscordChannelAudit(client, input) {
+    const assumptions = channelAuditInputSchema.parse(input.assumptions);
+    const deadline = Date.now() + 8_500;
+    const snapshot = {
+        guildId: input.guildId,
+        roles: [],
+        rolesComplete: false,
+        channels: [],
+        fetchedChannels: 0,
+        totalChannelsKnown: false,
+        fetchLimitations: [],
+    };
+    const guild = await readBefore(() => client.guilds.fetch(input.guildId), deadline).catch(() => null);
+    if (!guild) {
+        snapshot.fetchLimitations.push("The current Discord server could not be fetched; channel and role coverage is incomplete.");
+        return channelAuditReportSchema.parse(buildChannelAuditReport(snapshot, input.moduleId, assumptions, new Date().toISOString()));
+    }
+    if (guild.id !== input.guildId)
+        throw new Error("Discord returned a different server for this inspection");
+    const [rolesResult, channelsResult, memberResult] = await Promise.allSettled([
+        readBefore(() => guild.roles.fetch(), deadline),
+        readBefore(() => guild.channels.fetch(), deadline),
+        readBefore(() => guild.members.fetchMe({ force: true }), deadline),
+    ]);
+    const me = memberResult.status === "fulfilled" ? memberResult.value : null;
+    if (me && me.guild.id !== guild.id)
+        throw new Error("Discord bot member belongs to a different server");
+    if (!me)
+        snapshot.fetchLimitations.push("Helyx's current server member could not be fetched; bot publishing and assignment checks may be unknown.");
+    if (rolesResult.status === "fulfilled") {
+        snapshot.rolesComplete = true;
+        const canManage = me?.permissions.has(PermissionFlagsBits.ManageRoles) ?? false;
+        snapshot.roles = [...rolesResult.value.values()].map((role) => {
+            if (role.guild.id !== guild.id)
+                throw new Error("Discord role belongs to a different server");
+            const reason = role.id === guild.id
+                ? "The everyone role cannot be assigned."
+                : role.managed
+                    ? "This role is managed by Discord or an integration and cannot be assigned by Helyx."
+                    : !me
+                        ? undefined
+                        : !canManage
+                            ? "Helyx lacks Manage Roles in this server."
+                            : role.comparePositionTo(me.roles.highest) >= 0
+                                ? "The selected role is at or above Helyx's highest role."
+                                : undefined;
+            const dangerous = dangerousRolePermissions(role.permissions.bitfield);
+            return {
+                id: role.id,
+                permissions: role.permissions.bitfield,
+                managed: role.managed,
+                assignable: reason ? false : me ? true : null,
+                ...(reason ? { assignmentReason: reason } : {}),
+                ...(dangerous.length
+                    ? {
+                        assignmentPolicyReason: `Helyx's role-safety policy blocks managing roles with ${dangerous.join(", ")}. Discord hierarchy alone does not make this role eligible.`,
+                    }
+                    : {}),
+            };
+        });
+    }
+    else
+        snapshot.fetchLimitations.push("The current Discord role list could not be fetched; missing roles are unknown, not confirmed deleted.");
+    const observedIds = new Set();
+    if (channelsResult.status === "fulfilled") {
+        snapshot.fetchedChannels = channelsResult.value.size;
+        for (const channel of channelsResult.value.values()) {
+            if (!channel)
+                continue;
+            if (channel.guild.id !== guild.id)
+                throw new Error("Discord channel belongs to a different server");
+            observedIds.add(channel.id);
+            const flags = "flags" in channel ? BigInt(channel.flags.bitfield) : 0n;
+            const obfuscated = (flags & 131072n) !== 0n || channel.name === "___hidden___";
+            const overwrites = "permissionOverwrites" in channel
+                ? [...channel.permissionOverwrites.cache.values()].map((overwrite) => ({
+                    id: overwrite.id,
+                    type: overwrite.type,
+                    allow: overwrite.allow.bitfield,
+                    deny: overwrite.deny.bitfield,
+                }))
+                : [];
+            const botPermissions = !obfuscated && me
+                ? (channel.permissionsFor(me)?.bitfield ?? null)
+                : null;
+            snapshot.channels.push({
+                id: channel.id,
+                name: obfuscated ? "Unknown channel" : channel.name,
+                type: channel.type,
+                obfuscated,
+                overwrites: obfuscated ? [] : overwrites,
+                botPermissions,
+            });
+        }
+        snapshot.totalChannelsKnown =
+            me?.permissions.has(PermissionFlagsBits.Administrator) ?? false;
+    }
+    else
+        snapshot.fetchLimitations.push("Discord's channel list could not be fetched; cached metadata is not used as fresh permission evidence.");
+    // Bulk lists can omit invisible channels. Resolve only explicitly selected
+    // missing IDs; a permission failure or deadline remains unknown.
+    const selected = new Set([
+        assumptions.entryChannelId,
+        ...assumptions.allowedChannelIds,
+        ...(assumptions.reviewChannelId ? [assumptions.reviewChannelId] : []),
+    ]);
+    snapshot.invalidSelectedChannels = [];
+    for (const id of selected) {
+        if (observedIds.has(id))
+            continue;
+        try {
+            const channel = await readBefore(() => guild.channels.fetch(id, { force: true, cache: false }), deadline);
+            if (!channel)
+                continue;
+            if (channel.guild.id !== guild.id) {
+                snapshot.invalidSelectedChannels.push({ id, reason: "wrong_guild" });
+                continue;
+            }
+            observedIds.add(id);
+            const obfuscated = (BigInt("flags" in channel ? channel.flags.bitfield : 0) & 131072n) !==
+                0n || channel.name === "___hidden___";
+            snapshot.channels.push({
+                id,
+                name: obfuscated ? "Unknown channel" : channel.name,
+                type: channel.type,
+                obfuscated,
+                overwrites: !obfuscated && "permissionOverwrites" in channel
+                    ? [...channel.permissionOverwrites.cache.values()].map((overwrite) => ({
+                        id: overwrite.id,
+                        type: overwrite.type,
+                        allow: overwrite.allow.bitfield,
+                        deny: overwrite.deny.bitfield,
+                    }))
+                    : [],
+                botPermissions: !obfuscated && me
+                    ? (channel.permissionsFor(me)?.bitfield ?? null)
+                    : null,
+            });
+            snapshot.fetchedChannels += 1;
+        }
+        catch (error) {
+            const code = error && typeof error === "object" && "code" in error
+                ? error.code
+                : undefined;
+            if (code === 10003 || code === "GuildChannelUnowned")
+                snapshot.invalidSelectedChannels.push({
+                    id,
+                    reason: code === 10003 ? "not_found" : "wrong_guild",
+                });
+        }
+    }
+    // Cache-only entries establish known inventory, never current permissions or deletion.
+    for (const channel of guild.channels.cache.values()) {
+        if (observedIds.has(channel.id))
+            continue;
+        snapshot.channels.push(unknownChannel(channel));
+        snapshot.totalChannelsKnown = false;
+    }
+    return channelAuditReportSchema.parse(buildChannelAuditReport(snapshot, input.moduleId, assumptions, new Date().toISOString()));
+}
+function unknownChannel(channel) {
+    return {
+        id: channel.id,
+        name: "Unknown channel",
+        type: channel.type,
+        obfuscated: true,
+        overwrites: [],
+        botPermissions: null,
+    };
+}
+//# sourceMappingURL=discord-channel-audit.js.map

package/dist/discord-guild-health.d.ts

@@ -163,8 +163,8 @@ export declare class DiscordGuildHealthInspection implements DiscordGuildHealthI
             resourceValidationValid: boolean | null;
             activationValid: boolean | null;
             catalogueMatches: boolean;
-            requiredCapabilities: readonly ("guild-members" | "message-content")[];
-            missingCapabilities: ("guild-members" | "message-content")[];
+            requiredCapabilities: readonly ("message-content" | "guild-members")[];
+            missingCapabilities: ("message-content" | "guild-members")[];
             missingPermissions: string[];
             healthStatus: "healthy" | "degraded" | "unhealthy";
             healthMessage: string | null;