@helyx/module-reactionroles 1.0.14 → 1.0.17

package/dist/logging.d.ts

@@ -0,0 +1,33 @@
+export declare const reactionRoleLogging: {
+    readonly events: readonly [{
+        readonly id: "reaction-role-panel-created";
+        readonly name: "Role panel created";
+        readonly description: "A server manager created a Reaction Roles panel.";
+        readonly defaultEnabled: true;
+    }, {
+        readonly id: "reaction-role-panel-deleted";
+        readonly name: "Role panel deleted";
+        readonly description: "A server manager deleted a Reaction Roles panel.";
+        readonly defaultEnabled: true;
+    }, {
+        readonly id: "reaction-role-panel-updated";
+        readonly name: "Role panel updated";
+        readonly description: "A server manager updated a Reaction Roles panel.";
+        readonly defaultEnabled: true;
+    }, {
+        readonly id: "reaction-role-panel-reposted";
+        readonly name: "Role panel reposted";
+        readonly description: "A server manager published a replacement Reaction Roles message.";
+        readonly defaultEnabled: true;
+    }, {
+        readonly id: "reaction-role-panel-repaired";
+        readonly name: "Role panel repaired";
+        readonly description: "A server manager repaired a Reaction Roles panel.";
+        readonly defaultEnabled: true;
+    }, {
+        readonly id: "reaction-role-member-changed";
+        readonly name: "Member role changed";
+        readonly description: "A member added or removed an approved role through a panel.";
+        readonly defaultEnabled: false;
+    }];
+};

package/dist/logging.js

@@ -0,0 +1,40 @@
+export const reactionRoleLogging = {
+    events: [
+        {
+            id: "reaction-role-panel-created",
+            name: "Role panel created",
+            description: "A server manager created a Reaction Roles panel.",
+            defaultEnabled: true,
+        },
+        {
+            id: "reaction-role-panel-deleted",
+            name: "Role panel deleted",
+            description: "A server manager deleted a Reaction Roles panel.",
+            defaultEnabled: true,
+        },
+        {
+            id: "reaction-role-panel-updated",
+            name: "Role panel updated",
+            description: "A server manager updated a Reaction Roles panel.",
+            defaultEnabled: true,
+        },
+        {
+            id: "reaction-role-panel-reposted",
+            name: "Role panel reposted",
+            description: "A server manager published a replacement Reaction Roles message.",
+            defaultEnabled: true,
+        },
+        {
+            id: "reaction-role-panel-repaired",
+            name: "Role panel repaired",
+            description: "A server manager repaired a Reaction Roles panel.",
+            defaultEnabled: true,
+        },
+        {
+            id: "reaction-role-member-changed",
+            name: "Member role changed",
+            description: "A member added or removed an approved role through a panel.",
+            defaultEnabled: false,
+        },
+    ],
+};

package/dist/managed-resource.d.ts

@@ -0,0 +1,2 @@
+import type { ModuleManagedResource } from "@helyx/sdk";
+export declare const managedPanels: ModuleManagedResource;

package/dist/managed-resource.js

@@ -0,0 +1,72 @@
+import { DashboardActionValidationError } from "@helyx/sdk";
+import { randomUUID } from "node:crypto";
+import { managedContext, parseManagedDraft, toDetail, } from "./panel-service.js";
+import { reactionRolePanels as panels, runReactionRolePrimary as runPrimary, } from "./runtime-state.js";
+export const managedPanels = {
+    id: "panels",
+    list: (context, input) => runManaged(() => runPrimary(() => panels.list(context, input))),
+    read: (context, resourceId) => runManaged(() => runPrimary(() => panels.read(context, resourceId))),
+    preview: (context, value) => runManaged(() => runPrimary(() => panels.preview(context, value))),
+    async create(context, value) {
+        const panel = await runManaged(() => runPrimary(() => panels.create(managedContext(context), parseManagedDraft(value))));
+        return toDetail(panel);
+    },
+    async update(context, input) {
+        const panel = await runManaged(() => runPrimary(() => panels.update(managedContext(context), {
+            resourceId: input.resourceId,
+            expectedRevision: input.expectedRevision,
+            draft: parseManagedDraft(input.value),
+        })));
+        return toDetail(panel);
+    },
+    delete: (context, input) => runManaged(() => runPrimary(() => panels.delete(managedContext(context), input.resourceId, input.expectedRevision)).then((deleted) => ({ deleted }))),
+    executeAction: (context, input) => runManaged(async () => {
+        if (input.actionId === "duplicate") {
+            return runPrimary(async () => {
+                const current = await panels
+                    .repository(context.services)
+                    .findById(context.guildId, input.resourceId);
+                if (!current)
+                    throw new DashboardActionValidationError("Role panel was not found");
+                if (current.revision !== input.expectedRevision)
+                    throw new DashboardActionValidationError("This role panel changed in another session. Reload and try again.");
+                return toDetail(await panels.create(managedContext(context), {
+                    channelId: current.channelId,
+                    title: current.title,
+                    messageBody: current.messageBody,
+                    messageStyle: current.messageStyle,
+                    controlType: current.controlType,
+                    selectionMode: current.selectionMode,
+                    persistentReactions: current.persistentReactions,
+                    ...(current.embedColour === undefined
+                        ? {}
+                        : { embedColour: current.embedColour }),
+                    ...(current.dropdownPlaceholder === undefined
+                        ? {}
+                        : { dropdownPlaceholder: current.dropdownPlaceholder }),
+                    entries: current.entries.map((entry) => ({
+                        ...entry,
+                        entryId: `entry-${randomUUID().replaceAll("-", "")}`,
+                    })),
+                }));
+            });
+        }
+        if (input.actionId === "delete") {
+            await runPrimary(() => panels.delete(managedContext(context), input.resourceId, input.expectedRevision));
+            return null;
+        }
+        if (input.actionId !== "repair" && input.actionId !== "repost")
+            throw new DashboardActionValidationError("This Reaction Roles action is not supported.");
+        return toDetail(await runPrimary(() => panels.repair(managedContext(context), input.resourceId, input.expectedRevision, input.actionId === "repost")));
+    }),
+};
+async function runManaged(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        if (error instanceof DashboardActionValidationError)
+            throw error;
+        throw new DashboardActionValidationError("Reaction Roles is temporarily unavailable. Reload the current state before retrying.");
+    }
+}

package/dist/member-interactions.d.ts

@@ -0,0 +1,27 @@
+import type { ButtonContribution, MessageReactionAddContext, MessageReactionRemoveContext, MessageResponse, SelectInteractionContext, ServiceAccess } from "@helyx/sdk";
+import type { StoredPanel } from "./records.js";
+export declare function toggleSlot(context: Parameters<ButtonContribution["execute"]>[0], index: number): Promise<void>;
+export declare function reconcileSelection(context: SelectInteractionContext): Promise<void>;
+export declare function removeAllPanelRoles(context: Parameters<ButtonContribution["execute"]>[0]): Promise<void>;
+export declare function handleReactionAdd(context: MessageReactionAddContext): Promise<void>;
+export declare function handleReactionRemove(context: MessageReactionRemoveContext): Promise<void>;
+export declare function activePanelForInteraction(context: {
+    serverId?: string;
+    messageId?: string;
+    services: ServiceAccess;
+}): Promise<{
+    guildId: string;
+    panel: StoredPanel;
+}>;
+export declare function consumeMemberLimit(services: ServiceAccess, guildId: string, userId: string): Promise<void>;
+export declare function withMemberLock(guildId: string, panelId: string, userId: string, operation: () => Promise<void>): Promise<void>;
+export declare function memberOutcome(nameplate: string, changed: "added" | "removed"): MessageResponse;
+export declare function roleFailure(context: {
+    services: ServiceAccess;
+    reply(response: MessageResponse): Promise<void>;
+}, panel: StoredPanel): Promise<void>;
+export declare function emitMemberChanges(services: ServiceAccess, guildId: string, memberUserId: string, panelId: string, changes: readonly {
+    roleId: string;
+    outcome: "added" | "removed";
+}[]): Promise<void>;
+export declare function canonicalEmojiKey(value: string): string;

package/dist/member-interactions.js

@@ -0,0 +1,360 @@
+import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
+import { REACTION_ROLES_MODULE_ID } from "./constants.js";
+import { reactionRoleMemberLocks as memberLocks, reactionRoleHealth as moduleHealth, reactionRolePanels as panels, } from "./runtime-state.js";
+import { stalePanelReply } from "./builder-presentation.js";
+export async function toggleSlot(context, index) {
+    const { guildId, panel } = await activePanelForInteraction(context);
+    const entry = panel.entries[index];
+    if (!entry)
+        return stalePanelReply(context);
+    await consumeMemberLimit(context.services, guildId, context.userId);
+    let changed = "removed";
+    try {
+        await withMemberLock(guildId, panel.panelId, context.userId, async () => {
+            const roles = context.services.get(HELYX_SERVICE_NAMES.memberRoles);
+            const current = new Set(await roles.getCurrentRoleIds({
+                guildId,
+                memberUserId: context.userId,
+            }));
+            const changes = [];
+            if (panel.selectionMode === "one_only") {
+                const desired = current.has(entry.roleId) ? [] : [entry.roleId];
+                const result = await roles.reconcileApprovedRoles({
+                    guildId,
+                    memberUserId: context.userId,
+                    allowedRoleIds: panel.entries.map(({ roleId }) => roleId),
+                    desiredRoleIds: desired,
+                    moduleId: REACTION_ROLES_MODULE_ID,
+                    reason: `Reaction Roles panel ${panel.panelId}`,
+                });
+                changes.push(...result.added.map((roleId) => ({
+                    roleId,
+                    outcome: "added",
+                })), ...result.removed.map((roleId) => ({
+                    roleId,
+                    outcome: "removed",
+                })));
+                changed = result.added.includes(entry.roleId) ? "added" : "removed";
+            }
+            else if (current.has(entry.roleId)) {
+                await roles.removeApprovedRole({
+                    guildId,
+                    memberUserId: context.userId,
+                    roleId: entry.roleId,
+                    moduleId: REACTION_ROLES_MODULE_ID,
+                    reason: `Reaction Roles panel ${panel.panelId}`,
+                });
+                changed = "removed";
+                changes.push({ roleId: entry.roleId, outcome: changed });
+            }
+            else {
+                await roles.addApprovedRole({
+                    guildId,
+                    memberUserId: context.userId,
+                    roleId: entry.roleId,
+                    moduleId: REACTION_ROLES_MODULE_ID,
+                    reason: `Reaction Roles panel ${panel.panelId}`,
+                });
+                changed = "added";
+                changes.push({ roleId: entry.roleId, outcome: changed });
+            }
+            await emitMemberChanges(context.services, guildId, context.userId, panel.panelId, changes);
+        });
+    }
+    catch {
+        moduleHealth.primaryFailure("member");
+        await roleFailure(context, panel);
+        return;
+    }
+    moduleHealth.primarySuccess("member");
+    await context.reply(memberOutcome(entry.nameplate, changed));
+}
+export async function reconcileSelection(context) {
+    const { guildId, panel } = await activePanelForInteraction(context);
+    if (panel.controlType !== "dropdown")
+        return stalePanelReply(context);
+    await consumeMemberLimit(context.services, guildId, context.userId);
+    const selected = new Set(context.selectedValues);
+    const desired = panel.entries
+        .filter(({ entryId }) => selected.has(entryId))
+        .map(({ roleId }) => roleId);
+    if (selected.size !== desired.length ||
+        (panel.selectionMode === "one_only" && desired.length > 1))
+        return stalePanelReply(context);
+    let added = 0;
+    let removed = 0;
+    try {
+        await withMemberLock(guildId, panel.panelId, context.userId, async () => {
+            const result = await context.services
+                .get(HELYX_SERVICE_NAMES.memberRoles)
+                .reconcileApprovedRoles({
+                guildId,
+                memberUserId: context.userId,
+                allowedRoleIds: panel.entries.map(({ roleId }) => roleId),
+                desiredRoleIds: desired,
+                moduleId: REACTION_ROLES_MODULE_ID,
+                reason: `Reaction Roles panel ${panel.panelId}`,
+            });
+            added = result.added.length;
+            removed = result.removed.length;
+            await emitMemberChanges(context.services, guildId, context.userId, panel.panelId, [
+                ...result.added.map((roleId) => ({
+                    roleId,
+                    outcome: "added",
+                })),
+                ...result.removed.map((roleId) => ({
+                    roleId,
+                    outcome: "removed",
+                })),
+            ]);
+        });
+    }
+    catch {
+        moduleHealth.primaryFailure("member");
+        await roleFailure(context, panel);
+        return;
+    }
+    moduleHealth.primarySuccess("member");
+    await context.reply({
+        ephemeral: true,
+        componentsV2: {
+            text: [
+                {
+                    content: `Your panel roles were updated: ${added} added, ${removed} removed.`,
+                },
+            ],
+        },
+    });
+}
+export async function removeAllPanelRoles(context) {
+    const { guildId, panel } = await activePanelForInteraction(context);
+    await consumeMemberLimit(context.services, guildId, context.userId);
+    let removed = [];
+    try {
+        await withMemberLock(guildId, panel.panelId, context.userId, async () => {
+            const result = await context.services
+                .get(HELYX_SERVICE_NAMES.memberRoles)
+                .reconcileApprovedRoles({
+                guildId,
+                memberUserId: context.userId,
+                allowedRoleIds: panel.entries.map(({ roleId }) => roleId),
+                desiredRoleIds: [],
+                moduleId: REACTION_ROLES_MODULE_ID,
+                reason: `Reaction Roles panel ${panel.panelId}`,
+            });
+            removed = result.removed;
+            await emitMemberChanges(context.services, guildId, context.userId, panel.panelId, result.removed.map((roleId) => ({
+                roleId,
+                outcome: "removed",
+            })));
+        });
+    }
+    catch {
+        moduleHealth.primaryFailure("member");
+        await roleFailure(context, panel);
+        return;
+    }
+    moduleHealth.primarySuccess("member");
+    await context.reply({
+        ephemeral: true,
+        componentsV2: {
+            text: [
+                {
+                    content: removed.length === 0
+                        ? "You did not have any roles from this panel."
+                        : `${removed.length} panel ${removed.length === 1 ? "role was" : "roles were"} removed.`,
+                },
+            ],
+        },
+    });
+}
+export async function handleReactionAdd(context) {
+    if (context.reactionType !== "normal")
+        return;
+    const panel = await panels.resolveActive(context.serverId, context.messageId, context.services);
+    if (!panel || panel.controlType !== "reactions")
+        return;
+    const entry = panel.entries.find((candidate) => candidate.emoji &&
+        canonicalEmojiKey(candidate.emoji) === context.emojiKey);
+    if (!entry)
+        return;
+    const changes = [];
+    try {
+        await withMemberLock(context.serverId, panel.panelId, context.userId, async () => {
+            const roles = context.services.get(HELYX_SERVICE_NAMES.memberRoles);
+            if (panel.selectionMode === "one_only") {
+                const result = await roles.reconcileApprovedRoles({
+                    guildId: context.serverId,
+                    memberUserId: context.userId,
+                    allowedRoleIds: panel.entries.map(({ roleId }) => roleId),
+                    desiredRoleIds: [entry.roleId],
+                    moduleId: REACTION_ROLES_MODULE_ID,
+                    reason: `Reaction Roles panel ${panel.panelId}`,
+                });
+                changes.push(...result.added.map((roleId) => ({
+                    roleId,
+                    outcome: "added",
+                })), ...result.removed.map((roleId) => ({
+                    roleId,
+                    outcome: "removed",
+                })));
+                return;
+            }
+            const result = await roles.addApprovedRole({
+                guildId: context.serverId,
+                memberUserId: context.userId,
+                roleId: entry.roleId,
+                moduleId: REACTION_ROLES_MODULE_ID,
+                reason: `Reaction Roles panel ${panel.panelId}`,
+            });
+            if (result.changed)
+                changes.push({ roleId: entry.roleId, outcome: "added" });
+        });
+        await emitMemberChanges(context.services, context.serverId, context.userId, panel.panelId, changes);
+        moduleHealth.primarySuccess("member");
+    }
+    catch {
+        moduleHealth.primaryFailure("member");
+        await panels.markNeedsAttention(panel, context.services).catch(() => false);
+        await context.removeAddedReaction().catch(() => undefined);
+        return;
+    }
+    if (!panel.persistentReactions) {
+        try {
+            await context.removeAddedReaction();
+        }
+        catch {
+            await panels
+                .markNeedsAttention(panel, context.services)
+                .catch(() => false);
+        }
+    }
+}
+export async function handleReactionRemove(context) {
+    if (context.reactionType !== "normal")
+        return;
+    const panel = await panels.resolveActive(context.serverId, context.messageId, context.services);
+    if (!panel || panel.controlType !== "reactions" || !panel.persistentReactions)
+        return;
+    const entry = panel.entries.find((candidate) => candidate.emoji &&
+        canonicalEmojiKey(candidate.emoji) === context.emojiKey);
+    if (!entry)
+        return;
+    try {
+        await withMemberLock(context.serverId, panel.panelId, context.userId, () => context.services
+            .get(HELYX_SERVICE_NAMES.memberRoles)
+            .removeApprovedRole({
+            guildId: context.serverId,
+            memberUserId: context.userId,
+            roleId: entry.roleId,
+            moduleId: REACTION_ROLES_MODULE_ID,
+            reason: `Reaction Roles panel ${panel.panelId}`,
+        })
+            .then(() => undefined));
+        await emitMemberChanges(context.services, context.serverId, context.userId, panel.panelId, [{ roleId: entry.roleId, outcome: "removed" }]);
+        moduleHealth.primarySuccess("member");
+    }
+    catch {
+        moduleHealth.primaryFailure("member");
+        await panels.markNeedsAttention(panel, context.services).catch(() => false);
+    }
+}
+export async function activePanelForInteraction(context) {
+    const guildId = context.serverId;
+    if (!guildId || !context.messageId)
+        throw new Error("Server panel required");
+    let panel;
+    try {
+        panel = await panels.resolveActive(guildId, context.messageId, context.services);
+    }
+    catch (error) {
+        moduleHealth.primaryFailure("member");
+        throw error;
+    }
+    if (!panel)
+        throw new Error("Role panel is no longer active");
+    return { guildId, panel };
+}
+export async function consumeMemberLimit(services, guildId, userId) {
+    let result;
+    try {
+        result = await services
+            .get(HELYX_SERVICE_NAMES.rateLimits)
+            .consume({
+            scope: "user",
+            subjectId: userId,
+            action: `${REACTION_ROLES_MODULE_ID}:${guildId}:member-role`,
+            limit: 10,
+            windowSeconds: 10,
+        });
+    }
+    catch (error) {
+        moduleHealth.primaryFailure("member");
+        throw error;
+    }
+    if (!result.allowed)
+        throw new Error("Role panel rate limit reached");
+}
+export async function withMemberLock(guildId, panelId, userId, operation) {
+    const key = `${guildId}:${panelId}:${userId}`;
+    const previous = memberLocks.get(key) ?? Promise.resolve();
+    const current = previous.catch(() => undefined).then(operation);
+    memberLocks.set(key, current);
+    try {
+        await current;
+    }
+    finally {
+        if (memberLocks.get(key) === current)
+            memberLocks.delete(key);
+    }
+}
+export function memberOutcome(nameplate, changed) {
+    return {
+        ephemeral: true,
+        componentsV2: {
+            text: [
+                {
+                    content: `${nameplate} was ${changed === "added" ? "added to" : "removed from"} your roles.`,
+                },
+            ],
+        },
+        allowedUserMentionIds: [],
+    };
+}
+export async function roleFailure(context, panel) {
+    await panels.markNeedsAttention(panel, context.services).catch(() => false);
+    await context.reply({
+        ephemeral: true,
+        componentsV2: {
+            text: [
+                {
+                    content: "Helyx cannot manage that role right now. A server administrator needs to check the Reaction Roles panel.",
+                },
+            ],
+        },
+        allowedUserMentionIds: [],
+    });
+}
+export async function emitMemberChanges(services, guildId, memberUserId, panelId, changes) {
+    if (changes.length === 0 || !services.has(HELYX_SERVICE_NAMES.moduleLogging))
+        return;
+    const logging = services.get(HELYX_SERVICE_NAMES.moduleLogging);
+    await Promise.all(changes.slice(0, 25).map(({ roleId, outcome }) => logging
+        .emit({
+        guildId,
+        moduleId: REACTION_ROLES_MODULE_ID,
+        eventId: "reaction-role-member-changed",
+        summary: "A member changed an approved Reaction Roles role.",
+        details: [
+            { label: "Member ID", value: memberUserId },
+            { label: "Panel", value: panelId },
+            { label: "Role ID", value: roleId },
+            { label: "Outcome", value: outcome },
+        ],
+    })
+        .catch(() => ({ delivered: false }))));
+}
+export function canonicalEmojiKey(value) {
+    const custom = /^([A-Za-z0-9_]{2,32}):(\d{17,20})$/u.exec(value);
+    return custom ? `custom:${custom[2]}` : `unicode:${value.normalize("NFKC")}`;
+}

package/dist/module-lifecycle.d.ts

@@ -0,0 +1,3 @@
+import type { RuntimeContext } from "@helyx/sdk";
+export declare function startReactionRoles(context: RuntimeContext): Promise<void>;
+export declare function stopReactionRoles(context: RuntimeContext): Promise<void>;

package/dist/module-lifecycle.js

@@ -0,0 +1,48 @@
+import { reactionRoleCache as cache, reactionRoleHealth as health, reactionRoleMemberLocks as memberLocks, reactionRolePanels as panels, } from "./runtime-state.js";
+export async function startReactionRoles(context) {
+    health.start(context);
+    let cleanup = { completed: 0, failed: 0, abandoned: 0 };
+    let cleanupRecoveryFailed = false;
+    try {
+        cleanup = await panels.recoverMessageCleanup(context.services);
+    }
+    catch {
+        cleanupRecoveryFailed = true;
+        context.logger.warn({
+            event: "reactionroles.cleanup_recovery_failed",
+            reason: "owned_message_cleanup_unavailable",
+        }, "Reaction Roles could not reconcile old owned messages");
+    }
+    let count = 0;
+    let cacheWarmFailed = false;
+    try {
+        count = await panels.warm(context.services);
+    }
+    catch {
+        cacheWarmFailed = true;
+        context.logger.warn({
+            event: "reactionroles.cache_load_failed",
+            reason: "active_panel_preload_unavailable",
+        }, "Reaction Roles started without its active cache");
+    }
+    health.startupResult({
+        cacheWarmFailed,
+        cacheSaturated: cache.saturated(),
+        cleanupFailures: cleanup.failed + cleanup.abandoned + (cleanupRecoveryFailed ? 1 : 0),
+    });
+    context.logger.info({
+        event: "reactionroles.started",
+        activePanelCount: count,
+        cleanupCompleted: cleanup.completed,
+        cleanupFailed: cleanup.failed,
+        cleanupAbandoned: cleanup.abandoned,
+        cleanupRecoveryFailed,
+    }, "Reaction Roles started");
+}
+export function stopReactionRoles(context) {
+    cache.clear();
+    memberLocks.clear();
+    health.stop();
+    context.logger.info({ event: "reactionroles.stopped" }, "Reaction Roles stopped");
+    return Promise.resolve();
+}

package/dist/panel-cache.d.ts

@@ -0,0 +1,30 @@
+import type { StoredPanel } from "./records.js";
+export declare const PANEL_CACHE_LIMITS: {
+    readonly active: 10000;
+    readonly negative: 1000;
+    readonly loads: 1000;
+    readonly activeTtlMs: 60000;
+    readonly negativeTtlMs: 15000;
+};
+export interface PanelCacheStats {
+    active: number;
+    negative: number;
+    loads: number;
+    suspended: number;
+    saturated: boolean;
+}
+export declare class PanelSnapshotCache {
+    #private;
+    get(guildId: string, messageId: string): StoredPanel | null;
+    getFresh(guildId: string, messageId: string): StoredPanel | null;
+    negativeHit(guildId: string, messageId: string): boolean;
+    markMissing(guildId: string, messageId: string): void;
+    load(guildId: string, messageId: string, operation: () => Promise<StoredPanel | null>): Promise<StoredPanel | null>;
+    put(panel: StoredPanel): void;
+    remove(panel: Pick<StoredPanel, "guildId" | "messageId">): void;
+    suspend(panel: Pick<StoredPanel, "guildId" | "messageId">): (replacement?: StoredPanel | null) => void;
+    clear(): void;
+    size(): number;
+    saturated(): boolean;
+    stats(): PanelCacheStats;
+}