kalshi-trading-bot-cli 2.1.0

package/src/utils/bot-config.ts

@@ -0,0 +1,219 @@
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+import { appPath } from './paths.js';
+
+export interface BotConfig {
+  scan: { interval: number; theme: string };
+  risk: {
+    kelly_multiplier: number;
+    min_edge_threshold: number;
+    max_position_pct: number;
+    max_spread_cents: number;
+    min_volume_24h: number;
+    liquidity_haircut: number;
+    liquidity_spread_threshold: number;
+    liquidity_volume_threshold: number;
+    max_drawdown: number;
+    max_positions: number;
+    max_per_category: number;
+    daily_loss_limit: number;
+  };
+  octagon: { daily_credit_ceiling: number; price_move_threshold: number };
+  alerts: { min_edge: number; channels: string[] };
+  watch: { min_interval_minutes: number; ticker_interval_seconds: number };
+  gateway: { whatsapp: { enabled: boolean } };
+}
+
+const DEFAULTS: BotConfig = {
+  scan: { interval: 60, theme: 'top50' },
+  risk: { kelly_multiplier: 0.5, min_edge_threshold: 0.05, max_position_pct: 0.10, max_spread_cents: 5, min_volume_24h: 500, liquidity_haircut: 0.50, liquidity_spread_threshold: 3, liquidity_volume_threshold: 1000, max_drawdown: 0.20, max_positions: 10, max_per_category: 3, daily_loss_limit: 200 },
+  octagon: { daily_credit_ceiling: 100, price_move_threshold: 0.05 },
+  alerts: { min_edge: 0.05, channels: ['terminal'] },
+  watch: { min_interval_minutes: 15, ticker_interval_seconds: 5 },
+  gateway: { whatsapp: { enabled: false } },
+};
+
+const CONFIG_PATH = appPath('config.json');
+
+// In-memory cache to avoid re-reading config.json on every getBotSetting call
+let _cachedConfig: BotConfig | null = null;
+
+function deepMerge(defaults: Record<string, unknown>, overrides: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = { ...defaults };
+  for (const key of Object.keys(overrides)) {
+    if (
+      result[key] !== null &&
+      typeof result[key] === 'object' &&
+      !Array.isArray(result[key]) &&
+      typeof overrides[key] === 'object' &&
+      overrides[key] !== null &&
+      !Array.isArray(overrides[key])
+    ) {
+      result[key] = deepMerge(result[key] as Record<string, unknown>, overrides[key] as Record<string, unknown>);
+    } else {
+      result[key] = overrides[key];
+    }
+  }
+  return result;
+}
+
+export function loadBotConfig(): BotConfig {
+  if (_cachedConfig) return _cachedConfig;
+  try {
+    const raw = readFileSync(CONFIG_PATH, 'utf-8');
+    const parsed = JSON.parse(raw);
+    _cachedConfig = deepMerge(DEFAULTS as unknown as Record<string, unknown>, parsed) as unknown as BotConfig;
+    return _cachedConfig;
+  } catch {
+    _cachedConfig = structuredClone(DEFAULTS);
+    return _cachedConfig;
+  }
+}
+
+export function saveBotConfig(config: BotConfig): boolean {
+  try {
+    mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+    writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+    _cachedConfig = config;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function walkGet(obj: Record<string, unknown>, keys: string[]): unknown {
+  let current: unknown = obj;
+  for (const k of keys) {
+    if (current === null || typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[k];
+  }
+  return current;
+}
+
+function walkSet(obj: Record<string, unknown>, keys: string[], value: unknown): void {
+  let current: Record<string, unknown> = obj;
+  for (let i = 0; i < keys.length - 1; i++) {
+    if (typeof current[keys[i]] !== 'object' || current[keys[i]] === null) {
+      current[keys[i]] = {};
+    }
+    current = current[keys[i]] as Record<string, unknown>;
+  }
+  current[keys[keys.length - 1]] = value;
+}
+
+export function getBotSetting(dotKey: string): unknown {
+  const config = loadBotConfig();
+  const keys = dotKey.split('.');
+  return walkGet(config as unknown as Record<string, unknown>, keys);
+}
+
+const NUMERIC_VALIDATORS: Record<string, (v: number) => string | null> = {
+  'watch.min_interval_minutes': (v) => v > 0 ? null : 'must be > 0',
+  'watch.ticker_interval_seconds': (v) => v > 0 ? null : 'must be > 0',
+  'scan.interval': (v) => v > 0 ? null : 'must be > 0',
+  'risk.min_edge_threshold': (v) => v >= 0 && v <= 1 ? null : 'must be between 0 and 1',
+  'risk.max_position_pct': (v) => v > 0 && v <= 1 ? null : 'must be between 0 and 1',
+  'risk.liquidity_haircut': (v) => v >= 0 && v <= 1 ? null : 'must be between 0 and 1',
+  'risk.max_drawdown': (v) => v > 0 && v <= 1 ? null : 'must be between 0 and 1',
+  'risk.kelly_multiplier': (v) => v > 0 && v <= 1 ? null : 'must be between 0 and 1',
+  'risk.daily_loss_limit': (v) => v > 0 ? null : 'must be > 0',
+  'risk.max_spread_cents': (v) => v >= 0 ? null : 'must be >= 0',
+  'risk.min_volume_24h': (v) => v >= 0 ? null : 'must be >= 0',
+  'risk.max_positions': (v) => v > 0 && Number.isInteger(v) ? null : 'must be a positive integer',
+  'risk.max_per_category': (v) => v > 0 && Number.isInteger(v) ? null : 'must be a positive integer',
+  'octagon.price_move_threshold': (v) => v >= 0 && v <= 1 ? null : 'must be between 0 and 1',
+  'octagon.daily_credit_ceiling': (v) => v >= 0 ? null : 'must be >= 0',
+  'alerts.min_edge': (v) => v >= 0 && v <= 1 ? null : 'must be between 0 and 1',
+};
+
+export function setBotSetting(dotKey: string, rawValue: string): { oldValue: unknown; newValue: unknown } {
+  const keys = dotKey.split('.');
+  const defaultValue = walkGet(DEFAULTS as unknown as Record<string, unknown>, keys);
+  if (defaultValue === undefined) {
+    throw new Error(`Unknown config key: ${dotKey}`);
+  }
+
+  let newValue: unknown;
+  const defaultType = typeof defaultValue;
+  if (defaultType === 'number') {
+    newValue = Number(rawValue);
+    if (isNaN(newValue as number)) throw new Error(`Invalid number for ${dotKey}: ${rawValue}`);
+    const validator = NUMERIC_VALIDATORS[dotKey];
+    if (validator) {
+      const err = validator(newValue as number);
+      if (err) throw new Error(`Invalid value for ${dotKey}: ${rawValue} (${err})`);
+    }
+  } else if (defaultType === 'boolean') {
+    const lower = rawValue.toLowerCase();
+    if (lower !== 'true' && lower !== 'false') {
+      throw new Error(`Invalid boolean for ${dotKey}: ${rawValue} (expected 'true' or 'false')`);
+    }
+    newValue = lower === 'true';
+  } else if (Array.isArray(defaultValue)) {
+    try {
+      newValue = JSON.parse(rawValue);
+    } catch {
+      throw new Error(`Invalid JSON for ${dotKey}: ${rawValue}`);
+    }
+    if (!Array.isArray(newValue)) {
+      throw new Error(`Expected JSON array for ${dotKey}: ${rawValue}`);
+    }
+  } else {
+    newValue = rawValue;
+  }
+
+  const config = loadBotConfig();
+  const oldValue = walkGet(config as unknown as Record<string, unknown>, keys);
+  walkSet(config as unknown as Record<string, unknown>, keys, newValue);
+  saveBotConfig(config);
+
+  return { oldValue, newValue };
+}
+
+export interface FlatSetting {
+  key: string;
+  value: unknown;
+  default: unknown;
+  isDefault: boolean;
+}
+
+function flatten(
+  obj: Record<string, unknown>,
+  defaults: Record<string, unknown>,
+  prefix: string,
+  result: FlatSetting[],
+): void {
+  for (const key of Object.keys(defaults)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    const val = obj[key];
+    const def = defaults[key];
+
+    if (def !== null && typeof def === 'object' && !Array.isArray(def)) {
+      flatten(
+        (val ?? {}) as Record<string, unknown>,
+        def as Record<string, unknown>,
+        fullKey,
+        result,
+      );
+    } else {
+      result.push({
+        key: fullKey,
+        value: val ?? def,
+        default: def,
+        isDefault: JSON.stringify(val ?? def) === JSON.stringify(def),
+      });
+    }
+  }
+}
+
+export function getAllSettings(): FlatSetting[] {
+  const config = loadBotConfig();
+  const result: FlatSetting[] = [];
+  flatten(
+    config as unknown as Record<string, unknown>,
+    DEFAULTS as unknown as Record<string, unknown>,
+    '',
+    result,
+  );
+  return result;
+}

package/src/utils/cache.ts

@@ -0,0 +1,195 @@
+/**
+ * Local file cache for API responses.
+ *
+ * Pure storage layer — knows HOW to cache, not WHAT to cache.
+ * Callers opt in by passing `{ cacheable: true }` to API calls;
+ * the cache module unconditionally stores and retrieves keyed JSON.
+ *
+ * Cache files live in the app cache directory (gitignored).
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'fs';
+import { join, dirname } from 'path';
+import { createHash } from 'crypto';
+import { logger } from './logger.js';
+import { appPath } from './paths.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * A persisted cache entry.
+ * Stores enough context to validate freshness and aid debugging.
+ */
+interface CacheEntry {
+  endpoint: string;
+  params: Record<string, unknown>;
+  data: Record<string, unknown>;
+  url: string;
+  cachedAt: string;
+}
+
+const CACHE_DIR = appPath('cache');
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Build a human-readable label for log messages.
+ * If params contains a 'ticker' field, includes it for readability.
+ * Also appends all other defined params as key=value pairs.
+ * Example: "/prices/ (AAPL) interval=day limit=30" or "/search/ query=earnings"
+ */
+export function describeRequest(
+  endpoint: string,
+  params: Record<string, string | number | string[] | undefined>
+): string {
+  const ticker = typeof params.ticker === 'string' ? params.ticker.toUpperCase() : null;
+  const base = ticker ? `${endpoint} (${ticker})` : endpoint;
+  const extraParams = Object.entries(params)
+    .filter(([key, value]) => key !== 'ticker' && value !== undefined && value !== null)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, value]) => `${key}=${Array.isArray(value) ? value.join(',') : String(value)}`);
+  return extraParams.length > 0 ? `${base} ${extraParams.join(' ')}` : base;
+}
+
+/**
+ * Generate a deterministic cache key from endpoint + params.
+ * Params are sorted alphabetically so insertion order doesn't matter.
+ *
+ * If params contains a 'ticker' field, it's used as a prefix for human-readable filenames.
+ * Resulting path:  {clean_endpoint}/{TICKER_}{hash}.json (if ticker present)
+ *                  {clean_endpoint}/{hash}.json (otherwise)
+ * Example:         prices/AAPL_a1b2c3d4e5f6.json
+ */
+export function buildCacheKey(
+  endpoint: string,
+  params: Record<string, string | number | string[] | undefined>
+): string {
+  // Build a canonical string from sorted, non-empty params
+  const sortedParams = Object.entries(params)
+    .filter(([, v]) => v !== undefined && v !== null)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([k, v]) => `${k}=${Array.isArray(v) ? [...v].sort().join(',') : v}`)
+    .join('&');
+
+  const raw = `${endpoint}?${sortedParams}`;
+  const hash = createHash('md5').update(raw).digest('hex').slice(0, 12);
+
+  // Turn "/prices/" → "prices"
+  const cleanEndpoint = endpoint
+    .replace(/^\//, '')
+    .replace(/\/$/, '')
+    .replace(/\//g, '_');
+
+  // Prefix with ticker when available for human-readable filenames (optional)
+  const ticker = typeof params.ticker === 'string' ? params.ticker.toUpperCase() : null;
+  const prefix = ticker ? `${ticker}_` : '';
+
+  return `${cleanEndpoint}/${prefix}${hash}.json`;
+}
+
+/**
+ * Validate that a parsed object has the shape of a CacheEntry.
+ * Guards against truncated writes, schema changes, or manual edits.
+ */
+function isValidCacheEntry(value: unknown): value is CacheEntry {
+  if (typeof value !== 'object' || value === null) return false;
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj.endpoint === 'string' &&
+    typeof obj.url === 'string' &&
+    typeof obj.cachedAt === 'string' &&
+    typeof obj.data === 'object' &&
+    obj.data !== null
+  );
+}
+
+/**
+ * Safely remove a cache file (e.g. when it's corrupted).
+ * Logs on failure but never throws.
+ */
+function removeCacheFile(filepath: string): void {
+  try {
+    unlinkSync(filepath);
+  } catch {
+    // Best-effort cleanup — not critical
+  }
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Read a cached API response if it exists.
+ * Returns null on cache miss or any read/parse error.
+ */
+export function readCache(
+  endpoint: string,
+  params: Record<string, string | number | string[] | undefined>
+): { data: Record<string, unknown>; url: string } | null {
+  const cacheKey = buildCacheKey(endpoint, params);
+  const filepath = join(CACHE_DIR, cacheKey);
+  const label = describeRequest(endpoint, params);
+
+  if (!existsSync(filepath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(filepath, 'utf-8');
+    const parsed: unknown = JSON.parse(content);
+
+    // Validate entry structure
+    if (!isValidCacheEntry(parsed)) {
+      logger.warn(`Cache corrupted (invalid structure): ${label}`, { filepath });
+      removeCacheFile(filepath);
+      return null;
+    }
+
+    return { data: parsed.data, url: parsed.url };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.warn(`Cache read error: ${label} — ${message}`, { filepath });
+    // Remove corrupted file so subsequent calls don't hit the same error
+    removeCacheFile(filepath);
+    return null;
+  }
+}
+
+/**
+ * Write an API response to the cache.
+ * Logs on I/O errors but never throws — cache writes must not
+ * break the application.
+ */
+export function writeCache(
+  endpoint: string,
+  params: Record<string, string | number | string[] | undefined>,
+  data: Record<string, unknown>,
+  url: string
+): void {
+  const cacheKey = buildCacheKey(endpoint, params);
+  const filepath = join(CACHE_DIR, cacheKey);
+  const label = describeRequest(endpoint, params);
+
+  const entry: CacheEntry = {
+    endpoint,
+    params,
+    data,
+    url,
+    cachedAt: new Date().toISOString(),
+  };
+
+  try {
+    const dir = dirname(filepath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(filepath, JSON.stringify(entry, null, 2));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.warn(`Cache write error: ${label} — ${message}`, { filepath });
+  }
+}

package/src/utils/config.ts

@@ -0,0 +1,113 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+import { appPath } from './paths.js';
+
+const SETTINGS_FILE = appPath('settings.json');
+
+// Map legacy model IDs to provider IDs for migration
+const MODEL_TO_PROVIDER_MAP: Record<string, string> = {
+  'gpt-5.4': 'openai',
+  'gpt-5.2': 'openai',
+  'claude-sonnet-4-5': 'anthropic',
+  'gemini-3': 'google',
+};
+
+// Deprecated model IDs to upgrade on load
+const DEPRECATED_MODEL_UPGRADES: Record<string, string> = {
+  'gpt-5.2': 'gpt-5.4',
+};
+
+interface Config {
+  provider?: string;
+  modelId?: string;  // Selected model ID (e.g., "gpt-5.4", "ollama:llama3.1")
+  model?: string;    // Legacy key, kept for migration
+  anonymousId?: string;  // Persistent anonymous ID for telemetry
+  memory?: {
+    enabled?: boolean;
+    embeddingProvider?: 'openai' | 'gemini' | 'ollama' | 'auto';
+    embeddingModel?: string;
+    maxSessionContextTokens?: number;
+  };
+  [key: string]: unknown;
+}
+
+export function loadConfig(): Config {
+  if (!existsSync(SETTINGS_FILE)) {
+    return {};
+  }
+
+  try {
+    const content = readFileSync(SETTINGS_FILE, 'utf-8');
+    let config = JSON.parse(content) as Config;
+
+    // Upgrade deprecated model IDs (e.g. gpt-5.2 -> gpt-5.4)
+    if (config.modelId && DEPRECATED_MODEL_UPGRADES[config.modelId]) {
+      config.modelId = DEPRECATED_MODEL_UPGRADES[config.modelId];
+      saveConfig(config);
+    }
+
+    return config;
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(config: Config): boolean {
+  try {
+    const dir = dirname(SETTINGS_FILE);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(SETTINGS_FILE, JSON.stringify(config, null, 2));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Migrates legacy `model` setting to `provider` setting.
+ * Called once on config load to ensure backwards compatibility.
+ */
+function migrateModelToProvider(config: Config): Config {
+  // If already has provider, no migration needed
+  if (config.provider) {
+    return config;
+  }
+
+  // If has legacy model setting, convert to provider
+  if (config.model) {
+    const providerId = MODEL_TO_PROVIDER_MAP[config.model];
+    if (providerId) {
+      config.provider = providerId;
+      delete config.model;
+      // Save the migrated config
+      saveConfig(config);
+    }
+  }
+
+  return config;
+}
+
+export function getSetting<T>(key: string, defaultValue: T): T {
+  let config = loadConfig();
+  
+  // Run migration if accessing provider setting
+  if (key === 'provider') {
+    config = migrateModelToProvider(config);
+  }
+  
+  return (config[key] as T) ?? defaultValue;
+}
+
+export function setSetting(key: string, value: unknown): boolean {
+  const config = loadConfig();
+  config[key] = value;
+  
+  // If setting provider, remove legacy model key
+  if (key === 'provider' && config.model) {
+    delete config.model;
+  }
+  
+  return saveConfig(config);
+}

package/src/utils/env.ts

@@ -0,0 +1,111 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { config } from 'dotenv';
+import { getProviderById } from '@/providers';
+import { appPath, getAppDir } from './paths.js';
+
+// Resolve .env from a CWD override (dev workflow) or the home config dir
+// (default for `bunx` / global installs). The home path is also where
+// `saveApiKeyToEnv` writes new keys.
+const HOME_ENV_PATH = appPath('.env');
+const CWD_ENV_PATH = resolve(process.cwd(), '.env');
+export const ENV_PATH = existsSync(CWD_ENV_PATH) ? CWD_ENV_PATH : HOME_ENV_PATH;
+
+// Load .env on module import
+config({ path: ENV_PATH, quiet: true });
+
+export function getApiKeyNameForProvider(providerId: string): string | undefined {
+  return getProviderById(providerId)?.apiKeyEnvVar;
+}
+
+export function getProviderDisplayName(providerId: string): string {
+  return getProviderById(providerId)?.displayName ?? providerId;
+}
+
+export function checkApiKeyExistsForProvider(providerId: string): boolean {
+  const apiKeyName = getApiKeyNameForProvider(providerId);
+  if (!apiKeyName) return true;
+  return checkApiKeyExists(apiKeyName);
+}
+
+export function checkApiKeyExists(apiKeyName: string): boolean {
+  const value = process.env[apiKeyName];
+  if (value && value.trim() && !value.trim().startsWith('your-')) {
+    return true;
+  }
+
+  // Also check .env file directly
+  if (existsSync(ENV_PATH)) {
+    const envContent = readFileSync(ENV_PATH, 'utf-8');
+    const lines = envContent.split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed && !trimmed.startsWith('#') && trimmed.includes('=')) {
+        const [key, ...valueParts] = trimmed.split('=');
+        if (key.trim() === apiKeyName) {
+          const val = valueParts.join('=').trim();
+          if (val && !val.startsWith('your-')) {
+            return true;
+          }
+        }
+      }
+    }
+  }
+
+  return false;
+}
+
+export function saveApiKeyToEnv(apiKeyName: string, apiKeyValue: string): boolean {
+  try {
+    let lines: string[] = [];
+    let keyUpdated = false;
+
+    if (existsSync(ENV_PATH)) {
+      const existingContent = readFileSync(ENV_PATH, 'utf-8');
+      const existingLines = existingContent.split('\n');
+
+      for (const line of existingLines) {
+        const stripped = line.trim();
+        if (!stripped || stripped.startsWith('#')) {
+          lines.push(line);
+        } else if (stripped.includes('=')) {
+          const key = stripped.split('=')[0].trim();
+          if (key === apiKeyName) {
+            lines.push(`${apiKeyName}=${apiKeyValue}`);
+            keyUpdated = true;
+          } else {
+            lines.push(line);
+          }
+        } else {
+          lines.push(line);
+        }
+      }
+
+      if (!keyUpdated) {
+        if (lines.length > 0 && !lines[lines.length - 1].endsWith('\n')) {
+          lines.push('');
+        }
+        lines.push(`${apiKeyName}=${apiKeyValue}`);
+      }
+    } else {
+      lines.push('# LLM API Keys');
+      lines.push(`${apiKeyName}=${apiKeyValue}`);
+    }
+
+    mkdirSync(getAppDir(), { recursive: true });
+    writeFileSync(ENV_PATH, lines.join('\n'));
+
+    // Reload environment variables
+    config({ path: ENV_PATH, override: true, quiet: true });
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function saveApiKeyForProvider(providerId: string, apiKey: string): boolean {
+  const apiKeyName = getApiKeyNameForProvider(providerId);
+  if (!apiKeyName) return false;
+  return saveApiKeyToEnv(apiKeyName, apiKey);
+}