@helyx/module-reactionroles 1.0.15 → 1.0.17

package/dist/builder-presentation.js

@@ -0,0 +1,343 @@
+import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
+import { COMPONENT_IDS, PANEL_LIMITS } from "./constants.js";
+import { canonicaliseEmoji, panelMessageDraft, validatePanelDraft, } from "./builder.js";
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringValue(value) {
+    if (typeof value !== "string")
+        throw new Error("invalid string");
+    return value;
+}
+export function basicModal(panel, editing = false) {
+    return {
+        customId: COMPONENT_IDS.basicModal,
+        title: editing ? "Edit role panel" : "Create role panel",
+        fields: [
+            {
+                type: "discord-channel",
+                customId: "channel",
+                label: "Destination channel",
+                required: true,
+                channelTypes: ["guild_text", "guild_announcement"],
+                ...(panel?.channelId ? { defaultValues: [panel.channelId] } : {}),
+            },
+            {
+                customId: "title",
+                label: "Title",
+                style: "short",
+                required: true,
+                minLength: 1,
+                maxLength: 80,
+                ...(panel?.title ? { value: panel.title } : {}),
+            },
+            {
+                customId: "message",
+                label: "Message",
+                style: "paragraph",
+                required: true,
+                minLength: 1,
+                maxLength: 1_000,
+                ...(panel?.messageBody ? { value: panel.messageBody } : {}),
+            },
+            {
+                type: "string-select",
+                customId: "style",
+                label: "Message style",
+                required: true,
+                options: [
+                    {
+                        label: "Text",
+                        value: "text",
+                        default: panel?.messageStyle !== "embed",
+                    },
+                    {
+                        label: "Embed",
+                        value: "embed",
+                        default: panel?.messageStyle === "embed",
+                    },
+                ],
+            },
+            {
+                type: "string-select",
+                customId: "control",
+                label: "Role controls",
+                required: true,
+                options: [
+                    {
+                        label: "Buttons",
+                        value: "buttons",
+                        default: !panel?.controlType || panel.controlType === "buttons",
+                    },
+                    {
+                        label: "Dropdown",
+                        value: "dropdown",
+                        default: panel?.controlType === "dropdown",
+                    },
+                    {
+                        label: "Emoji reactions",
+                        value: "reactions",
+                        default: panel?.controlType === "reactions",
+                    },
+                ],
+            },
+        ],
+    };
+}
+export function defaultsFromSessionState(state) {
+    return {
+        ...(typeof state.channelId === "string"
+            ? { channelId: state.channelId }
+            : {}),
+        ...(state.messageStyle === "text" || state.messageStyle === "embed"
+            ? { messageStyle: state.messageStyle }
+            : {}),
+        ...(state.controlType === "buttons" ||
+            state.controlType === "dropdown" ||
+            state.controlType === "reactions"
+            ? { controlType: state.controlType }
+            : {}),
+    };
+}
+export function managedObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function entryModal(entry, editing = false) {
+    return {
+        customId: COMPONENT_IDS.entryModal,
+        title: editing ? "Edit role entry" : "Add a role entry",
+        fields: [
+            {
+                type: "discord-role",
+                customId: "role",
+                label: "Discord role",
+                required: true,
+                ...(entry ? { defaultValues: [entry.roleId] } : {}),
+            },
+            {
+                customId: "nameplate",
+                label: "Public label",
+                style: "short",
+                required: true,
+                minLength: 1,
+                maxLength: 80,
+                ...(entry ? { value: entry.nameplate } : {}),
+            },
+            {
+                customId: "emoji",
+                label: "Emoji",
+                description: "Optional for buttons and dropdowns; required for reactions.",
+                style: "short",
+                required: false,
+                minLength: 1,
+                maxLength: 100,
+                ...(entry?.emoji ? { value: entry.emoji } : {}),
+                placeholder: "✅ or <:updates:123456789012345678>",
+            },
+            {
+                type: "string-select",
+                customId: "button-style",
+                label: "Button colour",
+                required: false,
+                options: [
+                    { label: "Grey", value: "secondary", default: true },
+                    { label: "Blue", value: "primary" },
+                    { label: "Green", value: "success" },
+                    { label: "Red", value: "danger" },
+                ],
+            },
+            ...(editing
+                ? [
+                    {
+                        type: "string-select",
+                        customId: "entry-action",
+                        label: "Entry action",
+                        required: true,
+                        options: [
+                            { label: "Save changes", value: "save", default: true },
+                            { label: "Move up", value: "move-up" },
+                            { label: "Move down", value: "move-down" },
+                            { label: "Remove entry", value: "remove" },
+                        ],
+                    },
+                ]
+                : []),
+        ],
+    };
+}
+export function builderResponse(draft, services) {
+    const builder = services.get(HELYX_SERVICE_NAMES.messageBuilder);
+    const panel = draft.entries.length > 0
+        ? builder.build(panelMessageDraft(draft)).response
+        : builder.build({
+            presentation: draft.messageStyle === "embed"
+                ? {
+                    type: "embed",
+                    title: draft.title,
+                    body: draft.messageBody,
+                    ...(draft.embedColour === undefined
+                        ? {}
+                        : { color: draft.embedColour }),
+                }
+                : {
+                    type: "text",
+                    title: draft.title,
+                    body: draft.messageBody,
+                    accentColor: 0x7c3aed,
+                },
+            allowedUserMentionIds: [],
+        }).response;
+    return {
+        ...panel,
+        ephemeral: true,
+        selects: draft.entries.length === 0
+            ? []
+            : [
+                {
+                    type: "string",
+                    customId: COMPONENT_IDS.builderEntries,
+                    placeholder: "Edit, reorder or remove a role",
+                    minValues: 1,
+                    maxValues: 1,
+                    options: draft.entries.map((entry) => ({
+                        label: entry.nameplate,
+                        value: entry.entryId,
+                        ...(entry.emoji
+                            ? {
+                                emojiIdentifier: canonicaliseEmoji(entry.emoji)
+                                    .identifier,
+                            }
+                            : {}),
+                    })),
+                },
+            ],
+        buttons: [
+            {
+                type: "button",
+                customId: COMPONENT_IDS.addEntry,
+                label: "Add role",
+                style: "secondary",
+                disabled: draft.entries.length >= PANEL_LIMITS[draft.controlType],
+            },
+            {
+                type: "button",
+                customId: COMPONENT_IDS.publish,
+                label: "Publish panel",
+                style: "success",
+                disabled: draft.entries.length === 0,
+            },
+            {
+                type: "button",
+                customId: COMPONENT_IDS.cancel,
+                label: "Cancel",
+                style: "secondary",
+            },
+        ],
+        allowedUserMentionIds: [],
+    };
+}
+export function interactionMutationContext(context, guildId) {
+    return {
+        guildId,
+        actorUserId: context.userId,
+        source: "discord",
+        services: context.services,
+        correlationId: context.interactionId,
+        sendToChannel: (channelId, response) => context.sendToChannel(channelId, response),
+        deleteChannelMessage: (channelId, messageId) => context.deleteChannelMessage(channelId, messageId),
+        editChannelMessage: (channelId, messageId, response) => context.editChannelMessage(channelId, messageId, response),
+        addChannelMessageReaction: (channelId, messageId, emojiIdentifier) => context.addChannelMessageReaction(channelId, messageId, emojiIdentifier),
+    };
+}
+export function sessionService(services) {
+    return services.get(HELYX_SERVICE_NAMES.sessions);
+}
+export function requireGuild(context) {
+    if (!context.serverId)
+        throw new Error("Use this command in a Discord server");
+    return context.serverId;
+}
+export function expiresAt() {
+    return new Date(Date.now() + 20 * 60 * 1_000);
+}
+export function serializeDraft(draft) {
+    return {
+        channelId: draft.channelId,
+        title: draft.title,
+        messageBody: draft.messageBody,
+        messageStyle: draft.messageStyle,
+        controlType: draft.controlType,
+        selectionMode: draft.selectionMode,
+        persistentReactions: draft.persistentReactions,
+        ...(draft.embedColour === undefined
+            ? {}
+            : { embedColour: draft.embedColour }),
+        ...(draft.dropdownPlaceholder === undefined
+            ? {}
+            : { dropdownPlaceholder: draft.dropdownPlaceholder }),
+        entries: draft.entries.map((entry) => ({ ...entry })),
+    };
+}
+export function parseSessionDraft(value) {
+    if (!isObject(value) || !Array.isArray(value.entries))
+        return null;
+    try {
+        return validatePanelDraft({
+            channelId: stringValue(value.channelId),
+            title: stringValue(value.title),
+            messageBody: stringValue(value.messageBody),
+            messageStyle: stringValue(value.messageStyle),
+            controlType: stringValue(value.controlType),
+            selectionMode: stringValue(value.selectionMode),
+            persistentReactions: typeof value.persistentReactions === "boolean"
+                ? value.persistentReactions
+                : true,
+            ...(typeof value.embedColour === "number"
+                ? { embedColour: value.embedColour }
+                : {}),
+            ...(typeof value.dropdownPlaceholder === "string"
+                ? { dropdownPlaceholder: value.dropdownPlaceholder }
+                : {}),
+            entries: value.entries.map((entry) => {
+                if (!isObject(entry))
+                    throw new Error("invalid entry");
+                return {
+                    entryId: stringValue(entry.entryId),
+                    roleId: stringValue(entry.roleId),
+                    nameplate: stringValue(entry.nameplate),
+                    ...(typeof entry.emoji === "string" ? { emoji: entry.emoji } : {}),
+                    ...(typeof entry.buttonStyle === "string"
+                        ? { buttonStyle: entry.buttonStyle }
+                        : {}),
+                };
+            }),
+        }, { allowEmptyEntries: true });
+    }
+    catch {
+        return null;
+    }
+}
+export async function replyExpired(context) {
+    await context.reply({
+        ephemeral: true,
+        componentsV2: {
+            text: [
+                {
+                    content: "This role-panel builder expired. Run `/reaction-role create` or `/reaction-role edit` again.",
+                },
+            ],
+        },
+    });
+}
+export async function stalePanelReply(context) {
+    await context.reply({
+        ephemeral: true,
+        componentsV2: {
+            text: [
+                {
+                    content: "This role panel changed or is no longer active. Ask a server manager to repair it.",
+                },
+            ],
+        },
+    });
+}

package/dist/builder.d.ts

@@ -23,6 +23,9 @@ export interface PanelDraft {
     dropdownPlaceholder?: string;
     entries: readonly PanelEntryDraft[];
 }
+export declare class PanelDraftValidationError extends Error {
+    constructor(message: string);
+}
 export interface CanonicalEmoji {
     kind: "unicode" | "custom";
     name: string;

package/dist/builder.js

@@ -1,51 +1,57 @@
 import { COMPONENT_IDS, PANEL_LIMITS } from "./constants.js";
+export class PanelDraftValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PanelDraftValidationError";
+    }
+}
 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");
+        throw new PanelDraftValidationError("Choose Text or Embed for the message style");
     if (!["buttons", "dropdown", "reactions"].includes(input.controlType))
-        throw new Error("Choose Buttons, Dropdown or Emoji reactions");
+        throw new PanelDraftValidationError("Choose Buttons, Dropdown or Emoji reactions");
     if (!["multiple", "one_only"].includes(input.selectionMode))
-        throw new Error("Choose a valid selection mode");
+        throw new PanelDraftValidationError("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");
+        throw new PanelDraftValidationError("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");
+        throw new PanelDraftValidationError("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`);
+        throw new PanelDraftValidationError(`${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");
+            throw new PanelDraftValidationError("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");
+            throw new PanelDraftValidationError("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");
+            throw new PanelDraftValidationError("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");
+                throw new PanelDraftValidationError("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");
+            throw new PanelDraftValidationError("Choose a valid button colour");
         return {
             entryId,
             roleId,
@@ -58,7 +64,7 @@ export function validatePanelDraft(input, options = {}) {
     if (!Number.isInteger(embedColour) ||
         embedColour < 0 ||
         embedColour > 0xffffff)
-        throw new Error("Embed colour must be between 0 and 16777215");
+        throw new PanelDraftValidationError("Embed colour must be between 0 and 16777215");
     const dropdownPlaceholder = input.dropdownPlaceholder?.trim()
         ? boundedText(input.dropdownPlaceholder, "Dropdown label", 100)
         : "Choose your roles";
@@ -170,7 +176,7 @@ export function canonicaliseEmoji(input) {
     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");
+        throw new PanelDraftValidationError("Enter one Unicode emoji or a custom server emoji");
     return {
         kind: "unicode",
         name: value,
@@ -182,19 +188,19 @@ export function canonicaliseEmoji(input) {
 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`);
+        throw new PanelDraftValidationError(`${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`);
+        throw new PanelDraftValidationError(`${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`);
+        throw new PanelDraftValidationError(`${label} identifier is invalid`);
     return value;
 }
 function controlLabel(type) {

package/dist/cleanup-repository.d.ts

@@ -0,0 +1,24 @@
+import type { ModuleRecordService, ModuleRecordWriteValue } from "@helyx/sdk";
+import { type PendingMessageCleanup } from "./record-schema.js";
+export declare class MessageCleanupRepository {
+    private readonly records;
+    constructor(records: ModuleRecordService);
+    record(input: {
+        guildId: string;
+        panelId: string;
+        channelId: string;
+        messageId: string;
+        reason: "replacement" | "rollback" | "delete";
+        now?: Date;
+    }): Promise<boolean>;
+    list(limit?: number): Promise<readonly PendingMessageCleanup[]>;
+    listPage(limit?: number, cursor?: readonly ModuleRecordWriteValue[]): Promise<{
+        items: readonly PendingMessageCleanup[];
+        nextCursor: readonly ModuleRecordWriteValue[] | null;
+    }>;
+    find(cleanupId: string): Promise<PendingMessageCleanup | null>;
+    claim(cleanup: PendingMessageCleanup, now?: Date): Promise<PendingMessageCleanup | null>;
+    complete(cleanup: PendingMessageCleanup, now?: Date): Promise<boolean>;
+    count(panelId: string): Promise<number>;
+    private parse;
+}

package/dist/cleanup-repository.js

@@ -0,0 +1,118 @@
+import { randomUUID } from "node:crypto";
+import { REACTION_ROLES_MODULE_ID, REACTION_ROLE_CLEANUP_TASK, } from "./constants.js";
+import { requiredDate, requiredEnum, requiredNumber, requiredString, } from "./record-mapping.js";
+import { cleanupSelect } from "./record-schema.js";
+export class MessageCleanupRepository {
+    records;
+    constructor(records) {
+        this.records = records;
+    }
+    async record(input) {
+        const cleanupId = randomUUID();
+        const now = input.now ?? new Date();
+        const created = await this.records.appendUnique({
+            moduleId: REACTION_ROLES_MODULE_ID,
+            collection: "message_cleanup",
+            values: {
+                cleanup_id: cleanupId,
+                guild_id: input.guildId,
+                panel_id: input.panelId,
+                channel_id: input.channelId,
+                message_id: input.messageId,
+                reason: input.reason,
+                attempts: 0,
+                next_attempt_at: now,
+                created_at: now,
+            },
+            uniqueBy: ["guild_id", "channel_id", "message_id", "reason"],
+            schedule: {
+                taskKind: REACTION_ROLE_CLEANUP_TASK,
+                guildId: input.guildId,
+                idempotencyKey: `reactionroles:cleanup:${input.guildId}:${input.channelId}:${input.messageId}:${input.reason}`,
+                payload: { cleanupId },
+                scheduledFor: now,
+            },
+        });
+        return created.created;
+    }
+    async list(limit = 100) {
+        return (await this.listPage(limit)).items;
+    }
+    async listPage(limit = 100, cursor) {
+        const page = await this.records.findMany({
+            moduleId: REACTION_ROLES_MODULE_ID,
+            collection: "message_cleanup",
+            select: cleanupSelect,
+            where: { completed_at: null },
+            orderBy: [
+                { field: "next_attempt_at", direction: "asc" },
+                { field: "cleanup_id", direction: "asc" },
+            ],
+            ...(cursor ? { cursor } : {}),
+            limit: Math.min(100, Math.max(1, limit)),
+        });
+        return {
+            items: page.records.map((row) => this.parse(row)),
+            nextCursor: page.nextCursor,
+        };
+    }
+    async find(cleanupId) {
+        const row = await this.records.findOne({
+            moduleId: REACTION_ROLES_MODULE_ID,
+            collection: "message_cleanup",
+            select: cleanupSelect,
+            where: { cleanup_id: cleanupId, completed_at: null },
+        });
+        return row ? this.parse(row) : null;
+    }
+    async claim(cleanup, now = new Date()) {
+        if (cleanup.attempts >= 10 ||
+            cleanup.nextAttemptAt.getTime() > now.getTime())
+            return null;
+        const attempts = cleanup.attempts + 1;
+        const nextAttemptAt = new Date(now.getTime() + Math.min(3_600_000, 30_000 * 2 ** cleanup.attempts));
+        const claimed = await this.records.updateOne({
+            moduleId: REACTION_ROLES_MODULE_ID,
+            collection: "message_cleanup",
+            where: { cleanup_id: cleanup.cleanupId },
+            expected: { field: "attempts", value: cleanup.attempts },
+            values: {
+                attempts,
+                next_attempt_at: nextAttemptAt,
+            },
+        });
+        return claimed.updated ? { ...cleanup, attempts, nextAttemptAt } : null;
+    }
+    async complete(cleanup, now = new Date()) {
+        return (await this.records.updateOne({
+            moduleId: REACTION_ROLES_MODULE_ID,
+            collection: "message_cleanup",
+            where: { cleanup_id: cleanup.cleanupId },
+            expected: { field: "attempts", value: cleanup.attempts },
+            values: { completed_at: now },
+        })).updated;
+    }
+    count(panelId) {
+        return this.records.count({
+            moduleId: REACTION_ROLES_MODULE_ID,
+            collection: "message_cleanup",
+            where: { panel_id: panelId, completed_at: null },
+        });
+    }
+    parse(row) {
+        return {
+            cleanupId: requiredString(row, "cleanup_id"),
+            guildId: requiredString(row, "guild_id"),
+            panelId: requiredString(row, "panel_id"),
+            channelId: requiredString(row, "channel_id"),
+            messageId: requiredString(row, "message_id"),
+            reason: requiredEnum(row, "reason", [
+                "replacement",
+                "rollback",
+                "delete",
+            ]),
+            attempts: requiredNumber(row, "attempts"),
+            nextAttemptAt: requiredDate(row, "next_attempt_at"),
+        };
+    }
+}

package/dist/constants.d.ts

@@ -1,5 +1,8 @@
+export declare const REACTION_ROLES_MODULE_ID = "helyx.reactionroles";
+/** @deprecated Use the feature-specific canonical identity export. */
 export declare const MODULE_ID = "helyx.reactionroles";
 export declare const PANEL_PURPOSE = "helyx.reactionroles.builder";
+export declare const REACTION_ROLE_CLEANUP_TASK = "cleanup-owned-message";
 export declare const COMPONENT_IDS: {
     readonly addEntry: "helyx.reactionroles.builder.add-entry";
     readonly continueDraft: "helyx.reactionroles.builder.continue";

package/dist/constants.js

@@ -1,5 +1,8 @@
-export const MODULE_ID = "helyx.reactionroles";
+export const REACTION_ROLES_MODULE_ID = "helyx.reactionroles";
+/** @deprecated Use the feature-specific canonical identity export. */
+export const MODULE_ID = REACTION_ROLES_MODULE_ID;
 export const PANEL_PURPOSE = "helyx.reactionroles.builder";
+export const REACTION_ROLE_CLEANUP_TASK = "cleanup-owned-message";
 export const COMPONENT_IDS = {
     addEntry: "helyx.reactionroles.builder.add-entry",
     continueDraft: "helyx.reactionroles.builder.continue",

package/dist/health.d.ts

@@ -0,0 +1,16 @@
+import { type HealthResult, type RuntimeContext } from "@helyx/sdk";
+export declare class ReactionRolesHealthTracker {
+    #private;
+    start(context: RuntimeContext): void;
+    startupResult(input: {
+        cacheWarmFailed?: boolean;
+        cacheSaturated?: boolean;
+        cleanupFailures?: number;
+    }): void;
+    primarySuccess(source?: ReactionRolesHealthSource): void;
+    primaryFailure(source?: ReactionRolesHealthSource): void;
+    cleanupRecovered(): void;
+    stop(): void;
+    health(): HealthResult;
+}
+export type ReactionRolesHealthSource = "resource" | "member" | "lifecycle";