@helyx/bot 1.3.1 → 1.5.0

package/dist/cloud-control-dispatcher.js

@@ -1,11 +1,16 @@
 import { assertCloudResponseSize, parseOperationInput, } from "@helyx/control-protocol";
 import { CloudConnectorRepository } from "@helyx/database";
 export class CloudControlDispatcher {
-    database;
     control;
-    constructor(database, control) {
-        this.database = database;
+    commands;
+    #repository;
+    constructor(databaseOrInput, control, commands) {
         this.control = control;
+        this.commands = commands;
+        this.#repository =
+            "repository" in databaseOrInput
+                ? databaseOrInput.repository
+                : new CloudConnectorRepository(databaseOrInput);
     }
     async execute(request, correlationId) {
         const actorUserId = request.actor.kind === "customer"
@@ -52,6 +57,48 @@ export class CloudControlDispatcher {
                 });
                 break;
             }
+            case "guild.commands.status.read.v1": {
+                const input = parseOperationInput(request.operation, request.input);
+                await this.#requireCommandAccess(input.guildId, actorUserId);
+                result = await this.#commands().getStatus(input.guildId);
+                break;
+            }
+            case "guild.commands.history.read.v1": {
+                const input = parseOperationInput(request.operation, request.input);
+                await this.#requireCommandAccess(input.guildId, actorUserId);
+                result = await this.#commands().listHistory({
+                    guildId: input.guildId,
+                    ...(input.before ? { beforeEventId: BigInt(input.before) } : {}),
+                    ...(input.since ? { since: new Date(input.since) } : {}),
+                    limit: input.limit,
+                });
+                break;
+            }
+            case "guild.commands.status.refresh.v1": {
+                const input = parseOperationInput(request.operation, request.input);
+                const actor = await this.#requireCommandAccess(input.guildId, actorUserId);
+                result = await this.#commands().refreshStatus({
+                    guildId: input.guildId,
+                    actorUserId: actor,
+                    correlationId,
+                });
+                break;
+            }
+            case "guild.commands.rebuild.v1": {
+                const input = parseOperationInput(request.operation, request.input);
+                const actor = await this.#requireCommandAccess(input.guildId, actorUserId);
+                result = await this.#commands().requestReconciliation({
+                    guildId: input.guildId,
+                    actorUserId: actor,
+                    correlationId,
+                    expectedRevision: BigInt(input.expectedRevision),
+                    source: "customer_rebuild",
+                    budgetClass: "customer",
+                    delayMs: 120_000,
+                    summary: "A server manager requested a command rebuild.",
+                });
+                break;
+            }
             case "guild.module.public.read.v1": {
                 const input = parseOperationInput(request.operation, request.input);
                 if (request.actor.kind !== "public")
@@ -74,6 +121,28 @@ export class CloudControlDispatcher {
                 });
                 break;
             }
+            case "guild.module.channel-audit.config.read.v1": {
+                const input = parseOperationInput(request.operation, request.input);
+                if (!this.control.readChannelAuditConfiguration)
+                    throw new Error("Channel audit is not supported by this bot version");
+                result = await this.control.readChannelAuditConfiguration({
+                    ...input,
+                    actorUserId: requiredActor(actorUserId),
+                    correlationId,
+                });
+                break;
+            }
+            case "guild.module.channel-audit.check.v1": {
+                const input = parseOperationInput(request.operation, request.input);
+                if (!this.control.checkChannelAudit)
+                    throw new Error("Channel audit is not supported by this bot version");
+                result = await this.control.checkChannelAudit({
+                    ...input,
+                    actorUserId: requiredActor(actorUserId),
+                    correlationId,
+                });
+                break;
+            }
             case "guild.module.configuration.write.v1": {
                 const input = parseOperationInput(request.operation, request.input);
                 result = await this.control.updateConfiguration({
@@ -245,8 +314,19 @@ export class CloudControlDispatcher {
         assertCloudResponseSize(result);
         return result;
     }
+    #commands() {
+        if (!this.commands)
+            throw new Error("guild_command_state_unavailable");
+        return this.commands;
+    }
+    async #requireCommandAccess(guildId, actorUserId) {
+        const actor = requiredActor(actorUserId);
+        if (!(await this.control.canAccessDashboard({ guildId, actorUserId: actor })))
+            throw new CloudControlDeniedError("guild_command_access_denied");
+        return actor;
+    }
     async #supportSnapshot(input) {
-        const repository = new CloudConnectorRepository(this.database);
+        const repository = this.#repository;
         const consent = await repository.getConsent();
         const requested = input.dataClasses.filter((dataClass) => consent.supportDataClasses.includes(dataClass));
         if (!consent.supportInspectionEnabled || requested.length === 0) {

package/dist/control-errors.d.ts

@@ -1,4 +1,16 @@
 import { type PermissionMutationDenialReason } from "@helyx/core";
+export declare function isUnknownGuildError(error: unknown): boolean;
+export declare function isUnknownMemberError(error: unknown): boolean;
+export declare class BotControlTransportError extends Error {
+    readonly status: 400 | 403 | 404 | 409 | 502 | 503 | 504;
+    constructor(status: 400 | 403 | 404 | 409 | 502 | 503 | 504, message: string);
+}
+export declare class BotControlValidationError extends Error {
+    constructor(message: string);
+}
+export declare class BotControlNotFoundError extends Error {
+    constructor(message?: string);
+}
 export declare class BotControlForbiddenError extends Error {
     constructor(message?: string);
 }

package/dist/control-errors.js

@@ -1,4 +1,36 @@
 import { permissionMutationDenialMessage, } from "@helyx/core";
+export function isUnknownGuildError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === 10_004);
+}
+export function isUnknownMemberError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === 10_007);
+}
+export class BotControlTransportError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "BotControlTransportError";
+    }
+}
+export class BotControlValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BotControlValidationError";
+    }
+}
+export class BotControlNotFoundError extends Error {
+    constructor(message = "Discord server is not available to Helyx") {
+        super(message);
+        this.name = "BotControlNotFoundError";
+    }
+}
 export class BotControlForbiddenError extends Error {
     constructor(message = "You no longer have permission to perform this action") {
         super(message);

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

@@ -0,0 +1,84 @@
+import type { ManagedResourceValue } from "@helyx/sdk";
+import { z } from "zod";
+export declare const snowflake: z.ZodString;
+export declare const moduleId: z.ZodString;
+export declare const configurationValue: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodNull, z.ZodString, z.ZodBoolean, z.ZodNumber, z.ZodArray<z.ZodString>]>>;
+export declare const permissionState: z.ZodObject<{
+    version: z.ZodNumber;
+    module: z.ZodObject<{
+        preset: z.ZodEnum<{
+            everyone: "everyone";
+            moderators: "moderators";
+            administrators: "administrators";
+            custom: "custom";
+        }>;
+        allowedRoleIds: z.ZodArray<z.ZodString>;
+        deniedRoleIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    commands: z.ZodArray<z.ZodObject<{
+        commandId: z.ZodString;
+        version: z.ZodNumber;
+        enabled: z.ZodBoolean;
+        policy: z.ZodObject<{
+            preset: z.ZodEnum<{
+                everyone: "everyone";
+                moderators: "moderators";
+                administrators: "administrators";
+                custom: "custom";
+            }>;
+            allowedRoleIds: z.ZodArray<z.ZodString>;
+            deniedRoleIds: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const guildAccessPolicy: z.ZodObject<{
+    administratorRoleIds: z.ZodArray<z.ZodString>;
+    moderatorRoleIds: z.ZodArray<z.ZodString>;
+    dashboardModeratorsEnabled: z.ZodBoolean;
+    dashboardAllowedRoleIds: z.ZodArray<z.ZodString>;
+    dashboardDeniedRoleIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export declare const mutationContext: z.ZodObject<{
+    actorUserId: z.ZodString;
+    correlationId: z.ZodUUID;
+}, z.core.$strip>;
+export declare const resourceId: z.ZodString;
+export declare const resourceCursor: z.ZodString;
+export declare const resourceActionId: z.ZodString;
+export declare const managedResourceFilters: z.ZodRecord<z.ZodString, z.ZodString>;
+export declare const managedResourceObject: z.ZodRecord<z.ZodString, z.ZodCustom<ManagedResourceValue, ManagedResourceValue>>;
+export declare const managedResourceDetailSchema: z.ZodObject<{
+    id: z.ZodString;
+    revision: z.ZodNumber;
+    status: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<ManagedResourceValue, ManagedResourceValue>>>;
+    updatedAt: z.ZodISODateTime;
+    value: z.ZodRecord<z.ZodString, z.ZodCustom<ManagedResourceValue, ManagedResourceValue>>;
+    availableActionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const managedResourcePageSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        revision: z.ZodNumber;
+        status: z.ZodString;
+        title: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        attributes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<ManagedResourceValue, ManagedResourceValue>>>;
+        updatedAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+    nextCursor: z.ZodOptional<z.ZodString>;
+    total: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const managedResourceRelationPageSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        value: z.ZodRecord<z.ZodString, z.ZodCustom<ManagedResourceValue, ManagedResourceValue>>;
+    }, z.core.$strict>>;
+    nextCursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const managedResourceDeleteResultSchema: z.ZodObject<{
+    deleted: z.ZodBoolean;
+}, z.core.$strict>;
+//# sourceMappingURL=control-server-schemas.d.ts.map

package/dist/control-server-schemas.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { hasBoundedManagedResourceBytes, isBoundedManagedResourceValue, } from "./dashboard-feature-control.js";
+export const snowflake = z.string().regex(/^\d{17,20}$/u);
+export const moduleId = z.string().regex(/^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/u);
+export const configurationValue = z.record(z.string(), z.union([
+    z.null(),
+    z.string(),
+    z.boolean(),
+    z.number().finite(),
+    z.array(z.string()).max(100),
+]));
+const permissionPreset = z.enum([
+    "everyone",
+    "moderators",
+    "administrators",
+    "custom",
+]);
+const dashboardPermissionPolicy = z.object({
+    preset: permissionPreset,
+    allowedRoleIds: z.array(snowflake).max(100),
+    deniedRoleIds: z.array(snowflake).max(100),
+});
+export const permissionState = z.object({
+    version: z.number().int().min(0),
+    module: dashboardPermissionPolicy,
+    commands: z
+        .array(z.object({
+        commandId: z.string().min(1).max(100),
+        version: z.number().int().min(0),
+        enabled: z.boolean(),
+        policy: dashboardPermissionPolicy,
+    }))
+        .max(100),
+});
+export const guildAccessPolicy = z
+    .object({
+    administratorRoleIds: z.array(snowflake).max(25),
+    moderatorRoleIds: z.array(snowflake).max(25),
+    dashboardModeratorsEnabled: z.boolean(),
+    dashboardAllowedRoleIds: z.array(snowflake).max(25),
+    dashboardDeniedRoleIds: z.array(snowflake).max(25),
+})
+    .strict();
+export const mutationContext = z.object({
+    actorUserId: snowflake,
+    correlationId: z.uuid(),
+});
+export const resourceId = z.string().trim().min(1).max(100);
+export const resourceCursor = z.string().min(1).max(2_048);
+export const resourceActionId = z.string().regex(/^[a-z][a-z0-9_-]*$/u);
+export const managedResourceFilters = z
+    .record(z.string().regex(/^[a-z][a-zA-Z0-9_]*$/u), z.string().trim().min(1).max(100))
+    .refine((value) => Object.keys(value).length <= 8);
+const managedResourceValue = z.custom((value) => isBoundedManagedResourceValue(value), "Managed resource value exceeds the transport limits");
+export const managedResourceObject = z
+    .record(z.string().min(1).max(100), managedResourceValue)
+    .refine(hasBoundedManagedResourceBytes);
+const managedResourceSummarySchema = z
+    .object({
+    id: resourceId,
+    revision: z.number().int().min(0),
+    status: z.string().trim().min(1).max(100),
+    title: z.string().trim().min(1).max(200),
+    description: z.string().max(500).optional(),
+    attributes: managedResourceObject.optional(),
+    updatedAt: z.iso.datetime({ offset: true }),
+})
+    .strict();
+export const managedResourceDetailSchema = managedResourceSummarySchema
+    .extend({
+    value: managedResourceObject,
+    availableActionIds: z.array(z.string().min(1).max(100)).max(50).optional(),
+})
+    .strict()
+    .refine(hasBoundedManagedResourceBytes);
+export const managedResourcePageSchema = z
+    .object({
+    items: z.array(managedResourceSummarySchema).max(50),
+    nextCursor: resourceCursor.optional(),
+    total: z.number().int().min(0).optional(),
+})
+    .strict()
+    .refine(hasBoundedManagedResourceBytes);
+export const managedResourceRelationPageSchema = z
+    .object({
+    items: z
+        .array(z
+        .object({
+        id: resourceId,
+        value: managedResourceObject,
+    })
+        .strict())
+        .max(50),
+    nextCursor: resourceCursor.optional(),
+})
+    .strict()
+    .refine(hasBoundedManagedResourceBytes);
+export const managedResourceDeleteResultSchema = z
+    .object({ deleted: z.boolean() })
+    .strict();
+//# sourceMappingURL=control-server-schemas.js.map

package/dist/control-server.d.ts

@@ -1,4 +1,6 @@
-import { type DatabasePool, type GuildShardOwnership } from "@helyx/database";
+import { AuditRepository, GuildAccessPolicyRepository, InstallationRepository, ModuleLoggingPolicyRepository, PermissionPolicyRepository, type DatabasePool, type GuildShardOwnership } from "@helyx/database";
+import type { MysqlPool } from "@helyx/database-mysql";
+import type { CreatorOnboardingRequest, CreatorOnboardingResponse } from "@helyx/sdk";
 import { type DashboardActionInspection, type DashboardActionResult, type FeatureAccessDecision, type GuildAccessPolicy, type ManagedResourceCreationIntent, type ManagedResourceDetail, type ManagedResourcePage, type ManagedResourceRelationPage, type ManagedResourceValue, type MessageResponse, type ModuleDefinition, type OAuthConsumerCleanupResult, type PermissionActor, type PrivacyCapturePage, type PrivacyErasePage, type PrivacyProviderExecutor, type PublicAchievementProjectionPage, type ServiceAccess } from "@helyx/sdk";
 import { type ActionReceipt, type SignedAssessmentEnvelope } from "@helyx/verification-contracts";
 import { type Client } from "discord.js";
@@ -7,6 +9,8 @@ import { type BotModuleStatusMutationResult } from "./module-status-control.js";
 import { type FirstTimeCommandSetupHandler } from "./first-time-command-setup.js";
 import { type ShardHealthSnapshot } from "./shard-contracts.js";
 import { type DashboardPermissionState } from "./control-permissions.js";
+export { BotControlTransportError } from "./control-errors.js";
+import type { ChannelAuditControl } from "@helyx/sdk";
 import { type DashboardModuleDefinition } from "./dashboard-module-projection.js";
 import { type AvailabilityModuleCatalogue } from "./module-availability-control.js";
 import { registerGuildCommandControlRoutes } from "./guild-command-control-routes.js";
@@ -117,7 +121,8 @@ export interface DashboardGuildAccessState extends GuildAccessPolicy {
     actorHighestRolePosition: number | null;
     updatedAt: string | null;
 }
-export interface BotControlHandler extends FirstTimeCommandSetupHandler, DashboardActionHandler {
+export interface BotControlHandler extends FirstTimeCommandSetupHandler, DashboardActionHandler, ChannelAuditControl {
+    creatorOnboarding?(input: CreatorOnboardingRequest): Promise<CreatorOnboardingResponse>;
     cleanupOAuthConsumer(input: {
         consumerBindingId: string;
         moduleId: string;
@@ -324,21 +329,34 @@ export interface BotControlHandler extends FirstTimeCommandSetupHandler, Dashboa
         cursor?: string;
     }): Promise<PrivacyErasePage>;
 }
-export declare class BotControlTransportError extends Error {
-    readonly status: 400 | 403 | 404 | 409 | 502 | 503 | 504;
-    constructor(status: 400 | 403 | 404 | 409 | 502 | 503 | 504, message: string);
+export interface BotControlRepositories {
+    installations: Pick<InstallationRepository, "adoptGuildsForReconciliation" | "markGuildsRemovedForReconciliation" | "listModules" | "isModuleEnabled">;
+    accessPolicies: Pick<GuildAccessPolicyRepository, "get" | "save">;
+    loggingPolicies: Pick<ModuleLoggingPolicyRepository, "listForGuild" | "save">;
+    permissionPolicies: Pick<PermissionPolicyRepository, "save" | "deleteCommandPolicy">;
+    audit: Pick<AuditRepository, "append">;
 }
+interface ControlPersistence {
+    readonly repositories: BotControlRepositories;
+    withTransaction<Value>(operation: (repositories: BotControlRepositories) => Promise<Value>): Promise<Value>;
+}
+export interface BotControlPersistence extends ControlPersistence {
+    readonly engine: "mysql";
+}
+export declare function createMysqlBotControlPersistence(pool: MysqlPool): Promise<BotControlPersistence>;
 export declare class BotControlService implements BotControlHandler {
     #private;
-    private readonly database;
     private readonly resources;
     private readonly supportNotifications?;
     private readonly presenceOwnership?;
     private readonly presenceShardCount?;
-    constructor(database: DatabasePool, modules: readonly ModuleDefinition[], resources: BotControlGuildResourceDirectory, services: ServiceAccess, privacyExecutor?: PrivacyProviderExecutor, supportNotifications?: {
+    readonly readChannelAuditConfiguration: Required<ChannelAuditControl>["readChannelAuditConfiguration"];
+    readonly checkChannelAudit: Required<ChannelAuditControl>["checkChannelAudit"];
+    constructor(databaseOrPersistence: DatabasePool | BotControlPersistence, modules: readonly ModuleDefinition[], resources: BotControlGuildResourceDirectory, services: ServiceAccess, privacyExecutor?: PrivacyProviderExecutor, supportNotifications?: {
         guildId: string;
         channelId: string;
     } | undefined, presenceOwnership?: GuildShardOwnership | undefined, presenceShardCount?: number | undefined, statusModules?: readonly ModuleDefinition[]);
+    creatorOnboarding(input: CreatorOnboardingRequest): Promise<CreatorOnboardingResponse>;
     cleanupOAuthConsumer(input: {
         consumerBindingId: string;
         moduleId: string;
@@ -590,5 +608,4 @@ export declare function mapBotControlError(error: unknown): {
     status: 400 | 403 | 404 | 409;
     message: string;
 } | undefined;
-export {};
 //# sourceMappingURL=control-server.d.ts.map