@helyx/bot 0.4.36 → 0.4.38

package/dist/guild-command-control-routes.js

@@ -0,0 +1,191 @@
+import { z } from "zod";
+const snowflake = z.string().regex(/^\d{17,20}$/u);
+const reconciliationBody = z
+    .object({
+    actorUserId: snowflake,
+    correlationId: z.string().min(1).max(200),
+    expectedRevision: z.string().regex(/^\d+$/u),
+    source: z.enum(["customer_rebuild", "owner_repair"]),
+    budgetClass: z.enum(["customer", "owner"]),
+    delayMs: z.number().int().min(0).max(86_400_000),
+    summary: z.string().min(1).max(500),
+})
+    .strict();
+const profileBody = z
+    .object({
+    actorUserId: snowflake,
+    correlationId: z.string().min(1).max(200),
+    expectedRevision: z.string().regex(/^\d+$/u),
+    profile: z.enum(["enabled_only", "all_released", "all_loaded"]),
+    reasonSummary: z.string().min(1).max(500),
+})
+    .strict();
+const migrationHoldBody = z
+    .object({
+    actorUserId: snowflake,
+    correlationId: z.string().min(1).max(200),
+    expectedRevision: z.string().regex(/^\d+$/u),
+    enabled: z.boolean(),
+})
+    .strict();
+const refreshBody = z
+    .object({
+    actorUserId: snowflake,
+    correlationId: z.string().min(1).max(200),
+})
+    .strict();
+const moduleAvailabilityBody = z
+    .object({
+    moduleId: z.string().regex(/^helyx\.[a-z0-9][a-z0-9-]*$/u),
+    correlationId: z.string().min(1).max(200),
+})
+    .strict();
+export function registerGuildCommandControlRoutes(server, commands, setup) {
+    server.get("/v1/commands/health", async (_request, reply) => {
+        reply.header("Cache-Control", "no-store");
+        if (!commands)
+            return reply.code(503).send({ message: "Command state is unavailable" });
+        return commands.getHealth();
+    });
+    server.post("/v1/commands/reconcile-module", async (request, reply) => {
+        reply.header("Cache-Control", "no-store");
+        if (!commands)
+            return reply.code(503).send({ message: "Command state is unavailable" });
+        return commands.reconcileModuleAvailability(moduleAvailabilityBody.parse(request.body));
+    });
+    server.get("/v1/guilds/:guildId/commands/status", async (request, reply) => {
+        reply.header("Cache-Control", "no-store");
+        if (!commands)
+            return reply.code(503).send({ message: "Command state is unavailable" });
+        const { guildId } = z.object({ guildId: snowflake }).parse(request.params);
+        return commands.getStatus(guildId);
+    });
+    server.get("/v1/guilds/:guildId/commands/history", async (request, reply) => {
+        reply.header("Cache-Control", "no-store");
+        if (!commands)
+            return reply.code(503).send({ message: "Command state is unavailable" });
+        const { guildId } = z.object({ guildId: snowflake }).parse(request.params);
+        const query = z
+            .object({
+            before: z
+                .string()
+                .regex(/^[1-9]\d*$/u)
+                .optional(),
+            since: z.iso.datetime().optional(),
+            limit: z.coerce.number().int().min(1).max(10).default(10),
+        })
+            .strict()
+            .parse(request.query);
+        return commands.listHistory({
+            guildId,
+            ...(query.before ? { beforeEventId: BigInt(query.before) } : {}),
+            ...(query.since ? { since: new Date(query.since) } : {}),
+            limit: query.limit,
+        });
+    });
+    server.post("/v1/guilds/:guildId/commands/first-time-setup/preview", async (request, reply) => {
+        reply.header("Cache-Control", "no-store");
+        if (!commands)
+            return reply
+                .code(503)
+                .send({ message: "Command state is unavailable" });
+        z.object({ guildId: snowflake }).parse(request.params);
+        const body = z
+            .object({
+            moduleIds: z
+                .array(z.string().regex(/^helyx\.[a-z0-9][a-z0-9-]*$/u))
+                .min(1)
+                .max(100),
+        })
+            .strict()
+            .parse(request.body);
+        return commands.previewFirstTimeSetup(body.moduleIds);
+    });
+    server.post("/v1/guilds/:guildId/commands/reconcile", async (request, reply) => {
+        reply.header("Cache-Control", "no-store");
+        if (!commands)
+            return reply
+                .code(503)
+                .send({ message: "Command state is unavailable" });
+        const { guildId } = z
+            .object({ guildId: snowflake })
+            .parse(request.params);
+        const body = reconciliationBody.parse(request.body);
+        return commands.requestReconciliation({
+            guildId,
+            ...body,
+            expectedRevision: BigInt(body.expectedRevision),
+        });
+    });
+    server.post("/v1/guilds/:guildId/commands/refresh", async (request, reply) => {
+        reply.header("Cache-Control", "no-store");
+        if (!commands)
+            return reply
+                .code(503)
+                .send({ message: "Command state is unavailable" });
+        const { guildId } = z
+            .object({ guildId: snowflake })
+            .parse(request.params);
+        return commands.refreshStatus({
+            guildId,
+            ...refreshBody.parse(request.body),
+        });
+    });
+    server.patch("/v1/guilds/:guildId/commands/profile", async (request, reply) => {
+        reply.header("Cache-Control", "no-store");
+        if (!commands)
+            return reply
+                .code(503)
+                .send({ message: "Command state is unavailable" });
+        const { guildId } = z
+            .object({ guildId: snowflake })
+            .parse(request.params);
+        const body = profileBody.parse(request.body);
+        return commands.changeProfile({
+            guildId,
+            ...body,
+            expectedRevision: BigInt(body.expectedRevision),
+        });
+    });
+    server.patch("/v1/guilds/:guildId/commands/migration-hold", async (request, reply) => {
+        reply.header("Cache-Control", "no-store");
+        if (!commands)
+            return reply
+                .code(503)
+                .send({ message: "Command state is unavailable" });
+        const { guildId } = z
+            .object({ guildId: snowflake })
+            .parse(request.params);
+        const body = migrationHoldBody.parse(request.body);
+        return commands.setMigrationHold({
+            guildId,
+            ...body,
+            expectedRevision: BigInt(body.expectedRevision),
+        });
+    });
+    server.post("/v1/guilds/:guildId/commands/first-time-setup", async (request, reply) => {
+        reply.header("Cache-Control", "no-store");
+        const { guildId } = z
+            .object({ guildId: snowflake })
+            .parse(request.params);
+        const body = z
+            .object({
+            moduleIds: z
+                .array(z.string().regex(/^helyx\.[a-z0-9][a-z0-9-]*$/u))
+                .min(1)
+                .max(100),
+            expectedRevision: z.string().regex(/^\d+$/u),
+            idempotencyKey: z.string().min(1).max(160),
+            actorUserId: snowflake,
+            correlationId: z.string().min(1).max(200),
+        })
+            .strict()
+            .parse(request.body);
+        return setup.completeFirstTimeCommandSetup({
+            guildId,
+            ...body,
+            expectedRevision: BigInt(body.expectedRevision),
+        });
+    });
+}
+//# sourceMappingURL=guild-command-control-routes.js.map

package/dist/guild-command-discord-client.d.ts

@@ -0,0 +1,21 @@
+import type { ObservedGuildCommand, ProjectedGuildCommand } from "./guild-command-projection.js";
+export interface GuildCommandDiscordRest {
+    get(route: `/${string}`): Promise<unknown>;
+    put(route: `/${string}`, options: {
+        body: unknown;
+    }): Promise<unknown>;
+}
+export declare class GuildCommandDiscordClient {
+    #private;
+    constructor(input: {
+        applicationId: string;
+        token: string;
+        writeGuildIds: readonly string[];
+        writeAllGuilds?: boolean;
+        rest?: GuildCommandDiscordRest;
+    });
+    canWrite(guildId: string): boolean;
+    observe(guildId: string): Promise<ObservedGuildCommand[]>;
+    replace(guildId: string, definitions: readonly ProjectedGuildCommand[]): Promise<ObservedGuildCommand[]>;
+}
+//# sourceMappingURL=guild-command-discord-client.d.ts.map

package/dist/guild-command-discord-client.js

@@ -0,0 +1,50 @@
+import { REST, Routes } from "discord.js";
+const SNOWFLAKE = /^\d{17,20}$/u;
+export class GuildCommandDiscordClient {
+    #applicationId;
+    #writeGuildIds;
+    #writeAllGuilds;
+    #rest;
+    constructor(input) {
+        validateSnowflake(input.applicationId, "Application ID");
+        if (!input.token)
+            throw new Error("Discord token is required");
+        for (const guildId of input.writeGuildIds)
+            validateSnowflake(guildId, "Write-allowlisted guild ID");
+        this.#applicationId = input.applicationId;
+        this.#writeGuildIds = new Set(input.writeGuildIds);
+        this.#writeAllGuilds = input.writeAllGuilds ?? false;
+        this.#rest =
+            input.rest ?? new REST({ version: "10" }).setToken(input.token);
+    }
+    canWrite(guildId) {
+        return this.#writeAllGuilds || this.#writeGuildIds.has(guildId);
+    }
+    async observe(guildId) {
+        validateSnowflake(guildId, "Guild ID");
+        return parseCommandCollection(await this.#rest.get(Routes.applicationGuildCommands(this.#applicationId, guildId)));
+    }
+    async replace(guildId, definitions) {
+        validateSnowflake(guildId, "Guild ID");
+        if (!this.canWrite(guildId))
+            throw new Error("Guild command write target is not allowlisted");
+        return parseCommandCollection(await this.#rest.put(Routes.applicationGuildCommands(this.#applicationId, guildId), { body: definitions.map(({ definition }) => definition) }));
+    }
+}
+function parseCommandCollection(value) {
+    if (!Array.isArray(value))
+        throw new Error("Discord returned an invalid command collection");
+    return value.map((command) => {
+        if (!isRecord(command) || typeof command.name !== "string" || !command.name)
+            throw new Error("Discord returned an invalid command definition");
+        return command;
+    });
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateSnowflake(value, label) {
+    if (!SNOWFLAKE.test(value))
+        throw new Error(`${label} is invalid`);
+}
+//# sourceMappingURL=guild-command-discord-client.js.map

package/dist/guild-command-projection.d.ts

@@ -0,0 +1,46 @@
+import type { GuildCommandVisibilityProfile } from "@helyx/database";
+import type { ModuleDefinition } from "@helyx/sdk";
+export { commandRegistrationPolicy } from "./command-registration-policy.js";
+export interface ProjectedGuildCommand {
+    name: string;
+    type: number;
+    ownerModuleId: string;
+    ownerModuleName: string;
+    definition: Readonly<Record<string, unknown>>;
+    executablePaths: readonly string[];
+}
+export interface GuildCommandProjection {
+    definitions: readonly ProjectedGuildCommand[];
+    definitionHash: string;
+    rootCount: number;
+    subcommandCount: number;
+    selectedModuleIds: readonly string[];
+}
+export interface ObservedGuildCommand {
+    id?: string;
+    application_id?: string;
+    guild_id?: string;
+    version?: string;
+    name: string;
+    type?: number;
+    [key: string]: unknown;
+}
+export interface GuildCommandDiff {
+    unchanged: readonly string[];
+    create: readonly ProjectedGuildCommand[];
+    update: readonly ProjectedGuildCommand[];
+    remove: readonly ObservedGuildCommand[];
+    conflicts: readonly string[];
+    observationRequired: boolean;
+}
+export declare function projectGuildCommands(input: {
+    modules: readonly ModuleDefinition[];
+    enabledModuleIds: ReadonlySet<string>;
+    globallyDisabledModuleIds?: ReadonlySet<string>;
+    profile: GuildCommandVisibilityProfile;
+    includeInternalCommands?: boolean;
+}): GuildCommandProjection;
+export declare function diffGuildCommands(desired: GuildCommandProjection, observedInput: readonly ObservedGuildCommand[]): GuildCommandDiff;
+export declare function guildCommandDefinitionHash(definitions: readonly Readonly<Record<string, unknown>>[]): string;
+export declare function diffDryRunGuildCommands(desired: GuildCommandProjection, previousDesiredDefinitionHash: string | null): GuildCommandDiff;
+//# sourceMappingURL=guild-command-projection.d.ts.map

package/dist/guild-command-projection.js

@@ -0,0 +1,254 @@
+import { isCustomerSelectableModule } from "@helyx/module-manifest";
+import { createHash } from "node:crypto";
+import { collectCommandRegistrations, } from "./shared-commands.js";
+import { toCommandDefinition } from "./interactions.js";
+import { commandRegistrationPolicy, contributionRegistrationPolicy, } from "./command-registration-policy.js";
+const MAX_GUILD_ROOTS = 75;
+const MAX_IMMEDIATE_CHILDREN = 20;
+export { commandRegistrationPolicy } from "./command-registration-policy.js";
+export function projectGuildCommands(input) {
+    const byId = new Map(input.modules.map((module) => [module.manifest.id, module]));
+    if (byId.size !== input.modules.length)
+        throw new Error("Command projection received duplicate module IDs");
+    const globallyDisabled = input.globallyDisabledModuleIds ?? new Set();
+    const selected = new Set();
+    for (const module of input.modules) {
+        if (input.includeInternalCommands &&
+            commandRegistrationPolicy(module) === "internal-guild") {
+            selectWithDependencies(module, byId, selected);
+            continue;
+        }
+        if (!isCustomerSelectableModule(module.manifest))
+            continue;
+        if (globallyDisabled.has(module.manifest.id))
+            continue;
+        const visible = input.profile === "all_loaded" ||
+            (input.profile === "all_released" &&
+                (module.manifest.releaseStatus === "live" ||
+                    module.manifest.releaseStatus === "beta")) ||
+            (input.profile === "enabled_only" &&
+                input.enabledModuleIds.has(module.manifest.id));
+        if (visible)
+            selectWithDependencies(module, byId, selected);
+    }
+    const selectedModules = [...selected]
+        .map((moduleId) => byId.get(moduleId))
+        .filter(Boolean)
+        .sort((left, right) => left.manifest.id.localeCompare(right.manifest.id));
+    const registrations = collectCommandRegistrations(selectedModules);
+    const definitions = [...registrations.values()]
+        .filter(({ moduleId, contribution }) => {
+        const owner = byId.get(moduleId);
+        if (!owner)
+            throw new Error(`Command owner is not loaded: ${moduleId}`);
+        const policy = projectionRegistrationPolicy(owner, contribution);
+        return (policy === "enabled-guild" ||
+            (input.includeInternalCommands && policy === "internal-guild"));
+    })
+        .map(projectRegistration)
+        .sort(compareProjectedCommands);
+    validateProjectedCommands(definitions);
+    const canonicalDefinitions = definitions.map(({ definition }) => definition);
+    return {
+        definitions,
+        definitionHash: guildCommandDefinitionHash(canonicalDefinitions),
+        rootCount: definitions.length,
+        subcommandCount: definitions.reduce((total, definition) => total + definition.executablePaths.length, 0),
+        selectedModuleIds: [...selected].sort(),
+    };
+}
+function projectionRegistrationPolicy(module, contribution) {
+    return contributionRegistrationPolicy(module, contribution, {
+        allowLegacyCustomerGlobals: false,
+    });
+}
+export function diffGuildCommands(desired, observedInput) {
+    const observed = [...observedInput].sort(compareObservedCommands);
+    const conflicts = [];
+    const observedByKey = new Map();
+    for (const command of observed) {
+        const key = commandKey(command);
+        if (observedByKey.has(key))
+            conflicts.push(`duplicate_observed:${key}`);
+        else
+            observedByKey.set(key, command);
+    }
+    const desiredByKey = new Map(desired.definitions.map((command) => [
+        commandKey(command.definition),
+        command,
+    ]));
+    const unchanged = [];
+    const create = [];
+    const update = [];
+    for (const [key, command] of desiredByKey) {
+        const current = observedByKey.get(key);
+        if (!current) {
+            create.push(command);
+            continue;
+        }
+        if (canonicalStringify(normalizeGuildCommandDefinition(current)) ===
+            canonicalStringify(normalizeGuildCommandDefinition(command.definition)))
+            unchanged.push(command.name);
+        else
+            update.push(command);
+    }
+    const remove = observed.filter((command) => !desiredByKey.has(commandKey(command)));
+    return {
+        unchanged,
+        create,
+        update,
+        remove,
+        conflicts,
+        observationRequired: false,
+    };
+}
+export function guildCommandDefinitionHash(definitions) {
+    const normalized = [...definitions]
+        .sort((left, right) => commandKey(left).localeCompare(commandKey(right)))
+        .map((definition) => normalizeGuildCommandDefinition(definition));
+    return createHash("sha256")
+        .update(canonicalStringify(normalized))
+        .digest("hex");
+}
+export function diffDryRunGuildCommands(desired, previousDesiredDefinitionHash) {
+    if (previousDesiredDefinitionHash === desired.definitionHash) {
+        return {
+            unchanged: desired.definitions.map(({ name }) => name),
+            create: [],
+            update: [],
+            remove: [],
+            conflicts: [],
+            observationRequired: false,
+        };
+    }
+    return {
+        unchanged: [],
+        create: [],
+        update: [],
+        remove: [],
+        conflicts: [],
+        observationRequired: true,
+    };
+}
+function selectWithDependencies(module, byId, selected) {
+    if (selected.has(module.manifest.id))
+        return;
+    selected.add(module.manifest.id);
+    for (const dependency of module.manifest.dependencies) {
+        const definition = byId.get(dependency.id);
+        if (!definition)
+            throw new Error(`Command projection is missing dependency ${dependency.id} for ${module.manifest.id}`);
+        selectWithDependencies(definition, byId, selected);
+    }
+}
+function projectRegistration(registration) {
+    const definition = toCommandDefinition(registration);
+    return {
+        name: registration.contribution.name,
+        type: Number(definition.type ?? 1),
+        ownerModuleId: registration.moduleId,
+        ownerModuleName: registration.moduleName,
+        definition: canonicalValue(definition),
+        executablePaths: executablePaths(registration),
+    };
+}
+function executablePaths(registration) {
+    if (registration.routeOwners)
+        return [...registration.routeOwners.keys()].sort();
+    const command = registration.contribution;
+    if (command.subcommands?.length)
+        return command.subcommands.map(({ name }) => name).sort();
+    if (command.subcommandGroups?.length)
+        return command.subcommandGroups
+            .flatMap((group) => group.subcommands.map((subcommand) => `${group.name}.${subcommand.name}`))
+            .sort();
+    return [];
+}
+function validateProjectedCommands(definitions) {
+    if (definitions.length > MAX_GUILD_ROOTS)
+        throw new Error("Guild command projection exceeds 75 roots");
+    const keys = new Set();
+    for (const command of definitions) {
+        const key = `${command.type}:${command.name}`;
+        if (keys.has(key))
+            throw new Error(`Duplicate projected command: ${key}`);
+        keys.add(key);
+        const options = command.definition.options;
+        if (Array.isArray(options) && options.length > MAX_IMMEDIATE_CHILDREN)
+            throw new Error(`Command ${command.name} exceeds 20 immediate children`);
+        const contributionChildren = command.executablePaths.filter((path) => !path.includes(".")).length;
+        const groups = new Map();
+        for (const path of command.executablePaths) {
+            const [group, child] = path.split(".");
+            if (child)
+                groups.set(group, (groups.get(group) ?? 0) + 1);
+        }
+        if (contributionChildren + groups.size > MAX_IMMEDIATE_CHILDREN)
+            throw new Error(`Command ${command.name} exceeds 20 immediate children`);
+        for (const [group, count] of groups) {
+            if (count > MAX_IMMEDIATE_CHILDREN)
+                throw new Error(`Command ${command.name} group ${group} exceeds 20 children`);
+        }
+    }
+}
+function compareProjectedCommands(left, right) {
+    return left.name.localeCompare(right.name) || left.type - right.type;
+}
+function compareObservedCommands(left, right) {
+    return (left.name.localeCompare(right.name) ||
+        Number(left.type ?? 1) - Number(right.type ?? 1));
+}
+function commandKey(command) {
+    if (typeof command.name !== "string" || !command.name)
+        throw new Error("Observed command has no valid name");
+    const type = command.type === undefined ? 1 : Number(command.type);
+    if (!Number.isInteger(type) || type < 1 || type > 3)
+        throw new Error(`Observed command ${command.name} has an invalid type`);
+    return `${type}:${command.name}`;
+}
+function normalizeGuildCommandDefinition(value, root = true) {
+    if (Array.isArray(value))
+        return value.map((item) => normalizeGuildCommandDefinition(item, false));
+    if (value === null || typeof value !== "object")
+        return value;
+    const source = value;
+    const normalized = Object.entries(source)
+        .filter(([key, item]) => {
+        if (["id", "application_id", "guild_id", "version"].includes(key))
+            return false;
+        if (key === "nsfw" && item === false)
+            return false;
+        if (key === "default_permission" && item === true)
+            return false;
+        if (key === "default_member_permissions" && item === null)
+            return false;
+        if (key === "required" && item === false)
+            return false;
+        if (key.endsWith("_localizations") && item === null)
+            return false;
+        if (key === "options" && Array.isArray(item) && item.length === 0)
+            return false;
+        return item !== undefined;
+    })
+        .map(([key, item]) => [key, normalizeGuildCommandDefinition(item, false)]);
+    const result = Object.fromEntries(normalized);
+    if (root) {
+        result.contexts ??= [0];
+        result.integration_types ??= [0];
+    }
+    return result;
+}
+function canonicalStringify(value) {
+    return JSON.stringify(canonicalValue(value));
+}
+function canonicalValue(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalValue);
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, item]) => item !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, item]) => [key, canonicalValue(item)]));
+}
+//# sourceMappingURL=guild-command-projection.js.map