siftlode/backend/app/discover/pins.py

"""The comfort shelf: pin a thing you can always fall back to, and have it be one click from playing.

Five kinds are pinnable — a video, a YouTube channel, a Plex show, a Plex movie, a playlist — because
comfort media is almost always "put on X", a series or a channel, and only sometimes one particular
video. `models.ComfortPin` carries that union as five nullable FKs under a `num_nonnulls(...) = 1`
check; this module is where the union is spoken about in one vocabulary, so no call site invents a
second one.

Every shelf card carries a resolved `next`: the thing that actually plays when you click the tile —
a show's in-progress-or-next episode, a channel's newest unwatched video, a playlist's first
unwatched item. It costs a query per non-leaf pin, which is affordable precisely because this shelf is
short and hand-curated, and it buys the property the whole surface exists for: one click, no
intermediate page, no second decision.

Domain module, so nothing here raises HTTP. `resolve_ref` returns None for "no such thing, or not
yours" and the route turns that into its 404 — core never imports routes.
"""

from sqlalchemy import func, select
from sqlalchemy.orm import Session

from app.discover import cards, queries
from app.models import Channel, ComfortPin, PlexItem, PlexShow, Playlist, User, Video
from app.plex import rollup
from app.plex.cards import leaf_card, show_card
from app.plex.lookups import by_rating_key

# kind -> the ComfortPin column that holds it. The client's vocabulary and the schema's, in one place.
PIN_COLUMNS: dict[str, str] = {
    "video": "video_id",
    "channel": "channel_id",
    "plex_item": "plex_item_id",
    "plex_show": "plex_show_id",
    "playlist": "playlist_id",
}
PIN_KINDS = tuple(PIN_COLUMNS)


def resolve_ref(db: Session, user: User, kind: str, ref: str) -> tuple[str, object] | None:
    """Translate the client's (kind, ref) into the (column, value) the row stores, or None.

    The client speaks the ids the rest of the API speaks: a video id, a channel id, a Plex
    `rating_key`, a playlist id. Plex's internal integer keys never leave the backend, so the
    translation belongs here rather than in five call sites.

    The COLUMN half of every answer comes from `PIN_COLUMNS`; only the LOOKUP differs per kind
    (a direct `db.get`, a rating-key translation, an int parse plus an ownership check). Before the
    E24 review the branches spelled the column names out again and `PIN_COLUMNS` had no readers at
    all — a constant that called itself the one vocabulary while nothing spoke it."""
    col = PIN_COLUMNS.get(kind)
    if col is None:
        return None
    if kind == "video":
        return (col, ref) if db.get(Video, ref) is not None else None
    if kind == "channel":
        return (col, ref) if db.get(Channel, ref) is not None else None
    if kind == "plex_item":
        it = by_rating_key(db, PlexItem, ref)
        return (col, it.id) if it is not None else None
    if kind == "plex_show":
        sh = by_rating_key(db, PlexShow, ref)
        return (col, sh.id) if sh is not None else None
    try:
        pid = int(ref)
    # silent-ok: validating a reference the client supplied. "Not an integer" is answered as "no
    # such pin target", which is the same answer this function gives for one that does not exist.
    except ValueError:
        return None
    pl = db.get(Playlist, pid)
    # A playlist is per-user, unlike the other four (which are shared catalog rows whose PRIVACY
    # lives in the state tables). Someone else's list must read as "no such thing", not as a 403 —
    # the same reason `owned_or_404` 404s rather than 403s.
    return (col, pl.id) if pl is not None and pl.user_id == user.id else None


def list_pins(db: Session, user: User) -> list[ComfortPin]:
    return list(
        db.execute(
            select(ComfortPin)
            .where(ComfortPin.user_id == user.id)
            .order_by(ComfortPin.position.asc(), ComfortPin.id.asc())
        )
        .scalars()
        .all()
    )


def next_position(db: Session, user: User) -> int:
    """New pins land at the end of the shelf.

    `max(position) + 1`, not the row count. Positions are never renumbered on removal — `remove_pin`
    deletes the row, and every FK cascade silently removes a pin when the thing it points at goes
    away — so past the first hole a count under-counts and would drop the new pin into the MIDDLE of
    the shelf, or onto a position another pin already holds (nothing in the schema forbids that).
    Same idiom as `routes/playlists._next_playlist_position`."""
    return (
        db.scalar(
            select(func.coalesce(func.max(ComfortPin.position), -1)).where(
                ComfortPin.user_id == user.id
            )
        )
        + 1
    )


def _shelf_card(db: Session, user: User, pin: ComfortPin) -> dict | None:
    """One pin as a unified card with its resolved `next`. None when the pinned row has gone (the FK
    cascade removes the pin itself, so this is only the window between a delete and a refetch)."""
    card: dict | None = None
    nxt: dict | None = None

    if pin.video_id is not None:
        row = queries.yt_video_row(db, user, pin.video_id)
        if row is None:
            return None
        card = cards.from_video(row)
        nxt = dict(card)  # a video plays itself

    elif pin.channel_id is not None:
        ch = db.get(Channel, pin.channel_id)
        if ch is None:
            return None
        card = cards.from_channel(ch, queries.channel_unwatched_count(db, user, ch.id))
        row = queries.channel_next_video(db, user, ch.id)
        nxt = cards.from_video(row) if row else None

    elif pin.plex_item_id is not None:
        it = db.get(PlexItem, pin.plex_item_id)
        if it is None:
            return None
        st = rollup.item_state_map(db, user.id, [it.id]).get(it.id)
        card = cards.from_plex(leaf_card(it, st))
        nxt = dict(card)  # a movie or a single episode plays itself

    elif pin.plex_show_id is not None:
        sh = db.get(PlexShow, pin.plex_show_id)
        if sh is None:
            return None
        status = rollup.state_map(db, user.id, [sh.id]).get(sh.id, "new")
        card = cards.from_plex(show_card(sh, status))
        ep = queries.next_episode(db, user.id, sh.id)
        nxt = cards.from_plex(ep) if ep else None

    elif pin.playlist_id is not None:
        pl = db.get(Playlist, pin.playlist_id)
        if pl is None:
            return None
        count, row = queries.playlist_summary(db, user, pl.id)
        card = cards.from_playlist(pl, count, row.get("thumbnail_url") if row else None)
        nxt = cards.from_video(row) if row else None

    if card is None:
        return None
    # A COPY, never the card itself: a self-playing pin (a video, a movie) would otherwise make
    # `card["next"] is card`, which serializes as a circular reference and 500s the whole shelf. The
    # copy is taken before `pin_id`/`next` are attached, so `next` stays a plain playable card.
    card["pin_id"] = pin.id
    card["next"] = nxt
    return card


def shelf(db: Session, user: User) -> list[dict]:
    """The whole shelf, in the user's own order."""
    out = []
    for pin in list_pins(db, user):
        card = _shelf_card(db, user, pin)
        if card is not None:
            out.append(card)
    return out


def playables(shelf_cards: list[dict]) -> list[dict]:
    """The `next` of every shelf entry that has one — what the hero may draw from. A pinned channel
    with nothing unwatched left, or an empty playlist, simply is not an answer right now."""
    return [c["next"] for c in shelf_cards if c.get("next")]