@tokentop/ttop 0.4.0 → 0.6.0

package/src/utils/__tests__/error-category.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, test } from "bun:test";
+import { classifyProviderError } from "../error-category.ts";
+
+describe("classifyProviderError", () => {
+  describe("auth errors", () => {
+    test("classifies expired token errors", () => {
+      expect(classifyProviderError("Token expired. Run any command in OpenCode to refresh.")).toBe(
+        "auth",
+      );
+      expect(
+        classifyProviderError(
+          "Token expired or invalid. Re-authenticate in OpenCode or Claude Code.",
+        ),
+      ).toBe("auth");
+      expect(classifyProviderError("OAuth token expired. Re-authenticate in OpenCode.")).toBe(
+        "auth",
+      );
+      expect(
+        classifyProviderError("OAuth token expired or invalid. Re-authenticate in OpenCode."),
+      ).toBe("auth");
+      expect(
+        classifyProviderError("OAuth token expired or invalid. Re-authenticate via Gemini CLI."),
+      ).toBe("auth");
+      expect(classifyProviderError("Claude Code token expired")).toBe("auth");
+    });
+
+    test("classifies scope errors", () => {
+      expect(
+        classifyProviderError(
+          "Token lacks required scope. Re-authenticate in OpenCode or Claude Code.",
+        ),
+      ).toBe("auth");
+    });
+
+    test("classifies missing credential errors", () => {
+      expect(
+        classifyProviderError(
+          "OAuth token or API key required. Authenticate via OpenCode or Claude Code.",
+        ),
+      ).toBe("auth");
+      expect(
+        classifyProviderError(
+          "OAuth token required. Sign in via OpenCode with ChatGPT Pro account.",
+        ),
+      ).toBe("auth");
+      expect(
+        classifyProviderError("OAuth token required. Sign in via OpenCode with Google account."),
+      ).toBe("auth");
+      expect(
+        classifyProviderError("OAuth token required. Login via Gemini CLI with Google account."),
+      ).toBe("auth");
+      expect(
+        classifyProviderError("API key required. Set OPENAI_API_KEY environment variable."),
+      ).toBe("auth");
+      expect(
+        classifyProviderError("API key required. Set PERPLEXITY_API_KEY environment variable."),
+      ).toBe("auth");
+      expect(classifyProviderError("API key required. Configure MiniMax in OpenCode.")).toBe(
+        "auth",
+      );
+      expect(classifyProviderError("API key required. Configure Chutes in OpenCode.")).toBe("auth");
+      expect(classifyProviderError("API key required. Configure Z.ai in OpenCode.")).toBe("auth");
+      expect(
+        classifyProviderError("API key required. Run /connect in OpenCode to set up Zen."),
+      ).toBe("auth");
+    });
+
+    test("classifies authorization failure errors", () => {
+      expect(classifyProviderError("Authorization failed. Check your MiniMax API key.")).toBe(
+        "auth",
+      );
+      expect(classifyProviderError("Authorization failed. Check your Chutes API key.")).toBe(
+        "auth",
+      );
+      expect(classifyProviderError("Authorization failed. Check your Z.ai API key.")).toBe("auth");
+    });
+
+    test("classifies invalid key errors", () => {
+      expect(classifyProviderError("Invalid API key")).toBe("auth");
+      expect(classifyProviderError("Unauthorized – check API key")).toBe("auth");
+    });
+
+    test("classifies HTTP status code auth errors", () => {
+      expect(classifyProviderError("API error: 401 Unauthorized")).toBe("auth");
+      expect(classifyProviderError("API error: 403 Forbidden")).toBe("auth");
+      expect(classifyProviderError("Authentication failed (401). Check API key.")).toBe("auth");
+    });
+
+    test("classifies not-configured errors", () => {
+      expect(classifyProviderError("Not configured: missing GitHub token")).toBe("auth");
+      expect(classifyProviderError("Copilot not enabled for this account")).toBe("auth");
+    });
+
+    test("classifies refresh failure errors", () => {
+      expect(classifyProviderError("No valid access token and refresh failed.")).toBe("auth");
+      expect(
+        classifyProviderError("ChatGPT account ID required. Re-authenticate in OpenCode."),
+      ).toBe("auth");
+      expect(
+        classifyProviderError(
+          "MiniMax groupId required. Set MINIMAX_GROUP_ID or configure in OpenCode.",
+        ),
+      ).toBe("auth");
+    });
+  });
+
+  describe("rate limit errors", () => {
+    test("classifies rate limit errors", () => {
+      expect(classifyProviderError("Rate limited")).toBe("rate_limit");
+      expect(classifyProviderError("API error: 429 Too Many Requests")).toBe("rate_limit");
+    });
+  });
+
+  describe("insufficient credits errors", () => {
+    test("classifies insufficient credits errors", () => {
+      expect(classifyProviderError("Insufficient credits")).toBe("insufficient_credits");
+    });
+  });
+
+  describe("timeout errors", () => {
+    test("classifies timeout errors", () => {
+      expect(classifyProviderError("The operation timed out")).toBe("timeout");
+      expect(classifyProviderError("Request timeout")).toBe("timeout");
+      expect(classifyProviderError("ETIMEDOUT")).toBe("timeout");
+      expect(classifyProviderError("Request aborted")).toBe("timeout");
+    });
+  });
+
+  describe("network errors", () => {
+    test("classifies network errors", () => {
+      expect(classifyProviderError("fetch failed")).toBe("network");
+      expect(classifyProviderError("ECONNREFUSED")).toBe("network");
+      expect(classifyProviderError("ENOTFOUND")).toBe("network");
+      expect(classifyProviderError("ECONNRESET")).toBe("network");
+      expect(classifyProviderError("DNS resolution failed")).toBe("network");
+      expect(classifyProviderError("Network error")).toBe("network");
+    });
+  });
+
+  describe("unknown errors", () => {
+    test("classifies unrecognized errors as unknown", () => {
+      expect(classifyProviderError("Unknown error")).toBe("unknown");
+      expect(classifyProviderError("API error: 500 Internal Server Error")).toBe("unknown");
+      expect(classifyProviderError("Something went wrong")).toBe("unknown");
+    });
+  });
+});

package/src/utils/currency.ts

@@ -26,7 +26,9 @@ export function parseCurrencyInput(input: string): number | null {
   } else if (hasComma) {
     const parts = normalized.split(",");
     // 3 digits after comma = thousands separator (1,234), otherwise decimal (10,50)
-    if (parts.length === 2 && parts[1]!.length === 3 && parts[0]!.length > 0) {
+    const afterComma = parts[1]?.length ?? 0;
+    const beforeComma = parts[0]?.length ?? 0;
+    if (parts.length === 2 && afterComma === 3 && beforeComma > 0) {
       normalized = normalized.replace(",", "");
     } else {
       normalized = normalized.replace(",", ".");
@@ -35,7 +37,7 @@ export function parseCurrencyInput(input: string): number | null {
 
   const parsed = parseFloat(normalized);
 
-  if (isNaN(parsed) || !isFinite(parsed)) {
+  if (Number.isNaN(parsed) || !Number.isFinite(parsed)) {
     return null;
   }
 

package/src/utils/error-category.ts

@@ -0,0 +1,91 @@
+export type ProviderErrorCategory =
+  | "auth"
+  | "rate_limit"
+  | "timeout"
+  | "network"
+  | "insufficient_credits"
+  | "unknown";
+
+export function classifyProviderError(error: string): ProviderErrorCategory {
+  const lower = error.toLowerCase();
+
+  // Auth errors: expired tokens, invalid credentials, scope issues
+  if (
+    lower.includes("expired") ||
+    lower.includes("re-authenticate") ||
+    lower.includes("invalid") ||
+    lower.includes("unauthorized") ||
+    lower.includes("scope") ||
+    lower.includes("authentication failed") ||
+    lower.includes("authorization failed") ||
+    lower.includes("check api key") ||
+    lower.includes("api key required") ||
+    lower.includes("token required") ||
+    lower.includes("not configured") ||
+    lower.includes("sign in") ||
+    lower.includes("refresh failed") ||
+    lower.includes("not enabled") ||
+    lower.includes("configure") ||
+    /\b401\b/.test(lower) ||
+    /\b403\b/.test(lower)
+  ) {
+    return "auth";
+  }
+
+  // Rate limits
+  if (
+    lower.includes("rate limit") ||
+    lower.includes("too many requests") ||
+    /\b429\b/.test(lower)
+  ) {
+    return "rate_limit";
+  }
+
+  // Insufficient credits
+  if (lower.includes("insufficient") || lower.includes("credits") || /\b402\b/.test(lower)) {
+    return "insufficient_credits";
+  }
+
+  // Timeouts
+  if (
+    lower.includes("timeout") ||
+    lower.includes("timed out") ||
+    lower.includes("etimedout") ||
+    lower.includes("aborted")
+  ) {
+    return "timeout";
+  }
+
+  // Network errors
+  if (
+    lower.includes("econnrefused") ||
+    lower.includes("enotfound") ||
+    lower.includes("network") ||
+    lower.includes("fetch failed") ||
+    lower.includes("dns") ||
+    lower.includes("econnreset")
+  ) {
+    return "network";
+  }
+
+  return "unknown";
+}
+
+interface ErrorCategoryDisplay {
+  label: string;
+  icon: string;
+  isWarning: boolean;
+}
+
+const CATEGORY_DISPLAY: Record<ProviderErrorCategory, ErrorCategoryDisplay> = {
+  auth: { label: "AUTH", icon: "\u26B7", isWarning: true },
+  rate_limit: { label: "RATE", icon: "\u29D7", isWarning: true },
+  timeout: { label: "TIME", icon: "\u29D7", isWarning: true },
+  insufficient_credits: { label: "CRED", icon: "\u2717", isWarning: true },
+  network: { label: "NET", icon: "\u2717", isWarning: false },
+  unknown: { label: "ERR", icon: "\u2717", isWarning: false },
+};
+
+export function getErrorCategoryDisplay(category: ProviderErrorCategory): ErrorCategoryDisplay {
+  return CATEGORY_DISPLAY[category];
+}

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = "0.4.0"; // x-release-please-version
+export const VERSION = "0.6.0"; // x-release-please-version

package/src/plugins/types/agent.ts

@@ -1,108 +0,0 @@
-import { z } from "zod";
-import type { BasePlugin, PluginHttpClient, PluginLogger } from "./base.ts";
-import type { Credentials, OAuthCredentials, PluginContext } from "./provider.ts";
-
-export const AgentCapabilitiesSchema = z.object({
-  sessionParsing: z.boolean(),
-  authReading: z.boolean(),
-  realTimeTracking: z.boolean(),
-  multiProvider: z.boolean(),
-});
-
-export type AgentCapabilities = z.infer<typeof AgentCapabilitiesSchema>;
-
-export interface AgentConfig {
-  /** Display name for this coding agent (e.g. "OpenCode", "Cursor"). */
-  name: string;
-  /** CLI command that launches the agent (for display/detection). */
-  command?: string;
-  /** Path to the agent's config directory (for display/debugging). */
-  configPath?: string;
-  /** Path to the agent's session storage. */
-  sessionPath?: string;
-  /** Path to the agent's auth file (for credential reading). */
-  authPath?: string;
-}
-
-export interface AgentCredentials {
-  providers: Record<string, Credentials | undefined>;
-  oauth?: Record<string, OAuthCredentials>;
-}
-
-export interface AgentProviderConfig {
-  id: string;
-  name: string;
-  configured: boolean;
-  enabled?: boolean;
-}
-
-export interface SessionParseOptions {
-  sessionId?: string;
-  timePeriod?: "session" | "daily" | "weekly" | "monthly";
-  limit?: number;
-  /** Epoch ms — only return sessions updated after this timestamp. */
-  since?: number;
-}
-
-export interface SessionUsageData {
-  sessionId: string;
-  sessionName?: string;
-  providerId: string;
-  modelId: string;
-  tokens: {
-    input: number;
-    output: number;
-    cacheRead?: number;
-    cacheWrite?: number;
-  };
-  timestamp: number;
-  sessionUpdatedAt?: number;
-  projectPath?: string;
-  cost?: number;
-}
-
-export interface AgentFetchContext {
-  readonly http: PluginHttpClient;
-  readonly logger: PluginLogger;
-  readonly config: Record<string, unknown>;
-  readonly signal: AbortSignal;
-}
-
-export interface ActivityUpdate {
-  sessionId: string;
-  messageId: string;
-  tokens: {
-    input: number;
-    output: number;
-    reasoning?: number;
-    cacheRead?: number;
-    cacheWrite?: number;
-  };
-  timestamp: number;
-}
-
-export type ActivityCallback = (update: ActivityUpdate) => void;
-
-export interface AgentPlugin extends BasePlugin {
-  readonly type: "agent";
-  readonly agent: AgentConfig;
-  readonly capabilities: AgentCapabilities;
-
-  /** Check if this coding agent is installed on the user's machine. */
-  isInstalled(ctx: PluginContext): Promise<boolean>;
-
-  /** Read credentials that the coding agent has stored. */
-  readCredentials?(ctx: AgentFetchContext): Promise<AgentCredentials>;
-
-  /** Parse session usage data from the agent's local storage. */
-  parseSessions(options: SessionParseOptions, ctx: AgentFetchContext): Promise<SessionUsageData[]>;
-
-  /** List which model providers this agent is configured to use. */
-  getProviders?(ctx: AgentFetchContext): Promise<AgentProviderConfig[]>;
-
-  /** Start watching for real-time activity updates. */
-  startActivityWatch?(ctx: PluginContext, callback: ActivityCallback): void;
-
-  /** Stop watching for real-time activity updates. */
-  stopActivityWatch?(ctx: PluginContext): void;
-}

package/src/plugins/types/base.ts

@@ -1,278 +0,0 @@
-/**
- * Base plugin types and interfaces for the tokentop plugin system.
- *
- * These types mirror the Plugin SDK (@tokentop/plugin-sdk) — the SDK is the
- * authoritative contract for community developers; core adapts to match.
- */
-
-import { z } from "zod";
-
-// ---------------------------------------------------------------------------
-// Identity
-// ---------------------------------------------------------------------------
-
-/**
- * Plugin type discriminator
- */
-export type PluginType = "provider" | "agent" | "theme" | "notification";
-
-/**
- * Current API contract version.
- * Core checks this at load time to ensure compatibility.
- */
-export const CURRENT_API_VERSION = 2;
-
-// ---------------------------------------------------------------------------
-// Permissions
-// ---------------------------------------------------------------------------
-
-/**
- * Plugin permissions schema - defines what a plugin can access
- */
-export const PluginPermissionsSchema = z.object({
-  network: z
-    .object({
-      enabled: z.boolean(),
-      allowedDomains: z.array(z.string()).optional(),
-    })
-    .optional(),
-  filesystem: z
-    .object({
-      read: z.boolean().optional(),
-      write: z.boolean().optional(),
-      paths: z.array(z.string()).optional(),
-    })
-    .optional(),
-  env: z
-    .object({
-      read: z.boolean().optional(),
-      vars: z.array(z.string()).optional(),
-    })
-    .optional(),
-  system: z
-    .object({
-      notifications: z.boolean().optional(),
-      clipboard: z.boolean().optional(),
-    })
-    .optional(),
-});
-
-export type PluginPermissions = z.infer<typeof PluginPermissionsSchema>;
-
-// ---------------------------------------------------------------------------
-// Metadata
-// ---------------------------------------------------------------------------
-
-/**
- * Plugin metadata
- */
-export const PluginMetaSchema = z.object({
-  author: z.string().optional(),
-  description: z.string().optional(),
-  homepage: z.string().url().optional(),
-  repository: z.string().url().optional(),
-  license: z.string().optional(),
-  /**
-   * Brand color as a hex string (e.g. `"#d97757"`).
-   * Used by the TUI for provider cards, charts, and status indicators.
-   */
-  brandColor: z.string().optional(),
-  /**
-   * Single-character icon or short glyph for compact displays.
-   * Example: `"◆"`, `"▲"`, `"⚡"`
-   */
-  icon: z.string().optional(),
-  /**
-   * Additional provider IDs that should resolve to this plugin.
-   * Coding agents may tag sessions with provider IDs that differ from
-   * the plugin's `id` (e.g. OpenCode uses `"openai"` but the plugin
-   * registers as `"openai-api"`). List those alternate IDs here so the
-   * TUI can resolve brand colors and other metadata correctly.
-   */
-  providerAliases: z.array(z.string()).optional(),
-});
-
-export type PluginMeta = z.infer<typeof PluginMetaSchema>;
-
-// ---------------------------------------------------------------------------
-// Configuration
-// ---------------------------------------------------------------------------
-
-/**
- * Plugin configuration field definition (for plugin settings UI)
- */
-export interface ConfigField {
-  /** Data type of the setting value. */
-  type: "string" | "number" | "boolean" | "select";
-  /** Label shown in the settings UI. */
-  label?: string;
-  /** Help text shown below the field. */
-  description?: string;
-  /** Whether the field must have a value. */
-  required?: boolean;
-  /** Default value when no user config exists. */
-  default?: unknown;
-  /** Available options (for `select` type only). */
-  options?: Array<{ value: string; label: string }>;
-  /** Minimum value (for `number` type only). */
-  min?: number;
-  /** Maximum value (for `number` type only). */
-  max?: number;
-}
-
-// ---------------------------------------------------------------------------
-// Lifecycle Context
-// ---------------------------------------------------------------------------
-
-/**
- * Minimal context provided to lifecycle hooks.
- */
-export interface PluginLifecycleContext {
-  /** Plugin's validated configuration values. */
-  readonly config: Record<string, unknown>;
-  /** Scoped logger that prefixes all output with the plugin ID. */
-  readonly logger: PluginLogger;
-}
-
-// ---------------------------------------------------------------------------
-// Base Plugin
-// ---------------------------------------------------------------------------
-
-/**
- * Base plugin interface - all plugins must implement this.
- *
- * Provides identity, metadata, permissions, optional configuration schema,
- * and lifecycle hooks.
- */
-export interface BasePlugin {
-  /** API version this plugin targets. Must equal {@link CURRENT_API_VERSION}. */
-  readonly apiVersion: 2;
-
-  /** Unique plugin identifier (kebab-case) */
-  readonly id: string;
-
-  /** Plugin type discriminator */
-  readonly type: PluginType;
-
-  /** Human-readable display name */
-  readonly name: string;
-
-  /** Semantic version string */
-  readonly version: string;
-
-  /** Plugin metadata */
-  readonly meta?: PluginMeta;
-
-  /** Required permissions */
-  readonly permissions: PluginPermissions;
-
-  /** Plugin-declared configuration fields, rendered in Settings UI */
-  readonly configSchema?: Record<string, ConfigField>;
-
-  /**
-   * Default config values. Used when no user configuration exists.
-   * Keys must match those in {@link configSchema}.
-   */
-  readonly defaultConfig?: Record<string, unknown>;
-
-  // -- Lifecycle Hooks (all optional) -------------------------------------
-
-  /**
-   * Called once after the plugin is loaded and validated.
-   * Use for one-time setup (open connections, allocate resources).
-   */
-  initialize?(ctx: PluginLifecycleContext): Promise<void>;
-
-  /**
-   * Called when the plugin should begin active work (e.g. polling).
-   * Called after `initialize()` during app startup, and after re-enable.
-   */
-  start?(ctx: PluginLifecycleContext): Promise<void>;
-
-  /**
-   * Called when the plugin should pause active work.
-   * Called before `destroy()` during app shutdown, and on disable.
-   */
-  stop?(ctx: PluginLifecycleContext): Promise<void>;
-
-  /**
-   * Called once before the plugin is unloaded.
-   * Use for cleanup (close connections, flush buffers).
-   */
-  destroy?(ctx: PluginLifecycleContext): Promise<void>;
-
-  /**
-   * Called when the user changes this plugin's configuration.
-   * Receive the new validated config values.
-   */
-  onConfigChange?(
-    config: Record<string, unknown>,
-    ctx: PluginLifecycleContext,
-  ): Promise<void> | void;
-}
-
-// ---------------------------------------------------------------------------
-// Logger
-// ---------------------------------------------------------------------------
-
-/**
- * Logger interface provided to plugins
- */
-export interface PluginLogger {
-  debug(message: string, data?: Record<string, unknown>): void;
-  info(message: string, data?: Record<string, unknown>): void;
-  warn(message: string, data?: Record<string, unknown>): void;
-  error(message: string, data?: Record<string, unknown>): void;
-}
-
-// ---------------------------------------------------------------------------
-// HTTP Client
-// ---------------------------------------------------------------------------
-
-/**
- * HTTP client interface provided to plugins (sandboxed)
- */
-export interface PluginHttpClient {
-  fetch(url: string, init?: RequestInit): Promise<Response>;
-}
-
-// ---------------------------------------------------------------------------
-// Validation
-// ---------------------------------------------------------------------------
-
-/**
- * Plugin validation result
- */
-export interface PluginValidationResult {
-  valid: boolean;
-  errors: string[];
-  warnings: string[];
-}
-
-/**
- * Plugin load result
- */
-export interface PluginLoadResult<T extends BasePlugin = BasePlugin> {
-  success: boolean;
-  plugin?: T;
-  error?: string;
-  source: "builtin" | "local" | "npm";
-}
-
-// ---------------------------------------------------------------------------
-// Errors
-// ---------------------------------------------------------------------------
-
-/**
- * Plugin permission error
- */
-export class PluginPermissionError extends Error {
-  constructor(
-    public readonly pluginId: string,
-    public readonly permission: keyof PluginPermissions,
-    message: string,
-  ) {
-    super(`Plugin "${pluginId}" permission denied: ${message}`);
-    this.name = "PluginPermissionError";
-  }
-}

package/src/plugins/types/index.ts

@@ -1,19 +0,0 @@
-export * from "./agent.ts";
-export * from "./base.ts";
-export * from "./notification.ts";
-export * from "./provider.ts";
-export * from "./theme.ts";
-
-import type { AgentPlugin } from "./agent.ts";
-import type { NotificationPlugin } from "./notification.ts";
-import type { ProviderPlugin } from "./provider.ts";
-import type { ThemePlugin } from "./theme.ts";
-
-export type AnyPlugin = ProviderPlugin | AgentPlugin | ThemePlugin | NotificationPlugin;
-
-export type PluginByType = {
-  provider: ProviderPlugin;
-  agent: AgentPlugin;
-  theme: ThemePlugin;
-  notification: NotificationPlugin;
-};