@helyx/bot 1.5.4 → 1.7.0

package/dist/help-transport.js

@@ -0,0 +1,267 @@
+import { z } from "zod";
+import { createHelpRuntimeCollection, HELP_DOCS_URL, } from "@helyx/core";
+import { HELP_API_ORIGIN, parseHelpCredential, } from "./help-credentials.js";
+export class HelpTransportError extends Error {
+    code;
+    constructor(code = "unavailable") {
+        super(`Help ${code.replaceAll("_", " ")}`);
+        this.code = code;
+    }
+}
+const responseSchema = z
+    .object({
+    contractVersion: z.literal(1),
+    requestId: z.string().uuid(),
+    revision: z.string().regex(/^[a-f0-9]{64}$/u),
+    mode: z.enum(["lexical", "hybrid"]),
+    kind: z.enum(["answer", "choices", "no_match", "invalid"]),
+    degraded: z
+        .enum(["provider_disabled", "provider_unavailable", "budget_exhausted"])
+        .optional(),
+    faq: z.unknown().optional(),
+    faqs: z.array(z.unknown()).max(3).optional(),
+    choiceToken: z.string().max(2048).optional(),
+    reason: z.string().optional(),
+    docsUrl: z.string().optional(),
+})
+    .strict();
+function parseResponse(value) {
+    const parsed = responseSchema.parse(value), base = {
+        mode: parsed.mode,
+        revision: parsed.revision,
+        ...(parsed.degraded ? { degraded: parsed.degraded } : {}),
+    };
+    if (parsed.kind === "answer") {
+        const faqs = createHelpRuntimeCollection([
+            parsed.faq,
+        ]).faqs;
+        return { ...base, kind: "answer", faq: faqs[0] };
+    }
+    if (parsed.kind === "choices") {
+        if (!parsed.faqs?.length || !parsed.choiceToken)
+            throw new HelpTransportError();
+        const input = parsed.faqs;
+        const valid = new Map(createHelpRuntimeCollection(input).faqs.map((faq) => [faq.id, faq]));
+        const faqs = input.map((faq) => valid.get(faq.id));
+        return { ...base, kind: "choices", faqs, choiceToken: parsed.choiceToken };
+    }
+    if (parsed.kind === "no_match" &&
+        ["empty", "weak_match"].includes(parsed.reason ?? "") &&
+        parsed.docsUrl === HELP_DOCS_URL)
+        return {
+            ...base,
+            kind: "no_match",
+            reason: parsed.reason,
+            docsUrl: HELP_DOCS_URL,
+        };
+    if (parsed.kind === "invalid" && parsed.reason === "too_long")
+        return { ...base, kind: "invalid", reason: "too_long" };
+    throw new HelpTransportError();
+}
+export class HttpHelpTransport {
+    options;
+    blocked = false;
+    blockedUntil = 0;
+    failures = 0;
+    origin;
+    controller = new AbortController();
+    constructor(options) {
+        this.options = options;
+        const url = new URL(options.baseUrl ?? HELP_API_ORIGIN);
+        if (url.username ||
+            url.password ||
+            url.pathname !== "/" ||
+            url.search ||
+            url.hash ||
+            (url.protocol !== "https:" &&
+                !(url.protocol === "http:" &&
+                    ["127.0.0.1", "localhost", "[::1]"].includes(url.hostname))) ||
+            (options.kind === "self-host" && url.origin !== HELP_API_ORIGIN))
+            throw new HelpTransportError();
+        this.origin = url.origin;
+    }
+    query(input) {
+        return this.request("query", {
+            question: input.question,
+            ...(input.module ? { module: input.module } : {}),
+        }, input);
+    }
+    choose(input) {
+        return this.request("choose", { choiceToken: input.choiceToken, faqId: input.faqId }, input);
+    }
+    close() {
+        this.controller.abort();
+    }
+    async request(path, body, identity) {
+        if (this.blocked ||
+            Date.now() < this.blockedUntil ||
+            this.controller.signal.aborted)
+            throw new HelpTransportError();
+        try {
+            const response = await (this.options.fetch ?? fetch)(`${this.origin}/v1/help/${path}`, {
+                method: "POST",
+                redirect: "error",
+                signal: AbortSignal.any([
+                    this.controller.signal,
+                    AbortSignal.timeout(6000),
+                ]),
+                headers: {
+                    Authorization: `Bearer ${this.options.token}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    contractVersion: 1,
+                    locale: "en-GB",
+                    botVersion: this.options.botVersion,
+                    ...body,
+                    ...(this.options.kind === "hosted"
+                        ? {
+                            subject: {
+                                userId: identity.userId,
+                                ...(identity.guildId ? { guildId: identity.guildId } : {}),
+                            },
+                        }
+                        : {}),
+                }),
+            });
+            if (response.status === 401 || response.status === 403)
+                this.blocked = true;
+            if (response.status === 429)
+                this.blockedUntil =
+                    Date.now() +
+                        Math.min(3600, Math.max(60, Number(response.headers.get("Retry-After")) || 60)) *
+                            1000;
+            if (!response.ok) {
+                await response.body?.cancel();
+                if (response.status === 410)
+                    throw new HelpTransportError("expired_choice");
+                throw new HelpTransportError();
+            }
+            const value = parseResponse(await boundedJson(response));
+            this.failures = 0;
+            return value;
+        }
+        catch (error) {
+            if (error instanceof HelpTransportError &&
+                error.code === "expired_choice")
+                throw error;
+            if (++this.failures >= 3)
+                this.blockedUntil = Math.max(this.blockedUntil, Date.now() + 30000);
+            throw new HelpTransportError();
+        }
+    }
+}
+/** Read per request so local disconnect/replacement takes effect without a restart. */
+export class FileHelpTransport {
+    store;
+    botVersion;
+    fetcher;
+    current = null;
+    constructor(store, botVersion, fetcher) {
+        this.store = store;
+        this.botVersion = botVersion;
+        this.fetcher = fetcher;
+    }
+    async transport() {
+        const credential = await this.store.read();
+        if (!credential || Date.parse(credential.expiresAt) <= Date.now()) {
+            this.current?.transport.close();
+            this.current = null;
+            throw new HelpTransportError();
+        }
+        if (this.current?.token !== credential.token) {
+            this.current?.transport.close();
+            this.current = {
+                token: credential.token,
+                transport: new HttpHelpTransport({
+                    token: credential.token,
+                    kind: "self-host",
+                    botVersion: this.botVersion,
+                    ...(this.fetcher ? { fetch: this.fetcher } : {}),
+                }),
+            };
+        }
+        return this.current.transport;
+    }
+    async query(input) {
+        return (await this.transport()).query(input);
+    }
+    async choose(input) {
+        return (await this.transport()).choose(input);
+    }
+    close() {
+        this.current?.transport.close();
+        this.current = null;
+    }
+}
+export async function exchangeHelpEnrolment(code, fetcher = fetch) {
+    if (!/^hhe_[A-Za-z0-9_-]{43}$/u.test(code))
+        throw new HelpTransportError();
+    try {
+        const response = await fetcher(`${HELP_API_ORIGIN}/v1/help/enrolments/exchange`, {
+            method: "POST",
+            redirect: "error",
+            signal: AbortSignal.timeout(10000),
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ code }),
+        });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new HelpTransportError();
+        }
+        return parseHelpCredential(await boundedJson(response));
+    }
+    catch {
+        throw new HelpTransportError();
+    }
+}
+export async function revokeHelpCredential(token, fetcher = fetch) {
+    if (!/^hhp_[A-Za-z0-9_-]{43}$/u.test(token))
+        throw new HelpTransportError();
+    try {
+        const response = await fetcher(`${HELP_API_ORIGIN}/v1/help/disconnect`, {
+            method: "POST",
+            redirect: "error",
+            signal: AbortSignal.timeout(10000),
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ contractVersion: 1 }),
+        });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new HelpTransportError();
+        }
+        z.object({ revoked: z.literal(true) })
+            .strict()
+            .parse(await boundedJson(response));
+    }
+    catch {
+        throw new HelpTransportError();
+    }
+}
+async function boundedJson(response) {
+    const max = 512 * 1024;
+    if (!response.body ||
+        Number(response.headers.get("Content-Length") ?? 0) > max)
+        throw new HelpTransportError();
+    const reader = response.body.getReader(), chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            const value = chunk.value;
+            if (!(value instanceof Uint8Array) || (size += value.byteLength) > max)
+                throw new HelpTransportError();
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+    return JSON.parse(Buffer.concat(chunks, size).toString("utf8"));
+}
+//# sourceMappingURL=help-transport.js.map

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { type ModuleDefinition } from "@helyx/sdk";
 import { GatewayIntentBits } from "discord.js";
 import { type ShardHealthSnapshot } from "./shard-contracts.js";
+export { HelpCredentialStore } from "./help-credentials.js";
+export { exchangeHelpEnrolment, revokeHelpCredential, } from "./help-transport.js";
 export { loadConfiguredModulePackages } from "./modules.js";
 export { assertConfiguredModuleDatabaseCompatibility } from "./modules.js";
 export { resolveModulePackageSpecifiers } from "./module-configuration.js";

package/dist/index.js

@@ -35,6 +35,10 @@ import { shardHealthSnapshotSchema, } from "./shard-contracts.js";
 import { createSupportModule } from "./support-module.js";
 import { createOAuthModule } from "./oauth-module.js";
 import { createPrivacyModule } from "./privacy-module.js";
+import { createProcessInfoModule } from "./process-info-module.js";
+import { createRuntimeHelpModule } from "./help-runtime.js";
+export { HelpCredentialStore } from "./help-credentials.js";
+export { exchangeHelpEnrolment, revokeHelpCredential, } from "./help-transport.js";
 import { installModerationPlatformServices } from "./moderation-platform-services.js";
 import { EckoEvidenceReceiver } from "./ecko-evidence-receiver.js";
 import { EckoTransportAuthenticator } from "./ecko-transport-auth.js";
@@ -361,6 +365,8 @@ async function startUnshardedBot(processEnvironment) {
             : undefined;
         const supportModule = createSupportModule(cloudConnector);
         const privacyModule = createPrivacyModule();
+        const processInfoModule = createProcessInfoModule("unsharded bot process");
+        const helpModule = createRuntimeHelpModule(environment);
         const premiumEnvironment = requirePremiumProviderEnvironment(featureModules, environment.STRIPE_ENVIRONMENT);
         const premiumActivationModule = !premiumEnvironment || !database
             ? undefined
@@ -380,6 +386,8 @@ async function startUnshardedBot(processEnvironment) {
             permissionsModule,
             supportModule,
             privacyModule,
+            processInfoModule,
+            helpModule,
             ...(premiumActivationModule ? [premiumActivationModule] : []),
             ...(oauthModule ? [oauthModule] : []),
             ...(cloudManagementModule ? [cloudManagementModule] : []),
@@ -458,6 +466,8 @@ async function startUnshardedBot(processEnvironment) {
                     permissionsModule,
                     supportModule,
                     privacyModule,
+                    processInfoModule,
+                    helpModule,
                     ...(premiumActivationModule ? [premiumActivationModule] : []),
                     ...(oauthModule ? [oauthModule] : []),
                     ...(cloudManagementModule ? [cloudManagementModule] : []),

package/dist/interactions.js

@@ -141,15 +141,19 @@ export function installInteractions(client, modules, registration, logger, servi
                     const subcommand = resolveCommandSubcommand(registered?.contribution, subcommandName, groupName);
                     const owner = resolveCommandOwner(registered, subcommandName, groupName);
                     const ownerModuleId = owner?.moduleId ?? registered?.moduleId;
+                    const autocompleteOwner = subcommand ??
+                        (!hasNestedCommands(registered?.contribution)
+                            ? registered?.contribution
+                            : undefined);
                     if (!registered ||
-                        !subcommand?.autocomplete ||
+                        !autocompleteOwner?.autocomplete ||
                         !ownerModuleId ||
                         !(await authorizeAutocomplete(interaction, ownerModuleId, resolveDirectCommandPath(registered.contribution, subcommand, groupName).permissionId, services, registration.selfAuthorizingGuildModuleIds?.has(ownerModuleId) ??
-                            false, subcommand.authorization === "resource-scoped", isInstallationIndependentModule(modulesById, ownerModuleId), subcommand.authorization, requiredCommandModule(modulesById, ownerModuleId)))) {
+                            false, autocompleteOwner.authorization === "resource-scoped", isInstallationIndependentModule(modulesById, ownerModuleId), autocompleteOwner.authorization, requiredCommandModule(modulesById, ownerModuleId)))) {
                         await response.respond([]);
                         return;
                     }
-                    await subcommand.autocomplete(createAutocompleteContext(interaction, services, response.respond));
+                    await autocompleteOwner.autocomplete(createAutocompleteContext(interaction, services, response.respond));
                 }
                 catch (error) {
                     logger.error({
@@ -217,15 +221,15 @@ export function installInteractions(client, modules, registration, logger, servi
                     const acknowledgement = subcommand?.acknowledgement ?? command.acknowledgement;
                     const authorization = subcommand?.authorization ?? command.authorization;
                     const rateLimit = subcommand?.rateLimit ?? command.rateLimit;
+                    if (acknowledgement === "deferred-ephemeral") {
+                        await interaction.deferReply({ flags: MessageFlags.Ephemeral });
+                    }
                     if (installationIndependentCommand &&
                         authorization === "public" &&
                         !rateLimit) {
                         await execute(createCommandContext(interaction, services));
                         return;
                     }
-                    if (acknowledgement === "deferred-ephemeral") {
-                        await interaction.deferReply({ flags: MessageFlags.Ephemeral });
-                    }
                     if (await authorizeCommand(interaction, ownerModuleId, permissionId, rateLimit, services, registration.selfAuthorizingGuildModuleIds?.has(ownerModuleId) ??
                         false, subcommand?.authorization === "resource-scoped", owner?.moduleName, installationIndependentCommand, authorization, requiredCommandModule(modulesById, ownerModuleId))) {
                         const context = createCommandContext(interaction, services);

package/dist/process-info-module.d.ts

@@ -0,0 +1,3 @@
+/** Local process metrics remain available without database or installation checks. */
+export declare function createProcessInfoModule(processLabel: string): import("@helyx/sdk").ModuleDefinition;
+//# sourceMappingURL=process-info-module.d.ts.map

package/dist/process-info-module.js

@@ -0,0 +1,97 @@
+import { defineModule } from "@helyx/sdk";
+import { INTERNAL_MODULE_MANIFEST_FIELDS } from "./internal-module-manifest.js";
+const everyonePolicy = {
+    everyone: true,
+    requiredPermissions: [],
+    allowedRoleIds: [],
+    deniedRoleIds: [],
+    allowedUserIds: [],
+    deniedUserIds: [],
+};
+/** Local process metrics remain available without database or installation checks. */
+export function createProcessInfoModule(processLabel) {
+    return defineModule({
+        manifest: {
+            ...INTERNAL_MODULE_MANIFEST_FIELDS,
+            releaseStatus: "live",
+            id: "helyx.process-info",
+            name: "Helyx Process Information",
+            version: "0.1.0",
+            description: "Reports safe resource and uptime information for the running bot.",
+            entry: "./dist/process-info-module.js",
+            framework: "^0.1.0",
+            dependencies: [],
+            permissions: [],
+            contributions: { commands: ["proc"], events: [] },
+        },
+        defaultPermissions: {
+            module: everyonePolicy,
+            commands: { proc: everyonePolicy },
+        },
+        interactions: {
+            commands: [
+                {
+                    name: "proc",
+                    permissionId: "proc",
+                    description: "Show safe process resource and uptime information",
+                    acknowledgement: "immediate-response",
+                    registrationPolicy: "platform-global",
+                    contexts: ["guild", "bot_dm"],
+                    integrationTypes: ["guild_install"],
+                    authorization: "public",
+                    async execute(context) {
+                        const memory = process.memoryUsage();
+                        const cpu = process.cpuUsage();
+                        await context.reply({
+                            ephemeral: true,
+                            componentsV2: {
+                                accentColor: 0x2563eb,
+                                text: [
+                                    {
+                                        content: [
+                                            "## Process information",
+                                            `Runtime: ${processLabel}`,
+                                            `Uptime: ${formatDuration(process.uptime())}`,
+                                            `RSS memory: ${formatBytes(memory.rss)}`,
+                                            `Heap: ${formatBytes(memory.heapUsed)} used / ${formatBytes(memory.heapTotal)} allocated`,
+                                            `External memory: ${formatBytes(memory.external)}`,
+                                            `CPU time: ${formatCpu(cpu.user)} user / ${formatCpu(cpu.system)} system`,
+                                            `Node: ${safeInlineCode(process.version)}`,
+                                            `Platform: ${safeInlineCode(`${process.platform}/${process.arch}`)}`,
+                                            `PID: ${process.pid}`,
+                                        ].join("\n"),
+                                    },
+                                ],
+                            },
+                        });
+                    },
+                },
+            ],
+        },
+        start: () => Promise.resolve(),
+        stop: () => Promise.resolve(),
+    });
+}
+function safeInlineCode(value) {
+    return `\`${value.replaceAll("`", "'").slice(0, 120)}\``;
+}
+function formatBytes(value) {
+    return `${(value / (1024 * 1024)).toFixed(1)} MiB`;
+}
+function formatCpu(microseconds) {
+    return `${(microseconds / 1_000_000).toFixed(2)}s`;
+}
+function formatDuration(seconds) {
+    const total = Math.max(0, Math.floor(seconds));
+    const days = Math.floor(total / 86_400);
+    const hours = Math.floor((total % 86_400) / 3_600);
+    const minutes = Math.floor((total % 3_600) / 60);
+    const remainder = total % 60;
+    return [
+        ...(days > 0 ? [`${days}d`] : []),
+        ...(days > 0 || hours > 0 ? [`${hours}h`] : []),
+        `${minutes}m`,
+        `${remainder}s`,
+    ].join(" ");
+}
+//# sourceMappingURL=process-info-module.js.map

package/dist/server-overview-control.d.ts

@@ -0,0 +1,35 @@
+import { type OverviewReadInput, type OverviewResponse, type OverviewRevokeInput } from "@helyx/control-protocol";
+import { type GuildAccessPolicy, type ManagedResourceContext, type ModuleDefinition, type PermissionActor, type PermissionPolicyService, type ServiceAccess } from "@helyx/sdk";
+import type { OverviewDiscordDirectory } from "./server-overview-discord.js";
+export declare function createServerOverviewControl(deps: {
+    modules: ReadonlyMap<string, ModuleDefinition>;
+    services: ServiceAccess;
+    permissions: PermissionPolicyService;
+    resolveActor(guildId: string, actorUserId: string): Promise<PermissionActor>;
+    readGuildPolicy(guildId: string): Promise<GuildAccessPolicy>;
+    listModules(guildId: string): Promise<readonly {
+        moduleId: string;
+        enabled: boolean;
+    }[]>;
+    requireAccessible(guildId: string, moduleId: string): Promise<void>;
+    directory?: OverviewDiscordDirectory | undefined;
+    auditInviteRevoke?(input: {
+        guildId: string;
+        actorUserId: string;
+        code: string;
+        outcome: "requested" | "revoked";
+        correlationId: string;
+    }): Promise<void>;
+    context(guildId: string, actor: PermissionActor): ManagedResourceContext;
+}): {
+    invalidate(guildId: string): void;
+    readServerOverview(input: OverviewReadInput & {
+        actorUserId: string;
+    }): Promise<OverviewResponse>;
+    revokeServerOverviewInvite(input: OverviewRevokeInput & {
+        actorUserId: string;
+    }): Promise<{
+        revoked: true;
+    }>;
+};
+//# sourceMappingURL=server-overview-control.d.ts.map