@helyx/bot 0.4.8 → 0.4.11

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## 0.4.11
+
+### Patch Changes
+
+- Add the reusable Stage 8 Levels foundations: privacy-bounded guild message
+  events with optional transient type classification, optional Discord-user
+  command options, multiple channel settings, bounded ranked numeric records,
+  idempotent numeric mutation receipts, and core-owned write-behind accumulation
+  across local and coordinated shard compositions.
+- Updated dependencies
+  - @helyx/database@0.5.0
+  - @helyx/module-manifest@0.5.0
+  - @helyx/control-protocol@0.2.0
+  - @helyx/sdk@0.4.0
+  - @helyx/platform@0.3.0
+  - @helyx/core@0.1.11
+  - @helyx/framework@0.1.11
+
+## 0.4.10
+
+### Patch Changes
+
+- Add the shared session, Discord event, resource inspection, enforcement,
+  privacy and hosted/self-hosted composition support required by the Account Gate
+  Testing module.
+- Updated dependencies
+  - @helyx/config@0.4.3
+  - @helyx/database@0.4.4
+  - @helyx/sdk@0.3.5
+  - @helyx/platform@0.2.8
+  - @helyx/core@0.1.10
+  - @helyx/framework@0.1.10
+
+## 0.4.9
+
+### Patch Changes
+
+- Polish the Stage 4-6 resource dashboard and Discord flows, add durable
+  reaction-role controls, repair poll and giveaway lifecycle handling, and
+  strengthen shard-safe scheduling, retention, permissions and resource
+  inspection.
+- Updated dependencies
+  - @helyx/control-protocol@0.1.5
+  - @helyx/module-manifest@0.4.2
+  - @helyx/database@0.4.3
+  - @helyx/sdk@0.3.4
+  - @helyx/platform@0.2.7
+  - @helyx/core@0.1.9
+  - @helyx/framework@0.1.9
+
 ## 0.4.8
 
 ### Patch Changes

package/dist/cloud-control-dispatcher.js

@@ -146,11 +146,12 @@ export class CloudControlDispatcher {
                 break;
             }
             case "guild.module.resource.action.execute.v1": {
-                const input = parseOperationInput(request.operation, request.input);
+                const { actorAuthenticatedAt, ...input } = parseOperationInput(request.operation, request.input);
                 result = await this.control.executeManagedResourceAction({
                     ...input,
                     actorUserId: requiredActor(actorUserId),
                     correlationId,
+                    ...(actorAuthenticatedAt ? { actorAuthenticatedAt } : {}),
                 });
                 break;
             }

package/dist/control-server.d.ts

@@ -104,6 +104,9 @@ export interface SupportNotificationInput {
     source: "dashboard_bug" | "dashboard_support" | "dashboard_security" | "discord_command";
 }
 export interface BotControlState {
+    discordCapabilities?: {
+        messageContent: boolean;
+    };
     channels: BotControlGuildResources["channels"];
     roles: BotControlGuildResources["roles"];
     modules: DashboardModuleDefinition[];
@@ -237,6 +240,7 @@ export interface BotControlHandler {
         value: Readonly<Record<string, ManagedResourceValue>>;
         actorUserId: string;
         correlationId: string;
+        actorAuthenticatedAt?: string;
     }): Promise<ManagedResourceDetail | null>;
     listPrivacyProviders(): Promise<readonly {
         id: string;
@@ -415,6 +419,7 @@ export declare class BotControlService implements BotControlHandler {
         value: Readonly<Record<string, ManagedResourceValue>>;
         actorUserId: string;
         correlationId: string;
+        actorAuthenticatedAt?: string;
     }): Promise<ManagedResourceDetail | null>;
 }
 export declare function createBotControlServer(input: {

package/dist/control-server.js

@@ -9,7 +9,9 @@ import { addChannelMessageReaction as addDiscordChannelMessageReaction, deleteCh
 import { SHARD_HEALTH_STALE_MS, } from "./shard-contracts.js";
 const snowflake = z.string().regex(/^\d{17,20}$/u);
 const moduleId = z.string().regex(/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/u);
+const MAX_DISCORD_SETTING_SELECTIONS = 25;
 const configurationValue = z.record(z.string(), z.union([
+    z.null(),
     z.string(),
     z.boolean(),
     z.number().finite(),
@@ -222,7 +224,7 @@ export class BotControlService {
             ? modules
                 .filter((module) => module.privacy !== undefined)
                 .map((module) => {
-                const provider = module.privacy.create(privacyExecutor);
+                const provider = module.privacy.create(privacyExecutor, this.#services);
                 return [provider.id, provider];
             })
             : []);
@@ -289,10 +291,11 @@ export class BotControlService {
         });
     }
     async getGuildState(guildId) {
-        const [resources, installedModules, storedLoggingPolicies] = await Promise.all([
+        const [resources, installedModules, storedLoggingPolicies, runtime] = await Promise.all([
             this.resources.getGuildResources(guildId),
             new InstallationRepository(this.database).listModules(guildId),
             new ModuleLoggingPolicyRepository(this.database).listForGuild(guildId),
+            this.#inspectRuntimeCapabilities(),
         ]);
         const installed = new Map(installedModules.map((module) => [module.moduleId, module]));
         const moduleStatuses = {};
@@ -331,6 +334,9 @@ export class BotControlService {
             });
         }));
         return {
+            discordCapabilities: {
+                messageContent: runtime.messageContent,
+            },
             ...resources,
             modules: structuredClone(this.#dashboardModules),
             moduleStatuses,
@@ -339,9 +345,29 @@ export class BotControlService {
             logging,
         };
     }
+    async #inspectRuntimeCapabilities() {
+        if (!this.#services.has(HELYX_SERVICE_NAMES.discordResources))
+            return { messageContent: false };
+        const inspector = this.#services.get(HELYX_SERVICE_NAMES.discordResources);
+        if (typeof inspector.inspectRuntimeCapabilities !== "function")
+            return { messageContent: false };
+        const runtime = await inspector.inspectRuntimeCapabilities();
+        return { messageContent: runtime.messageContent };
+    }
     async setModuleStatus(input) {
-        this.#requireDashboardModule(input.moduleId);
-        await this.#installations.setModuleEnabled({
+        const module = this.#requireDashboardModule(input.moduleId);
+        const scopes = Object.entries(module.records ?? {})
+            .filter(([, collection]) => (collection.incrementableFields?.length ?? 0) > 0)
+            .map(([collection]) => ({
+            moduleId: input.moduleId,
+            collection,
+            guildId: input.guildId,
+        }));
+        const writeBehind = scopes.length > 0 &&
+            this.#services.has(HELYX_SERVICE_NAMES.numericWriteBehind)
+            ? this.#services.get(HELYX_SERVICE_NAMES.numericWriteBehind)
+            : null;
+        const setEnabled = () => this.#installations.setModuleEnabled({
             guildId: input.guildId,
             moduleId: input.moduleId,
             enabled: input.enabled,
@@ -351,11 +377,56 @@ export class BotControlService {
                 source: "dashboard",
             },
         });
+        if (!writeBehind) {
+            await setEnabled();
+        }
+        else if (input.enabled) {
+            for (const scope of scopes) {
+                const suppression = await writeBehind.suppressGuild(scope);
+                await writeBehind.releaseGuild({
+                    ...scope,
+                    suppressionId: suppression.suppressionId,
+                });
+            }
+            await setEnabled();
+        }
+        else {
+            const runBoundary = async (index) => {
+                const scope = scopes[index];
+                if (!scope) {
+                    await setEnabled();
+                    return;
+                }
+                await writeBehind.runGuildBarrier(scope, () => runBoundary(index + 1));
+            };
+            await runBoundary(0);
+            for (const scope of scopes)
+                await writeBehind.flushGuild(scope);
+            for (const scope of scopes)
+                await writeBehind.suppressGuild(scope);
+        }
         return this.getGuildState(input.guildId);
     }
     async updateConfiguration(input) {
         const module = this.#requireDashboardModule(input.moduleId);
         await this.#validateDiscordSettings(input.guildId, module, input.value);
+        if (module.configuration?.validateUpdate) {
+            try {
+                const value = module.configuration.validate(input.value);
+                await module.configuration.validateUpdate({
+                    guildId: input.guildId,
+                    value,
+                    services: this.#services,
+                });
+            }
+            catch (error) {
+                if (error instanceof ModuleStateValidationError)
+                    throw error;
+                throw new DashboardActionValidationError(error instanceof Error
+                    ? error.message
+                    : "The module rejected these settings.");
+            }
+        }
         const saved = await this.#configurations.update({
             guildId: input.guildId,
             moduleId: input.moduleId,
@@ -602,15 +673,13 @@ export class BotControlService {
         }));
     }
     async executeManagedResourceAction(input) {
-        const module = this.#requireDashboardModule(input.moduleId);
+        const { module, resource } = await this.#prepareManagedResource(input);
         const declared = module.manifest.dashboard?.resources
             ?.find(({ id }) => id === input.resourceType)
             ?.actions?.find(({ id }) => id === input.actionId);
-        const resource = this.#requireManagedResource(module, input.resourceType);
         this.#requireManagedResourceOperation(module, input.resourceType, "action");
         if (!declared)
             throw new BotControlNotFoundError("Managed resource action is not declared by this module");
-        await this.#requireEnabledManagedResource(input.guildId, input.moduleId);
         const permissionId = managedResourcePermissionId(module, input.resourceType, "action", input.actionId, declared.permissionId);
         const context = await this.#managedResourceContext(input, module, "action", permissionId);
         validateManagedResourceActionValue(declared.inputs ?? [], input.value);
@@ -627,7 +696,8 @@ export class BotControlService {
     async #prepareManagedResource(input) {
         const module = this.#requireDashboardModule(input.moduleId);
         const resource = this.#requireManagedResource(module, input.resourceType);
-        await this.#requireEnabledManagedResource(input.guildId, input.moduleId);
+        if (!resource.availableWhileDisabled)
+            await this.#requireEnabledManagedResource(input.guildId, input.moduleId);
         return { module, resource };
     }
     #requireManagedResource(module, resourceType) {
@@ -666,6 +736,10 @@ export class BotControlService {
         return {
             guildId: input.guildId,
             actor,
+            ...("actorAuthenticatedAt" in input &&
+                typeof input.actorAuthenticatedAt === "string"
+                ? { actorAuthenticatedAt: input.actorAuthenticatedAt }
+                : {}),
             correlationId: input.correlationId,
             services: this.#services,
             sendToChannel: (channelId, response) => this.resources.sendToChannel(channelId, response),
@@ -733,14 +807,25 @@ export class BotControlService {
             if (setting.type === "discord-channel") {
                 if (configured === "" || configured === undefined)
                     continue;
-                const channel = typeof configured === "string" ? channels.get(configured) : null;
-                if (!channel || !setting.channelTypes.includes(channel.type))
-                    throw new BotControlValidationError(`${setting.label} must be an available supported Discord channel`);
+                if (Boolean(setting.multiple) !== Array.isArray(configured))
+                    throw new BotControlValidationError(`${setting.label} has an invalid Discord channel selection`);
+                const configuredChannels = Array.isArray(configured)
+                    ? configured
+                    : [configured];
+                if (configuredChannels.length > MAX_DISCORD_SETTING_SELECTIONS ||
+                    new Set(configuredChannels).size !== configuredChannels.length ||
+                    configuredChannels.some((channelId) => {
+                        if (typeof channelId !== "string")
+                            return true;
+                        const channel = channels.get(channelId);
+                        return !channel || !setting.channelTypes.includes(channel.type);
+                    }))
+                    throw new BotControlValidationError(`${setting.label} must contain available supported Discord channels`);
             }
             if (setting.type === "discord-role") {
                 if (configured === "" || configured === undefined)
                     continue;
-                if (setting.multiple !== Array.isArray(configured))
+                if (Boolean(setting.multiple) !== Array.isArray(configured))
                     throw new BotControlValidationError(`${setting.label} has an invalid Discord role selection`);
                 const configuredRoles = Array.isArray(configured)
                     ? configured
@@ -1099,13 +1184,20 @@ export async function createBotControlServer(input) {
         const body = mutationContext
             .extend({
             expectedRevision: z.number().int().min(0),
-            value: managedResourceObject,
+            value: managedResourceObject.optional().default({}),
+            actorAuthenticatedAt: z.iso.datetime({ offset: true }).optional(),
         })
             .strict()
             .parse(request.body);
         return input.service.executeManagedResourceAction({
             ...params,
-            ...body,
+            actorUserId: body.actorUserId,
+            correlationId: body.correlationId,
+            expectedRevision: body.expectedRevision,
+            value: body.value,
+            ...(body.actorAuthenticatedAt === undefined
+                ? {}
+                : { actorAuthenticatedAt: body.actorAuthenticatedAt }),
         });
     });
     server.put("/v1/guilds/:guildId/modules/:moduleId/configuration", async (request) => {

package/dist/discord-owned-message-service.js

@@ -21,7 +21,7 @@ export class DiscordOwnedMessageDeletionService {
             return { cleared: false };
         const reaction = message.reactions.resolve(emoji.cacheKey);
         if (!reaction)
-            return { cleared: false };
+            return { cleared: true };
         await reaction.remove();
         return { cleared: true };
     }
@@ -108,6 +108,14 @@ function prepareEmojiIdentifier(value) {
     if (value.length < 1 || value.length > 128 || /[\r\n]/u.test(value)) {
         throw new Error("Invalid bounded Discord emoji identifier");
     }
+    const canonicalCustom = /^custom:(\d{17,20})$/u.exec(value);
+    if (canonicalCustom) {
+        const id = canonicalCustom[1];
+        return { identifier: id, cacheKey: id };
+    }
+    const canonicalUnicode = /^unicode:(.+)$/u.exec(value);
+    if (canonicalUnicode)
+        value = canonicalUnicode[1];
     const custom = /^(?:<a?:([A-Za-z0-9_]{2,32}):(\d{17,20})>|([A-Za-z0-9_]{2,32}):(\d{17,20}))$/u.exec(value);
     if (custom) {
         const name = custom[1] ?? custom[3];

package/dist/events.d.ts

@@ -1,4 +1,4 @@
-import type { DiscordChannelInspection, DiscordEmojiInspection, DiscordResourceInspectionService, DiscordRoleInspection, MemberRoleService, ModuleDefinition, ServiceAccess } from "@helyx/sdk";
+import type { DiscordChannelAudienceInspection, DiscordChannelInspection, DiscordEmojiInspection, DiscordMessageInspection, DiscordGuildCapabilityInspection, DiscordGuildChannelAudienceInspection, DiscordResourceInspectionService, DiscordRoleInspection, DiscordMessageService, MemberEnforcementService, MemberRoleService, ModuleDefinition, ServiceAccess } from "@helyx/sdk";
 import { type Client, type MessageReaction, type PartialMessageReaction } from "discord.js";
 import { type InteractionLogger } from "./interactions.js";
 export declare function installModuleEvents(client: Client, modules: readonly ModuleDefinition[], logger: InteractionLogger, services: ServiceAccess): ModuleEventHandle;
@@ -15,9 +15,30 @@ interface ApprovedRoleMutation {
     moduleId: string;
     reason: string;
 }
+export declare class DiscordMessageDeliveryService implements DiscordMessageService {
+    private readonly client;
+    constructor(client: Client);
+    send(input: Parameters<DiscordMessageService["send"]>[0]): ReturnType<DiscordMessageService["send"]>;
+    sendDirect(input: Parameters<DiscordMessageService["sendDirect"]>[0]): ReturnType<DiscordMessageService["sendDirect"]>;
+}
+export declare class DiscordMemberEnforcementService implements MemberEnforcementService {
+    #private;
+    private readonly client;
+    constructor(client: Client);
+    kick(input: Parameters<MemberEnforcementService["kick"]>[0]): ReturnType<MemberEnforcementService["kick"]>;
+}
 export declare class DiscordMemberRoleService implements MemberRoleService {
     private readonly client;
     constructor(client: Client);
+    createApprovedRole(input: {
+        guildId: string;
+        name: string;
+        moduleId: string;
+        reason: string;
+    }): Promise<{
+        roleId: string;
+        name: string;
+    }>;
     getCurrentRoleIds(input: {
         guildId: string;
         memberUserId: string;
@@ -45,6 +66,15 @@ export declare class DiscordResourceInspection implements DiscordResourceInspect
     #private;
     private readonly client;
     constructor(client: Client);
+    inspectGuildCapabilities(input: {
+        guildId: string;
+    }): Promise<DiscordGuildCapabilityInspection>;
+    inspectRuntimeCapabilities(): Promise<{
+        guildMembers: boolean;
+        guildMessages: boolean;
+        guildMessageReactions: boolean;
+        messageContent: boolean;
+    }>;
     resolveMemberSnapshots(input: {
         guildId: string;
         userIds: readonly string[];
@@ -61,6 +91,17 @@ export declare class DiscordResourceInspection implements DiscordResourceInspect
     }): Promise<readonly {
         userId: string;
         displayName: string | null;
+        avatarUrl?: string;
+    }[]>;
+    searchMembers(input: {
+        guildId: string;
+        query: string;
+        limit: number;
+    }): Promise<readonly {
+        userId: string;
+        displayName: string;
+        avatarUrl?: string;
+        isBot: boolean;
     }[]>;
     inspectRole(input: {
         guildId: string;
@@ -75,6 +116,28 @@ export declare class DiscordResourceInspection implements DiscordResourceInspect
         guildId: string;
         channelId: string;
     }): Promise<DiscordChannelInspection>;
+    inspectMessage(input: {
+        guildId: string;
+        channelId: string;
+        messageId: string;
+    }): Promise<DiscordMessageInspection>;
+    inspectChannelAudience(input: {
+        guildId: string;
+        channelId: string;
+        roleIds: readonly string[];
+    }): Promise<DiscordChannelAudienceInspection>;
+    inspectGuildChannelAudience(input: {
+        guildId: string;
+        roleIds: readonly string[];
+    }): Promise<DiscordGuildChannelAudienceInspection>;
+    seedMessageReaction(input: {
+        guildId: string;
+        channelId: string;
+        messageId: string;
+        emojiIdentifier: string;
+    }): Promise<{
+        added: boolean;
+    }>;
 }
 export {};
 //# sourceMappingURL=events.d.ts.map