API

type Side = 'buy' | 'sell'
type Tier = 'strong' | 'notable' | 'moderate' | 'weak'

interface CompanyRef { cik: string; ticker: string | null; name: string; exchange?: string | null; sic?: string | null }
interface InsiderRef { cik: string; name: string; roles: string[]; title: string | null }
interface ScoreComponent { key: string; label: string; points: number; detail: string }

interface PriceContext {
  as_of: string               // date of the close used
  close: number | null
  low_52w: number | null
  high_52w: number | null
  from_low_pct: number | null // (close - low) / low
  from_high_pct: number | null // (close - high) / high, negative
}

interface Outcome { horizon: '1m' | '3m' | '6m'; n: number; median_return: number | null; mean_return: number | null; hit_rate: number | null }

interface Signal {
  id: string
  accession: string
  filed_at: string            // ISO 8601, UTC
  trade_date: string          // earliest transaction date in the signal
  side: Side
  score: number               // 0..100
  tier: Tier
  company: CompanyRef
  insider: InsiderRef
  shares: number
  value_usd: number
  avg_price: number | null
  holdings_after: number | null
  holdings_change_pct: number | null
  is_10b5_1: boolean
  cluster: { insiders: number; window_days: 14; signal_ids: string[] } | null
  price: PriceContext | null
  components: ScoreComponent[]
  outcomes?: Outcome[]        // comparable past signals, same side and tier
  returns?: { '1m': number | null; '3m': number | null; '6m': number | null }
  filing_url: string
}

interface Transaction {
  id: string
  accession: string
  filed_at: string
  date: string
  company: CompanyRef
  insider: InsiderRef
  code: string                // P, S, A, M, F, G, D, C, X, J, ...
  code_label: string
  derivative: boolean
  security_title: string
  acquired: boolean
  shares: number | null
  price: number | null
  value_usd: number | null
  holdings_after: number | null
  ownership: 'D' | 'I'
  ownership_nature: string | null
  is_10b5_1: boolean
  signal_id: string | null
  filing_url: string
}

// Congressional trades (STOCK Act periodic transaction reports)
interface CongressMemberRef { id: string; name: string; party: string | null; state: string | null; slug: string | null }

interface CongressTrade {
  id: string
  report_id: string
  source: 'house' | 'senate'
  chamber: 'house' | 'senate'
  member: CongressMemberRef
  filed_at: string            // the day the report was filed
  trade_date: string | null
  days_to_report: number | null
  owner: 'self' | 'spouse' | 'joint' | 'child' | null
  ticker: string | null       // only for common stock with a ticker
  raw_ticker: string | null   // as filed, for options and the like
  is_stock: boolean
  asset_name: string
  asset_code: string | null   // House two-letter asset code (ST, OP, GS, ...)
  asset_type: string | null   // Senate asset type text
  type: 'purchase' | 'sale' | 'sale_partial' | 'exchange' | null
  amount_min: number | null   // the range as filed
  amount_max: number | null   // null means "over amount_min"
  description: string | null
  comment: string | null
  url: string                 // the source report
  returns: { pending: boolean; '1m': { ret: number; excess: number | null } | null; '3m': ...; '6m': ... } | null
}

interface CongressMember {
  id: string                  // bioguide id, or chamber:slug for an unmatched filer
  slug: string
  name: string
  chamber: 'house' | 'senate'
  state: string | null
  district: number | null
  party: string | null
  in_office: boolean | null
  matched: boolean
  image_url: string | null
  stats: { trades: number; trades_365d: number; purchases: number; sales: number; exchanges: number; reports: number; tickers: number; amount_min: number; amount_max: number; first_filed_at: string | null; last_filed_at: string | null }
  track_record: { n: number; median_6m_excess: number | null; hit_rate_6m: number | null; label: 'strong' | 'positive' | 'negative' | 'unknown' }
}