TypeScript Types

// Base API response wrapper
interface ApiResponse<T> {
  success: boolean;
  data: T;
  meta: ResponseMeta;
}

// Response metadata
interface ResponseMeta {
  request_id: string;
  response_time_ms: number;
  cache_hit?: boolean;
  cache_ttl?: number;
  fetched_at?: string;
}

// Error response
interface ApiError {
  success: false;
  error: {
    code: string;
    message: string;
    details?: Record<string, unknown>;
  };
  meta: {
    request_id: string;
  };
}

interface ExtractResponse {
  url: string;
  resolved_url: string;
  title: string | null;
  description: string | null;
  image: string | null;

  open_graph: OpenGraphData;
  twitter: TwitterCardData;
  meta: MetaData;
  article: ArticleData;
  icons: IconData[];
}

interface OpenGraphData {
  title: string | null;
  description: string | null;
  image: string | null;
  url: string | null;
  type: string | null;
  site_name: string | null;
  locale: string | null;
}

interface TwitterCardData {
  card: 'summary' | 'summary_large_image' | 'app' | 'player' | null;
  site: string | null;
  creator: string | null;
  title: string | null;
  description: string | null;
  image: string | null;
}

interface MetaData {
  author: string | null;
  keywords: string[];
  theme_color: string | null;
  canonical_url: string | null;
  favicon: string | null;
  language: string | null;
  charset: string | null;
}

interface ArticleData {
  published_time: string | null;
  modified_time: string | null;
  author: string | null;
  section: string | null;
  tags: string[];
}

interface IconData {
  url: string;
  type: string | null;
  sizes: string | null;
}

interface ValidateResponse {
  url: string;
  valid: boolean;
  score: number;
  grade: 'A' | 'B' | 'C' | 'D' | 'F';

  checks: Record<string, ValidationCheck>;
  warnings: string[];
  recommendations: Recommendation[];
  preview: PreviewPlatforms;
}

interface ValidationCheck {
  present: boolean;
  valid: boolean;
  value?: string;
  url?: string;
  length?: number;
  accessible?: boolean;
  dimensions?: { width: number; height: number };
  matches_canonical?: boolean;
  recommendation: string | null;
}

interface Recommendation {
  priority: 'high' | 'medium' | 'low';
  tag: string;
  message: string;
  suggested_value?: string;
}

interface PreviewPlatforms {
  facebook: SocialPreview;
  twitter: SocialPreview;
  linkedin: SocialPreview;
}

interface SocialPreview {
  title: string;
  description: string;
  image: string | null;
}

interface TechResponse {
  url: string;
  technologies: Technology[];
  categories: TechCategory[];
  summary: TechSummary;
}

interface Technology {
  name: string;
  slug: string;
  version: string | null;
  confidence: number;
  website: string | null;
  icon: string | null;
  categories: string[];
}

interface TechCategory {
  name: string;
  slug: string;
  technologies: string[];
}

interface TechSummary {
  total_technologies: number;
  primary_framework: string | null;
  hosting: string | null;
  cms: string | null;
  analytics: string[];
}

interface ClassifyResponse {
  url: string;
  content_type: 'article' | 'product' | 'homepage' | 'category' | 'other';

  classification: Classification;
  topics: Topic[];
  entities?: Entity[];
  sentiment?: Sentiment;

  language: LanguageInfo;
  reading_time: ReadingTime;
  publish_info: PublishInfo;
}

interface Classification {
  primary_category: string;
  secondary_categories: string[];
  confidence: number;
  iab_categories: string[];
}

interface Topic {
  name: string;
  relevance: number;
}

interface Entity {
  name: string;
  type: 'person' | 'organization' | 'location' | 'product' | 'event';
  mentions: number;
}

interface Sentiment {
  overall: 'positive' | 'negative' | 'neutral';
  score: number;
  confidence: number;
}

interface LanguageInfo {
  detected: string;
  confidence: number;
}

interface ReadingTime {
  minutes: number;
  words: number;
}

interface PublishInfo {
  published_at: string | null;
  modified_at: string | null;
  author: string | null;
}

interface ScreenshotResponse {
  url: string;
  screenshot_url: string;

  options: ScreenshotOptions;
  dimensions: Dimensions;
  format: ImageFormat;
  size_bytes: number;

  expires_at: string;
}

interface ScreenshotOptions {
  width: number;
  height: number;
  full_page: boolean;
  dark_mode: boolean;
  device_scale_factor: number;
  delay: number;
}

interface Dimensions {
  width: number;
  height: number;
}

type ImageFormat = 'png' | 'jpeg' | 'webp';

// Preset viewports
type ScreenshotPreset =
  | 'desktop'
  | 'tablet'
  | 'mobile'
  | 'social_card'
  | 'og_image';

interface PreviewResponse {
  url: string;
  previews: {
    twitter?: TwitterPreview;
    facebook?: FacebookPreview;
    linkedin?: LinkedInPreview;
    slack?: SlackPreview;
    discord?: DiscordPreview;
  };
}

interface TwitterPreview {
  card_type: 'summary' | 'summary_large_image';
  title: string;
  description: string;
  image: string | null;
  site: string | null;
  creator: string | null;
}

interface FacebookPreview {
  title: string;
  description: string;
  image: string | null;
  site_name: string | null;
  type: string;
}

interface LinkedInPreview {
  title: string;
  description: string;
  image: string | null;
}

interface SlackPreview {
  title: string;
  text: string;
  image: string | null;
  favicon: string | null;
  site_name: string | null;
}

interface DiscordPreview {
  title: string;
  description: string;
  image: string | null;
  color: string | null;
  site_name: string | null;
}

interface BatchRequest {
  urls: string[];
  operation: 'extract' | 'validate' | 'tech';
  options?: Record<string, unknown>;
}

interface BatchResponse {
  job_id: string;
  status: 'queued' | 'processing' | 'completed' | 'failed';
  total: number;
  completed: number;
  failed: number;
  results: BatchResult[];
}

interface BatchResult {
  url: string;
  success: boolean;
  data?: ExtractResponse | ValidateResponse | TechResponse;
  error?: {
    code: string;
    message: string;
  };
}

interface Monitor {
  id: string;
  url: string;
  name: string;

  interval: MonitorInterval;
  status: MonitorStatus;

  webhook_url: string | null;
  notify_on: NotifyEvent[];

  last_check: string | null;
  next_check: string;

  created_at: string;
  updated_at: string;
}

type MonitorInterval =
  | '5min'
  | '15min'
  | '30min'
  | '1hour'
  | '6hours'
  | '12hours'
  | '24hours';

type MonitorStatus = 'active' | 'paused' | 'error';

type NotifyEvent =
  | 'title_change'
  | 'description_change'
  | 'image_change'
  | 'any_change'
  | 'error';

interface MonitorEvent {
  id: string;
  monitor_id: string;
  event_type: NotifyEvent;

  previous_value: string | null;
  new_value: string | null;

  detected_at: string;
  notified: boolean;
}

// Import your types
import type { ApiResponse, ExtractResponse } from './katsau';

async function getMetadata(url: string): Promise<ExtractResponse> {
  const response = await fetch(
    `https://api.katsau.com/v1/extract?url=${encodeURIComponent(url)}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.KATSAU_API_KEY}`
      }
    }
  );

  const result: ApiResponse<ExtractResponse> = await response.json();

  if (!result.success) {
    throw new Error('Failed to extract metadata');
  }

  return result.data;
}

// Full type safety
const metadata = await getMetadata('https://github.com');
console.log(metadata.title);        // string | null
console.log(metadata.open_graph);   // OpenGraphData
console.log(metadata.twitter.card); // 'summary' | 'summary_large_image' | ...