gerbeur/api/services/playlist-service.ts

/**
 * Stores playlists and the ordered dumps in them. The playlist routes call it,
 * and so do the search, users and dumps routes to list playlists. Every write
 * is broadcast over the WebSocket, and a viewer is only ever sent the dumps
 * {@link isMemberVisibleTo} lets them see.
 *
 * @module
 */

import { APIErrorCode } from "../../shared/api.ts";
import { APIException } from "../lib/api-exception.ts";
import type {
  CreatePlaylistRequest,
  Playlist,
  PlaylistMembership,
  PlaylistWithDumps,
  UpdatePlaylistRequest,
} from "../../shared/playlist.ts";
import type { Dump } from "../../shared/dump.ts";
import { db, transaction } from "../db/connection.ts";
import {
  DUMP_COLUMNS_ALIASED,
  dumpRowToApi,
  isDumpRow,
} from "../model/dump.ts";
import { isPlaylistRow, playlistRowToApi } from "../model/playlist.ts";
import { type Page, pageOf } from "../lib/pagination.ts";
import {
  broadcastPlaylistCreated,
  broadcastPlaylistDeleted,
  broadcastPlaylistDumpsUpdated,
  broadcastPlaylistUpdated,
} from "./ws-service.ts";
import {
  notifyMentions,
  notifyPlaylistFollowersNewDump,
} from "./notification-service.ts";
import { makeSlug, UUID_RE } from "../lib/slugify.ts";
import { linkAttachments } from "./attachment-service.ts";
import {
  isMemberVisibleTo,
  type PlaylistMember,
} from "../lib/playlist-members.ts";

/**
 * The select list and `FROM` clause of a playlist query, adding the owner's
 * name and the dump count. Callers append the `WHERE`. The dump count includes
 * dumps the viewer can't see.
 */
const PLAYLIST_SELECT = `p.*, u.username as owner_username,
   (SELECT COUNT(*) FROM playlist_dumps pd WHERE pd.playlist_id = p.id) as dump_count
   FROM playlists p LEFT JOIN users u ON u.id = p.user_id`;

/**
 * Returns the playlist with id or slug `idOrSlug`, private or not. A caller
 * that shows it to someone must check `isPublic` first, as the OG middleware
 * does.
 *
 * @throws {APIException} 404 when there is no such playlist.
 */
export function getPlaylistById(idOrSlug: string): Playlist {
  const row = UUID_RE.test(idOrSlug)
    ? db.prepare(`SELECT ${PLAYLIST_SELECT} WHERE p.id = ?;`).get(idOrSlug)
    : db.prepare(`SELECT ${PLAYLIST_SELECT} WHERE p.slug = ?;`).get(idOrSlug);
  if (!row || !isPlaylistRow(row)) {
    throw new APIException(APIErrorCode.NOT_FOUND, 404, "Playlist not found");
  }
  return playlistRowToApi(row);
}

/**
 * Creates a playlist owned by `userId`, for `POST /api/playlists`. It notifies
 * the users its description mentions, links the attachments it embeds, and
 * broadcasts `playlist_created`.
 */
export function createPlaylist(
  req: CreatePlaylistRequest,
  userId: string,
): Playlist {
  const id = crypto.randomUUID();
  const createdAt = new Date();
  const slug = makeSlug(req.title, id);
  db.prepare(
    `INSERT INTO playlists (id, user_id, title, slug, description, is_public, created_at)
     VALUES (?, ?, ?, ?, ?, ?, ?);`,
  ).run(
    id,
    userId,
    req.title,
    slug,
    req.description ?? null,
    req.isPublic ? 1 : 0,
    createdAt.toISOString(),
  );
  const playlist: Playlist = {
    id,
    userId,
    title: req.title,
    slug,
    description: req.description,
    isPublic: req.isPublic,
    createdAt,
  };
  if (req.description) {
    notifyMentions(userId, req.description, "playlist", id, req.title);
    linkAttachments(req.description, id);
  }
  broadcastPlaylistCreated(playlist);
  return playlist;
}

/**
 * Returns a playlist with the dumps `requestingUserId` may see in it, in
 * order, for `GET /api/playlists/:playlistId`. A null `requestingUserId` is a
 * signed-out viewer.
 *
 * @throws {APIException} 404 when there is no such playlist, or it is private
 * and not theirs.
 */
export function getPlaylist(
  playlistId: string,
  requestingUserId: string | null,
): PlaylistWithDumps {
  const playlist = getPlaylistById(playlistId);

  if (!playlist.isPublic && requestingUserId !== playlist.userId) {
    throw new APIException(APIErrorCode.NOT_FOUND, 404, "Playlist not found");
  }

  const rows = db.prepare(
    `SELECT ${DUMP_COLUMNS_ALIASED},
       (SELECT COUNT(*) FROM comments WHERE dump_id = d.id AND deleted = 0) as comment_count
     FROM dumps d
     INNER JOIN playlist_dumps pd ON d.id = pd.dump_id
     WHERE pd.playlist_id = ?
       AND (d.is_private = 0 OR d.user_id = ?)
     ORDER BY pd.position ASC;`,
  ).all(playlist.id, requestingUserId ?? "");

  const dumps: Dump[] = rows.filter(isDumpRow).map(dumpRowToApi);
  const visibleDumps = dumps.filter((d) =>
    isMemberVisibleTo(d, playlist, requestingUserId)
  );

  return { ...playlist, dumps: visibleDumps };
}

/**
 * Returns up to `limit` playlists whose title or description contains
 * `query`, newest first, for `GET /api/search`. Private playlists are left
 * out, except `requestingUserId`'s own. A blank `query` finds nothing.
 */
export function searchPlaylists(
  query: string,
  limit: number,
  requestingUserId?: string,
): Playlist[] {
  if (!query.trim()) return [];
  const pattern = `%${query}%`;
  const searchClause = `(p.title LIKE ? OR p.description LIKE ?)`;

  const rows = requestingUserId
    ? db.prepare(
      `SELECT ${PLAYLIST_SELECT} WHERE (p.is_public = 1 OR p.user_id = ?) AND ${searchClause} ORDER BY p.created_at DESC LIMIT ?;`,
    ).all(requestingUserId, pattern, pattern, limit)
    : db.prepare(
      `SELECT ${PLAYLIST_SELECT} WHERE p.is_public = 1 AND ${searchClause} ORDER BY p.created_at DESC LIMIT ?;`,
    ).all(pattern, pattern, limit);

  return rows.filter(isPlaylistRow).map(playlistRowToApi);
}

/**
 * Returns a page of `userId`'s playlists, newest first, for
 * `GET /api/users/:username/playlists`. The private ones are listed only when
 * `requestingUserId` is `userId`.
 */
export function listPlaylistsByUser(
  userId: string,
  requestingUserId: string | null,
  page: number,
  limit: number,
): Page<Playlist> {
  const isOwner = requestingUserId === userId;
  const offset = (page - 1) * limit;

  const sql = isOwner
    ? `SELECT ${PLAYLIST_SELECT} WHERE p.user_id = ? ORDER BY p.created_at DESC LIMIT ? OFFSET ?;`
    : `SELECT ${PLAYLIST_SELECT} WHERE p.user_id = ? AND p.is_public = 1 ORDER BY p.created_at DESC LIMIT ? OFFSET ?;`;

  const rows = db.prepare(sql).all(userId, limit + 1, offset);
  return pageOf(rows.filter(isPlaylistRow).map(playlistRowToApi), limit);
}

/**
 * Applies `req` to a playlist for `PUT /api/playlists/:playlistId`, and returns
 * it as it now is. The slug follows the title. `canModerate` lets someone
 * other than the owner edit it. It notifies the users the description
 * mentions, links its attachments and broadcasts `playlist_updated`.
 *
 * @throws {APIException} 404 when there is no such playlist, 403 when the user
 * is neither its owner nor a moderator.
 */
export function updatePlaylist(
  playlistId: string,
  req: UpdatePlaylistRequest,
  requestingUserId: string,
  canModerate: boolean,
): Playlist {
  const playlist = getPlaylistById(playlistId);

  if (playlist.userId !== requestingUserId && !canModerate) {
    throw new APIException(APIErrorCode.UNAUTHORIZED, 403, "Forbidden");
  }

  const newTitle = req.title ?? playlist.title;
  const newDescription = "description" in req
    ? (req.description ?? null)
    : (playlist.description ?? null);
  const newIsPublic = req.isPublic !== undefined
    ? req.isPublic
    : playlist.isPublic;

  const now = new Date();
  const newSlug = makeSlug(newTitle, playlist.id);
  db.prepare(
    `UPDATE playlists SET title = ?, slug = ?, description = ?, is_public = ?, updated_at = ? WHERE id = ?;`,
  ).run(
    newTitle,
    newSlug,
    newDescription,
    newIsPublic ? 1 : 0,
    now.toISOString(),
    playlist.id,
  );

  const updated: Playlist = {
    ...playlist,
    title: newTitle,
    slug: newSlug,
    description: newDescription ?? undefined,
    isPublic: newIsPublic,
    updatedAt: now,
  };
  if (newDescription) {
    notifyMentions(
      requestingUserId,
      newDescription,
      "playlist",
      playlist.id,
      newTitle,
    );
    linkAttachments(newDescription, playlist.id);
  }
  broadcastPlaylistUpdated(updated, playlist.isPublic);
  return updated;
}

/**
 * Deletes a playlist for `DELETE /api/playlists/:playlistId`, and broadcasts
 * `playlist_deleted`. `canModerate` lets someone other than the owner do it.
 *
 * @throws {APIException} 404 when there is no such playlist, 403 when the user
 * is neither its owner nor a moderator.
 */
export function deletePlaylist(
  playlistId: string,
  requestingUserId: string,
  canModerate: boolean,
): void {
  const playlist = getPlaylistById(playlistId);

  if (playlist.userId !== requestingUserId && !canModerate) {
    throw new APIException(APIErrorCode.UNAUTHORIZED, 403, "Forbidden");
  }

  db.prepare(`DELETE FROM playlists WHERE id = ?;`).run(playlist.id);
  broadcastPlaylistDeleted(playlist.id, playlist.userId, playlist.isPublic);
}

/**
 * Returns the playlist if `requestingUserId` may edit it. The cover upload
 * route checks this before it writes the file, then calls
 * {@link setPlaylistImage}.
 *
 * @throws {APIException} 404 when there is no such playlist, 403 when the user
 * is neither its owner nor a moderator.
 */
export function getEditablePlaylist(
  playlistId: string,
  requestingUserId: string,
  canModerate: boolean,
): Playlist {
  const playlist = getPlaylistById(playlistId);
  if (playlist.userId !== requestingUserId && !canModerate) {
    throw new APIException(APIErrorCode.UNAUTHORIZED, 403, "Forbidden");
  }
  return playlist;
}

/**
 * Records the type of a playlist's new cover and broadcasts `playlist_updated`.
 * The route must have written the file already, since clients fetch the cover
 * as soon as they get the broadcast.
 *
 * @throws {APIException} 404 when there is no such playlist, 403 when the user
 * is neither its owner nor a moderator.
 */
export function setPlaylistImage(
  playlistId: string,
  imageMime: string,
  requestingUserId: string,
  canModerate: boolean,
): Playlist {
  const playlist = getEditablePlaylist(
    playlistId,
    requestingUserId,
    canModerate,
  );
  // updated_at is the `?v=` the client puts on the cover URL, so bumping it
  // keeps browsers from showing the cached old cover.
  db.prepare(
    `UPDATE playlists SET image_mime = ?, updated_at = ? WHERE id = ?;`,
  ).run(imageMime, new Date().toISOString(), playlist.id);
  const updated = getPlaylistById(playlist.id);
  broadcastPlaylistUpdated(updated, playlist.isPublic);
  return updated;
}

/**
 * Puts a dump at the top of a playlist, for
 * `POST /api/playlists/:playlistId/dumps/:dumpId`, and broadcasts
 * `playlist_dumps_updated`. The followers of a public playlist are notified
 * when the dump is public.
 *
 * @throws {APIException} 404 when there is no such playlist, or when the dump
 * doesn't exist or is someone else's private dump, 403 when the user is
 * neither the playlist's owner nor a moderator, 409 when the dump is already
 * in it.
 */
export function addDumpToPlaylist(
  playlistId: string,
  dumpId: string,
  requestingUserId: string,
  canModerate: boolean,
): void {
  const playlist = getPlaylistById(playlistId);

  if (playlist.userId !== requestingUserId && !canModerate) {
    throw new APIException(APIErrorCode.UNAUTHORIZED, 403, "Forbidden");
  }

  // Else someone else's private dump would land in the playlist, and its title
  // in the followers' notifications.
  const dump = db.prepare(
    `SELECT title, is_private, user_id FROM dumps WHERE id = ?;`,
  ).get(dumpId) as
    | { title: string; is_private: number; user_id: string }
    | undefined;
  if (!dump || (dump.is_private && dump.user_id !== requestingUserId)) {
    throw new APIException(APIErrorCode.NOT_FOUND, 404, "Dump not found");
  }

  const minRow = db.prepare(
    `SELECT MIN(position) as min_pos FROM playlist_dumps WHERE playlist_id = ?;`,
  ).get(playlist.id) as { min_pos: number | null } | undefined;

  const nextPos = (minRow?.min_pos ?? 1) - 1;
  const addedAt = new Date().toISOString();

  try {
    db.prepare(
      `INSERT INTO playlist_dumps (playlist_id, dump_id, position, added_at)
       VALUES (?, ?, ?, ?);`,
    ).run(playlist.id, dumpId, nextPos, addedAt);
  } catch (err) {
    const msg = err instanceof Error ? err.message : String(err);
    if (msg.includes("UNIQUE") || msg.includes("unique")) {
      throw new APIException(
        APIErrorCode.VALIDATION_ERROR,
        409,
        "Dump already in playlist",
      );
    }
    throw err;
  }

  broadcastPlaylistDumpsUpdated(playlist, getCurrentMembers(playlist.id));

  // Followers can't open a private dump, even one of the owner's own.
  if (playlist.isPublic && !dump.is_private) {
    notifyPlaylistFollowersNewDump(
      playlist.id,
      playlist.title,
      dumpId,
      dump.title,
    );
  }
}

/**
 * Takes a dump out of a playlist, for
 * `DELETE /api/playlists/:playlistId/dumps/:dumpId`, and broadcasts
 * `playlist_dumps_updated`. A dump that isn't in it is no error.
 *
 * @throws {APIException} 404 when there is no such playlist, 403 when the user
 * is neither its owner nor a moderator.
 */
export function removeDumpFromPlaylist(
  playlistId: string,
  dumpId: string,
  requestingUserId: string,
  canModerate: boolean,
): void {
  const playlist = getPlaylistById(playlistId);

  if (playlist.userId !== requestingUserId && !canModerate) {
    throw new APIException(APIErrorCode.UNAUTHORIZED, 403, "Forbidden");
  }

  db.prepare(
    `DELETE FROM playlist_dumps WHERE playlist_id = ? AND dump_id = ?;`,
  ).run(playlist.id, dumpId);

  broadcastPlaylistDumpsUpdated(playlist, getCurrentMembers(playlist.id));
}

/**
 * Puts the dumps of a playlist that the requester can see in the order of
 * `dumpIds`, for `PUT /api/playlists/:playlistId/order`, and broadcasts
 * `playlist_dumps_updated`.
 *
 * @throws {APIException} 404 when there is no such playlist, 403 when the user
 * is neither its owner nor a moderator, 400 when `dumpIds` isn't exactly the
 * members they can see.
 */
export function reorderPlaylist(
  playlistId: string,
  dumpIds: string[],
  requestingUserId: string,
  canModerate: boolean,
): void {
  const playlist = getPlaylistById(playlistId);

  if (playlist.userId !== requestingUserId && !canModerate) {
    throw new APIException(APIErrorCode.UNAUTHORIZED, 403, "Forbidden");
  }

  // The requester can only name the dumps GET showed them. A hidden one
  // (someone else's dump that went private, or the owner's private dump for a
  // moderator) keeps its slot, and the visible ones are reordered around it.
  const members = getCurrentMembers(playlist.id);
  const visibleIds = members
    .filter((m) => isMemberVisibleTo(m, playlist, requestingUserId))
    .map((m) => m.id);
  const newSet = new Set(dumpIds);

  if (
    dumpIds.length !== newSet.size ||
    visibleIds.length !== newSet.size ||
    !visibleIds.every((id) => newSet.has(id))
  ) {
    throw new APIException(
      APIErrorCode.BAD_REQUEST,
      400,
      "dumpIds must match current playlist members exactly",
    );
  }

  let next = 0;
  const order = members.map((m) =>
    isMemberVisibleTo(m, playlist, requestingUserId) ? dumpIds[next++] : m.id
  );
  const update = db.prepare(
    `UPDATE playlist_dumps SET position = ? WHERE playlist_id = ? AND dump_id = ?;`,
  );
  transaction(() => {
    for (let i = 0; i < order.length; i++) {
      update.run(i, playlist.id, order[i]);
    }
  });

  broadcastPlaylistDumpsUpdated(playlist, getCurrentMembers(playlist.id));
}

/**
 * Returns each of `userId`'s playlists, newest first, and whether it holds
 * dump `dumpId`, for `GET /api/playlists/by-dump/:dumpId/memberships`. The
 * client's add-to-playlist modal shows it. The playlists have no dump count.
 *
 * @throws {APIException} 500 when a row doesn't parse as a playlist.
 */
export function getPlaylistMembershipsForDump(
  dumpId: string,
  userId: string,
): PlaylistMembership[] {
  const rows = db.prepare(
    `SELECT p.*, pd.dump_id IS NOT NULL as has_dump
     FROM playlists p
     LEFT JOIN playlist_dumps pd ON pd.playlist_id = p.id AND pd.dump_id = ?
     WHERE p.user_id = ?
     ORDER BY p.created_at DESC;`,
  ).all(dumpId, userId);

  return rows.map((row) => {
    if (!isPlaylistRow(row)) {
      throw new APIException(
        APIErrorCode.SERVER_ERROR,
        500,
        "Malformed playlist data",
      );
    }
    return {
      playlist: playlistRowToApi(row),
      hasDump: Boolean(row.has_dump),
    };
  });
}

/**
 * Returns up to 20 playlists that hold dump `dumpId`, newest first, for
 * `GET /api/dumps/:dumpId/playlists`. Private playlists are left out, except
 * `requestingUserId`'s own. The route checks first that the caller may see the
 * dump.
 */
export function getPlaylistsForDump(
  dumpId: string,
  requestingUserId?: string,
): Playlist[] {
  const rows = db.prepare(
    `SELECT ${PLAYLIST_SELECT}
     INNER JOIN playlist_dumps pd ON pd.playlist_id = p.id
     WHERE pd.dump_id = ? AND (p.is_public = 1 OR p.user_id = ?)
     ORDER BY p.created_at DESC LIMIT 20;`,
  ).all(dumpId, requestingUserId ?? "");

  return rows.filter(isPlaylistRow).map(playlistRowToApi);
}

/**
 * Returns what `GET /api/playlists/:playlistId/image` needs to serve a
 * playlist's cover, or undefined when it has none. The route serves a private
 * playlist's cover as private, so no shared cache keeps it.
 *
 * @throws {APIException} 404 when there is no such playlist, or it is private
 * and `requestingUserId` isn't its owner.
 */
export function getPlaylistImageInfo(
  idOrSlug: string,
  requestingUserId: string | null,
): { id: string; imageMime: string; isPublic: boolean } | undefined {
  const playlist = getPlaylistById(idOrSlug);
  if (!playlist.isPublic && requestingUserId !== playlist.userId) {
    throw new APIException(APIErrorCode.NOT_FOUND, 404, "Playlist not found");
  }
  return playlist.imageMime
    ? {
      id: playlist.id,
      imageMime: playlist.imageMime,
      isPublic: playlist.isPublic,
    }
    : undefined;
}

/**
 * Returns a playlist's dumps in order, all of them, for the callers to filter
 * per viewer.
 */
function getCurrentMembers(playlistId: string): PlaylistMember[] {
  const rows = db.prepare(
    `SELECT pd.dump_id, d.is_private, d.user_id
     FROM playlist_dumps pd INNER JOIN dumps d ON d.id = pd.dump_id
     WHERE pd.playlist_id = ? ORDER BY pd.position ASC;`,
  ).all(playlistId) as Array<
    { dump_id: string; is_private: number; user_id: string }
  >;
  return rows.map((r) => ({
    id: r.dump_id,
    isPrivate: Boolean(r.is_private),
    userId: r.user_id,
  }));
}