@kodelyth/twitch 2026.5.39 → 2026.5.42

package/src/status.test.ts

@@ -0,0 +1,298 @@
+/**
+ * Tests for status.ts module
+ *
+ * Tests cover:
+ * - Detection of unconfigured accounts
+ * - Detection of disabled accounts
+ * - Detection of missing clientId
+ * - Token format warnings
+ * - Access control warnings
+ * - Runtime error detection
+ */
+
+import { describe, expect, it } from "vitest";
+import { collectTwitchStatusIssues } from "./status.js";
+import type { ChannelAccountSnapshot } from "./types.js";
+
+function createSnapshot(overrides: Partial<ChannelAccountSnapshot> = {}): ChannelAccountSnapshot {
+  return {
+    accountId: "default",
+    configured: true,
+    enabled: true,
+    running: false,
+    ...overrides,
+  };
+}
+
+function createSimpleTwitchConfig(overrides: Record<string, unknown>) {
+  return {
+    channels: {
+      twitch: overrides,
+    },
+  };
+}
+
+function expectSingleIssue(
+  issues: ReturnType<typeof collectTwitchStatusIssues>,
+  expected: ReturnType<typeof collectTwitchStatusIssues>[number],
+): void {
+  expect(issues).toEqual([expected]);
+}
+
+function expectIssues(
+  issues: ReturnType<typeof collectTwitchStatusIssues>,
+  expected: ReturnType<typeof collectTwitchStatusIssues>,
+): void {
+  expect(issues).toEqual(expected);
+}
+
+function neverConnectedIssue(): ReturnType<typeof collectTwitchStatusIssues>[number] {
+  return {
+    channel: "twitch",
+    accountId: "default",
+    kind: "runtime",
+    message: "Account has never connected successfully",
+    fix: "Start the Twitch gateway to begin receiving messages. Check logs for connection errors.",
+  };
+}
+
+describe("status", () => {
+  describe("collectTwitchStatusIssues", () => {
+    it("should detect unconfigured accounts", () => {
+      const snapshots: ChannelAccountSnapshot[] = [createSnapshot({ configured: false })];
+
+      const issues = collectTwitchStatusIssues(snapshots);
+
+      expectSingleIssue(issues, {
+        channel: "twitch",
+        accountId: "default",
+        kind: "config",
+        message: "Twitch account is not properly configured",
+        fix: "Add required fields: username, accessToken, and clientId to your account configuration",
+      });
+    });
+
+    it("should detect disabled accounts", () => {
+      const snapshots: ChannelAccountSnapshot[] = [createSnapshot({ enabled: false })];
+
+      const issues = collectTwitchStatusIssues(snapshots);
+
+      expectSingleIssue(issues, {
+        channel: "twitch",
+        accountId: "default",
+        kind: "config",
+        message: "Twitch account is disabled",
+        fix: "Set enabled: true in your account configuration to enable this account",
+      });
+    });
+
+    it("should detect missing clientId when account configured (simplified config)", () => {
+      const snapshots: ChannelAccountSnapshot[] = [createSnapshot()];
+      const mockCfg = createSimpleTwitchConfig({
+        username: "testbot",
+        accessToken: "oauth:test123",
+        // clientId missing
+      });
+
+      const issues = collectTwitchStatusIssues(snapshots, () => mockCfg as never);
+
+      expectIssues(issues, [
+        {
+          channel: "twitch",
+          accountId: "default",
+          kind: "config",
+          message: "Twitch client ID is required",
+          fix: "Add clientId to your Twitch account configuration (from Twitch Developer Portal)",
+        },
+        neverConnectedIssue(),
+      ]);
+    });
+
+    it("should warn about oauth: prefix in token (simplified config)", () => {
+      const snapshots: ChannelAccountSnapshot[] = [createSnapshot()];
+      const mockCfg = createSimpleTwitchConfig({
+        username: "testbot",
+        accessToken: "oauth:test123", // has prefix
+        clientId: "test-id",
+      });
+
+      const issues = collectTwitchStatusIssues(snapshots, () => mockCfg as never);
+
+      expectIssues(issues, [
+        {
+          channel: "twitch",
+          accountId: "default",
+          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).",
+        },
+        neverConnectedIssue(),
+      ]);
+    });
+
+    it("should detect clientSecret without refreshToken (simplified config)", () => {
+      const snapshots: ChannelAccountSnapshot[] = [createSnapshot()];
+      const mockCfg = createSimpleTwitchConfig({
+        username: "testbot",
+        accessToken: "oauth:test123",
+        clientId: "test-id",
+        clientSecret: "secret123",
+        // refreshToken missing
+      });
+
+      const issues = collectTwitchStatusIssues(snapshots, () => mockCfg as never);
+
+      expectIssues(issues, [
+        {
+          channel: "twitch",
+          accountId: "default",
+          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).",
+        },
+        {
+          channel: "twitch",
+          accountId: "default",
+          kind: "config",
+          message: "clientSecret provided without refreshToken",
+          fix: "For automatic token refresh, provide both clientSecret and refreshToken. Otherwise, clientSecret is not needed.",
+        },
+        neverConnectedIssue(),
+      ]);
+    });
+
+    it("should detect empty allowFrom array (simplified config)", () => {
+      const snapshots: ChannelAccountSnapshot[] = [createSnapshot()];
+      const mockCfg = createSimpleTwitchConfig({
+        username: "testbot",
+        accessToken: "test123",
+        clientId: "test-id",
+        allowFrom: [], // empty array
+      });
+
+      const issues = collectTwitchStatusIssues(snapshots, () => mockCfg as never);
+
+      expectIssues(issues, [
+        {
+          channel: "twitch",
+          accountId: "default",
+          kind: "config",
+          message: "allowFrom is configured but empty",
+          fix: "Either add user IDs to allowFrom, remove the allowFrom field, or use allowedRoles instead.",
+        },
+        neverConnectedIssue(),
+      ]);
+    });
+
+    it("should detect allowedRoles 'all' with allowFrom conflict (simplified config)", () => {
+      const snapshots: ChannelAccountSnapshot[] = [createSnapshot()];
+      const mockCfg = createSimpleTwitchConfig({
+        username: "testbot",
+        accessToken: "test123",
+        clientId: "test-id",
+        allowedRoles: ["all"],
+        allowFrom: ["123456"], // conflict!
+      });
+
+      const issues = collectTwitchStatusIssues(snapshots, () => mockCfg as never);
+
+      expectIssues(issues, [
+        {
+          channel: "twitch",
+          accountId: "default",
+          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.",
+        },
+        neverConnectedIssue(),
+      ]);
+    });
+
+    it("should detect runtime errors", () => {
+      const snapshots: ChannelAccountSnapshot[] = [
+        createSnapshot({ lastError: "Connection timeout" }),
+      ];
+
+      const issues = collectTwitchStatusIssues(snapshots);
+
+      expectIssues(issues, [
+        {
+          channel: "twitch",
+          accountId: "default",
+          kind: "runtime",
+          message: "Last error: Connection timeout",
+          fix: "Check your token validity and network connection. Ensure the bot has the required OAuth scopes.",
+        },
+        neverConnectedIssue(),
+      ]);
+    });
+
+    it("should detect accounts that never connected", () => {
+      const snapshots: ChannelAccountSnapshot[] = [
+        createSnapshot({
+          lastStartAt: undefined,
+          lastInboundAt: undefined,
+          lastOutboundAt: undefined,
+        }),
+      ];
+
+      const issues = collectTwitchStatusIssues(snapshots);
+
+      expectSingleIssue(issues, {
+        channel: "twitch",
+        accountId: "default",
+        kind: "runtime",
+        message: "Account has never connected successfully",
+        fix: "Start the Twitch gateway to begin receiving messages. Check logs for connection errors.",
+      });
+    });
+
+    it("should detect long-running connections", () => {
+      const oldDate = Date.now() - 8 * 24 * 60 * 60 * 1000; // 8 days ago
+
+      const snapshots: ChannelAccountSnapshot[] = [
+        createSnapshot({
+          running: true,
+          lastStartAt: oldDate,
+        }),
+      ];
+
+      const issues = collectTwitchStatusIssues(snapshots);
+
+      expectSingleIssue(issues, {
+        channel: "twitch",
+        accountId: "default",
+        kind: "runtime",
+        message: "Connection has been running for 8 days",
+        fix: "Consider restarting the connection periodically to refresh the connection. Twitch tokens may expire after long periods.",
+      });
+    });
+
+    it("should handle empty snapshots array", () => {
+      const issues = collectTwitchStatusIssues([]);
+
+      expect(issues).toStrictEqual([]);
+    });
+
+    it("should skip non-Twitch accounts gracefully", () => {
+      const snapshots: ChannelAccountSnapshot[] = [
+        {
+          accountId: "unknown",
+          configured: false,
+          enabled: true,
+          running: false,
+        },
+      ];
+
+      const issues = collectTwitchStatusIssues(snapshots);
+
+      expectSingleIssue(issues, {
+        channel: "twitch",
+        accountId: "unknown",
+        kind: "config",
+        message: "Twitch account is not properly configured",
+        fix: "Add required fields: username, accessToken, and clientId to your account configuration",
+      });
+    });
+  });
+});

package/src/status.ts

@@ -0,0 +1,179 @@
+/**
+ * Twitch status issues collector.
+ *
+ * Detects and reports configuration issues for Twitch accounts.
+ */
+
+import type { ChannelStatusIssue } from "klaw/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;
+}

package/src/test-fixtures.ts

@@ -0,0 +1,30 @@
+import { afterEach, beforeEach, vi } from "vitest";
+import type { KlawConfig } from "../runtime-api.js";
+
+export const BASE_TWITCH_TEST_ACCOUNT = {
+  username: "testbot",
+  clientId: "test-client-id",
+  channel: "#testchannel",
+};
+
+export function makeTwitchTestConfig(account: Record<string, unknown>): KlawConfig {
+  return {
+    channels: {
+      twitch: {
+        accounts: {
+          default: account,
+        },
+      },
+    },
+  } as unknown as KlawConfig;
+}
+
+export function installTwitchTestHooks() {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+}

package/src/token.test.ts

@@ -0,0 +1,198 @@
+/**
+ * Tests for token.ts module
+ *
+ * Tests cover:
+ * - Token resolution from config
+ * - Token resolution from environment variable
+ * - Fallback behavior when token not found
+ * - Account ID normalization
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { KlawConfig } from "../api.js";
+import { resolveTwitchToken, type TwitchTokenSource } from "./token.js";
+
+describe("token", () => {
+  const originalAccessToken = process.env.KLAW_TWITCH_ACCESS_TOKEN;
+
+  // Multi-account config for testing non-default accounts
+  const mockMultiAccountConfig = {
+    channels: {
+      twitch: {
+        accounts: {
+          default: {
+            username: "testbot",
+            accessToken: "oauth:config-token",
+          },
+          other: {
+            username: "otherbot",
+            accessToken: "oauth:other-token",
+          },
+        },
+      },
+    },
+  } as unknown as KlawConfig;
+
+  // Simplified single-account config
+  const mockSimplifiedConfig = {
+    channels: {
+      twitch: {
+        username: "testbot",
+        accessToken: "oauth:config-token",
+      },
+    },
+  } as unknown as KlawConfig;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    if (originalAccessToken === undefined) {
+      delete process.env.KLAW_TWITCH_ACCESS_TOKEN;
+    } else {
+      process.env.KLAW_TWITCH_ACCESS_TOKEN = originalAccessToken;
+    }
+  });
+
+  describe("resolveTwitchToken", () => {
+    it("should resolve token from simplified config for default account", () => {
+      const result = resolveTwitchToken(mockSimplifiedConfig, { accountId: "default" });
+
+      expect(result.token).toBe("oauth:config-token");
+      expect(result.source).toBe("config");
+    });
+
+    it("should resolve token from config for non-default account (multi-account)", () => {
+      const result = resolveTwitchToken(mockMultiAccountConfig, { accountId: "other" });
+
+      expect(result.token).toBe("oauth:other-token");
+      expect(result.source).toBe("config");
+    });
+
+    it("should resolve token from normalized account id", () => {
+      const result = resolveTwitchToken(
+        {
+          channels: {
+            twitch: {
+              accounts: {
+                Secondary: {
+                  username: "secondary",
+                  accessToken: "oauth:secondary-token",
+                },
+              },
+            },
+          },
+        } as unknown as KlawConfig,
+        { accountId: "secondary" },
+      );
+
+      expect(result.token).toBe("oauth:secondary-token");
+      expect(result.source).toBe("config");
+    });
+
+    it("should prioritize config token over env var (simplified config)", () => {
+      process.env.KLAW_TWITCH_ACCESS_TOKEN = "oauth:env-token";
+
+      const result = resolveTwitchToken(mockSimplifiedConfig, { accountId: "default" });
+
+      // Config token should be used even if env var exists
+      expect(result.token).toBe("oauth:config-token");
+      expect(result.source).toBe("config");
+    });
+
+    it("should use env var when config token is empty (simplified config)", () => {
+      process.env.KLAW_TWITCH_ACCESS_TOKEN = "oauth:env-token";
+
+      const configWithEmptyToken = {
+        channels: {
+          twitch: {
+            username: "testbot",
+            accessToken: "",
+          },
+        },
+      } as unknown as KlawConfig;
+
+      const result = resolveTwitchToken(configWithEmptyToken, { accountId: "default" });
+
+      expect(result.token).toBe("oauth:env-token");
+      expect(result.source).toBe("env");
+    });
+
+    it("should return empty token when neither config nor env has token (simplified config)", () => {
+      const configWithoutToken = {
+        channels: {
+          twitch: {
+            username: "testbot",
+            accessToken: "",
+          },
+        },
+      } as unknown as KlawConfig;
+
+      const result = resolveTwitchToken(configWithoutToken, { accountId: "default" });
+
+      expect(result.token).toBe("");
+      expect(result.source).toBe("none");
+    });
+
+    it("should not use env var for non-default accounts (multi-account)", () => {
+      process.env.KLAW_TWITCH_ACCESS_TOKEN = "oauth:env-token";
+
+      const configWithoutToken = {
+        channels: {
+          twitch: {
+            accounts: {
+              secondary: {
+                username: "secondary",
+                accessToken: "",
+              },
+            },
+          },
+        },
+      } as unknown as KlawConfig;
+
+      const result = resolveTwitchToken(configWithoutToken, { accountId: "secondary" });
+
+      // Non-default accounts shouldn't use env var
+      expect(result.token).toBe("");
+      expect(result.source).toBe("none");
+    });
+
+    it("should handle missing account gracefully", () => {
+      const configWithoutAccount = {
+        channels: {
+          twitch: {
+            accounts: {},
+          },
+        },
+      } as unknown as KlawConfig;
+
+      const result = resolveTwitchToken(configWithoutAccount, { accountId: "nonexistent" });
+
+      expect(result.token).toBe("");
+      expect(result.source).toBe("none");
+    });
+
+    it("should handle missing Twitch config section", () => {
+      const configWithoutSection = {
+        channels: {},
+      } as unknown as KlawConfig;
+
+      const result = resolveTwitchToken(configWithoutSection, { accountId: "default" });
+
+      expect(result.token).toBe("");
+      expect(result.source).toBe("none");
+    });
+  });
+
+  describe("TwitchTokenSource type", () => {
+    it("should have correct values", () => {
+      const sources: TwitchTokenSource[] = ["env", "config", "none"];
+
+      expect(sources).toContain("env");
+      expect(sources).toContain("config");
+      expect(sources).toContain("none");
+    });
+  });
+});