feat(library): mark search results already in a Calibre library (#1377)

Per discussion #1372, where you said you were fine with this specific
implementation: check whether metadata.db exists, read it if so, and
show a check mark saying the book is already there.

Searching for a book you already own gives no hint that you own it, so
the easiest way to end up with a second copy is to not remember you have
the first. This reads a Calibre `metadata.db`, read only, and marks
matching results with an **In library** badge in the card, list and
compact views and in the details dialog.

Off by default. It sits in Settings, General beside the existing Library
URL, with a test button that reports how many books it indexed. No HTTP
call, no token, nothing written back.

Matching runs most to least confident: a shared external id, then an
ISBN compared in both ISBN-10 and ISBN-13 form, then fuzzy title tokens
plus the author surname. The check fails open, so an unreadable database
degrades the badge and never blocks a search, and entries are cached for
ten minutes with an early refresh when the file changes, so a large
library costs one read rather than one per search.

`text_match.py` is new and shared by the index and the provider, so
title, author and ISBN matching stays consistent in one place.

## On the provider interface

`library_index` talks only to a `LibraryProvider` protocol and knows
nothing about Calibre. That is deliberate but it is not speculative
generality, it is what let me send you the Calibre half on its own: I
run an Audiobookshelf provider on the same interface in my fork, which
is where the audiobook side of the badge comes from. I have left that
out because it is a new service integration rather than something
already in the codebase, which is the line your non-goals draw. Happy to
send it separately if you ever want it, and equally happy for the answer
to be no.

Adding a library is a module with the `LibraryProvider` shape plus one
line in `all_providers()`.

## Verification

- `tests/core/test_library_index.py`: id, ISBN and fuzzy matching,
per-content-type provider selection, fail-open on provider errors,
stale-cache reuse, TTL and fingerprint refresh, per-provider cache
isolation, and the test-connection path including unsaved form values.
- `tests/core/test_text_match.py`: ISBN variants and token matching.
- `src/frontend/src/tests/libraryBadge.test.ts` and the added cases in
`bookTransformers.test.ts`.
- Python suite (3269) and frontend suite (206) green, plus ruff, ruff
format, basedpyright, vulture, tsc, oxlint, oxfmt and the production
build.
This commit is contained in:
splitsec2 authored and GitHub committed 2026-09-25 18:18:10 -04:00
1 parent fe99d4bb5b
commit 37a77e9562
22 files changed
+1709 -4

No files matched your search

@@ -9,6 +9,7 @@ import { isMetadataBook } from '../types';
import { bookSupportsTargets } from '../utils/bookTargetLoader';
import { isUserCancelledError } from '../utils/errors';
import { BookTargetDropdown } from './BookTargetDropdown';
import { LibraryBadge, isInLibrary } from './shared';
interface DetailsModalProps {
book: Book | null;
@@ -292,6 +293,13 @@ export const DetailsModal = ({
))}
</div>
{isMetadata && isInLibrary(book.library) && (
<div className={`${infoCardClass} space-y-1`}>
<p className={infoLabelClass}>Library</p>
<LibraryBadge library={book.library} />
</div>
)}
{/* ISBN - Universal mode only */}
{isMetadata && (book.isbn_13 || book.isbn_10) && (
<div className={`${infoCardClass} space-y-1`}>
@@ -6,7 +6,7 @@ import { getDownloadsCount } from '../../types';
import { bookSupportsTargets } from '../../utils/bookTargetLoader';
import { BookActionButton } from '../BookActionButton';
import { BookTargetDropdown } from '../BookTargetDropdown';
import { DisplayFieldBadges } from '../shared';
import { DisplayFieldBadges, LibraryBadge } from '../shared';
const SkeletonLoader = () => (
<div className="h-full w-full animate-pulse bg-linear-to-r from-gray-300 via-gray-200 to-gray-300 dark:from-gray-700 dark:via-gray-600 dark:to-gray-700" />
@@ -99,6 +99,7 @@ export const CardView = ({
#{book.series_position}
</div>
)}
<LibraryBadge library={book.library} overlay className="absolute top-2 right-2 z-10" />
{book.preview && !imageError ? (
<>
{!imageLoaded && (
@@ -6,7 +6,7 @@ import { getDownloadsCount } from '../../types';
import { bookSupportsTargets } from '../../utils/bookTargetLoader';
import { BookActionButton } from '../BookActionButton';
import { BookTargetDropdown } from '../BookTargetDropdown';
import { DisplayFieldBadges, DisplayFieldIcon } from '../shared';
import { DisplayFieldBadges, DisplayFieldIcon, LibraryBadge } from '../shared';
const SkeletonLoader = () => (
<div className="h-full w-full animate-pulse bg-linear-to-r from-gray-300 via-gray-200 to-gray-300 dark:from-gray-700 dark:via-gray-600 dark:to-gray-700" />
@@ -99,6 +99,7 @@ export const CompactView = ({
#{book.series_position}
</div>
)}
<LibraryBadge library={book.library} overlay className="absolute top-2 right-2 z-10" />
{book.preview && !imageError ? (
<>
{!imageLoaded && (
@@ -7,7 +7,7 @@ import { bookSupportsTargets } from '../../utils/bookTargetLoader';
import { getFormatColor, getLanguageColor } from '../../utils/colorMaps';
import { BookActionButton } from '../BookActionButton';
import { BookTargetDropdown } from '../BookTargetDropdown';
import { DisplayFieldIcon, DisplayFieldBadge } from '../shared';
import { DisplayFieldIcon, DisplayFieldBadge, LibraryBadge } from '../shared';
interface ListViewProps {
books: Book[];
@@ -203,6 +203,7 @@ export const ListView = ({
{book.author || 'Unknown author'}
{book.year && <span className="sm:hidden"> • {book.year}</span>}
</p>
<LibraryBadge library={book.library} className="mt-0.5" />
</div>
{/* Mobile universal mode info */}
@@ -0,0 +1,50 @@
import type { LibraryOwnership } from '../../types';
/** True when the library check reports this book held in any format. */
export function isInLibrary(library?: LibraryOwnership | null): boolean {
if (!library) return false;
return Object.values(library).some((holding) => holding === 'owned' || holding === 'collection');
}
/** True when every format that holds it holds it inside a larger volume. */
export function isCollectionOnly(library?: LibraryOwnership | null): boolean {
if (!isInLibrary(library)) return false;
return !Object.values(library ?? {}).includes('owned');
}
interface LibraryBadgeProps {
library?: LibraryOwnership | null;
/** Solid pill for use over cover art; otherwise a tinted inline pill. */
overlay?: boolean;
className?: string;
}
/** "Already in your library" badge. Renders nothing when the book is not held. */
export function LibraryBadge({ library, overlay = false, className = '' }: LibraryBadgeProps) {
if (!isInLibrary(library)) return null;
const collectionOnly = isCollectionOnly(library);
const label = collectionOnly ? 'In your library, inside a collection' : 'Already in your library';
const text = collectionOnly ? 'In a collection' : 'In library';
const pill = overlay
? 'rounded-md border border-sky-700 bg-sky-600 px-1.5 py-0.5 text-[10px] font-bold text-white'
: 'rounded-md bg-sky-600/15 px-1.5 py-0.5 text-[10px] font-semibold text-sky-700 dark:text-sky-300';
const style = overlay
? { boxShadow: '0 2px 8px rgba(0, 0, 0, 0.4), 0 1px 3px rgba(0, 0, 0, 0.3)' }
: undefined;
return (
<span
className={`flex w-fit items-center gap-0.5 ${pill} ${className}`}
style={style}
title={label}
aria-label={label}
>
<svg className="h-3 w-3" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M5 13l4 4L19 7" />
</svg>
{text}
</span>
);
}
@@ -1,3 +1,4 @@
export { DisplayFieldIcon, DisplayFieldBadge, DisplayFieldBadges } from './DisplayFieldIcon';
export { CircularProgress } from './CircularProgress';
export { ToggleSwitch } from './ToggleSwitch';
export { LibraryBadge, isInLibrary, isCollectionOnly } from './LibraryBadge';
@@ -2,6 +2,7 @@ import { describe, it, expect } from 'vitest';
import { isMetadataBook, type Release } from '../types/index';
import {
transformMetadataToBook,
transformReleaseToDirectBook,
transformSourceRecordToBook,
} from '../utils/bookTransformers';
@@ -84,3 +85,22 @@ describe('bookTransformers.transformSourceRecordToBook', () => {
expect(isMetadataBook(book)).toBe(false);
});
});
describe('bookTransformers.transformMetadataToBook', () => {
const metadata = {
provider: 'hardcover',
provider_id: '446681',
title: 'Dungeon Crawler Carl',
authors: ['Matt Dinniman'],
};
it('carries the library ownership flags through to the Book', () => {
const book = transformMetadataToBook({ ...metadata, library: { ebook: 'owned' as const } });
expect(book.library).toEqual({ ebook: 'owned' });
});
it('leaves library undefined when the API sends none', () => {
expect(transformMetadataToBook(metadata).library).toBeUndefined();
});
});
@@ -0,0 +1,39 @@
import { describe, expect, it } from 'vitest';
import { isCollectionOnly, isInLibrary } from '../components/shared/LibraryBadge';
describe('isInLibrary', () => {
it('is false without a library result', () => {
expect(isInLibrary(undefined)).toBe(false);
expect(isInLibrary(null)).toBe(false);
expect(isInLibrary({})).toBe(false);
});
it('is false when no format holds it', () => {
expect(isInLibrary({ ebook: null })).toBe(false);
expect(isInLibrary({ ebook: null, audiobook: null })).toBe(false);
});
it('is true for a book held outright or inside a collection', () => {
expect(isInLibrary({ ebook: 'owned' })).toBe(true);
expect(isInLibrary({ ebook: 'collection' })).toBe(true);
expect(isInLibrary({ ebook: null, audiobook: 'owned' })).toBe(true);
});
});
describe('isCollectionOnly', () => {
it('is true only when every holding is inside a collection', () => {
expect(isCollectionOnly({ ebook: 'collection' })).toBe(true);
expect(isCollectionOnly({ ebook: 'collection', audiobook: null })).toBe(true);
});
it('is false when any format holds the book on its own', () => {
expect(isCollectionOnly({ ebook: 'owned' })).toBe(false);
expect(isCollectionOnly({ ebook: 'collection', audiobook: 'owned' })).toBe(false);
});
it('is false when the book is not held at all', () => {
expect(isCollectionOnly({ ebook: null })).toBe(false);
expect(isCollectionOnly(undefined)).toBe(false);
});
});
+9
View File
@@ -32,6 +32,7 @@ export interface Book {
status_message?: string; // Detailed status message (e.g., "Trying Libgen (2/5)")
added_time?: number; // Timestamp when added to queue
content_type?: string; // "ebook", "audiobook", or related book subtype
library?: LibraryOwnership; // "already in your library" flags from the library check
source?: string; // Release source handler (e.g., "direct_download", "prowlarr")
source_display_name?: string; // Human-readable source name (e.g., "Direct Download")
// Metadata provider fields (used in universal search mode)
@@ -277,6 +278,14 @@ export interface QueuedDownloadResult {
export type RequestSubmissionResult = RequestRecord | QueuedDownloadResult;
/** How the library holds a book, per format: owned outright, or inside a collection. */
export type LibraryHolding = 'owned' | 'collection';
export interface LibraryOwnership {
ebook?: LibraryHolding | null;
audiobook?: LibraryHolding | null;
}
export type BooksOutputMode = 'folder' | 'booklore' | 'email';
export interface AppConfig {
+3 -1
View File
@@ -1,4 +1,4 @@
import type { Book, Release } from '../types';
import type { Book, LibraryOwnership, Release } from '../types';
import { isRecord, isStringArray } from './objectHelpers';
/**
@@ -6,6 +6,7 @@ import { isRecord, isStringArray } from './objectHelpers';
* Used by both search and single-book endpoints.
*/
export interface MetadataBookData {
library?: LibraryOwnership; // ownership flags from the library check
provider: string;
provider_display_name?: string;
provider_id: string;
@@ -102,6 +103,7 @@ export function transformMetadataToBook(data: MetadataBookData): Book {
search_author: data.search_author,
authors: data.authors,
titles_by_language: data.titles_by_language,
library: data.library,
info: {
...(data.isbn_13 && { ISBN: data.isbn_13 }),
...(data.isbn_10 && !data.isbn_13 && { ISBN: data.isbn_10 }),