@helyx/bot 1.0.1 → 1.2.0

package/dist/dashboard-action-routes.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+const snowflake = z.string().regex(/^\d{17,20}$/u);
+const moduleId = z.string().regex(/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/u);
+const actionParameters = z.object({
+    guildId: snowflake,
+    moduleId,
+    actionId: z.string().regex(/^[a-z][a-z0-9_-]*$/u),
+});
+const mutationContext = z.object({
+    actorUserId: snowflake,
+    correlationId: z.uuid(),
+});
+export function registerDashboardActionRoutes(server, service) {
+    server.post("/v1/guilds/:guildId/modules/:moduleId/actions/:actionId/preview", async (request) => {
+        const params = actionParameters.parse(request.params);
+        const body = mutationContext.parse(request.body);
+        return service.previewDashboardAction({ ...params, ...body });
+    });
+    server.post("/v1/guilds/:guildId/modules/:moduleId/actions/:actionId", async (request) => {
+        const params = actionParameters.parse(request.params);
+        const body = mutationContext
+            .extend({
+            inspectionRevision: z.string().min(1).max(200).optional(),
+        })
+            .parse(request.body);
+        return service.executeDashboardAction({
+            ...params,
+            actorUserId: body.actorUserId,
+            correlationId: body.correlationId,
+            ...(body.inspectionRevision === undefined
+                ? {}
+                : { inspectionRevision: body.inspectionRevision }),
+        });
+    });
+}
+//# sourceMappingURL=dashboard-action-routes.js.map

package/dist/dashboard-feature-control.d.ts

@@ -0,0 +1,37 @@
+import type { DashboardResourceField, DashboardResourceScalarField, DashboardSetting } from "@helyx/module-manifest";
+import { type ManagedResourceDetail, type ManagedResourcePage, type ManagedResourceRelationPage, type ManagedResourceValue, type ModuleConfigurationService, type ModuleDefinition, type ServiceAccess } from "@helyx/sdk";
+export declare function requireDashboardFeatures(services: ServiceAccess, guildId: string, moduleId: string, featureIds: readonly (string | undefined)[]): Promise<void>;
+export declare function changedSettingFeatureIds(settings: readonly DashboardSetting[], current: Readonly<Record<string, unknown>>, next: Readonly<Record<string, unknown>>): readonly string[];
+export declare function scalarInputFeatureIds(inputs: readonly DashboardResourceScalarField[], value: Readonly<Record<string, ManagedResourceValue>>): readonly string[];
+export declare function configurationPreviewFeatureIds(configurations: ModuleConfigurationService, guildId: string, module: ModuleDefinition, preview: {
+    featureId?: string | undefined;
+    inputs: readonly DashboardResourceScalarField[];
+}, input: {
+    value: Readonly<Record<string, unknown>>;
+    input: Readonly<Record<string, ManagedResourceValue>>;
+}): Promise<readonly (string | undefined)[]>;
+export declare function resourceFieldFeatureIds(fields: readonly DashboardResourceField[], value: Readonly<Record<string, ManagedResourceValue>>): readonly string[];
+export declare function validateManagedResourceInput(inputs: readonly DashboardResourceScalarField[], value: Readonly<Record<string, ManagedResourceValue>>): void;
+export declare function isBoundedManagedResourceValue(value: unknown, depth?: number, budget?: {
+    keys: number;
+}): value is ManagedResourceValue;
+export declare function hasBoundedManagedResourceBytes(value: unknown): boolean;
+export declare function normalizeManagedResourceDetail(value: Omit<ManagedResourceDetail, "description" | "attributes"> & {
+    description?: string | undefined;
+    attributes?: Readonly<Record<string, ManagedResourceValue>> | undefined;
+}, attributeKeys: readonly string[]): ManagedResourceDetail;
+export declare function normalizeManagedResourcePage(value: {
+    items: readonly (Omit<ManagedResourcePage["items"][number], "description" | "attributes"> & {
+        description?: string | undefined;
+        attributes?: Readonly<Record<string, ManagedResourceValue>> | undefined;
+    })[];
+    nextCursor?: string | undefined;
+    total?: number | undefined;
+}, attributeKeys: readonly string[]): ManagedResourcePage;
+export declare function normalizeManagedResourceRelationPage(value: {
+    items: ManagedResourceRelationPage["items"];
+    nextCursor?: string | undefined;
+}, valueKeys: readonly string[]): ManagedResourceRelationPage;
+export declare function projectManagedResourceObject(value: Readonly<Record<string, ManagedResourceValue>>, declaredKeys: readonly string[]): Record<string, ManagedResourceValue>;
+export declare function managedResourceColumnKeys(module: ModuleDefinition, resourceType: string): readonly string[];
+//# sourceMappingURL=dashboard-feature-control.d.ts.map

package/dist/dashboard-feature-control.js

@@ -0,0 +1,206 @@
+import { DashboardActionValidationError, HELYX_SERVICE_NAMES, } from "@helyx/sdk";
+import { BotControlForbiddenError } from "./control-errors.js";
+const SNOWFLAKE_PATTERN = /^\d{17,20}$/u;
+export async function requireDashboardFeatures(services, guildId, moduleId, featureIds) {
+    const unique = [...new Set(featureIds.filter(isDefined))];
+    if (unique.length === 0)
+        return;
+    if (!services.has(HELYX_SERVICE_NAMES.featureAccess))
+        throw new BotControlForbiddenError();
+    const access = services.get(HELYX_SERVICE_NAMES.featureAccess);
+    const decisions = await Promise.all(unique.map((featureId) => access.check({ guildId, moduleId, featureId }))).catch(() => []);
+    if (decisions.length !== unique.length ||
+        decisions.some(({ decision }) => decision !== "granted"))
+        throw new BotControlForbiddenError();
+}
+export function changedSettingFeatureIds(settings, current, next) {
+    return settings.flatMap((setting) => {
+        if (!Object.hasOwn(next, setting.key))
+            return [];
+        const changed = !configurationValuesEqual(Object.hasOwn(current, setting.key)
+            ? current[setting.key]
+            : "default" in setting
+                ? setting.default
+                : undefined, next[setting.key]);
+        if (!changed)
+            return [];
+        const selectedFeatureId = setting.type === "select" && typeof next[setting.key] === "string"
+            ? setting.options.find(({ value }) => value === next[setting.key])
+                ?.featureId
+            : undefined;
+        return [setting.featureId, selectedFeatureId].filter(isDefined);
+    });
+}
+export function scalarInputFeatureIds(inputs, value) {
+    return inputs.flatMap((input) => input.featureId && Object.hasOwn(value, input.key) ? [input.featureId] : []);
+}
+export async function configurationPreviewFeatureIds(configurations, guildId, module, preview, input) {
+    const current = await configurations.get(guildId, module.manifest.id);
+    return [
+        preview.featureId,
+        ...scalarInputFeatureIds(preview.inputs, input.input),
+        ...(module.manifest.manifestVersion === "0.5"
+            ? changedSettingFeatureIds(module.manifest.dashboard?.settings ?? [], current?.value ?? {}, input.value)
+            : []),
+    ];
+}
+export function resourceFieldFeatureIds(fields, value) {
+    const featureIds = [];
+    for (const field of fields) {
+        const item = value[field.key];
+        if (item === undefined)
+            continue;
+        if (field.featureId &&
+            (!("default" in field) || !configurationValuesEqual(field.default, item)))
+            featureIds.push(field.featureId);
+        if (field.type !== "list" || !Array.isArray(item))
+            continue;
+        for (const entry of item) {
+            if (!isRecord(entry))
+                continue;
+            featureIds.push(...scalarInputFeatureIds(field.fields, entry));
+        }
+    }
+    return featureIds;
+}
+export function validateManagedResourceInput(inputs, value) {
+    const declared = new Map(inputs.map((input) => [input.key, input]));
+    for (const key of Object.keys(value))
+        if (!declared.has(key))
+            throw new DashboardActionValidationError(`The action value "${key}" is not declared by the module.`);
+    for (const input of inputs) {
+        const item = value[input.key];
+        if (item === undefined) {
+            if (input.required)
+                throw new DashboardActionValidationError(`${input.label} is required for this action.`);
+            continue;
+        }
+        const valid = input.type === "boolean"
+            ? typeof item === "boolean"
+            : input.type === "integer"
+                ? typeof item === "number" &&
+                    Number.isInteger(item) &&
+                    item >= input.minimum &&
+                    item <= input.maximum &&
+                    (item - input.minimum) % (input.step ?? 1) === 0
+                : input.type === "select"
+                    ? typeof item === "string" &&
+                        input.options.some(({ value: option }) => option === item)
+                    : input.type === "discord-channel" || input.type === "discord-role"
+                        ? isValidDiscordResourceSelection(input, item)
+                        : typeof item === "string" &&
+                            item.length >= input.minLength &&
+                            item.length <= input.maxLength;
+        if (!valid)
+            throw new DashboardActionValidationError(`${input.label} is not a valid action value.`);
+    }
+}
+function isValidDiscordResourceSelection(input, value) {
+    if (input.multiple !== true)
+        return typeof value === "string" && SNOWFLAKE_PATTERN.test(value);
+    if (!Array.isArray(value))
+        return false;
+    const minimum = input.minItems ?? (input.required ? 1 : 0);
+    const maximum = input.maxItems ?? 25;
+    return (value.length >= minimum &&
+        value.length <= maximum &&
+        new Set(value).size === value.length &&
+        value.every((item) => typeof item === "string" && SNOWFLAKE_PATTERN.test(item)));
+}
+export function isBoundedManagedResourceValue(value, depth = 0, budget = { keys: 0 }) {
+    if (depth > 8)
+        return false;
+    if (value === null ||
+        typeof value === "boolean" ||
+        (typeof value === "number" && Number.isFinite(value)))
+        return true;
+    if (typeof value === "string")
+        return value.length <= 4_000;
+    if (Array.isArray(value))
+        return (value.length <= 100 &&
+            value.every((item) => isBoundedManagedResourceValue(item, depth + 1, budget)));
+    if (!isRecord(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return false;
+    const entries = Object.entries(value);
+    budget.keys += entries.length;
+    return (entries.length <= 100 &&
+        budget.keys <= 500 &&
+        entries.every(([key, item]) => key.length >= 1 &&
+            key.length <= 100 &&
+            isBoundedManagedResourceValue(item, depth + 1, budget)));
+}
+export function hasBoundedManagedResourceBytes(value) {
+    return (new TextEncoder().encode(JSON.stringify(value)).byteLength <= 48 * 1_024);
+}
+export function normalizeManagedResourceDetail(value, attributeKeys) {
+    return {
+        id: value.id,
+        revision: value.revision,
+        status: value.status,
+        title: value.title,
+        ...(value.description === undefined
+            ? {}
+            : { description: value.description }),
+        ...(value.attributes === undefined || attributeKeys.length === 0
+            ? {}
+            : {
+                attributes: projectManagedResourceObject(value.attributes, attributeKeys),
+            }),
+        updatedAt: value.updatedAt,
+        value: value.value,
+    };
+}
+export function normalizeManagedResourcePage(value, attributeKeys) {
+    return {
+        items: value.items.map((item) => ({
+            id: item.id,
+            revision: item.revision,
+            status: item.status,
+            title: item.title,
+            ...(item.description === undefined
+                ? {}
+                : { description: item.description }),
+            ...(item.attributes === undefined || attributeKeys.length === 0
+                ? {}
+                : {
+                    attributes: projectManagedResourceObject(item.attributes, attributeKeys),
+                }),
+            updatedAt: item.updatedAt,
+        })),
+        ...(value.nextCursor === undefined ? {} : { nextCursor: value.nextCursor }),
+        ...(value.total === undefined ? {} : { total: value.total }),
+    };
+}
+export function normalizeManagedResourceRelationPage(value, valueKeys) {
+    return {
+        items: value.items.map((item) => ({
+            id: item.id,
+            value: projectManagedResourceObject(item.value, valueKeys),
+        })),
+        ...(value.nextCursor === undefined ? {} : { nextCursor: value.nextCursor }),
+    };
+}
+export function projectManagedResourceObject(value, declaredKeys) {
+    const allowed = new Set(declaredKeys);
+    return Object.fromEntries(Object.entries(value)
+        .filter(([key]) => allowed.has(key))
+        .map(([key, item]) => [key, structuredClone(item)]));
+}
+export function managedResourceColumnKeys(module, resourceType) {
+    return (module.manifest.dashboard?.resources
+        ?.find(({ id }) => id === resourceType)
+        ?.columns?.map(({ key }) => key) ?? []);
+}
+function configurationValuesEqual(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function isDefined(value) {
+    return value !== undefined;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=dashboard-feature-control.js.map

package/dist/dashboard-module-projection.d.ts

@@ -9,10 +9,15 @@ interface DashboardLogEventDefinition {
 }
 interface DashboardActionDefinition {
     id: string;
+    permissionId?: string | undefined;
+    featureId?: string | undefined;
     label: string;
     description: string;
     buttonLabel: string;
     style: "primary" | "secondary" | "danger";
+    confirmation?: string | undefined;
+    inputs?: readonly unknown[] | undefined;
+    inspection?: "optional" | "required" | undefined;
 }
 type DashboardResourceDefinition = NonNullable<NonNullable<ModuleDefinition["manifest"]["dashboard"]>["resources"]>[number];
 export interface DashboardModuleDefinition {
@@ -27,6 +32,10 @@ export interface DashboardModuleDefinition {
     tier: ModuleTier;
     requiredPermissions: string[];
     settings: readonly unknown[];
+    settingsMutationPermissionId?: string;
+    settingsPreview?: Readonly<Record<string, unknown>>;
+    features: readonly unknown[];
+    permissionOperations: readonly unknown[];
     commands: DashboardCommandDefinition[];
     logEvents: DashboardLogEventDefinition[];
     actions: DashboardActionDefinition[];

package/dist/dashboard-module-projection.js

@@ -15,6 +15,21 @@ export function mapDashboardModule(module) {
         tier: getModuleTier(module.manifest),
         requiredPermissions: [...module.manifest.permissions],
         settings: dashboard.settings,
+        ...("settingsMutationPermissionId" in dashboard &&
+            dashboard.settingsMutationPermissionId
+            ? {
+                settingsMutationPermissionId: dashboard.settingsMutationPermissionId,
+            }
+            : {}),
+        ...("settingsPreview" in dashboard && dashboard.settingsPreview
+            ? { settingsPreview: structuredClone(dashboard.settingsPreview) }
+            : {}),
+        features: module.manifest.manifestVersion === "0.5"
+            ? module.manifest.features.map((feature) => structuredClone(feature))
+            : [],
+        permissionOperations: module.manifest.manifestVersion === "0.5"
+            ? module.manifest.permissionOperations.map((operation) => structuredClone(operation))
+            : [],
         commands: dashboardCommands(module),
         logEvents: (module.logging?.events ?? []).map((event) => ({ ...event })),
         actions: (dashboard.actions ?? []).map((action) => ({ ...action })),

package/dist/dashboard-preview-import-routes.d.ts

@@ -0,0 +1,6 @@
+import type { FastifyInstance } from "fastify";
+import type { BotControlHandler } from "./control-server.js";
+/** Registers the bounded, non-persisting preview and import boundaries. */
+export declare function registerDashboardPreviewImportRoutes(server: FastifyInstance, service: BotControlHandler): void;
+export declare function registerDashboardResourceMutationRoutes(server: FastifyInstance, service: BotControlHandler): void;
+//# sourceMappingURL=dashboard-preview-import-routes.d.ts.map

package/dist/dashboard-preview-import-routes.js

@@ -0,0 +1,121 @@
+import { z } from "zod";
+import { hasBoundedManagedResourceBytes, isBoundedManagedResourceValue, } from "./dashboard-feature-control.js";
+const snowflake = z.string().regex(/^\d{17,20}$/u);
+const moduleId = z.string().regex(/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/u);
+const resourceType = z.string().regex(/^[a-z][a-z0-9_-]*$/u);
+const mutationContext = z.object({
+    actorUserId: snowflake,
+    correlationId: z.uuid(),
+});
+const configurationValue = z.record(z.string(), z.union([
+    z.null(),
+    z.string(),
+    z.boolean(),
+    z.number().finite(),
+    z.array(z.string()).max(100),
+]));
+const managedResourceValue = z.custom((value) => isBoundedManagedResourceValue(value), "Managed resource value exceeds the transport limits");
+const managedResourceObject = z
+    .record(z.string().min(1).max(100), managedResourceValue)
+    .refine(hasBoundedManagedResourceBytes);
+/** Registers the bounded, non-persisting preview and import boundaries. */
+export function registerDashboardPreviewImportRoutes(server, service) {
+    server.post("/v1/guilds/:guildId/modules/:moduleId/configuration/preview", async (request) => {
+        const params = z
+            .object({ guildId: snowflake, moduleId })
+            .strict()
+            .parse(request.params);
+        const body = mutationContext
+            .extend({ value: configurationValue, input: managedResourceObject })
+            .strict()
+            .parse(request.body);
+        return service.previewConfiguration({ ...params, ...body });
+    });
+    server.post("/v1/guilds/:guildId/modules/:moduleId/resources/:resourceType/import", async (request) => {
+        const params = z
+            .object({ guildId: snowflake, moduleId, resourceType })
+            .strict()
+            .parse(request.params);
+        const body = mutationContext
+            .extend({
+            format: z.literal("utf8_text"),
+            content: z
+                .string()
+                .min(1)
+                .refine((value) => Buffer.byteLength(value, "utf8") <= 48 * 1_024, "Managed resource import exceeds the transport byte limit"),
+        })
+            .strict()
+            .parse(request.body);
+        return service.importManagedResource({ ...params, ...body });
+    });
+}
+export function registerDashboardResourceMutationRoutes(server, service) {
+    const resourceParams = z
+        .object({ guildId: snowflake, moduleId, resourceType })
+        .strict();
+    const identifiedResourceParams = resourceParams.extend({
+        resourceId: z.string().trim().min(1).max(100),
+    });
+    server.post("/v1/guilds/:guildId/modules/:moduleId/resources/:resourceType/preview", async (request) => {
+        const params = resourceParams.parse(request.params);
+        const body = mutationContext
+            .extend({ value: managedResourceObject })
+            .strict()
+            .parse(request.body);
+        return service.previewManagedResource({ ...params, ...body });
+    });
+    server.post("/v1/guilds/:guildId/modules/:moduleId/resources/:resourceType", async (request) => {
+        const params = resourceParams.parse(request.params);
+        const body = mutationContext
+            .extend({
+            intent: z.enum(["draft", "publish"]).optional().default("publish"),
+            value: managedResourceObject,
+        })
+            .strict()
+            .parse(request.body);
+        return service.createManagedResource({ ...params, ...body });
+    });
+    server.put("/v1/guilds/:guildId/modules/:moduleId/resources/:resourceType/:resourceId", async (request) => {
+        const params = identifiedResourceParams.parse(request.params);
+        const body = mutationContext
+            .extend({
+            expectedRevision: z.number().int().min(0),
+            value: managedResourceObject.optional().default({}),
+        })
+            .strict()
+            .parse(request.body);
+        return service.updateManagedResource({ ...params, ...body });
+    });
+    server.delete("/v1/guilds/:guildId/modules/:moduleId/resources/:resourceType/:resourceId", async (request) => {
+        const params = identifiedResourceParams.parse(request.params);
+        const body = mutationContext
+            .extend({ expectedRevision: z.number().int().min(0) })
+            .strict()
+            .parse(request.body);
+        return service.deleteManagedResource({ ...params, ...body });
+    });
+    server.post("/v1/guilds/:guildId/modules/:moduleId/resources/:resourceType/:resourceId/actions/:actionId", async (request) => {
+        const params = identifiedResourceParams
+            .extend({ actionId: resourceType })
+            .parse(request.params);
+        const body = mutationContext
+            .extend({
+            expectedRevision: z.number().int().min(0),
+            value: managedResourceObject.optional().default({}),
+            actorAuthenticatedAt: z.iso.datetime({ offset: true }).optional(),
+        })
+            .strict()
+            .parse(request.body);
+        return service.executeManagedResourceAction({
+            ...params,
+            actorUserId: body.actorUserId,
+            correlationId: body.correlationId,
+            expectedRevision: body.expectedRevision,
+            value: body.value,
+            ...(body.actorAuthenticatedAt === undefined
+                ? {}
+                : { actorAuthenticatedAt: body.actorAuthenticatedAt }),
+        });
+    });
+}
+//# sourceMappingURL=dashboard-preview-import-routes.js.map

package/dist/developer-operations-module.d.ts

@@ -1,6 +1,7 @@
 import { type ModuleDefinition } from "@helyx/sdk";
 import { type ShardHealthSnapshot } from "./shard-contracts.js";
 import type { TriviaDataProvider } from "./trivia-data-provider.js";
+import type { DeveloperServerModeration } from "./hosted-server-moderation.js";
 export interface ShardHealthProvider {
     getHealth(): Promise<ShardHealthSnapshot>;
 }
@@ -19,6 +20,7 @@ export interface DeveloperOperationsInput {
     processLabel: string;
     health: ShardHealthProvider;
     triviaData: TriviaDataProvider;
+    moderation?: DeveloperServerModeration;
 }
 export declare function createDeveloperOperationsModule(input: DeveloperOperationsInput): ModuleDefinition;
 export declare class WorkerShardHealthProvider implements ShardHealthProvider {