@kodelyth/discord 2026.5.42 → 2026.6.1

package/src/actions/runtime.moderation.authz.test.ts

@@ -1,151 +0,0 @@
-import { PermissionFlagsBits } from "discord-api-types/v10";
-import type { DiscordActionConfig } from "klaw/plugin-sdk/config-contracts";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import { EMPTY_DISCORD_TEST_CONFIG } from "../test-support/config.js";
-import {
-  discordModerationActionRuntime,
-  handleDiscordModerationAction,
-} from "./runtime.moderation.js";
-
-const originalDiscordModerationActionRuntime = { ...discordModerationActionRuntime };
-const banMemberDiscord = vi.fn(async () => ({ ok: true }));
-const kickMemberDiscord = vi.fn(async () => ({ ok: true }));
-const timeoutMemberDiscord = vi.fn(async () => ({ id: "user-1" }));
-const hasAnyGuildPermissionDiscord = vi.fn(async () => false);
-
-const enableAllActions = (_key: keyof DiscordActionConfig, _defaultValue = true) => true;
-const DISCORD_TEST_CFG = EMPTY_DISCORD_TEST_CONFIG;
-
-function handleModerationAction(action: string, params: Record<string, unknown>) {
-  return handleDiscordModerationAction(action, params, enableAllActions, DISCORD_TEST_CFG);
-}
-
-describe("discord moderation sender authorization", () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-    Object.assign(discordModerationActionRuntime, originalDiscordModerationActionRuntime, {
-      banMemberDiscord,
-      kickMemberDiscord,
-      timeoutMemberDiscord,
-      hasAnyGuildPermissionDiscord,
-    });
-  });
-
-  it("rejects ban when sender lacks BAN_MEMBERS", async () => {
-    hasAnyGuildPermissionDiscord.mockResolvedValueOnce(false);
-
-    await expect(
-      handleModerationAction("ban", {
-        guildId: "guild-1",
-        userId: "user-1",
-        senderUserId: "sender-1",
-      }),
-    ).rejects.toThrow("required permissions");
-
-    expect(hasAnyGuildPermissionDiscord).toHaveBeenCalledWith(
-      "guild-1",
-      "sender-1",
-      [PermissionFlagsBits.BanMembers],
-      { cfg: DISCORD_TEST_CFG },
-    );
-    expect(banMemberDiscord).not.toHaveBeenCalled();
-  });
-
-  it("rejects kick when sender lacks KICK_MEMBERS", async () => {
-    hasAnyGuildPermissionDiscord.mockResolvedValueOnce(false);
-
-    await expect(
-      handleModerationAction("kick", {
-        guildId: "guild-1",
-        userId: "user-1",
-        senderUserId: "sender-1",
-      }),
-    ).rejects.toThrow("required permissions");
-
-    expect(hasAnyGuildPermissionDiscord).toHaveBeenCalledWith(
-      "guild-1",
-      "sender-1",
-      [PermissionFlagsBits.KickMembers],
-      { cfg: DISCORD_TEST_CFG },
-    );
-    expect(kickMemberDiscord).not.toHaveBeenCalled();
-  });
-
-  it("rejects timeout when sender lacks MODERATE_MEMBERS", async () => {
-    hasAnyGuildPermissionDiscord.mockResolvedValueOnce(false);
-
-    await expect(
-      handleModerationAction("timeout", {
-        guildId: "guild-1",
-        userId: "user-1",
-        senderUserId: "sender-1",
-        durationMinutes: 60,
-      }),
-    ).rejects.toThrow("required permissions");
-
-    expect(hasAnyGuildPermissionDiscord).toHaveBeenCalledWith(
-      "guild-1",
-      "sender-1",
-      [PermissionFlagsBits.ModerateMembers],
-      { cfg: DISCORD_TEST_CFG },
-    );
-    expect(timeoutMemberDiscord).not.toHaveBeenCalled();
-  });
-
-  it("executes moderation action when sender has required permission", async () => {
-    hasAnyGuildPermissionDiscord.mockResolvedValueOnce(true);
-    kickMemberDiscord.mockResolvedValueOnce({ ok: true });
-
-    await handleModerationAction("kick", {
-      guildId: "guild-1",
-      userId: "user-1",
-      senderUserId: "sender-1",
-      reason: "rule violation",
-    });
-
-    expect(hasAnyGuildPermissionDiscord).toHaveBeenCalledWith(
-      "guild-1",
-      "sender-1",
-      [PermissionFlagsBits.KickMembers],
-      { cfg: DISCORD_TEST_CFG },
-    );
-    expect(kickMemberDiscord).toHaveBeenCalledWith(
-      {
-        guildId: "guild-1",
-        userId: "user-1",
-        reason: "rule violation",
-      },
-      { cfg: DISCORD_TEST_CFG },
-    );
-  });
-
-  it("forwards accountId into permission check and moderation execution", async () => {
-    hasAnyGuildPermissionDiscord.mockResolvedValueOnce(true);
-    timeoutMemberDiscord.mockResolvedValueOnce({ id: "user-1" });
-
-    await handleModerationAction("timeout", {
-      guildId: "guild-1",
-      userId: "user-1",
-      senderUserId: "sender-1",
-      accountId: "ops",
-      durationMinutes: 5,
-    });
-
-    expect(hasAnyGuildPermissionDiscord).toHaveBeenCalledWith(
-      "guild-1",
-      "sender-1",
-      [PermissionFlagsBits.ModerateMembers],
-      { cfg: DISCORD_TEST_CFG, accountId: "ops" },
-    );
-    expect(timeoutMemberDiscord).toHaveBeenCalledWith(
-      {
-        guildId: "guild-1",
-        userId: "user-1",
-        durationMinutes: 5,
-        until: undefined,
-        reason: undefined,
-      },
-      { cfg: DISCORD_TEST_CFG, accountId: "ops" },
-    );
-  });
-});

package/src/actions/runtime.moderation.ts

@@ -1,116 +0,0 @@
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import {
-  type ActionGate,
-  jsonResult,
-  readStringParam,
-  type DiscordActionConfig,
-  type KlawConfig,
-} from "../runtime-api.js";
-import {
-  banMemberDiscord,
-  hasAnyGuildPermissionDiscord,
-  kickMemberDiscord,
-  timeoutMemberDiscord,
-} from "../send.js";
-import {
-  isDiscordModerationAction,
-  readDiscordModerationCommand,
-  requiredGuildPermissionForModerationAction,
-} from "./runtime.moderation-shared.js";
-import { createDiscordActionOptions } from "./runtime.shared.js";
-
-export const discordModerationActionRuntime = {
-  banMemberDiscord,
-  hasAnyGuildPermissionDiscord,
-  kickMemberDiscord,
-  timeoutMemberDiscord,
-};
-
-async function verifySenderModerationPermission(params: {
-  guildId: string;
-  senderUserId?: string;
-  requiredPermission: bigint;
-  accountId?: string;
-  cfg: KlawConfig;
-}) {
-  // CLI/manual flows may not have sender context; enforce only when present.
-  if (!params.senderUserId) {
-    return;
-  }
-  const hasPermission = await discordModerationActionRuntime.hasAnyGuildPermissionDiscord(
-    params.guildId,
-    params.senderUserId,
-    [params.requiredPermission],
-    createDiscordActionOptions({ cfg: params.cfg, accountId: params.accountId }),
-  );
-  if (!hasPermission) {
-    throw new Error("Sender does not have required permissions for this moderation action.");
-  }
-}
-
-export async function handleDiscordModerationAction(
-  action: string,
-  params: Record<string, unknown>,
-  isActionEnabled: ActionGate<DiscordActionConfig>,
-  cfg: KlawConfig,
-): Promise<AgentToolResult<unknown>> {
-  if (!isDiscordModerationAction(action)) {
-    throw new Error(`Unknown action: ${action}`);
-  }
-  if (!isActionEnabled("moderation", false)) {
-    throw new Error("Discord moderation is disabled.");
-  }
-  if (!cfg) {
-    throw new Error("Discord moderation actions require a resolved runtime config.");
-  }
-  const accountId = readStringParam(params, "accountId");
-  const command = readDiscordModerationCommand(action, params);
-  const senderUserId = readStringParam(params, "senderUserId");
-  const withOpts = () => createDiscordActionOptions({ cfg, accountId });
-  await verifySenderModerationPermission({
-    guildId: command.guildId,
-    senderUserId,
-    requiredPermission: requiredGuildPermissionForModerationAction(command.action),
-    accountId,
-    cfg,
-  });
-  switch (command.action) {
-    case "timeout": {
-      const member = await discordModerationActionRuntime.timeoutMemberDiscord(
-        {
-          guildId: command.guildId,
-          userId: command.userId,
-          durationMinutes: command.durationMinutes,
-          until: command.until,
-          reason: command.reason,
-        },
-        withOpts(),
-      );
-      return jsonResult({ ok: true, member });
-    }
-    case "kick": {
-      await discordModerationActionRuntime.kickMemberDiscord(
-        {
-          guildId: command.guildId,
-          userId: command.userId,
-          reason: command.reason,
-        },
-        withOpts(),
-      );
-      return jsonResult({ ok: true });
-    }
-    case "ban": {
-      await discordModerationActionRuntime.banMemberDiscord(
-        {
-          guildId: command.guildId,
-          userId: command.userId,
-          reason: command.reason,
-          deleteMessageDays: command.deleteMessageDays,
-        },
-        withOpts(),
-      );
-      return jsonResult({ ok: true });
-    }
-  }
-  throw new Error("Unsupported Discord moderation action");
-}

package/src/actions/runtime.presence.test.ts

@@ -1,165 +0,0 @@
-import type { DiscordActionConfig } from "klaw/plugin-sdk/config-contracts";
-import { beforeEach, describe, expect, it, vi } from "vitest";
-import type { GatewayPlugin } from "../internal/gateway.js";
-import { clearGateways, registerGateway } from "../monitor/gateway-registry.js";
-import type { ActionGate } from "../runtime-api.js";
-import { handleDiscordPresenceAction } from "./runtime.presence.js";
-
-const mockUpdatePresence = vi.fn();
-
-function createMockGateway(connected = true): GatewayPlugin {
-  return { isConnected: connected, updatePresence: mockUpdatePresence } as unknown as GatewayPlugin;
-}
-
-const presenceEnabled: ActionGate<DiscordActionConfig> = (key) => key === "presence";
-const presenceDisabled: ActionGate<DiscordActionConfig> = () => false;
-
-describe("handleDiscordPresenceAction", () => {
-  async function setPresence(
-    params: Record<string, unknown>,
-    actionGate: ActionGate<DiscordActionConfig> = presenceEnabled,
-  ) {
-    return await handleDiscordPresenceAction("setPresence", params, actionGate);
-  }
-
-  beforeEach(() => {
-    mockUpdatePresence.mockClear();
-    clearGateways();
-    registerGateway(undefined, createMockGateway());
-  });
-
-  it("sets playing activity", async () => {
-    const result = await handleDiscordPresenceAction(
-      "setPresence",
-      { activityType: "playing", activityName: "with fire", status: "online" },
-      presenceEnabled,
-    );
-    expect(mockUpdatePresence).toHaveBeenCalledWith({
-      since: null,
-      activities: [{ name: "with fire", type: 0 }],
-      status: "online",
-      afk: false,
-    });
-    const textBlock = result.content.find((block) => block.type === "text");
-    const payload = JSON.parse(
-      (textBlock as { type: "text"; text: string } | undefined)?.text ?? "{}",
-    );
-    expect(payload.ok).toBe(true);
-    expect(payload.activities[0]).toEqual({ type: 0, name: "with fire" });
-  });
-
-  it.each([
-    {
-      name: "streaming activity with URL",
-      params: {
-        activityType: "streaming",
-        activityName: "My Stream",
-        activityUrl: "https://twitch.tv/example",
-      },
-      expectedActivities: [{ name: "My Stream", type: 1, url: "https://twitch.tv/example" }],
-    },
-    {
-      name: "streaming activity without URL",
-      params: { activityType: "streaming", activityName: "My Stream" },
-      expectedActivities: [{ name: "My Stream", type: 1 }],
-    },
-    {
-      name: "listening activity",
-      params: { activityType: "listening", activityName: "Spotify" },
-      expectedActivities: [{ name: "Spotify", type: 2 }],
-    },
-    {
-      name: "watching activity",
-      params: { activityType: "watching", activityName: "you" },
-      expectedActivities: [{ name: "you", type: 3 }],
-    },
-    {
-      name: "custom activity using state",
-      params: { activityType: "custom", activityState: "Vibing" },
-      expectedActivities: [{ name: "", type: 4, state: "Vibing" }],
-    },
-    {
-      name: "activity with state",
-      params: { activityType: "playing", activityName: "My Game", activityState: "In the lobby" },
-      expectedActivities: [{ name: "My Game", type: 0, state: "In the lobby" }],
-    },
-    {
-      name: "default empty activity name when only type provided",
-      params: { activityType: "playing" },
-      expectedActivities: [{ name: "", type: 0 }],
-    },
-  ])("sets $name", async ({ params, expectedActivities }) => {
-    await setPresence(params);
-    expect(mockUpdatePresence).toHaveBeenCalledWith({
-      since: null,
-      activities: expectedActivities,
-      status: "online",
-      afk: false,
-    });
-  });
-
-  it("sets status-only without activity", async () => {
-    await setPresence({ status: "idle" });
-    expect(mockUpdatePresence).toHaveBeenCalledWith({
-      since: null,
-      activities: [],
-      status: "idle",
-      afk: false,
-    });
-  });
-
-  it.each([
-    { name: "invalid status", params: { status: "offline" }, expectedMessage: /Invalid status/ },
-    {
-      name: "invalid activity type",
-      params: { activityType: "invalid" },
-      expectedMessage: /Invalid activityType/,
-    },
-  ])("rejects $name", async ({ params, expectedMessage }) => {
-    await expect(setPresence(params)).rejects.toThrow(expectedMessage);
-  });
-
-  it("defaults status to online", async () => {
-    await setPresence({ activityType: "playing", activityName: "test" });
-    expect(mockUpdatePresence).toHaveBeenCalledWith({
-      since: null,
-      activities: [{ name: "test", type: 0 }],
-      status: "online",
-      afk: false,
-    });
-  });
-
-  it("respects presence gating", async () => {
-    await expect(setPresence({ status: "online" }, presenceDisabled)).rejects.toThrow(/disabled/);
-  });
-
-  it("errors when gateway is not registered", async () => {
-    clearGateways();
-    await expect(setPresence({ status: "dnd" })).rejects.toThrow(/not available/);
-  });
-
-  it("errors when gateway is not connected", async () => {
-    clearGateways();
-    registerGateway(undefined, createMockGateway(false));
-    await expect(setPresence({ status: "dnd" })).rejects.toThrow(/not connected/);
-  });
-
-  it("uses accountId to resolve gateway", async () => {
-    const accountGateway = createMockGateway();
-    registerGateway("my-account", accountGateway);
-    await setPresence({ accountId: "my-account", activityType: "playing", activityName: "test" });
-    expect(mockUpdatePresence).toHaveBeenCalled();
-  });
-
-  it("requires activityType when activityName is provided", async () => {
-    await expect(setPresence({ activityName: "My Game" })).rejects.toThrow(
-      /activityType is required/,
-    );
-  });
-
-  it("rejects unknown presence actions", async () => {
-    await expect(handleDiscordPresenceAction("unknownAction", {}, presenceEnabled)).rejects.toThrow(
-      /Unknown presence action/,
-    );
-  });
-});

package/src/actions/runtime.presence.ts

@@ -1,117 +0,0 @@
-import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import { normalizeLowercaseStringOrEmpty } from "klaw/plugin-sdk/string-coerce-runtime";
-import type { Activity, UpdatePresenceData } from "../internal/gateway.js";
-import { getGateway } from "../monitor/gateway-registry.js";
-import {
-  type ActionGate,
-  jsonResult,
-  readStringParam,
-  type DiscordActionConfig,
-} from "../runtime-api.js";
-
-const ACTIVITY_TYPE_MAP: Record<string, number> = {
-  playing: 0,
-  streaming: 1,
-  listening: 2,
-  watching: 3,
-  custom: 4,
-  competing: 5,
-};
-
-const VALID_STATUSES = new Set(["online", "dnd", "idle", "invisible"]);
-
-export async function handleDiscordPresenceAction(
-  action: string,
-  params: Record<string, unknown>,
-  isActionEnabled: ActionGate<DiscordActionConfig>,
-): Promise<AgentToolResult<unknown>> {
-  if (action !== "setPresence") {
-    throw new Error(`Unknown presence action: ${action}`);
-  }
-
-  if (!isActionEnabled("presence", false)) {
-    throw new Error("Discord presence changes are disabled.");
-  }
-
-  const accountId = readStringParam(params, "accountId");
-  const gateway = getGateway(accountId);
-  if (!gateway) {
-    throw new Error(
-      `Discord gateway not available${accountId ? ` for account "${accountId}"` : ""}. The bot may not be connected.`,
-    );
-  }
-  if (!gateway.isConnected) {
-    throw new Error(
-      `Discord gateway is not connected${accountId ? ` for account "${accountId}"` : ""}.`,
-    );
-  }
-
-  const statusRaw = readStringParam(params, "status") ?? "online";
-  if (!VALID_STATUSES.has(statusRaw)) {
-    throw new Error(
-      `Invalid status "${statusRaw}". Must be one of: ${[...VALID_STATUSES].join(", ")}`,
-    );
-  }
-  const status = statusRaw as UpdatePresenceData["status"];
-
-  const activityTypeRaw = readStringParam(params, "activityType");
-  const activityName = readStringParam(params, "activityName");
-
-  const activities: Activity[] = [];
-
-  if (activityTypeRaw || activityName) {
-    if (!activityTypeRaw) {
-      throw new Error(
-        "activityType is required when activityName is provided. " +
-          `Valid types: ${Object.keys(ACTIVITY_TYPE_MAP).join(", ")}`,
-      );
-    }
-    const typeNum = ACTIVITY_TYPE_MAP[normalizeLowercaseStringOrEmpty(activityTypeRaw)];
-    if (typeNum === undefined) {
-      throw new Error(
-        `Invalid activityType "${activityTypeRaw}". Must be one of: ${Object.keys(ACTIVITY_TYPE_MAP).join(", ")}`,
-      );
-    }
-
-    const activity: Activity = {
-      name: activityName ?? "",
-      type: typeNum,
-    };
-
-    // Streaming URL (Twitch/YouTube). May not render for bots but is the correct payload shape.
-    if (typeNum === 1) {
-      const url = readStringParam(params, "activityUrl");
-      if (url) {
-        activity.url = url;
-      }
-    }
-
-    const state = readStringParam(params, "activityState");
-    if (state) {
-      activity.state = state;
-    }
-
-    activities.push(activity);
-  }
-
-  const presenceData: UpdatePresenceData = {
-    since: null,
-    activities,
-    status,
-    afk: false,
-  };
-
-  gateway.updatePresence(presenceData);
-
-  return jsonResult({
-    ok: true,
-    status,
-    activities: activities.map((a) =>
-      Object.assign(
-        { type: a.type, name: a.name },
-        a.url ? { url: a.url } : {},
-        a.state ? { state: a.state } : {},
-      ),
-    ),
-  });
-}

package/src/actions/runtime.shared.ts

@@ -1,86 +0,0 @@
-import { parseAvailableTags, readNumberParam, readStringParam } from "../runtime-api.js";
-import type { KlawConfig } from "../runtime-api.js";
-import type {
-  DiscordChannelCreate,
-  DiscordChannelEdit,
-  DiscordChannelMove,
-} from "../send.types.js";
-
-export function readDiscordParentIdParam(
-  params: Record<string, unknown>,
-): string | null | undefined {
-  if (params.clearParent === true) {
-    return null;
-  }
-  if (params.parentId === null) {
-    return null;
-  }
-  return readStringParam(params, "parentId");
-}
-
-function readDiscordBooleanParam(
-  params: Record<string, unknown>,
-  key: string,
-): boolean | undefined {
-  return typeof params[key] === "boolean" ? params[key] : undefined;
-}
-
-export function createDiscordActionOptions<
-  T extends Record<string, unknown> = Record<string, never>,
->(params: {
-  cfg: KlawConfig;
-  accountId?: string;
-  extra?: T;
-}): { cfg: KlawConfig; accountId?: string } & T {
-  return {
-    cfg: params.cfg,
-    ...(params.accountId ? { accountId: params.accountId } : {}),
-    ...(params.extra ?? ({} as T)),
-  };
-}
-
-export function readDiscordChannelCreateParams(
-  params: Record<string, unknown>,
-): DiscordChannelCreate {
-  const parentId = readDiscordParentIdParam(params);
-  return {
-    guildId: readStringParam(params, "guildId", { required: true }),
-    name: readStringParam(params, "name", { required: true }),
-    type:
-      readNumberParam(params, "channelType", { integer: true }) ??
-      readNumberParam(params, "type", { integer: true }) ??
-      undefined,
-    parentId: parentId ?? undefined,
-    topic: readStringParam(params, "topic") ?? undefined,
-    position: readNumberParam(params, "position", { integer: true }) ?? undefined,
-    nsfw: readDiscordBooleanParam(params, "nsfw"),
-  };
-}
-
-export function readDiscordChannelEditParams(params: Record<string, unknown>): DiscordChannelEdit {
-  const parentId = readDiscordParentIdParam(params);
-  return {
-    channelId: readStringParam(params, "channelId", { required: true }),
-    name: readStringParam(params, "name") ?? undefined,
-    topic: readStringParam(params, "topic") ?? undefined,
-    position: readNumberParam(params, "position", { integer: true }) ?? undefined,
-    parentId: parentId === undefined ? undefined : parentId,
-    nsfw: readDiscordBooleanParam(params, "nsfw"),
-    rateLimitPerUser: readNumberParam(params, "rateLimitPerUser", { integer: true }) ?? undefined,
-    archived: readDiscordBooleanParam(params, "archived"),
-    locked: readDiscordBooleanParam(params, "locked"),
-    autoArchiveDuration:
-      readNumberParam(params, "autoArchiveDuration", { integer: true }) ?? undefined,
-    availableTags: parseAvailableTags(params.availableTags),
-  };
-}
-
-export function readDiscordChannelMoveParams(params: Record<string, unknown>): DiscordChannelMove {
-  const parentId = readDiscordParentIdParam(params);
-  return {
-    guildId: readStringParam(params, "guildId", { required: true }),
-    channelId: readStringParam(params, "channelId", { required: true }),
-    parentId: parentId === undefined ? undefined : parentId,
-    position: readNumberParam(params, "position", { integer: true }) ?? undefined,
-  };
-}