@helyx/module-reactionroles 1.0.15 → 1.0.18

package/dist/panel-cache.js

@@ -0,0 +1,197 @@
+export const PANEL_CACHE_LIMITS = {
+    active: 10_000,
+    negative: 1_000,
+    loads: 1_000,
+    activeTtlMs: 60_000,
+    negativeTtlMs: 15_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 <= PANEL_CACHE_LIMITS.activeTtlMs
+            ? 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 >= PANEL_CACHE_LIMITS.negative &&
+            !this.#negative.has(key)) {
+            const oldest = this.#negative.keys().next().value;
+            if (oldest) {
+                this.#negative.delete(oldest);
+                this.#pruneEpoch(oldest);
+            }
+        }
+        this.#negative.set(key, Date.now() + PANEL_CACHE_LIMITS.negativeTtlMs);
+        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 >= PANEL_CACHE_LIMITS.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(() => {
+            if (this.#loads.get(key) === pending)
+                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 >= PANEL_CACHE_LIMITS.active &&
+            !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)
+            return oneShotResume((replacement) => 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);
+        return oneShotResume((replacement) => {
+            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;
+    }
+    stats() {
+        return {
+            active: this.#panels.size,
+            negative: this.#negative.size,
+            loads: this.#loads.size,
+            suspended: this.#suspensions.size,
+            saturated: 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);
+    }
+}
+function cacheKey(guildId, messageId) {
+    return `${guildId}:${messageId}`;
+}
+function oneShotResume(operation) {
+    let resumed = false;
+    return (replacement) => {
+        if (resumed)
+            return;
+        resumed = true;
+        operation(replacement);
+    };
+}

package/dist/panel-create.d.ts

@@ -0,0 +1,10 @@
+import { type PanelDraft } from "./builder.js";
+import type { PanelSnapshotCache } from "./panel-cache.js";
+import type { PanelMutationContext } from "./panel-service.js";
+import type { ReactionRolePanelRepository, StoredPanel } from "./records.js";
+export declare function createPanel(input: {
+    cache: PanelSnapshotCache;
+    repository: ReactionRolePanelRepository;
+    context: PanelMutationContext;
+    draftInput: PanelDraft;
+}): Promise<StoredPanel>;

package/dist/panel-create.js

@@ -0,0 +1,80 @@
+import { DashboardActionValidationError } from "@helyx/sdk";
+import { randomUUID } from "node:crypto";
+import { validatePanelDraft } from "./builder.js";
+import { appendPanelAudit, buildPanel, emitLog, prepareEntries, seedReactions, validateDiscordResources, } from "./panel-support.js";
+export async function createPanel(input) {
+    const { cache, context, repository } = input;
+    const draft = validatePanelDraft(input.draftInput);
+    await validateDiscordResources(context.services, context.guildId, context.actorUserId, draft);
+    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 appendPanelAudit(context, "reactionroles.panel.publication.failed", failed, "cleanup_pending").catch(() => undefined);
+        }
+        await repository.remove(panelId, 1, context.actorUserId).catch(() => false);
+        throw error;
+    }
+    cache.put(panel);
+    await appendPanelAudit(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;
+}

package/dist/panel-lifecycle.d.ts

@@ -0,0 +1,47 @@
+import { type ScheduledTaskExecutionResult, type ServiceAccess } from "@helyx/sdk";
+import type { PanelSnapshotCache } from "./panel-cache.js";
+import type { ReactionRolePanelRepository, StoredPanel } from "./records.js";
+type RepositoryFactory = (services: ServiceAccess) => ReactionRolePanelRepository;
+export declare class PanelLifecycleService {
+    private readonly cache;
+    private readonly repositoryFor;
+    constructor(cache: PanelSnapshotCache, repositoryFor: RepositoryFactory);
+    warm(services: ServiceAccess): Promise<number>;
+    recoverMessageCleanup(services: ServiceAccess): Promise<{
+        completed: number;
+        failed: number;
+        abandoned: number;
+    }>;
+    executeMessageCleanup(services: ServiceAccess, cleanupId: string): Promise<ScheduledTaskExecutionResult>;
+    executeMessageCleanupWithRecovery(services: ServiceAccess, cleanupId: string): Promise<{
+        result: ScheduledTaskExecutionResult;
+        recovered: boolean;
+    }>;
+    private completeClaimedCleanup;
+    resolveActive(guildId: string, messageId: string, services: ServiceAccess): Promise<StoredPanel | null>;
+    markMessageMissing(input: {
+        guildId: string;
+        messageId: string;
+        services: ServiceAccess;
+    }): Promise<void>;
+    markNeedsAttention(panel: StoredPanel, services: ServiceAccess): Promise<boolean>;
+    handleChannelLifecycle(input: {
+        guildId: string;
+        channelId: string;
+        deleted: boolean;
+        services: ServiceAccess;
+    }): Promise<number>;
+    handleRoleLifecycle(input: {
+        guildId: string;
+        roleId: string;
+        deleted: boolean;
+        services: ServiceAccess;
+    }): Promise<number>;
+    handleEmojiLifecycle(input: {
+        guildId: string;
+        emojiId: string;
+        deleted: boolean;
+        services: ServiceAccess;
+    }): Promise<number>;
+}
+export {};

package/dist/panel-lifecycle.js

@@ -0,0 +1,272 @@
+import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { canonicaliseEmoji } from "./builder.js";
+import { channelSupportsPanel } from "./panel-support.js";
+export class PanelLifecycleService {
+    cache;
+    repositoryFor;
+    constructor(cache, repositoryFor) {
+        this.cache = cache;
+        this.repositoryFor = repositoryFor;
+    }
+    async warm(services) {
+        const repository = this.repositoryFor(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.repositoryFor(services);
+        const messages = services.get(HELYX_SERVICE_NAMES.discordOwnedMessages);
+        let completed = 0;
+        let failed = 0;
+        let abandoned = 0;
+        let cursor;
+        let pages = 0;
+        do {
+            const page = await repository.listPendingCleanupPage(100, cursor);
+            for (const cleanup of page.items) {
+                if (cleanup.attempts >= 10) {
+                    abandoned += 1;
+                    continue;
+                }
+                const claimed = await repository.claimCleanup(cleanup);
+                if (!claimed)
+                    continue;
+                try {
+                    await this.completeClaimedCleanup(repository, messages, claimed);
+                    completed += 1;
+                }
+                catch {
+                    failed += 1;
+                }
+            }
+            cursor = page.nextCursor ?? undefined;
+            pages += 1;
+        } while (cursor && pages < 10);
+        return { completed, failed, abandoned };
+    }
+    async executeMessageCleanup(services, cleanupId) {
+        return (await this.executeMessageCleanupWithRecovery(services, cleanupId))
+            .result;
+    }
+    async executeMessageCleanupWithRecovery(services, cleanupId) {
+        if (!services.has(HELYX_SERVICE_NAMES.discordOwnedMessages))
+            return {
+                result: {
+                    outcome: "retry",
+                    delayMs: 60_000,
+                    safeCode: "reaction_role_cleanup_service_missing",
+                },
+                recovered: false,
+            };
+        const repository = this.repositoryFor(services);
+        let cleanup;
+        try {
+            cleanup = await repository.findPendingCleanup(cleanupId);
+        }
+        catch {
+            return {
+                result: {
+                    outcome: "retry",
+                    delayMs: 60_000,
+                    safeCode: "reaction_role_cleanup_lookup_failed",
+                },
+                recovered: false,
+            };
+        }
+        if (!cleanup)
+            return { result: { outcome: "completed" }, recovered: false };
+        if (cleanup.attempts >= 10)
+            return {
+                result: {
+                    outcome: "requires_review",
+                    safeCode: "reaction_role_cleanup_exhausted",
+                },
+                recovered: false,
+            };
+        const wait = cleanup.nextAttemptAt.getTime() - Date.now();
+        if (wait > 0)
+            return {
+                result: {
+                    outcome: "deferred",
+                    delayMs: Math.max(100, wait),
+                    safeCode: "reaction_role_cleanup_backoff",
+                },
+                recovered: false,
+            };
+        let claimed;
+        try {
+            claimed = await repository.claimCleanup(cleanup);
+        }
+        catch {
+            return {
+                result: {
+                    outcome: "retry",
+                    delayMs: 60_000,
+                    safeCode: "reaction_role_cleanup_claim_failed",
+                },
+                recovered: false,
+            };
+        }
+        if (!claimed)
+            return {
+                result: {
+                    outcome: "retry",
+                    delayMs: 1_000,
+                    safeCode: "reaction_role_cleanup_claim_changed",
+                },
+                recovered: false,
+            };
+        try {
+            await this.completeClaimedCleanup(repository, services.get(HELYX_SERVICE_NAMES.discordOwnedMessages), claimed);
+            return { result: { outcome: "completed" }, recovered: true };
+        }
+        catch {
+            return {
+                result: {
+                    outcome: "retry",
+                    delayMs: Math.max(1_000, claimed.nextAttemptAt.getTime() - Date.now()),
+                    safeCode: "reaction_role_cleanup_failed",
+                },
+                recovered: false,
+            };
+        }
+    }
+    async completeClaimedCleanup(repository, messages, cleanup) {
+        await messages.deleteOwnedMessage({
+            guildId: cleanup.guildId,
+            channelId: cleanup.channelId,
+            messageId: cleanup.messageId,
+        });
+        if ((await repository.pendingCleanupCount(cleanup.panelId)) === 1) {
+            const panel = await repository.findById(cleanup.guildId, cleanup.panelId);
+            if (panel?.status === "cleanup_pending" &&
+                !(await repository.markStatus({
+                    panelId: panel.panelId,
+                    expectedRevision: panel.revision,
+                    status: "active",
+                })))
+                throw new Error("Reaction Roles cleanup panel state changed");
+        }
+        if (!(await repository.completeCleanup(cleanup)))
+            throw new Error("Reaction Roles cleanup completion changed");
+    }
+    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.repositoryFor(services).findByMessage(guildId, messageId);
+            return panel &&
+                (panel.status === "active" || panel.status === "cleanup_pending")
+                ? panel
+                : null;
+        });
+    }
+    async markMessageMissing(input) {
+        const repository = this.repositoryFor(input.services);
+        const panel = this.cache.get(input.guildId, input.messageId) ??
+            (await repository.findByMessage(input.guildId, input.messageId));
+        if (!panel || 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.repositoryFor(services).markStatus({
+            panelId: panel.panelId,
+            expectedRevision: panel.revision,
+            status: "needs_attention",
+        });
+        if (changed)
+            this.cache.remove(panel);
+        return changed;
+    }
+    async handleChannelLifecycle(input) {
+        const candidates = await this.repositoryFor(input.services).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 candidates = await this.repositoryFor(input.services).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.repositoryFor(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;
+    }
+}

package/dist/panel-managed.d.ts

@@ -0,0 +1,14 @@
+import type { ManagedResourceContext, ManagedResourceDetail, ManagedResourcePage, ManagedResourceValue, MessageResponse, ServiceAccess } from "@helyx/sdk";
+import type { ReactionRolePanelRepository } from "./records.js";
+type RepositoryFactory = (services: ServiceAccess) => ReactionRolePanelRepository;
+export declare class ManagedPanelReader {
+    private readonly repositoryFor;
+    constructor(repositoryFor: RepositoryFactory);
+    list(context: ManagedResourceContext, input: {
+        cursor?: string;
+        limit: number;
+    }): Promise<ManagedResourcePage>;
+    read(context: ManagedResourceContext, resourceId: string): Promise<ManagedResourceDetail | null>;
+    preview(context: ManagedResourceContext, value: Readonly<Record<string, ManagedResourceValue>>): Promise<MessageResponse>;
+}
+export {};

package/dist/panel-managed.js

@@ -0,0 +1,27 @@
+import { buildPanel, decodeCursor, encodeCursor, parseManagedDraft, toDetail, toSummary, validateDiscordResources, } from "./panel-support.js";
+export class ManagedPanelReader {
+    repositoryFor;
+    constructor(repositoryFor) {
+        this.repositoryFor = repositoryFor;
+    }
+    async list(context, input) {
+        const page = await this.repositoryFor(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.repositoryFor(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;
+    }
+}