@helyx/module-reactionroles 1.0.15 → 1.0.17

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @helyx/module-reactionroles
 
+## 1.0.17
+
+### Patch Changes
+
+- Updated dependencies [bbc4eee]
+  - @helyx/sdk@0.10.0
+
+## 1.0.16
+
+### Patch Changes
+
+- Add declared command-operation permission targets, project them through both permission-management surfaces, and harden module lifecycle, health, visibility, bounded-work, optional-side-effect, command-permission, and Forms durable-workflow behavior. Preserve existing FAQ, Access Control, Achievements, Giveaways and Levels overrides through additive migrations while assigning every slash-command path its own permission identity.
+
 ## 1.0.15
 
 ### Patch Changes

package/README.md

@@ -1,53 +1,37 @@
-# 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.
+# @helyx/module-reactionroles
+
+Reaction Roles publishes Helyx-owned panels that let members assign approved Discord roles to themselves.
+
+## Availability and deployment
+
+Reaction Roles is a **Live** module for Helyx-hosted and self-hosted deployments. Its migrations are additive and must be applied through the normal Helyx migration runner before the module starts.
+
+## What it does
+
+Server managers create button, dropdown, or emoji-reaction panels through the dashboard. Panels support multiple-role and one-role-only selection, text or embed messages, persistent reactions by default, generated emoji-to-role keys, repair, repost, duplicate, and deletion workflows. Discord remains the source of truth for membership.
+
+## Commands and interactions
+
+The module has no slash-command root. Managers use the dashboard resource manager. Members use the published buttons, dropdowns, or reactions. The stable manager policy identifiers are `reactionroles.create`, `reactionroles.manage`, and `reactionroles.delete`.
+
+## Dashboard configuration
+
+The `panels` resource supports list, read, preview, create, update, duplicate, repair, repost, and delete operations. Publication validates channel access, role hierarchy, dangerous role permissions, custom emoji availability, entry limits, and optimistic revisions before changing Discord or stored state.
+
+## Discord requirements
+
+Helyx needs View Channel, Send Messages, and Manage Roles. Embed panels also need Embed Links. Reaction panels need Read Message History and Add Reactions. Non-persistent reaction panels need Manage Messages so Helyx can remove the member reaction after assigning the role. The module does not request Administrator or Message Content.
+
+## Data, privacy and retention
+
+Helyx stores panel and entry configuration, Helyx-owned message references, lifecycle state, revision, cleanup work, and privacy-detachable creator and updater IDs. It does not store member selections, role membership history, click history, or reaction history. Privacy access and erasure remain available while the module is disabled.
+
+## Operations and failure behavior
+
+Every owned-message cleanup record atomically schedules a bounded one-shot retry through the core scheduler; startup also reconciles paginated pending work before warming the bounded active-panel cache. Exhausted cleanup remains durable for operator review. Unknown message reactions use a short negative cache and coalesced lookups. Deleted or invalid Discord resources move affected panels to `message_missing` or `needs_attention`; repair or repost restores them. Health is unhealthy while stopped, when required services are missing, or after a recent primary operation failure, and degraded for cold-cache startup, cache saturation, or pending cleanup failure.
+
+Disablement stops new interactions without deleting configuration. Re-enable only after checking channel access, role hierarchy, and emoji availability. Rollback may restore compatible application code, but must not reverse migrations or delete panel data.
+
+## Documentation and support
+
+User guides, permissions, troubleshooting, privacy details, and dashboard walkthroughs are published in the [Reaction Roles documentation](https://docs.helyx.gg/modules/reaction-roles/). Report defects through the [Helyx issue tracker](https://github.com/ZyC0R3/Helyx/issues).

package/dist/builder-interactions.d.ts

@@ -0,0 +1,11 @@
+import type { ButtonContribution, ModalInteractionContext, SelectInteractionContext } from "@helyx/sdk";
+export declare function continueDraft(context: Parameters<ButtonContribution["execute"]>[0]): Promise<void>;
+export declare function replaceDraft(context: Parameters<ButtonContribution["execute"]>[0]): Promise<void>;
+export declare function keepDraft(context: Parameters<ButtonContribution["execute"]>[0]): Promise<void>;
+export declare function saveBasicDraft(context: ModalInteractionContext): Promise<void>;
+export declare function openEntryModal(context: Parameters<ButtonContribution["execute"]>[0]): Promise<void>;
+export declare function openEditEntryModal(context: SelectInteractionContext): Promise<void>;
+export declare function saveEntry(context: ModalInteractionContext): Promise<void>;
+export declare function publishDraft(context: Parameters<ButtonContribution["execute"]>[0]): Promise<void>;
+export declare function cancelDraft(context: Parameters<ButtonContribution["execute"]>[0]): Promise<void>;
+export declare function confirmDelete(context: Parameters<ButtonContribution["execute"]>[0]): Promise<void>;

package/dist/builder-interactions.js

@@ -0,0 +1,293 @@
+import { randomUUID } from "node:crypto";
+import { PANEL_LIMITS, PANEL_PURPOSE } from "./constants.js";
+import { validatePanelDraft, } from "./builder.js";
+import { reactionRolePanels as panels } from "./runtime-state.js";
+import { basicModal, builderResponse, defaultsFromSessionState, entryModal, expiresAt, interactionMutationContext, managedObject, parseSessionDraft, replyExpired, requireGuild, serializeDraft, sessionService, } from "./builder-presentation.js";
+function requiredStyle(values) {
+    const value = values[0];
+    if (value !== "text" && value !== "embed")
+        throw new Error("Choose Text or Embed");
+    return value;
+}
+function requiredControl(values) {
+    const value = values[0];
+    if (value !== "buttons" && value !== "dropdown" && value !== "reactions")
+        throw new Error("Choose valid role controls");
+    return value;
+}
+export async function continueDraft(context) {
+    const guildId = requireGuild(context);
+    const session = await sessionService(context.services).getFor(guildId, context.userId, PANEL_PURPOSE);
+    if (!session)
+        return replyExpired(context);
+    const draft = parseSessionDraft(session.state.draft);
+    if (draft) {
+        await context.reply(builderResponse(draft, context.services));
+        return;
+    }
+    await context.showModal(basicModal(defaultsFromSessionState(session.state)));
+}
+export async function replaceDraft(context) {
+    const guildId = requireGuild(context);
+    const sessions = sessionService(context.services);
+    const session = await sessions.getFor(guildId, context.userId, PANEL_PURPOSE);
+    if (!session)
+        return replyExpired(context);
+    const replacement = managedObject(session.state.pendingReplacement)
+        ? session.state.pendingReplacement
+        : {
+            mode: "create",
+            selectionMode: "multiple",
+            persistentReactions: true,
+        };
+    await sessions.create({
+        guildId,
+        userId: context.userId,
+        purpose: PANEL_PURPOSE,
+        state: { ...replacement },
+        expiresAt: expiresAt(),
+        replace: true,
+    });
+    await context.showModal(basicModal(defaultsFromSessionState(replacement)));
+}
+export async function keepDraft(context) {
+    const guildId = requireGuild(context);
+    const sessions = sessionService(context.services);
+    const session = await sessions.getFor(guildId, context.userId, PANEL_PURPOSE);
+    if (!session)
+        return replyExpired(context);
+    const state = { ...session.state };
+    delete state.pendingReplacement;
+    await sessions.update({
+        sessionId: session.sessionId,
+        state,
+        expectedVersion: session.version,
+        expiresAt: expiresAt(),
+    });
+    await context.reply({
+        ephemeral: true,
+        componentsV2: {
+            text: [{ content: "Your existing Reaction Roles draft was kept." }],
+        },
+    });
+}
+export async function saveBasicDraft(context) {
+    const guildId = requireGuild(context);
+    const sessions = sessionService(context.services);
+    const session = await sessions.getFor(guildId, context.userId, PANEL_PURPOSE);
+    if (!session)
+        return replyExpired(context);
+    const prior = parseSessionDraft(session.state.draft);
+    const controlType = requiredControl(context.getStringSelectValues("control"));
+    const selectionMode = session.state.selectionMode === "one_only"
+        ? "one_only"
+        : (prior?.selectionMode ?? "multiple");
+    const persistentReactions = controlType === "reactions" && selectionMode === "one_only"
+        ? false
+        : (prior?.persistentReactions ??
+            session.state.persistentReactions !== false);
+    const draft = {
+        channelId: context.getSelectedChannelIds("channel")[0] ?? "",
+        title: context.getField("title"),
+        messageBody: context.getField("message"),
+        messageStyle: requiredStyle(context.getStringSelectValues("style")),
+        controlType,
+        selectionMode,
+        persistentReactions,
+        ...(prior?.embedColour === undefined
+            ? { embedColour: 0x7c3aed }
+            : { embedColour: prior.embedColour }),
+        ...(prior?.dropdownPlaceholder
+            ? { dropdownPlaceholder: prior.dropdownPlaceholder }
+            : {}),
+        entries: prior?.entries ?? [],
+    };
+    await sessions.update({
+        sessionId: session.sessionId,
+        state: { ...session.state, draft: serializeDraft(draft) },
+        expectedVersion: session.version,
+        expiresAt: expiresAt(),
+    });
+    await context.reply(builderResponse(draft, context.services));
+}
+export async function openEntryModal(context) {
+    const guildId = requireGuild(context);
+    const session = await sessionService(context.services).getFor(guildId, context.userId, PANEL_PURPOSE);
+    if (!session)
+        return replyExpired(context);
+    const draft = parseSessionDraft(session.state.draft);
+    if (!draft)
+        return replyExpired(context);
+    if (draft.entries.length >= PANEL_LIMITS[draft.controlType]) {
+        await context.reply({
+            ephemeral: true,
+            componentsV2: {
+                text: [{ content: "This panel already has the maximum role entries." }],
+            },
+        });
+        return;
+    }
+    await context.showModal(entryModal());
+}
+export async function openEditEntryModal(context) {
+    const guildId = requireGuild(context);
+    const sessions = sessionService(context.services);
+    const session = await sessions.getFor(guildId, context.userId, PANEL_PURPOSE);
+    if (!session)
+        return replyExpired(context);
+    const draft = parseSessionDraft(session.state.draft);
+    const entryId = context.selectedValues[0];
+    const entry = draft?.entries.find((candidate) => candidate.entryId === entryId);
+    if (!draft || !entry || context.selectedValues.length !== 1)
+        return replyExpired(context);
+    await sessions.update({
+        sessionId: session.sessionId,
+        state: { ...session.state, editingEntryId: entry.entryId },
+        expectedVersion: session.version,
+        expiresAt: expiresAt(),
+    });
+    await context.showModal(entryModal(entry, true));
+}
+export async function saveEntry(context) {
+    const guildId = requireGuild(context);
+    const sessions = sessionService(context.services);
+    const session = await sessions.getFor(guildId, context.userId, PANEL_PURPOSE);
+    if (!session)
+        return replyExpired(context);
+    const draft = parseSessionDraft(session.state.draft);
+    if (!draft)
+        return replyExpired(context);
+    const editingEntryId = typeof session.state.editingEntryId === "string"
+        ? session.state.editingEntryId
+        : null;
+    const editingIndex = editingEntryId
+        ? draft.entries.findIndex(({ entryId }) => entryId === editingEntryId)
+        : -1;
+    if (editingEntryId && editingIndex < 0)
+        return replyExpired(context);
+    const action = editingEntryId
+        ? (context.getStringSelectValues("entry-action")[0] ?? "save")
+        : "save";
+    const entries = [...draft.entries];
+    if (editingEntryId && action === "remove") {
+        entries.splice(editingIndex, 1);
+    }
+    else if (editingEntryId && action === "move-up") {
+        if (editingIndex > 0)
+            [entries[editingIndex - 1], entries[editingIndex]] = [
+                entries[editingIndex],
+                entries[editingIndex - 1],
+            ];
+    }
+    else if (editingEntryId && action === "move-down") {
+        if (editingIndex < entries.length - 1)
+            [entries[editingIndex], entries[editingIndex + 1]] = [
+                entries[editingIndex + 1],
+                entries[editingIndex],
+            ];
+    }
+    else {
+        const roleId = context.getSelectedRoleIds("role")[0] ?? "";
+        const buttonStyle = context.getStringSelectValues("button-style")[0];
+        const entry = {
+            entryId: editingEntryId ?? `entry-${randomUUID().replaceAll("-", "")}`,
+            roleId,
+            nameplate: context.getField("nameplate"),
+            ...(context.getField("emoji").trim()
+                ? { emoji: context.getField("emoji") }
+                : {}),
+            ...(buttonStyle
+                ? {
+                    buttonStyle: buttonStyle,
+                }
+                : {}),
+        };
+        if (editingEntryId)
+            entries[editingIndex] = entry;
+        else
+            entries.push(entry);
+    }
+    const next = entries.length === 0
+        ? { ...draft, entries }
+        : validatePanelDraft({
+            ...draft,
+            entries,
+        });
+    const state = {
+        ...session.state,
+        draft: serializeDraft(next),
+    };
+    delete state.editingEntryId;
+    await sessions.update({
+        sessionId: session.sessionId,
+        state,
+        expectedVersion: session.version,
+        expiresAt: expiresAt(),
+    });
+    await context.reply(builderResponse(next, context.services));
+}
+export async function publishDraft(context) {
+    const guildId = requireGuild(context);
+    const sessions = sessionService(context.services);
+    const session = await sessions.getFor(guildId, context.userId, PANEL_PURPOSE);
+    if (!session)
+        return replyExpired(context);
+    const draft = parseSessionDraft(session.state.draft);
+    if (!draft)
+        return replyExpired(context);
+    const mutation = interactionMutationContext(context, guildId);
+    const panel = session.state.mode === "edit" &&
+        typeof session.state.panelId === "string" &&
+        typeof session.state.expectedRevision === "number"
+        ? await panels.update(mutation, {
+            resourceId: session.state.panelId,
+            expectedRevision: session.state.expectedRevision,
+            draft,
+        })
+        : await panels.create(mutation, draft);
+    await sessions.delete(session.sessionId);
+    await context.reply({
+        ephemeral: true,
+        componentsV2: {
+            text: [
+                {
+                    content: `Reaction Roles panel **${panel.title}** is active in <#${panel.channelId}>.`,
+                },
+            ],
+        },
+        allowedUserMentionIds: [],
+    });
+}
+export async function cancelDraft(context) {
+    const guildId = requireGuild(context);
+    const sessions = sessionService(context.services);
+    const session = await sessions.getFor(guildId, context.userId, PANEL_PURPOSE);
+    if (session)
+        await sessions.delete(session.sessionId);
+    await context.reply({
+        ephemeral: true,
+        componentsV2: { text: [{ content: "Nothing was changed." }] },
+    });
+}
+export async function confirmDelete(context) {
+    const guildId = requireGuild(context);
+    const sessions = sessionService(context.services);
+    const session = await sessions.getFor(guildId, context.userId, PANEL_PURPOSE);
+    if (!session ||
+        session.state.mode !== "delete" ||
+        typeof session.state.panelId !== "string" ||
+        typeof session.state.expectedRevision !== "number")
+        return replyExpired(context);
+    await panels.delete(interactionMutationContext(context, guildId), session.state.panelId, session.state.expectedRevision);
+    await sessions.delete(session.sessionId);
+    await context.reply({
+        ephemeral: true,
+        componentsV2: {
+            text: [
+                {
+                    content: "The role panel was deleted. Existing member roles were not changed.",
+                },
+            ],
+        },
+    });
+}

package/dist/builder-presentation.d.ts

@@ -0,0 +1,30 @@
+import type { InteractionSessionService, MessageResponse, ModalDefinition, ServiceAccess } from "@helyx/sdk";
+import { type PanelDraft } from "./builder.js";
+import type { PanelMutationContext } from "./panel-service.js";
+export declare function basicModal(panel?: Partial<PanelDraft>, editing?: boolean): ModalDefinition;
+export declare function defaultsFromSessionState(state: Readonly<Record<string, unknown>>): Partial<PanelDraft>;
+export declare function managedObject(value: unknown): value is Record<string, unknown>;
+export declare function entryModal(entry?: PanelDraft["entries"][number], editing?: boolean): ModalDefinition;
+export declare function builderResponse(draft: PanelDraft, services: ServiceAccess): MessageResponse;
+export declare function interactionMutationContext(context: {
+    userId: string;
+    services: ServiceAccess;
+    interactionId: string;
+    sendToChannel: PanelMutationContext["sendToChannel"];
+    deleteChannelMessage: PanelMutationContext["deleteChannelMessage"];
+    editChannelMessage: PanelMutationContext["editChannelMessage"];
+    addChannelMessageReaction: PanelMutationContext["addChannelMessageReaction"];
+}, guildId: string): PanelMutationContext;
+export declare function sessionService(services: ServiceAccess): InteractionSessionService;
+export declare function requireGuild(context: {
+    serverId?: string;
+}): string;
+export declare function expiresAt(): Date;
+export declare function serializeDraft(draft: PanelDraft): Record<string, unknown>;
+export declare function parseSessionDraft(value: unknown): PanelDraft | null;
+export declare function replyExpired(context: {
+    reply(response: MessageResponse): Promise<void>;
+}): Promise<void>;
+export declare function stalePanelReply(context: {
+    reply(response: MessageResponse): Promise<void>;
+}): Promise<void>;