@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/group-policy.ts

@@ -0,0 +1,113 @@
+import type { ChannelGroupContext } from "klaw/plugin-sdk/channel-contract";
+import {
+  resolveToolsBySender,
+  type GroupToolPolicyBySenderConfig,
+  type GroupToolPolicyConfig,
+} from "klaw/plugin-sdk/channel-policy";
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+import { normalizeAtHashSlug } from "klaw/plugin-sdk/string-normalization-runtime";
+import type { DiscordConfig } from "./runtime-api.js";
+
+function normalizeDiscordSlug(value?: string | null) {
+  return normalizeAtHashSlug(value);
+}
+
+type SenderScopedToolsEntry = {
+  tools?: GroupToolPolicyConfig;
+  toolsBySender?: GroupToolPolicyBySenderConfig;
+  requireMention?: boolean;
+};
+
+function resolveDiscordGuildEntry(guilds: DiscordConfig["guilds"], groupSpace?: string | null) {
+  if (!guilds || Object.keys(guilds).length === 0) {
+    return null;
+  }
+  const space = normalizeOptionalString(groupSpace) ?? "";
+  if (space && guilds[space]) {
+    return guilds[space];
+  }
+  const normalized = normalizeDiscordSlug(space);
+  if (normalized && guilds[normalized]) {
+    return guilds[normalized];
+  }
+  if (normalized) {
+    const match = Object.values(guilds).find(
+      (entry) => normalizeDiscordSlug(entry?.slug ?? undefined) === normalized,
+    );
+    if (match) {
+      return match;
+    }
+  }
+  return guilds["*"] ?? null;
+}
+
+function resolveDiscordChannelEntry<TEntry extends SenderScopedToolsEntry>(
+  channelEntries: Record<string, TEntry> | undefined,
+  params: { groupId?: string | null; groupChannel?: string | null },
+): TEntry | undefined {
+  if (!channelEntries || Object.keys(channelEntries).length === 0) {
+    return undefined;
+  }
+  const groupChannel = params.groupChannel;
+  const channelSlug = normalizeDiscordSlug(groupChannel);
+  return (
+    (params.groupId ? channelEntries[params.groupId] : undefined) ??
+    (channelSlug
+      ? (channelEntries[channelSlug] ?? channelEntries[`#${channelSlug}`])
+      : undefined) ??
+    (groupChannel ? channelEntries[normalizeDiscordSlug(groupChannel)] : undefined)
+  );
+}
+
+function resolveSenderToolsEntry(
+  entry: SenderScopedToolsEntry | undefined | null,
+  params: ChannelGroupContext,
+): GroupToolPolicyConfig | undefined {
+  if (!entry) {
+    return undefined;
+  }
+  const senderPolicy = resolveToolsBySender({
+    toolsBySender: entry.toolsBySender,
+    senderId: params.senderId,
+    senderName: params.senderName,
+    senderUsername: params.senderUsername,
+    senderE164: params.senderE164,
+  });
+  return senderPolicy ?? entry.tools;
+}
+
+function resolveDiscordPolicyContext(params: ChannelGroupContext) {
+  const guilds =
+    (params.accountId
+      ? params.cfg.channels?.discord?.accounts?.[params.accountId]?.guilds
+      : undefined) ?? params.cfg.channels?.discord?.guilds;
+  const guildEntry = resolveDiscordGuildEntry(guilds, params.groupSpace);
+  const channelEntries = guildEntry?.channels;
+  const channelEntry =
+    channelEntries && Object.keys(channelEntries).length > 0
+      ? resolveDiscordChannelEntry(channelEntries, params)
+      : undefined;
+  return { guildEntry, channelEntry };
+}
+
+export function resolveDiscordGroupRequireMention(params: ChannelGroupContext): boolean {
+  const context = resolveDiscordPolicyContext(params);
+  if (typeof context.channelEntry?.requireMention === "boolean") {
+    return context.channelEntry.requireMention;
+  }
+  if (typeof context.guildEntry?.requireMention === "boolean") {
+    return context.guildEntry.requireMention;
+  }
+  return true;
+}
+
+export function resolveDiscordGroupToolPolicy(
+  params: ChannelGroupContext,
+): GroupToolPolicyConfig | undefined {
+  const context = resolveDiscordPolicyContext(params);
+  const channelPolicy = resolveSenderToolsEntry(context.channelEntry, params);
+  if (channelPolicy) {
+    return channelPolicy;
+  }
+  return resolveSenderToolsEntry(context.guildEntry, params);
+}

package/src/guilds.ts

@@ -0,0 +1,29 @@
+import { fetchDiscord } from "./api.js";
+import { normalizeDiscordSlug } from "./monitor/allow-list.js";
+
+export type DiscordGuildSummary = {
+  id: string;
+  name: string;
+  slug: string;
+};
+
+export async function listGuilds(
+  token: string,
+  fetcher: typeof fetch,
+): Promise<DiscordGuildSummary[]> {
+  const raw = await fetchDiscord<Array<{ id?: string; name?: string }>>(
+    "/users/@me/guilds",
+    token,
+    fetcher,
+  );
+  return raw
+    .filter(
+      (guild): guild is { id: string; name: string } =>
+        typeof guild.id === "string" && typeof guild.name === "string",
+    )
+    .map((guild) => ({
+      id: guild.id,
+      name: guild.name,
+      slug: normalizeDiscordSlug(guild.name),
+    }));
+}

package/src/inbound-context.contract.test.ts

@@ -0,0 +1,11 @@
+import { expectChannelInboundContextContract } from "klaw/plugin-sdk/channel-contract-testing";
+import { describe, it } from "vitest";
+import { buildFinalizedDiscordDirectInboundContext } from "./monitor/inbound-context.test-helpers.js";
+
+describe("Discord inbound context contract", () => {
+  it("keeps inbound context finalized", () => {
+    const ctx = buildFinalizedDiscordDirectInboundContext();
+
+    expectChannelInboundContextContract(ctx);
+  });
+});

package/src/inbound-event-delivery.ts

@@ -0,0 +1,135 @@
+import type { ReplyPayload } from "klaw/plugin-sdk/reply-payload";
+
+export type DiscordInboundEventDeliveryEnd = () => void;
+
+type ActiveEvent = {
+  outboundTo: string;
+  outboundAccountId?: string;
+  markInboundEventDelivered: () => void;
+};
+
+const DISCORD_INBOUND_EVENT_DELIVERY_KEY = "__klawInboundEventDelivery";
+const registry = new Map<string, ActiveEvent>();
+
+function normalizeDiscordDeliveryTarget(value: string): string {
+  return value
+    .trim()
+    .replace(/^discord:/iu, "")
+    .replace(/^channel:/iu, "")
+    .toLowerCase();
+}
+
+function resolveDiscordInboundEventDeliveryCorrelationKey(
+  sessionKey: string | undefined,
+  inboundEventKind?: string,
+): string | undefined {
+  const key = sessionKey?.trim();
+  if (!key) {
+    return undefined;
+  }
+  return inboundEventKind === "room_event" ? `${key}:room_event` : key;
+}
+
+export function beginDiscordInboundEventDeliveryCorrelation(
+  sessionKey: string | undefined,
+  event: ActiveEvent,
+  options?: { inboundEventKind?: string },
+): DiscordInboundEventDeliveryEnd {
+  const key = resolveDiscordInboundEventDeliveryCorrelationKey(
+    sessionKey,
+    options?.inboundEventKind,
+  );
+  if (!key) {
+    return () => {};
+  }
+  registry.set(key, event);
+  return () => {
+    if (registry.get(key) === event) {
+      registry.delete(key);
+    }
+  };
+}
+
+export function notifyDiscordInboundEventOutboundSuccess(params: {
+  sessionKey: string | undefined;
+  to: string;
+  accountId?: string | null;
+  inboundEventKind?: string;
+}): void {
+  const key = resolveDiscordInboundEventDeliveryCorrelationKey(
+    params.sessionKey,
+    params.inboundEventKind,
+  );
+  if (!key) {
+    return;
+  }
+  const event = registry.get(key);
+  if (
+    !event ||
+    normalizeDiscordDeliveryTarget(event.outboundTo) !== normalizeDiscordDeliveryTarget(params.to)
+  ) {
+    return;
+  }
+  if (event.outboundAccountId && params.accountId && params.accountId !== event.outboundAccountId) {
+    return;
+  }
+  registry.delete(key);
+  event.markInboundEventDelivered();
+}
+
+function readRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+export function withDiscordInboundEventDeliveryMetadata(
+  payload: ReplyPayload,
+  params: {
+    sessionKey?: string | null;
+    inboundEventKind?: string;
+  },
+): ReplyPayload {
+  const sessionKey = params.sessionKey?.trim();
+  if (!sessionKey || params.inboundEventKind !== "room_event") {
+    return payload;
+  }
+  const channelData = readRecord(payload.channelData) ?? {};
+  const discordData = readRecord(channelData.discord) ?? {};
+  return {
+    ...payload,
+    channelData: {
+      ...channelData,
+      discord: {
+        ...discordData,
+        [DISCORD_INBOUND_EVENT_DELIVERY_KEY]: {
+          sessionKey,
+          inboundEventKind: params.inboundEventKind,
+        },
+      },
+    },
+  };
+}
+
+export function notifyDiscordInboundEventOutboundPayloadSuccess(params: {
+  payload: ReplyPayload;
+  to: string;
+  accountId?: string | null;
+}): void {
+  const channelData = readRecord(params.payload.channelData);
+  const discordData = readRecord(channelData?.discord);
+  const metadata = readRecord(discordData?.[DISCORD_INBOUND_EVENT_DELIVERY_KEY]);
+  if (!metadata) {
+    return;
+  }
+  notifyDiscordInboundEventOutboundSuccess({
+    sessionKey: readString(metadata.sessionKey),
+    inboundEventKind: readString(metadata.inboundEventKind),
+    to: params.to,
+    accountId: params.accountId,
+  });
+}

package/src/interactive-dispatch.ts

@@ -0,0 +1,104 @@
+import type { ChannelStructuredComponents } from "klaw/plugin-sdk/channel-contract";
+import {
+  createInteractiveConversationBindingHelpers,
+  dispatchPluginInteractiveHandler,
+  type PluginConversationBinding,
+  type PluginConversationBindingRequestParams,
+  type PluginConversationBindingRequestResult,
+  type PluginInteractiveRegistration,
+} from "klaw/plugin-sdk/plugin-runtime";
+
+export type DiscordInteractiveHandlerContext = {
+  channel: "discord";
+  accountId: string;
+  interactionId: string;
+  conversationId: string;
+  parentConversationId?: string;
+  guildId?: string;
+  senderId?: string;
+  senderUsername?: string;
+  auth: {
+    isAuthorizedSender: boolean;
+  };
+  interaction: {
+    kind: "button" | "select" | "modal";
+    data: string;
+    namespace: string;
+    payload: string;
+    messageId?: string;
+    values?: string[];
+    fields?: Array<{ id: string; name: string; values: string[] }>;
+  };
+  respond: {
+    acknowledge: () => Promise<void>;
+    reply: (params: { text: string; ephemeral?: boolean }) => Promise<void>;
+    followUp: (params: { text: string; ephemeral?: boolean }) => Promise<void>;
+    editMessage: (params: {
+      text?: string;
+      components?: ChannelStructuredComponents;
+    }) => Promise<void>;
+    clearComponents: (params?: { text?: string }) => Promise<void>;
+  };
+  requestConversationBinding: (
+    params?: PluginConversationBindingRequestParams,
+  ) => Promise<PluginConversationBindingRequestResult>;
+  detachConversationBinding: () => Promise<{ removed: boolean }>;
+  getCurrentConversationBinding: () => Promise<PluginConversationBinding | null>;
+};
+
+export type DiscordInteractiveHandlerRegistration = PluginInteractiveRegistration<
+  DiscordInteractiveHandlerContext,
+  "discord"
+>;
+
+type DiscordInteractiveDispatchContext = Omit<
+  DiscordInteractiveHandlerContext,
+  | "interaction"
+  | "respond"
+  | "channel"
+  | "requestConversationBinding"
+  | "detachConversationBinding"
+  | "getCurrentConversationBinding"
+> & {
+  interaction: Omit<
+    DiscordInteractiveHandlerContext["interaction"],
+    "data" | "namespace" | "payload"
+  >;
+};
+
+export async function dispatchDiscordPluginInteractiveHandler(params: {
+  data: string;
+  interactionId: string;
+  ctx: DiscordInteractiveDispatchContext;
+  respond: DiscordInteractiveHandlerContext["respond"];
+  onMatched?: () => Promise<void> | void;
+}) {
+  return await dispatchPluginInteractiveHandler<DiscordInteractiveHandlerRegistration>({
+    channel: "discord",
+    data: params.data,
+    dedupeId: params.interactionId,
+    onMatched: params.onMatched,
+    invoke: ({ registration, namespace, payload }) =>
+      registration.handler({
+        ...params.ctx,
+        channel: "discord",
+        interaction: {
+          ...params.ctx.interaction,
+          data: params.data,
+          namespace,
+          payload,
+        },
+        respond: params.respond,
+        ...createInteractiveConversationBindingHelpers({
+          registration,
+          senderId: params.ctx.senderId,
+          conversation: {
+            channel: "discord",
+            accountId: params.ctx.accountId,
+            conversationId: params.ctx.conversationId,
+            parentConversationId: params.ctx.parentConversationId,
+          },
+        }),
+      }),
+  });
+}

package/src/internal/api.commands.ts

@@ -0,0 +1,51 @@
+import { Routes, type APIApplicationCommand } from "discord-api-types/v10";
+import type { RequestClient } from "./rest.js";
+
+export async function listApplicationCommands(
+  rest: RequestClient,
+  clientId: string,
+): Promise<APIApplicationCommand[]> {
+  return (await rest.get(Routes.applicationCommands(clientId))) as APIApplicationCommand[];
+}
+
+export async function createApplicationCommand(
+  rest: RequestClient,
+  clientId: string,
+  body: unknown,
+): Promise<unknown> {
+  return await rest.post(Routes.applicationCommands(clientId), { body });
+}
+
+export async function editApplicationCommand(
+  rest: RequestClient,
+  clientId: string,
+  commandId: string,
+  body: unknown,
+): Promise<unknown> {
+  return await rest.patch(Routes.applicationCommand(clientId, commandId), { body });
+}
+
+export async function deleteApplicationCommand(
+  rest: RequestClient,
+  clientId: string,
+  commandId: string,
+): Promise<void> {
+  await rest.delete(Routes.applicationCommand(clientId, commandId));
+}
+
+export async function overwriteApplicationCommands(
+  rest: RequestClient,
+  clientId: string,
+  body: unknown,
+): Promise<void> {
+  await rest.put(Routes.applicationCommands(clientId), { body });
+}
+
+export async function overwriteGuildApplicationCommands(
+  rest: RequestClient,
+  clientId: string,
+  guildId: string,
+  body: unknown,
+): Promise<void> {
+  await rest.put(Routes.applicationGuildCommands(clientId, guildId), { body });
+}

package/src/internal/api.guild.ts

@@ -0,0 +1,164 @@
+import {
+  Routes,
+  type APIChannel,
+  type APIGuild,
+  type APIGuildMember,
+  type APIGuildScheduledEvent,
+  type APIRole,
+  type APIVoiceState,
+  type RESTPostAPIGuildScheduledEventJSONBody,
+} from "discord-api-types/v10";
+import type { RequestClient, RequestData } from "./rest.js";
+
+export async function getGuild(rest: RequestClient, guildId: string): Promise<APIGuild> {
+  return (await rest.get(Routes.guild(guildId))) as APIGuild;
+}
+
+export async function createGuildChannel(
+  rest: RequestClient,
+  guildId: string,
+  data: RequestData,
+): Promise<APIChannel> {
+  return (await rest.post(Routes.guildChannels(guildId), data)) as APIChannel;
+}
+
+export async function moveGuildChannels(
+  rest: RequestClient,
+  guildId: string,
+  data: RequestData,
+): Promise<void> {
+  await rest.patch(Routes.guildChannels(guildId), data);
+}
+
+export async function getGuildMember(
+  rest: RequestClient,
+  guildId: string,
+  userId: string,
+): Promise<APIGuildMember> {
+  return (await rest.get(Routes.guildMember(guildId, userId))) as APIGuildMember;
+}
+
+export async function listGuildRoles(rest: RequestClient, guildId: string): Promise<APIRole[]> {
+  return (await rest.get(Routes.guildRoles(guildId))) as APIRole[];
+}
+
+export async function listGuildChannels(
+  rest: RequestClient,
+  guildId: string,
+): Promise<APIChannel[]> {
+  return (await rest.get(Routes.guildChannels(guildId))) as APIChannel[];
+}
+
+export async function putChannelPermission(
+  rest: RequestClient,
+  channelId: string,
+  targetId: string,
+  data: RequestData,
+): Promise<void> {
+  await rest.put(Routes.channelPermission(channelId, targetId), data);
+}
+
+export async function deleteChannelPermission(
+  rest: RequestClient,
+  channelId: string,
+  targetId: string,
+): Promise<void> {
+  await rest.delete(Routes.channelPermission(channelId, targetId));
+}
+
+export async function listGuildActiveThreads(
+  rest: RequestClient,
+  guildId: string,
+): Promise<unknown> {
+  return await rest.get(Routes.guildActiveThreads(guildId));
+}
+
+export async function getGuildVoiceState(
+  rest: RequestClient,
+  guildId: string,
+  userId: string,
+): Promise<APIVoiceState> {
+  return (await rest.get(Routes.guildVoiceState(guildId, userId))) as APIVoiceState;
+}
+
+export async function listGuildScheduledEvents(
+  rest: RequestClient,
+  guildId: string,
+): Promise<APIGuildScheduledEvent[]> {
+  return (await rest.get(Routes.guildScheduledEvents(guildId))) as APIGuildScheduledEvent[];
+}
+
+export async function createGuildScheduledEvent(
+  rest: RequestClient,
+  guildId: string,
+  body: RESTPostAPIGuildScheduledEventJSONBody,
+): Promise<APIGuildScheduledEvent> {
+  return (await rest.post(Routes.guildScheduledEvents(guildId), {
+    body,
+  })) as APIGuildScheduledEvent;
+}
+
+export async function timeoutGuildMember(
+  rest: RequestClient,
+  guildId: string,
+  userId: string,
+  data: RequestData,
+): Promise<APIGuildMember> {
+  return (await rest.patch(Routes.guildMember(guildId, userId), data)) as APIGuildMember;
+}
+
+export async function addGuildMemberRole(
+  rest: RequestClient,
+  guildId: string,
+  userId: string,
+  roleId: string,
+): Promise<void> {
+  await rest.put(Routes.guildMemberRole(guildId, userId, roleId));
+}
+
+export async function removeGuildMemberRole(
+  rest: RequestClient,
+  guildId: string,
+  userId: string,
+  roleId: string,
+): Promise<void> {
+  await rest.delete(Routes.guildMemberRole(guildId, userId, roleId));
+}
+
+export async function removeGuildMember(
+  rest: RequestClient,
+  guildId: string,
+  userId: string,
+  data?: RequestData,
+): Promise<void> {
+  await rest.delete(Routes.guildMember(guildId, userId), data);
+}
+
+export async function createGuildBan(
+  rest: RequestClient,
+  guildId: string,
+  userId: string,
+  data?: RequestData,
+): Promise<void> {
+  await rest.put(Routes.guildBan(guildId, userId), data);
+}
+
+export async function listGuildEmojis(rest: RequestClient, guildId: string): Promise<unknown> {
+  return await rest.get(Routes.guildEmojis(guildId));
+}
+
+export async function createGuildEmoji(
+  rest: RequestClient,
+  guildId: string,
+  data: RequestData,
+): Promise<unknown> {
+  return await rest.post(Routes.guildEmojis(guildId), data);
+}
+
+export async function createGuildSticker(
+  rest: RequestClient,
+  guildId: string,
+  data: RequestData,
+): Promise<unknown> {
+  return await rest.post(Routes.guildStickers(guildId), data);
+}

package/src/internal/api.interactions.ts

@@ -0,0 +1,53 @@
+import { Routes } from "discord-api-types/v10";
+import type { RequestQuery } from "./rest-scheduler.js";
+import type { RequestClient, RequestData } from "./rest.js";
+
+export async function createInteractionCallback(
+  rest: RequestClient,
+  interactionId: string,
+  token: string,
+  body: unknown,
+): Promise<unknown> {
+  return await rest.post(Routes.interactionCallback(interactionId, token), { body });
+}
+
+export async function editWebhookMessage(
+  rest: RequestClient,
+  applicationId: string,
+  token: string,
+  messageId: string,
+  data: RequestData,
+  query?: RequestQuery,
+): Promise<unknown> {
+  return query
+    ? await rest.patch(Routes.webhookMessage(applicationId, token, messageId), data, query)
+    : await rest.patch(Routes.webhookMessage(applicationId, token, messageId), data);
+}
+
+export async function deleteWebhookMessage(
+  rest: RequestClient,
+  applicationId: string,
+  token: string,
+  messageId: string,
+): Promise<unknown> {
+  return await rest.delete(Routes.webhookMessage(applicationId, token, messageId));
+}
+
+export async function getWebhookMessage(
+  rest: RequestClient,
+  applicationId: string,
+  token: string,
+  messageId: string,
+): Promise<unknown> {
+  return await rest.get(Routes.webhookMessage(applicationId, token, messageId));
+}
+
+export async function createWebhookMessage(
+  rest: RequestClient,
+  applicationId: string,
+  token: string,
+  data: RequestData,
+  query?: RequestQuery,
+): Promise<unknown> {
+  return await rest.post(Routes.webhook(applicationId, token), data, query);
+}