@helyx/bot 0.4.46 → 0.6.1

package/dist/dashboard-module-projection.js

@@ -0,0 +1,28 @@
+import { getModuleTier } from "@helyx/module-manifest";
+import { dashboardCategoryLabel } from "./dashboard-category.js";
+import { dashboardCommands, } from "./dashboard-commands.js";
+export function mapDashboardModule(module) {
+    const dashboard = module.manifest.dashboard;
+    return {
+        id: module.manifest.id,
+        name: module.manifest.name,
+        version: module.manifest.version,
+        summary: module.manifest.description,
+        category: dashboardCategoryLabel(dashboard.category),
+        icon: dashboard.icon,
+        availability: "available",
+        releaseStatus: module.manifest.releaseStatus,
+        tier: getModuleTier(module.manifest),
+        requiredPermissions: [...module.manifest.permissions],
+        settings: dashboard.settings,
+        commands: dashboardCommands(module),
+        logEvents: (module.logging?.events ?? []).map((event) => ({ ...event })),
+        actions: (dashboard.actions ?? []).map((action) => ({ ...action })),
+        achievementTriggers: (module.manifest.contributions?.achievementTriggers ?? []).map((trigger) => structuredClone(trigger)),
+        resources: (dashboard.resources ?? []).map((resource) => structuredClone(resource)),
+        workspace: dashboard.workspace
+            ? structuredClone(dashboard.workspace)
+            : undefined,
+    };
+}
+//# sourceMappingURL=dashboard-module-projection.js.map

package/dist/discord-analytics.d.ts

@@ -0,0 +1,30 @@
+import type { DiscordAnalyticsInspectionService } from "@helyx/sdk";
+import { type Client } from "discord.js";
+export declare class DiscordAnalyticsInspection implements DiscordAnalyticsInspectionService {
+    private readonly client;
+    constructor(client: Client);
+    listChannels(input: {
+        guildId: string;
+        roleId?: string;
+    }): ReturnType<DiscordAnalyticsInspectionService["listChannels"]>;
+    listMessages(input: {
+        guildId: string;
+        channelId: string;
+        before?: string;
+        limit: number;
+    }): ReturnType<DiscordAnalyticsInspectionService["listMessages"]>;
+    listMembers(input: {
+        guildId: string;
+        after?: string;
+        limit: number;
+    }): ReturnType<DiscordAnalyticsInspectionService["listMembers"]>;
+    listThreads(input: {
+        guildId: string;
+        parentChannelId?: string;
+        cursor?: string;
+        limit: number;
+        includeArchived: boolean;
+        includePrivate: boolean;
+    }): ReturnType<DiscordAnalyticsInspectionService["listThreads"]>;
+}
+//# sourceMappingURL=discord-analytics.d.ts.map

package/dist/discord-analytics.js

@@ -0,0 +1,337 @@
+import { ChannelType, GatewayIntentBits, PermissionFlagsBits, } from "discord.js";
+const MAX_MESSAGE_PAGE = 100;
+const MAX_MEMBER_PAGE = 1_000;
+const MAX_THREAD_PAGE = 100;
+export class DiscordAnalyticsInspection {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    async listChannels(input) {
+        const guild = this.client.guilds.cache.get(input.guildId);
+        if (!guild)
+            return unavailable("discord_unavailable");
+        try {
+            const [channels, selectedRole] = await Promise.all([
+                guild.channels.fetch(),
+                input.roleId
+                    ? guild.roles.fetch(input.roleId).catch(() => null)
+                    : Promise.resolve(null),
+            ]);
+            if (input.roleId && !selectedRole)
+                return unavailable("missing_permission");
+            const items = [];
+            for (const channel of channels.values()) {
+                if (!channel)
+                    continue;
+                const type = analyticsChannelType(channel);
+                if (!type)
+                    continue;
+                const botPermissions = guild.members.me
+                    ? channel.permissionsFor(guild.members.me)
+                    : null;
+                const rolePermissions = selectedRole
+                    ? channel.permissionsFor(selectedRole)
+                    : null;
+                const threadLike = type === "forum" || type === "media";
+                items.push({
+                    channelId: channel.id,
+                    type,
+                    parentId: channel.parentId,
+                    botCanView: botPermissions?.has(PermissionFlagsBits.ViewChannel) ?? false,
+                    botCanReadHistory: botPermissions?.has(PermissionFlagsBits.ReadMessageHistory) ??
+                        false,
+                    selectedRoleCanView: selectedRole
+                        ? (rolePermissions?.has(PermissionFlagsBits.ViewChannel) ?? false)
+                        : null,
+                    selectedRoleCanWrite: selectedRole
+                        ? (rolePermissions?.has(threadLike
+                            ? PermissionFlagsBits.SendMessagesInThreads
+                            : PermissionFlagsBits.SendMessages) ?? false)
+                        : null,
+                });
+            }
+            return {
+                available: true,
+                items: items.sort((left, right) => left.channelId.localeCompare(right.channelId)),
+            };
+        }
+        catch {
+            return unavailable("discord_unavailable");
+        }
+    }
+    async listMessages(input) {
+        const limit = boundedLimit(input.limit, MAX_MESSAGE_PAGE);
+        if (!limit)
+            return unavailable("not_supported");
+        const guild = this.client.guilds.cache.get(input.guildId);
+        if (!guild)
+            return unavailable("discord_unavailable");
+        try {
+            const channel = await guild.channels.fetch(input.channelId);
+            if (!channel?.isTextBased() || !("messages" in channel))
+                return unavailable("not_supported");
+            const permissions = guild.members.me
+                ? channel.permissionsFor(guild.members.me)
+                : null;
+            if (!permissions?.has(PermissionFlagsBits.ViewChannel))
+                return unavailable("missing_permission");
+            if (!permissions.has(PermissionFlagsBits.ReadMessageHistory))
+                return unavailable("missing_permission");
+            const messages = await channel.messages.fetch({
+                limit,
+                ...(input.before ? { before: input.before } : {}),
+            });
+            const items = [...messages.values()].map((message) => ({
+                messageId: message.id,
+                createdAt: message.createdAt,
+                authorUserId: message.author?.id ?? null,
+                authorIsBot: message.author?.bot ?? false,
+                webhook: message.webhookId !== null,
+                system: message.system,
+                currentRoleIds: message.member
+                    ? [...message.member.roles.cache.keys()].sort()
+                    : null,
+            }));
+            return {
+                available: true,
+                items,
+                ...(items.length === limit
+                    ? { nextBefore: items.at(-1).messageId }
+                    : {}),
+            };
+        }
+        catch {
+            return unavailable("discord_unavailable");
+        }
+    }
+    async listMembers(input) {
+        const limit = boundedLimit(input.limit, MAX_MEMBER_PAGE);
+        if (!limit)
+            return unavailable("not_supported");
+        if (!this.client.options.intents.has(GatewayIntentBits.GuildMembers))
+            return unavailable("missing_intent");
+        const guild = this.client.guilds.cache.get(input.guildId);
+        if (!guild)
+            return unavailable("discord_unavailable");
+        try {
+            const members = await guild.members.list({
+                limit,
+                ...(input.after ? { after: input.after } : {}),
+            });
+            const items = [...members.values()].map((member) => ({
+                userId: member.id,
+                joinedAt: member.joinedAt,
+                accountCreatedAt: member.user.createdAt,
+                isBot: member.user.bot,
+                roleIds: [...member.roles.cache.keys()].sort(),
+            }));
+            return {
+                available: true,
+                items,
+                ...(items.length === limit ? { nextAfter: items.at(-1).userId } : {}),
+            };
+        }
+        catch {
+            return unavailable("discord_unavailable");
+        }
+    }
+    async listThreads(input) {
+        const limit = boundedLimit(input.limit, MAX_THREAD_PAGE);
+        if (!limit)
+            return unavailable("not_supported");
+        const guild = this.client.guilds.cache.get(input.guildId);
+        if (!guild)
+            return unavailable("discord_unavailable");
+        const cursor = decodeThreadCursor(input.cursor);
+        if (input.cursor && !cursor)
+            return unavailable("not_supported");
+        try {
+            const parents = await threadParents(guild, input.parentChannelId);
+            const privateCoverage = privateThreadCoverage(guild);
+            const current = cursor ?? { phase: "active", offset: 0 };
+            if (current.phase === "active") {
+                const active = await guild.channels.fetchActiveThreads(false);
+                const facts = [...active.threads.values()]
+                    .filter((thread) => !input.parentChannelId ||
+                    thread.parentId === input.parentChannelId)
+                    .sort((left, right) => left.id.localeCompare(right.id))
+                    .map((thread) => threadFact(guild, thread));
+                const items = facts.slice(current.offset, current.offset + limit);
+                const nextOffset = current.offset + items.length;
+                const nextCursor = nextOffset < facts.length
+                    ? encodeThreadCursor({ phase: "active", offset: nextOffset })
+                    : input.includeArchived
+                        ? encodeThreadCursor({ phase: "public", parentIndex: 0 })
+                        : undefined;
+                return {
+                    available: true,
+                    items,
+                    ...(nextCursor ? { nextCursor } : {}),
+                    privateCoverage,
+                };
+            }
+            const phases = input.includePrivate
+                ? ["public", "private"]
+                : ["public"];
+            let phaseIndex = phases.indexOf(current.phase);
+            if (phaseIndex < 0)
+                return unavailable("not_supported");
+            let parentIndex = current.parentIndex;
+            let before = current.before;
+            while (phaseIndex < phases.length) {
+                const phase = phases[phaseIndex];
+                while (parentIndex < parents.length) {
+                    const parent = parents[parentIndex];
+                    const page = await parent.threads.fetchArchived({
+                        type: phase,
+                        fetchAll: phase === "private" && privateCoverage === "all",
+                        limit,
+                        ...(before ? { before } : {}),
+                    }, false);
+                    const threads = [...page.threads.values()].sort((left, right) => left.id.localeCompare(right.id));
+                    const items = threads.map((thread) => threadFact(guild, thread));
+                    if (page.hasMore && threads.length > 0) {
+                        const oldestArchive = threads.reduce((oldest, thread) => thread.archivedAt &&
+                            (!oldest || thread.archivedAt.getTime() < oldest.getTime())
+                            ? thread.archivedAt
+                            : oldest, null);
+                        return {
+                            available: true,
+                            items,
+                            nextCursor: encodeThreadCursor({
+                                phase,
+                                parentIndex,
+                                before: oldestArchive?.toISOString() ?? threads.at(0).id,
+                            }),
+                            privateCoverage,
+                        };
+                    }
+                    parentIndex += 1;
+                    before = undefined;
+                    if (items.length > 0) {
+                        const next = nextArchiveCursor(phases, phaseIndex, parentIndex, parents.length);
+                        return {
+                            available: true,
+                            items,
+                            ...(next ? { nextCursor: encodeThreadCursor(next) } : {}),
+                            privateCoverage,
+                        };
+                    }
+                }
+                phaseIndex += 1;
+                parentIndex = 0;
+            }
+            return { available: true, items: [], privateCoverage };
+        }
+        catch {
+            return unavailable("discord_unavailable");
+        }
+    }
+}
+function analyticsChannelType(channel) {
+    switch (channel.type) {
+        case ChannelType.GuildCategory:
+            return "category";
+        case ChannelType.GuildText:
+            return "text";
+        case ChannelType.GuildAnnouncement:
+            return "announcement";
+        case ChannelType.GuildForum:
+            return "forum";
+        case ChannelType.GuildMedia:
+            return "media";
+        default:
+            return null;
+    }
+}
+async function threadParents(guild, parentChannelId) {
+    const channels = await guild.channels.fetch();
+    return [...channels.values()]
+        .filter((channel) => channel !== null &&
+        "threads" in channel &&
+        (!parentChannelId || channel.id === parentChannelId))
+        .sort((left, right) => left.id.localeCompare(right.id));
+}
+function threadFact(guild, thread) {
+    const permissions = guild.members.me
+        ? thread.permissionsFor(guild.members.me)
+        : null;
+    return {
+        threadId: thread.id,
+        parentChannelId: thread.parentId ?? "",
+        type: thread.type === ChannelType.PrivateThread
+            ? "private"
+            : thread.type === ChannelType.AnnouncementThread
+                ? "announcement"
+                : "public",
+        ownerUserId: thread.ownerId,
+        createdAt: thread.createdAt ?? new Date(snowflakeTimestamp(thread.id)),
+        lastActivityAt: thread.lastMessageId
+            ? new Date(snowflakeTimestamp(thread.lastMessageId))
+            : null,
+        archived: thread.archived ?? false,
+        locked: thread.locked ?? false,
+        messageCount: thread.messageCount ?? 0,
+        totalMessageSent: thread.totalMessageSent ?? 0,
+        appliedTagIds: "appliedTags" in thread ? [...thread.appliedTags] : [],
+        botCanView: permissions?.has(PermissionFlagsBits.ViewChannel) ?? false,
+        botCanReadHistory: permissions?.has(PermissionFlagsBits.ReadMessageHistory) ?? false,
+    };
+}
+function privateThreadCoverage(guild) {
+    const member = guild.members.me;
+    if (!member)
+        return "none";
+    return member.permissions.has(PermissionFlagsBits.ManageThreads)
+        ? "all"
+        : "joined_only";
+}
+function nextArchiveCursor(phases, phaseIndex, parentIndex, parentCount) {
+    if (parentIndex < parentCount)
+        return { phase: phases[phaseIndex], parentIndex };
+    const nextPhase = phases[phaseIndex + 1];
+    return nextPhase ? { phase: nextPhase, parentIndex: 0 } : undefined;
+}
+function encodeThreadCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+function decodeThreadCursor(value) {
+    if (!value)
+        return null;
+    try {
+        const candidate = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+        if (candidate.phase === "active")
+            return Number.isSafeInteger(candidate.offset) && candidate.offset >= 0
+                ? { phase: "active", offset: candidate.offset }
+                : null;
+        if (candidate.phase === "public" || candidate.phase === "private")
+            return Number.isSafeInteger(candidate.parentIndex) &&
+                candidate.parentIndex >= 0 &&
+                (candidate.before === undefined ||
+                    (typeof candidate.before === "string" &&
+                        candidate.before.length <= 100))
+                ? {
+                    phase: candidate.phase,
+                    parentIndex: candidate.parentIndex,
+                    ...(candidate.before ? { before: candidate.before } : {}),
+                }
+                : null;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function boundedLimit(value, maximum) {
+    return Number.isSafeInteger(value) && value >= 1 && value <= maximum
+        ? value
+        : null;
+}
+function snowflakeTimestamp(id) {
+    return Number((BigInt(id) >> 22n) + 1420070400000n);
+}
+function unavailable(code) {
+    return { available: false, code };
+}
+//# sourceMappingURL=discord-analytics.js.map

package/dist/discord-invites.d.ts

@@ -0,0 +1,24 @@
+import type { DiscordInviteInspectionService, DiscordInviteSnapshot, DiscordInviteUnavailable } from "@helyx/sdk";
+import { type Client } from "discord.js";
+export declare class DiscordInviteInspection implements DiscordInviteInspectionService {
+    #private;
+    private readonly client;
+    constructor(client: Client, fingerprintKey: Uint8Array);
+    continuityGeneration(input: {
+        guildId: string;
+    }): string;
+    invalidateContinuity(input: {
+        guildId: string;
+        reason: "event_queue_gap" | "gateway_session_gap" | "ownership_gap";
+    }): void;
+    fingerprintCode(input: {
+        guildId: string;
+        code: string;
+    }): Promise<{
+        sourceKey: string;
+    }>;
+    captureSnapshot(input: {
+        guildId: string;
+    }): Promise<DiscordInviteSnapshot | DiscordInviteUnavailable>;
+}
+//# sourceMappingURL=discord-invites.d.ts.map

package/dist/discord-invites.js

@@ -0,0 +1,91 @@
+import { PermissionFlagsBits } from "discord.js";
+import { createHmac, randomUUID } from "node:crypto";
+const VANITY_FEATURE = "VANITY_URL";
+export class DiscordInviteInspection {
+    client;
+    #processGeneration = randomUUID();
+    #guildGenerations = new Map();
+    #fingerprintKey;
+    constructor(client, fingerprintKey) {
+        this.client = client;
+        if (fingerprintKey.byteLength !== 32)
+            throw new Error("Discord invite fingerprint key must contain 32 bytes");
+        this.#fingerprintKey = Buffer.from(fingerprintKey);
+    }
+    continuityGeneration(input) {
+        const readyGeneration = this.client.readyTimestamp ?? 0;
+        const localGeneration = this.#guildGenerations.get(input.guildId) ?? 0;
+        return `${this.#processGeneration}:${readyGeneration}:${localGeneration}`;
+    }
+    invalidateContinuity(input) {
+        void input.reason;
+        this.#guildGenerations.set(input.guildId, (this.#guildGenerations.get(input.guildId) ?? 0) + 1);
+    }
+    fingerprintCode(input) {
+        const code = input.code.trim();
+        if (!/^\d{17,20}$/u.test(input.guildId))
+            return Promise.reject(new Error("Discord server ID is invalid"));
+        if (code.length < 1 || code.length > 128)
+            return Promise.reject(new Error("Discord invite code is invalid"));
+        return Promise.resolve({
+            sourceKey: this.#fingerprint(input.guildId, code),
+        });
+    }
+    async captureSnapshot(input) {
+        const guild = this.client.guilds.cache.get(input.guildId);
+        if (!guild)
+            return unavailable("discord_unavailable");
+        if (!hasManageGuild(guild))
+            return unavailable("missing_permission");
+        try {
+            const [invites, vanity] = await Promise.all([
+                guild.invites.fetch(),
+                guild.features.includes(VANITY_FEATURE)
+                    ? guild.fetchVanityData().catch(() => null)
+                    : Promise.resolve(null),
+            ]);
+            const observedAt = new Date();
+            return {
+                available: true,
+                observedAt,
+                continuityGeneration: this.continuityGeneration(input),
+                invites: [...invites.values()]
+                    .map((invite) => ({
+                    sourceKey: this.#fingerprint(guild.id, invite.code),
+                    channelId: invite.channelId,
+                    inviterUserId: invite.inviterId,
+                    createdAt: invite.createdAt,
+                    expiresAt: invite.expiresAt,
+                    maxUses: invite.maxUses ?? 0,
+                    uses: invite.uses ?? 0,
+                    temporary: invite.temporary ?? false,
+                }))
+                    .sort((left, right) => left.sourceKey.localeCompare(right.sourceKey)),
+                vanity: vanity?.code && typeof vanity.uses === "number"
+                    ? {
+                        sourceKey: this.#fingerprint(guild.id, vanity.code),
+                        uses: vanity.uses,
+                    }
+                    : null,
+            };
+        }
+        catch {
+            return unavailable("discord_unavailable");
+        }
+    }
+    #fingerprint(guildId, code) {
+        return createHmac("sha256", this.#fingerprintKey)
+            .update("helyx.discord-invite-source.v1\0", "utf8")
+            .update(guildId, "utf8")
+            .update("\0", "utf8")
+            .update(code, "utf8")
+            .digest("base64url");
+    }
+}
+function hasManageGuild(guild) {
+    return (guild.members.me?.permissions.has(PermissionFlagsBits.ManageGuild) ?? false);
+}
+function unavailable(code) {
+    return { available: false, code };
+}
+//# sourceMappingURL=discord-invites.js.map

package/dist/events.d.ts

@@ -1,7 +1,7 @@
 import type { DiscordChannelAudienceInspection, DiscordChannelInspection, DiscordEmojiInspection, DiscordMessageInspection, DiscordGuildCapabilityInspection, DiscordGuildChannelAudienceInspection, DiscordResourceInspectionService, DiscordRoleInspection, DiscordMessageService, InstallationService, MemberEnforcementService, MemberRoleService, ModuleDefinition, ServiceAccess, VerificationMemberService } from "@helyx/sdk";
 import { type Client, type MessageReaction, type PartialMessageReaction } from "discord.js";
 import { type InteractionLogger } from "./interactions.js";
-export declare function availabilityAwareInstallations(services: ServiceAccess): Pick<InstallationService, "isModuleEnabled">;
+export declare function availabilityAwareInstallations(services: ServiceAccess, modulesById?: ReadonlyMap<string, ModuleDefinition>): Pick<InstallationService, "isModuleEnabled">;
 export declare function installModuleEvents(client: Client, modules: readonly ModuleDefinition[], logger: InteractionLogger, services: ServiceAccess): ModuleEventHandle;
 export interface ModuleEventHandle {
     stop(): Promise<void>;