kalshi-trading-bot-cli 2.1.3 → 2.1.5

package/src/commands/catalysts.ts

@@ -0,0 +1,121 @@
+/**
+ * `catalysts upcoming [--days N]` — list active Kalshi markets sorted by
+ * close_time within the next N days. Group by week so the user can scan an
+ * event-calendar view.
+ *
+ * Pure composition over /kalshi/markets — no new endpoint needed.
+ */
+import { wrapSuccess, wrapError } from './json.js';
+import type { CLIResponse } from './json.js';
+import type { ParsedArgs } from './parse-args.js';
+import { fetchUniverse } from './series.js';
+import { formatTable } from './scan-formatters.js';
+
+function truncate(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+
+function fmtVol(v: number | null | undefined): string {
+  if (v === null || v === undefined) return '-';
+  if (v >= 1_000_000) return `${(v / 1_000_000).toFixed(1)}M`;
+  if (v >= 1_000) return `${(v / 1_000).toFixed(1)}k`;
+  return v.toFixed(0);
+}
+
+function isoWeek(d: Date): string {
+  // Return YYYY-MM-DD of the Monday of the ISO week.
+  const tmp = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+  const day = tmp.getUTCDay() || 7;
+  if (day !== 1) tmp.setUTCDate(tmp.getUTCDate() - (day - 1));
+  return tmp.toISOString().slice(0, 10);
+}
+
+export interface CatalystRow {
+  market_ticker: string;
+  series_prefix: string;
+  title: string;
+  category: string | null;
+  close_time: string;
+  volume_24h: number | null;
+}
+
+export interface CatalystsResult {
+  days: number;
+  weeks: Array<{ week_starting: string; markets: CatalystRow[] }>;
+  total: number;
+}
+
+export async function handleCatalysts(args: ParsedArgs): Promise<CLIResponse<CatalystsResult>> {
+  const sub = args.positionalArgs[0]?.toLowerCase() ?? 'upcoming';
+  if (sub !== 'upcoming') {
+    return wrapError('catalysts', 'UNKNOWN_SUB', `Unknown subcommand "${sub}". Try: catalysts upcoming [--days N]`);
+  }
+  const days = args.days ?? 30;
+  const now = new Date();
+  const cutoff = new Date(now.getTime() + days * 86_400_000);
+
+  try {
+    const universe = await fetchUniverse({
+      close_before: cutoff.toISOString(),
+      min_volume_24h: args.minVolume,
+      category: args.category,
+    });
+    // Filter to markets that close in the future window
+    const candidates = universe
+      .filter((m) => m.close_time && new Date(m.close_time) > now)
+      .map<CatalystRow>((m) => ({
+        market_ticker: m.market_ticker,
+        series_prefix: m.market_ticker.split('-')[0],
+        title: m.title,
+        category: m.category ?? null,
+        close_time: m.close_time as string,
+        volume_24h: m.volume_24h ?? null,
+      }))
+      .sort((a, b) => a.close_time.localeCompare(b.close_time));
+
+    // Group by ISO week of close_time
+    const buckets = new Map<string, CatalystRow[]>();
+    for (const c of candidates) {
+      const week = isoWeek(new Date(c.close_time));
+      const arr = buckets.get(week) ?? [];
+      arr.push(c);
+      buckets.set(week, arr);
+    }
+    const limit = args.limit ?? 8;
+    const weeks = Array.from(buckets.entries())
+      .sort((a, b) => a[0].localeCompare(b[0]))
+      .map(([week_starting, markets]) => ({
+        week_starting,
+        markets: markets
+          .sort((a, b) => (b.volume_24h ?? 0) - (a.volume_24h ?? 0))
+          .slice(0, limit),
+      }));
+    return wrapSuccess('catalysts', { days, weeks, total: candidates.length });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return wrapError('catalysts', 'OCTAGON_ERROR', message);
+  }
+}
+
+export function formatCatalystsHuman(result: CatalystsResult): string {
+  const lines: string[] = [];
+  lines.push(`Upcoming catalysts — next ${result.days} days, ${result.total} markets across ${result.weeks.length} weeks`);
+  lines.push('');
+  if (result.weeks.length === 0) {
+    lines.push('No markets closing in that window.');
+    return lines.join('\n');
+  }
+  for (const w of result.weeks) {
+    lines.push(`Week of ${w.week_starting} — ${w.markets.length} markets`);
+    const rows: string[][] = w.markets.map((m) => [
+      m.market_ticker,
+      truncate(m.title, 45),
+      m.close_time.slice(0, 16).replace('T', ' '),
+      fmtVol(m.volume_24h),
+      m.category ?? '-',
+    ]);
+    lines.push(formatTable(['Market', 'Title', 'Closes (UTC)', '24h Vol', 'Category'], rows));
+    lines.push('');
+  }
+  return lines.join('\n');
+}

package/src/commands/clusters.ts

@@ -0,0 +1,153 @@
+import { wrapSuccess, wrapError } from './json.js';
+import type { CLIResponse } from './json.js';
+import type { ParsedArgs } from './parse-args.js';
+import {
+  listClusters,
+  listBehavioralClusters,
+  getClusterMarkets,
+  getBehavioralClusterMarkets,
+  getClustersRankedByReturn,
+  type ClusterRow,
+  type PagedResult,
+  type SimilarMarketRow,
+  type RankedClustersResponse,
+} from '../scan/octagon-kalshi-api.js';
+import { formatTable } from './scan-formatters.js';
+
+function truncate(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+
+function fmtPct(v: number): string {
+  return `${(v * 100).toFixed(1)}%`;
+}
+
+export type ClustersResult =
+  | { kind: 'list'; behavioral: boolean; data: ClusterRow[] }
+  | { kind: 'members'; behavioral: boolean; cluster_id: number; markets: PagedResult<SimilarMarketRow> }
+  | { kind: 'ranked'; data: RankedClustersResponse };
+
+export async function handleClusters(args: ParsedArgs): Promise<CLIResponse<ClustersResult>> {
+  try {
+    if (args.ranked) {
+      const data = await getClustersRankedByReturn({
+        timeframe: args.timeframe,
+        min_return: args.minReturn,
+        top_n_per_cluster: args.topK,
+        kind: args.behavioral ? 'behavioral' : 'thematic',
+        max_clusters: args.limit,
+      });
+      return wrapSuccess('clusters', { kind: 'ranked', data });
+    }
+
+    const positional = args.positionalArgs[0];
+    if (positional !== undefined && /^\d+$/.test(positional)) {
+      const clusterId = Number(positional);
+      const markets = args.behavioral
+        ? await getBehavioralClusterMarkets(clusterId, { limit: args.limit })
+        : await getClusterMarkets(clusterId, { limit: args.limit });
+      return wrapSuccess('clusters', { kind: 'members', behavioral: args.behavioral, cluster_id: clusterId, markets });
+    }
+
+    const params = {
+      limit: args.limit,
+      sample_titles: 3,
+      label_contains: args.labelContains,
+    };
+    const data = args.behavioral
+      ? await listBehavioralClusters(params)
+      : await listClusters(params);
+    return wrapSuccess('clusters', { kind: 'list', behavioral: args.behavioral, data: data.data });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return wrapError('clusters', 'OCTAGON_ERROR', message);
+  }
+}
+
+export function formatClustersHuman(result: ClustersResult): string {
+  if (result.kind === 'list') return formatClusterList(result.data, result.behavioral);
+  if (result.kind === 'members') return formatClusterMembers(result.cluster_id, result.markets, result.behavioral);
+  return formatRankedClusters(result.data);
+}
+
+function formatClusterList(clusters: ClusterRow[], behavioral: boolean): string {
+  const lines: string[] = [];
+  const kindLabel = behavioral ? 'Behavioral' : 'Thematic';
+  lines.push(`${kindLabel} clusters — ${clusters.length} result(s)`);
+  lines.push('');
+
+  if (clusters.length === 0) {
+    lines.push('No clusters found.');
+    return lines.join('\n');
+  }
+
+  const headers = behavioral
+    ? ['ID', 'Label', 'Size', 'Mean Ret', 'Vol', 'Sample']
+    : ['ID', 'Label', 'Size', 'Sample'];
+
+  const rows: string[][] = clusters.map((c) => {
+    const sample = truncate(c.sample_titles[0] ?? '-', 50);
+    if (behavioral) {
+      return [
+        String(c.cluster_id),
+        truncate(c.label, 30),
+        String(c.size),
+        c.mean_daily_return != null ? fmtPct(c.mean_daily_return) : '-',
+        c.daily_volatility != null ? fmtPct(c.daily_volatility) : '-',
+        sample,
+      ];
+    }
+    return [String(c.cluster_id), truncate(c.label, 30), String(c.size), sample];
+  });
+
+  lines.push(formatTable(headers, rows));
+  lines.push('');
+  lines.push(`Use "clusters <id>${behavioral ? ' --behavioral' : ''}" to list members.`);
+  return lines.join('\n');
+}
+
+function formatClusterMembers(clusterId: number, page: PagedResult<SimilarMarketRow>, behavioral: boolean): string {
+  const lines: string[] = [];
+  const kindLabel = behavioral ? 'behavioral' : 'thematic';
+  lines.push(`Markets in ${kindLabel} cluster ${clusterId} — ${page.data.length} shown${page.has_more ? ' (more available)' : ''}`);
+  lines.push('');
+
+  if (page.data.length === 0) {
+    lines.push('No markets in this cluster.');
+    return lines.join('\n');
+  }
+
+  const rows: string[][] = page.data.map((m) => [
+    m.market_ticker,
+    truncate(m.title, 45),
+    m.distance != null ? m.distance.toFixed(3) : '-',
+    m.category ?? '-',
+  ]);
+
+  lines.push(formatTable(['Ticker', 'Title', 'Distance', 'Category'], rows));
+  return lines.join('\n');
+}
+
+function formatRankedClusters(data: RankedClustersResponse): string {
+  const lines: string[] = [];
+  lines.push(`Clusters ranked by ${data.timeframe} return (${data.kind}, top ${data.top_n_per_cluster} per cluster, min return ${(data.min_return * 100).toFixed(1)}%)`);
+  lines.push('');
+
+  if (data.data.length === 0) {
+    lines.push('No clusters meet the threshold.');
+    return lines.join('\n');
+  }
+
+  const rows: string[][] = data.data.map((c) => [
+    String(c.cluster_id),
+    truncate(c.label, 30),
+    String(c.size),
+    fmtPct(c.summary.total_return),
+    c.summary.sharpe != null ? c.summary.sharpe.toFixed(2) : '-',
+    fmtPct(c.summary.max_drawdown),
+    fmtPct(c.summary.win_rate),
+  ]);
+
+  lines.push(formatTable(['ID', 'Label', 'Size', 'Total Ret', 'Sharpe', 'Max DD', 'Win%'], rows));
+  return lines.join('\n');
+}

package/src/commands/correlate.ts

@@ -0,0 +1,112 @@
+import { wrapSuccess, wrapError } from './json.js';
+import type { CLIResponse } from './json.js';
+import type { ParsedArgs } from './parse-args.js';
+import { getCorrelations, type CorrelationResponseWithSides } from '../scan/octagon-kalshi-api.js';
+import { formatTable } from './scan-formatters.js';
+
+function shortTicker(t: string, max = 18): string {
+  return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+}
+
+function collectTickers(args: ParsedArgs): string[] {
+  const set = new Set<string>();
+  for (const p of args.positionalArgs) {
+    const upper = p.toUpperCase();
+    if (upper) set.add(upper);
+  }
+  if (args.tickers) {
+    for (const t of args.tickers.split(',')) {
+      const upper = t.trim().toUpperCase();
+      if (upper) set.add(upper);
+    }
+  }
+  return Array.from(set);
+}
+
+export async function handleCorrelate(args: ParsedArgs): Promise<CLIResponse<CorrelationResponseWithSides>> {
+  const tickers = collectTickers(args);
+  if (tickers.length < 2) {
+    return wrapError(
+      'correlate',
+      'TOO_FEW_TICKERS',
+      'Usage: correlate <ticker1> <ticker2> [...] [--window-days N] [--sides yes,no,yes] [--cells]',
+    );
+  }
+  if (tickers.length > 100) {
+    return wrapError('correlate', 'TOO_MANY_TICKERS', 'At most 100 tickers allowed.');
+  }
+
+  // --sides yes,no,yes — must match ticker count (server enforces this too)
+  let sides: ('yes' | 'no')[] | undefined;
+  if (args.sides) {
+    sides = args.sides.split(',').map((s) => (s.trim().toLowerCase() === 'no' ? 'no' : 'yes'));
+    if (sides.length !== tickers.length) {
+      return wrapError('correlate', 'SIDES_MISMATCH',
+        `--sides has ${sides.length} entries but ${tickers.length} tickers were supplied.`);
+    }
+  }
+
+  try {
+    const data = await getCorrelations({
+      market_tickers: tickers,
+      sides,
+      include_cell_detail: args.cells || undefined,
+      window_days: args.windowDays,
+      interval: args.correlationInterval,
+    });
+    return wrapSuccess('correlate', data);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return wrapError('correlate', 'OCTAGON_ERROR', message);
+  }
+}
+
+export function formatCorrelationHuman(data: CorrelationResponseWithSides): string {
+  const lines: string[] = [];
+  const sidesLabel = data.sides ? ` (sides: ${data.sides.join(',')})` : '';
+  lines.push(`Correlation matrix — ${data.tickers.length} markets${sidesLabel}, ${data.window_days}d window, interval ${data.interval}`);
+  if (data.missing.length > 0) {
+    lines.push(`  Dropped (no candle data): ${data.missing.join(', ')}`);
+  }
+  lines.push('');
+
+  if (data.tickers.length === 0) {
+    lines.push('No matrix available — all tickers were missing candle data.');
+    return lines.join('\n');
+  }
+
+  // Matrix table — header row of short tickers, body of correlation values.
+  const headerRow: string[][] = [['', ...data.tickers.map((t) => shortTicker(t, 14))]];
+  const bodyRows: string[][] = data.matrix.map((row, i) => [
+    shortTicker(data.tickers[i] ?? '?', 14),
+    ...row.map((v) => (v == null ? '-' : v.toFixed(2))),
+  ]);
+  lines.push(formatTable(headerRow[0], bodyRows));
+
+  if (data.ranked_pairs.length > 0) {
+    lines.push('');
+    lines.push('Most-uncorrelated pairs (ascending):');
+    const topN = data.ranked_pairs.slice(0, 10);
+    const rows: string[][] = topN.map((p) => [
+      shortTicker(p.ticker_a, 22),
+      shortTicker(p.ticker_b, 22),
+      p.correlation.toFixed(3),
+    ]);
+    lines.push(formatTable(['Ticker A', 'Ticker B', 'Corr'], rows));
+  }
+
+  if (data.cells_detail && data.cells_detail.length > 0) {
+    lines.push('');
+    lines.push('Cell detail:');
+    const rows: string[][] = data.cells_detail.map((c) => [
+      shortTicker(c.ticker_a, 20),
+      shortTicker(c.ticker_b, 20),
+      c.correlation == null ? '-' : c.correlation.toFixed(3),
+      String(c.overlap_count),
+      c.reason,
+    ]);
+    lines.push(formatTable(['Ticker A', 'Ticker B', 'Corr', 'Overlap', 'Reason'], rows));
+  }
+
+  return lines.join('\n');
+}