@helyx/bot 0.4.37 → 0.4.39

package/dist/oauth-module.js

@@ -2,6 +2,7 @@ import { defineModule, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
 import { INTERNAL_MODULE_MANIFEST_FIELDS } from "./internal-module-manifest.js";
 const MODULE_ID = "helyx.oauth";
 const MODAL_ID = "helyx.oauth.revoke";
+const OPEN_MODAL_ID = "helyx.oauth.revoke.open";
 const SERVICE_FIELD_ID = "helyx.oauth.revoke.service";
 const CONFIRM_FIELD_ID = "helyx.oauth.revoke.confirm";
 const COMMENT_FIELD_ID = "helyx.oauth.revoke.comment";
@@ -14,6 +15,7 @@ const everyonePolicy = {
     deniedUserIds: [],
 };
 export function createOAuthModule() {
+    const preparedModals = new Map();
     return defineModule({
         manifest: {
             ...INTERNAL_MODULE_MANIFEST_FIELDS,
@@ -26,108 +28,153 @@ export function createOAuthModule() {
             framework: "^0.1.0",
             dependencies: [],
             permissions: [],
-            contributions: { commands: ["oauth"], events: [] },
+            contributions: { commands: ["helyx.connections"], events: [] },
         },
         defaultPermissions: {
             module: everyonePolicy,
             commands: { "oauth.revoke": everyonePolicy },
         },
+        sharedCommands: [
+            {
+                family: "helyx",
+                path: "connections",
+                permissionId: "oauth.revoke",
+                description: "Review or revoke OAuth access granted to Helyx.",
+                acknowledgement: "deferred-ephemeral",
+                authorization: "public",
+                rateLimit: { scope: "user", limit: 5, windowSeconds: 60 },
+                execute: async (context) => {
+                    const oauth = context.services.get(HELYX_SERVICE_NAMES.oauth);
+                    let connections;
+                    try {
+                        connections = await oauth.listConnections({
+                            discordUserId: context.userId,
+                        });
+                    }
+                    catch {
+                        await context.reply(unavailable());
+                        return;
+                    }
+                    if (connections.length === 0) {
+                        await context.reply({
+                            ephemeral: true,
+                            componentsV2: {
+                                text: [
+                                    {
+                                        content: "You do not have any OAuth services connected to Helyx.",
+                                    },
+                                ],
+                            },
+                        });
+                        return;
+                    }
+                    const definition = {
+                        customId: MODAL_ID,
+                        title: "Revoke OAuth access",
+                        items: [
+                            {
+                                type: "text-display",
+                                content: "Choose one connection. This disconnects the service from Helyx everywhere. Any Helyx module, server or panel using it will lose access.",
+                            },
+                            {
+                                type: "string-select",
+                                customId: SERVICE_FIELD_ID,
+                                label: "Connected service",
+                                placeholder: "Choose a connection",
+                                required: true,
+                                minValues: 1,
+                                maxValues: 1,
+                                options: connections.slice(0, 25).map((connection) => ({
+                                    label: `${providerName(connection.provider)} — ${connection.displayName}`.slice(0, 100),
+                                    value: connection.selectionRef,
+                                    description: "Remove this connection",
+                                })),
+                            },
+                            {
+                                type: "string-select",
+                                customId: CONFIRM_FIELD_ID,
+                                label: "Confirm removal",
+                                placeholder: "Select Remove access",
+                                required: true,
+                                minValues: 1,
+                                maxValues: 1,
+                                options: [
+                                    {
+                                        label: "Remove access",
+                                        value: "remove_access",
+                                        description: "Revoke access and delete my stored details",
+                                    },
+                                ],
+                            },
+                            {
+                                customId: COMMENT_FIELD_ID,
+                                label: "Reason or comment (optional)",
+                                description: "Stored only in Helyx's restricted security audit.",
+                                style: "paragraph",
+                                required: false,
+                                maxLength: 250,
+                            },
+                        ],
+                        fields: [],
+                    };
+                    for (const [userId, prepared] of preparedModals) {
+                        if (prepared.expiresAt <= Date.now())
+                            preparedModals.delete(userId);
+                    }
+                    preparedModals.set(context.userId, {
+                        definition,
+                        expiresAt: Date.now() + 2 * 60 * 1_000,
+                    });
+                    await context.reply({
+                        ephemeral: true,
+                        componentsV2: {
+                            text: [
+                                {
+                                    content: `Found ${connections.length} connected service${connections.length === 1 ? "" : "s"}. Open the secure form to choose which connection to remove.`,
+                                },
+                            ],
+                        },
+                        buttons: [
+                            {
+                                type: "button",
+                                customId: OPEN_MODAL_ID,
+                                label: "Open connection form",
+                                style: "primary",
+                            },
+                        ],
+                    });
+                },
+            },
+        ],
         interactions: {
-            commands: [
+            buttons: [
                 {
-                    name: "oauth",
-                    description: "Manage OAuth access granted to Helyx.",
-                    registration: "global",
-                    contexts: ["guild"],
-                    integrationTypes: ["guild_install"],
-                    subcommands: [
-                        {
-                            name: "revoke",
-                            description: "Revoke a service and delete the OAuth details Helyx stores for you.",
-                            acknowledgement: "immediate-modal",
-                            rateLimit: { scope: "user", limit: 5, windowSeconds: 60 },
-                            execute: async (context) => {
-                                const oauth = context.services.get(HELYX_SERVICE_NAMES.oauth);
-                                let connections;
-                                try {
-                                    connections = await oauth.listConnections({
-                                        discordUserId: context.userId,
-                                    });
-                                }
-                                catch {
-                                    await context.reply(unavailable());
-                                    return;
-                                }
-                                if (connections.length === 0) {
-                                    await context.reply({
-                                        ephemeral: true,
-                                        componentsV2: {
-                                            text: [
-                                                {
-                                                    content: "You do not have any OAuth services connected to Helyx.",
-                                                },
-                                            ],
-                                        },
-                                    });
-                                    return;
-                                }
-                                await context.showModal({
-                                    customId: MODAL_ID,
-                                    title: "Revoke OAuth access",
-                                    items: [
-                                        {
-                                            type: "text-display",
-                                            content: "Choose one connection. This disconnects the service from Helyx everywhere. Any Helyx module, server or panel using it will lose access.",
-                                        },
-                                        {
-                                            type: "string-select",
-                                            customId: SERVICE_FIELD_ID,
-                                            label: "Connected service",
-                                            placeholder: "Choose a connection",
-                                            required: true,
-                                            minValues: 1,
-                                            maxValues: 1,
-                                            options: connections.slice(0, 25).map((connection) => ({
-                                                label: `${providerName(connection.provider)} — ${connection.displayName}`.slice(0, 100),
-                                                value: connection.selectionRef,
-                                                description: "Remove this connection",
-                                            })),
-                                        },
-                                        {
-                                            type: "string-select",
-                                            customId: CONFIRM_FIELD_ID,
-                                            label: "Confirm removal",
-                                            placeholder: "Select Remove access",
-                                            required: true,
-                                            minValues: 1,
-                                            maxValues: 1,
-                                            options: [
-                                                {
-                                                    label: "Remove access",
-                                                    value: "remove_access",
-                                                    description: "Revoke access and delete my stored details",
-                                                },
-                                            ],
-                                        },
+                    customId: OPEN_MODAL_ID,
+                    authorization: "public",
+                    execute: async (context) => {
+                        const prepared = preparedModals.get(context.userId);
+                        preparedModals.delete(context.userId);
+                        if (!prepared || prepared.expiresAt <= Date.now()) {
+                            await context.reply({
+                                ephemeral: true,
+                                componentsV2: {
+                                    text: [
                                         {
-                                            customId: COMMENT_FIELD_ID,
-                                            label: "Reason or comment (optional)",
-                                            description: "Stored only in Helyx's restricted security audit.",
-                                            style: "paragraph",
-                                            required: false,
-                                            maxLength: 250,
+                                            content: "This connection form expired. Run `/helyx connections` again.",
                                         },
                                     ],
-                                    fields: [],
-                                });
-                            },
-                        },
-                    ],
+                                },
+                            });
+                            return;
+                        }
+                        await context.showModal(prepared.definition);
+                    },
                 },
             ],
             modals: [
                 {
                     customId: MODAL_ID,
+                    acknowledgement: "deferred-ephemeral",
                     execute: async (context) => {
                         const selectionRef = context.getStringSelectValues(SERVICE_FIELD_ID)[0];
                         const confirmation = context.getStringSelectValues(CONFIRM_FIELD_ID)[0];
@@ -141,7 +188,6 @@ export function createOAuthModule() {
                             return;
                         }
                         const comment = context.getField(COMMENT_FIELD_ID).trim();
-                        await context.deferReply?.(true);
                         try {
                             const result = await context.services
                                 .get(HELYX_SERVICE_NAMES.oauth)

package/dist/permissions-module.js

@@ -10,6 +10,7 @@ const MODULE_NEXT_ID = "helyx.permissions.module.next";
 const TARGET_PREVIOUS_ID = "helyx.permissions.target.previous";
 const TARGET_NEXT_ID = "helyx.permissions.target.next";
 const POLICY_MODAL_ID = "helyx.permissions.policy";
+const OPEN_POLICY_MODAL_ID = "helyx.permissions.policy.open";
 const EVERYONE_FIELD_ID = "helyx.permissions.policy.everyone";
 const REQUIRED_PERMISSIONS_FIELD_ID = "helyx.permissions.policy.required";
 const ALLOWED_MENTIONABLES_FIELD_ID = "helyx.permissions.policy.allowed";
@@ -25,6 +26,8 @@ export function createPermissionsModule(configurableModules) {
     const commandModules = [...modules.values()]
         .filter((module) => commandTargets(module).length > 0)
         .sort((left, right) => left.manifest.name.localeCompare(right.manifest.name, "en-GB"));
+    const preparedPolicies = new Map();
+    const preparedPolicyKey = (serverId, userId) => `${serverId}:${userId}`;
     return defineModule({
         manifest: {
             ...INTERNAL_MODULE_MANIFEST_FIELDS,
@@ -37,7 +40,7 @@ export function createPermissionsModule(configurableModules) {
             framework: "^0.1.0",
             dependencies: [],
             permissions: [],
-            contributions: { commands: ["permissions"], events: [] },
+            contributions: { commands: ["helyx.permissions"], events: [] },
         },
         defaultPermissions: {
             module: restrictedPolicy(),
@@ -45,47 +48,49 @@ export function createPermissionsModule(configurableModules) {
                 permissions: restrictedPolicy(),
             },
         },
-        interactions: {
-            commands: [
-                {
-                    name: "permissions",
-                    description: "Configure access to Helyx modules and commands",
-                    acknowledgement: "deferred-ephemeral",
-                    registration: "global",
-                    contexts: ["guild"],
-                    integrationTypes: ["guild_install"],
-                    rateLimit: { scope: "user", limit: 20, windowSeconds: 60 },
-                    async execute(context) {
-                        if (!context.serverId)
-                            return;
-                        if (commandModules.length === 0) {
-                            await context.reply({
-                                ephemeral: true,
-                                embed: {
-                                    title: "No configurable modules",
-                                    description: "Install a feature module that contributes Discord commands first.",
-                                    color: 0xdc2626,
-                                },
-                            });
-                            return;
-                        }
-                        await context.services
-                            .get(HELYX_SERVICE_NAMES.sessions)
-                            .create({
-                            guildId: context.serverId,
-                            userId: context.userId,
-                            purpose: SESSION_PURPOSE,
-                            state: { modulePage: 0 },
-                            expiresAt: new Date(Date.now() + 10 * 60 * 1_000),
-                            replace: true,
+        sharedCommands: [
+            {
+                family: "helyx",
+                path: "permissions",
+                permissionId: "permissions",
+                description: "Configure access to Helyx modules and commands",
+                acknowledgement: "deferred-ephemeral",
+                rateLimit: { scope: "user", limit: 20, windowSeconds: 60 },
+                async execute(context) {
+                    if (!context.serverId) {
+                        await context.reply(serverOnlyResponse());
+                        return;
+                    }
+                    if (commandModules.length === 0) {
+                        await context.reply({
+                            ephemeral: true,
+                            embed: {
+                                title: "No configurable modules",
+                                description: "Install a feature module that contributes Discord commands first.",
+                                color: 0xdc2626,
+                            },
                         });
-                        await context.reply(modulePickerResponse(commandModules, 0));
-                    },
+                        return;
+                    }
+                    await context.services
+                        .get(HELYX_SERVICE_NAMES.sessions)
+                        .create({
+                        guildId: context.serverId,
+                        userId: context.userId,
+                        purpose: SESSION_PURPOSE,
+                        state: { modulePage: 0 },
+                        expiresAt: new Date(Date.now() + 10 * 60 * 1_000),
+                        replace: true,
+                    });
+                    await context.reply(modulePickerResponse(commandModules, 0));
                 },
-            ],
+            },
+        ],
+        interactions: {
             selects: [
                 {
                     customId: MODULE_SELECT_ID,
+                    acknowledgement: "deferred-update",
                     async execute(context) {
                         const session = await getSession(context);
                         if (!session || !context.serverId)
@@ -113,6 +118,7 @@ export function createPermissionsModule(configurableModules) {
                 },
                 {
                     customId: TARGET_SELECT_ID,
+                    acknowledgement: "deferred-update",
                     async execute(context) {
                         const session = await getSession(context);
                         if (!session || !context.serverId)
@@ -156,7 +162,7 @@ export function createPermissionsModule(configurableModules) {
                             },
                             expectedVersion: session.version,
                         });
-                        await context.showModal({
+                        const definition = {
                             customId: POLICY_MODAL_ID,
                             title: "Edit permission policy",
                             fields: [
@@ -213,11 +219,63 @@ export function createPermissionsModule(configurableModules) {
                                     defaultValues: deniedDefaults,
                                 },
                             ],
+                        };
+                        for (const [key, prepared] of preparedPolicies) {
+                            if (prepared.expiresAt <= Date.now())
+                                preparedPolicies.delete(key);
+                        }
+                        preparedPolicies.set(preparedPolicyKey(context.serverId, context.userId), {
+                            definition,
+                            expiresAt: Date.now() + 2 * 60 * 1_000,
+                        });
+                        await context.reply({
+                            ephemeral: true,
+                            componentsV2: {
+                                text: [
+                                    {
+                                        content: "The current permission policy is ready. Open the editor to make changes.",
+                                    },
+                                ],
+                            },
+                            buttons: [
+                                {
+                                    type: "button",
+                                    customId: OPEN_POLICY_MODAL_ID,
+                                    label: "Open policy editor",
+                                    style: "primary",
+                                },
+                            ],
                         });
                     },
                 },
             ],
             buttons: [
+                {
+                    customId: OPEN_POLICY_MODAL_ID,
+                    authorization: "public",
+                    async execute(context) {
+                        const key = context.serverId
+                            ? preparedPolicyKey(context.serverId, context.userId)
+                            : null;
+                        const prepared = key ? preparedPolicies.get(key) : undefined;
+                        if (key)
+                            preparedPolicies.delete(key);
+                        if (!prepared || prepared.expiresAt <= Date.now()) {
+                            await context.reply({
+                                ephemeral: true,
+                                componentsV2: {
+                                    text: [
+                                        {
+                                            content: "This policy editor expired. Run `/helyx permissions` again.",
+                                        },
+                                    ],
+                                },
+                            });
+                            return;
+                        }
+                        await context.showModal(prepared.definition);
+                    },
+                },
                 modulePageButton(MODULE_PREVIOUS_ID, -1),
                 modulePageButton(MODULE_NEXT_ID, 1),
                 targetPageButton(TARGET_PREVIOUS_ID, -1),
@@ -226,6 +284,7 @@ export function createPermissionsModule(configurableModules) {
             modals: [
                 {
                     customId: POLICY_MODAL_ID,
+                    acknowledgement: "deferred-ephemeral",
                     async execute(context) {
                         const session = await getSession(context);
                         if (!session || !context.serverId)
@@ -309,6 +368,7 @@ export function createPermissionsModule(configurableModules) {
     function modulePageButton(customId, change) {
         return {
             customId,
+            acknowledgement: "deferred-update",
             async execute(context) {
                 const session = await getSession(context);
                 if (!session)
@@ -329,6 +389,7 @@ export function createPermissionsModule(configurableModules) {
     function targetPageButton(customId, change) {
         return {
             customId,
+            acknowledgement: "deferred-update",
             async execute(context) {
                 const session = await getSession(context);
                 if (!session)
@@ -352,6 +413,18 @@ export function createPermissionsModule(configurableModules) {
         };
     }
 }
+function serverOnlyResponse() {
+    return {
+        ephemeral: true,
+        componentsV2: {
+            text: [
+                {
+                    content: "This command needs a server. Open a server where Helyx is installed, then use `/helyx permissions` there.",
+                },
+            ],
+        },
+    };
+}
 function restrictedPolicy() {
     return {
         everyone: false,
@@ -373,7 +446,7 @@ function commandTargets(module) {
             return nested;
         return [command.name];
     });
-    targets.push(...(module.nexusCommands ?? []).map((command) => `nexus.${command.path}`));
+    targets.push(...(module.sharedCommands ?? []).map((command) => command.permissionId ?? `${command.family}.${command.path}`), ...(module.nexusCommands ?? []).map((command) => `nexus.${command.path}`));
     return [...new Set(targets)];
 }
 function modulePickerResponse(modules, requestedPage) {

package/dist/privacy-module.d.ts

@@ -0,0 +1,2 @@
+export declare function createPrivacyModule(): import("@helyx/sdk").ModuleDefinition;
+//# sourceMappingURL=privacy-module.d.ts.map

package/dist/privacy-module.js

@@ -0,0 +1,60 @@
+import { defineModule } from "@helyx/sdk";
+import { INTERNAL_MODULE_MANIFEST_FIELDS } from "./internal-module-manifest.js";
+const everyonePolicy = {
+    everyone: true,
+    requiredPermissions: [],
+    allowedRoleIds: [],
+    deniedRoleIds: [],
+    allowedUserIds: [],
+    deniedUserIds: [],
+};
+export function createPrivacyModule() {
+    return defineModule({
+        manifest: {
+            ...INTERNAL_MODULE_MANIFEST_FIELDS,
+            releaseStatus: "live",
+            id: "helyx.privacy",
+            name: "Helyx Privacy",
+            version: "0.1.0",
+            description: "Provides an always-available route to Helyx data controls.",
+            entry: "./dist/privacy-module.js",
+            framework: "^0.1.0",
+            dependencies: [],
+            permissions: [],
+            contributions: { commands: ["helyx.privacy"], events: [] },
+        },
+        defaultPermissions: {
+            module: everyonePolicy,
+            commands: { "helyx.privacy": everyonePolicy },
+        },
+        sharedCommands: [
+            {
+                family: "helyx",
+                path: "privacy",
+                permissionId: "helyx.privacy",
+                description: "Open the Helyx Privacy Centre and data controls",
+                acknowledgement: "immediate-response",
+                authorization: "public",
+                async execute(context) {
+                    await context.reply({
+                        ephemeral: true,
+                        componentsV2: {
+                            text: [
+                                {
+                                    content: "## Helyx Privacy Centre\nView your data and request changes or deletion at [app.helyx.gg/privacy](https://app.helyx.gg/privacy).",
+                                },
+                            ],
+                        },
+                    });
+                },
+            },
+        ],
+        start() {
+            return Promise.resolve();
+        },
+        stop() {
+            return Promise.resolve();
+        },
+    });
+}
+//# sourceMappingURL=privacy-module.js.map

package/dist/scheduled-task-runner.js

@@ -1,4 +1,4 @@
-import { CORE_RECORD_RETENTION_TASK, ScheduledTaskRepository, } from "@helyx/database";
+import { CORE_RECORD_RETENTION_TASK, MODULE_ACTIVATION_RECOVERY_TASK, ScheduledTaskRepository, } from "@helyx/database";
 import { getModuleScheduledTaskContribution, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
 import { randomUUID } from "node:crypto";
 const DEFAULT_POLL_INTERVAL_MS = 1_000;
@@ -279,6 +279,16 @@ export function createScheduledTaskRunner(input) {
                 delivery: "one-shot",
                 runWhenDisabled: true,
             },
+            ...input.modules
+                .filter((module) => typeof module.onActivated === "function" ||
+                typeof module.onDeactivated === "function")
+                .map((module) => ({
+                moduleId: module.manifest.id,
+                taskKind: MODULE_ACTIVATION_RECOVERY_TASK.taskKind,
+                taskVersion: MODULE_ACTIVATION_RECOVERY_TASK.taskVersion,
+                delivery: "one-shot",
+                runWhenDisabled: true,
+            })),
             ...input.modules.flatMap((module) => (module.scheduledTasks ?? []).map((contribution) => ({
                 moduleId: module.manifest.id,
                 taskKind: contribution.kind,
@@ -328,6 +338,24 @@ export function createLocalScheduledTaskRoute(input) {
         const module = modules.get(task.moduleId);
         if (!module)
             return deferred("module_unavailable", DEFAULT_POLL_INTERVAL_MS * 30);
+        if (task.taskKind === MODULE_ACTIVATION_RECOVERY_TASK.taskKind &&
+            task.taskVersion === MODULE_ACTIVATION_RECOVERY_TASK.taskVersion &&
+            task.delivery === "one-shot") {
+            const state = parseActivationRecoveryState(task.payload);
+            if (!state || !task.guildId)
+                return { outcome: "requires_review", safeCode: "payload_invalid" };
+            const enabled = await input.services
+                .get(HELYX_SERVICE_NAMES.installations)
+                .isModuleEnabled(task.guildId, task.moduleId);
+            if (enabled !== (state === "enabled"))
+                return { outcome: "completed" };
+            const context = { guildId: task.guildId, services: input.services };
+            if (state === "enabled")
+                await module.onActivated?.(context);
+            else
+                await module.onDeactivated?.(context);
+            return { outcome: "completed" };
+        }
         if (typeof input.services.has === "function" &&
             input.services.has(HELYX_SERVICE_NAMES.moduleAvailability)) {
             const availability = input.services.get(HELYX_SERVICE_NAMES.moduleAvailability);
@@ -368,6 +396,13 @@ export function createLocalScheduledTaskRoute(input) {
         }, task);
     };
 }
+function parseActivationRecoveryState(payload) {
+    if (Object.keys(payload).length !== 1)
+        return null;
+    return payload.stateId === "enabled" || payload.stateId === "disabled"
+        ? payload.stateId
+        : null;
+}
 function toExecution(task) {
     const common = {
         taskId: task.record.id,