"""GitHub-specific metadata contracts for Thread and Signal models.

This module defines TypedDict contracts for GitHub metadata stored in
Thread.metadata["github"] and Signal.metadata["github"].

These contracts provide:
- Static type checking at development time
- Clear documentation of expected metadata structure
- Type-safe accessor pattern support

Usage:
    from integrations.contracts import GitHubIssueMeta, GitHubStarMeta

    # Type checker knows the structure
    thread.metadata["github"]  # GitHubThreadMeta

See also:
    - messages/contracts.py for base metadata types
    - B12 in constitution for metadata contract requirements
"""

from typing import Literal, NotRequired, TypedDict

from messages.contracts import GitHubAuthorMeta, GitHubLabelMeta

# =============================================================================
# Thread Metadata Contracts (conversations with replies)
# =============================================================================


class GitHubIssueMeta(TypedDict):
    """Metadata for GitHub issues stored in Thread.metadata["github"]."""

    type: Literal["issue"]
    number: int
    state: str  # "open", "closed"
    html_url: str
    labels: list[GitHubLabelMeta]
    author: GitHubAuthorMeta
    author_member_id: NotRequired[str]  # UUID of linked Member record


class GitHubPRMeta(TypedDict):
    """Metadata for GitHub pull requests stored in Thread.metadata["github"]."""

    type: Literal["pull_request"]
    number: int
    state: str  # "open", "closed", "merged"
    html_url: str
    labels: list[GitHubLabelMeta]
    author: GitHubAuthorMeta
    draft: bool
    merged: bool
    head_ref: NotRequired[str]
    base_ref: NotRequired[str]
    author_member_id: NotRequired[str]  # UUID of linked Member record


class GitHubDiscussionMeta(TypedDict):
    """Metadata for GitHub discussions stored in Thread.metadata["github"]."""

    type: Literal["discussion"]
    number: int
    state: str  # "open", "closed"
    html_url: str
    labels: list[GitHubLabelMeta]
    author: GitHubAuthorMeta
    category: NotRequired[str]  # Discussion category name
    answered: bool
    author_member_id: NotRequired[str]  # UUID of linked Member record


# Union type for all GitHub thread metadata
GitHubThreadMeta = GitHubIssueMeta | GitHubPRMeta | GitHubDiscussionMeta


# =============================================================================
# Signal Metadata Contracts (standalone events)
# =============================================================================


class GitHubStarMeta(TypedDict):
    """Metadata for GitHub star events stored in Signal.metadata["github"]."""

    starred_at: str  # ISO 8601 timestamp
    repo_full_name: str


class GitHubForkMeta(TypedDict):
    """Metadata for GitHub fork events stored in Signal.metadata["github"]."""

    forked_at: str  # ISO 8601 timestamp
    fork_full_name: str


class GitHubReleaseMeta(TypedDict):
    """Metadata for GitHub release events stored in Signal.metadata["github"]."""

    tag_name: str
    name: str
    prerelease: bool
    published_at: str  # ISO 8601 timestamp


# Union type for all GitHub signal metadata
GitHubSignalMeta = GitHubStarMeta | GitHubForkMeta | GitHubReleaseMeta


# =============================================================================
# LinkedIn Metadata Contracts (signals from organization notifications)
# =============================================================================


class LinkedInAuthorMeta(TypedDict):
    """Author metadata for LinkedIn signals."""

    person_urn: str
    name: NotRequired[str]
    profile_url: NotRequired[str]
    avatar_url: NotRequired[str]


class LinkedInMentionMeta(TypedDict):
    """Metadata for LinkedIn mention signals stored in Signal.metadata["linkedin"].

    Used for all notification types: SHARE_MENTION, COMMENT, SHARE, LIKE
    """

    action: str  # SHARE_MENTION, COMMENT, SHARE, LIKE
    notification_id: int
    source_post: str  # Activity URN
    author_urn: str
    author: NotRequired[LinkedInAuthorMeta]
    organization_urn: str
    reaction_type: NotRequired[str]  # For LIKE: LIKE, PRAISE, EMPATHY, etc.
    author_member_id: NotRequired[str]  # UUID of linked Member record


# Union type for all LinkedIn signal metadata
LinkedInSignalMeta = LinkedInMentionMeta