@helyx/bot 0.4.2 → 0.4.5

package/dist/shard-worker.js

@@ -9,18 +9,22 @@ import { monitorEventLoopDelay } from "node:perf_hooks";
 import pino from "pino";
 import { createCloudManagementModule } from "./cloud-management-module.js";
 import { BotControlService, DiscordGuildResourceDirectory, mapBotControlError, } from "./control-server.js";
-import { installModuleEvents } from "./events.js";
+import { DiscordMemberRoleService, DiscordResourceInspection, installModuleEvents, } from "./events.js";
 import { installGuildTracking } from "./guilds.js";
 import { installInteractions, } from "./interactions.js";
 import { createManagementModule } from "./management-module.js";
 import { DiscordModuleLoggingService } from "./module-logging.js";
 import { resolveModulePackageSpecifiers } from "./module-configuration.js";
-import { loadConfiguredModulePackages } from "./modules.js";
+import { loadConfiguredModulePackages, platformServiceOptions, secureRandomSelectionWorkerKeyName, } from "./modules.js";
 import { createPermissionsModule } from "./permissions-module.js";
 import { WorkerCloudConnectorProxy } from "./shard-cloud-proxy.js";
+import { DiscordOwnedMessageDeletionService } from "./discord-owned-message-service.js";
+import { CoreResourceAuthorizationService } from "./resource-authorization.js";
 import { createDeveloperOperationsModule, WorkerShardHealthProvider, } from "./developer-operations-module.js";
 import { assertShardMessageSize, controlOperationGuildId, executeShardControlOperation, guildIdToShardId, SHARD_LEASE_HEARTBEAT_TIMEOUT_MS, shardIdentitySchema, supervisorMessageSchema, } from "./shard-contracts.js";
 import { gatewayIntentsForModules, readBotVersion, } from "./index.js";
+import { createSupportModule } from "./support-module.js";
+import { createLocalScheduledTaskRoute, } from "./scheduled-task-runner.js";
 const HEALTH_INTERVAL_MS = 5_000;
 export const WORKER_ORPHAN_TERMINATION_BOUND_MS = SHARD_LEASE_HEARTBEAT_TIMEOUT_MS + 5_000;
 export function createLeaseHeartbeatWatchdog(onExpired, timeoutMs = SHARD_LEASE_HEARTBEAT_TIMEOUT_MS) {
@@ -109,10 +113,8 @@ export async function startShardWorker(processEnvironment = process.env, identit
         const guildResources = new DiscordGuildResourceDirectory(client);
         const permissionsModule = createPermissionsModule(featureModules);
         const managementModule = createManagementModule(featureModules, guildResources);
-        cloudProxy = environment.HELYX_CLOUD_CONNECT_ENABLED
-            ? new WorkerCloudConnectorProxy()
-            : undefined;
-        const cloudManagementModule = cloudProxy
+        cloudProxy = new WorkerCloudConnectorProxy();
+        const cloudManagementModule = environment.HELYX_CLOUD_CONNECT_ENABLED
             ? createCloudManagementModule({
                 connector: cloudProxy,
                 client,
@@ -120,9 +122,11 @@ export async function startShardWorker(processEnvironment = process.env, identit
                 periodicOwnerRefresh: false,
             })
             : undefined;
+        const supportModule = createSupportModule(cloudProxy);
         const publicModules = [
             managementModule,
             permissionsModule,
+            supportModule,
             ...(cloudManagementModule ? [cloudManagementModule] : []),
             ...featureModules,
         ];
@@ -140,6 +144,7 @@ export async function startShardWorker(processEnvironment = process.env, identit
                 coreFunctions: [
                     managementModule,
                     permissionsModule,
+                    supportModule,
                     ...(cloudManagementModule ? [cloudManagementModule] : []),
                 ].map(({ manifest }) => manifest),
                 modules: featureModules.map(({ manifest }) => manifest),
@@ -151,14 +156,24 @@ export async function startShardWorker(processEnvironment = process.env, identit
             ...publicModules,
             ...(operationsModule ? [operationsModule] : []),
         ];
-        const platformServices = new Map(createPlatformServices(database, publicModules));
+        const platformServices = new Map(createPlatformServices(database, publicModules, platformServiceOptions(environment, publicModules)));
+        platformServices.set(HELYX_SERVICE_NAMES.resourceAuthorization, new CoreResourceAuthorizationService(platformServices.get(HELYX_SERVICE_NAMES.permissions)));
+        platformServices.set(HELYX_SERVICE_NAMES.discordOwnedMessages, new DiscordOwnedMessageDeletionService(client));
+        platformServices.set(HELYX_SERVICE_NAMES.memberRoles, new DiscordMemberRoleService(client));
+        platformServices.set(HELYX_SERVICE_NAMES.discordResources, new DiscordResourceInspection(client));
         if (featureModules.some(({ manifest }) => manifest.id === "helyx.logging"))
             platformServices.set(HELYX_SERVICE_NAMES.moduleLogging, new DiscordModuleLoggingService(client, database, publicModules, logger));
         const serviceAccess = new ServiceRegistry(platformServices);
+        const scheduledTaskRoute = createLocalScheduledTaskRoute({
+            modules: publicModules,
+            services: serviceAccess,
+            logger,
+        });
         runtime = createRuntime({ modules, logger, services: platformServices });
         const enabledCoreModuleIds = new Set([
             managementModule.manifest.id,
             permissionsModule.manifest.id,
+            supportModule.manifest.id,
             ...(cloudManagementModule ? [cloudManagementModule.manifest.id] : []),
             ...(operationsModule ? [operationsModule.manifest.id] : []),
         ]);
@@ -177,9 +192,16 @@ export async function startShardWorker(processEnvironment = process.env, identit
             ...(operationsModule
                 ? { operationsModuleId: operationsModule.manifest.id }
                 : {}),
+            supportModuleId: supportModule.manifest.id,
         }), logger, serviceAccess);
         moduleEvents = installModuleEvents(client, publicModules, logger, serviceAccess);
-        const controlService = new BotControlService(database, publicModules, guildResources, serviceAccess);
+        const controlService = new BotControlService(database, publicModules, guildResources, serviceAccess, undefined, environment.DISCORD_INTERNAL_GUILD_ID &&
+            environment.HELYX_SUPPORT_STAFF_CHANNEL_ID
+            ? {
+                guildId: environment.DISCORD_INTERNAL_GUILD_ID,
+                channelId: environment.HELYX_SUPPORT_STAFF_CHANNEL_ID,
+            }
+            : undefined);
         process.on("message", (raw) => {
             const parsed = supervisorMessageSchema.safeParse(raw);
             if (!parsed.success)
@@ -200,6 +222,13 @@ export async function startShardWorker(processEnvironment = process.env, identit
             else if (parsed.data.type === "helyx.operations.health.response") {
                 shardHealthProvider?.accept(parsed.data);
             }
+            else if (parsed.data.type === "helyx.scheduled.request") {
+                void executeShardScheduledTaskRequest(identity, parsed.data, scheduledTaskRoute).then((response) => {
+                    assertShardMessageSize(response);
+                    if (process.connected)
+                        process.send?.(response);
+                });
+            }
             else if (parsed.data.type === "helyx.shutdown") {
                 void shutdown(parsed.data.reason).finally(() => {
                     if (process.connected)
@@ -236,7 +265,8 @@ export async function startShardWorker(processEnvironment = process.env, identit
         client.on(Events.Error, (error) => {
             logger.error({ event: "discord.error", error: safeError(error) }, "Discord shard error");
         });
-        await cloudProxy?.start();
+        if (environment.HELYX_CLOUD_CONNECT_ENABLED)
+            await cloudProxy.start();
         await runtime.start();
         runtimeStarted = true;
         await client.login(environment.DISCORD_TOKEN);
@@ -253,6 +283,50 @@ export async function startShardWorker(processEnvironment = process.env, identit
         throw error;
     }
 }
+export async function executeShardScheduledTaskRequest(identity, request, route, now = Date.now()) {
+    const defer = (safeCode) => ({
+        version: 1,
+        type: "helyx.scheduled.response",
+        requestId: request.requestId,
+        result: { outcome: "deferred", delayMs: 1_000, safeCode },
+    });
+    if (!sameShardIdentity(request.identity, identity))
+        return defer("stale_owner");
+    if (new Date(request.deadlineAt).getTime() <= now)
+        return defer("deadline_expired");
+    if (guildIdToShardId(request.task.guildId, identity.shardCount) !==
+        identity.shardId)
+        return defer("wrong_shard");
+    const controller = new AbortController();
+    const remaining = Math.max(1, new Date(request.deadlineAt).getTime() - now);
+    const timer = setTimeout(() => controller.abort(), remaining);
+    timer.unref();
+    try {
+        return {
+            version: 1,
+            type: "helyx.scheduled.response",
+            requestId: request.requestId,
+            result: await route(request.task, controller.signal),
+        };
+    }
+    catch {
+        return {
+            version: 1,
+            type: "helyx.scheduled.response",
+            requestId: request.requestId,
+            result: {
+                outcome: "retry",
+                delayMs: 1_000,
+                safeCode: controller.signal.aborted
+                    ? "deadline_expired"
+                    : "handler_failed",
+            },
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 function sameShardIdentity(left, right) {
     return (left.generation === right.generation &&
         left.deploymentOrder === right.deploymentOrder &&
@@ -282,7 +356,8 @@ export function parseShardWorkerEnvironment(processEnvironment, identity) {
         ...(cloudEnabled
             ? {
                 HELYX_BOT_CONTROL_SECRET: Buffer.alloc(32).toString("base64"),
-                HELYX_DATA_ENCRYPTION_KEY: Buffer.alloc(32).toString("base64"),
+                HELYX_DATA_ENCRYPTION_KEY: processEnvironment[secureRandomSelectionWorkerKeyName] ??
+                    Buffer.alloc(32).toString("base64"),
             }
             : {}),
         ...(identity.scope === "coordinated"
@@ -293,7 +368,14 @@ export function parseShardWorkerEnvironment(processEnvironment, identity) {
         environment.HELYX_SHARD_MODE !== identity.mode ||
         environment.HELYX_SHARD_SCOPE !== identity.scope)
         throw new Error("Shard worker launch contract conflicts with configuration");
-    return environment;
+    const internalSelectionKey = processEnvironment[secureRandomSelectionWorkerKeyName];
+    return {
+        ...environment,
+        HELYX_DATA_ENCRYPTION_KEY: undefined,
+        ...(internalSelectionKey
+            ? { HELYX_INTERNAL_SECURE_RANDOM_SELECTION_KEY: internalSelectionKey }
+            : {}),
+    };
 }
 export function shardWorkerCommandRegistration(input) {
     return {
@@ -302,11 +384,10 @@ export function shardWorkerCommandRegistration(input) {
             : {}),
         prepare: input.prepare,
         synchronise: false,
-        ...(input.operationsModuleId
-            ? {
-                selfAuthorizingGuildModuleIds: new Set([input.operationsModuleId]),
-            }
-            : {}),
+        selfAuthorizingGuildModuleIds: new Set([
+            input.supportModuleId,
+            ...(input.operationsModuleId ? [input.operationsModuleId] : []),
+        ]),
     };
 }
 async function handleControl(identity, service, request) {

package/dist/support-module.d.ts

@@ -0,0 +1,9 @@
+import type { SupportBugCreatePayload, SupportBugCreateResponsePayload } from "@helyx/control-protocol";
+import { type ModuleDefinition } from "@helyx/sdk";
+export interface SupportBugTransport {
+    submitBug(input: SupportBugCreatePayload): Promise<Extract<SupportBugCreateResponsePayload, {
+        ok: true;
+    }>["result"]>;
+}
+export declare function createSupportModule(transport: SupportBugTransport): ModuleDefinition;
+//# sourceMappingURL=support-module.d.ts.map

package/dist/support-module.js

@@ -0,0 +1,172 @@
+import { defineModule, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { randomUUID } from "node:crypto";
+const MODAL_ID = "helyx.support.bug";
+const MODULE_FIELD_ID = "helyx.support.bug.module";
+const SUMMARY_FIELD_ID = "helyx.support.bug.summary";
+const HAPPENED_FIELD_ID = "helyx.support.bug.happened";
+const DETAIL_FIELD_ID = "helyx.support.bug.detail";
+const SUPPORT_URL = "https://app.helyx.gg/support";
+const MODULE_ID = "helyx.support";
+const HOUR_SECONDS = 60 * 60;
+export function createSupportModule(transport) {
+    return defineModule({
+        manifest: {
+            manifestVersion: "0.1",
+            releaseStatus: "live",
+            id: MODULE_ID,
+            name: "Helyx Support",
+            version: "0.1.0",
+            description: "Provides the always-available Helyx bug report command.",
+            entry: "./dist/support-module.js",
+            framework: "^0.1.0",
+            dependencies: [],
+            permissions: [],
+            contributions: { commands: ["bug"], events: [] },
+        },
+        interactions: {
+            commands: [
+                {
+                    name: "bug",
+                    description: "Report a Helyx bug to the support team",
+                    registration: "global",
+                    contexts: ["guild"],
+                    integrationTypes: ["guild_install"],
+                    async execute(context) {
+                        await context.showModal({
+                            customId: MODAL_ID,
+                            title: "Report a Helyx bug",
+                            fields: [
+                                {
+                                    customId: MODULE_FIELD_ID,
+                                    label: "Module or area",
+                                    style: "short",
+                                    required: true,
+                                    minLength: 1,
+                                    maxLength: 100,
+                                },
+                                {
+                                    customId: SUMMARY_FIELD_ID,
+                                    label: "Summary",
+                                    style: "short",
+                                    required: true,
+                                    minLength: 10,
+                                    maxLength: 200,
+                                },
+                                {
+                                    customId: HAPPENED_FIELD_ID,
+                                    label: "What happened?",
+                                    style: "paragraph",
+                                    required: true,
+                                    minLength: 10,
+                                    maxLength: 1_000,
+                                },
+                                {
+                                    customId: DETAIL_FIELD_ID,
+                                    label: "Steps to reproduce or extra detail",
+                                    style: "paragraph",
+                                    required: false,
+                                    maxLength: 1_000,
+                                },
+                            ],
+                        });
+                    },
+                },
+            ],
+            modals: [
+                {
+                    customId: MODAL_ID,
+                    async execute(context) {
+                        if (!context.serverId) {
+                            await context.reply(notSavedResponse());
+                            return;
+                        }
+                        const limits = context.services.get(HELYX_SERVICE_NAMES.rateLimits);
+                        const userLimit = await limits.consume({
+                            scope: "user",
+                            subjectId: context.userId,
+                            action: `${MODULE_ID}:bug:create:user`,
+                            limit: 5,
+                            windowSeconds: HOUR_SECONDS,
+                        });
+                        const guildLimit = userLimit.allowed
+                            ? await limits.consume({
+                                scope: "guild",
+                                subjectId: context.serverId,
+                                action: `${MODULE_ID}:bug:create:guild`,
+                                limit: 20,
+                                windowSeconds: HOUR_SECONDS,
+                            })
+                            : undefined;
+                        const denied = !userLimit.allowed
+                            ? userLimit
+                            : guildLimit && !guildLimit.allowed
+                                ? guildLimit
+                                : undefined;
+                        if (denied) {
+                            await context.reply({
+                                ephemeral: true,
+                                componentsV2: {
+                                    text: [
+                                        {
+                                            content: `Bug reporting is temporarily rate limited. Try again <t:${Math.ceil(denied.resetsAt.getTime() / 1_000)}:R>.`,
+                                        },
+                                    ],
+                                },
+                            });
+                            return;
+                        }
+                        await context.deferReply?.(true);
+                        const detail = context.getField(DETAIL_FIELD_ID).trim();
+                        try {
+                            const result = await transport.submitBug({
+                                operation: "support.bug.create.v1",
+                                reporterDiscordUserId: context.userId,
+                                guildId: context.serverId,
+                                moduleOrArea: context.getField(MODULE_FIELD_ID).trim(),
+                                summary: context.getField(SUMMARY_FIELD_ID).trim(),
+                                whatHappened: context.getField(HAPPENED_FIELD_ID).trim(),
+                                ...(detail ? { extraDetail: detail } : {}),
+                                interactionId: context.interactionId,
+                                correlationId: randomUUID(),
+                            });
+                            await context.reply(successResponse(result));
+                        }
+                        catch {
+                            await context.reply(notSavedResponse());
+                        }
+                    },
+                },
+            ],
+        },
+        start: () => Promise.resolve(),
+        stop: () => Promise.resolve(),
+    });
+}
+function successResponse(result) {
+    const content = result.claimUrl
+        ? `Bug report **${result.reference}** has been received from this self-hosted deployment. Use this one-time link to claim it, then track the report and reply through Helyx Support: ${result.claimUrl}`
+        : `Bug report **${result.reference}** has been received. You can track the report and reply through Helyx Support: ${SUPPORT_URL}`;
+    return {
+        ephemeral: true,
+        componentsV2: {
+            text: [
+                {
+                    content,
+                },
+            ],
+        },
+    };
+}
+function notSavedResponse() {
+    return {
+        ephemeral: true,
+        componentsV2: {
+            text: [
+                {
+                    content: `The bug report was not saved. Please use the Helyx dashboard: ${SUPPORT_URL}`,
+                },
+            ],
+        },
+    };
+}
+//# sourceMappingURL=support-module.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "0.4.2",
+  "version": "0.4.5",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",
@@ -48,14 +48,14 @@
     "start": "node --env-file-if-exists=../../.env dist/index.js"
   },
   "dependencies": {
-    "@helyx/config": "0.4.1",
-    "@helyx/control-protocol": "0.1.2",
-    "@helyx/core": "0.1.7",
-    "@helyx/database": "0.4.0",
-    "@helyx/framework": "0.1.7",
-    "@helyx/module-manifest": "0.4.0",
-    "@helyx/platform": "0.2.3",
-    "@helyx/sdk": "0.3.2",
+    "@helyx/config": "0.4.2",
+    "@helyx/control-protocol": "0.1.4",
+    "@helyx/core": "0.1.8",
+    "@helyx/database": "0.4.2",
+    "@helyx/framework": "0.1.8",
+    "@helyx/module-manifest": "0.4.1",
+    "@helyx/platform": "0.2.5",
+    "@helyx/sdk": "0.3.3",
     "discord.js": "14.27.0",
     "fastify": "5.10.0",
     "pino": "10.3.1",