@helyx/bot 0.4.24 → 0.4.25

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.4.25
+
+### Patch Changes
+
+- Launch the shared gaming statistics foundation and the Achievements, Counting and Trivia module integrations, while removing retired Access Control and Counting storage through guarded migrations.
+
 ## 0.4.24
 
 ### Patch Changes

package/README.md

@@ -23,6 +23,12 @@ resume secure weighted-selection checkpoints without exposing the selection
 key to a module. Keep it stable across deployments; do not rotate it while a
 giveaway is drawing.
 
+Trivia uses the operator-only `HELYX_TRIVIA_API_KEY`. Commercial deployments
+need a paid The Trivia API subscription. Guess reuses saved Multiple Choice
+questions and checks answers locally, so it does not require the provider's
+Complete subscription. Local development may exercise Multiple Choice without
+a key; production never enables the provider adapter without one.
+
 The always-available guild-only `/bug` command can be used by any guild member.
 Hosted deployments submit through the dedicated `HELYX_SUPPORT_SERVICE_SECRET`;
 paired self-hosted deployments use their authenticated Cloud Connect session

package/dist/cloud-connector.d.ts

@@ -4,7 +4,7 @@ import { type CloudConnectorConsentRecord, type DatabasePool } from "@helyx/data
 import type { Client } from "discord.js";
 import type { Logger } from "pino";
 import type { ConfiguredModulePackage } from "./modules.js";
-import type { BotControlHandler } from "./control-server.js";
+import { type BotControlHandler } from "./control-server.js";
 type ConnectorState = "disabled" | "unpaired" | "connecting" | "online" | "offline" | "recovery_required" | "revoked" | "stopped";
 export interface CloudConnectorStatus {
     state: ConnectorState;
@@ -80,5 +80,7 @@ export declare class CloudConnectorController implements CloudConnector {
 export declare class CloudConnectorUserError extends Error {
     constructor(message: string);
 }
+export declare function mapControlError(error: unknown): "not_found" | "conflict" | "bad_request" | "forbidden" | "temporarily_unavailable" | "internal_error";
+export declare function safeControlMessage(error: unknown): string;
 export {};
 //# sourceMappingURL=cloud-connector.d.ts.map

package/dist/cloud-connector.js

@@ -6,6 +6,7 @@ import { resolve } from "node:path";
 import WebSocket from "ws";
 import { z } from "zod";
 import { CloudControlDeniedError, CloudControlDispatcher, } from "./cloud-control-dispatcher.js";
+import { BotControlTransportError, } from "./control-server.js";
 const enrolmentFileSchema = z
     .object({
     schemaVersion: z.literal(1),
@@ -786,7 +787,19 @@ function connectedMessage(input) {
         payload: input.payload,
     });
 }
-function mapControlError(error) {
+export function mapControlError(error) {
+    if (error instanceof BotControlTransportError) {
+        if (error.status === 400)
+            return "bad_request";
+        if (error.status === 403)
+            return "forbidden";
+        if (error.status === 404)
+            return "not_found";
+        if (error.status === 409)
+            return "conflict";
+        if (error.status >= 502)
+            return "temporarily_unavailable";
+    }
     const name = error instanceof Error ? error.name : "";
     if (name.includes("NotFound"))
         return "not_found";
@@ -798,7 +811,7 @@ function mapControlError(error) {
         return "temporarily_unavailable";
     return "internal_error";
 }
-function safeControlMessage(error) {
+export function safeControlMessage(error) {
     const code = mapControlError(error);
     if (code === "not_found")
         return "The requested Helyx resource was not found";
@@ -808,6 +821,8 @@ function safeControlMessage(error) {
         return error instanceof Error
             ? error.message.slice(0, 300)
             : "The requested change was not valid";
+    if (code === "forbidden")
+        return "You do not have permission to make this change";
     if (code === "temporarily_unavailable")
         return "The self-hosted bot is temporarily unavailable";
     return "The self-hosted bot could not complete the request";

package/dist/events.js

@@ -14,6 +14,10 @@ export function installModuleEvents(client, modules, logger, services) {
             false,
         contribution,
     })));
+    const guildVoiceSessionContributions = modules.flatMap((module) => (module.events?.guildVoiceSession ?? []).map((contribution) => ({
+        moduleId: module.manifest.id,
+        contribution,
+    })));
     const messageClassificationRequested = modules.some((module) => module.requiredDiscordCapabilities?.includes("message-content"));
     const messageClassificationAvailable = messageClassificationRequested &&
         client.options.intents.has(GatewayIntentBits.MessageContent);
@@ -63,6 +67,7 @@ export function installModuleEvents(client, modules, logger, services) {
     })));
     if (privilegedMessageContributions.length === 0 &&
         guildMessageContributions.length === 0 &&
+        guildVoiceSessionContributions.length === 0 &&
         reactionContributions.length === 0 &&
         reactionRemoveContributions.length === 0 &&
         messageDeleteContributions.length === 0 &&
@@ -76,6 +81,7 @@ export function installModuleEvents(client, modules, logger, services) {
         guildEmojiUpdateContributions.length === 0)
         return { stop: () => Promise.resolve(), queueDepth: () => 0 };
     const queue = new BoundedGuildEventQueue(logger);
+    const voiceSessions = new Map();
     const privilegedEligibilityQueue = privilegedMessageContributions.length > 0
         ? new BoundedGuildEventQueue(logger)
         : null;
@@ -129,6 +135,13 @@ export function installModuleEvents(client, modules, logger, services) {
             guildMessageQueue.enqueue(message.guildId, () => handleGuildMessageCreate(message));
         });
     }
+    if (guildVoiceSessionContributions.length > 0) {
+        client.on(Events.VoiceStateUpdate, (before, after) => {
+            if ((after.member ?? before.member)?.user.bot)
+                return;
+            queue.enqueue(after.guild.id, () => handleVoiceState(before, after));
+        });
+    }
     if (reactionContributions.length > 0) {
         client.on(Events.MessageReactionAdd, (reaction, user, details) => {
             const guildId = reaction.message.guildId;
@@ -271,6 +284,8 @@ export function installModuleEvents(client, modules, logger, services) {
                     channelId: message.channelId,
                     ...(parentChannelId ? { parentChannelId } : {}),
                     messageId: message.id,
+                    isReply: message.reference?.messageId !== null &&
+                        message.reference?.messageId !== undefined,
                     authorId: message.author.id,
                     authorDisplayName,
                     authorRoleIds,
@@ -514,11 +529,64 @@ export function installModuleEvents(client, modules, logger, services) {
             }
         }
     }
+    async function handleVoiceState(before, after) {
+        const memberId = after.id;
+        const key = `${after.guild.id}:${memberId}`;
+        const previous = voiceSessions.get(key);
+        const channelId = eligibleVoiceChannel(after);
+        if (previous && previous.channelId !== channelId) {
+            voiceSessions.delete(key);
+            const endedAt = new Date();
+            const durationSeconds = Math.max(1, Math.floor((endedAt.getTime() - previous.startedAt.getTime()) / 1_000));
+            const installations = services.get(HELYX_SERVICE_NAMES.installations);
+            for (const { moduleId, contribution } of guildVoiceSessionContributions) {
+                try {
+                    if (!(await installations.isModuleEnabled(previous.guildId, moduleId)))
+                        continue;
+                    await contribution.execute({
+                        serverId: previous.guildId,
+                        channelId: previous.channelId,
+                        memberId,
+                        startedAt: previous.startedAt,
+                        endedAt,
+                        durationSeconds,
+                        services,
+                    });
+                }
+                catch (error) {
+                    logger.warn({
+                        event: "module.guild_voice_session_failed",
+                        moduleId,
+                        guildId: previous.guildId,
+                        error: safeError(error),
+                    }, "Module guild voice session event failed");
+                }
+            }
+        }
+        if (channelId && (!previous || previous.channelId !== channelId)) {
+            voiceSessions.set(key, {
+                guildId: after.guild.id,
+                memberId,
+                channelId,
+                startedAt: new Date(),
+            });
+        }
+    }
+    function eligibleVoiceChannel(state) {
+        if (!state.channelId || !state.channel)
+            return null;
+        if (state.channel.type !== ChannelType.GuildVoice)
+            return null;
+        if (state.guild.afkChannelId === state.channelId)
+            return null;
+        return state.channelId;
+    }
     return {
         stop: async () => {
             await privilegedEligibilityQueue?.stop();
             await guildMessageQueue?.stop();
             await queue.stop();
+            voiceSessions.clear();
         },
         queueDepth: () => queue.queueDepth() +
             (privilegedEligibilityQueue?.queueDepth() ?? 0) +

package/dist/index.js

@@ -2,7 +2,7 @@ import { parseBotEnvironment } from "@helyx/config";
 import { safeError, ServiceRegistry } from "@helyx/core";
 import { checkDatabaseConnection, createDatabasePool, AuditRepository, InteractionSessionRepository, RateLimitRepository, runCoreMigrations, runConfiguredModuleMigrations, } from "@helyx/database";
 import { createRuntime } from "@helyx/framework";
-import { createPlatformServices, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
+import { createPlatformServices, gamingStatisticsRecordOwner, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
 import { HELYX_SERVICE_NAMES, } from "@helyx/sdk";
 import { Client, Events, GatewayIntentBits, Partials } from "discord.js";
 import pino from "pino";
@@ -292,11 +292,11 @@ async function startUnshardedBot(processEnvironment) {
             ]),
         }, bootstrapLogger, serviceAccess);
         const moduleEvents = installModuleEvents(client, publicModules, bootstrapLogger, serviceAccess);
-        const controlService = new BotControlService(database, publicModules, guildResources, serviceAccess, privacyDatabase
+        const controlService = new BotControlService(database, [...publicModules, gamingStatisticsRecordOwner], guildResources, serviceAccess, privacyDatabase
             ? new PostgresPrivacyProviderExecutor({
                 readPool: database,
                 executorPool: privacyDatabase,
-                modules: featureModules,
+                modules: [...featureModules, gamingStatisticsRecordOwner],
             })
             : undefined, environment.DISCORD_INTERNAL_GUILD_ID &&
             environment.HELYX_SUPPORT_STAFF_CHANNEL_ID
@@ -484,6 +484,9 @@ export function gatewayIntentsForModules(modules, messageContentEnabled = false)
         module.events?.guildMemberRemove?.length)) {
         intents.push(GatewayIntentBits.GuildMembers);
     }
+    if (modules.some((module) => module.events?.guildVoiceSession?.length)) {
+        intents.push(GatewayIntentBits.GuildVoiceStates);
+    }
     if (modules.some((module) => module.events?.guildEmojiDelete?.length ||
         module.events?.guildEmojiUpdate?.length)) {
         intents.push(GatewayIntentBits.GuildExpressions);

package/dist/interactions.js

@@ -277,6 +277,20 @@ function addCommandOption(builder, option) {
             .setRequired(option.required ?? false));
         return;
     }
+    if (option.type === "integer") {
+        builder.addIntegerOption((optionBuilder) => {
+            optionBuilder
+                .setName(option.name)
+                .setDescription(option.description)
+                .setRequired(option.required ?? false);
+            if (option.minimum !== undefined)
+                optionBuilder.setMinValue(option.minimum);
+            if (option.maximum !== undefined)
+                optionBuilder.setMaxValue(option.maximum);
+            return optionBuilder;
+        });
+        return;
+    }
     if (option.type === "user") {
         builder.addUserOption((optionBuilder) => optionBuilder
             .setName(option.name)
@@ -399,6 +413,7 @@ function createCommandContext(interaction, services) {
         ...createContext(interaction, services),
         getStringOption: (name) => interaction.options.getString(name),
         getBooleanOption: (name) => interaction.options.getBoolean(name),
+        getIntegerOption: (name) => interaction.options.getInteger(name),
         getUserOption: (name) => {
             const user = interaction.options.getUser(name);
             return user

package/dist/modules.js

@@ -100,6 +100,7 @@ export function validateContributionParity(definition) {
     const executableEvents = [
         ...(definition.events?.privilegedMessageCreate ?? []),
         ...(definition.events?.guildMessageCreate ?? []),
+        ...(definition.events?.guildVoiceSession ?? []),
         ...(definition.events?.messageReactionAdd ?? []),
         ...(definition.events?.messageReactionRemove ?? []),
         ...(definition.events?.messageDelete ?? []),

package/dist/numeric-write-behind-proxy.js

@@ -275,8 +275,10 @@ function encodeRecord(input) {
             result[field] = { type: "string", value };
         else if (typeof value === "boolean")
             result[field] = { type: "boolean", value };
-        else
+        else if (typeof value === "number")
             result[field] = { type: "number", value };
+        else
+            throw new Error("Numeric write-behind values must be scalar");
     }
     return result;
 }

package/dist/shard-supervisor.js

@@ -1,6 +1,6 @@
 import { safeError, ServiceRegistry } from "@helyx/core";
 import { checkDatabaseConnection, createDatabasePool, AuditRepository, InteractionSessionRepository, RateLimitRepository, runConfiguredModuleMigrations, runCoreMigrations, RuntimeStateRepository, } from "@helyx/database";
-import { createPlatformServices, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
+import { createPlatformServices, gamingStatisticsRecordOwner, PostgresPrivacyProviderExecutor, } from "@helyx/platform";
 import { HELYX_SERVICE_NAMES } from "@helyx/sdk";
 import { Client, ShardingManager } from "discord.js";
 import { createHash, randomUUID } from "node:crypto";
@@ -230,11 +230,11 @@ export async function startShardSupervisor(environment, processEnvironment, work
             const services = new Map(createPlatformServices(database, publicModules, platformServiceOptions(environment, publicModules)));
             if (numericWriteBehind)
                 services.set(HELYX_SERVICE_NAMES.numericWriteBehind, numericWriteBehind);
-            privacyService = new BotControlService(database, publicModules, unavailableResources, new ServiceRegistry(services), privacyDatabase
+            privacyService = new BotControlService(database, [...publicModules, gamingStatisticsRecordOwner], unavailableResources, new ServiceRegistry(services), privacyDatabase
                 ? new PostgresPrivacyProviderExecutor({
                     readPool: database,
                     executorPool: privacyDatabase,
-                    modules: featureModules,
+                    modules: [...featureModules, gamingStatisticsRecordOwner],
                 })
                 : undefined);
             cloudConnector?.setControlHandler(new ShardControlRouter({

package/dist/shard-worker.d.ts

@@ -41,6 +41,7 @@ export declare function parseShardWorkerEnvironment(processEnvironment: NodeJS.P
     HELYX_GUILD_RECONCILIATION_INTERVAL_SECONDS: number;
     HELYX_PRIVACY_ENABLED: boolean;
     HELYX_MESSAGE_CONTENT_ENABLED: boolean;
+    HELYX_TRIVIA_API_KEY: string | undefined;
     HELYX_CLOUD_CONNECT_ENABLED: boolean;
     HELYX_CLOUD_ENROLMENT_TOKEN: string | undefined;
     HELYX_CLOUD_ENROLMENT_FILE: string;

package/dist/shard-worker.js

@@ -10,6 +10,7 @@ import pino from "pino";
 import { createCloudManagementModule } from "./cloud-management-module.js";
 import { BotControlService, DiscordGuildResourceDirectory, mapBotControlError, } from "./control-server.js";
 import { HttpVerificationService } from "./verification-service.js";
+import { HttpTriviaQuestionProvider } from "./trivia-provider.js";
 import { DiscordMessageDeliveryService, DiscordMemberEnforcementService, DiscordMemberRoleService, DiscordVerificationMemberService, DiscordResourceInspection, installModuleEvents, } from "./events.js";
 import { installGuildTracking, } from "./guilds.js";
 import { installInteractions, } from "./interactions.js";
@@ -182,6 +183,14 @@ export async function startShardWorker(processEnvironment = process.env, identit
             }));
             platformServices.set(HELYX_SERVICE_NAMES.verificationMembers, new DiscordVerificationMemberService(client));
         }
+        if (environment.HELYX_TRIVIA_API_KEY ||
+            environment.NODE_ENV !== "production") {
+            platformServices.set(HELYX_SERVICE_NAMES.triviaQuestions, new HttpTriviaQuestionProvider({
+                ...(environment.HELYX_TRIVIA_API_KEY
+                    ? { apiKey: environment.HELYX_TRIVIA_API_KEY }
+                    : {}),
+            }));
+        }
         numericWriteBehind =
             identity.scope === "coordinated"
                 ? new WorkerNumericWriteBehindProxy(identity)

package/dist/trivia-provider.d.ts

@@ -0,0 +1,15 @@
+import { type TriviaProviderFailureCode, type TriviaQuestion, type TriviaQuestionProvider } from "@helyx/sdk";
+export interface HttpTriviaQuestionProviderOptions {
+    apiKey?: string;
+    fetchImplementation?: typeof fetch;
+}
+export declare class HttpTriviaQuestionProvider implements TriviaQuestionProvider {
+    #private;
+    constructor(options: HttpTriviaQuestionProviderOptions);
+    getQuestions(input: Parameters<TriviaQuestionProvider["getQuestions"]>[0]): Promise<readonly TriviaQuestion[]>;
+    health(): Promise<{
+        status: "healthy" | "degraded" | "unavailable";
+        safeCode?: TriviaProviderFailureCode;
+    }>;
+}
+//# sourceMappingURL=trivia-provider.d.ts.map

package/dist/trivia-provider.js

@@ -0,0 +1,123 @@
+import { TRIVIA_CATEGORIES, TriviaProviderError, } from "@helyx/sdk";
+import { z } from "zod";
+const BASE_URL = "https://the-trivia-api.com/v2";
+const MAX_RESPONSE_BYTES = 256 * 1_024;
+const REQUEST_TIMEOUT_MS = 8_000;
+const questionSchema = z.object({
+    category: z.enum(TRIVIA_CATEGORIES),
+    id: z.string().regex(/^[A-Za-z0-9_-]{1,100}$/u),
+    tags: z.array(z.string().trim().min(1).max(100)).max(100),
+    difficulty: z.enum(["easy", "medium", "hard"]),
+    regions: z.array(z.string().trim().min(1).max(20)).max(100),
+    isNiche: z.boolean(),
+    question: z.object({ text: z.string().trim().min(1).max(2_000) }),
+    correctAnswer: z.string().trim().min(1).max(500),
+    incorrectAnswers: z.array(z.string().trim().min(1).max(500)).max(10),
+    type: z.literal("text_choice"),
+});
+export class HttpTriviaQuestionProvider {
+    #apiKey;
+    #fetch;
+    #lastFailure;
+    constructor(options) {
+        this.#apiKey = options.apiKey;
+        this.#fetch = options.fetchImplementation ?? fetch;
+    }
+    async getQuestions(input) {
+        if (!Number.isSafeInteger(input.limit) ||
+            input.limit < 1 ||
+            input.limit > 50)
+            this.#fail("invalid_response");
+        const query = new URLSearchParams({
+            limit: input.isNiche === undefined ? String(input.limit) : "50",
+            types: input.type,
+            contentFilter: input.familyContentOnly ? "family" : "all",
+        });
+        if (input.category)
+            query.set("categories", input.category);
+        if (input.difficulty)
+            query.set("difficulties", input.difficulty);
+        const raw = await this.#request(`/questions?${query.toString()}`, "GET");
+        const parsed = z.array(questionSchema).max(50).safeParse(raw);
+        if (!parsed.success) {
+            this.#fail("invalid_response");
+        }
+        const matching = parsed.data.filter((question) => question.type === input.type &&
+            (input.isNiche === undefined || question.isNiche === input.isNiche));
+        this.#lastFailure = undefined;
+        return matching.slice(0, input.limit);
+    }
+    health() {
+        return Promise.resolve(this.#lastFailure
+            ? { status: "degraded", safeCode: this.#lastFailure }
+            : { status: "healthy" });
+    }
+    async #request(path, method) {
+        let response;
+        try {
+            response = await this.#fetch(`${BASE_URL}${path}`, {
+                method,
+                headers: {
+                    accept: "application/json",
+                    ...(this.#apiKey ? { "x-api-key": this.#apiKey } : {}),
+                },
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+        }
+        catch (error) {
+            this.#fail(error instanceof DOMException && error.name === "TimeoutError"
+                ? "timeout"
+                : "unavailable");
+        }
+        if (!response.ok) {
+            if (response.status === 429)
+                this.#fail("rate_limited");
+            if (response.status === 401)
+                this.#fail("authentication");
+            if (response.status === 403)
+                this.#fail("subscription");
+            this.#fail(response.status >= 500 ? "unavailable" : "invalid_response");
+        }
+        try {
+            return JSON.parse(await readBoundedResponse(response));
+        }
+        catch (error) {
+            if (error instanceof TriviaProviderError)
+                throw error;
+            this.#fail("invalid_response");
+        }
+    }
+    #fail(code) {
+        this.#lastFailure = code;
+        throw new TriviaProviderError(code);
+    }
+}
+async function readBoundedResponse(response) {
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES)
+        throw new TriviaProviderError("invalid_response");
+    if (!response.body)
+        return "";
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            const boundedValue = chunk.value;
+            if (!(boundedValue instanceof Uint8Array))
+                throw new TriviaProviderError("invalid_response");
+            total += boundedValue.byteLength;
+            if (total > MAX_RESPONSE_BYTES)
+                throw new TriviaProviderError("invalid_response");
+            chunks.push(boundedValue);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks, total).toString("utf8");
+}
+//# sourceMappingURL=trivia-provider.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helyx/bot",
-  "version": "0.4.24",
+  "version": "0.4.25",
   "description": "Production Discord runtime for the modular Helyx platform.",
   "keywords": [
     "helyx",