@gakr-gakr/discord 0.1.0

package/src/actions/runtime.moderation.ts

@@ -0,0 +1,116 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import {
+  type ActionGate,
+  jsonResult,
+  readStringParam,
+  type DiscordActionConfig,
+  type AutoBotConfig,
+} 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: AutoBotConfig;
+}) {
+  // 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: AutoBotConfig,
+): 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.ts

@@ -0,0 +1,117 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { normalizeLowercaseStringOrEmpty } from "autobot/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

@@ -0,0 +1,86 @@
+import { parseAvailableTags, readNumberParam, readStringParam } from "../runtime-api.js";
+import type { AutoBotConfig } 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: AutoBotConfig;
+  accountId?: string;
+  extra?: T;
+}): { cfg: AutoBotConfig; 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,
+  };
+}

package/src/actions/runtime.ts

@@ -0,0 +1,87 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import { createDiscordActionGate } from "../accounts.js";
+import { readStringParam, type AutoBotConfig } from "../runtime-api.js";
+import { handleDiscordGuildAction } from "./runtime.guild.js";
+import { handleDiscordMessagingAction } from "./runtime.messaging.js";
+import { handleDiscordModerationAction } from "./runtime.moderation.js";
+import { handleDiscordPresenceAction } from "./runtime.presence.js";
+
+const messagingActions = new Set([
+  "react",
+  "reactions",
+  "sticker",
+  "poll",
+  "permissions",
+  "fetchMessage",
+  "readMessages",
+  "sendMessage",
+  "editMessage",
+  "deleteMessage",
+  "threadCreate",
+  "threadList",
+  "threadReply",
+  "pinMessage",
+  "unpinMessage",
+  "listPins",
+  "searchMessages",
+]);
+
+const guildActions = new Set([
+  "memberInfo",
+  "roleInfo",
+  "emojiList",
+  "emojiUpload",
+  "stickerUpload",
+  "roleAdd",
+  "roleRemove",
+  "channelInfo",
+  "channelList",
+  "voiceStatus",
+  "eventList",
+  "eventCreate",
+  "channelCreate",
+  "channelEdit",
+  "channelDelete",
+  "channelMove",
+  "categoryCreate",
+  "categoryEdit",
+  "categoryDelete",
+  "channelPermissionSet",
+  "channelPermissionRemove",
+]);
+
+const moderationActions = new Set(["timeout", "kick", "ban"]);
+
+const presenceActions = new Set(["setPresence"]);
+
+export async function handleDiscordAction(
+  params: Record<string, unknown>,
+  cfg: AutoBotConfig,
+  options?: {
+    mediaAccess?: {
+      localRoots?: readonly string[];
+      readFile?: (filePath: string) => Promise<Buffer>;
+      workspaceDir?: string;
+    };
+    mediaLocalRoots?: readonly string[];
+    mediaReadFile?: (filePath: string) => Promise<Buffer>;
+  },
+): Promise<AgentToolResult<unknown>> {
+  const action = readStringParam(params, "action", { required: true });
+  const accountId = readStringParam(params, "accountId");
+  const isActionEnabled = createDiscordActionGate({ cfg, accountId });
+
+  if (messagingActions.has(action)) {
+    return await handleDiscordMessagingAction(action, params, isActionEnabled, cfg, options);
+  }
+  if (guildActions.has(action)) {
+    return await handleDiscordGuildAction(action, params, isActionEnabled, cfg, options);
+  }
+  if (moderationActions.has(action)) {
+    return await handleDiscordModerationAction(action, params, isActionEnabled, cfg);
+  }
+  if (presenceActions.has(action)) {
+    return await handleDiscordPresenceAction(action, params, isActionEnabled);
+  }
+  throw new Error(`Unknown action: ${action}`);
+}

package/src/api.ts

@@ -0,0 +1,219 @@
+import { resolveFetch } from "autobot/plugin-sdk/fetch-runtime";
+import {
+  resolveRetryConfig,
+  retryAsync,
+  type RetryConfig,
+} from "autobot/plugin-sdk/retry-runtime";
+import { isDiscordHtmlResponseBody, summarizeDiscordResponseBody } from "./error-body.js";
+
+const DISCORD_API_BASE = "https://discord.com/api/v10";
+const DISCORD_API_RETRY_DEFAULTS = {
+  attempts: 3,
+  minDelayMs: 500,
+  maxDelayMs: 5 * 60_000,
+  jitter: 0.1,
+};
+const DISCORD_API_429_FALLBACK_RETRY_AFTER_SECONDS = 60;
+
+type DiscordApiErrorPayload = {
+  message?: string;
+  retry_after?: number;
+  code?: number;
+  global?: boolean;
+};
+
+function parseDiscordApiErrorPayload(text: string): DiscordApiErrorPayload | null {
+  const trimmed = text.trim();
+  if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) {
+    return null;
+  }
+  try {
+    const payload = JSON.parse(trimmed);
+    if (payload && typeof payload === "object") {
+      return payload as DiscordApiErrorPayload;
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function parseRetryAfterSeconds(text: string, response: Response): number | undefined {
+  const payload = parseDiscordApiErrorPayload(text);
+  const retryAfter =
+    payload && typeof payload.retry_after === "number" && Number.isFinite(payload.retry_after)
+      ? payload.retry_after
+      : undefined;
+  if (retryAfter !== undefined) {
+    return retryAfter;
+  }
+  const header = response.headers.get("Retry-After");
+  if (!header) {
+    return undefined;
+  }
+  const parsed = Number(header);
+  if (Number.isFinite(parsed) && parsed >= 0) {
+    return parsed;
+  }
+  const retryAt = Date.parse(header);
+  if (!Number.isFinite(retryAt)) {
+    return undefined;
+  }
+  return Math.max(0, (retryAt - Date.now()) / 1000);
+}
+
+function formatRetryAfterSeconds(value: number | undefined): string | undefined {
+  if (value === undefined || !Number.isFinite(value) || value < 0) {
+    return undefined;
+  }
+  const rounded = value < 10 ? value.toFixed(1) : Math.round(value).toString();
+  return `${rounded}s`;
+}
+
+function formatDiscordApiErrorText(text: string, response: Response): string | undefined {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return undefined;
+  }
+  const payload = parseDiscordApiErrorPayload(trimmed);
+  if (!payload) {
+    const looksJson = trimmed.startsWith("{") && trimmed.endsWith("}");
+    if (looksJson) {
+      return "unknown error";
+    }
+    const summary = summarizeDiscordResponseBody(trimmed);
+    if (isDiscordHtmlResponseBody(trimmed, response.headers.get("content-type"))) {
+      if (!summary) {
+        return response.status === 429 ? "rate limited by Discord upstream" : undefined;
+      }
+      return response.status === 429 ? `rate limited by Discord upstream: ${summary}` : summary;
+    }
+    return summary;
+  }
+  const message =
+    typeof payload.message === "string" && payload.message.trim()
+      ? payload.message.trim()
+      : "unknown error";
+  const retryAfter = formatRetryAfterSeconds(
+    typeof payload.retry_after === "number" ? payload.retry_after : undefined,
+  );
+  return retryAfter ? `${message} (retry after ${retryAfter})` : message;
+}
+
+export class DiscordApiError extends Error {
+  status: number;
+  retryAfter?: number;
+
+  constructor(message: string, status: number, retryAfter?: number) {
+    super(message);
+    this.status = status;
+    this.retryAfter = retryAfter;
+  }
+}
+
+function getDiscordApiRetryAfterMs(
+  err: unknown,
+  retryConfig: Required<RetryConfig>,
+): number | undefined {
+  if (!(err instanceof DiscordApiError) || typeof err.retryAfter !== "number") {
+    return undefined;
+  }
+  return Math.min(Math.max(0, err.retryAfter * 1000), retryConfig.maxDelayMs);
+}
+
+type DiscordFetchOptions = {
+  retry?: RetryConfig;
+  label?: string;
+};
+
+type DiscordApiRequestOptions = DiscordFetchOptions & {
+  body?: unknown;
+  fetcher?: typeof fetch;
+  headers?: Record<string, string>;
+  method?: string;
+  signal?: AbortSignal;
+  timeoutMs?: number;
+};
+
+function normalizeDiscordRequestBody(body: unknown, headers: Headers): BodyInit | null | undefined {
+  if (body === undefined) {
+    return undefined;
+  }
+  if (
+    typeof body === "string" ||
+    body instanceof Blob ||
+    body instanceof FormData ||
+    body instanceof URLSearchParams ||
+    body instanceof ArrayBuffer
+  ) {
+    return body;
+  }
+  headers.set("Content-Type", headers.get("Content-Type") ?? "application/json");
+  return JSON.stringify(body);
+}
+
+function resolveDiscordRequestSignal(options: DiscordApiRequestOptions) {
+  if (options.signal || typeof options.timeoutMs !== "number") {
+    return options.signal;
+  }
+  return AbortSignal.timeout(options.timeoutMs);
+}
+
+export async function requestDiscord<T>(
+  path: string,
+  token: string,
+  options?: DiscordApiRequestOptions,
+): Promise<T> {
+  const fetchImpl = resolveFetch(options?.fetcher ?? fetch);
+  if (!fetchImpl) {
+    throw new Error("fetch is not available");
+  }
+
+  const retryConfig = resolveRetryConfig(DISCORD_API_RETRY_DEFAULTS, options?.retry);
+  return retryAsync(
+    async () => {
+      const headers = new Headers(options?.headers);
+      headers.set("Authorization", `Bot ${token}`);
+      const body = normalizeDiscordRequestBody(options?.body, headers);
+      const res = await fetchImpl(`${DISCORD_API_BASE}${path}`, {
+        method: options?.method ?? (body === undefined ? "GET" : "POST"),
+        headers,
+        body,
+        signal: resolveDiscordRequestSignal(options ?? {}),
+      });
+      const text = await res.text().catch(() => "");
+      if (!res.ok) {
+        const detail = formatDiscordApiErrorText(text, res);
+        const suffix = detail ? `: ${detail}` : "";
+        const retryAfter =
+          res.status === 429
+            ? (parseRetryAfterSeconds(text, res) ?? DISCORD_API_429_FALLBACK_RETRY_AFTER_SECONDS)
+            : undefined;
+        throw new DiscordApiError(
+          `Discord API ${path} failed (${res.status})${suffix}`,
+          res.status,
+          retryAfter,
+        );
+      }
+      if (!text.trim()) {
+        return undefined as T;
+      }
+      return JSON.parse(text) as T;
+    },
+    {
+      ...retryConfig,
+      label: options?.label ?? path,
+      shouldRetry: (err) => err instanceof DiscordApiError && err.status === 429,
+      retryAfterMs: (err) => getDiscordApiRetryAfterMs(err, retryConfig),
+    },
+  );
+}
+
+export async function fetchDiscord<T>(
+  path: string,
+  token: string,
+  fetcher: typeof fetch = fetch,
+  options?: DiscordFetchOptions,
+): Promise<T> {
+  return await requestDiscord<T>(path, token, { ...options, fetcher, method: "GET" });
+}