Link Types

@dataclass(frozen=True)
class CreateLinkResult:
    id: str                                     # Unique link identifier
    url: str                                    # The saved URL
    domain: str                                 # Extracted domain
    crawl_status: str                           # pending | processing | completed | failed
    title: Optional[str] = None                 # User-provided or OG metadata title
    tags: Optional[list[str]] = None
    folder_id: Optional[str] = None
    og_metadata: Optional[LinkOGMetadata] = None  # Open Graph metadata (if crawled)
    created_at: Optional[datetime] = None

@dataclass(frozen=True)
class LinkDetails:
    id: str
    url: str
    domain: str
    title: Optional[str] = None
    tags: Optional[list[str]] = None
    folder_id: Optional[str] = None
    crawl_status: Optional[str] = None
    crawl_error: Optional[str] = None
    crawled_at: Optional[datetime] = None
    og_metadata: Optional[LinkOGMetadata] = None
    favicon_url: Optional[str] = None
    extracted_images: Optional[list[dict[str, Any]]] = None
    extracted_images_count: Optional[int] = None
    created_at: Optional[datetime] = None
    updated_at: Optional[datetime] = None

    # Properties
    is_crawl_complete: bool   # crawl_status == "completed"
    is_crawl_failed: bool     # crawl_status == "failed"
    is_crawling: bool         # crawl_status in ("pending", "queued", "processing")

@dataclass(frozen=True)
class LinkItem:
    id: str
    url: str
    domain: str
    title: Optional[str] = None
    tags: Optional[list[str]] = None
    folder_id: Optional[str] = None
    crawl_status: Optional[str] = None
    og_metadata: Optional[LinkOGMetadata] = None
    favicon_url: Optional[str] = None
    created_at: Optional[datetime] = None

@dataclass(frozen=True)
class LinkList:
    links: list[LinkItem]    # Link summaries
    total_count: int         # Total links matching query
    has_more: bool           # More links available

@dataclass(frozen=True)
class LinkOGMetadata:
    title: Optional[str] = None           # og:title or <title>
    description: Optional[str] = None     # og:description or meta description
    image_url: Optional[str] = None       # og:image
    site_name: Optional[str] = None       # og:site_name
    type: Optional[str] = None            # og:type
    locale: Optional[str] = None          # og:locale

@dataclass(frozen=True)
class RecrawlLinkResult:
    id: str                                             # Link identifier
    status: str                                         # queued | completed | failed
    message: str = ""
    og_metadata: Optional[LinkOGMetadata] = None        # Updated metadata (if available)
    next_allowed_recrawl: Optional[datetime] = None     # Rate limit reset time

@dataclass(frozen=True)
class LinkUpdateResult:
    id: str
    title: Optional[str] = None
    tags: Optional[list[str]] = None
    updated_at: Optional[datetime] = None

@dataclass(frozen=True)
class LinkDeleteResult:
    id: str                                  # Deleted link ID
    deleted_at: Optional[datetime] = None
    message: str = ""

class LinkCrawlStatus(str, Enum):
    PENDING = "pending"
    QUEUED = "queued"
    PROCESSING = "processing"
    COMPLETED = "completed"
    FAILED = "failed"