catalogTitle

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

Type Aliases

CatalogFilterKind

type CatalogFilterKind = "all" | "authors" | "series" | "narrators" | "genres" | "sources";

Client-side catalog filter categories (legacy / local lists).


CatalogSearchField

type CatalogSearchField = "author" | "narrator" | "series" | "genre";

Storefront search facet passed as ?field= on /api/discover/search.


CatalogSortKey

type CatalogSortKey = CatalogSearchSort;

Alias of CatalogSearchSort for Discover UI state.


CatalogTitle

type CatalogTitle = object;

Unified title shape for Discover / Wishlist detail dialogs and result rows.

Properties

asin
asin: string | null;
authors
authors: string | null;
available_through?
available_through?: BranchAvailability[];

Branches of this library that currently list this title.

cover_path
cover_path: string | null;

Same-origin path of the processed cover (see coverSrc).

cover_url
cover_url: string | null;
description?
description?: string | null;
genres?
genres?: string | null;
is_abridged?
is_abridged?: boolean | null;

true abridged / false unabridged when known.

isbn
isbn: string | null;
language?
language?: string | null;
length_minutes?
length_minutes?: number | null;
narrators
narrators: string | null;
notes?
notes?: string | null;
published_at?
published_at?: string | null;
publisher?
publisher?: string | null;
purchase_hints?
purchase_hints?: PurchaseHint[];
rating_overall?
rating_overall?: number | null;

Audible community overall rating (0–5), when known.

reasons?
reasons?: string[];
series
series: string | null;
series_index?
series_index?: string | null;
sources
sources: string[];
store_editions
store_editions: StoreEdition[];
subtitle?
subtitle?: string | null;
title
title: string;
wish_count?
wish_count?: number;

Distinct wisher count (may exceed wishers.length).

wishers?
wishers?: QueueWisher[];

People who have this title on an open wishlist.

wishlist_uuid?
wishlist_uuid?: string | null;

Present when the title is already on the current user’s wishlist.

work_key
work_key: string;

RuntimeBucket

type RuntimeBucket = "any" | "under6" | "6to12" | "12to20" | "over20";

Discover runtime length buckets for server filters.

Variables

CATALOG_FILTER_KINDS

const CATALOG_FILTER_KINDS: object[];

UI labels for CatalogFilterKind.

Type Declaration

Name Type
label string
value CatalogFilterKind

CATALOG_LANGUAGE_ALL

const CATALOG_LANGUAGE_ALL: "__all__" = "__all__";

Wire value for “no hard language filter” in the Discover language control.


CATALOG_LANGUAGE_OPTIONS

const CATALOG_LANGUAGE_OPTIONS: object[];

Language select options for Discover (includes CATALOG_LANGUAGE_ALL).

Type Declaration

Name Type
label string
value string

CATALOG_SORT_OPTIONS

const CATALOG_SORT_OPTIONS: object[];

UI labels for Discover catalog sort keys.

Type Declaration

Name Type
label string
value CatalogSortKey

CATALOG_SOURCE_IDS

const CATALOG_SOURCE_IDS: readonly ["audible", "chirp", "libro", "graphicaudio"];

Known storefront ids for prefs / empty facet fallbacks.


RUNTIME_BUCKET_OPTIONS

const RUNTIME_BUCKET_OPTIONS: object[];

UI options and minute bounds for RuntimeBucket.

Type Declaration

Name Type
label string
max? number
min? number
value RuntimeBucket

VIRTUAL_VOICE_EXCLUDE

const VIRTUAL_VOICE_EXCLUDE: "Virtual Voice" = "Virtual Voice";

Narrator name excluded when “Hide Virtual Voice” is enabled.

Functions

applyTitleMeta()

function applyTitleMeta(title, meta): CatalogTitle;

Overlays public Audnexus / catalog metadata onto a sparse CatalogTitle.

An Audnexus ASIN is a trusted Audible product id (same rule as purchase-hint resolve), so a missing Audible store edition is filled in for Where-to-buy.

Parameters

Parameter Type Description
title CatalogTitle Existing title.
meta TitleMeta | null | undefined Fetched metadata (no-op when nullish).

Returns

CatalogTitle

Merged title.


attachWishersFromQueue()

function attachWishersFromQueue(title, queue): CatalogTitle;

Copies household queue identity onto a personal wishlist title.

Personal TitleRequest rows do not include household wishers or the merged store editions from the global queue. Discover shelves use that merged row, so Wishlist must union the same editions or Where-to-buy diverges.

Parameters

Parameter Type Description
title CatalogTitle Catalog title, typically from catalogTitleFromRequest.
queue readonly GlobalQueueEntry[] Global request-queue entries.

Returns

CatalogTitle

Title with wishers, identifiers, and store editions from the queue.


attachWishlistCommerce()

function attachWishlistCommerce(title, wishlist): CatalogTitle;

Unions snapshotted wishlist store editions / hints onto a Discover (or other) catalog title so Where-to-buy matches the Wishlist detail for the same work.

Parameters

Parameter Type Description
title CatalogTitle Catalog title from search or shelves.
wishlist readonly TitleRequest[] Open personal wishlist rows.

Returns

CatalogTitle

Title with wishlist commerce merged when a row matches.


buildCatalogSearchFilters()

function buildCatalogSearchFilters(opts): CatalogSearchFilters;

Builds the server filter payload from UI multi-select state.

Parameters

Parameter Type Description
opts { authors: string[]; excludeSources?: string[]; genres: string[]; hideVirtualVoice: boolean; languages?: string[]; minRating?: number | null; narrators: string[]; runtimeBucket?: RuntimeBucket; series: string[]; sources?: string[]; } Include lists, exclusions, rating, and runtime bucket.
opts.authors string[] -
opts.excludeSources? string[] -
opts.genres string[] -
opts.hideVirtualVoice boolean -
opts.languages? string[] -
opts.minRating? number | null -
opts.narrators string[] -
opts.runtimeBucket? RuntimeBucket -
opts.series string[] -
opts.sources? string[] Deprecated prefer excludeSources

Returns

CatalogSearchFilters

CatalogSearchFilters for searchCatalog.


catalogFilterValues()

function catalogFilterValues(titles, kind): object[];

Builds distinct local filter options from a title list.

Parameters

Parameter Type Description
titles CatalogTitle[] Catalog titles.
kind CatalogFilterKind Filter category.

Returns

object[]

Value/label pairs.


catalogIdentityMatches()

function catalogIdentityMatches(a, b): boolean;

True when two catalog identities refer to the same work (work key, ASIN, ISBN, or title).

Parameters

Parameter Type Description
a { asin?: string | null; isbn?: string | null; title?: string | null; work_key?: string | null; } First identity.
a.asin? string | null -
a.isbn? string | null -
a.title? string | null -
a.work_key? string | null -
b { asin?: string | null; isbn?: string | null; title?: string | null; work_key?: string | null; } Second identity.
b.asin? string | null -
b.isbn? string | null -
b.title? string | null -
b.work_key? string | null -

Returns

boolean

Whether the rows should share store editions and wishlist state.


catalogLanguageRank()

function catalogLanguageRank(hitLanguage, preferred?): number;

Soft language rank for ordering search hits.

Parameters

Parameter Type Description
hitLanguage string | null | undefined Language on the hit.
preferred? string Preferred language (default: browser).

Returns

number

0 preferred, 1 unknown, 2 other.


catalogLanguageSearchOpts()

function catalogLanguageSearchOpts(filterLanguage): object;

Maps Discover language control → hard filter / all-languages flag.

Parameters

Parameter Type Description
filterLanguage string Selected language code or CATALOG_LANGUAGE_ALL.

Returns

object

Server search language options.

Name Type
allLanguages? boolean
languages? string[]

catalogLanguageSelectOptions()

function catalogLanguageSelectOptions(preferred?): object[];

Options for the language <select>, ensuring the browser default appears.

Parameters

Parameter Type Description
preferred? string Preferred BCP-47 primary tag (default: browser language).

Returns

object[]

Value/label pairs for the control.


catalogMatchesFilter()

function catalogMatchesFilter(
   title, 
   kind, 
   value
): boolean;

Returns whether a title matches a local catalog filter.

Parameters

Parameter Type Description
title CatalogTitle Catalog title.
kind CatalogFilterKind Filter category.
value string Selected value (all / empty always matches).

Returns

boolean

True when visible under the filter.


catalogTitleFromHit()

function catalogTitleFromHit(hit, wishlistUuid?): CatalogTitle;

Maps a catalog search hit into a CatalogTitle.

Parameters

Parameter Type Description
hit CatalogSearchHit Search hit.
wishlistUuid? string | null Optional wishlist uuid when already wished.

Returns

CatalogTitle

Unified catalog title.


catalogTitleFromQueueEntry()

function catalogTitleFromQueueEntry(entry, wishlistUuid?): CatalogTitle;

Maps a global request-queue entry into a CatalogTitle.

Parameters

Parameter Type Description
entry GlobalQueueEntry Queue entry.
wishlistUuid? string | null Optional wishlist uuid when the current user also wished it.

Returns

CatalogTitle

Unified catalog title.


catalogTitleFromRec()

function catalogTitleFromRec(rec, wishlistUuid?): CatalogTitle;

Maps a Discover recommendation into a CatalogTitle.

Parameters

Parameter Type Description
rec Recommendation Recommendation row.
wishlistUuid? string | null Optional wishlist uuid override.

Returns

CatalogTitle

Unified catalog title.


catalogTitleFromRequest()

function catalogTitleFromRequest(req): CatalogTitle;

Maps a wishlist title-request into a CatalogTitle.

Parameters

Parameter Type Description
req TitleRequest Wishlist row.

Returns

CatalogTitle

Unified catalog title (with wishlist_uuid set).


defaultSortDirFor()

function defaultSortDirFor(sort): "desc" | "asc";

Default sort direction for a catalog sort key.

Parameters

Parameter Type Description
sort CatalogSearchSort Catalog sort key.

Returns

"desc" | "asc"

asc for title/author/length; otherwise desc.


descriptionLooksComplete()

function descriptionLooksComplete(raw): boolean;

Returns whether a blurb looks like a full store description, not a truncated teaser.

Parameters

Parameter Type Description
raw string | null | undefined Optional HTML/plain description.

Returns

boolean

True when length and ending look complete.


discoverSearchFromMeta()

function discoverSearchFromMeta(kind, value): object;

Composes a Discover catalog search + facet filter from a title-detail meta link.

Parameters

Parameter Type Description
kind "series" | "authors" | "narrators" | "genres" Metadata link kind (authors / narrators / series / genres).
value string Linked label text.

Returns

object

Search query, field, sort, and matching include filters.

Name Type
authors? string[]
field CatalogSearchField
genres? string[]
hideVirtualVoice boolean
narrators? string[]
q string
series? string[]
sort CatalogSearchSort

formatPurchasePrices()

function formatPurchasePrices(hint): string | null;

Compact purchase price line; prefers dual member/list when both exist.

Parameters

Parameter Type Description
hint { list_price_label?: string | null; member_price_label?: string | null; price_label?: string | null; } Price label fields from a purchase hint.
hint.list_price_label? string | null -
hint.member_price_label? string | null -
hint.price_label? string | null -

Returns

string | null

Display string, or null when no prices.


formatSeriesLabel()

function formatSeriesLabel(series, seriesIndex?): string | null;

Formats series name + book number for list/card rows (Sun Eater #3).

Parameters

Parameter Type Description
series string | null | undefined Series name.
seriesIndex? string | null Optional book number.

Returns

string | null

Label, or null when series is empty.


formatShelfBestPrice()

function formatShelfBestPrice(hint): string | null;

Single best price for shelf cards (member / primary only — no dual list).

Parameters

Parameter Type Description
hint { list_price_label?: string | null; member_price_label?: string | null; price_label?: string | null; } Price label fields from a purchase hint.
hint.list_price_label? string | null -
hint.member_price_label? string | null -
hint.price_label? string | null -

Returns

string | null

Display string, or null when no prices.


pickBetterDescription()

function pickBetterDescription(a, b): string | null;

Prefers richer store/Audnexus blurbs over short plain catalog teasers.

HTML descriptions win over plain text; otherwise the longer string wins.

Parameters

Parameter Type Description
a string | null | undefined Current description.
b string | null | undefined Incoming description.

Returns

string | null

Preferred non-empty description, or null.


preferCatalogLanguageOrder()

function preferCatalogLanguageOrder<T>(items, preferred?): T[];

Stable soft-sort: preferred language first, then unknown, then other.

Type Parameters

Type Parameter
<a id="type-parameter-t"></a> T extends object

Parameters

Parameter Type Description
items T[] Rows with optional language.
preferred? string Preferred language code.

Returns

T[]

New array sorted by catalogLanguageRank.


preferredCatalogLanguage()

function preferredCatalogLanguage(): string;

Primary BCP-47 language tag from the browser (default en).

Returns

string

Two/three-letter language code.


runtimeBucketBounds()

function runtimeBucketBounds(bucket): object;

Maps a runtime bucket to server min/max length filters.

Parameters

Parameter Type Description
bucket RuntimeBucket Selected runtime bucket.

Returns

object

Optional min_length_minutes / max_length_minutes.

Name Type
max_length_minutes? number
min_length_minutes? number

seriesChoices()

function seriesChoices(names): string[];

One label per series among names that may spell it differently.

Names are grouped by seriesKey; each group shows the spelling most of its names use (the first seen on a tie).

Parameters

Parameter Type Description
names Iterable<string> Series names, blanks allowed.

Returns

string[]

The labels, sorted.


seriesKey()

function seriesKey(name): string;

The key series names are grouped by.

Stores spell one series differently (King & Maxwell, King and Maxwell); the key reads & as and and ignores case, accents, apostrophes, parenthesised text and extra spaces, as the server's series filter does.

Parameters

Parameter Type Description
name string A series name.

Returns

string

The key; empty for a blank name.


sortCatalogTitles()

function sortCatalogTitles(titles, sortKey): CatalogTitle[];

Client-sorts catalog titles for keys the server does not re-rank locally.

Relevance / popularity / rating keep input order (server ranking).

Parameters

Parameter Type Description
titles CatalogTitle[] Catalog titles.
sortKey CatalogSearchSort Sort key.

Returns

CatalogTitle[]

Sorted copy or original order for server-ranked keys.


splitMetaList()

function splitMetaList(raw): string[];

Splits genre / category blobs (Fantasy; Epic / comma / pipe).

Parameters

Parameter Type Description
raw string | null | undefined Combined list string.

Returns

string[]

Trimmed non-empty parts.


storeIconSrc()

function storeIconSrc(source): string | undefined;

Same-origin icon for a storefront or integration id (audible, libro, …).

Bookclerk downloads the icon the plugin names and serves a 128 px copy; the route fails when no deployed plugin has that id, so callers fall back to a monogram on error.

Parameters

Parameter Type Description
source string Store id.

Returns

string | undefined

Icon path, or undefined for an id that cannot name a plugin.


storeLabel()

function storeLabel(source): string;

Human-readable label for a storefront plugin id in Discover filters.

Falls back to the raw id when the store is unknown so future plugins still render.

Parameters

Parameter Type Description
source string Store id (audible, libro, …).

Returns

string

Display name for UI chrome.


titleNeedsMeta()

function titleNeedsMeta(title): boolean;

Returns whether a title still needs public metadata enrichment.

Parameters

Parameter Type Description
title CatalogTitle Catalog title.

Returns

boolean

True when core fields (description, length, publisher, narrators, series index) are incomplete.


titleNeedsShelfMeta()

function titleNeedsShelfMeta(title): boolean;

Returns whether a shelf card should pull title-meta (includes missing overall rating).

Parameters

Parameter Type Description
title CatalogTitle Catalog title.

Returns

boolean

True when titleNeedsMeta or rating_overall is unknown.


withAudibleEditionFromAsin()

function withAudibleEditionFromAsin<T>(row): T;

Adds an Audible store edition when an ASIN is known and no Audible row exists.

Used by Discover shelves, Wishlist enrichment, and the shared detail modal so Where-to-buy does not depend on which surface fetched title-meta first.

Type Parameters

Type Parameter
<a id="type-parameter-t-1"></a> T extends object

Parameters

Parameter Type Description
row T Title or detail fields that carry editions.

Returns

T

The same object, or a copy with an Audible edition appended.

Generated from ui/src/lib at main · View as Markdown