@helyx/module-reactionroles 1.0.15 → 1.0.18

package/dist/panel-support.d.ts

@@ -0,0 +1,35 @@
+import { type DiscordResourceInspectionService, type ManagedResourceContext, type ManagedResourceDetail, type ManagedResourceValue, type MessageBuilderResult, type ServiceAccess } from "@helyx/sdk";
+import { type PanelDraft, type PanelEntryDraft } from "./builder.js";
+import type { PanelMutationContext } from "./panel-service.js";
+import type { StoredPanel } from "./records.js";
+export declare function managedContext(context: ManagedResourceContext): PanelMutationContext;
+export declare function parseManagedDraft(value: Readonly<Record<string, ManagedResourceValue>>): PanelDraft;
+export declare function toDetail(panel: StoredPanel): ManagedResourceDetail;
+export declare function toSummary(panel: StoredPanel): {
+    id: string;
+    revision: number;
+    status: import("./record-schema.js").PanelStatus;
+    title: string;
+    description: string;
+    updatedAt: string;
+};
+export declare function validateDiscordResources(services: ServiceAccess, guildId: string, actorUserId: string, draft: PanelDraft): Promise<void>;
+export declare function channelSupportsPanel(channel: Awaited<ReturnType<DiscordResourceInspectionService["inspectChannel"]>>, panel: Pick<PanelDraft, "messageStyle" | "controlType" | "persistentReactions">): boolean;
+export declare function prepareEntries(entries: readonly PanelEntryDraft[], existing?: StoredPanel): {
+    entryId: string;
+    roleId: string;
+    nameplate: string;
+    emoji: import("./builder.js").CanonicalEmoji | null;
+    buttonStyle: import("./builder.js").PanelButtonStyle | null;
+}[];
+export declare function seedReactions(context: Pick<PanelMutationContext, "services" | "addChannelMessageReaction">, draft: PanelDraft, messageId: string): Promise<void>;
+export declare function buildPanel(services: ServiceAccess, draft: PanelDraft): MessageBuilderResult;
+export declare function requiresReplacement(current: StoredPanel, draft: PanelDraft): boolean;
+export declare function emitLog(services: ServiceAccess, guildId: string, input: {
+    eventId: string;
+    summary: string;
+    panelId: string;
+}): Promise<void>;
+export declare function appendPanelAudit(context: PanelMutationContext, action: string, panel: StoredPanel, result?: "success" | "cleanup_pending"): Promise<void>;
+export declare function encodeCursor(cursor: readonly (string | boolean | number | Date)[]): string;
+export declare function decodeCursor(cursor: string): readonly (string | boolean | number | Date)[];

package/dist/panel-support.js

@@ -0,0 +1,291 @@
+import { DashboardActionValidationError, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { randomUUID } from "node:crypto";
+import { canonicaliseEmoji, panelMessageDraft, PanelDraftValidationError, validatePanelDraft, } from "./builder.js";
+import { REACTION_ROLES_MODULE_ID } from "./constants.js";
+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;
+        if (error instanceof PanelDraftValidationError)
+            throw new DashboardActionValidationError(error.message);
+        throw new DashboardActionValidationError("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 } : {}),
+            })),
+        },
+    };
+}
+export 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(),
+    };
+}
+export 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,
+        });
+        validateRole(entry.nameplate, role);
+        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 validateRole(nameplate, role) {
+    if (!role.exists || !role.guildMatches)
+        throw new DashboardActionValidationError(`The role for "${nameplate}" is no longer available in this server`);
+    if (role.everyone)
+        throw new DashboardActionValidationError(`@everyone cannot be made self-assignable for "${nameplate}"`);
+    if (role.managed)
+        throw new DashboardActionValidationError(`The role for "${nameplate}" is managed by Discord or an integration and cannot be assigned`);
+    if (role.dangerousPermissionNames.length > 0)
+        throw new DashboardActionValidationError(`The role for "${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 "${nameplate}"`);
+    if (role.hierarchy === "above-helyx" || !role.assignable)
+        throw new DashboardActionValidationError(`Move Helyx's highest role above the role for "${nameplate}", then try again`);
+    if (role.hierarchy === "above-actor" || !role.actorAssignable)
+        throw new DashboardActionValidationError(`Your highest role must be above the role for "${nameplate}"`);
+}
+export 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")))));
+}
+export 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,
+        };
+    });
+}
+export async function seedReactions(context, draft, messageId) {
+    for (const emojiIdentifier of buildPanel(context.services, draft)
+        .reactionSeeds)
+        await context.addChannelMessageReaction(draft.channelId, messageId, emojiIdentifier);
+}
+export function buildPanel(services, draft) {
+    return services
+        .get(HELYX_SERVICE_NAMES.messageBuilder)
+        .build(panelMessageDraft(draft));
+}
+export 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);
+}
+export async function emitLog(services, guildId, input) {
+    if (!services.has(HELYX_SERVICE_NAMES.moduleLogging))
+        return;
+    await services
+        .get(HELYX_SERVICE_NAMES.moduleLogging)
+        .emit({
+        guildId,
+        moduleId: REACTION_ROLES_MODULE_ID,
+        eventId: input.eventId,
+        summary: input.summary,
+        details: [{ label: "Panel", value: input.panelId }],
+    })
+        .catch(() => undefined);
+}
+export async function appendPanelAudit(context, action, panel, result = "success") {
+    try {
+        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: REACTION_ROLES_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,
+            },
+        });
+    }
+    catch {
+        // The Discord/database mutation is already committed. Audit delivery must
+        // not misreport that customer operation as failed.
+    }
+}
+export function encodeCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor.map((value) => value instanceof Date ? { date: value.toISOString() } : { value }))).toString("base64url");
+}
+export function decodeCursor(cursor) {
+    try {
+        const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (!Array.isArray(parsed) || parsed.length !== 2)
+            throw new Error();
+        return parsed.map((item) => {
+            if (!isManagedObject(item))
+                throw new Error();
+            if (typeof item.date === "string") {
+                const date = new Date(item.date);
+                if (Number.isNaN(date.getTime()))
+                    throw new Error();
+                return date;
+            }
+            if (typeof item.value !== "string" &&
+                typeof item.value !== "boolean" &&
+                typeof item.value !== "number")
+                throw new Error();
+            return item.value;
+        });
+    }
+    catch {
+        throw new DashboardActionValidationError("The role-panel page cursor is invalid");
+    }
+}
+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;
+}

package/dist/permissions.d.ts

@@ -0,0 +1,2 @@
+import type { PermissionPolicy } from "@helyx/sdk";
+export declare const reactionRoleManagerPolicy: PermissionPolicy;

package/dist/permissions.js

@@ -0,0 +1,8 @@
+export const reactionRoleManagerPolicy = {
+    everyone: false,
+    requiredPermissions: ["MANAGE_GUILD"],
+    allowedRoleIds: [],
+    deniedRoleIds: [],
+    allowedUserIds: [],
+    deniedUserIds: [],
+};

package/dist/privacy.d.ts

@@ -0,0 +1,5 @@
+import { createPrivacyProvider, getModulePrivacyDeclaration } from "@helyx/sdk";
+export declare function createReactionRolePrivacy(manifest: Parameters<typeof getModulePrivacyDeclaration>[0]): {
+    providerVersion: number;
+    create: (executor: Parameters<typeof createPrivacyProvider>[0]["executor"]) => import("@helyx/sdk").PrivacyProvider;
+};

package/dist/privacy.js

@@ -0,0 +1,12 @@
+import { createPrivacyProvider, getModulePrivacyDeclaration } from "@helyx/sdk";
+import { REACTION_ROLES_MODULE_ID } from "./constants.js";
+export function createReactionRolePrivacy(manifest) {
+    return {
+        providerVersion: 1,
+        create: (executor) => createPrivacyProvider({
+            id: REACTION_ROLES_MODULE_ID,
+            declaration: getModulePrivacyDeclaration(manifest),
+            executor,
+        }),
+    };
+}

package/dist/record-mapping.d.ts

@@ -0,0 +1,28 @@
+import type { ModuleRecordValue, ModuleRecordWriteValue } from "@helyx/sdk";
+import type { CanonicalEmoji, PanelButtonStyle, PanelDraft } from "./builder.js";
+import type { PanelStatus, StoredPanel } from "./record-schema.js";
+export declare function panelValues(input: {
+    panelId: string;
+    guildId: string;
+    actorUserId: string;
+    draft: PanelDraft;
+    messageId?: string;
+    status: PanelStatus;
+    revision: number;
+    now: Date;
+}): Record<string, ModuleRecordWriteValue>;
+export declare function entryValues(panelId: string, entry: {
+    entryId: string;
+    roleId: string;
+    nameplate: string;
+    emoji: CanonicalEmoji | null;
+    buttonStyle: PanelButtonStyle | null;
+}, position: number, now: Date): Record<string, ModuleRecordWriteValue>;
+export declare function mapPanel(row: Readonly<Record<string, ModuleRecordValue>>, entries: readonly Readonly<Record<string, ModuleRecordValue>>[]): StoredPanel;
+export declare function requiredString(row: Readonly<Record<string, ModuleRecordValue>>, field: string): string;
+export declare function nullableString(row: Readonly<Record<string, ModuleRecordValue>>, field: string): string | null;
+export declare function requiredNumber(row: Readonly<Record<string, ModuleRecordValue>>, field: string): number;
+export declare function optionalBoolean(row: Readonly<Record<string, ModuleRecordValue>>, field: string, fallback: boolean): boolean;
+export declare function requiredDate(row: Readonly<Record<string, ModuleRecordValue>>, field: string): Date;
+export declare function requiredEnum<const T extends string>(row: Readonly<Record<string, ModuleRecordValue>>, field: string, values: readonly T[]): T;
+export declare function requiredLiteral<const T extends string>(value: string, values: readonly T[]): T;

package/dist/record-mapping.js

@@ -0,0 +1,161 @@
+export function panelValues(input) {
+    return {
+        panel_id: input.panelId,
+        guild_id: input.guildId,
+        channel_id: input.draft.channelId,
+        ...(input.messageId ? { message_id: input.messageId } : {}),
+        title: input.draft.title,
+        message_body: input.draft.messageBody,
+        message_style: input.draft.messageStyle,
+        control_type: input.draft.controlType,
+        selection_mode: input.draft.selectionMode,
+        persistent_reactions: input.draft.persistentReactions,
+        ...(input.draft.embedColour === undefined
+            ? {}
+            : { embed_colour: input.draft.embedColour }),
+        ...(input.draft.dropdownPlaceholder === undefined
+            ? {}
+            : { dropdown_placeholder: input.draft.dropdownPlaceholder }),
+        status: input.status,
+        revision: input.revision,
+        created_by_user_id: input.actorUserId,
+        updated_by_user_id: input.actorUserId,
+        created_at: input.now,
+        updated_at: input.now,
+    };
+}
+export function entryValues(panelId, entry, position, now) {
+    return {
+        entry_id: entry.entryId,
+        panel_id: panelId,
+        position,
+        role_id: entry.roleId,
+        nameplate: entry.nameplate,
+        ...(entry.emoji
+            ? {
+                emoji_kind: entry.emoji.kind,
+                emoji_name: entry.emoji.name,
+                ...(entry.emoji.id ? { emoji_id: entry.emoji.id } : {}),
+                emoji_animated: entry.emoji.animated,
+            }
+            : {}),
+        ...(entry.buttonStyle ? { button_style: entry.buttonStyle } : {}),
+        created_at: now,
+        updated_at: now,
+    };
+}
+export function mapPanel(row, entries) {
+    return {
+        panelId: requiredString(row, "panel_id"),
+        guildId: requiredString(row, "guild_id"),
+        channelId: requiredString(row, "channel_id"),
+        messageId: nullableString(row, "message_id"),
+        title: requiredString(row, "title"),
+        messageBody: requiredString(row, "message_body"),
+        messageStyle: requiredEnum(row, "message_style", ["text", "embed"]),
+        controlType: requiredEnum(row, "control_type", [
+            "buttons",
+            "dropdown",
+            "reactions",
+        ]),
+        selectionMode: requiredEnum(row, "selection_mode", [
+            "multiple",
+            "one_only",
+        ]),
+        persistentReactions: optionalBoolean(row, "persistent_reactions", true),
+        ...(row.embed_colour === null
+            ? {}
+            : { embedColour: requiredNumber(row, "embed_colour") }),
+        ...(row.dropdown_placeholder === null
+            ? {}
+            : {
+                dropdownPlaceholder: requiredString(row, "dropdown_placeholder"),
+            }),
+        entries: entries.map((entry) => {
+            const emojiKind = nullableString(entry, "emoji_kind");
+            const emojiName = nullableString(entry, "emoji_name");
+            const emojiId = nullableString(entry, "emoji_id");
+            const emoji = emojiKind && emojiName
+                ? {
+                    kind: requiredLiteral(emojiKind, ["unicode", "custom"]),
+                    name: emojiName,
+                    ...(emojiId ? { id: emojiId } : {}),
+                    animated: entry.emoji_animated === true,
+                    identifier: emojiId ? `${emojiName}:${emojiId}` : emojiName,
+                    key: emojiId ? `custom:${emojiId}` : `unicode:${emojiName}`,
+                }
+                : null;
+            return {
+                entryId: requiredString(entry, "entry_id"),
+                roleId: requiredString(entry, "role_id"),
+                nameplate: requiredString(entry, "nameplate"),
+                ...(emoji ? { emoji: emoji.identifier } : {}),
+                ...(entry.button_style
+                    ? {
+                        buttonStyle: requiredEnum(entry, "button_style", [
+                            "primary",
+                            "secondary",
+                            "success",
+                            "danger",
+                        ]),
+                    }
+                    : {}),
+            };
+        }),
+        status: requiredEnum(row, "status", [
+            "pending",
+            "active",
+            "disabled",
+            "message_missing",
+            "needs_attention",
+            "cleanup_pending",
+            "deleting",
+        ]),
+        revision: requiredNumber(row, "revision"),
+        createdByUserId: nullableString(row, "created_by_user_id"),
+        updatedByUserId: nullableString(row, "updated_by_user_id"),
+        createdAt: requiredDate(row, "created_at"),
+        updatedAt: requiredDate(row, "updated_at"),
+    };
+}
+export function requiredString(row, field) {
+    const value = row[field];
+    if (typeof value !== "string" || value.length === 0)
+        throw new Error(`Invalid Reaction Roles record field: ${field}`);
+    return value;
+}
+export function nullableString(row, field) {
+    const value = row[field];
+    if (value === null || value === undefined)
+        return null;
+    return requiredString(row, field);
+}
+export function requiredNumber(row, field) {
+    const value = Number(row[field]);
+    if (!Number.isSafeInteger(value))
+        throw new Error(`Invalid Reaction Roles record field: ${field}`);
+    return value;
+}
+export function optionalBoolean(row, field, fallback) {
+    const value = row[field];
+    if (value === null || value === undefined)
+        return fallback;
+    if (typeof value !== "boolean")
+        throw new Error(`Invalid Reaction Roles record field: ${field}`);
+    return value;
+}
+export function requiredDate(row, field) {
+    const value = row[field];
+    const date = value instanceof Date ? value : new Date(String(value));
+    if (Number.isNaN(date.getTime()))
+        throw new Error(`Invalid Reaction Roles record field: ${field}`);
+    return date;
+}
+export function requiredEnum(row, field, values) {
+    return requiredLiteral(requiredString(row, field), values);
+}
+export function requiredLiteral(value, values) {
+    if (!values.includes(value))
+        throw new Error("Invalid Reaction Roles record enum");
+    return value;
+}