@helyx/module-account-gate 1.0.14 → 1.1.1

package/dist/member-start.js

@@ -0,0 +1,199 @@
+import { HELYX_SERVICE_NAMES, generateChallengeChain, ACCOUNT_GATE_COMPONENTS, ACCOUNT_GATE_SESSION_PURPOSE, validateRuntimeCapabilities, getGatePanelRuntime, createAccountGateSessionState, parseAccountGateSessionState, VIOLET, GREEN, RED, } from "./runtime-dependencies.js";
+import { resumeRevokedMember } from "./member-restart.js";
+import { loadMemberSummary } from "./member-summary.js";
+import { dateValue, numberValue, replyError, secureRandom, } from "./runtime-support.js";
+import { challengeMessage, configurationForPanel, currentStrictMode, getConfiguration, loadQuestions, validateAccountGateSetup, } from "./setup-presentation.js";
+import { scheduleSessionExpiry } from "./task-scheduling.js";
+import { ensureTerminalFinalization, finalizeTerminalFinalization, } from "./terminal-finalization.js";
+export async function startCheck(context) {
+    if (!context.serverId) {
+        await replyError(context, "Access Control only works in a Discord server.");
+        return;
+    }
+    const configuration = await getConfiguration(context.services, context.serverId);
+    if (!configuration) {
+        await replyError(context, "Access Control has not been configured by the server team.");
+        return;
+    }
+    const panelId = startPanelId(context.customId);
+    if (context.customId?.startsWith(ACCOUNT_GATE_COMPONENTS.startPrefix) &&
+        panelId === null) {
+        await replyError(context, "This Access Control panel control is invalid.");
+        return;
+    }
+    const panel = panelId === null
+        ? null
+        : await getGatePanelRuntime(context.services.get(HELYX_SERVICE_NAMES.records), context.serverId, panelId);
+    if (panelId !== null && !panel) {
+        await replyError(context, "This Access Control panel is no longer available. Ask the server team to publish or repair it.");
+        return;
+    }
+    if (panel?.accessType === "password" && !panel.password) {
+        await replyError(context, "This Password Entry panel does not have a password. Ask the server team to update it.");
+        return;
+    }
+    if (panel?.accessType === "challenges" &&
+        configuration.accessType !== "challenges") {
+        await replyError(context, "This Challenge panel is not currently active. Ask the server team to publish the current Access Control setup.");
+        return;
+    }
+    const activeConfiguration = panel
+        ? configurationForPanel(configuration, panel.accessType)
+        : configuration;
+    const setupErrors = await validateAccountGateSetup(context.services, context.serverId, activeConfiguration, false);
+    if (setupErrors.length > 0) {
+        await replyError(context, setupErrors[0]);
+        return;
+    }
+    const resources = context.services.get(HELYX_SERVICE_NAMES.discordResources);
+    let summary = await loadMemberSummary(context.services.get(HELYX_SERVICE_NAMES.records), context.serverId, context.userId);
+    const [member] = await resources.resolveMemberSnapshots({
+        guildId: context.serverId,
+        userIds: [context.userId],
+    });
+    if (summary?.last_decision === "revoked" &&
+        member?.exists &&
+        !member.isBot &&
+        !member.roleIds.includes(activeConfiguration.verifiedRoleId)) {
+        summary = await resumeRevokedMember(context.services, context.serverId, context.userId, summary, activeConfiguration, context.interactionId);
+        if (!summary) {
+            await replyError(context, "The revoked Access Control state changed while this check was starting. Press Start check again.");
+            return;
+        }
+    }
+    if (!summary ||
+        summary.last_decision !== "pending" ||
+        !member?.exists ||
+        member.isBot ||
+        member.roleIds.includes(activeConfiguration.verifiedRoleId)) {
+        await replyError(context, "There is no current pending Access Control check for this member.");
+        return;
+    }
+    const capabilityErrors = validateRuntimeCapabilities(activeConfiguration, await resources.inspectRuntimeCapabilities());
+    if (capabilityErrors.length > 0) {
+        await replyError(context, capabilityErrors[0]);
+        return;
+    }
+    const sessions = context.services.get(HELYX_SERVICE_NAMES.sessions);
+    const lockoutUntil = dateValue(summary?.lockout_until);
+    if (lockoutUntil && lockoutUntil.getTime() > Date.now()) {
+        await replyError(context, `Please wait until <t:${Math.floor(lockoutUntil.getTime() / 1_000)}:R> before starting another check.`);
+        return;
+    }
+    let existing = await sessions.getFor(context.serverId, context.userId, ACCOUNT_GATE_SESSION_PURPOSE);
+    if (existing) {
+        const existingState = parseAccountGateSessionState(existing.state);
+        if (existingState.joinGeneration !== numberValue(summary.join_generation)) {
+            await sessions.delete(existing.sessionId);
+            existing = null;
+        }
+    }
+    if (existing) {
+        const existingState = parseAccountGateSessionState(existing.state);
+        if (existingState.status === "passed" ||
+            existingState.status === "failed") {
+            if (await ensureTerminalFinalization(context.services, context.serverId, context.userId, existing.sessionId, existingState, existingState.status))
+                await finalizeTerminalFinalization(context.services, context.serverId, existing.sessionId);
+            const finalizedSummary = await loadMemberSummary(context.services.get(HELYX_SERVICE_NAMES.records), context.serverId, context.userId);
+            await context.reply(terminalRecoveryMessage(existingState.status, typeof finalizedSummary?.last_decision === "string"
+                ? finalizedSummary.last_decision
+                : "pending"));
+            return;
+        }
+        await context.reply(challengeMessage(existingState, {
+            sessionId: existing.sessionId,
+            version: existing.version,
+        }));
+        return;
+    }
+    const strictModeActive = await currentStrictMode(context.services, context.serverId);
+    const random = secureRandom(context.services);
+    const questions = activeConfiguration.enabledChallengeTypes.includes("server_question")
+        ? await loadQuestions(context.services, context.serverId)
+        : [];
+    const state = createAccountGateSessionState(generateChallengeChain({
+        configuration: activeConfiguration,
+        random,
+        operationContext: `${context.serverId}:${context.userId}:${context.interactionId}`,
+        strictModeActive,
+        adaptiveRisk: (summary ? numberValue(summary.failure_count) : 0) > 0 ||
+            summary?.pending_reason === "account_too_new",
+        questions,
+    }), numberValue(summary.join_generation), new Date(), panelId ?? undefined);
+    const expiresAt = new Date(Date.now() + activeConfiguration.sessionExpirySeconds * 1_000);
+    const created = await sessions.create({
+        guildId: context.serverId,
+        userId: context.userId,
+        purpose: ACCOUNT_GATE_SESSION_PURPOSE,
+        state,
+        expiresAt,
+    });
+    await scheduleSessionExpiry(context.services, {
+        guildId: context.serverId,
+        userId: context.userId,
+        sessionId: created.sessionId,
+        expiredAt: expiresAt,
+    });
+    await context.reply(challengeMessage(state, {
+        sessionId: created.sessionId,
+        version: created.version,
+    }));
+}
+export function startPanelId(customId) {
+    if (!customId?.startsWith(ACCOUNT_GATE_COMPONENTS.startPrefix))
+        return null;
+    const panelId = customId.slice(ACCOUNT_GATE_COMPONENTS.startPrefix.length);
+    return panelId.length >= 1 && panelId.length <= 100 && !panelId.includes(":")
+        ? panelId
+        : null;
+}
+export function terminalRecoveryMessage(outcome, decision) {
+    if (outcome === "passed" && decision === "passed")
+        return {
+            ephemeral: true,
+            componentsV2: {
+                accentColor: GREEN,
+                text: [
+                    { content: "## Access applied" },
+                    {
+                        content: "Your Access Control check is complete and your server access has been applied.",
+                        markdown: false,
+                    },
+                ],
+            },
+        };
+    if (decision === "review")
+        return {
+            ephemeral: true,
+            componentsV2: {
+                accentColor: VIOLET,
+                text: [
+                    { content: "## Check sent for review" },
+                    {
+                        content: "Your check is complete, but Helyx could not safely apply the configured roles. The server team has been notified.",
+                        markdown: false,
+                    },
+                ],
+            },
+        };
+    return {
+        ephemeral: true,
+        componentsV2: {
+            accentColor: outcome === "passed" ? VIOLET : RED,
+            text: [
+                {
+                    content: outcome === "passed"
+                        ? "## Access is being finalized"
+                        : "## Attempt submitted",
+                },
+                {
+                    content: outcome === "passed"
+                        ? "Your Access Control check is complete. Helyx is still applying the configured access changes."
+                        : "Your attempt has been recorded. Start a new check after the configured cooldown if another attempt is available.",
+                    markdown: false,
+                },
+            ],
+        },
+    };
+}
+//# sourceMappingURL=member-start.js.map

package/dist/member-summary.d.ts

@@ -0,0 +1,47 @@
+import type { ModuleRecordService, ServiceAccess } from "./runtime-dependencies.js";
+export declare function loadMemberSummary(records: ModuleRecordService, guildId: string, memberUserId: string): Promise<Readonly<Record<string, import("@helyx/sdk").ModuleRecordValue>> | null>;
+export declare function isCurrentPendingMember(services: ServiceAccess, guildId: string, memberUserId: string, verifiedRoleId: string): Promise<boolean>;
+export declare function summaryValues(input: {
+    guildId: string;
+    memberUserId: string;
+    now: Date;
+    previous?: Readonly<Record<string, unknown>> | null;
+    previousSuccessAt?: Date;
+    failureCount: number;
+    lockoutUntil: Date;
+    rejoinCount: number;
+    joinGeneration: number;
+    accountCreatedAt: Date;
+    joinedAt: Date;
+    deadlineAt: Date;
+    pendingReason: "none" | "account_too_new";
+    lastFailureTerminalId?: string;
+    leftAt?: Date;
+    lastDecision: "pending" | "finalizing" | "passed" | "failed" | "review" | "kick_pending" | "kicked" | "dismissed" | "revoked";
+}): {
+    summary_id: string;
+    guild_id: string;
+    member_user_id: string;
+    previous_success_at: Date;
+    failure_count: number;
+    lockout_until: Date;
+    rejoin_count: number;
+    join_generation: number;
+    account_created_at: Date;
+    joined_at: Date;
+    deadline_at: Date;
+    pending_reason: "none" | "account_too_new";
+    last_failure_terminal_id: string;
+    left_at: Date;
+    last_decision: "passed" | "failed" | "review" | "kicked" | "pending" | "finalizing" | "kick_pending" | "dismissed" | "revoked";
+    revision: number;
+    retention_until: Date;
+    created_at: Date;
+    updated_at: Date;
+};
+export declare function summaryUpdateValues(values: ReturnType<typeof summaryValues>): Readonly<Record<string, string | number | boolean | Date>>;
+export declare function setSummaryDecision(records: ModuleRecordService, guildId: string, memberUserId: string, generation: number, decision: "pending" | "finalizing" | "passed" | "failed" | "review" | "kick_pending" | "kicked" | "dismissed" | "revoked", expectedDecision?: string): Promise<boolean>;
+export declare function recordFailureSummary(records: ModuleRecordService, guildId: string, memberUserId: string, now: Date, cooldownSeconds: number, attemptLimit: number, terminalId: string, expectedGeneration: number): Promise<number | null>;
+export declare function markSummaryPassed(records: ModuleRecordService, guildId: string, memberUserId: string, now: Date, expectedGeneration: number): Promise<boolean>;
+export declare function resetSummaryForRetry(records: ModuleRecordService, guildId: string, memberUserId: string, now: Date, expectedGeneration: number): Promise<boolean>;
+//# sourceMappingURL=member-summary.d.ts.map

package/dist/member-summary.js

@@ -0,0 +1,200 @@
+import { randomUUID, HELYX_SERVICE_NAMES, ACCOUNT_GATE_IDENTITY, accountGateRecords, RETENTION_MS, } from "./runtime-dependencies.js";
+import { dateValue, numberValue } from "./runtime-support.js";
+export async function loadMemberSummary(records, guildId, memberUserId) {
+    return records.findOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "member_summaries",
+        select: accountGateRecords.member_summaries.readableFields,
+        where: { guild_id: guildId, member_user_id: memberUserId },
+    });
+}
+export async function isCurrentPendingMember(services, guildId, memberUserId, verifiedRoleId) {
+    const [summary, members] = await Promise.all([
+        loadMemberSummary(services.get(HELYX_SERVICE_NAMES.records), guildId, memberUserId),
+        services
+            .get(HELYX_SERVICE_NAMES.discordResources)
+            .resolveMemberSnapshots({ guildId, userIds: [memberUserId] }),
+    ]);
+    const member = members[0];
+    return (summary?.last_decision === "pending" &&
+        member?.exists === true &&
+        !member.isBot &&
+        !member.roleIds.includes(verifiedRoleId));
+}
+export function summaryValues(input) {
+    return {
+        summary_id: typeof input.previous?.summary_id === "string"
+            ? input.previous.summary_id
+            : randomUUID(),
+        guild_id: input.guildId,
+        member_user_id: input.memberUserId,
+        previous_success_at: input.previousSuccessAt ??
+            dateValue(input.previous?.previous_success_at) ??
+            new Date(0),
+        failure_count: input.failureCount,
+        lockout_until: input.lockoutUntil,
+        rejoin_count: input.rejoinCount,
+        join_generation: input.joinGeneration,
+        account_created_at: input.accountCreatedAt,
+        joined_at: input.joinedAt,
+        deadline_at: input.deadlineAt,
+        pending_reason: input.pendingReason,
+        last_failure_terminal_id: input.lastFailureTerminalId ??
+            (typeof input.previous?.last_failure_terminal_id === "string"
+                ? input.previous.last_failure_terminal_id
+                : ""),
+        left_at: input.leftAt ?? new Date(0),
+        last_decision: input.lastDecision,
+        revision: input.previous ? numberValue(input.previous.revision) + 1 : 1,
+        retention_until: new Date(input.now.getTime() + RETENTION_MS),
+        created_at: dateValue(input.previous?.created_at) ?? input.now,
+        updated_at: input.now,
+    };
+}
+export function summaryUpdateValues(values) {
+    return {
+        previous_success_at: values.previous_success_at,
+        failure_count: values.failure_count,
+        lockout_until: values.lockout_until,
+        rejoin_count: values.rejoin_count,
+        join_generation: values.join_generation,
+        account_created_at: values.account_created_at,
+        joined_at: values.joined_at,
+        deadline_at: values.deadline_at,
+        pending_reason: values.pending_reason,
+        last_failure_terminal_id: values.last_failure_terminal_id,
+        left_at: values.left_at,
+        last_decision: values.last_decision,
+        revision: values.revision,
+        retention_until: values.retention_until,
+        updated_at: values.updated_at,
+    };
+}
+export async function setSummaryDecision(records, guildId, memberUserId, generation, decision, expectedDecision = "pending") {
+    const row = await loadMemberSummary(records, guildId, memberUserId);
+    if (!row ||
+        numberValue(row.join_generation) !== generation ||
+        row.last_decision !== expectedDecision)
+        return false;
+    return (await records.updateOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "member_summaries",
+        where: { guild_id: guildId, member_user_id: memberUserId },
+        expected: { field: "revision", value: numberValue(row.revision) },
+        values: {
+            last_decision: decision,
+            revision: numberValue(row.revision) + 1,
+            updated_at: new Date(),
+        },
+    })).updated;
+}
+export async function recordFailureSummary(records, guildId, memberUserId, now, cooldownSeconds, attemptLimit, terminalId, expectedGeneration) {
+    for (let retry = 0; retry < 4; retry += 1) {
+        const previous = await loadMemberSummary(records, guildId, memberUserId);
+        if (!previous ||
+            numberValue(previous.join_generation) !== expectedGeneration)
+            return null;
+        if (previous?.last_failure_terminal_id === terminalId)
+            return numberValue(previous.failure_count);
+        const failureCount = (previous ? numberValue(previous.failure_count) : 0) + 1;
+        const requestedLockout = new Date(now.getTime() + cooldownSeconds * 1_000);
+        const existingLockout = dateValue(previous?.lockout_until);
+        const lockoutUntil = existingLockout && existingLockout.getTime() > requestedLockout.getTime()
+            ? existingLockout
+            : requestedLockout;
+        const values = summaryValues({
+            guildId,
+            memberUserId,
+            now,
+            previous,
+            failureCount,
+            lockoutUntil,
+            rejoinCount: previous ? numberValue(previous.rejoin_count) : 0,
+            joinGeneration: expectedGeneration,
+            accountCreatedAt: dateValue(previous?.account_created_at) ?? now,
+            joinedAt: dateValue(previous?.joined_at) ?? now,
+            deadlineAt: dateValue(previous?.deadline_at) ?? now,
+            pendingReason: previous?.pending_reason === "account_too_new"
+                ? "account_too_new"
+                : "none",
+            lastDecision: failureCount >= attemptLimit ? "failed" : "pending",
+            lastFailureTerminalId: terminalId,
+        });
+        const result = await records.updateOne({
+            moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+            collection: "member_summaries",
+            where: { guild_id: guildId, member_user_id: memberUserId },
+            expected: {
+                field: "revision",
+                value: numberValue(previous.revision),
+            },
+            values: summaryUpdateValues(values),
+        });
+        if (result.updated)
+            return failureCount;
+    }
+    const current = await loadMemberSummary(records, guildId, memberUserId);
+    return current &&
+        numberValue(current.join_generation) === expectedGeneration &&
+        current.last_failure_terminal_id === terminalId
+        ? numberValue(current.failure_count)
+        : null;
+}
+export async function markSummaryPassed(records, guildId, memberUserId, now, expectedGeneration) {
+    const previous = await loadMemberSummary(records, guildId, memberUserId);
+    if (!previous || numberValue(previous.join_generation) !== expectedGeneration)
+        return false;
+    const values = summaryValues({
+        guildId,
+        memberUserId,
+        now,
+        previous,
+        previousSuccessAt: now,
+        failureCount: 0,
+        lockoutUntil: new Date(0),
+        rejoinCount: previous ? numberValue(previous.rejoin_count) : 0,
+        joinGeneration: expectedGeneration,
+        accountCreatedAt: dateValue(previous?.account_created_at) ?? now,
+        joinedAt: dateValue(previous?.joined_at) ?? now,
+        deadlineAt: dateValue(previous?.deadline_at) ?? now,
+        pendingReason: "none",
+        lastDecision: "passed",
+    });
+    return (await records.updateOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "member_summaries",
+        where: { guild_id: guildId, member_user_id: memberUserId },
+        expected: { field: "revision", value: numberValue(previous.revision) },
+        values: summaryUpdateValues(values),
+    })).updated;
+}
+export async function resetSummaryForRetry(records, guildId, memberUserId, now, expectedGeneration) {
+    const previous = await loadMemberSummary(records, guildId, memberUserId);
+    if (!previous || numberValue(previous.join_generation) !== expectedGeneration)
+        return false;
+    const values = summaryValues({
+        guildId,
+        memberUserId,
+        now,
+        previous,
+        failureCount: 0,
+        lockoutUntil: new Date(0),
+        rejoinCount: previous ? numberValue(previous.rejoin_count) : 0,
+        joinGeneration: expectedGeneration,
+        accountCreatedAt: dateValue(previous?.account_created_at) ?? now,
+        joinedAt: dateValue(previous?.joined_at) ?? now,
+        deadlineAt: dateValue(previous?.deadline_at) ?? now,
+        pendingReason: previous?.pending_reason === "account_too_new"
+            ? "account_too_new"
+            : "none",
+        lastDecision: "pending",
+    });
+    return (await records.updateOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "member_summaries",
+        where: { guild_id: guildId, member_user_id: memberUserId },
+        expected: { field: "revision", value: numberValue(previous.revision) },
+        values: summaryUpdateValues(values),
+    })).updated;
+}
+//# sourceMappingURL=member-summary.js.map

package/dist/panel-maintenance.d.ts

@@ -0,0 +1,26 @@
+import type { RuntimeContext, ScheduledTaskPayload, ServiceAccess } from "@helyx/sdk";
+export declare const PANEL_MESSAGE_CLEANUP_TASK = "account-gate.panel-message-cleanup";
+export declare function queuePanelMessageCleanup(input: {
+    services: ServiceAccess;
+    guildId: string;
+    panelId: string;
+    channelId: string;
+    messageId: string;
+}): Promise<void>;
+export declare function validatePanelCleanupPayload(input: unknown): ScheduledTaskPayload;
+export declare function executePanelMessageCleanup(context: RuntimeContext, task: {
+    payload: ScheduledTaskPayload;
+}): Promise<{
+    outcome: "completed";
+    safeCode?: never;
+    delayMs?: never;
+} | {
+    outcome: "requires_review";
+    safeCode: string;
+    delayMs?: never;
+} | {
+    outcome: "retry";
+    delayMs: number;
+    safeCode: string;
+}>;
+//# sourceMappingURL=panel-maintenance.d.ts.map

package/dist/panel-maintenance.js

@@ -0,0 +1,143 @@
+import { randomUUID } from "node:crypto";
+import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
+import { ACCOUNT_GATE_IDENTITY } from "./contracts.js";
+import { accountGateRecords } from "./records.js";
+export const PANEL_MESSAGE_CLEANUP_TASK = "account-gate.panel-message-cleanup";
+export async function queuePanelMessageCleanup(input) {
+    const records = recordService(input.services);
+    const cleanupId = randomUUID();
+    const now = new Date();
+    const created = await records.appendUnique({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "panel_message_cleanup",
+        values: {
+            cleanup_id: cleanupId,
+            guild_id: input.guildId,
+            panel_id: input.panelId,
+            channel_id: input.channelId,
+            message_id: input.messageId,
+            attempts: 0,
+            next_attempt_at: now,
+            created_at: now,
+        },
+        uniqueBy: ["guild_id", "channel_id", "message_id"],
+        schedule: {
+            taskKind: PANEL_MESSAGE_CLEANUP_TASK,
+            guildId: input.guildId,
+            idempotencyKey: `account-gate-panel-cleanup:${input.guildId}:${input.channelId}:${input.messageId}`,
+            payload: { cleanupId },
+            scheduledFor: now,
+        },
+    });
+    if (created.created)
+        return;
+    const existing = await records.findOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "panel_message_cleanup",
+        select: accountGateRecords.panel_message_cleanup.readableFields,
+        where: {
+            guild_id: input.guildId,
+            channel_id: input.channelId,
+            message_id: input.messageId,
+        },
+    });
+    if (!existing || existing.completed_at !== null)
+        return;
+    const existingId = recordString(existing.cleanup_id);
+    await input.services
+        .get(HELYX_SERVICE_NAMES.scheduledTasks)
+        .schedule({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        taskKind: PANEL_MESSAGE_CLEANUP_TASK,
+        guildId: input.guildId,
+        idempotencyKey: `account-gate-panel-cleanup:${input.guildId}:${input.channelId}:${input.messageId}`,
+        payload: { cleanupId: existingId },
+        scheduledFor: now,
+    });
+}
+export function validatePanelCleanupPayload(input) {
+    const cleanupId = input && typeof input === "object" && !Array.isArray(input)
+        ? input.cleanupId
+        : undefined;
+    if (typeof cleanupId !== "string" || cleanupId === "")
+        throw new Error("Access Control panel cleanup payload is invalid");
+    return { cleanupId };
+}
+export async function executePanelMessageCleanup(context, task) {
+    const cleanupId = recordString(task.payload.cleanupId);
+    const records = recordService(context.services);
+    const row = await records.findOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "panel_message_cleanup",
+        select: accountGateRecords.panel_message_cleanup.readableFields,
+        where: { cleanup_id: cleanupId },
+    });
+    if (!row || row.completed_at !== null)
+        return { outcome: "completed" };
+    const attempts = recordNumber(row.attempts);
+    if (attempts >= 10)
+        return {
+            outcome: "requires_review",
+            safeCode: "account_gate.panel_cleanup_exhausted",
+        };
+    const claimed = await records.updateOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "panel_message_cleanup",
+        where: { cleanup_id: cleanupId },
+        expected: { field: "attempts", value: attempts },
+        values: {
+            attempts: attempts + 1,
+            next_attempt_at: new Date(Date.now() + Math.min(3_600_000, 30_000 * 2 ** attempts)),
+        },
+    });
+    if (!claimed.updated)
+        return {
+            outcome: "retry",
+            delayMs: 5_000,
+            safeCode: "account_gate.panel_cleanup_claim_conflict",
+        };
+    try {
+        await context.services
+            .get(HELYX_SERVICE_NAMES.discordOwnedMessages)
+            .deleteOwnedMessage({
+            guildId: recordString(row.guild_id),
+            channelId: recordString(row.channel_id),
+            messageId: recordString(row.message_id),
+        });
+    }
+    catch {
+        return {
+            outcome: "retry",
+            delayMs: Math.min(3_600_000, 30_000 * 2 ** attempts),
+            safeCode: "account_gate.panel_cleanup_retry",
+        };
+    }
+    const completed = await records.updateOne({
+        moduleId: ACCOUNT_GATE_IDENTITY.moduleId,
+        collection: "panel_message_cleanup",
+        where: { cleanup_id: cleanupId },
+        expected: { field: "attempts", value: attempts + 1 },
+        values: { completed_at: new Date() },
+    });
+    return completed.updated
+        ? { outcome: "completed" }
+        : {
+            outcome: "retry",
+            delayMs: 5_000,
+            safeCode: "account_gate.panel_cleanup_finalize_conflict",
+        };
+}
+function recordService(services) {
+    return services.get(HELYX_SERVICE_NAMES.records);
+}
+function recordString(value) {
+    if (typeof value !== "string" || value === "")
+        throw new Error("Access Control panel cleanup record is invalid");
+    return value;
+}
+function recordNumber(value) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value))
+        throw new Error("Access Control panel cleanup record is invalid");
+    return value;
+}
+//# sourceMappingURL=panel-maintenance.js.map

package/dist/panel-model.d.ts

@@ -0,0 +1,47 @@
+import { DashboardActionValidationError } from "@helyx/sdk";
+import type { ManagedResourceDetail } from "@helyx/sdk";
+export type GatePanelAccessType = "challenges" | "password" | "emoji";
+export interface PanelPassword {
+    encodedHash: string;
+    ignoreCase: boolean;
+    trimWhitespace: boolean;
+}
+export declare const DEFAULT_PANEL_MESSAGES: Readonly<Record<GatePanelAccessType, string>>;
+export declare function panelMessage(messageBody: string, accessType: GatePanelAccessType, panelId: string): {
+    allowedUserMentionIds: never[];
+    componentsV2: {
+        text: {
+            content: string;
+            markdown: boolean;
+        }[];
+    };
+    buttons?: never;
+} | {
+    allowedUserMentionIds: never[];
+    componentsV2: {
+        text: ({
+            content: string;
+            markdown?: never;
+        } | {
+            content: string;
+            markdown: boolean;
+        })[];
+        accentColor?: number;
+    };
+    buttons: {
+        type: "button";
+        customId: string;
+        label: string;
+        style: "primary";
+    }[];
+};
+export declare function panelDetail(row: Readonly<Record<string, unknown>>, status: "posted" | "missing"): ManagedResourceDetail;
+export declare function panelAccessType(row: Readonly<Record<string, unknown>>): GatePanelAccessType;
+export declare function panelMessageFromValue(value: Readonly<Record<string, unknown>>, fallback: string): string;
+export declare function savedPanelMessage(row: Readonly<Record<string, unknown>>): string;
+export declare function panelPasswordFromRow(row: Readonly<Record<string, unknown>>): PanelPassword | null;
+export declare function replacementPhrase(value: Readonly<Record<string, unknown>>, required: boolean): string;
+export declare function panelLimitError(): DashboardActionValidationError;
+export declare function panelString(value: unknown): string;
+export declare function panelNumber(value: unknown): number;
+//# sourceMappingURL=panel-model.d.ts.map