Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion documentation/features/bookdate.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@ Personalized audiobook discovery using OpenAI/Claude APIs. Admin configures AI p
- Request: 20 recommendations (expect ~10 after filtering)

3. **Post-Processing:**
- Match to Audnexus (database cache first, API fallback)
- Match to Audnexus (database cache first, API fallback: first Audible search result, filtered by `audible.language_filter` when on)
- Filter: Already in library (uses centralized audiobook-matcher.ts - same as homepage), already requested, already swiped
- Two-stage library filtering:
- Stage 1: Fuzzy match with AI-provided title/author (before Audnexus)
Expand Down
9 changes: 9 additions & 0 deletions documentation/integrations/audible.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ Populates every `AudibleAudiobook` field. Covered:

- **Catalog API cannot filter preorders or surface curated bestsellers.** The API's `BestSellers` sort is a right-now velocity rank that spikes on launch-day promos and preorder windows; the `-ReleaseDate` sort returns 100% future preorders. There is no server-side `release_time`, `released-only`, `customer_rights`, or alternate sort (`Reviewed`, `MostListened`, etc.) — every plausible variant was tested and silently ignored. This is why the nightly refresh job uses the curated HTML storefront pages instead.
- **`author=` takes a name, not an ASIN.** The catalog API has no ASIN-based author param. `searchByAuthorAsin()` queries by name, then filters client-side: keeps only products where `products[].authors[].asin === authorAsin`. Preserves ASIN-authoritative author identity. Also filters by `product.language` via `isAcceptedLanguage()` for the configured region.
- **Keyword search returns every language.** `search()` sends no language param, so results include editions in languages other than the region's. Opt-in filter, see Language Filter below.
- **Invalid ASIN returns HTTP 200 with stub body.** `/1.0/catalog/products/{asin}` responds 200 with `{product: {asin: INPUT}}` and no other fields. `fetchAudibleDetailsFromApi()` detects this via missing `product.title` and returns `null`.
- **`publisher_summary` is HTML.** Service strips tags via inline `stripHtml()` helper (regex-based, no cheerio) before populating `description`. Falls back to `merchandising_summary` (plain text) if `publisher_summary` missing.
- **Series is an array.** `products[].series[]` — a book may belong to multiple series. Service picks the first entry with non-empty `sequence`, else the first entry. `sequence` is cleaned by extracting first `/\d+(?:\.\d+)?/` match for numeric ordering.
Expand Down Expand Up @@ -111,6 +112,14 @@ Configurable Audible region for accurate metadata matching across international
- Cache clearing: Region change clears ConfigService cache and AudibleService state.
- Automatic refresh: Region change triggers `audible_refresh` job.

**Language Filter:**
- Key: `audible.language_filter` (`'true'`/`'false'`, default off). Read via `ConfigService.getAudibleLanguageFilter()`.
- `search(query, page, { respectLanguageFilter: true })`: when the key is on, drops products whose `language` fails `isAcceptedLanguage()` for the region. Products without `language` are kept.
- Opted in: search page (`/api/audiobooks/search`), BookDate (`matchToAudnexus`), shelf sync (`performAudibleLookup`). Not opted in: bulk import (matches files already on disk).
- Shelf sync: a book with no edition in the region's language becomes a `noMatch` mapping (retried every 7 days). Mappings resolved before the filter was enabled are not re-resolved.
- `hasMore` is computed on the raw page, so a page whose books were all filtered out does not end pagination for API callers. `totalResults` stays Audible's unfiltered total.
- Discovery pages (popular, new releases, categories) are not filtered: they come from the region's HTML storefronts, not keyword search.

**Per-region HTTP clients (on init):**
- `apiClient` — `baseURL=apiBaseUrl`, `Accept: application/json`, `User-Agent: ReadMeABook/1.0`, no language/ipRedirect params. Used for the real-time JSON catalog operations (search, author books, categories listing, per-ASIN details fallback).
- `htmlClient` — `baseURL=baseUrl`, rotating browser headers (`pickUserAgent` + `getBrowserHeaders`), default params `ipRedirectOverride=true` + `language=<audibleLocaleParam>`. Used by the nightly discovery refresh (`/adblbestsellers`, `/newreleases`, `/search?node=...`), by `audible-series.ts`, and by `getBaseUrl()`-based link generation.
Expand Down
15 changes: 10 additions & 5 deletions documentation/settings-pages.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,8 +64,8 @@ src/app/admin/settings/

## Sections

1. **Plex** - URL, token (masked), library ID, Audible region, filesystem scan trigger toggle
2. **Audiobookshelf** - URL, API token (masked), library ID, Audible region, filesystem scan trigger toggle
1. **Plex** - URL, token (masked), library ID, Audible region, language filter toggle, filesystem scan trigger toggle
2. **Audiobookshelf** - URL, API token (masked), library ID, Audible region, language filter toggle, filesystem scan trigger toggle
3. **Prowlarr** - URL, API key (masked), indexer selection with priority, seeding time, RSS monitoring toggle, **audiobook/ebook categories per indexer**
4. **Download Client** - Type (qBittorrent, Transmission, SABnzbd), URL, credentials (masked), custom download path (per-client relative sub-path with live preview)
5. **Paths** - Download + media directories, audiobook organization template, metadata tagging toggle, chapter merging toggle, Plex format coercion toggle
Expand Down Expand Up @@ -176,6 +176,11 @@ src/app/admin/settings/
- **Smart re-initialization**: Service automatically detects region changes and re-initializes before each request
- See: `documentation/integrations/audible.md` for technical details

**Language filter toggle** ("Only show books in the region's language"):
- Key: `audible.language_filter` (boolean as string, default off)
- UI: `AudibleLanguageFilterOption` checkbox under the region dropdown, shared by both sections
- Effect: hides other-language editions from search, BookDate and shelf sync. See `documentation/integrations/audible.md#region-configuration`

## Audiobook Organization Template

**Purpose:** Customize how audiobooks are organized within the media directory using variable-based templates.
Expand Down Expand Up @@ -310,9 +315,9 @@ src/app/admin/settings/
- Requires prior successful test if values changed

**PUT /api/admin/settings/audible**
- Updates Audible region
- Body: `{ region: string }` (one of: us, ca, uk, au, in, es, fr)
- No validation required
- Updates Audible region and, when sent, the language filter
- Body: `{ region: string, languageFilter?: boolean }` (region one of: us, ca, uk, au, in, es, fr)
- 400 if `region` is invalid or `languageFilter` is not a boolean; omitted `languageFilter` leaves the stored value unchanged

**PUT /api/admin/settings/prowlarr/indexers**
- Updates indexer configuration (enabled, priority, seeding time, RSS)
Expand Down
7 changes: 5 additions & 2 deletions src/app/admin/settings/lib/helpers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,11 +39,14 @@ export const saveTabSettings = async (
): Promise<void> => {
switch (activeTab) {
case 'library':
// Save Audible region
// Save Audible region and language filter
await fetchWithAuth('/api/admin/settings/audible', {
method: 'PUT',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ region: settings.audibleRegion }),
body: JSON.stringify({
region: settings.audibleRegion,
languageFilter: settings.audibleLanguageFilter,
}),
}).then(res => {
if (!res.ok) throw new Error('Failed to save Audible region settings');
});
Expand Down
1 change: 1 addition & 0 deletions src/app/admin/settings/lib/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ export interface Settings {
hasLocalUsers: boolean;
hasLocalAdmins: boolean;
audibleRegion: string;
audibleLanguageFilter: boolean;
plex: PlexSettings;
audiobookshelf: AudiobookshelfSettings;
oidc: OIDCSettings;
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
/**
* Component: Audible Language Filter Toggle
* Documentation: documentation/settings-pages.md
*/

import { Settings } from '../../lib/types';

interface AudibleLanguageFilterOptionProps {
settings: Settings;
onChange: (settings: Settings) => void;
}

export function AudibleLanguageFilterOption({ settings, onChange }: AudibleLanguageFilterOptionProps) {
return (
<label className="flex items-start gap-3 cursor-pointer">
<input
type="checkbox"
checked={settings.audibleLanguageFilter}
onChange={(e) => onChange({ ...settings, audibleLanguageFilter: e.target.checked })}
className="mt-1 h-4 w-4 rounded border-gray-300 text-blue-600 focus:ring-blue-500 dark:border-gray-600 dark:bg-gray-800"
/>
<div className="flex-1">
<span className="text-sm font-medium text-gray-700 dark:text-gray-300">
Only show books in the region&apos;s language
</span>
<p className="text-sm text-gray-500 dark:text-gray-400 mt-1">
Hides editions that are not in the region&apos;s language from search, BookDate and shelf
sync. Books with no language listed are kept.
</p>
</div>
</label>
);
}
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import { Input } from '@/components/ui/Input';
import { Button } from '@/components/ui/Button';
import { Settings, ABSLibrary } from '../../lib/types';
import { AUDIBLE_REGIONS } from '@/lib/types/audible';
import { AudibleLanguageFilterOption } from './AudibleLanguageFilterOption';

interface AudiobookshelfSectionProps {
settings: Settings;
Expand Down Expand Up @@ -199,6 +200,7 @@ export function AudiobookshelfSection({
Select the Audible region that matches your metadata engine (Audnexus/Audible Agent)
configuration in Audiobookshelf. This ensures accurate book matching and metadata.
</p>
<AudibleLanguageFilterOption settings={settings} onChange={onChange} />
</div>

<div className="border-t border-gray-200 dark:border-gray-700 pt-6">
Expand Down
2 changes: 2 additions & 0 deletions src/app/admin/settings/tabs/LibraryTab/PlexSection.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import { Input } from '@/components/ui/Input';
import { Button } from '@/components/ui/Button';
import { Settings, PlexLibrary } from '../../lib/types';
import { AUDIBLE_REGIONS } from '@/lib/types/audible';
import { AudibleLanguageFilterOption } from './AudibleLanguageFilterOption';

interface PlexSectionProps {
settings: Settings;
Expand Down Expand Up @@ -199,6 +200,7 @@ export function PlexSection({
Select the Audible region that matches your metadata engine (Audnexus/Audible Agent)
configuration in Plex. This ensures accurate book matching and metadata.
</p>
<AudibleLanguageFilterOption settings={settings} onChange={onChange} />
</div>

<div className="border-t border-gray-200 dark:border-gray-700 pt-6">
Expand Down
27 changes: 23 additions & 4 deletions src/app/api/admin/settings/audible/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ export async function PUT(request: NextRequest) {
return requireAuth(request, async (req: AuthenticatedRequest) => {
return requireAdmin(req, async () => {
try {
const { region } = await request.json();
const { region, languageFilter } = await request.json();

// Validate region
if (!region || !VALID_REGIONS.includes(region)) {
Expand All @@ -30,19 +30,38 @@ export async function PUT(request: NextRequest) {
);
}

// Optional: omitting languageFilter keeps the stored value
if (languageFilter !== undefined && typeof languageFilter !== 'boolean') {
logger.warn('Invalid language filter provided', { languageFilter });
return NextResponse.json(
{ success: false, error: 'languageFilter must be a boolean' },
{ status: 400 }
);
}

// Save region to configuration
const configService = getConfigService();
await configService.setMany([
const updates = [
{
key: 'audible.region',
value: region,
category: 'system',
description: 'Audible region for metadata and search',
},
]);
];
if (languageFilter !== undefined) {
updates.push({
key: 'audible.language_filter',
value: String(languageFilter),
category: 'system',
description: "Hide books not in the region's language from search, BookDate and shelf sync",
});
}
await configService.setMany(updates);

// Clear config cache to ensure new region is loaded immediately
// Clear config cache to ensure new values are loaded immediately
configService.clearCache('audible.region');
configService.clearCache('audible.language_filter');

// Force AudibleService to re-initialize with new region
const audibleService = getAudibleService();
Expand Down
1 change: 1 addition & 0 deletions src/app/api/admin/settings/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,7 @@ export async function GET(request: NextRequest) {
hasLocalUsers,
hasLocalAdmins,
audibleRegion: configMap.get('audible.region') || 'us',
audibleLanguageFilter: configMap.get('audible.language_filter') === 'true',
plex: {
url: configMap.get('plex_url') || '',
token: maskValue('token', configMap.get('plex_token')),
Expand Down
2 changes: 1 addition & 1 deletion src/app/api/audiobooks/search/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ export async function GET(request: NextRequest) {
}

const audibleService = getAudibleService();
const results = await audibleService.search(query, page);
const results = await audibleService.search(query, page, { respectLanguageFilter: true });

// Get current user (optional — JWT or API token — for request-status enrichment)
const currentUser = await getCurrentUserAsync(request);
Expand Down
2 changes: 1 addition & 1 deletion src/lib/bookdate/helpers.ts
Original file line number Diff line number Diff line change
Expand Up @@ -922,7 +922,7 @@ export async function matchToAudnexus(
logger.info(`Not in cache, searching Audible for "${title}" by ${author}...`);
const audibleService = new AudibleService();
const searchQuery = `${title} ${author}`;
const searchResults = await audibleService.search(searchQuery, 1);
const searchResults = await audibleService.search(searchQuery, 1, { respectLanguageFilter: true });

if (!searchResults.results || searchResults.results.length === 0) {
logger.warn(`No Audible search results for "${title}" by ${author}`);
Expand Down
32 changes: 27 additions & 5 deletions src/lib/integrations/audible.service.ts
Original file line number Diff line number Diff line change
Expand Up @@ -532,7 +532,16 @@ export class AudibleService {
return audiobooks;
}

async search(query: string, page: number = 1): Promise<AudibleSearchResult> {
/**
* Keyword search on the catalog API, which returns every language.
* `respectLanguageFilter` applies the admin `audible.language_filter` setting
* (products with no language are kept).
*/
async search(
query: string,
page: number = 1,
options: { respectLanguageFilter?: boolean } = {},
): Promise<AudibleSearchResult> {
await this.initialize();

try {
Expand All @@ -556,20 +565,33 @@ export class AudibleService {
const products = envelope.products ?? [];
const totalResults = envelope.total_results ?? 0;

const results = products.map(mapCatalogProduct);
const filterLanguage =
options.respectLanguageFilter && (await getConfigService().getAudibleLanguageFilter());
const kept = filterLanguage
? products.filter(
(p) => !p.language || isAcceptedLanguage(p.language, getLanguageForRegion(this.region)),
)
: products;
const results = kept.map(mapCatalogProduct);

logger.info(` Found ${results.length} results for "${query}"`);
logger.info(
` Found ${results.length} results for "${query}"` +
(kept.length < products.length
? ` (${products.length - kept.length} in other languages hidden)`
: ''),
);

// Paginate on the raw page: a page whose books were all filtered out is not the last one
return {
query,
results,
totalResults,
page,
hasMore:
results.length > 0 &&
products.length > 0 &&
(totalResults > 0
? totalResults > page * AUDIBLE_PAGE_SIZE
: results.length >= AUDIBLE_PAGE_SIZE),
: products.length >= AUDIBLE_PAGE_SIZE),
};
} catch (error) {
logger.error('Search failed', {
Expand Down
7 changes: 7 additions & 0 deletions src/lib/services/config.service.ts
Original file line number Diff line number Diff line change
Expand Up @@ -237,6 +237,13 @@ export class ConfigurationService {
return (region as AudibleRegion) || DEFAULT_AUDIBLE_REGION;
}

/**
* Check if the Audible language filter is enabled
*/
async getAudibleLanguageFilter(): Promise<boolean> {
return (await this.get('audible.language_filter')) === 'true';
}

/**
* Clear the cache for a specific key or all keys
*/
Expand Down
4 changes: 2 additions & 2 deletions src/lib/services/shelf-sync-core.service.ts
Original file line number Diff line number Diff line change
Expand Up @@ -205,15 +205,15 @@ async function performAudibleLookup(
const fullQuery = `${book.title} ${book.author}`;
log.info(`Searching Audible for: "${fullQuery}"`);

let searchResult = await audibleService.search(fullQuery);
let searchResult = await audibleService.search(fullQuery, 1, { respectLanguageFilter: true });
let firstResult = searchResult.results[0];

if (!firstResult?.asin) {
const cleanTitle = book.title.replace(/\s*\(.*\)\s*$/, '').trim();
if (cleanTitle !== book.title) {
const cleanQuery = `${cleanTitle} ${book.author}`;
log.info(`No results with full title, retrying without series info: "${cleanQuery}"`);
searchResult = await audibleService.search(cleanQuery);
searchResult = await audibleService.search(cleanQuery, 1, { respectLanguageFilter: true });
firstResult = searchResult.results[0];
}
}
Expand Down
Loading