@helyx/module-reactionroles 1.0.1

package/README.md

@@ -0,0 +1,53 @@
+# Reaction Roles module
+
+Reaction Roles lets server managers publish Helyx-owned panels from Discord or
+the dashboard. Members can select only the approved roles on each panel using
+buttons, a dropdown or emoji reactions.
+
+Reaction messages include an automatically generated emoji-to-role key.
+Persistent reactions are enabled by default, so adding and removing a reaction
+synchronises the mapped role. Managers can turn persistence off so Helyx
+assigns the role and removes only the member's reaction. Non-persistent panels
+also support one-role-only reconciliation.
+
+The module validates role ownership, hierarchy and dangerous permissions before
+publication and again before a role changes. Discord remains the source of
+truth for membership: Helyx does not store member selections, click history or
+reaction history.
+
+## Permissions
+
+Helyx needs View Channel, Send Messages and Manage Roles. Embed panels also
+need Embed Links. Emoji-reaction panels need Read Message History and Add
+Reactions. Non-persistent emoji panels additionally need Manage Messages so
+Helyx can remove the reacting member's reaction. The module never requests
+Administrator or Message Content.
+
+## Stored data
+
+Helyx stores panel and entry configuration, the Helyx-owned Discord message
+reference, lifecycle status, revision and privacy-detachable creator/updater
+IDs. It does not store lists of members holding a role.
+
+This package remains in Testing until its automated and controlled Discord
+acceptance gates have passed.
+
+## Operator runbook
+
+Before Beta, enable the Testing package in one dedicated guild and apply its
+guarded migration through the normal Helyx migration runner. Confirm module
+health is healthy, create one panel of each control type through both the
+dashboard and Discord, restart the shard worker, and verify the panels still
+respond.
+
+If a role, channel, emoji or owned message is removed, the panel should become
+`needs_attention` or `message_missing`. Correct the Discord resource and use
+the module's Repair or Repost action. A `cleanup_pending` panel remains safe to
+use while Helyx retries deletion of the old owned message. Repeated or
+abandoned cleanup failures are an operator alert and must be investigated
+before promotion.
+
+Disabling the module stops its interactions without deleting configuration.
+Re-enable only after current channel permissions, role hierarchy and emoji
+availability have been checked. Rollback may restore compatible application
+code, but must not reverse the migration or delete panel data.

package/dist/builder.d.ts

@@ -0,0 +1,38 @@
+import type { MessageBuilderDraft } from "@helyx/sdk";
+import { PANEL_LIMITS } from "./constants.js";
+export type PanelControlType = keyof typeof PANEL_LIMITS;
+export type PanelMessageStyle = "text" | "embed";
+export type PanelSelectionMode = "multiple" | "one_only";
+export type PanelButtonStyle = "primary" | "secondary" | "success" | "danger";
+export interface PanelEntryDraft {
+    entryId: string;
+    roleId: string;
+    nameplate: string;
+    emoji?: string;
+    buttonStyle?: PanelButtonStyle;
+}
+export interface PanelDraft {
+    channelId: string;
+    title: string;
+    messageBody: string;
+    messageStyle: PanelMessageStyle;
+    controlType: PanelControlType;
+    selectionMode: PanelSelectionMode;
+    persistentReactions: boolean;
+    embedColour?: number;
+    dropdownPlaceholder?: string;
+    entries: readonly PanelEntryDraft[];
+}
+export interface CanonicalEmoji {
+    kind: "unicode" | "custom";
+    name: string;
+    id?: string;
+    animated: boolean;
+    identifier: string;
+    key: string;
+}
+export declare function validatePanelDraft(input: PanelDraft, options?: {
+    allowEmptyEntries?: boolean;
+}): PanelDraft;
+export declare function panelMessageDraft(input: PanelDraft): MessageBuilderDraft;
+export declare function canonicaliseEmoji(input: string): CanonicalEmoji;

package/dist/builder.js

@@ -0,0 +1,206 @@
+import { COMPONENT_IDS, PANEL_LIMITS } from "./constants.js";
+export function validatePanelDraft(input, options = {}) {
+    const channelId = snowflake(input.channelId, "Destination channel");
+    const title = boundedText(input.title, "Title", 80);
+    const messageBody = boundedText(input.messageBody, "Message", 1_000);
+    if (!["text", "embed"].includes(input.messageStyle))
+        throw new Error("Choose Text or Embed for the message style");
+    if (!["buttons", "dropdown", "reactions"].includes(input.controlType))
+        throw new Error("Choose Buttons, Dropdown or Emoji reactions");
+    if (!["multiple", "one_only"].includes(input.selectionMode))
+        throw new Error("Choose a valid selection mode");
+    const persistentReactions = input.persistentReactions === undefined ? true : input.persistentReactions;
+    if (typeof persistentReactions !== "boolean")
+        throw new Error("Choose whether member reactions remain on the panel");
+    if (input.controlType === "reactions" &&
+        input.selectionMode === "one_only" &&
+        persistentReactions)
+        throw new Error("Turn off Persistent reactions to use one role only with emoji reactions");
+    const maximum = PANEL_LIMITS[input.controlType];
+    const minimum = options.allowEmptyEntries === true ? 0 : 1;
+    if (input.entries.length < minimum || input.entries.length > maximum)
+        throw new Error(`${controlLabel(input.controlType)} panels require between 1 and ${maximum} role entries`);
+    const roleIds = new Set();
+    const emojiKeys = new Set();
+    const entryIds = new Set();
+    const entries = input.entries.map((entry) => {
+        const entryId = boundedIdentifier(entry.entryId, "Entry");
+        if (entryIds.has(entryId))
+            throw new Error("Role entries must be unique");
+        entryIds.add(entryId);
+        const roleId = snowflake(entry.roleId, "Role");
+        if (roleIds.has(roleId))
+            throw new Error("Each Discord role can appear only once");
+        roleIds.add(roleId);
+        const nameplate = boundedText(entry.nameplate, "Role label", 80);
+        const emoji = entry.emoji?.trim()
+            ? canonicaliseEmoji(entry.emoji)
+            : undefined;
+        if (input.controlType === "reactions" && !emoji)
+            throw new Error("Every emoji-reaction entry needs an emoji");
+        if (emoji && input.controlType === "reactions") {
+            if (emojiKeys.has(emoji.key))
+                throw new Error("Each reaction emoji can appear only once");
+            emojiKeys.add(emoji.key);
+        }
+        const buttonStyle = entry.buttonStyle ?? "secondary";
+        if (!["primary", "secondary", "success", "danger"].includes(buttonStyle))
+            throw new Error("Choose a valid button colour");
+        return {
+            entryId,
+            roleId,
+            nameplate,
+            ...(emoji ? { emoji: emoji.identifier } : {}),
+            ...(input.controlType === "buttons" ? { buttonStyle } : {}),
+        };
+    });
+    const embedColour = input.embedColour === undefined ? 0x7c3aed : input.embedColour;
+    if (!Number.isInteger(embedColour) ||
+        embedColour < 0 ||
+        embedColour > 0xffffff)
+        throw new Error("Embed colour must be between 0 and 16777215");
+    const dropdownPlaceholder = input.dropdownPlaceholder?.trim()
+        ? boundedText(input.dropdownPlaceholder, "Dropdown label", 100)
+        : "Choose your roles";
+    return {
+        channelId,
+        title,
+        messageBody,
+        messageStyle: input.messageStyle,
+        controlType: input.controlType,
+        selectionMode: input.selectionMode,
+        persistentReactions,
+        ...(input.messageStyle === "embed" ? { embedColour } : {}),
+        ...(input.controlType === "dropdown" ? { dropdownPlaceholder } : {}),
+        entries,
+    };
+}
+export function panelMessageDraft(input) {
+    const panel = validatePanelDraft(input);
+    const body = panel.controlType === "reactions"
+        ? `${panel.messageBody}\n\n${panel.entries
+            .map((entry) => `${displayEmoji(entry.emoji)} — <@&${entry.roleId}>`)
+            .join("\n")}`
+        : panel.messageBody;
+    const presentation = panel.messageStyle === "embed"
+        ? {
+            type: "embed",
+            title: panel.title,
+            body,
+            ...(panel.embedColour === undefined
+                ? {}
+                : { color: panel.embedColour }),
+        }
+        : {
+            type: "text",
+            title: panel.title,
+            body,
+            accentColor: 0x7c3aed,
+        };
+    const allowedUserMentionIds = [];
+    if (panel.controlType === "buttons") {
+        return {
+            presentation,
+            allowedUserMentionIds,
+            buttons: panel.entries.map((entry, index) => ({
+                customId: COMPONENT_IDS.slots[index],
+                label: entry.nameplate,
+                style: entry.buttonStyle ?? "secondary",
+                ...(entry.emoji
+                    ? { emojiIdentifier: canonicaliseEmoji(entry.emoji).identifier }
+                    : {}),
+            })),
+        };
+    }
+    if (panel.controlType === "dropdown") {
+        return {
+            presentation,
+            allowedUserMentionIds,
+            selects: [
+                {
+                    customId: COMPONENT_IDS.select,
+                    placeholder: panel.dropdownPlaceholder ?? "Choose your roles",
+                    minValues: 0,
+                    maxValues: panel.selectionMode === "one_only" ? 1 : panel.entries.length,
+                    options: panel.entries.map((entry) => ({
+                        label: entry.nameplate,
+                        value: entry.entryId,
+                        ...(entry.emoji
+                            ? { emojiIdentifier: canonicaliseEmoji(entry.emoji).identifier }
+                            : {}),
+                    })),
+                },
+            ],
+            buttons: [
+                {
+                    customId: COMPONENT_IDS.removeAll,
+                    label: "Remove my panel roles",
+                    style: "secondary",
+                },
+            ],
+        };
+    }
+    return {
+        presentation,
+        reactionIdentifiers: panel.entries.map((entry) => canonicaliseEmoji(entry.emoji).identifier),
+        allowedUserMentionIds,
+    };
+}
+function displayEmoji(input) {
+    const emoji = canonicaliseEmoji(input);
+    return emoji.id ? `<:${emoji.name}:${emoji.id}>` : emoji.name;
+}
+export function canonicaliseEmoji(input) {
+    const value = input.trim().normalize("NFKC");
+    const mention = /^<(a?):([A-Za-z0-9_]{2,32}):(\d{17,20})>$/u.exec(value);
+    const identifier = /^([A-Za-z0-9_]{2,32}):(\d{17,20})$/u.exec(value);
+    if (mention || identifier) {
+        const animated = mention?.[1] === "a";
+        const name = mention?.[2] ?? identifier[1];
+        const id = mention?.[3] ?? identifier[2];
+        return {
+            kind: "custom",
+            name,
+            id,
+            animated,
+            identifier: `${name}:${id}`,
+            key: `custom:${id}`,
+        };
+    }
+    if (value.length === 0 ||
+        value.length > 32 ||
+        /^[\p{L}\p{N}\s.,!?_-]+$/u.test(value))
+        throw new Error("Enter one Unicode emoji or a custom server emoji");
+    return {
+        kind: "unicode",
+        name: value,
+        animated: false,
+        identifier: value,
+        key: `unicode:${value}`,
+    };
+}
+function boundedText(input, label, maximum) {
+    const value = input.trim().normalize("NFC");
+    if (value.length < 1 || value.length > maximum)
+        throw new Error(`${label} must be between 1 and ${maximum} characters`);
+    return value;
+}
+function snowflake(input, label) {
+    const value = input.trim();
+    if (!/^\d{17,20}$/u.test(value))
+        throw new Error(`${label} is not a valid Discord resource`);
+    return value;
+}
+function boundedIdentifier(input, label) {
+    const value = input.trim();
+    if (!/^[A-Za-z0-9_-]{1,100}$/u.test(value))
+        throw new Error(`${label} identifier is invalid`);
+    return value;
+}
+function controlLabel(type) {
+    return {
+        buttons: "Button",
+        dropdown: "Dropdown",
+        reactions: "Emoji-reaction",
+    }[type];
+}

package/dist/constants.d.ts

@@ -0,0 +1,22 @@
+export declare const MODULE_ID = "helyx.reactionroles";
+export declare const PANEL_PURPOSE = "helyx.reactionroles.builder";
+export declare const COMPONENT_IDS: {
+    readonly addEntry: "helyx.reactionroles.builder.add-entry";
+    readonly continueDraft: "helyx.reactionroles.builder.continue";
+    readonly replaceDraft: "helyx.reactionroles.builder.replace";
+    readonly keepDraft: "helyx.reactionroles.builder.keep";
+    readonly publish: "helyx.reactionroles.builder.publish";
+    readonly cancel: "helyx.reactionroles.builder.cancel";
+    readonly deleteConfirm: "helyx.reactionroles.delete.confirm";
+    readonly basicModal: "helyx.reactionroles.builder.basic";
+    readonly entryModal: "helyx.reactionroles.builder.entry";
+    readonly builderEntries: "helyx.reactionroles.builder.entries";
+    readonly select: "helyx.reactionroles.select";
+    readonly removeAll: "helyx.reactionroles.remove-all";
+    readonly slots: string[];
+};
+export declare const PANEL_LIMITS: {
+    readonly buttons: 5;
+    readonly dropdown: 25;
+    readonly reactions: 20;
+};

package/dist/constants.js

@@ -0,0 +1,22 @@
+export const MODULE_ID = "helyx.reactionroles";
+export const PANEL_PURPOSE = "helyx.reactionroles.builder";
+export const COMPONENT_IDS = {
+    addEntry: "helyx.reactionroles.builder.add-entry",
+    continueDraft: "helyx.reactionroles.builder.continue",
+    replaceDraft: "helyx.reactionroles.builder.replace",
+    keepDraft: "helyx.reactionroles.builder.keep",
+    publish: "helyx.reactionroles.builder.publish",
+    cancel: "helyx.reactionroles.builder.cancel",
+    deleteConfirm: "helyx.reactionroles.delete.confirm",
+    basicModal: "helyx.reactionroles.builder.basic",
+    entryModal: "helyx.reactionroles.builder.entry",
+    builderEntries: "helyx.reactionroles.builder.entries",
+    select: "helyx.reactionroles.select",
+    removeAll: "helyx.reactionroles.remove-all",
+    slots: Array.from({ length: 5 }, (_, index) => `helyx.reactionroles.slot.${index + 1}`),
+};
+export const PANEL_LIMITS = {
+    buttons: 5,
+    dropdown: 25,
+    reactions: 20,
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export declare const reactionRolesModule: import("@helyx/sdk").ModuleDefinition;
+export default reactionRolesModule;