web/src/types.ts

// Ukweli — shared types

// --- API Response Types ---

export interface Report {
  report_id: string
  title: string
  slug: string
  source_url: string
  pdf_url: string | null
  pdf_filename: string | null
  report_type: string
  fiscal_year: string | null
  audit_period: string | null
  auditee: string | null
  auditee_type: string
  county_name: string | null
  page_count: number | null
  file_size_bytes: number | null
  content_hash: string | null
  audit_opinion: string | null
  published_date: string | null
  uploaded_date: string | null
  crawled_at: string
  status: string
  s3_url: string | null
}

export interface Citation {
  document_id: string
  title: string
  page: number
  paragraph: number
  url: string
  excerpt: string
}

export interface QueryResponse {
  answer: string
  citations: Citation[]
  retrieval_metadata: {
    chunks_considered: number
    latency_ms: number
    graph_entities_used: string[]
  }
  confidence: 'high' | 'medium' | 'low' | 'insufficient_context'
  suggested_followups: string[]
}

export interface ChatMessage {
  id: string
  role: 'user' | 'assistant' | 'system'
  content: string
  citations?: Citation[]
  confidence?: string
  timestamp: string
  isStreaming?: boolean
}

export interface GraphNode {
  id: string
  label: string
  type: 'auditee' | 'report' | 'finding' | 'legal' | 'amount'
  properties: Record<string, any>
}

export interface GraphEdge {
  source: string
  target: string
  type: string
  properties: Record<string, any>
}

export interface GraphData {
  nodes: GraphNode[]
  edges: GraphEdge[]
}

export interface SearchFilters {
  auditee?: string[]
  fy?: string[]
  report_type?: string[]
  finding_type?: string[]
  county?: string[]
}

export interface FeedbackPayload {
  query_id: string
  rating: number
  correction?: string
  suggested_citation?: string
}

export interface StreamEvent {
  event: 'retrieval' | 'citation' | 'delta' | 'done' | 'error'
  data: any
}

// --- Auth Types ---

export type AuthTier = 'public' | 'registered' | 'api' | 'enterprise'

export interface AuthUser {
  id: string
  email: string
  tier: AuthTier
  display_name: string | null
  organization: string | null
  created_at: string
}

export interface RateInfo {
  tier: AuthTier
  limit: number           // -1 = unlimited
  used: number
  remaining: number
  reset_at: string
  soft_warning?: boolean
}

export interface RegisterResponse {
  status: 'otp_sent'
  message: string
  expires_in_seconds: number
}

export interface TokenResponse {
  access_token: string
  token_type: 'bearer'
  expires_in: number
  user: AuthUser
  rate_info: RateInfo
}

export interface MeResponse {
  tier: AuthTier
  user: AuthUser | null
  rate_info: RateInfo
}

export interface ApiKeySummary {
  id: string
  key_id: string
  name: string
  description: string | null
  tier: AuthTier
  quota_per_day: number
  requests_today: number
  last_used_at: string | null
  status: 'active' | 'revoked' | 'expired'
  created_at: string
  expires_at: string | null
}

export interface ApiKeyCreateResponse extends ApiKeySummary {
  secret: string
  message: string
}

export interface ApiKeyListResponse {
  keys: ApiKeySummary[]
  total: number
}