@digitalpaws/starr 0.0.1

package/src/library/library-cache.ts

@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type Database from "better-sqlite3";
+import type { EventBus, Logger, StarrEvent } from "../types/plugin.js";
+
+/**
+ * A single row in the library_cache table, exposed to the API.
+ */
+export interface CachedLibraryItem {
+  requestId: string;
+  contentTypeId: string;
+  title: string;
+  sortTitle?: string;
+  summary?: string;
+  releaseDate?: string;
+  images: any[];
+  externalIds: Record<string, string>;
+  fields?: Record<string, unknown>;
+  libraryPath: string;
+  fileSize?: number;
+  importedAt: string;
+}
+
+export class LibraryCache {
+  private db: Database.Database;
+  private bus: EventBus;
+  private logger: Logger;
+  private stmtInsert: Database.Statement;
+  private stmtDelete: Database.Statement;
+  private stmtGetAll: Database.Statement;
+  private stmtGetByType: Database.Statement;
+  private stmtCount: Database.Statement;
+
+  constructor(db: Database.Database, bus: EventBus, logger: Logger) {
+    this.db = db;
+    this.bus = bus;
+    this.logger = logger.child("library-cache");
+
+    this.stmtInsert = db.prepare(`
+      INSERT INTO library_cache
+        (request_id, content_type_id, content_identity, title, sort_title,
+         summary, release_date, images, external_ids, fields,
+         library_path, file_size, imported_at, updated_at)
+      VALUES
+        (@requestId, @contentTypeId, @contentIdentity, @title, @sortTitle,
+         @summary, @releaseDate, @images, @externalIds, @fields,
+         @libraryPath, @fileSize, @importedAt, datetime('now'))
+      ON CONFLICT(request_id) DO UPDATE SET
+        title = excluded.title,
+        library_path = excluded.library_path,
+        file_size = excluded.file_size,
+        updated_at = datetime('now')
+    `);
+
+    this.stmtDelete = db.prepare(
+      "DELETE FROM library_cache WHERE request_id = @requestId",
+    );
+
+    this.stmtGetAll = db.prepare(
+      "SELECT * FROM library_cache ORDER BY imported_at DESC",
+    );
+
+    this.stmtGetByType = db.prepare(
+      "SELECT * FROM library_cache WHERE content_type_id = @type ORDER BY imported_at DESC",
+    );
+
+    this.stmtCount = db.prepare(
+      "SELECT COUNT(*) AS count FROM library_cache",
+    );
+
+    // Subscribe to events
+    bus.on("library.file_added", this.onFileAdded.bind(this));
+    bus.on("request.deleted", this.onRequestDeleted.bind(this));
+  }
+
+  /**
+   * Populate the cache from tracked_requests on startup.
+   */
+  refreshFromDb(): void {
+    const rows = this.db
+      .prepare(
+        `SELECT tr.request_id, tr.content_type_id, tr.content_identity,
+                tr.item, tr.updated_at,
+                lp.library_path, lp.file_size, lp.imported_at
+         FROM tracked_requests tr
+         JOIN library_paths lp ON lp.request_id = tr.request_id
+         WHERE tr.status = 'imported' OR tr.status = 'downloaded'`,
+      )
+      .all() as any[];
+
+    const txn = this.db.transaction(() => {
+      this.db.exec("DELETE FROM library_cache");
+      for (const row of rows) {
+        const item = JSON.parse(row.item);
+        this.stmtInsert.run({
+          requestId: row.request_id,
+          contentTypeId: row.content_type_id,
+          contentIdentity: row.content_identity,
+          title: item.title ?? "",
+          sortTitle: item.sortTitle ?? null,
+          summary: item.summary ?? null,
+          releaseDate: item.releaseDate ?? null,
+          images: item.images ? JSON.stringify(item.images) : "[]",
+          externalIds: JSON.stringify(item.externalIds ?? {}),
+          fields: item.fields ? JSON.stringify(item.fields) : null,
+          libraryPath: row.library_path,
+          fileSize: row.file_size ?? null,
+          importedAt: row.imported_at,
+        });
+      }
+    });
+    txn();
+
+    const count = (this.stmtCount.get() as { count: number }).count;
+    this.logger.info("library cache refreshed", { count });
+  }
+
+  /**
+   * Return all cached library items, optionally filtered by content type.
+   */
+  getItems(contentTypeId?: string): CachedLibraryItem[] {
+    const rows = contentTypeId
+      ? (this.stmtGetByType.all({ type: contentTypeId }) as any[])
+      : (this.stmtGetAll.all() as any[]);
+
+    return rows.map(this.rowToItem);
+  }
+
+  /**
+   * Return total count of cached items.
+   */
+  count(): number {
+    return (this.stmtCount.get() as { count: number }).count;
+  }
+
+  // ── Event handlers ──
+
+  private onFileAdded(event: StarrEvent): void {
+    const payload = event.payload as {
+      requestId: string;
+      libraryPath: string;
+      contentTypeId: string;
+      contentIdentity: string;
+    };
+
+    // Fetch the full item from tracked_requests to cache it
+    const row = this.db
+      .prepare(
+        `SELECT tr.request_id, tr.content_type_id, tr.content_identity,
+                tr.item, tr.updated_at,
+                lp.library_path, lp.file_size, lp.imported_at
+         FROM tracked_requests tr
+         JOIN library_paths lp ON lp.request_id = tr.request_id
+         WHERE tr.request_id = @requestId`,
+      )
+      .get({ requestId: payload.requestId }) as any;
+
+    if (!row) {
+      this.logger.warn("library.file_added for unknown request", {
+        requestId: payload.requestId,
+      });
+      return;
+    }
+
+    const item = JSON.parse(row.item);
+    this.stmtInsert.run({
+      requestId: row.request_id,
+      contentTypeId: row.content_type_id,
+      contentIdentity: row.content_identity,
+      title: item.title ?? "",
+      sortTitle: item.sortTitle ?? null,
+      summary: item.summary ?? null,
+      releaseDate: item.releaseDate ?? null,
+      images: item.images ? JSON.stringify(item.images) : "[]",
+      externalIds: JSON.stringify(item.externalIds ?? {}),
+      fields: item.fields ? JSON.stringify(item.fields) : null,
+      libraryPath: row.library_path,
+      fileSize: row.file_size ?? null,
+      importedAt: row.imported_at,
+    });
+
+    this.logger.debug("library cache updated", {
+      requestId: payload.requestId,
+      title: item.title,
+    });
+  }
+
+  private onRequestDeleted(event: StarrEvent): void {
+    const payload = event.payload as { requestId: string };
+    this.stmtDelete.run({ requestId: payload.requestId });
+  }
+
+  // ── Helpers ──
+
+  private rowToItem(row: any): CachedLibraryItem {
+    return {
+      requestId: row.request_id,
+      contentTypeId: row.content_type_id,
+      title: row.title,
+      sortTitle: row.sort_title ?? undefined,
+      summary: row.summary ?? undefined,
+      releaseDate: row.release_date ?? undefined,
+      images: JSON.parse(row.images ?? "[]"),
+      externalIds: JSON.parse(row.external_ids ?? "{}"),
+      fields: row.fields ? JSON.parse(row.fields) : undefined,
+      libraryPath: row.library_path,
+      fileSize: row.file_size ?? undefined,
+      importedAt: row.imported_at,
+    };
+  }
+}

package/src/library/library-config.ts

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+export interface LibraryRoots {
+  [contentTypeId: string]: string;
+}
+
+export interface LibraryConfig {
+  defaultLibraryRoot: string;
+  roots: LibraryRoots;
+  linkType: "move" | "hardlink" | "symlink" | "copy";
+  importSubtitles: boolean;
+  subtitleExtensions: string[];
+}
+
+export const DEFAULT_LIBRARY_CONFIG: LibraryConfig = {
+  defaultLibraryRoot: "/media/library",
+  roots: {},
+  linkType: "hardlink",
+  importSubtitles: true,
+  subtitleExtensions: ["srt", "ass", "ssa", "sub", "vtt"],
+};

package/src/library/library-scanner.ts

@@ -0,0 +1,404 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import type Database from "better-sqlite3";
+import type { Logger } from "../types/plugin.js";
+import type { LibraryService, Library } from "./library-service.js";
+
+const MEDIA_EXTENSIONS = new Set([
+  // Video
+  "mkv", "mp4", "avi", "mov", "wmv", "flv", "webm",
+  "m4v", "mpg", "mpeg", "ts", "m2ts",
+  // Audio / Audiobooks
+  "mp3", "m4a", "m4b", "aac", "flac", "ogg", "wav",
+  // eBooks
+  "epub", "mobi", "azw", "azw3", "pdf", "cbr", "cbz",
+  "djvu",
+]);
+
+const SUBTITLE_EXTENSIONS = new Set([
+  "srt", "ass", "ssa", "sub", "vtt",
+]);
+
+/** Directories to skip when scanning. */
+const SKIP_DIRS = new Set([
+  ".", "..", "Extras", "Sample", "samples", "Behind the Scenes",
+  "Featurettes", "Trailers",
+]);
+
+export interface DiscoveredGroup {
+  /** Absolute path to the subdirectory. */
+  directory: string;
+  /** Folder name (last path component). */
+  folderName: string;
+  /** All media files within this directory. */
+  files: string[];
+  /** All subtitle files within this directory. */
+  subtitleFiles: string[];
+  /** Content type id inferred from which library root this falls under. */
+  contentTypeId: string;
+  /** The library this group belongs to, if known (multi-library support). */
+  libraryId?: string;
+}
+
+export interface ScanOptions {
+  /** Only scan this specific library. If unset, scan all libraries. */
+  libraryId?: string;
+  /** Only scan these content type ids. If empty, scan all configured roots. */
+  contentTypeIds?: string[];
+  /** Include items already in the library (for re-scan). */
+  includeExisting?: boolean;
+}
+
+function isMediaFile(filePath: string): boolean {
+  const ext = path.extname(filePath).slice(1).toLowerCase();
+  return MEDIA_EXTENSIONS.has(ext);
+}
+
+function isSubtitleFile(filePath: string): boolean {
+  const ext = path.extname(filePath).slice(1).toLowerCase();
+  return SUBTITLE_EXTENSIONS.has(ext);
+}
+
+export class LibraryScanner {
+  private db: Database.Database;
+  private logger: Logger;
+  private libraryService: LibraryService;
+  private stmtCheckPath: Database.Statement;
+
+  constructor(
+    db: Database.Database,
+    logger: Logger,
+    libraryService: LibraryService,
+  ) {
+    this.db = db;
+    this.logger = logger.child("library-scanner");
+    this.libraryService = libraryService;
+
+    this.stmtCheckPath = db.prepare(
+      "SELECT 1 FROM library_paths WHERE library_path = @path LIMIT 1",
+    );
+  }
+
+  /**
+   * Scan all configured library roots and discover media groups.
+   * Returns grouped results without metadata enrichment.
+   * Supports multi-library: scans roots from ALL libraries, or a specific
+   * library if options.libraryId is set, or roots matching specific content
+   * types if options.contentTypeIds is set.
+   */
+  async discoverGroups(options?: ScanOptions): Promise<DiscoveredGroup[]> {
+    const allGroups: DiscoveredGroup[] = [];
+
+    // Determine which libraries to scan
+    const librariesToScan: Library[] = this.resolveLibrariesToScan(options);
+
+    // Collect roots to scan: (contentTypeId, rootPath, libraryId)
+    const rootsToScan: Array<{ contentTypeId: string; rootPath: string; libraryId: string }> = [];
+
+    for (const lib of librariesToScan) {
+      if (options?.contentTypeIds && options.contentTypeIds.length > 0) {
+        // Scan only specified content types within this library
+        for (const ctId of options.contentTypeIds) {
+          const rootPath = lib.roots[ctId];
+          if (rootPath) {
+            rootsToScan.push({ contentTypeId: ctId, rootPath, libraryId: lib.id });
+          } else {
+            this.logger.warn("content type has no root in library", {
+              contentTypeId: ctId,
+              library: lib.name,
+            });
+          }
+        }
+        // Do NOT add default root; only scan explicitly requested roots
+      } else {
+        // Scan all content-type-specific roots for this library
+        for (const [ctId, rootPath] of Object.entries(lib.roots)) {
+          rootsToScan.push({ contentTypeId: ctId, rootPath, libraryId: lib.id });
+        }
+        // Also scan this library's default root
+        if (lib.defaultLibraryRoot) {
+          rootsToScan.push({
+            contentTypeId: "unknown",
+            rootPath: lib.defaultLibraryRoot,
+            libraryId: lib.id,
+          });
+        }
+      }
+    }
+
+    // De-duplicate root paths (avoid scanning the same dir twice)
+    const seenRoots = new Set<string>();
+    for (const { contentTypeId, rootPath, libraryId } of rootsToScan) {
+      if (seenRoots.has(rootPath)) continue;
+      seenRoots.add(rootPath);
+
+      const lib = this.libraryService.get(libraryId);
+      if (!lib) {
+        this.logger.warn("library not found for root, skipping", { libraryId, rootPath });
+        continue;
+      }
+
+      const normalizedRoot = path.resolve(rootPath);
+      this.logger.info("scanning library root", {
+        library: lib.name,
+        contentTypeId,
+        rootPath,
+        normalizedRoot,
+      });
+      let entries: string[];
+      try {
+        entries = await fs.readdir(normalizedRoot, { withFileTypes: false });
+      } catch (err: any) {
+        this.logger.warn("cannot read library root directory", {
+          library: lib.name,
+          root: normalizedRoot,
+          error: err.message,
+        });
+        continue;
+      }
+
+      for (const entry of entries) {
+        // Skip hidden files/dirs
+        if (entry.startsWith(".")) continue;
+        const fullPath = path.join(normalizedRoot, entry);
+
+        let stat;
+        try {
+          stat = await fs.stat(fullPath);
+        } catch {
+          this.logger.debug("cannot stat entry (permission or deleted during scan)", {
+            entry,
+            reason: "stat failed",
+          });
+          continue;
+        }
+
+        if (stat.isDirectory()) {
+          if (SKIP_DIRS.has(entry)) {
+            this.logger.debug("skipping excluded directory", { entry });
+            continue;
+          }
+
+          await this.processSubdirectory(fullPath, entry, contentTypeId, libraryId, lib, allGroups);
+        } else if (stat.isFile()) {
+          // Files directly in the library root → treat as single-item group
+          if (isMediaFile(fullPath)) {
+            allGroups.push({
+              directory: path.dirname(fullPath),
+              folderName: entry,
+              files: [fullPath],
+              subtitleFiles: [],
+              contentTypeId: this.resolveContentType(fullPath, contentTypeId, lib),
+              libraryId,
+            });
+            this.logger.debug("discovered media file at root", {
+              library: lib.name,
+              file: entry,
+              contentTypeId: this.resolveContentType(fullPath, contentTypeId, lib),
+            });
+          } else {
+            this.logger.debug("skipping non-media file at root", { entry });
+          }
+        }
+      }
+    }
+
+    return allGroups;
+  }
+
+  /**
+   * Resolve which libraries to scan based on options.
+   */
+  private resolveLibrariesToScan(options?: ScanOptions): Library[] {
+    if (options?.libraryId) {
+      const lib = this.libraryService.get(options.libraryId);
+      return lib ? [lib] : [];
+    }
+
+    if (options?.contentTypeIds && options.contentTypeIds.length > 0) {
+      // Find libraries that have roots for any of the requested types
+      const allLibs = this.libraryService.list();
+      const matchingLibs: Library[] = [];
+      for (const lib of allLibs) {
+        for (const ctId of options.contentTypeIds) {
+          if (lib.roots[ctId]) {
+            matchingLibs.push(lib);
+            break;
+          }
+        }
+      }
+      // If no library has a matching root, fall back to all libraries so the
+      // default roots are scanned (the contentTypeIds filter is handled above).
+      return matchingLibs.length > 0 ? matchingLibs : allLibs;
+    }
+
+    // No filter — scan all libraries
+    return this.libraryService.list();
+  }
+
+  /**
+   * Scan a subdirectory for media and subtitle files.
+   */
+  private async processSubdirectory(
+    dirPath: string,
+    dirName: string,
+    rootContentTypeId: string,
+    libraryId: string,
+    library: Library,
+    allGroups: DiscoveredGroup[],
+  ): Promise<void> {
+    this.logger.debug("scanning subdirectory", { entry: dirName, fullPath: dirPath });
+
+    // Files directly in this directory (e.g. file.mkv inside item dir)
+    const directFiles: string[] = [];
+    const directSubs: string[] = [];
+
+    try {
+      const subEntries = await fs.readdir(dirPath, { withFileTypes: true });
+      for (const sub of subEntries) {
+        if (sub.isDirectory()) {
+          if (sub.name.startsWith(".")) continue;
+          if (SKIP_DIRS.has(sub.name)) continue;
+
+          // This subdirectory IS a content item (e.g. Movies/Dune (2021)/Dune.mkv)
+          // Create a separate group for it rather than merging into parent
+          const nestedPath = path.join(dirPath, sub.name);
+          await this.processItemDirectory(nestedPath, sub.name, rootContentTypeId, libraryId, library, allGroups);
+          continue;
+        }
+        const subFullPath = path.join(dirPath, sub.name);
+        if (isMediaFile(subFullPath)) {
+          directFiles.push(subFullPath);
+        } else if (isSubtitleFile(subFullPath)) {
+          directSubs.push(subFullPath);
+        }
+      }
+    } catch {
+      return;
+    }
+
+    // Files directly in this dir → treat this dir as the content item
+    if (directFiles.length > 0) {
+      const resolvedCT = this.resolveContentType(dirPath, rootContentTypeId, library);
+      allGroups.push({
+        directory: dirPath,
+        folderName: dirName,
+        files: directFiles,
+        subtitleFiles: directSubs,
+        contentTypeId: resolvedCT,
+        libraryId,
+      });
+      this.logger.debug("discovered media group in directory", {
+        folderName: dirName,
+        files: directFiles.length,
+      });
+    }
+
+    if (directFiles.length === 0 && !allGroups.some((g) => g.directory.startsWith(dirPath))) {
+      this.logger.debug("skipping directory (no media files found)", { entry: dirName, fullPath: dirPath });
+    }
+  }
+
+  /**
+   * Scan a directory that is expected to be a single content item.
+   * Supports nested structures like "Author/Title/file.epub" up to 2 levels deep.
+   */
+  private async processItemDirectory(
+    dirPath: string,
+    dirName: string,
+    rootContentTypeId: string,
+    libraryId: string,
+    library: Library,
+    allGroups: DiscoveredGroup[],
+  ): Promise<void> {
+    const files: string[] = [];
+    const subtitleFiles: string[] = [];
+
+    try {
+      const entries = await fs.readdir(dirPath, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name.startsWith(".")) continue;
+        const fullPath = path.join(dirPath, entry.name);
+
+        if (entry.isDirectory()) {
+          if (SKIP_DIRS.has(entry.name)) continue;
+          // One more level for deeply nested structures
+          try {
+            const deeper = await fs.readdir(fullPath, { withFileTypes: true });
+            for (const d of deeper) {
+              const dFull = path.join(fullPath, d.name);
+              if (d.isFile()) {
+                if (isMediaFile(dFull)) files.push(dFull);
+                else if (isSubtitleFile(dFull)) subtitleFiles.push(dFull);
+              }
+            }
+          } catch {
+            // Ignore — subdirectory may be inaccessible
+          }
+          continue;
+        }
+
+        if (isMediaFile(fullPath)) files.push(fullPath);
+        else if (isSubtitleFile(fullPath)) subtitleFiles.push(fullPath);
+      }
+    } catch {
+      return;
+    }
+
+    if (files.length > 0) {
+      const resolvedCT = this.resolveContentType(dirPath, rootContentTypeId, library);
+      allGroups.push({
+        directory: dirPath,
+        folderName: dirName,
+        files,
+        subtitleFiles,
+        contentTypeId: resolvedCT,
+        libraryId,
+      });
+      this.logger.debug("discovered media group in item directory", {
+        folderName: dirName,
+        files: files.length,
+      });
+    }
+  }
+
+  /**
+   * Determine the content type for a given path.
+   */
+  private resolveContentType(
+    itemPath: string,
+    rootContentTypeId: string,
+    library: Library,
+  ): string {
+    if (rootContentTypeId !== "unknown") return rootContentTypeId;
+
+    for (const [ctId, root] of Object.entries(library.roots)) {
+      const normalizedRootPath = path.resolve(root);
+      if (itemPath.startsWith(normalizedRootPath)) {
+        return ctId;
+      }
+    }
+
+    return "unknown";
+  }
+
+  /**
+   * Check which directories are already registered in library_paths.
+   */
+  findExisting(directories: string[]): Set<string> {
+    const existing = new Set<string>();
+    for (const dir of directories) {
+      // Check if any library_path starts with this directory
+      const row = this.db
+        .prepare("SELECT library_path FROM library_paths WHERE library_path LIKE @pattern LIMIT 1")
+        .get({ pattern: `${dir}%` }) as { library_path: string } | undefined;
+      if (row) {
+        existing.add(dir);
+      }
+    }
+    return existing;
+  }
+}