@kodelyth/discord 2026.5.39 → 2026.5.42

package/src/client.test.ts

@@ -0,0 +1,83 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createDiscordRestClient } from "./client.js";
+import type { RequestClient } from "./internal/discord.js";
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe("createDiscordRestClient", () => {
+  const fakeRest = {} as RequestClient;
+
+  it("uses explicit token without resolving config token SecretRefs", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          token: {
+            source: "exec",
+            provider: "vault",
+            id: "discord/bot-token",
+          },
+        },
+      },
+    } as KlawConfig;
+
+    const result = createDiscordRestClient({ cfg, token: "Bot explicit-token", rest: fakeRest });
+
+    expect(result.token).toBe("explicit-token");
+    expect(result.rest).toBe(fakeRest);
+    expect(result.account.accountId).toBe("default");
+  });
+
+  it("keeps account retry config when explicit token is provided", () => {
+    const cfg = {
+      channels: {
+        discord: {
+          accounts: {
+            ops: {
+              token: {
+                source: "exec",
+                provider: "vault",
+                id: "discord/ops-token",
+              },
+              retry: {
+                attempts: 7,
+              },
+            },
+          },
+        },
+      },
+    } as KlawConfig;
+
+    const result = createDiscordRestClient({
+      cfg,
+      accountId: "ops",
+      token: "Bot explicit-account-token",
+      rest: fakeRest,
+    });
+
+    expect(result.token).toBe("explicit-account-token");
+    expect(result.account.accountId).toBe("ops");
+    expect(result.account.config.retry).toEqual({ attempts: 7 });
+  });
+
+  it("still fails closed when no explicit token is provided and config token is unresolved", () => {
+    vi.stubEnv("DISCORD_BOT_TOKEN", "env-token");
+    const cfg = {
+      channels: {
+        discord: {
+          token: {
+            source: "file",
+            provider: "default",
+            id: "/discord/token",
+          },
+        },
+      },
+    } as KlawConfig;
+
+    expect(() => createDiscordRestClient({ cfg, rest: fakeRest })).toThrow(
+      /configured for account "default" is unavailable/i,
+    );
+  });
+});

package/src/client.ts

@@ -0,0 +1,143 @@
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import { requireRuntimeConfig } from "klaw/plugin-sdk/plugin-config-runtime";
+import type { RetryConfig, RetryRunner } from "klaw/plugin-sdk/retry-runtime";
+import { normalizeAccountId } from "klaw/plugin-sdk/routing";
+import type { RuntimeEnv } from "klaw/plugin-sdk/runtime-env";
+import { normalizeOptionalString } from "klaw/plugin-sdk/string-coerce-runtime";
+import {
+  mergeDiscordAccountConfig,
+  resolveDiscordAccount,
+  type ResolvedDiscordAccount,
+} from "./accounts.js";
+import { RequestClient } from "./internal/discord.js";
+import { resolveDiscordProxyFetchForAccount } from "./proxy-fetch.js";
+import { createDiscordRequestClient } from "./proxy-request-client.js";
+import { createDiscordRetryRunner } from "./retry.js";
+import type { DiscordRuntimeAccountContext } from "./send.types.js";
+import { normalizeDiscordToken } from "./token.js";
+
+export type DiscordClientOpts = {
+  cfg: KlawConfig;
+  token?: string;
+  accountId?: string;
+  rest?: RequestClient;
+  retry?: RetryConfig;
+  verbose?: boolean;
+};
+
+export function createDiscordRuntimeAccountContext(params: {
+  cfg: KlawConfig;
+  accountId: string;
+}): DiscordRuntimeAccountContext {
+  return {
+    cfg: params.cfg,
+    accountId: normalizeAccountId(params.accountId),
+  };
+}
+
+export function resolveDiscordClientAccountContext(
+  opts: Pick<DiscordClientOpts, "cfg" | "accountId">,
+  runtime?: Pick<RuntimeEnv, "error">,
+) {
+  const resolvedCfg = requireRuntimeConfig(opts.cfg, "Discord client");
+  const account = resolveAccountWithoutToken({
+    cfg: resolvedCfg,
+    accountId: opts.accountId,
+  });
+  return {
+    cfg: resolvedCfg,
+    account,
+    proxyFetch: resolveDiscordProxyFetchForAccount(account, resolvedCfg, runtime),
+  };
+}
+
+function resolveToken(params: {
+  account: ResolvedDiscordAccount;
+  accountId: string;
+  fallbackToken?: string;
+}) {
+  const fallback = normalizeDiscordToken(params.fallbackToken, "channels.discord.token");
+  if (!fallback) {
+    if (params.account.tokenStatus === "configured_unavailable") {
+      throw new Error(
+        `Discord bot token configured for account "${params.accountId}" is unavailable; resolve SecretRefs against the active runtime snapshot before using this account.`,
+      );
+    }
+    throw new Error(
+      `Discord bot token missing for account "${params.accountId}" (set discord.accounts.${params.accountId}.token or DISCORD_BOT_TOKEN for default).`,
+    );
+  }
+  return fallback;
+}
+
+function resolveRest(
+  token: string,
+  account: ResolvedDiscordAccount,
+  cfg: KlawConfig,
+  rest?: RequestClient,
+  proxyFetch?: typeof fetch,
+) {
+  if (rest) {
+    return rest;
+  }
+  const resolvedProxyFetch = proxyFetch ?? resolveDiscordProxyFetchForAccount(account, cfg);
+  return createDiscordRequestClient(
+    token,
+    resolvedProxyFetch ? { fetch: resolvedProxyFetch } : undefined,
+  );
+}
+
+function resolveAccountWithoutToken(params: {
+  cfg: KlawConfig;
+  accountId?: string;
+}): ResolvedDiscordAccount {
+  const accountId = normalizeAccountId(params.accountId);
+  const merged = mergeDiscordAccountConfig(params.cfg, accountId);
+  const baseEnabled = params.cfg.channels?.discord?.enabled !== false;
+  const accountEnabled = merged.enabled !== false;
+  return {
+    accountId,
+    enabled: baseEnabled && accountEnabled,
+    name: normalizeOptionalString(merged.name),
+    token: "",
+    tokenSource: "none",
+    tokenStatus: "missing",
+    config: merged,
+  };
+}
+
+export function createDiscordRestClient(opts: DiscordClientOpts) {
+  const explicitToken = normalizeDiscordToken(opts.token, "channels.discord.token");
+  const proxyContext = resolveDiscordClientAccountContext(opts);
+  const resolvedCfg = proxyContext.cfg;
+  const account = explicitToken
+    ? proxyContext.account
+    : resolveDiscordAccount({ cfg: resolvedCfg, accountId: opts.accountId });
+  const token =
+    explicitToken ??
+    resolveToken({
+      account,
+      accountId: account.accountId,
+      fallbackToken: account.token,
+    });
+  const rest = resolveRest(token, account, resolvedCfg, opts.rest, proxyContext.proxyFetch);
+  return { token, rest, account };
+}
+
+export function createDiscordClient(opts: DiscordClientOpts): {
+  token: string;
+  rest: RequestClient;
+  request: RetryRunner;
+} {
+  const { token, rest, account } = createDiscordRestClient(opts);
+  const request = createDiscordRetryRunner({
+    retry: opts.retry,
+    configRetry: account.config.retry,
+    verbose: opts.verbose,
+  });
+  return { token, rest, request };
+}
+
+export function resolveDiscordRest(opts: DiscordClientOpts) {
+  return createDiscordRestClient(opts).rest;
+}

package/src/component-custom-id.ts

@@ -0,0 +1,72 @@
+import { parseCustomId, type ComponentParserResult } from "./internal/discord.js";
+
+export const DISCORD_COMPONENT_CUSTOM_ID_KEY = "occomp";
+export const DISCORD_MODAL_CUSTOM_ID_KEY = "ocmodal";
+
+export function buildDiscordComponentCustomId(params: {
+  componentId: string;
+  modalId?: string;
+}): string {
+  const base = `${DISCORD_COMPONENT_CUSTOM_ID_KEY}:cid=${params.componentId}`;
+  return params.modalId ? `${base};mid=${params.modalId}` : base;
+}
+
+export function buildDiscordModalCustomId(modalId: string): string {
+  return `${DISCORD_MODAL_CUSTOM_ID_KEY}:mid=${modalId}`;
+}
+
+export function parseDiscordComponentCustomId(
+  id: string,
+): { componentId: string; modalId?: string } | null {
+  const parsed = parseCustomId(id);
+  if (parsed.key !== DISCORD_COMPONENT_CUSTOM_ID_KEY) {
+    return null;
+  }
+  const componentId = parsed.data.cid;
+  if (typeof componentId !== "string" || !componentId.trim()) {
+    return null;
+  }
+  const modalId = parsed.data.mid;
+  return {
+    componentId,
+    modalId: typeof modalId === "string" && modalId.trim() ? modalId : undefined,
+  };
+}
+
+export function parseDiscordModalCustomId(id: string): string | null {
+  const parsed = parseCustomId(id);
+  if (parsed.key !== DISCORD_MODAL_CUSTOM_ID_KEY) {
+    return null;
+  }
+  const modalId = parsed.data.mid;
+  if (typeof modalId !== "string" || !modalId.trim()) {
+    return null;
+  }
+  return modalId;
+}
+
+function isDiscordComponentWildcardRegistrationId(id: string): boolean {
+  return /^__klaw_discord_component_[a-z_]+_wildcard__$/.test(id);
+}
+
+export function parseDiscordComponentCustomIdForInteraction(id: string): ComponentParserResult {
+  if (id === "*" || isDiscordComponentWildcardRegistrationId(id)) {
+    return { key: "*", data: {} };
+  }
+  const parsed = parseCustomId(id);
+  if (parsed.key !== DISCORD_COMPONENT_CUSTOM_ID_KEY) {
+    return parsed;
+  }
+  return { key: "*", data: parsed.data };
+}
+
+export function parseDiscordModalCustomIdForInteraction(id: string): ComponentParserResult {
+  if (id === "*" || isDiscordComponentWildcardRegistrationId(id)) {
+    return { key: "*", data: {} };
+  }
+  const parsed = parseCustomId(id);
+  if (parsed.key !== DISCORD_MODAL_CUSTOM_ID_KEY) {
+    return parsed;
+  }
+  return { key: "*", data: parsed.data };
+}

package/src/components-registry.ts

@@ -0,0 +1,356 @@
+import { resolveGlobalMap } from "klaw/plugin-sdk/global-singleton";
+import type { DiscordComponentEntry, DiscordModalEntry } from "./components.js";
+import { getOptionalDiscordRuntime } from "./runtime.js";
+
+const DEFAULT_COMPONENT_TTL_MS = 30 * 60 * 1000;
+const PERSISTENT_COMPONENT_NAMESPACE = "discord.components";
+const PERSISTENT_MODAL_NAMESPACE = "discord.modals";
+const PERSISTENT_COMPONENT_MAX_ENTRIES = 500;
+const PERSISTENT_MODAL_MAX_ENTRIES = 500;
+const DISCORD_COMPONENT_ENTRIES_KEY = Symbol.for("klaw.discord.componentEntries");
+const DISCORD_MODAL_ENTRIES_KEY = Symbol.for("klaw.discord.modalEntries");
+
+type PersistedDiscordRegistryEntry<T extends { id: string }> = {
+  version: 1;
+  entry: T;
+};
+
+type DiscordPersistentStore<T> = {
+  register(key: string, value: T, opts?: { ttlMs?: number }): Promise<void>;
+  lookup(key: string): Promise<T | undefined>;
+  consume(key: string): Promise<T | undefined>;
+  delete(key: string): Promise<boolean>;
+};
+
+type DiscordRegistryStore<T extends { id: string }> = DiscordPersistentStore<
+  PersistedDiscordRegistryEntry<T>
+>;
+
+let componentEntries: Map<string, DiscordComponentEntry> | undefined;
+let modalEntries: Map<string, DiscordModalEntry> | undefined;
+let persistentComponentStore: DiscordRegistryStore<DiscordComponentEntry> | undefined;
+let persistentModalStore: DiscordRegistryStore<DiscordModalEntry> | undefined;
+let persistentRegistryDisabled = false;
+
+function getComponentEntries(): Map<string, DiscordComponentEntry> {
+  componentEntries ??= resolveGlobalMap<string, DiscordComponentEntry>(
+    DISCORD_COMPONENT_ENTRIES_KEY,
+  );
+  return componentEntries;
+}
+
+function getModalEntries(): Map<string, DiscordModalEntry> {
+  modalEntries ??= resolveGlobalMap<string, DiscordModalEntry>(DISCORD_MODAL_ENTRIES_KEY);
+  return modalEntries;
+}
+
+function reportPersistentComponentRegistryError(error: unknown): void {
+  try {
+    getOptionalDiscordRuntime()
+      ?.logging.getChildLogger({ plugin: "discord", feature: "component-registry-state" })
+      .warn("Discord persistent component registry state failed", { error: String(error) });
+  } catch {
+    // Best effort only: persistent state must never break Discord interactions.
+  }
+}
+
+function disablePersistentComponentRegistry(error: unknown): void {
+  persistentRegistryDisabled = true;
+  persistentComponentStore = undefined;
+  persistentModalStore = undefined;
+  reportPersistentComponentRegistryError(error);
+}
+
+function getPersistentComponentStore(): DiscordRegistryStore<DiscordComponentEntry> | undefined {
+  if (persistentRegistryDisabled) {
+    return undefined;
+  }
+  if (persistentComponentStore) {
+    return persistentComponentStore;
+  }
+  const runtime = getOptionalDiscordRuntime();
+  if (!runtime) {
+    return undefined;
+  }
+  try {
+    persistentComponentStore = runtime.state.openKeyedStore<
+      PersistedDiscordRegistryEntry<DiscordComponentEntry>
+    >({
+      namespace: PERSISTENT_COMPONENT_NAMESPACE,
+      maxEntries: PERSISTENT_COMPONENT_MAX_ENTRIES,
+      defaultTtlMs: DEFAULT_COMPONENT_TTL_MS,
+    });
+    return persistentComponentStore;
+  } catch (error) {
+    disablePersistentComponentRegistry(error);
+    return undefined;
+  }
+}
+
+function getPersistentModalStore(): DiscordRegistryStore<DiscordModalEntry> | undefined {
+  if (persistentRegistryDisabled) {
+    return undefined;
+  }
+  if (persistentModalStore) {
+    return persistentModalStore;
+  }
+  const runtime = getOptionalDiscordRuntime();
+  if (!runtime) {
+    return undefined;
+  }
+  try {
+    persistentModalStore = runtime.state.openKeyedStore<
+      PersistedDiscordRegistryEntry<DiscordModalEntry>
+    >({
+      namespace: PERSISTENT_MODAL_NAMESPACE,
+      maxEntries: PERSISTENT_MODAL_MAX_ENTRIES,
+      defaultTtlMs: DEFAULT_COMPONENT_TTL_MS,
+    });
+    return persistentModalStore;
+  } catch (error) {
+    disablePersistentComponentRegistry(error);
+    return undefined;
+  }
+}
+
+function isExpired(entry: { expiresAt?: number }, now: number) {
+  return typeof entry.expiresAt === "number" && entry.expiresAt <= now;
+}
+
+function normalizeEntryTimestamps<T extends { createdAt?: number; expiresAt?: number }>(
+  entry: T,
+  now: number,
+  ttlMs: number,
+): T {
+  const createdAt = entry.createdAt ?? now;
+  const expiresAt = entry.expiresAt ?? createdAt + ttlMs;
+  return { ...entry, createdAt, expiresAt };
+}
+
+function registerEntries<
+  T extends { id: string; messageId?: string; createdAt?: number; expiresAt?: number },
+>(
+  entries: T[],
+  store: Map<string, T>,
+  params: { now: number; ttlMs: number; messageId?: string },
+): T[] {
+  const normalizedEntries: T[] = [];
+  for (const entry of entries) {
+    const normalized = normalizeEntryTimestamps(
+      { ...entry, messageId: params.messageId ?? entry.messageId },
+      params.now,
+      params.ttlMs,
+    );
+    store.set(entry.id, normalized);
+    normalizedEntries.push(normalized);
+  }
+  return normalizedEntries;
+}
+
+function resolveEntry<T extends { expiresAt?: number }>(
+  store: Map<string, T>,
+  params: { id: string; consume?: boolean },
+): T | null {
+  const entry = store.get(params.id);
+  if (!entry) {
+    return null;
+  }
+  const now = Date.now();
+  if (isExpired(entry, now)) {
+    store.delete(params.id);
+    return null;
+  }
+  if (params.consume !== false) {
+    store.delete(params.id);
+  }
+  return entry;
+}
+
+function readPersistedRegistryEntry<T extends { id: string }>(
+  persisted: PersistedDiscordRegistryEntry<T> | undefined,
+): T | null {
+  if (persisted?.version !== 1 || typeof persisted.entry?.id !== "string") {
+    return null;
+  }
+  return persisted.entry;
+}
+
+function registerPersistentRegistryEntries<T extends { id: string }>(params: {
+  entries: T[];
+  ttlMs: number;
+  openStore: () => DiscordRegistryStore<T> | undefined;
+}): void {
+  if (params.entries.length === 0) {
+    return;
+  }
+  const store = params.openStore();
+  if (!store) {
+    return;
+  }
+  for (const entry of params.entries) {
+    void store
+      .register(entry.id, { version: 1, entry }, { ttlMs: params.ttlMs })
+      .catch(disablePersistentComponentRegistry);
+  }
+}
+
+function registerPersistentEntries(params: {
+  entries: DiscordComponentEntry[];
+  modals: DiscordModalEntry[];
+  ttlMs: number;
+}): void {
+  registerPersistentRegistryEntries({
+    entries: params.entries,
+    ttlMs: params.ttlMs,
+    openStore: getPersistentComponentStore,
+  });
+  registerPersistentRegistryEntries({
+    entries: params.modals,
+    ttlMs: params.ttlMs,
+    openStore: getPersistentModalStore,
+  });
+}
+
+function deletePersistentEntry<T extends { id: string }>(params: {
+  id: string;
+  openStore: () => DiscordRegistryStore<T> | undefined;
+}): void {
+  const store = params.openStore();
+  if (!store) {
+    return;
+  }
+  void store.delete(params.id).catch(disablePersistentComponentRegistry);
+}
+
+function resolveComponentConsumptionIds(entry: DiscordComponentEntry): string[] {
+  if (!entry.consumptionGroupId) {
+    return [entry.id];
+  }
+  const ids = entry.consumptionGroupEntryIds?.filter((id) => typeof id === "string" && id) ?? [];
+  return ids.length > 0 ? Array.from(new Set(ids)) : [entry.id];
+}
+
+function deleteComponentConsumptionGroup(entry: DiscordComponentEntry): void {
+  const store = getComponentEntries();
+  for (const id of resolveComponentConsumptionIds(entry)) {
+    store.delete(id);
+  }
+}
+
+function deletePersistentComponentConsumptionGroup(entry: DiscordComponentEntry): void {
+  const store = getPersistentComponentStore();
+  if (!store) {
+    return;
+  }
+  for (const id of resolveComponentConsumptionIds(entry)) {
+    void store.delete(id).catch(disablePersistentComponentRegistry);
+  }
+}
+
+async function resolvePersistentRegistryEntry<T extends { id: string }>(params: {
+  id: string;
+  consume?: boolean;
+  openStore: () => DiscordRegistryStore<T> | undefined;
+}): Promise<T | null> {
+  const store = params.openStore();
+  if (!store) {
+    return null;
+  }
+  try {
+    const value =
+      params.consume === false ? await store.lookup(params.id) : await store.consume(params.id);
+    return readPersistedRegistryEntry(value);
+  } catch (error) {
+    disablePersistentComponentRegistry(error);
+    return null;
+  }
+}
+
+export function registerDiscordComponentEntries(params: {
+  entries: DiscordComponentEntry[];
+  modals: DiscordModalEntry[];
+  ttlMs?: number;
+  messageId?: string;
+}): void {
+  const now = Date.now();
+  const ttlMs = params.ttlMs ?? DEFAULT_COMPONENT_TTL_MS;
+  const normalizedEntries = registerEntries(params.entries, getComponentEntries(), {
+    now,
+    ttlMs,
+    messageId: params.messageId,
+  });
+  const normalizedModals = registerEntries(params.modals, getModalEntries(), {
+    now,
+    ttlMs,
+    messageId: params.messageId,
+  });
+  registerPersistentEntries({
+    entries: normalizedEntries,
+    modals: normalizedModals,
+    ttlMs,
+  });
+}
+
+export function resolveDiscordComponentEntry(params: {
+  id: string;
+  consume?: boolean;
+}): DiscordComponentEntry | null {
+  const entry = resolveEntry(getComponentEntries(), params);
+  if (entry && params.consume !== false) {
+    deleteComponentConsumptionGroup(entry);
+  }
+  return entry;
+}
+
+export async function resolveDiscordComponentEntryWithPersistence(params: {
+  id: string;
+  consume?: boolean;
+}): Promise<DiscordComponentEntry | null> {
+  const inMemory = resolveDiscordComponentEntry(params);
+  if (inMemory) {
+    if (params.consume !== false) {
+      deletePersistentComponentConsumptionGroup(inMemory);
+    }
+    return inMemory;
+  }
+  const persisted = await resolvePersistentRegistryEntry({
+    ...params,
+    openStore: getPersistentComponentStore,
+  });
+  if (persisted && params.consume !== false) {
+    deletePersistentComponentConsumptionGroup(persisted);
+  }
+  return persisted;
+}
+
+export function resolveDiscordModalEntry(params: {
+  id: string;
+  consume?: boolean;
+}): DiscordModalEntry | null {
+  return resolveEntry(getModalEntries(), params);
+}
+
+export async function resolveDiscordModalEntryWithPersistence(params: {
+  id: string;
+  consume?: boolean;
+}): Promise<DiscordModalEntry | null> {
+  const inMemory = resolveDiscordModalEntry(params);
+  if (inMemory) {
+    if (params.consume !== false) {
+      deletePersistentEntry({ ...params, openStore: getPersistentModalStore });
+    }
+    return inMemory;
+  }
+  return await resolvePersistentRegistryEntry({
+    ...params,
+    openStore: getPersistentModalStore,
+  });
+}
+
+export function clearDiscordComponentEntries(): void {
+  getComponentEntries().clear();
+  getModalEntries().clear();
+  persistentComponentStore = undefined;
+  persistentModalStore = undefined;
+  persistentRegistryDisabled = false;
+}