@helyx/module-reactionroles 1.0.1

package/manifest.json

@@ -0,0 +1,310 @@
+{
+  "manifestVersion": "0.2",
+  "releaseStatus": "live",
+  "id": "helyx.reactionroles",
+  "name": "Reaction Roles",
+  "version": "1.0.1",
+  "description": "Let members select approved roles themselves.",
+  "entry": "./dist/index.js",
+  "framework": "^0.1.0",
+  "dependencies": [],
+  "permissions": [
+    "ADD_REACTIONS",
+    "EMBED_LINKS",
+    "MANAGE_MESSAGES",
+    "MANAGE_ROLES",
+    "READ_MESSAGE_HISTORY",
+    "SEND_MESSAGES",
+    "VIEW_CHANNEL"
+  ],
+  "privacy": {
+    "containsPersonalData": true,
+    "providerVersion": 1,
+    "collections": [
+      {
+        "name": "panels",
+        "createdAtField": "created_at",
+        "subjectFields": [
+          {
+            "field": "created_by_user_id",
+            "role": "creator",
+            "erasure": "set-null"
+          },
+          {
+            "field": "updated_by_user_id",
+            "role": "updater",
+            "erasure": "set-null"
+          }
+        ]
+      }
+    ]
+  },
+  "dashboard": {
+    "category": "automation",
+    "icon": "roles",
+    "settings": [],
+    "resources": [
+      {
+        "id": "panels",
+        "name": "Role panels",
+        "singularName": "Role panel",
+        "description": "Create and manage Helyx-owned self-service role panels.",
+        "publicationMode": "validate_on_publish",
+        "fields": [
+          {
+            "key": "channelId",
+            "type": "discord-channel",
+            "label": "Destination channel",
+            "description": "Text or announcement channel that receives the panel.",
+            "required": true,
+            "group": "Panel setup",
+            "channelTypes": ["guild_text", "guild_announcement"]
+          },
+          {
+            "key": "title",
+            "type": "string",
+            "label": "Title",
+            "description": "Short public panel title.",
+            "required": true,
+            "group": "Message",
+            "minLength": 1,
+            "maxLength": 80
+          },
+          {
+            "key": "messageBody",
+            "type": "string",
+            "label": "Message",
+            "description": "Public guidance shown above the role controls.",
+            "required": true,
+            "group": "Message",
+            "multiline": true,
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          {
+            "key": "messageStyle",
+            "type": "select",
+            "label": "Message style",
+            "description": "Show the panel as clear text or a compact embed.",
+            "required": true,
+            "group": "Message",
+            "options": [
+              {
+                "value": "text",
+                "label": "Text"
+              },
+              {
+                "value": "embed",
+                "label": "Embed"
+              }
+            ],
+            "default": "text"
+          },
+          {
+            "key": "controlType",
+            "type": "select",
+            "label": "Role controls",
+            "description": "Choose buttons, a dropdown or emoji reactions.",
+            "required": true,
+            "group": "Panel setup",
+            "options": [
+              {
+                "value": "buttons",
+                "label": "Buttons"
+              },
+              {
+                "value": "dropdown",
+                "label": "Dropdown"
+              },
+              {
+                "value": "reactions",
+                "label": "Emoji reactions"
+              }
+            ],
+            "default": "buttons"
+          },
+          {
+            "key": "selectionMode",
+            "type": "select",
+            "label": "Selection mode",
+            "description": "Allow several panel roles or only one.",
+            "required": true,
+            "group": "Panel setup",
+            "options": [
+              {
+                "value": "multiple",
+                "label": "Several roles"
+              },
+              {
+                "value": "one_only",
+                "label": "One role only"
+              }
+            ],
+            "default": "multiple"
+          },
+          {
+            "key": "persistentReactions",
+            "type": "boolean",
+            "label": "Persistent reactions",
+            "description": "Keep member reactions visible and remove roles when members unreact. Turn this off to remove each member reaction after assigning its role.",
+            "required": true,
+            "group": "Panel setup",
+            "visibleWhen": {
+              "field": "controlType",
+              "equals": "reactions"
+            },
+            "default": true
+          },
+          {
+            "key": "embedColour",
+            "type": "integer",
+            "label": "Embed colour",
+            "description": "Discord embed colour as a six-digit hex code.",
+            "required": false,
+            "group": "Message",
+            "visibleWhen": {
+              "field": "messageStyle",
+              "equals": "embed"
+            },
+            "minimum": 0,
+            "maximum": 16777215,
+            "default": 8141549,
+            "display": "hex_colour"
+          },
+          {
+            "key": "dropdownPlaceholder",
+            "type": "string",
+            "label": "Dropdown label",
+            "description": "Short instruction shown before a member opens the dropdown.",
+            "required": false,
+            "group": "Panel setup",
+            "visibleWhen": {
+              "field": "controlType",
+              "equals": "dropdown"
+            },
+            "minLength": 1,
+            "maxLength": 100,
+            "default": "Choose your roles"
+          },
+          {
+            "key": "entries",
+            "type": "list",
+            "label": "Role entries",
+            "description": "Roles and labels available from this panel.",
+            "required": true,
+            "group": "Roles",
+            "minItems": 1,
+            "maxItems": 25,
+            "itemLabel": "Role entry",
+            "fields": [
+              {
+                "key": "roleId",
+                "type": "discord-role",
+                "label": "Role",
+                "description": "Approved role members can add or remove.",
+                "required": true
+              },
+              {
+                "key": "nameplate",
+                "type": "string",
+                "label": "Label",
+                "description": "Public label for this role.",
+                "required": true,
+                "minLength": 1,
+                "maxLength": 80
+              },
+              {
+                "key": "emoji",
+                "type": "string",
+                "label": "Emoji",
+                "description": "Optional for buttons or dropdowns and required for reactions.",
+                "required": false,
+                "minLength": 1,
+                "maxLength": 100,
+                "placeholder": "✅ or <:updates:123456789012345678>",
+                "display": "emoji"
+              },
+              {
+                "key": "buttonStyle",
+                "type": "select",
+                "label": "Button colour",
+                "description": "Colour used for a button control.",
+                "required": false,
+                "options": [
+                  {
+                    "value": "primary",
+                    "label": "Blue"
+                  },
+                  {
+                    "value": "secondary",
+                    "label": "Grey"
+                  },
+                  {
+                    "value": "success",
+                    "label": "Green"
+                  },
+                  {
+                    "value": "danger",
+                    "label": "Red"
+                  }
+                ],
+                "default": "secondary"
+              }
+            ]
+          }
+        ],
+        "actions": [
+          {
+            "id": "duplicate",
+            "label": "Duplicate panel",
+            "description": "Create and publish a new panel using these settings.",
+            "style": "secondary",
+            "confirmation": "Publish a duplicate of this role panel?"
+          },
+          {
+            "id": "repair",
+            "label": "Repair panel",
+            "description": "Revalidate the panel and recreate its Helyx-owned message when required.",
+            "style": "secondary"
+          },
+          {
+            "id": "repost",
+            "label": "Repost panel",
+            "description": "Publish a replacement Helyx-owned message and retire the old reference.",
+            "style": "secondary",
+            "confirmation": "Repost this role panel and replace its current Discord message?"
+          },
+          {
+            "id": "delete",
+            "label": "Delete panel",
+            "description": "Delete Helyx data and attempt to remove its current panel message.",
+            "style": "danger",
+            "confirmation": "Delete this role panel? Existing member roles will not be changed."
+          }
+        ]
+      }
+    ]
+  },
+  "contributions": {
+    "commands": ["reaction-role"],
+    "events": [
+      "discord.channel-delete",
+      "discord.channel-update",
+      "discord.guild-emoji-delete",
+      "discord.guild-emoji-update",
+      "discord.guild-role-delete",
+      "discord.guild-role-update",
+      "discord.message-delete",
+      "discord.message-reaction-add",
+      "discord.message-reaction-remove"
+    ],
+    "logs": [
+      "reaction-role-panel-created",
+      "reaction-role-panel-deleted",
+      "reaction-role-panel-updated",
+      "reaction-role-panel-reposted",
+      "reaction-role-panel-repaired",
+      "reaction-role-member-changed"
+    ]
+  }
+}

package/migrations/0001_reactionroles_foundation.sql

@@ -0,0 +1,108 @@
+CREATE TABLE IF NOT EXISTS reactionroles_panels (
+  panel_id text PRIMARY KEY,
+  guild_id text NOT NULL,
+  channel_id text NOT NULL,
+  message_id text,
+  title text NOT NULL CHECK (length(title) BETWEEN 1 AND 80),
+  message_body text NOT NULL CHECK (length(message_body) BETWEEN 1 AND 1000),
+  message_style text NOT NULL CHECK (message_style IN ('text', 'embed')),
+  control_type text NOT NULL CHECK (
+    control_type IN ('buttons', 'dropdown', 'reactions')
+  ),
+  selection_mode text NOT NULL CHECK (
+    selection_mode IN ('multiple', 'one_only')
+  ),
+  embed_colour integer CHECK (
+    embed_colour IS NULL OR embed_colour BETWEEN 0 AND 16777215
+  ),
+  dropdown_placeholder text CHECK (
+    dropdown_placeholder IS NULL
+    OR length(dropdown_placeholder) BETWEEN 1 AND 100
+  ),
+  status text NOT NULL CHECK (
+    status IN (
+      'pending', 'active', 'disabled', 'message_missing',
+      'needs_attention', 'cleanup_pending', 'deleting'
+    )
+  ),
+  revision bigint NOT NULL DEFAULT 1 CHECK (revision > 0),
+  created_by_user_id text,
+  updated_by_user_id text,
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  CHECK (
+    control_type <> 'reactions' OR selection_mode = 'multiple'
+  )
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS reactionroles_panels_message_idx
+  ON reactionroles_panels (guild_id, message_id)
+  WHERE message_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS reactionroles_panels_guild_status_idx
+  ON reactionroles_panels (guild_id, status, updated_at DESC, panel_id);
+
+CREATE TABLE IF NOT EXISTS reactionroles_entries (
+  entry_id text PRIMARY KEY,
+  panel_id text NOT NULL
+    REFERENCES reactionroles_panels (panel_id) ON DELETE CASCADE,
+  position integer NOT NULL CHECK (position BETWEEN 0 AND 24),
+  role_id text NOT NULL,
+  nameplate text NOT NULL CHECK (length(nameplate) BETWEEN 1 AND 80),
+  emoji_kind text CHECK (emoji_kind IS NULL OR emoji_kind IN ('unicode', 'custom')),
+  emoji_name text,
+  emoji_id text,
+  emoji_animated boolean,
+  button_style text CHECK (
+    button_style IS NULL
+    OR button_style IN ('primary', 'secondary', 'success', 'danger')
+  ),
+  created_at timestamptz NOT NULL,
+  updated_at timestamptz NOT NULL,
+  UNIQUE (panel_id, position),
+  UNIQUE (panel_id, role_id),
+  CHECK (
+    (emoji_kind IS NULL AND emoji_name IS NULL AND emoji_id IS NULL)
+    OR (emoji_kind = 'unicode' AND emoji_name IS NOT NULL AND emoji_id IS NULL)
+    OR (emoji_kind = 'custom' AND emoji_name IS NOT NULL AND emoji_id IS NOT NULL)
+  )
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS reactionroles_entries_emoji_idx
+  ON reactionroles_entries (
+    panel_id,
+    emoji_kind,
+    emoji_name,
+    COALESCE(emoji_id, '')
+  )
+  WHERE emoji_kind IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS reactionroles_entries_panel_idx
+  ON reactionroles_entries (panel_id, position);
+
+CREATE TABLE IF NOT EXISTS reactionroles_message_cleanup (
+  cleanup_id text PRIMARY KEY,
+  guild_id text NOT NULL,
+  panel_id text NOT NULL,
+  channel_id text NOT NULL,
+  message_id text NOT NULL,
+  reason text NOT NULL CHECK (
+    reason IN ('replacement', 'rollback', 'delete')
+  ),
+  attempts integer NOT NULL DEFAULT 0 CHECK (attempts BETWEEN 0 AND 10),
+  next_attempt_at timestamptz,
+  created_at timestamptz NOT NULL,
+  completed_at timestamptz
+);
+
+CREATE INDEX IF NOT EXISTS reactionroles_cleanup_pending_idx
+  ON reactionroles_message_cleanup (next_attempt_at, created_at)
+  WHERE completed_at IS NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS reactionroles_cleanup_message_reason_idx
+  ON reactionroles_message_cleanup (
+    guild_id,
+    channel_id,
+    message_id,
+    reason
+  );

package/migrations/0002_cleanup_retry_order.sql

@@ -0,0 +1,6 @@
+UPDATE reactionroles_message_cleanup
+SET next_attempt_at = created_at
+WHERE next_attempt_at IS NULL;
+
+ALTER TABLE reactionroles_message_cleanup
+  ALTER COLUMN next_attempt_at SET NOT NULL;

package/migrations/0003_persistent_reactions.sql

@@ -0,0 +1,37 @@
+ALTER TABLE reactionroles_panels
+  ADD COLUMN IF NOT EXISTS persistent_reactions boolean NOT NULL DEFAULT true;
+
+DO $$
+DECLARE
+  constraint_name text;
+BEGIN
+  FOR constraint_name IN
+    SELECT conname
+    FROM pg_constraint
+    WHERE conrelid = 'reactionroles_panels'::regclass
+      AND contype = 'c'
+      AND conname <> 'reactionroles_panels_reaction_selection_check'
+      AND pg_get_constraintdef(oid) LIKE '%control_type%reactions%selection_mode%'
+  LOOP
+    EXECUTE format(
+      'ALTER TABLE reactionroles_panels DROP CONSTRAINT %I',
+      constraint_name
+    );
+  END LOOP;
+
+  IF NOT EXISTS (
+    SELECT 1
+    FROM pg_constraint
+    WHERE conrelid = 'reactionroles_panels'::regclass
+      AND conname = 'reactionroles_panels_reaction_selection_check'
+  ) THEN
+    ALTER TABLE reactionroles_panels
+      ADD CONSTRAINT reactionroles_panels_reaction_selection_check
+      CHECK (
+        control_type <> 'reactions'
+        OR selection_mode <> 'one_only'
+        OR persistent_reactions = false
+      );
+  END IF;
+END
+$$;

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@helyx/module-reactionroles",
+  "version": "1.0.1",
+  "description": "Configurable self-service Discord role panels for Helyx.",
+  "keywords": [
+    "helyx",
+    "discord",
+    "roles",
+    "module"
+  ],
+  "private": false,
+  "license": "HSAL 1.0",
+  "homepage": "https://helyx.gg/modules/",
+  "bugs": {
+    "url": "https://github.com/ZyC0R3/Helyx/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZyC0R3/Helyx.git",
+    "directory": "modules/reactionroles"
+  },
+  "engines": {
+    "node": ">=24 <27",
+    "npm": ">=11"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "!dist/*.tsbuildinfo",
+    "!dist/**/*.map",
+    "migrations",
+    "manifest.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  },
+  "dependencies": {
+    "@helyx/module-manifest": "0.4.2",
+    "@helyx/sdk": "0.3.4"
+  }
+}