@helyx/module-reactionroles 1.0.1

package/dist/panel-service.js

@@ -0,0 +1,961 @@
+import { DashboardActionValidationError, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { randomUUID } from "node:crypto";
+import { canonicaliseEmoji, panelMessageDraft, validatePanelDraft, } from "./builder.js";
+import { MODULE_ID } from "./constants.js";
+import { ReactionRolePanelRepository } from "./records.js";
+const MAX_ACTIVE_CACHE = 10_000;
+const ACTIVE_CACHE_TTL_MS = 60_000;
+const NEGATIVE_CACHE_TTL_MS = 15_000;
+const MAX_CONCURRENT_CACHE_LOADS = 1_000;
+export class PanelSnapshotCache {
+    #panels = new Map();
+    #negative = new Map();
+    #loads = new Map();
+    #epochs = new Map();
+    #suspensions = new Map();
+    #deferred = new Map();
+    #saturated = false;
+    get(guildId, messageId) {
+        const key = cacheKey(guildId, messageId);
+        if (this.#suspensions.has(key))
+            return null;
+        return this.#panels.get(key)?.panel ?? null;
+    }
+    getFresh(guildId, messageId) {
+        const key = cacheKey(guildId, messageId);
+        if (this.#suspensions.has(key))
+            return null;
+        const cached = this.#panels.get(key);
+        return cached && Date.now() - cached.cachedAt <= ACTIVE_CACHE_TTL_MS
+            ? cached.panel
+            : null;
+    }
+    negativeHit(guildId, messageId) {
+        const key = cacheKey(guildId, messageId);
+        if (this.#suspensions.has(key))
+            return false;
+        const expiresAt = this.#negative.get(key);
+        if (!expiresAt)
+            return false;
+        if (expiresAt > Date.now())
+            return true;
+        this.#negative.delete(key);
+        this.#pruneEpoch(key);
+        return false;
+    }
+    markMissing(guildId, messageId) {
+        const key = cacheKey(guildId, messageId);
+        if (this.#negative.size >= MAX_CONCURRENT_CACHE_LOADS) {
+            const oldest = this.#negative.keys().next().value;
+            this.#negative.delete(oldest);
+            this.#pruneEpoch(oldest);
+        }
+        this.#negative.set(key, Date.now() + NEGATIVE_CACHE_TTL_MS);
+        this.#panels.delete(key);
+    }
+    load(guildId, messageId, operation) {
+        const key = cacheKey(guildId, messageId);
+        if (this.#suspensions.has(key))
+            return Promise.resolve(null);
+        const existing = this.#loads.get(key);
+        if (existing)
+            return existing;
+        if (this.#loads.size >= MAX_CONCURRENT_CACHE_LOADS)
+            return Promise.resolve(null);
+        const epoch = this.#epoch(key);
+        const pending = operation()
+            .then((panel) => {
+            if (this.#epochs.get(key) !== epoch || this.#suspensions.has(key))
+                return null;
+            if (panel)
+                this.put(panel);
+            else
+                this.markMissing(guildId, messageId);
+            return panel;
+        })
+            .finally(() => {
+            this.#loads.delete(key);
+            this.#pruneEpoch(key);
+        });
+        this.#loads.set(key, pending);
+        return pending;
+    }
+    put(panel) {
+        if (!panel.messageId ||
+            (panel.status !== "active" && panel.status !== "cleanup_pending")) {
+            this.remove(panel);
+            return;
+        }
+        const key = cacheKey(panel.guildId, panel.messageId);
+        if (this.#suspensions.has(key)) {
+            const deferred = this.#deferred.get(key);
+            if (!deferred || deferred.revision <= panel.revision)
+                this.#deferred.set(key, panel);
+            return;
+        }
+        const cached = this.#panels.get(key);
+        if (cached && cached.panel.revision > panel.revision)
+            return;
+        if (this.#panels.size >= MAX_ACTIVE_CACHE && !this.#panels.has(key)) {
+            this.#saturated = true;
+            return;
+        }
+        this.#panels.set(key, { panel, cachedAt: Date.now() });
+        this.#negative.delete(key);
+    }
+    remove(panel) {
+        if (!panel.messageId)
+            return;
+        const key = cacheKey(panel.guildId, panel.messageId);
+        this.#invalidate(key);
+        this.#deferred.delete(key);
+    }
+    suspend(panel) {
+        if (!panel.messageId) {
+            let resumed = false;
+            return (replacement) => {
+                if (resumed)
+                    return;
+                resumed = true;
+                if (replacement)
+                    this.put(replacement);
+            };
+        }
+        const key = cacheKey(panel.guildId, panel.messageId);
+        const token = {};
+        const suspensions = this.#suspensions.get(key) ?? new Set();
+        suspensions.add(token);
+        this.#suspensions.set(key, suspensions);
+        this.#invalidate(key);
+        let resumed = false;
+        return (replacement) => {
+            if (resumed)
+                return;
+            resumed = true;
+            const current = this.#suspensions.get(key);
+            current?.delete(token);
+            if (current?.size === 0) {
+                this.#suspensions.delete(key);
+                const deferred = this.#deferred.get(key);
+                this.#deferred.delete(key);
+                if (deferred)
+                    this.put(deferred);
+            }
+            if (replacement)
+                this.put(replacement);
+            this.#pruneEpoch(key);
+        };
+    }
+    clear() {
+        this.#panels.clear();
+        this.#negative.clear();
+        this.#loads.clear();
+        this.#epochs.clear();
+        this.#suspensions.clear();
+        this.#deferred.clear();
+        this.#saturated = false;
+    }
+    size() {
+        return this.#panels.size;
+    }
+    saturated() {
+        return this.#saturated;
+    }
+    #epoch(key) {
+        const epoch = this.#epochs.get(key) ?? {};
+        this.#epochs.set(key, epoch);
+        return epoch;
+    }
+    #invalidate(key) {
+        if (this.#loads.has(key) || this.#suspensions.has(key))
+            this.#epochs.set(key, {});
+        else
+            this.#epochs.delete(key);
+        this.#panels.delete(key);
+        this.#negative.delete(key);
+    }
+    #pruneEpoch(key) {
+        if (!this.#loads.has(key) &&
+            !this.#panels.has(key) &&
+            !this.#negative.has(key) &&
+            !this.#suspensions.has(key))
+            this.#epochs.delete(key);
+    }
+}
+export class ReactionRolePanelService {
+    cache;
+    constructor(cache) {
+        this.cache = cache;
+    }
+    repository(services) {
+        return new ReactionRolePanelRepository(services.get(HELYX_SERVICE_NAMES.records));
+    }
+    async warm(services) {
+        const repository = this.repository(services);
+        this.cache.clear();
+        for (const status of ["active", "cleanup_pending"]) {
+            let cursor;
+            do {
+                const page = await repository.listInteractive({
+                    status,
+                    ...(cursor ? { cursor } : {}),
+                    limit: 100,
+                });
+                for (const panel of page.panels)
+                    this.cache.put(panel);
+                cursor = page.nextCursor ?? undefined;
+            } while (cursor && !this.cache.saturated());
+            if (this.cache.saturated())
+                break;
+        }
+        return this.cache.size();
+    }
+    async recoverMessageCleanup(services) {
+        if (!services.has(HELYX_SERVICE_NAMES.discordOwnedMessages))
+            return { completed: 0, failed: 0, abandoned: 0 };
+        const repository = this.repository(services);
+        const pending = await repository.listPendingCleanup(100);
+        const messages = services.get(HELYX_SERVICE_NAMES.discordOwnedMessages);
+        let completed = 0;
+        let failed = 0;
+        let abandoned = 0;
+        for (const cleanup of pending) {
+            if (cleanup.attempts >= 10) {
+                abandoned += 1;
+                continue;
+            }
+            const claimed = await repository.claimCleanup(cleanup);
+            if (!claimed)
+                continue;
+            try {
+                await messages.deleteOwnedMessage({
+                    guildId: claimed.guildId,
+                    channelId: claimed.channelId,
+                    messageId: claimed.messageId,
+                });
+                if (!(await repository.completeCleanup(claimed))) {
+                    failed += 1;
+                    continue;
+                }
+                completed += 1;
+                if ((await repository.pendingCleanupCount(claimed.panelId)) === 0) {
+                    const panel = await repository.findById(claimed.guildId, claimed.panelId);
+                    if (panel?.status === "cleanup_pending")
+                        await repository.markStatus({
+                            panelId: panel.panelId,
+                            expectedRevision: panel.revision,
+                            status: "active",
+                        });
+                }
+            }
+            catch {
+                failed += 1;
+            }
+        }
+        return { completed, failed, abandoned };
+    }
+    getCached(guildId, messageId) {
+        return this.cache.get(guildId, messageId);
+    }
+    async resolveActive(guildId, messageId, services) {
+        const fresh = this.cache.getFresh(guildId, messageId);
+        if (fresh)
+            return fresh;
+        if (this.cache.negativeHit(guildId, messageId))
+            return null;
+        return this.cache.load(guildId, messageId, async () => {
+            const panel = await this.repository(services).findByMessage(guildId, messageId);
+            if (panel &&
+                (panel.status === "active" || panel.status === "cleanup_pending"))
+                return panel;
+            return null;
+        });
+    }
+    async list(context, input) {
+        const page = await this.repository(context.services).list({
+            guildId: context.guildId,
+            ...(input.cursor ? { cursor: decodeCursor(input.cursor) } : {}),
+            limit: Math.min(100, Math.max(1, input.limit)),
+        });
+        return {
+            items: page.panels.map(toSummary),
+            ...(page.nextCursor ? { nextCursor: encodeCursor(page.nextCursor) } : {}),
+        };
+    }
+    async read(context, resourceId) {
+        const panel = await this.repository(context.services).findById(context.guildId, resourceId);
+        return panel ? toDetail(panel) : null;
+    }
+    async preview(context, value) {
+        const draft = parseManagedDraft(value);
+        await validateDiscordResources(context.services, context.guildId, context.actor.userId, draft);
+        return buildPanel(context.services, draft).response;
+    }
+    async create(context, draftInput) {
+        const draft = validatePanelDraft(draftInput);
+        await validateDiscordResources(context.services, context.guildId, context.actorUserId, draft);
+        const repository = this.repository(context.services);
+        const panelId = randomUUID();
+        const entries = prepareEntries(draft.entries);
+        const staged = await repository.create({
+            panelId,
+            guildId: context.guildId,
+            actorUserId: context.actorUserId,
+            draft,
+            entries,
+        });
+        if (!staged)
+            throw new DashboardActionValidationError("A role panel with this identifier already exists");
+        let messageId;
+        let panel;
+        try {
+            const message = await context.sendToChannel(draft.channelId, buildPanel(context.services, draft).response);
+            messageId = message.messageId;
+            await seedReactions(context, draft, message.messageId);
+            const pending = await repository.findById(context.guildId, panelId);
+            if (!pending)
+                throw new Error("Staged role panel could not be reloaded");
+            const activated = await repository.update({
+                panel: pending,
+                actorUserId: context.actorUserId,
+                draft,
+                messageId: message.messageId,
+                status: "active",
+                entries,
+            });
+            if (!activated)
+                throw new Error("Role panel activation conflicted");
+            const published = await repository.findById(context.guildId, panelId);
+            if (!published)
+                throw new Error("Published role panel could not be reloaded");
+            panel = published;
+        }
+        catch (error) {
+            let cleanupPending = false;
+            if (messageId) {
+                try {
+                    await context.deleteChannelMessage(draft.channelId, messageId);
+                }
+                catch {
+                    cleanupPending = await repository
+                        .recordCleanup({
+                        guildId: context.guildId,
+                        panelId,
+                        channelId: draft.channelId,
+                        messageId,
+                        reason: "rollback",
+                    })
+                        .catch(() => false);
+                }
+            }
+            if (cleanupPending) {
+                const failed = await repository
+                    .findById(context.guildId, panelId)
+                    .catch(() => null);
+                if (failed)
+                    await this.audit(context, "reactionroles.panel.publication.failed", failed, "cleanup_pending").catch(() => undefined);
+            }
+            await repository
+                .remove(panelId, 1, context.actorUserId)
+                .catch(() => false);
+            throw error;
+        }
+        this.cache.put(panel);
+        await this.audit(context, "reactionroles.panel.created", panel);
+        await emitLog(context.services, context.guildId, {
+            eventId: "reaction-role-panel-created",
+            summary: "A Reaction Roles panel was created.",
+            panelId,
+        });
+        return panel;
+    }
+    async update(context, input) {
+        const repository = this.repository(context.services);
+        const current = await repository.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.");
+        const draft = validatePanelDraft(input.draft);
+        await validateDiscordResources(context.services, context.guildId, context.actorUserId, draft);
+        const entries = prepareEntries(draft.entries, current);
+        const replace = input.replacementAction !== undefined ||
+            current.status === "message_missing" ||
+            requiresReplacement(current, draft);
+        let cleanupPending = false;
+        const resumeCache = this.cache.suspend(current);
+        let safeFallback = current;
+        let saved;
+        try {
+            if (!current.messageId || replace) {
+                const replacement = await context.sendToChannel(draft.channelId, buildPanel(context.services, draft).response);
+                try {
+                    await seedReactions(context, draft, replacement.messageId);
+                    safeFallback = null;
+                    const applied = await repository.update({
+                        panel: current,
+                        actorUserId: context.actorUserId,
+                        draft,
+                        messageId: replacement.messageId,
+                        status: "active",
+                        entries,
+                    });
+                    if (!applied) {
+                        safeFallback = await repository.findById(context.guildId, current.panelId);
+                        throw new DashboardActionValidationError("This role panel changed in another session. Reload and try again.");
+                    }
+                }
+                catch (error) {
+                    await context
+                        .deleteChannelMessage(draft.channelId, replacement.messageId)
+                        .catch(() => undefined);
+                    throw error;
+                }
+                if (current.messageId && current.status !== "message_missing") {
+                    try {
+                        await context.deleteChannelMessage(current.channelId, current.messageId);
+                    }
+                    catch {
+                        cleanupPending = true;
+                        await repository.recordCleanup({
+                            guildId: context.guildId,
+                            panelId: current.panelId,
+                            channelId: current.channelId,
+                            messageId: current.messageId,
+                            reason: "replacement",
+                        });
+                    }
+                }
+            }
+            else {
+                await context.editChannelMessage(current.channelId, current.messageId, buildPanel(context.services, draft).response);
+                let applied;
+                try {
+                    safeFallback = null;
+                    applied = await repository.update({
+                        panel: current,
+                        actorUserId: context.actorUserId,
+                        draft,
+                        messageId: current.messageId,
+                        status: "active",
+                        entries,
+                    });
+                }
+                catch (error) {
+                    await context
+                        .editChannelMessage(current.channelId, current.messageId, buildPanel(context.services, current).response)
+                        .catch(() => undefined);
+                    throw error;
+                }
+                if (!applied) {
+                    const latest = await repository.findById(context.guildId, current.panelId);
+                    safeFallback = latest;
+                    if (latest?.messageId === current.messageId)
+                        await context
+                            .editChannelMessage(latest.channelId, latest.messageId, buildPanel(context.services, latest).response)
+                            .catch(() => undefined);
+                    throw new DashboardActionValidationError("This role panel changed in another session. Reload and try again.");
+                }
+            }
+            const reloaded = await repository.findById(context.guildId, current.panelId);
+            if (!reloaded)
+                throw new Error("Updated role panel could not be reloaded");
+            saved = reloaded;
+            if (cleanupPending) {
+                const marked = await repository.markStatus({
+                    panelId: saved.panelId,
+                    expectedRevision: saved.revision,
+                    actorUserId: context.actorUserId,
+                    status: "cleanup_pending",
+                });
+                if (marked) {
+                    saved =
+                        (await repository.findById(context.guildId, current.panelId)) ??
+                            saved;
+                }
+            }
+            resumeCache(saved);
+        }
+        catch (error) {
+            resumeCache(safeFallback);
+            throw error;
+        }
+        await this.audit(context, "reactionroles.panel.updated", saved, cleanupPending ? "cleanup_pending" : "success");
+        await emitLog(context.services, context.guildId, {
+            eventId: "reaction-role-panel-updated",
+            summary: "A Reaction Roles panel was updated.",
+            panelId: saved.panelId,
+        });
+        if (input.replacementAction === "repair") {
+            await this.audit(context, "reactionroles.panel.repaired", saved);
+            await emitLog(context.services, context.guildId, {
+                eventId: "reaction-role-panel-repaired",
+                summary: "A Reaction Roles panel was repaired.",
+                panelId: saved.panelId,
+            });
+        }
+        else if (replace) {
+            await this.audit(context, "reactionroles.panel.reposted", saved);
+            await emitLog(context.services, context.guildId, {
+                eventId: "reaction-role-panel-reposted",
+                summary: "A Reaction Roles panel was reposted.",
+                panelId: saved.panelId,
+            });
+        }
+        if (cleanupPending)
+            await this.audit(context, "reactionroles.panel.cleanup.failed", saved, "cleanup_pending");
+        return saved;
+    }
+    async delete(context, panelId, expectedRevision) {
+        const repository = this.repository(context.services);
+        const panel = await repository.findById(context.guildId, panelId);
+        if (!panel)
+            return false;
+        if (panel.revision !== expectedRevision)
+            throw new DashboardActionValidationError("This role panel changed in another session. Reload and try again.");
+        const claimed = await repository.claimDeleting(panel.panelId, panel.revision, context.actorUserId);
+        if (!claimed)
+            throw new DashboardActionValidationError("This role panel changed in another session. Reload and try again.");
+        this.cache.remove(panel);
+        let cleanupPending = false;
+        if (panel.messageId) {
+            try {
+                await context.deleteChannelMessage(panel.channelId, panel.messageId);
+            }
+            catch {
+                cleanupPending = await repository.recordCleanup({
+                    guildId: context.guildId,
+                    panelId: panel.panelId,
+                    channelId: panel.channelId,
+                    messageId: panel.messageId,
+                    reason: "delete",
+                });
+            }
+        }
+        if (!(await repository.deleteClaimed(panel.panelId)))
+            throw new Error("The claimed role panel could not be deleted");
+        await this.audit(context, "reactionroles.panel.deleted", panel, cleanupPending ? "cleanup_pending" : "success");
+        if (cleanupPending)
+            await this.audit(context, "reactionroles.panel.cleanup.failed", panel, "cleanup_pending");
+        await emitLog(context.services, context.guildId, {
+            eventId: "reaction-role-panel-deleted",
+            summary: "A Reaction Roles panel was deleted.",
+            panelId,
+        });
+        return true;
+    }
+    async repair(context, panelId, expectedRevision, repost) {
+        await this.recoverMessageCleanup(context.services);
+        const repository = this.repository(context.services);
+        const panel = await repository.findById(context.guildId, panelId);
+        if (!panel)
+            throw new DashboardActionValidationError("Role panel was not found");
+        if (panel.revision !== expectedRevision)
+            throw new DashboardActionValidationError("This role panel changed in another session. Reload and try again.");
+        await validateDiscordResources(context.services, context.guildId, context.actorUserId, panel);
+        if (repost || !panel.messageId || panel.status === "message_missing")
+            return this.update(context, {
+                resourceId: panel.panelId,
+                expectedRevision: panel.revision,
+                draft: panel,
+                replacementAction: repost ? "repost" : "repair",
+            });
+        await context.editChannelMessage(panel.channelId, panel.messageId, buildPanel(context.services, panel).response);
+        await seedReactions(context, panel, panel.messageId);
+        const repaired = await repository.markStatus({
+            panelId,
+            expectedRevision,
+            actorUserId: context.actorUserId,
+            status: (await repository.pendingCleanupCount(panelId)) > 0
+                ? "cleanup_pending"
+                : "active",
+        });
+        if (!repaired)
+            throw new DashboardActionValidationError("This role panel changed in another session. Reload and try again.");
+        const saved = await repository.findById(context.guildId, panelId);
+        if (!saved)
+            throw new Error("Repaired role panel could not be reloaded");
+        this.cache.put(saved);
+        await this.audit(context, "reactionroles.panel.repaired", saved);
+        await emitLog(context.services, context.guildId, {
+            eventId: "reaction-role-panel-repaired",
+            summary: "A Reaction Roles panel was repaired.",
+            panelId,
+        });
+        return saved;
+    }
+    async markMessageMissing(input) {
+        const repository = this.repository(input.services);
+        const panel = this.cache.get(input.guildId, input.messageId) ??
+            (await repository.findByMessage(input.guildId, input.messageId));
+        if (!panel)
+            return;
+        if (panel.status === "deleting")
+            return;
+        const changed = await repository.markStatus({
+            panelId: panel.panelId,
+            expectedRevision: panel.revision,
+            status: "message_missing",
+        });
+        if (changed)
+            this.cache.remove(panel);
+    }
+    async markNeedsAttention(panel, services) {
+        if (panel.status === "deleting" ||
+            panel.status === "message_missing" ||
+            panel.status === "needs_attention")
+            return false;
+        const changed = await this.repository(services).markStatus({
+            panelId: panel.panelId,
+            expectedRevision: panel.revision,
+            status: "needs_attention",
+        });
+        if (changed)
+            this.cache.remove(panel);
+        return changed;
+    }
+    async handleChannelLifecycle(input) {
+        const repository = this.repository(input.services);
+        const candidates = await repository.listByChannel(input.guildId, input.channelId);
+        const inspection = input.deleted
+            ? null
+            : await input.services
+                .get(HELYX_SERVICE_NAMES.discordResources)
+                .inspectChannel({
+                guildId: input.guildId,
+                channelId: input.channelId,
+            });
+        let changed = 0;
+        for (const panel of candidates) {
+            if (input.deleted ||
+                !inspection ||
+                !channelSupportsPanel(inspection, panel))
+                changed += (await this.markNeedsAttention(panel, input.services))
+                    ? 1
+                    : 0;
+        }
+        return changed;
+    }
+    async handleRoleLifecycle(input) {
+        const repository = this.repository(input.services);
+        const candidates = await repository.listByRole(input.guildId, input.roleId);
+        const inspection = input.deleted
+            ? null
+            : await input.services
+                .get(HELYX_SERVICE_NAMES.discordResources)
+                .inspectRole({
+                guildId: input.guildId,
+                roleId: input.roleId,
+            });
+        if (!input.deleted &&
+            inspection?.exists &&
+            inspection.guildMatches &&
+            inspection.assignable &&
+            !inspection.managed &&
+            !inspection.everyone &&
+            inspection.dangerousPermissionNames.length === 0)
+            return 0;
+        let changed = 0;
+        for (const panel of candidates)
+            changed += (await this.markNeedsAttention(panel, input.services)) ? 1 : 0;
+        return changed;
+    }
+    async handleEmojiLifecycle(input) {
+        const candidates = await this.repository(input.services).listByEmoji(input.guildId, input.emojiId);
+        const resources = input.services.get(HELYX_SERVICE_NAMES.discordResources);
+        let changed = 0;
+        for (const panel of candidates) {
+            const entry = panel.entries.find(({ emoji }) => emoji && canonicaliseEmoji(emoji).id === input.emojiId);
+            const invalid = input.deleted ||
+                !entry?.emoji ||
+                !(await resources.inspectEmoji({
+                    guildId: input.guildId,
+                    emojiIdentifier: entry.emoji,
+                })).usable;
+            if (invalid)
+                changed += (await this.markNeedsAttention(panel, input.services))
+                    ? 1
+                    : 0;
+        }
+        return changed;
+    }
+    async audit(context, action, panel, result = "success") {
+        const audit = context.services.get(HELYX_SERVICE_NAMES.audit);
+        await audit.append({
+            guildId: context.guildId,
+            actorUserId: context.actorUserId,
+            action,
+            source: context.source,
+            ...(context.correlationId
+                ? { correlationId: context.correlationId }
+                : {}),
+            moduleId: MODULE_ID,
+            targetType: "reaction_role_panel",
+            targetId: panel.panelId,
+            metadata: {
+                channelId: panel.channelId,
+                revision: panel.revision,
+                controlType: panel.controlType,
+                status: panel.status,
+                entryCount: panel.entries.length,
+                result,
+            },
+        });
+    }
+}
+export function managedContext(context) {
+    return {
+        guildId: context.guildId,
+        actorUserId: context.actor.userId,
+        source: "dashboard",
+        services: context.services,
+        correlationId: context.correlationId,
+        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 parseManagedDraft(value) {
+    const entriesValue = value.entries;
+    if (!Array.isArray(entriesValue))
+        throw new DashboardActionValidationError("Add at least one role entry before publishing");
+    const entries = entriesValue.map((item, index) => {
+        if (!isManagedObject(item))
+            throw new DashboardActionValidationError(`Role entry ${index + 1} is invalid`);
+        return {
+            entryId: optionalString(item.entryId) ??
+                `entry-${randomUUID().replaceAll("-", "")}`,
+            roleId: requiredManagedString(item.roleId, "Role"),
+            nameplate: requiredManagedString(item.nameplate, "Role label"),
+            ...(optionalString(item.emoji)
+                ? { emoji: optionalString(item.emoji) }
+                : {}),
+            ...(optionalString(item.buttonStyle)
+                ? {
+                    buttonStyle: requiredLiteral(optionalString(item.buttonStyle), ["primary", "secondary", "success", "danger"], "button colour"),
+                }
+                : {}),
+        };
+    });
+    try {
+        return validatePanelDraft({
+            channelId: requiredManagedString(value.channelId, "Destination channel"),
+            title: requiredManagedString(value.title, "Title"),
+            messageBody: requiredManagedString(value.messageBody, "Message"),
+            messageStyle: requiredLiteral(requiredManagedString(value.messageStyle, "Message style"), ["text", "embed"], "message style"),
+            controlType: requiredLiteral(requiredManagedString(value.controlType, "Role controls"), ["buttons", "dropdown", "reactions"], "role controls"),
+            selectionMode: requiredLiteral(requiredManagedString(value.selectionMode, "Selection mode"), ["multiple", "one_only"], "selection mode"),
+            persistentReactions: typeof value.persistentReactions === "boolean"
+                ? value.persistentReactions
+                : true,
+            ...(typeof value.embedColour === "number"
+                ? { embedColour: value.embedColour }
+                : {}),
+            ...(optionalString(value.dropdownPlaceholder)
+                ? { dropdownPlaceholder: optionalString(value.dropdownPlaceholder) }
+                : {}),
+            entries,
+        });
+    }
+    catch (error) {
+        if (error instanceof DashboardActionValidationError)
+            throw error;
+        throw new DashboardActionValidationError(error instanceof Error ? error.message : "Role panel draft is invalid");
+    }
+}
+export function toDetail(panel) {
+    return {
+        ...toSummary(panel),
+        value: {
+            channelId: panel.channelId,
+            title: panel.title,
+            messageBody: panel.messageBody,
+            messageStyle: panel.messageStyle,
+            controlType: panel.controlType,
+            selectionMode: panel.selectionMode,
+            persistentReactions: panel.persistentReactions,
+            ...(panel.embedColour === undefined
+                ? {}
+                : { embedColour: panel.embedColour }),
+            ...(panel.dropdownPlaceholder === undefined
+                ? {}
+                : { dropdownPlaceholder: panel.dropdownPlaceholder }),
+            entries: panel.entries.map((entry) => ({
+                entryId: entry.entryId,
+                roleId: entry.roleId,
+                nameplate: entry.nameplate,
+                ...(entry.emoji ? { emoji: entry.emoji } : {}),
+                ...(entry.buttonStyle ? { buttonStyle: entry.buttonStyle } : {}),
+            })),
+        },
+    };
+}
+function toSummary(panel) {
+    return {
+        id: panel.panelId,
+        revision: panel.revision,
+        status: panel.status,
+        title: panel.title,
+        description: `${panel.entries.length} role ${panel.entries.length === 1 ? "entry" : "entries"} · ${panel.controlType}`,
+        updatedAt: panel.updatedAt.toISOString(),
+    };
+}
+async function validateDiscordResources(services, guildId, actorUserId, draft) {
+    const resources = services.get(HELYX_SERVICE_NAMES.discordResources);
+    const channel = await resources.inspectChannel({
+        guildId,
+        channelId: draft.channelId,
+    });
+    if (!channel.exists || !channel.guildMatches || !channel.viewable)
+        throw new DashboardActionValidationError("Helyx cannot view the selected destination channel");
+    if (!channel.sendMessages)
+        throw new DashboardActionValidationError("Helyx cannot send messages in the selected destination channel");
+    if (draft.messageStyle === "embed" &&
+        !channel.effectivePermissionNames.includes("EMBED_LINKS"))
+        throw new DashboardActionValidationError("Helyx needs Embed Links in the selected destination channel");
+    if (draft.controlType === "reactions" &&
+        (!channel.addReactions || !channel.readMessageHistory))
+        throw new DashboardActionValidationError("Emoji-reaction panels need Add Reactions and Read Message History in the selected channel");
+    if (draft.controlType === "reactions" &&
+        !draft.persistentReactions &&
+        !channel.effectivePermissionNames.includes("MANAGE_MESSAGES"))
+        throw new DashboardActionValidationError("Non-persistent emoji reactions need Manage Messages in the selected channel");
+    for (const entry of draft.entries) {
+        const role = await resources.inspectRole({
+            guildId,
+            roleId: entry.roleId,
+            actorUserId,
+        });
+        if (!role.exists || !role.guildMatches)
+            throw new DashboardActionValidationError(`The role for "${entry.nameplate}" is no longer available in this server`);
+        if (role.everyone)
+            throw new DashboardActionValidationError(`@everyone cannot be made self-assignable for "${entry.nameplate}"`);
+        if (role.managed)
+            throw new DashboardActionValidationError(`The role for "${entry.nameplate}" is managed by Discord or an integration and cannot be assigned`);
+        if (role.dangerousPermissionNames.length > 0)
+            throw new DashboardActionValidationError(`The role for "${entry.nameplate}" grants administrative or moderation permissions and cannot be self-assigned`);
+        if (role.hierarchy === "missing-manage-roles")
+            throw new DashboardActionValidationError(`Helyx needs Manage Roles before it can assign "${entry.nameplate}"`);
+        if (role.hierarchy === "above-helyx" || !role.assignable)
+            throw new DashboardActionValidationError(`Move Helyx's highest role above the role for "${entry.nameplate}", then try again`);
+        if (role.hierarchy === "above-actor" || !role.actorAssignable)
+            throw new DashboardActionValidationError(`Your highest role must be above the role for "${entry.nameplate}"`);
+        if (entry.emoji) {
+            const emoji = await resources.inspectEmoji({
+                guildId,
+                emojiIdentifier: entry.emoji,
+            });
+            if (!emoji.exists || !emoji.guildMatches || !emoji.usable)
+                throw new DashboardActionValidationError(`The emoji for "${entry.nameplate}" is not available in this server`);
+        }
+    }
+}
+function channelSupportsPanel(channel, panel) {
+    return (channel.exists &&
+        channel.guildMatches &&
+        channel.viewable &&
+        channel.sendMessages &&
+        (panel.messageStyle !== "embed" ||
+            channel.effectivePermissionNames.includes("EMBED_LINKS")) &&
+        (panel.controlType !== "reactions" ||
+            (channel.addReactions &&
+                channel.readMessageHistory &&
+                (panel.persistentReactions ||
+                    channel.effectivePermissionNames.includes("MANAGE_MESSAGES")))));
+}
+function prepareEntries(entries, existing) {
+    return entries.map((entry) => {
+        const prior = existing?.entries.find((candidate) => candidate.roleId === entry.roleId);
+        return {
+            entryId: prior?.entryId ?? entry.entryId,
+            roleId: entry.roleId,
+            nameplate: entry.nameplate,
+            emoji: entry.emoji ? canonicaliseEmoji(entry.emoji) : null,
+            buttonStyle: entry.buttonStyle ?? null,
+        };
+    });
+}
+async function seedReactions(context, draft, messageId) {
+    for (const emojiIdentifier of buildPanel(context.services, draft)
+        .reactionSeeds)
+        await context.addChannelMessageReaction(draft.channelId, messageId, emojiIdentifier);
+}
+function buildPanel(services, draft) {
+    return services
+        .get(HELYX_SERVICE_NAMES.messageBuilder)
+        .build(panelMessageDraft(draft));
+}
+function requiresReplacement(current, draft) {
+    if (current.channelId !== draft.channelId)
+        return true;
+    if (current.controlType !== "reactions" && draft.controlType !== "reactions")
+        return false;
+    if (current.controlType !== draft.controlType)
+        return true;
+    return (current.entries.some((entry, index) => {
+        const next = draft.entries[index];
+        return (!next || entry.roleId !== next.roleId || entry.emoji !== next.emoji);
+    }) || current.entries.length !== draft.entries.length);
+}
+async function emitLog(services, guildId, input) {
+    if (!services.has(HELYX_SERVICE_NAMES.moduleLogging))
+        return;
+    await services
+        .get(HELYX_SERVICE_NAMES.moduleLogging)
+        .emit({
+        guildId,
+        moduleId: MODULE_ID,
+        eventId: input.eventId,
+        summary: input.summary,
+        details: [{ label: "Panel", value: input.panelId }],
+    })
+        .catch(() => undefined);
+}
+function encodeCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor.map((value) => value instanceof Date ? { date: value.toISOString() } : { value }))).toString("base64url");
+}
+function decodeCursor(cursor) {
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (!Array.isArray(parsed) || parsed.length !== 2)
+            throw new Error("invalid");
+        return parsed.map((item) => {
+            if (!isManagedObject(item))
+                throw new Error("invalid");
+            if (typeof item.date === "string") {
+                const date = new Date(item.date);
+                if (Number.isNaN(date.getTime()))
+                    throw new Error("invalid");
+                return date;
+            }
+            if (typeof item.value !== "string" &&
+                typeof item.value !== "boolean" &&
+                typeof item.value !== "number")
+                throw new Error("invalid");
+            return item.value;
+        });
+    }
+    catch {
+        throw new DashboardActionValidationError("The role-panel page cursor is invalid");
+    }
+}
+function cacheKey(guildId, messageId) {
+    return `${guildId}:${messageId}`;
+}
+function isManagedObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requiredManagedString(value, label) {
+    if (typeof value !== "string")
+        throw new DashboardActionValidationError(`${label} is required`);
+    return value;
+}
+function optionalString(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}
+function requiredLiteral(value, allowed, label) {
+    if (!allowed.includes(value))
+        throw new DashboardActionValidationError(`Choose a valid ${label}`);
+    return value;
+}