siftlode/backend/app/models.py

from datetime import date, datetime

from sqlalchemy import (
    BigInteger,
    Boolean,
    Computed,
    Date,
    DateTime,
    Float,
    ForeignKey,
    Integer,
    JSON,
    String,
    Text,
    UniqueConstraint,
    func,
)
from sqlalchemy.dialects.postgresql import TSVECTOR
from sqlalchemy.orm import Mapped, mapped_column, relationship

from app.db import Base


class TimestampMixin:
    """Adds a server-defaulted `created_at`. Models that index created_at or order it
    differently (QuotaEvent, Notification, Message) keep their own column on purpose."""

    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now()
    )


class UpdatedAtMixin:
    """Adds an `updated_at` that server-defaults on insert and bumps on every UPDATE."""

    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now(), onupdate=func.now()
    )


class User(Base, TimestampMixin):
    __tablename__ = "users"

    id: Mapped[int] = mapped_column(primary_key=True)
    # NULL for an email+password account that hasn't linked Google yet (Postgres allows
    # multiple NULLs under a unique index). Set on Google sign-in / in-app linking.
    google_sub: Mapped[str | None] = mapped_column(String(64), unique=True, index=True)
    email: Mapped[str] = mapped_column(String(320), unique=True, index=True)
    # argon2id hash for email+password login; NULL for Google-only / demo accounts.
    password_hash: Mapped[str | None] = mapped_column(String(255))
    # Email ownership proven (Google sign-in is implicitly verified; password registration
    # verifies via a link). Login requires this AND is_active.
    email_verified: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default="false"
    )
    # Admin-approved & enabled. A pending password registration starts inactive; admin
    # approval activates it. A deactivated account can't log in.
    is_active: Mapped[bool] = mapped_column(Boolean, default=True, server_default="true")
    # Admin-imposed access block, distinct from is_active (approval lifecycle). A suspended
    # account can't sign in by any method and its live sessions are rejected; the user is told
    # why and pointed at the operator's contact. The demo account is never suspendable.
    is_suspended: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default="false"
    )
    display_name: Mapped[str | None] = mapped_column(String(255))
    avatar_url: Mapped[str | None] = mapped_column(String(1024))
    role: Mapped[str] = mapped_column(String(16), default="user", server_default="user")
    # The user's own YouTube channel id, resolved lazily (channels.list?mine=true) and
    # cached. Used to exclude their own channel from playlist discovery. NULL = unresolved.
    yt_channel_id: Mapped[str | None] = mapped_column(String(32))
    # The single shared "demo" account: signed into without Google OAuth (via a whitelisted
    # email on the login page), has no OAuth token / YouTube scope, and its per-user state is
    # shared by everyone who enters this way. Exactly one such row is expected.
    is_demo: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default="false", index=True
    )
    # Free-form UI preferences (theme, color scheme, font scale, default filters…).
    preferences: Mapped[dict | None] = mapped_column(JSON)

    token: Mapped["OAuthToken | None"] = relationship(
        back_populates="user", uselist=False, cascade="all, delete-orphan"
    )
    subscriptions: Mapped[list["Subscription"]] = relationship(
        back_populates="user", cascade="all, delete-orphan"
    )


class OAuthToken(Base, UpdatedAtMixin):
    __tablename__ = "oauth_tokens"

    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), unique=True
    )
    # Refresh token encrypted at rest (Fernet). Access token is short-lived and low risk.
    refresh_token_enc: Mapped[str | None] = mapped_column(String)
    access_token: Mapped[str | None] = mapped_column(String)
    expiry: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
    scopes: Mapped[str | None] = mapped_column(String)

    user: Mapped["User"] = relationship(back_populates="token")


class AuthToken(Base, TimestampMixin):
    """Single-use, expiring token for email verification or password reset. Only the SHA-256
    HASH of the token is stored, so a DB leak can't be used to verify/reset; the raw token
    lives only in the emailed link. Consumed (used_at set) on first valid use."""

    __tablename__ = "auth_tokens"

    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), index=True
    )
    kind: Mapped[str] = mapped_column(String(16))  # "verify" | "reset"
    token_hash: Mapped[str] = mapped_column(String(64), unique=True, index=True)
    expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))
    used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))


class Invite(Base):
    """Access-request / whitelist row. Source of truth for who may sign in; the env
    ALLOWED_EMAILS/ADMIN_EMAILS act only as a bootstrap fallback (see auth.is_allowed)."""

    __tablename__ = "invites"

    id: Mapped[int] = mapped_column(primary_key=True)
    email: Mapped[str] = mapped_column(String(320), unique=True, index=True)
    # pending | approved | denied
    status: Mapped[str] = mapped_column(
        String(16), default="pending", server_default="pending"
    )
    note: Mapped[str | None] = mapped_column(Text)
    requested_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now()
    )
    decided_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
    decided_by: Mapped[str | None] = mapped_column(String(320))  # admin email


class DemoWhitelist(Base, TimestampMixin):
    """Emails that may enter the shared demo account from the login page (no Google OAuth).
    A hidden, admin-curated list of "keys to the same door" — every entry logs into the one
    shared demo user. Distinct from Invite (which gates real Google sign-in)."""

    __tablename__ = "demo_whitelist"

    id: Mapped[int] = mapped_column(primary_key=True)
    email: Mapped[str] = mapped_column(String(320), unique=True, index=True)
    note: Mapped[str | None] = mapped_column(Text)
    added_by: Mapped[str | None] = mapped_column(String(320))  # admin email


class Channel(Base, TimestampMixin):
    """A YouTube channel. Shared across all users (one channel's videos are the same
    for everyone), so its expensive metadata is fetched and stored only once."""

    __tablename__ = "channels"

    id: Mapped[str] = mapped_column(String(32), primary_key=True)  # "UC..." channel id
    title: Mapped[str | None] = mapped_column(String(255))
    handle: Mapped[str | None] = mapped_column(String(255))
    description: Mapped[str | None] = mapped_column(Text)
    thumbnail_url: Mapped[str | None] = mapped_column(String(1024))
    uploads_playlist_id: Mapped[str | None] = mapped_column(String(64))
    subscriber_count: Mapped[int | None] = mapped_column(BigInteger)
    video_count: Mapped[int | None] = mapped_column(BigInteger)
    # Channel "About" metadata (fetched with the same channels.list call, no extra quota):
    # lifetime view count, the channel's join date, banner image, and external links.
    total_view_count: Mapped[int | None] = mapped_column(BigInteger)
    published_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
    banner_url: Mapped[str | None] = mapped_column(String(1024))
    external_links: Mapped[list | None] = mapped_column(JSON)
    topic_categories: Mapped[list | None] = mapped_column(JSON)
    default_language: Mapped[str | None] = mapped_column(String(16))
    country: Mapped[str | None] = mapped_column(String(8))

    # Sync bookkeeping.
    details_synced_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
    recent_synced_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
    last_rss_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
    backfill_cursor: Mapped[str | None] = mapped_column(String(128))
    backfill_done: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default="false"
    )
    # True when this channel only entered the catalog because a live YouTube search
    # surfaced one of its videos (nobody subscribes to it / it has no organic upload sync).
    # Lets the Library hide search-only "noise" by default.
    from_search: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default="false", index=True
    )
    # True when this channel exists only because a user EXPLORED it (opened its page without
    # subscribing) — an ephemeral, per-explorer addition. The cleanup job hard-deletes such a
    # channel (and its via_explore videos) once nobody keeps it (no subscription, no live
    # ExploredChannel row, no per-user state) after a grace period. Cleared when someone
    # subscribes (the "keep" signal promotes it to organic).
    from_explore: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default="false", index=True
    )

    videos: Mapped[list["Video"]] = relationship(back_populates="channel")
    subscriptions: Mapped[list["Subscription"]] = relationship(back_populates="channel")


class Subscription(Base, TimestampMixin):
    """Per-user link to a channel, with the user's own priority/visibility overrides."""

    __tablename__ = "subscriptions"
    __table_args__ = (UniqueConstraint("user_id", "channel_id", name="uq_user_channel"),)

    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), index=True
    )
    channel_id: Mapped[str] = mapped_column(
        ForeignKey("channels.id", ondelete="CASCADE"), index=True
    )
    # YouTube's subscription resource id, needed to unsubscribe via the API.
    yt_subscription_id: Mapped[str | None] = mapped_column(String(128))
    priority: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    hidden: Mapped[bool] = mapped_column(Boolean, default=False, server_default="false")
    # Per-user opt-in to full-history (deep) backfill of this channel. Default off so a
    # new user's unique channels don't trigger a big shared-quota burst; the deep
    # scheduler only picks up channels at least one user has requested.
    deep_requested: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default="false"
    )
    subscribed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))

    user: Mapped["User"] = relationship(back_populates="subscriptions")
    channel: Mapped["Channel"] = relationship(back_populates="subscriptions")


class Video(Base, TimestampMixin):
    """A YouTube video. Shared across users; per-user state lives elsewhere."""

    __tablename__ = "videos"

    id: Mapped[str] = mapped_column(String(16), primary_key=True)  # video id
    channel_id: Mapped[str] = mapped_column(
        ForeignKey("channels.id", ondelete="CASCADE"), index=True
    )
    title: Mapped[str | None] = mapped_column(Text)
    description: Mapped[str | None] = mapped_column(Text)
    published_at: Mapped[datetime | None] = mapped_column(
        DateTime(timezone=True), index=True
    )
    thumbnail_url: Mapped[str | None] = mapped_column(String(1024))
    duration_seconds: Mapped[int | None] = mapped_column(Integer)
    view_count: Mapped[int | None] = mapped_column(BigInteger)
    like_count: Mapped[int | None] = mapped_column(BigInteger)
    category_id: Mapped[int | None] = mapped_column(Integer)
    topic_categories: Mapped[list | None] = mapped_column(JSON)
    default_language: Mapped[str | None] = mapped_column(String(16))
    detected_language: Mapped[str | None] = mapped_column(String(16))
    # Creator-supplied keyword tags (snippet.tags joined by spaces) — fetched for free with the
    # snippet we already request. Indexed into search_vector so the feed search matches the
    # uploader's own keywords, not just words in the title.
    keywords: Mapped[str | None] = mapped_column(Text)
    # Accumulated distinct live-search queries that surfaced this video (across all users) —
    # folds YouTube's own relevance judgement into the local search: a video YouTube returned
    # for "ti amo magyarul" becomes findable by that query locally even if its title lacks it.
    search_terms: Mapped[str | None] = mapped_column(Text)
    is_short: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default="false", index=True
    )
    # Whether the youtube.com/shorts/<id> probe has run for this video.
    shorts_probed: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default="false", index=True
    )
    # True when this video first entered the catalog via a live YouTube search (not an
    # organic channel/playlist sync). Used to hide search-discovered "noise" from the
    # Library by default; left False by the organic ingest paths.
    via_search: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default="false", index=True
    )
    # True when this video entered the catalog because a user EXPLORED its (un-subscribed)
    # channel. Like via_search it's hidden from the shared Library by default, but it's
    # additionally PER-USER private: a via_explore video is only visible to users who
    # explored or subscribe to its channel (a gate in the feed query), so one user's
    # curiosity never floods everyone else's catalog. Left False by the organic ingest paths.
    via_explore: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default="false", index=True
    )
    # none | live | upcoming | premiere | was_live
    live_status: Mapped[str] = mapped_column(
        String(16), default="none", server_default="none", index=True
    )
    enriched_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
    # videos.list?part=status fields (populated during enrichment); used by the
    # maintenance/validation job to decide whether a video is playable anywhere.
    embeddable: Mapped[bool | None] = mapped_column(Boolean)
    privacy_status: Mapped[str | None] = mapped_column(String(16))  # public|unlisted|private
    upload_status: Mapped[str | None] = mapped_column(String(16))  # processed|failed|rejected|deleted
    # Maintenance/validation lifecycle. last_checked_at drives the rolling re-validation
    # (least-recently-checked first); unavailable_since marks a video as currently
    # unplayable (hidden from the feed immediately, hard-deleted after a grace period);
    # unavailable_reason records why (deleted|private|paywalled|abandoned|stuck_live).
    last_checked_at: Mapped[datetime | None] = mapped_column(
        DateTime(timezone=True), index=True
    )
    unavailable_since: Mapped[datetime | None] = mapped_column(
        DateTime(timezone=True), index=True
    )
    unavailable_reason: Mapped[str | None] = mapped_column(String(24))

    # Weighted full-text search document (DB-generated, never written by the app): title (A) >
    # creator keywords + search queries (B) > truncated description (C). ts_rank honours the
    # weights so title matches outrank description matches. Backed by a GIN index (migration
    # 0032). The accent-insensitive `unaccent_simple` config comes from migration 0031.
    search_vector: Mapped[object | None] = mapped_column(
        TSVECTOR,
        Computed(
            "setweight(to_tsvector('public.unaccent_simple', coalesce(title, '')), 'A') || "
            "setweight(to_tsvector('public.unaccent_simple', coalesce(keywords, '') || ' ' || "
            "coalesce(search_terms, '')), 'B') || "
            "setweight(to_tsvector('public.unaccent_simple', left(coalesce(description, ''), 1000)), 'C')",
            persisted=True,
        ),
    )

    channel: Mapped["Channel"] = relationship(back_populates="videos")


class Tag(Base, TimestampMixin):
    """A label. System tags (user_id NULL) are computed automatically and shared by all
    users; user tags (user_id set) are personal. category groups them in the UI."""

    __tablename__ = "tags"

    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int | None] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), index=True
    )
    name: Mapped[str] = mapped_column(String(64))
    color: Mapped[str | None] = mapped_column(String(16))
    # language | topic | other
    category: Mapped[str] = mapped_column(
        String(16), default="other", server_default="other"
    )


class ChannelTag(Base):
    """Links a tag to a channel. source='auto' rows are managed by the auto-tagger and
    regenerated freely; source='user' rows are never touched by the system."""

    __tablename__ = "channel_tags"
    __table_args__ = (
        UniqueConstraint("channel_id", "tag_id", "user_id", name="uq_channel_tag"),
    )

    id: Mapped[int] = mapped_column(primary_key=True)
    channel_id: Mapped[str] = mapped_column(
        ForeignKey("channels.id", ondelete="CASCADE"), index=True
    )
    tag_id: Mapped[int] = mapped_column(
        ForeignKey("tags.id", ondelete="CASCADE"), index=True
    )
    # NULL = system/auto link visible to everyone; set = a specific user's link.
    user_id: Mapped[int | None] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE")
    )
    source: Mapped[str] = mapped_column(String(8), default="auto", server_default="auto")
    confidence: Mapped[float | None] = mapped_column(Float)


class VideoState(Base, UpdatedAtMixin):
    """Per-user watch state for a video. Rows exist only for non-default states; the
    absence of a row means 'new/unseen'."""

    __tablename__ = "video_states"
    __table_args__ = (UniqueConstraint("user_id", "video_id", name="uq_user_video"),)

    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), index=True
    )
    video_id: Mapped[str] = mapped_column(
        ForeignKey("videos.id", ondelete="CASCADE"), index=True
    )
    # new | watched | hidden  ("saved" is now Watch-later playlist membership, not a status)
    status: Mapped[str] = mapped_column(String(12), default="new", server_default="new")
    watched_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
    # Resume position (seconds into the video) for the in-app player. Orthogonal to
    # status: a partially-watched video keeps status "new" but a non-zero position, so
    # it can render a progress bar and match the "in progress" feed filter. 0 = not
    # started / finished (trivially-early and near-finished positions are not stored).
    position_seconds: Mapped[int] = mapped_column(
        Integer, default=0, server_default="0", nullable=False
    )
    progress_updated_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))


class SearchFind(Base, TimestampMixin):
    """Per-user record of a video the user surfaced via their own live YouTube search.

    Lets "videos I searched for" appear in that user's own (Mine) feed and the Mine Source
    filter — distinct from the GLOBAL `Video.via_search` provenance, which marks a video as
    search-discovered by *anyone* and drives the shared Library's Source filter."""

    __tablename__ = "search_finds"
    __table_args__ = (UniqueConstraint("user_id", "video_id", name="uq_user_search_video"),)

    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), index=True
    )
    video_id: Mapped[str] = mapped_column(
        ForeignKey("videos.id", ondelete="CASCADE"), index=True
    )


class ExploredChannel(Base, TimestampMixin):
    """Per-user record of a channel the user opened the page of WITHOUT subscribing.

    Exploring an un-subscribed channel ingests its recent uploads (flagged via_explore) so the
    user can browse them, but keeps them out of everyone else's catalog. This row (a) gates the
    explorer's access to those ephemeral videos in the feed query and (b) drives the grace-period
    purge: a from_explore channel with no live ExploredChannel row (and no subscription / no
    per-user state on its videos) is hard-deleted by the cleanup job. Subscribing is the "keep"
    signal — it promotes the channel to organic and these rows become irrelevant. `created_at`
    (from TimestampMixin) is the grace clock; a re-visit refreshes it."""

    __tablename__ = "explored_channels"
    __table_args__ = (
        UniqueConstraint("user_id", "channel_id", name="uq_user_explored_channel"),
    )

    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), index=True
    )
    channel_id: Mapped[str] = mapped_column(
        ForeignKey("channels.id", ondelete="CASCADE"), index=True
    )


class BlockedChannel(Base, TimestampMixin):
    """Per-user channel blocklist. Videos from a blocked channel are excluded from this user's
    live YouTube search (and not ingested on their behalf) and hidden from their feed / explore
    views — a personal "never show me this channel again" that doesn't affect other users."""

    __tablename__ = "blocked_channels"
    __table_args__ = (
        UniqueConstraint("user_id", "channel_id", name="uq_user_blocked_channel"),
    )

    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), index=True
    )
    channel_id: Mapped[str] = mapped_column(
        ForeignKey("channels.id", ondelete="CASCADE"), index=True
    )


class ApiQuotaUsage(Base):
    """Tracks YouTube Data API units spent per Pacific-time day (the quota resets at
    midnight Pacific). The whole app shares one daily budget."""

    __tablename__ = "api_quota_usage"

    day: Mapped[date] = mapped_column(Date, primary_key=True)
    units_used: Mapped[int] = mapped_column(Integer, default=0, server_default="0")


class QuotaEvent(Base):
    """Per-spend audit log for YouTube API quota attribution. `user_id` is the end-user
    whose action caused the spend; NULL means background/system work (scheduler backfill,
    enrichment, resync). The aggregate budget still lives in ApiQuotaUsage; this is detail."""

    __tablename__ = "quota_events"

    id: Mapped[int] = mapped_column(primary_key=True)
    # SET NULL on user delete: keep the audit trail (it just becomes system-attributed).
    user_id: Mapped[int | None] = mapped_column(
        ForeignKey("users.id", ondelete="SET NULL"), index=True
    )
    action: Mapped[str] = mapped_column(String(40), index=True)
    units: Mapped[int] = mapped_column(Integer)
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now(), index=True
    )


class AppState(Base):
    """Single-row global app state (admin-controlled)."""

    __tablename__ = "app_state"

    id: Mapped[int] = mapped_column(primary_key=True, default=1)
    sync_paused: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default="false"
    )
    # Admin override for the maintenance job's rolling re-validation batch (videos re-checked
    # per run). NULL = use the config/env default (settings.maintenance_revalidate_batch).
    maintenance_revalidate_batch: Mapped[int | None] = mapped_column(Integer)
    # First-run install wizard. `configured` is False on a fresh instance (the app runs in
    # setup mode: only the wizard works) and flipped True when the wizard finishes. While
    # unconfigured, a one-time setup token (only its SHA-256 hash stored) gates the wizard;
    # the raw token + URL are printed to the container logs on each startup.
    configured: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default="false"
    )
    setup_token_hash: Mapped[str | None] = mapped_column(String(64))


class SchedulerSetting(Base):
    """Admin override for a scheduler job's run interval (minutes). One row per job id;
    absent = use the env/config default. DB-backed so it's editable from the admin UI at
    runtime without a redeploy (env stays a fallback)."""

    __tablename__ = "scheduler_settings"

    job_id: Mapped[str] = mapped_column(String(40), primary_key=True)
    interval_minutes: Mapped[int] = mapped_column(Integer)


class SystemConfig(Base):
    """Admin-set overrides for operational config that otherwise comes from env/config
    defaults. Generic key/value store (one row per key); absent = use the env/config
    default. DB-backed so it's editable from the admin Configuration page at runtime without
    a redeploy. Secret values (e.g. SMTP password) are stored Fernet-encrypted (`encrypted`
    flag) using TOKEN_ENCRYPTION_KEY; non-secrets are plaintext. The set of known keys + their
    types/groups/defaults lives in app.sysconfig (the single source of truth)."""

    __tablename__ = "system_config"

    key: Mapped[str] = mapped_column(String(64), primary_key=True)
    value: Mapped[str | None] = mapped_column(Text)
    encrypted: Mapped[bool] = mapped_column(Boolean, default=False, server_default="false")
    updated_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), default=func.now(), onupdate=func.now()
    )


class Playlist(Base, TimestampMixin, UpdatedAtMixin):
    """A per-user named, ordered collection of videos from the shared catalog.

    `kind`: 'user' (normal) or 'watch_later' (built-in, undeletable, one per user).
    `source`: 'local' (created here) or 'youtube' (mirrored from the user's YouTube
    playlists). `yt_playlist_id` links a mirrored/exported playlist to its YouTube id.
    `dirty` marks a YouTube-linked playlist with local edits not yet pushed, so the read
    sync won't clobber them. (source/yt_playlist_id/dirty are forward-looking for the YT
    sync phases; the foundation phase only uses local playlists.)"""

    __tablename__ = "playlists"

    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), index=True
    )
    name: Mapped[str] = mapped_column(String(255))
    kind: Mapped[str] = mapped_column(String(16), default="user", server_default="user")
    source: Mapped[str] = mapped_column(
        String(16), default="local", server_default="local"
    )
    yt_playlist_id: Mapped[str | None] = mapped_column(String(64))
    # True when the current items/name differ from `synced_fingerprint` (unpushed edits).
    dirty: Mapped[bool] = mapped_column(Boolean, default=False, server_default="false")
    # SHA-256 of name + ordered video ids as last synced from / pushed to YouTube; the
    # baseline `dirty` is derived against. NULL = no baseline yet (treated as dirty).
    synced_fingerprint: Mapped[str | None] = mapped_column(String)
    position: Mapped[int] = mapped_column(Integer, default=0, server_default="0")

    items: Mapped[list["PlaylistItem"]] = relationship(
        back_populates="playlist",
        cascade="all, delete-orphan",
        order_by="PlaylistItem.position",
    )


class PlaylistItem(Base):
    """A video's membership in a playlist, with its order within that playlist."""

    __tablename__ = "playlist_items"
    __table_args__ = (
        UniqueConstraint("playlist_id", "video_id", name="uq_playlist_video"),
    )

    id: Mapped[int] = mapped_column(primary_key=True)
    playlist_id: Mapped[int] = mapped_column(
        ForeignKey("playlists.id", ondelete="CASCADE"), index=True
    )
    video_id: Mapped[str] = mapped_column(
        ForeignKey("videos.id", ondelete="CASCADE"), index=True
    )
    position: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    added_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now()
    )

    playlist: Mapped["Playlist"] = relationship(back_populates="items")


class SavedView(Base, TimestampMixin, UpdatedAtMixin):
    """A per-user named snapshot of the feed's filter/sort state (a "smart view").

    `filters` is the serialized FeedFilters JSON the frontend applies with one click.
    `position` orders them in the sidebar (drag-reorder); `is_default` marks the one view
    applied automatically on load — at most one per user, enforced by the API on set."""

    __tablename__ = "saved_views"
    __table_args__ = (UniqueConstraint("user_id", "name", name="uq_user_saved_view"),)

    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), index=True
    )
    name: Mapped[str] = mapped_column(String(80))
    filters: Mapped[dict] = mapped_column(JSON)
    position: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    is_default: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default="false"
    )


class Notification(Base):
    """A durable, server-backed per-user notification (the inbox center, phase 1).

    Distinct from the client-side transient "bell" (toasts kept only in localStorage):
    these survive reloads and devices, and are produced server-side (first producer = the
    maintenance/validation job's batched "N saved/playlisted videos removed" notice). The
    column is named `data` (not `metadata`, which SQLAlchemy's declarative Base reserves):
    a free-form JSON payload (e.g. the list of removed videos) the UI can render. `read`
    and `dismissed` are separate: read clears the unread badge but keeps the row in the
    inbox; dismissed removes it from the default view. Unread rows never auto-expire; read
    ones are trimmed past a soft per-user cap (see app.notifications.trim_read)."""

    __tablename__ = "notifications"

    id: Mapped[int] = mapped_column(primary_key=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), index=True
    )
    type: Mapped[str] = mapped_column(String(32), index=True)  # e.g. "maintenance"
    title: Mapped[str] = mapped_column(String(255))
    body: Mapped[str | None] = mapped_column(Text)
    data: Mapped[dict | None] = mapped_column(JSON)
    read: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default="false", index=True
    )
    dismissed: Mapped[bool] = mapped_column(
        Boolean, default=False, server_default="false"
    )
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now(), index=True
    )


class Message(Base):
    """A message in the notification module (phase 2).

    Two kinds share this table:
      - `kind="user"`: a private, END-TO-END ENCRYPTED direct message between two users. The
        server only ever stores `ciphertext` + `iv` (base64); it never holds the plaintext or
        the keys, so not even an admin can read it. A conversation is just the set of messages
        between two users — no separate thread entity; queries group by the {sender, recipient}
        pair.
      - `kind="system"`: a server-authored plaintext message (e.g. the welcome, or future admin
        announcements). `sender_id` is NULL and `body` holds the text. These are non-private
        boilerplate, readable without any E2EE key setup, and surface as a "Siftlode" conversation.

    `read_at` is stamped when the recipient opens the thread (NULL = unread, feeds the nav
    badge). The recipient FK cascades (and sender, for user messages) so a GDPR account erasure
    removes that user's messages outright."""

    __tablename__ = "messages"

    id: Mapped[int] = mapped_column(primary_key=True)
    kind: Mapped[str] = mapped_column(
        String(16), default="user", server_default="user"
    )
    # NULL for system messages (no human sender).
    sender_id: Mapped[int | None] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), index=True
    )
    recipient_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), index=True
    )
    # System messages carry plaintext `body`; user messages carry `ciphertext`+`iv` (base64).
    body: Mapped[str | None] = mapped_column(Text)
    ciphertext: Mapped[str | None] = mapped_column(Text)
    iv: Mapped[str | None] = mapped_column(String(32))
    read_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now(), index=True
    )


class MessageKey(Base, TimestampMixin):
    """A user's end-to-end-encryption key material for direct messaging (phase 2).

    One row per user. `public_key` (base64 SPKI, ECDH P-256) is shared with others so they can
    derive the pairwise conversation key. `wrapped_private_key` is the user's private key
    encrypted IN THE BROWSER with a key derived (PBKDF2) from a message passphrase the server
    never sees — so the server stores only an opaque blob it cannot unwrap. `salt`/`wrap_iv`
    parameterise that derivation; `key_check` is a small ciphertext the client decrypts to
    verify a passphrase on unlock. The server is purely a key directory + blob store; it can
    never read any message."""

    __tablename__ = "message_keys"

    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), primary_key=True
    )
    public_key: Mapped[str] = mapped_column(Text)
    wrapped_private_key: Mapped[str] = mapped_column(Text)
    salt: Mapped[str] = mapped_column(String(64))
    wrap_iv: Mapped[str] = mapped_column(String(32))
    key_check: Mapped[str] = mapped_column(Text)