"""Type-safe metadata contracts for activity models.

This module defines TypedDict contracts for metadata stored in Thread and Signal models.
These contracts provide static type checking without runtime overhead.

Usage:
    from messages.contracts import GitHubAuthorMeta, GitHubLabelMeta

See also:
    - integrations/contracts.py for source-specific metadata contracts
    - B12 in constitution for metadata contract requirements
"""

from typing import NotRequired, TypedDict

# =============================================================================
# Base Metadata Types (shared across sources)
# =============================================================================


class GitHubAuthorMeta(TypedDict):
    """GitHub author/user metadata embedded in thread or signal metadata."""

    login: str
    id: int
    avatar_url: NotRequired[str]


class GitHubLabelMeta(TypedDict):
    """GitHub label metadata for issues and PRs."""

    name: str
    color: str


# =============================================================================
# Future: Additional base types can be added here
# =============================================================================
# class LinkedInAuthorMeta(TypedDict):
#     name: str
#     profile_url: NotRequired[str]