@helyx/bot 1.6.0 → 1.7.0

package/dist/help-credentials.js

@@ -0,0 +1,149 @@
+import { createCipheriv, createDecipheriv, createHmac, randomBytes, randomUUID, } from "node:crypto";
+import { mkdir, lstat, readFile, writeFile, rename, rm, chmod, } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import { z } from "zod";
+export const HELP_API_ORIGIN = "https://api.helyx.gg";
+const credentialSchema = z
+    .object({
+    installationId: z.string().uuid(),
+    token: z.string().regex(/^hhp_[A-Za-z0-9_-]{43}$/u),
+    expiresAt: z.string().datetime(),
+})
+    .strict();
+export const parseHelpCredential = (value) => credentialSchema.parse(value);
+const storedSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    installationId: z.string().uuid(),
+    expiresAt: z.string().datetime(),
+    iv: z.string().regex(/^[a-f0-9]{24}$/u),
+    tag: z.string().regex(/^[a-f0-9]{32}$/u),
+    ciphertext: z.string().regex(/^[a-f0-9]{94}$/u),
+})
+    .strict();
+export class HelpCredentialError extends Error {
+    constructor() {
+        super("The private Help credential could not be read or saved. Check the local data-encryption key and file permissions.");
+    }
+}
+const missing = (error) => !!error &&
+    typeof error === "object" &&
+    "code" in error &&
+    error.code === "ENOENT";
+/** Encrypted, opt-in file; separate from Cloud Connect and every provider secret. */
+export class HelpCredentialStore {
+    path;
+    key;
+    constructor(directory, dataKey) {
+        this.path = resolve(directory, ".helyx/help-credential.json");
+        const decoded = Buffer.from(dataKey, "base64");
+        if (decoded.length !== 32)
+            throw new HelpCredentialError();
+        this.key = createHmac("sha256", decoded)
+            .update("helyx.help.credential.v1")
+            .digest();
+    }
+    aad(id, expiresAt) {
+        return Buffer.from(`helyx.help.credential.v1:${id}:${expiresAt}`);
+    }
+    async checkDirectory() {
+        try {
+            const stat = await lstat(dirname(this.path));
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                throw new HelpCredentialError();
+        }
+        catch (error) {
+            if (!missing(error))
+                throw error;
+        }
+    }
+    async read() {
+        try {
+            await this.checkDirectory();
+            let stat;
+            try {
+                stat = await lstat(this.path);
+            }
+            catch (error) {
+                if (missing(error))
+                    return null;
+                throw error;
+            }
+            if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 4096)
+                throw new HelpCredentialError();
+            const value = storedSchema.parse(JSON.parse(await readFile(this.path, "utf8"))), decipher = createDecipheriv("aes-256-gcm", this.key, Buffer.from(value.iv, "hex"));
+            decipher.setAAD(this.aad(value.installationId, value.expiresAt));
+            decipher.setAuthTag(Buffer.from(value.tag, "hex"));
+            const token = Buffer.concat([
+                decipher.update(Buffer.from(value.ciphertext, "hex")),
+                decipher.final(),
+            ]).toString("utf8");
+            return credentialSchema.parse({
+                installationId: value.installationId,
+                expiresAt: value.expiresAt,
+                token,
+            });
+        }
+        catch {
+            throw new HelpCredentialError();
+        }
+    }
+    async save(input) {
+        const temporary = this.path + `.${randomUUID()}.tmp`;
+        try {
+            const credential = credentialSchema.parse(input);
+            await this.checkDirectory();
+            await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+            await this.checkDirectory();
+            await chmod(dirname(this.path), 0o700);
+            const existing = await lstat(this.path).catch((error) => {
+                if (missing(error))
+                    return null;
+                throw error;
+            });
+            if (existing && (!existing.isFile() || existing.isSymbolicLink()))
+                throw new HelpCredentialError();
+            const iv = randomBytes(12), cipher = createCipheriv("aes-256-gcm", this.key, iv);
+            cipher.setAAD(this.aad(credential.installationId, credential.expiresAt));
+            const ciphertext = Buffer.concat([
+                cipher.update(credential.token, "utf8"),
+                cipher.final(),
+            ]);
+            await writeFile(temporary, JSON.stringify({
+                schemaVersion: 1,
+                installationId: credential.installationId,
+                expiresAt: credential.expiresAt,
+                iv: iv.toString("hex"),
+                tag: cipher.getAuthTag().toString("hex"),
+                ciphertext: ciphertext.toString("hex"),
+            }) + "\n", { flag: "wx", mode: 0o600 });
+            await rename(temporary, this.path);
+            await chmod(this.path, 0o600);
+        }
+        catch {
+            throw new HelpCredentialError();
+        }
+        finally {
+            await rm(temporary, { force: true }).catch(() => undefined);
+        }
+    }
+    async remove() {
+        try {
+            await this.checkDirectory();
+            const stat = await lstat(this.path).catch((error) => {
+                if (missing(error))
+                    return null;
+                throw error;
+            });
+            if (!stat)
+                return;
+            if (!stat.isFile() || stat.isSymbolicLink())
+                throw new HelpCredentialError();
+            await rm(this.path);
+        }
+        catch {
+            throw new HelpCredentialError();
+        }
+    }
+}
+//# sourceMappingURL=help-credentials.js.map

package/dist/help-module.d.ts

@@ -0,0 +1,27 @@
+import { type ModuleDefinition } from "@helyx/sdk";
+import { type HelpRuntimeCollection, type HelpRuntimeResult, type HelpArea } from "@helyx/core";
+export interface HelpTransport {
+    query(input: {
+        question: string;
+        module?: string;
+        userId: string;
+        guildId?: string;
+    }): Promise<HelpRuntimeResult & {
+        choiceToken?: string;
+    }>;
+    choose(input: {
+        choiceToken: string;
+        faqId: string;
+        userId: string;
+        guildId?: string;
+    }): Promise<HelpRuntimeResult>;
+    close?(): void | Promise<void>;
+}
+/** Platform-owned FAQ lookup. Local Help needs no account, network or platform service. */
+export declare function createHelpModule(options?: {
+    deployment?: "hosted" | "self-hosted";
+    transport?: HelpTransport;
+    collection?: HelpRuntimeCollection;
+    areas?: readonly HelpArea[];
+}): ModuleDefinition;
+//# sourceMappingURL=help-module.d.ts.map

package/dist/help-module.js

@@ -0,0 +1,288 @@
+import { randomUUID } from "node:crypto";
+import { escapeMarkdown } from "discord.js";
+import { defineModule, } from "@helyx/sdk";
+import { BUNDLED_HELP_COLLECTION, BUNDLED_HELP_AREAS, BUNDLED_HELP_RUNTIME_COLLECTION, HELP_DOCS_URL, helpRuntimeFromLegacy, parseHelpRuntimeCollection, helpLexicalResult, } from "@helyx/core";
+import { INTERNAL_MODULE_MANIFEST_FIELDS } from "./internal-module-manifest.js";
+const prefix = "helyx.help.choice.";
+const everyone = {
+    everyone: true,
+    requiredPermissions: [],
+    allowedRoleIds: [],
+    deniedRoleIds: [],
+    allowedUserIds: [],
+    deniedUserIds: [],
+};
+const safeLabel = (text, max) => text
+    .replace(/[\p{Cc}\p{Cf}]/gu, " ")
+    .slice(0, max)
+    .replace(/[\uD800-\uDBFF]$/u, "");
+const fold = (text) => text.normalize("NFKC").toLowerCase().trim();
+const text = (content) => ({
+    ephemeral: true,
+    allowedRoleMentionIds: [],
+    allowedUserMentionIds: [],
+    componentsV2: { accentColor: 0x8b5cf6, text: [{ content }] },
+});
+/** Platform-owned FAQ lookup. Local Help needs no account, network or platform service. */
+export function createHelpModule(options = {}) {
+    const packaged = options.collection ?? BUNDLED_HELP_RUNTIME_COLLECTION;
+    const collection = packaged
+        ? parseHelpRuntimeCollection(packaged)
+        : helpRuntimeFromLegacy(BUNDLED_HELP_COLLECTION.faqs);
+    const areas = [...(options.areas ?? BUNDLED_HELP_AREAS)].sort((a, b) => Number(a.code) - Number(b.code));
+    const choices = new Map(), rates = new Map();
+    function admit(userId) {
+        const current = rates.get(userId);
+        if (current) {
+            if (current.count >= 5)
+                return false;
+            current.count++;
+            return true;
+        }
+        if (rates.size >= 2000)
+            return false;
+        const timer = setTimeout(() => rates.delete(userId), 60000);
+        timer.unref();
+        rates.set(userId, { count: 1, timer });
+        return true;
+    }
+    const identity = (context) => ({
+        userId: context.userId,
+        ...(context.serverId ? { guildId: context.serverId } : {}),
+    });
+    async function present(context, result, local = false, question) {
+        const freshness = local
+            ? `Local Help · bundled documentation ${collection.revision.slice(0, 12)}`
+            : result.degraded
+                ? "Stored Help answer · reduced matching"
+                : "Stored Help answer";
+        if (result.kind === "invalid") {
+            await context.reply(text("Keep your question to 600 characters."));
+            return;
+        }
+        if (result.kind === "no_match") {
+            await context.reply(text(`I couldn’t find a reliable answer. Try naming the module or rewording your question.\n\n[Browse Helyx documentation](${HELP_DOCS_URL}).`));
+            return;
+        }
+        if (result.kind === "answer") {
+            await answer(context, result.faq, freshness);
+            return;
+        }
+        if (!result.faqs.length ||
+            result.faqs.length > 3 ||
+            (!local && !result.choiceToken)) {
+            await context.reply(text(`Help is temporarily unavailable. [Browse the documentation](${HELP_DOCS_URL}).`));
+            return;
+        }
+        if (choices.size >= 1000) {
+            await context.reply(text("Help is busy. Try your question again in a moment."));
+            return;
+        }
+        const nonce = randomUUID(), timer = setTimeout(() => choices.delete(nonce), 120000);
+        timer.unref();
+        choices.set(nonce, {
+            expiresAt: Date.now() + 120000,
+            userId: context.userId,
+            serverId: context.serverId ?? null,
+            ids: result.faqs.map((faq) => faq.id),
+            revision: result.revision,
+            token: local ? null : result.choiceToken,
+            timer,
+        });
+        const introduction = result.faqs.length > 1
+            ? "I’ve found a few questions that match or are similar to yours:"
+            : "I’ve found a question that may match yours:";
+        const userQuestionText = question
+            ? `\n\n${escapeMarkdown(question.trim())}`
+            : "";
+        await context.reply({
+            ...text(`${introduction}${userQuestionText}`),
+            buttons: result.faqs.map((faq) => ({
+                type: "button",
+                customId: `${prefix}${nonce}.${faq.id}`,
+                label: safeLabel(faq.source.kind === "custom"
+                    ? faq.question
+                    : `${faq.areaName} · ${faq.question}`, 80),
+                style: "secondary",
+            })),
+        });
+    }
+    async function answer(context, faq, freshness) {
+        const heading = `## ${safeLabel(faq.question, 600)}`;
+        const source = faq.source.kind === "website" ? `[Read this FAQ](${faq.source.url})` : "";
+        const notice = freshness.startsWith("Local Help")
+            ? "\n\n-# Offline documentation snapshot"
+            : freshness.includes("reduced matching")
+                ? "\n\n-# Reduced matching"
+                : "";
+        const footer = `\n\n-# ID:${faq.id}`;
+        const content = `${heading}\n\n${faq.answerMarkdown}${faq.context.length ? "\n\n" + faq.context.join("\n\n") : ""}${source ? "\n\n" + source : ""}${notice}${footer}`;
+        if (faq.source.kind === "website" && content.length > 7000) {
+            await context.reply(text(`${heading}\n\nThis stored answer and its context are too long for Discord. ${source}${notice}${footer}`));
+            return;
+        }
+        // Send the entire stored answer; do not silently cut a warning or negation.
+        const chunks = [];
+        let rest = content;
+        while (rest.length) {
+            let end = Math.min(3500, rest.length);
+            if (end < rest.length && /[\uD800-\uDBFF]/u.test(rest[end - 1]))
+                end--;
+            chunks.push(rest.slice(0, end));
+            rest = rest.slice(end);
+        }
+        for (const [index, chunk] of chunks.entries())
+            await context.reply(text(chunks.length > 1
+                ? `${chunk}\n\n(${index + 1}/${chunks.length})`
+                : chunk));
+    }
+    return defineModule({
+        manifest: {
+            ...INTERNAL_MODULE_MANIFEST_FIELDS,
+            releaseStatus: "live",
+            id: "helyx.help",
+            name: "Helyx Help",
+            version: "0.1.0",
+            description: "Always-available help from approved Helyx FAQs.",
+            entry: "./dist/help-module.js",
+            framework: "^0.1.0",
+            dependencies: [],
+            permissions: [],
+            contributions: { commands: ["help"], events: [] },
+        },
+        defaultPermissions: { module: everyone, commands: { help: everyone } },
+        interactions: {
+            commands: [
+                {
+                    name: "help",
+                    permissionId: "help",
+                    description: "Find an answer in the Helyx FAQs",
+                    registrationPolicy: "platform-global",
+                    acknowledgement: "deferred-ephemeral",
+                    authorization: "public",
+                    contexts: ["guild", "bot_dm"],
+                    integrationTypes: ["guild_install"],
+                    options: [
+                        {
+                            type: "string",
+                            name: "question",
+                            description: "Your question about Helyx",
+                            maxLength: 600,
+                        },
+                        {
+                            type: "string",
+                            name: "module",
+                            description: "Optional module or documentation area",
+                            autocomplete: true,
+                            maxLength: 200,
+                        },
+                    ],
+                    async autocomplete(context) {
+                        const value = fold(context.focusedValue);
+                        await context.respond(context.focusedOptionName === "module"
+                            ? areas
+                                .filter((area) => fold(`${area.code} ${area.name} ${area.area}`).includes(value))
+                                .slice(0, 25)
+                                .map((area) => ({
+                                name: safeLabel(`${area.code} · ${area.name}`, 100),
+                                value: area.code,
+                            }))
+                            : []);
+                    },
+                    async execute(context) {
+                        const question = context.getStringOption("question"), moduleInput = context.getStringOption("module");
+                        if (!question?.trim()) {
+                            await context.reply(text(`Ask a question about Helyx, with an optional module or area.\n\nExample: \`/help question: The command is not visible module: Feedback\`\n\nHelp returns stored FAQ answers. [Browse the documentation](${HELP_DOCS_URL}).`));
+                            return;
+                        }
+                        if (question.length > 600 ||
+                            !question.isWellFormed() ||
+                            /[\p{Cc}\p{Cf}]/u.test(question.replace(/[\r\n\t]/gu, ""))) {
+                            await context.reply(text("Use a question of at most 600 characters with ordinary readable text."));
+                            return;
+                        }
+                        const area = moduleInput
+                            ? areas.find((area) => [area.code, area.area, area.name, `helyx.${area.area}`].some((value) => fold(value) === fold(moduleInput)))
+                            : undefined;
+                        if (moduleInput && !area) {
+                            await context.reply(text("Choose a module or area from the suggestions, or enter its three-digit number."));
+                            return;
+                        }
+                        if (!admit(context.userId)) {
+                            await context.reply(text("You’ve reached Help’s short limit. Try again in a minute."));
+                            return;
+                        }
+                        if (options.transport)
+                            try {
+                                await present(context, await options.transport.query({
+                                    question,
+                                    ...(area ? { module: area.code } : {}),
+                                    ...identity(context),
+                                }), false, question);
+                                return;
+                            }
+                            catch {
+                                if (options.deployment === "hosted") {
+                                    await context.reply(text(`Online Help is temporarily unavailable. [Browse the documentation](${HELP_DOCS_URL}) or try again shortly.`));
+                                    return;
+                                }
+                            }
+                        await present(context, helpLexicalResult(collection.faqs, question, collection.revision, area?.code), true, question);
+                    },
+                },
+            ],
+            buttons: [
+                {
+                    customIdPrefix: prefix,
+                    acknowledgement: "deferred-update",
+                    authorization: "public",
+                    async execute(context) {
+                        const parts = /^helyx\.help\.choice\.([a-f0-9-]{36})\.([1-9]\d{5})$/u.exec(context.customId ?? ""), state = parts ? choices.get(parts[1]) : undefined;
+                        if (!parts ||
+                            !state ||
+                            state.expiresAt <= Date.now() ||
+                            state.userId !== context.userId ||
+                            state.serverId !== (context.serverId ?? null) ||
+                            !state.ids.includes(parts[2])) {
+                            await context.reply(text("This selection is unavailable. Ask `/help` again."));
+                            return;
+                        }
+                        choices.delete(parts[1]);
+                        clearTimeout(state.timer);
+                        if (state.token && options.transport)
+                            try {
+                                await present(context, await options.transport.choose({
+                                    choiceToken: state.token,
+                                    faqId: parts[2],
+                                    ...identity(context),
+                                }));
+                            }
+                            catch {
+                                await context.reply(text("This answer changed or the selection expired. Ask `/help` again."));
+                            }
+                        else {
+                            const faq = state.revision === collection.revision
+                                ? collection.faqs.find((faq) => faq.id === parts[2])
+                                : undefined;
+                            if (!faq)
+                                await context.reply(text("This selection expired. Ask `/help` again."));
+                            else
+                                await answer(context, faq, `Local Help · bundled documentation ${collection.revision.slice(0, 12)}`);
+                        }
+                    },
+                },
+            ],
+        },
+        start: () => Promise.resolve(),
+        stop: async () => {
+            for (const choice of choices.values())
+                clearTimeout(choice.timer);
+            choices.clear();
+            for (const rate of rates.values())
+                clearTimeout(rate.timer);
+            rates.clear();
+            await options.transport?.close?.();
+        },
+    });
+}
+//# sourceMappingURL=help-module.js.map

package/dist/help-runtime.d.ts

@@ -0,0 +1,3 @@
+import type { BotEnvironment } from "@helyx/config";
+export declare function createRuntimeHelpModule(environment: Pick<BotEnvironment, "HELYX_RUNTIME_PROFILE" | "HELYX_DATA_ENCRYPTION_KEY" | "HELYX_CLOUD_API_URL" | "HELYX_BOT_CONTROL_SECRET">): import("@helyx/sdk").ModuleDefinition;
+//# sourceMappingURL=help-runtime.d.ts.map

package/dist/help-runtime.js

@@ -0,0 +1,42 @@
+import { readFileSync } from "node:fs";
+import { createHelpModule } from "./help-module.js";
+import { HelpCredentialStore } from "./help-credentials.js";
+import { FileHelpTransport, HttpHelpTransport, HelpTransportError, } from "./help-transport.js";
+export function createRuntimeHelpModule(environment) {
+    let botVersion = "unknown";
+    try {
+        const value = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+        if (typeof value.version === "string" &&
+            /^[A-Za-z0-9.+_-]{1,50}$/u.test(value.version))
+            botVersion = value.version;
+    }
+    catch {
+        /* Packaging validation checks the real package metadata separately. */
+    }
+    let transport;
+    if (environment.HELYX_RUNTIME_PROFILE === "hosted") {
+        try {
+            if (!environment.HELYX_BOT_CONTROL_SECRET)
+                throw new HelpTransportError();
+            transport = new HttpHelpTransport({
+                kind: "hosted",
+                token: environment.HELYX_BOT_CONTROL_SECRET,
+                baseUrl: environment.HELYX_CLOUD_API_URL,
+                botVersion,
+            });
+        }
+        catch {
+            transport = {
+                query: () => Promise.reject(new HelpTransportError()),
+                choose: () => Promise.reject(new HelpTransportError()),
+            };
+        }
+    }
+    else if (environment.HELYX_DATA_ENCRYPTION_KEY)
+        transport = new FileHelpTransport(new HelpCredentialStore(process.cwd(), environment.HELYX_DATA_ENCRYPTION_KEY), botVersion);
+    return createHelpModule({
+        deployment: environment.HELYX_RUNTIME_PROFILE,
+        ...(transport ? { transport } : {}),
+    });
+}
+//# sourceMappingURL=help-runtime.js.map

package/dist/help-transport.d.ts

@@ -0,0 +1,53 @@
+import { type HelpRuntimeResult } from "@helyx/core";
+import { type HelpCredentialStore } from "./help-credentials.js";
+import type { HelpTransport } from "./help-module.js";
+export declare class HelpTransportError extends Error {
+    readonly code: "unavailable" | "expired_choice";
+    constructor(code?: "unavailable" | "expired_choice");
+}
+export declare class HttpHelpTransport implements HelpTransport {
+    private readonly options;
+    private blocked;
+    private blockedUntil;
+    private failures;
+    private readonly origin;
+    private readonly controller;
+    constructor(options: {
+        token: string;
+        kind: "hosted" | "self-host";
+        baseUrl?: string;
+        botVersion: string;
+        fetch?: typeof fetch;
+    });
+    query(input: Parameters<HelpTransport["query"]>[0]): Promise<HelpRuntimeResult & {
+        choiceToken?: string;
+    }>;
+    choose(input: Parameters<HelpTransport["choose"]>[0]): Promise<HelpRuntimeResult & {
+        choiceToken?: string;
+    }>;
+    close(): void;
+    private request;
+}
+/** Read per request so local disconnect/replacement takes effect without a restart. */
+export declare class FileHelpTransport implements HelpTransport {
+    private readonly store;
+    private readonly botVersion;
+    private readonly fetcher?;
+    private current;
+    constructor(store: HelpCredentialStore, botVersion: string, fetcher?: typeof fetch | undefined);
+    private transport;
+    query(input: Parameters<HelpTransport["query"]>[0]): Promise<HelpRuntimeResult & {
+        choiceToken?: string;
+    }>;
+    choose(input: Parameters<HelpTransport["choose"]>[0]): Promise<HelpRuntimeResult & {
+        choiceToken?: string;
+    }>;
+    close(): void;
+}
+export declare function exchangeHelpEnrolment(code: string, fetcher?: typeof fetch): Promise<{
+    installationId: string;
+    token: string;
+    expiresAt: string;
+}>;
+export declare function revokeHelpCredential(token: string, fetcher?: typeof fetch): Promise<void>;
+//# sourceMappingURL=help-transport.d.ts.map