@gakr-gakr/twitch 0.1.0

package/src/setup-surface.ts

@@ -0,0 +1,526 @@
+/**
+ * Twitch setup wizard surface for CLI setup.
+ */
+
+import { normalizeOptionalAccountId } from "autobot/plugin-sdk/account-id";
+import { getChatChannelMeta, type ChannelPlugin } from "autobot/plugin-sdk/core";
+import {
+  formatDocsLink,
+  type ChannelSetupAdapter,
+  type ChannelSetupDmPolicy,
+  type ChannelSetupWizard,
+  type AutoBotConfig,
+  type WizardPrompter,
+  normalizeAccountId,
+  createSetupTranslator,
+} from "autobot/plugin-sdk/setup";
+import {
+  DEFAULT_ACCOUNT_ID,
+  getAccountConfig,
+  listAccountIds,
+  resolveDefaultTwitchAccountId,
+  resolveTwitchAccountContext,
+} from "./config.js";
+import type { TwitchAccountConfig, TwitchRole } from "./types.js";
+import { isAccountConfigured } from "./utils/twitch.js";
+
+const channel = "twitch" as const;
+const t = createSetupTranslator();
+const INVALID_ACCOUNT_ID_MESSAGE = "Invalid Twitch account id";
+
+function normalizeRequestedSetupAccountId(accountId: string): string {
+  const normalized = normalizeOptionalAccountId(accountId);
+  if (!normalized) {
+    throw new Error(INVALID_ACCOUNT_ID_MESSAGE);
+  }
+  return normalized;
+}
+
+function resolveSetupAccountId(cfg: AutoBotConfig, requestedAccountId?: string): string {
+  const requested = requestedAccountId?.trim();
+  if (requested) {
+    return normalizeRequestedSetupAccountId(requested);
+  }
+
+  const preferred = cfg.channels?.twitch?.defaultAccount?.trim();
+  return preferred ? normalizeAccountId(preferred) : resolveDefaultTwitchAccountId(cfg);
+}
+
+export function setTwitchAccount(
+  cfg: AutoBotConfig,
+  account: Partial<TwitchAccountConfig>,
+  accountId: string = resolveSetupAccountId(cfg),
+): AutoBotConfig {
+  const resolvedAccountId = accountId.trim()
+    ? normalizeRequestedSetupAccountId(accountId)
+    : resolveSetupAccountId(cfg);
+  const existing = getAccountConfig(cfg, resolvedAccountId);
+  const merged: TwitchAccountConfig = {
+    username: account.username ?? existing?.username ?? "",
+    accessToken: account.accessToken ?? existing?.accessToken ?? "",
+    clientId: account.clientId ?? existing?.clientId ?? "",
+    channel: account.channel ?? existing?.channel ?? "",
+    enabled: account.enabled ?? existing?.enabled ?? true,
+    allowFrom: account.allowFrom ?? existing?.allowFrom,
+    allowedRoles: account.allowedRoles ?? existing?.allowedRoles,
+    requireMention: account.requireMention ?? existing?.requireMention,
+    clientSecret: account.clientSecret ?? existing?.clientSecret,
+    refreshToken: account.refreshToken ?? existing?.refreshToken,
+    expiresIn: account.expiresIn ?? existing?.expiresIn,
+    obtainmentTimestamp: account.obtainmentTimestamp ?? existing?.obtainmentTimestamp,
+  };
+
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      twitch: {
+        ...((cfg.channels as Record<string, unknown>)?.twitch as
+          | Record<string, unknown>
+          | undefined),
+        enabled: true,
+        accounts: {
+          ...((
+            (cfg.channels as Record<string, unknown>)?.twitch as Record<string, unknown> | undefined
+          )?.accounts as Record<string, unknown> | undefined),
+          [resolvedAccountId]: merged,
+        },
+      },
+    },
+  };
+}
+
+async function noteTwitchSetupHelp(prompter: WizardPrompter): Promise<void> {
+  await prompter.note(
+    [
+      t("wizard.twitch.helpRequiresBot"),
+      t("wizard.twitch.helpCreateApp"),
+      t("wizard.twitch.helpGenerateToken"),
+      t("wizard.twitch.helpTokenTools"),
+      t("wizard.twitch.helpCopyToken"),
+      t("wizard.twitch.helpEnvVars"),
+      `Docs: ${formatDocsLink("/channels/twitch", "channels/twitch")}`,
+    ].join("\n"),
+    t("wizard.twitch.setupTitle"),
+  );
+}
+
+export async function promptToken(
+  prompter: WizardPrompter,
+  account: TwitchAccountConfig | null,
+  envToken: string | undefined,
+): Promise<string> {
+  const existingToken = account?.accessToken ?? "";
+
+  if (existingToken && !envToken) {
+    const keepToken = await prompter.confirm({
+      message: t("wizard.twitch.accessTokenKeep"),
+      initialValue: true,
+    });
+    if (keepToken) {
+      return existingToken;
+    }
+  }
+
+  return (
+    await prompter.text({
+      message: t("wizard.twitch.oauthTokenPrompt"),
+      initialValue: envToken ?? "",
+      validate: (value) => {
+        const raw = value?.trim() ?? "";
+        if (!raw) {
+          return "Required";
+        }
+        if (!raw.startsWith("oauth:")) {
+          return "Token should start with 'oauth:'";
+        }
+        return undefined;
+      },
+    })
+  ).trim();
+}
+
+export async function promptUsername(
+  prompter: WizardPrompter,
+  account: TwitchAccountConfig | null,
+): Promise<string> {
+  return (
+    await prompter.text({
+      message: t("wizard.twitch.botUsernamePrompt"),
+      initialValue: account?.username ?? "",
+      validate: (value) => (value?.trim() ? undefined : "Required"),
+    })
+  ).trim();
+}
+
+export async function promptClientId(
+  prompter: WizardPrompter,
+  account: TwitchAccountConfig | null,
+): Promise<string> {
+  return (
+    await prompter.text({
+      message: t("wizard.twitch.clientIdPrompt"),
+      initialValue: account?.clientId ?? "",
+      validate: (value) => (value?.trim() ? undefined : "Required"),
+    })
+  ).trim();
+}
+
+export async function promptChannelName(
+  prompter: WizardPrompter,
+  account: TwitchAccountConfig | null,
+): Promise<string> {
+  return (
+    await prompter.text({
+      message: t("wizard.twitch.channelJoinPrompt"),
+      initialValue: account?.channel ?? "",
+      validate: (value) => (value?.trim() ? undefined : "Required"),
+    })
+  ).trim();
+}
+
+export async function promptRefreshTokenSetup(
+  prompter: WizardPrompter,
+  account: TwitchAccountConfig | null,
+): Promise<{ clientSecret?: string; refreshToken?: string }> {
+  const useRefresh = await prompter.confirm({
+    message: t("wizard.twitch.refreshTokenPrompt"),
+    initialValue: Boolean(account?.clientSecret && account?.refreshToken),
+  });
+
+  if (!useRefresh) {
+    return {};
+  }
+
+  const clientSecret =
+    (
+      await prompter.text({
+        message: t("wizard.twitch.clientSecretPrompt"),
+        initialValue: account?.clientSecret ?? "",
+        validate: (value) => (value?.trim() ? undefined : "Required"),
+      })
+    ).trim() || undefined;
+
+  const refreshToken =
+    (
+      await prompter.text({
+        message: t("wizard.twitch.refreshTokenInputPrompt"),
+        initialValue: account?.refreshToken ?? "",
+        validate: (value) => (value?.trim() ? undefined : "Required"),
+      })
+    ).trim() || undefined;
+
+  return { clientSecret, refreshToken };
+}
+
+export async function configureWithEnvToken(
+  cfg: AutoBotConfig,
+  prompter: WizardPrompter,
+  account: TwitchAccountConfig | null,
+  envToken: string,
+  forceAllowFrom: boolean,
+  dmPolicy: ChannelSetupDmPolicy,
+  accountId: string = resolveSetupAccountId(cfg),
+): Promise<{ cfg: AutoBotConfig } | null> {
+  const resolvedAccountId = accountId.trim()
+    ? normalizeRequestedSetupAccountId(accountId)
+    : resolveSetupAccountId(cfg);
+  if (resolvedAccountId !== DEFAULT_ACCOUNT_ID) {
+    return null;
+  }
+
+  const useEnv = await prompter.confirm({
+    message: t("wizard.twitch.envPrompt"),
+    initialValue: true,
+  });
+  if (!useEnv) {
+    return null;
+  }
+
+  const username = await promptUsername(prompter, account);
+  const clientId = await promptClientId(prompter, account);
+
+  const cfgWithAccount = setTwitchAccount(
+    cfg,
+    {
+      username,
+      clientId,
+      accessToken: envToken,
+      enabled: true,
+    },
+    resolvedAccountId,
+  );
+
+  if (forceAllowFrom && dmPolicy.promptAllowFrom) {
+    return {
+      cfg: await dmPolicy.promptAllowFrom({
+        cfg: cfgWithAccount,
+        prompter,
+        accountId: resolvedAccountId,
+      }),
+    };
+  }
+
+  return { cfg: cfgWithAccount };
+}
+
+function setTwitchAccessControl(
+  cfg: AutoBotConfig,
+  allowedRoles: TwitchRole[],
+  requireMention: boolean,
+  accountId?: string,
+): AutoBotConfig {
+  const resolvedAccountId = resolveSetupAccountId(cfg, accountId);
+  const account = getAccountConfig(cfg, resolvedAccountId);
+  if (!account) {
+    return cfg;
+  }
+
+  return setTwitchAccount(
+    cfg,
+    {
+      ...account,
+      allowedRoles,
+      requireMention,
+    },
+    resolvedAccountId,
+  );
+}
+
+function resolveTwitchGroupPolicy(
+  cfg: AutoBotConfig,
+  accountId?: string,
+): "open" | "allowlist" | "disabled" {
+  const account = getAccountConfig(cfg, resolveSetupAccountId(cfg, accountId));
+  if (account?.allowedRoles?.includes("all")) {
+    return "open";
+  }
+  if (account?.allowedRoles?.includes("moderator")) {
+    return "allowlist";
+  }
+  return "disabled";
+}
+
+function setTwitchGroupPolicy(
+  cfg: AutoBotConfig,
+  policy: "open" | "allowlist" | "disabled",
+  accountId?: string,
+): AutoBotConfig {
+  const allowedRoles: TwitchRole[] =
+    policy === "open" ? ["all"] : policy === "allowlist" ? ["moderator", "vip"] : [];
+  return setTwitchAccessControl(cfg, allowedRoles, true, accountId);
+}
+
+const twitchDmPolicy: ChannelSetupDmPolicy = {
+  label: "Twitch",
+  channel,
+  policyKey: "channels.twitch.accounts.default.allowedRoles",
+  allowFromKey: "channels.twitch.accounts.default.allowFrom",
+  resolveConfigKeys: (cfg, accountId) => {
+    const resolvedAccountId = resolveSetupAccountId(cfg, accountId);
+    return {
+      policyKey: `channels.twitch.accounts.${resolvedAccountId}.allowedRoles`,
+      allowFromKey: `channels.twitch.accounts.${resolvedAccountId}.allowFrom`,
+    };
+  },
+  getCurrent: (cfg, accountId) => {
+    const account = getAccountConfig(cfg, resolveSetupAccountId(cfg, accountId));
+    if (account?.allowedRoles?.includes("all")) {
+      return "open";
+    }
+    if (account?.allowFrom && account.allowFrom.length > 0) {
+      return "allowlist";
+    }
+    return "disabled";
+  },
+  setPolicy: (cfg, policy, accountId) => {
+    const allowedRoles: TwitchRole[] =
+      policy === "open" ? ["all"] : policy === "allowlist" ? [] : ["moderator"];
+    return setTwitchAccessControl(cfg, allowedRoles, true, accountId);
+  },
+  promptAllowFrom: async ({ cfg, prompter, accountId }) => {
+    const resolvedAccountId = resolveSetupAccountId(cfg, accountId);
+    const account = getAccountConfig(cfg, resolvedAccountId);
+    const existingAllowFrom = account?.allowFrom ?? [];
+
+    const entry = await prompter.text({
+      message: t("wizard.twitch.allowFromPrompt"),
+      placeholder: "123456789",
+      initialValue: existingAllowFrom[0] || undefined,
+    });
+
+    const allowFrom = (entry ?? "")
+      .split(/[\n,;]+/g)
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    return setTwitchAccount(
+      cfg,
+      {
+        ...(account ?? undefined),
+        allowFrom,
+      },
+      resolvedAccountId,
+    );
+  },
+};
+
+const twitchGroupAccess: NonNullable<ChannelSetupWizard["groupAccess"]> = {
+  label: "Twitch chat",
+  placeholder: "",
+  skipAllowlistEntries: true,
+  currentPolicy: ({ cfg, accountId }) => resolveTwitchGroupPolicy(cfg, accountId),
+  currentEntries: ({ cfg, accountId }) => {
+    const account = getAccountConfig(cfg, resolveSetupAccountId(cfg, accountId));
+    return account?.allowFrom ?? [];
+  },
+  updatePrompt: ({ cfg, accountId }) => {
+    const account = getAccountConfig(cfg, resolveSetupAccountId(cfg, accountId));
+    return Boolean(account?.allowedRoles?.length || account?.allowFrom?.length);
+  },
+  setPolicy: ({ cfg, accountId, policy }) => setTwitchGroupPolicy(cfg, policy, accountId),
+  resolveAllowlist: async () => [],
+  applyAllowlist: ({ cfg }) => cfg,
+};
+
+export const twitchSetupAdapter: ChannelSetupAdapter = {
+  resolveAccountId: ({ cfg }) => resolveSetupAccountId(cfg),
+  applyAccountConfig: ({ cfg, accountId }) =>
+    setTwitchAccount(
+      cfg,
+      {
+        enabled: true,
+      },
+      accountId,
+    ),
+};
+
+export const twitchSetupWizard: ChannelSetupWizard = {
+  channel,
+  resolveAccountIdForConfigure: ({ cfg, accountOverride }) =>
+    resolveSetupAccountId(cfg, accountOverride),
+  resolveShouldPromptAccountIds: () => false,
+  status: {
+    configuredLabel: t("wizard.channels.statusConfigured"),
+    unconfiguredLabel: t("wizard.channels.statusNeedsUsernameTokenClientId"),
+    configuredHint: t("wizard.channels.statusConfigured"),
+    unconfiguredHint: t("wizard.channels.statusNeedsSetup"),
+    resolveConfigured: ({ cfg, accountId }) => {
+      return resolveTwitchAccountContext(cfg, resolveSetupAccountId(cfg, accountId)).configured;
+    },
+    resolveStatusLines: ({ cfg, accountId }) => {
+      const resolvedAccountId = resolveSetupAccountId(cfg, accountId);
+      const configured = resolveTwitchAccountContext(cfg, resolvedAccountId).configured;
+      return [
+        `Twitch${resolvedAccountId !== DEFAULT_ACCOUNT_ID ? ` (${resolvedAccountId})` : ""}: ${
+          configured
+            ? t("wizard.channels.statusConfigured")
+            : t("wizard.channels.statusNeedsUsernameTokenClientId")
+        }`,
+      ];
+    },
+  },
+  credentials: [],
+  finalize: async ({ cfg, accountId: requestedAccountId, prompter, forceAllowFrom }) => {
+    const accountId = resolveSetupAccountId(cfg, requestedAccountId);
+    const account = getAccountConfig(cfg, accountId);
+
+    if (!account || !isAccountConfigured(account)) {
+      await noteTwitchSetupHelp(prompter);
+    }
+
+    const envToken = process.env.AUTOBOT_TWITCH_ACCESS_TOKEN?.trim();
+
+    if (accountId === DEFAULT_ACCOUNT_ID && envToken && !account?.accessToken) {
+      const envResult = await configureWithEnvToken(
+        cfg,
+        prompter,
+        account,
+        envToken,
+        forceAllowFrom,
+        twitchDmPolicy,
+        accountId,
+      );
+      if (envResult) {
+        return envResult;
+      }
+    }
+
+    const username = await promptUsername(prompter, account);
+    const token = await promptToken(prompter, account, envToken);
+    const clientId = await promptClientId(prompter, account);
+    const channelName = await promptChannelName(prompter, account);
+    const { clientSecret, refreshToken } = await promptRefreshTokenSetup(prompter, account);
+
+    const cfgWithAccount = setTwitchAccount(
+      cfg,
+      {
+        username,
+        accessToken: token,
+        clientId,
+        channel: channelName,
+        clientSecret,
+        refreshToken,
+        enabled: true,
+      },
+      accountId,
+    );
+
+    const cfgWithAllowFrom =
+      forceAllowFrom && twitchDmPolicy.promptAllowFrom
+        ? await twitchDmPolicy.promptAllowFrom({ cfg: cfgWithAccount, prompter, accountId })
+        : cfgWithAccount;
+
+    return { cfg: cfgWithAllowFrom };
+  },
+  dmPolicy: twitchDmPolicy,
+  groupAccess: twitchGroupAccess,
+  disable: (cfg) => {
+    const twitch = (cfg.channels as Record<string, unknown>)?.twitch as
+      | Record<string, unknown>
+      | undefined;
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        twitch: { ...twitch, enabled: false },
+      },
+    };
+  },
+};
+
+type ResolvedTwitchAccount = TwitchAccountConfig & { accountId?: string | null };
+
+export const twitchSetupPlugin: ChannelPlugin<ResolvedTwitchAccount> = {
+  id: channel,
+  meta: getChatChannelMeta(channel),
+  capabilities: {
+    chatTypes: ["group"],
+  },
+  config: {
+    listAccountIds: (cfg) => listAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => {
+      const resolvedAccountId = normalizeAccountId(accountId ?? resolveDefaultTwitchAccountId(cfg));
+      const account = getAccountConfig(cfg, resolvedAccountId);
+      if (!account) {
+        return {
+          accountId: resolvedAccountId,
+          username: "",
+          accessToken: "",
+          clientId: "",
+          channel: "",
+          enabled: false,
+        };
+      }
+      return {
+        accountId: resolvedAccountId,
+        ...account,
+      };
+    },
+    defaultAccountId: (cfg) => resolveDefaultTwitchAccountId(cfg),
+    isConfigured: (account, cfg) => resolveTwitchAccountContext(cfg, account?.accountId).configured,
+    isEnabled: (account) => account.enabled !== false,
+  },
+  setup: twitchSetupAdapter,
+  setupWizard: twitchSetupWizard,
+};

package/src/status.ts

@@ -0,0 +1,179 @@
+/**
+ * Twitch status issues collector.
+ *
+ * Detects and reports configuration issues for Twitch accounts.
+ */
+
+import type { ChannelStatusIssue } from "autobot/plugin-sdk/channel-contract";
+import { getAccountConfig } from "./config.js";
+import { resolveTwitchToken } from "./token.js";
+import type { ChannelAccountSnapshot } from "./types.js";
+import { isAccountConfigured } from "./utils/twitch.js";
+
+/**
+ * Collect status issues for Twitch accounts.
+ *
+ * Analyzes account snapshots and detects configuration problems,
+ * authentication issues, and other potential problems.
+ *
+ * @param accounts - Array of account snapshots to analyze
+ * @param getCfg - Optional function to get full config for additional checks
+ * @returns Array of detected status issues
+ *
+ * @example
+ * const issues = collectTwitchStatusIssues(accountSnapshots);
+ * if (issues.length > 0) {
+ *   console.warn("Twitch configuration issues detected:");
+ *   issues.forEach(issue => console.warn(`- ${issue.message}`));
+ * }
+ */
+export function collectTwitchStatusIssues(
+  accounts: ChannelAccountSnapshot[],
+  getCfg?: () => unknown,
+): ChannelStatusIssue[] {
+  const issues: ChannelStatusIssue[] = [];
+
+  for (const entry of accounts) {
+    const accountId = entry.accountId;
+
+    if (!accountId) {
+      continue;
+    }
+
+    let account: ReturnType<typeof getAccountConfig> | null = null;
+    let cfg: Parameters<typeof resolveTwitchToken>[0] | undefined;
+    if (getCfg) {
+      try {
+        cfg = getCfg() as {
+          channels?: { twitch?: { accounts?: Record<string, unknown> } };
+        };
+        account = getAccountConfig(cfg, accountId);
+      } catch {
+        // Ignore config access errors
+      }
+    }
+
+    if (!entry.configured) {
+      issues.push({
+        channel: "twitch",
+        accountId,
+        kind: "config",
+        message: "Twitch account is not properly configured",
+        fix: "Add required fields: username, accessToken, and clientId to your account configuration",
+      });
+      continue;
+    }
+
+    if (entry.enabled === false) {
+      issues.push({
+        channel: "twitch",
+        accountId,
+        kind: "config",
+        message: "Twitch account is disabled",
+        fix: "Set enabled: true in your account configuration to enable this account",
+      });
+      continue;
+    }
+
+    if (account && account.username && account.accessToken && !account.clientId) {
+      issues.push({
+        channel: "twitch",
+        accountId,
+        kind: "config",
+        message: "Twitch client ID is required",
+        fix: "Add clientId to your Twitch account configuration (from Twitch Developer Portal)",
+      });
+    }
+
+    const tokenResolution = cfg
+      ? resolveTwitchToken(cfg as Parameters<typeof resolveTwitchToken>[0], { accountId })
+      : { token: "", source: "none" };
+    if (account && isAccountConfigured(account, tokenResolution.token)) {
+      if (account.accessToken?.startsWith("oauth:")) {
+        issues.push({
+          channel: "twitch",
+          accountId,
+          kind: "config",
+          message: "Token contains 'oauth:' prefix (will be stripped)",
+          fix: "The 'oauth:' prefix is optional. You can use just the token value, or keep it as-is (it will be normalized automatically).",
+        });
+      }
+
+      if (account.clientSecret && !account.refreshToken) {
+        issues.push({
+          channel: "twitch",
+          accountId,
+          kind: "config",
+          message: "clientSecret provided without refreshToken",
+          fix: "For automatic token refresh, provide both clientSecret and refreshToken. Otherwise, clientSecret is not needed.",
+        });
+      }
+
+      if (account.allowFrom && account.allowFrom.length === 0) {
+        issues.push({
+          channel: "twitch",
+          accountId,
+          kind: "config",
+          message: "allowFrom is configured but empty",
+          fix: "Either add user IDs to allowFrom, remove the allowFrom field, or use allowedRoles instead.",
+        });
+      }
+
+      if (
+        account.allowedRoles?.includes("all") &&
+        account.allowFrom &&
+        account.allowFrom.length > 0
+      ) {
+        issues.push({
+          channel: "twitch",
+          accountId,
+          kind: "intent",
+          message: "allowedRoles is set to 'all' but allowFrom is also configured",
+          fix: "When allowedRoles is 'all', the allowFrom list is not needed. Remove allowFrom or set allowedRoles to specific roles.",
+        });
+      }
+    }
+
+    if (entry.lastError) {
+      issues.push({
+        channel: "twitch",
+        accountId,
+        kind: "runtime",
+        message: `Last error: ${entry.lastError}`,
+        fix: "Check your token validity and network connection. Ensure the bot has the required OAuth scopes.",
+      });
+    }
+
+    if (
+      entry.configured &&
+      !entry.running &&
+      !entry.lastStartAt &&
+      !entry.lastInboundAt &&
+      !entry.lastOutboundAt
+    ) {
+      issues.push({
+        channel: "twitch",
+        accountId,
+        kind: "runtime",
+        message: "Account has never connected successfully",
+        fix: "Start the Twitch gateway to begin receiving messages. Check logs for connection errors.",
+      });
+    }
+
+    if (entry.running && entry.lastStartAt) {
+      const uptime = Date.now() - entry.lastStartAt;
+      const daysSinceStart = uptime / (1000 * 60 * 60 * 24);
+      if (daysSinceStart > 7) {
+        issues.push({
+          channel: "twitch",
+          accountId,
+          kind: "runtime",
+          message: `Connection has been running for ${Math.floor(daysSinceStart)} days`,
+          fix: "Consider restarting the connection periodically to refresh the connection. Twitch tokens may expire after long periods.",
+        });
+      }
+    }
+  }
+
+  return issues;
+}