Acquisition and Import

This page tracks how Library Manager will acquire and import media.

Planned Acquisition Paths

• Usenet via external indexers and SABnzbd.
• Torrents via external trackers/indexers and qBittorrent.
• Generic Torznab/Newznab endpoints and Prowlarr-compatible aggregator endpoints.
• Direct-source connectors, subject to legal, safety, availability, provider-behavior, credential, and traffic-protection review.
• Manual incoming folders for files acquired outside the app.

Automation-first finding and making available is the primary product focus. Manual incoming is useful for rare imports, staged libraries, and safe lab testing, but it is not the main workflow.

MyAnonamouse.net is expected to be an important source path. Treat it as a first-class research target before implementing a hard-coded connector. The first integration path should support generic/Prowlarr-style tracker setup where possible and document account, ratio, and client requirements carefully.

Generic Indexers

Generic Newznab, Torznab, and Prowlarr-compatible endpoints can be saved from Integrations.

Validation behavior:

• Save the indexer first.
• Test saved indexer runs a backend search validation request.
• The backend loads the stored server-side API key.
• Browser responses expose only success or failure metadata, failure category, protected-route warning, redacted error text, and result count.
• The validation endpoint does not expose API keys, raw secrets, or release download URLs.

This closes the generic indexer/proxy setup loop while leaving MyAnonamouse-specific assumptions for a verified research pass.

Wanted Items

Wanted items support:

• Author
• Series
• Work/book
• Edition
• Format-specific request

Each wanted item can be monitored or manual-only. Authors and series default to monitored. One-off edition and format requests default to manual-only.

Manual Incoming

Manual incoming folders are used when files arrive outside Pagemaster:

• Manual downloads.
• Files copied from old drives.
• Public-domain batches.
• Completed files from a client that is not integrated yet.
• Safe real-file testing before external providers are connected.

Manual incoming behavior:

• Operator-triggered scan first.
• Automatic watching can be enabled later, but defaults off.
• Folder ownership is configurable per folder.
• Default ownership is read-only staging.
• Scanner grouping rules create candidates, so audiobook folders, disc folders, sidecars, single-file ebooks, partial downloads, and weird folders follow the same rules as fixture scanning.
• Incoming files are not moved, deleted, or renamed by default.

Matching

Manual incoming candidates can match wanted items conservatively:

• Exact normalized title plus author: auto-link.
• Strong identifier match later, such as ISBN or ASIN: auto-link.
• Title-only: review.
• Author-only: review.
• Multiple possible matches: review.
• No match: allowed as unmatched/manual import.

Wanted indexer searches now run a first deterministic ranking pass before release candidates are stored:

• Strong normalized release-name matches are labeled linked with high confidence.
• Partial or weak release-name matches stay in review with lower confidence.
• Requested format mismatches add warnings such as wanted-format-mismatch.
• Requested media-kind mismatches add warnings such as wanted-media-kind-mismatch.
• Existing indexer warnings are preserved.

This does not auto-download by itself; it gives the operator a sorted Search Results review surface before selecting a release. Operators can reject an unwanted candidate from Search Results. Rejected candidates remain persisted for audit context, are hidden from the active review list, are blocked from later download handoff, and can be restored from Activity Blocklist if rejected by mistake.

Release Candidates

Every source should produce normalized release-candidate records with:

• Source type.
• Title or release name.
• Media kind.
• Format.
• Size.
• Source path or provider payload.
• Decision status.
• Match status and confidence.
• Wanted item link when matched.
• Warnings.

This keeps manual incoming, Usenet, torrent, direct-source, and future providers on one pipeline.

Download Clients

Usenet and torrent downloads should hand off to external clients rather than downloading inside Pagemaster.

Primary first clients:

• SABnzbd
• qBittorrent

Completed-download detection uses both client API status and configured completed-folder path mappings. Pagemaster does not assume a client path is the same as the local container or LXC path.

SABnzbd Checkpoint

The SABnzbd path now supports connection testing, release handoff, completed-job polling, and completed-path import planning.

Stored settings:

• Base URL.
• Category, initially expected to be books.
• SABnzbd completed path.
• Local Library Manager completed path mapping.
• Protected-route requirement and warning text.
• API key as a server-side secret for local testing.

Public/API behavior:

• Responses can show config metadata and apiKeyConfigured: true.
• Responses must not return the raw API key or a masked version of it.
• Test connection calls SABnzbd's version endpoint.
• Results include success/failure, client name, kind, latency, version when available, auth/network/config failure category, protected-route warning, and redacted error text.

Completed-Download Import Bridge

As of v0.2.5, completed SABnzbd and qBittorrent jobs can become reviewable import work:

• A download job stores the configured download-client source name.
• The background poller resolves that saved source and reads its clientKind.
• SABnzbd history or qBittorrent torrent info is checked for the external job ID.
• When the client reports an importable completed item, Pagemaster records the job as completed with the mapped local path.
• The completed-download importer scans that local path with the normal scanner.
• The scan run and an Audiobookshelf-style dry-run organization plan are persisted.
• Linked release candidates are created when the original handoff came from a wanted item.
• Activity receives acquisition.completed and then acquisition.import_ready.
• Failures while scanning or planning are logged as acquisition.import_failed.

This is still review-gated. The job is not marked imported and no final library copy happens until an operator reviews, approves, and applies the organization plan.

Prototype Run-Out

The current prototype now includes fixture-backed versions of the main M4 acquisition flows:

• Manual incoming fixture scan uses the real scanner against the fixture incoming/ folder.
• Manual incoming scan persists scan state, an organization plan, and normalized release candidates.
• SABnzbd and qBittorrent handoff create wanted items, release candidates, download jobs, completed status, and mapped local paths.
• qBittorrent fixture connection test uses the Web API login plus app-version pattern.
• Saved generic Newznab/Torznab/Prowlarr indexers can be validated from the setup form or Acquisition Sources list.
• Download client credentials remain server-side; public responses expose only configured-state metadata.
• The Pagemaster operator console shows acquisition controls, client checks, download counts, organization review, and copy-only apply controls.

These flows are for safe local testing. Real configured SABnzbd/qBittorrent clients can be contacted from the app, but final managed-output writes remain approval-gated.

Security And Traffic Protection

• Provider credentials, API keys, tokens, cookies, and login details are secrets.
• Secrets stay server-side.
• Secrets are not committed to the repo or wiki.
• Secrets are not returned to the browser.
• API responses return metadata only, such as apiKeyConfigured: true.
• Logs and diagnostics must redact secrets.
• Testing may use disposable credentials stored in SQLite, but production should move toward local secret config or encrypted storage.
• Provider/client config should support protected-route expectations and warnings.
• Pagemaster should document VPN/proxy/network layout, but should not try to be the VPN.
• Test-connection results should include success/failure, name, latency, version when available, indexer result count when relevant, failure category, protected-route warning, and redacted errors only.

Import Principles

• Completed-download detection comes before import.
• Partial downloads must not be imported.
• Duplicate detection and metadata confidence must be visible.
• Import plans should explain proposed matches, filenames, folder destinations, conflicts, and warnings.
• Source files are not deleted or mutated without explicit design and confirmation.
• Per-root behavior should allow read-only, copy, move, cleanup/archive, and profile-specific apply policies.
• Balanced automation should auto-import high-confidence completed downloads while holding collisions, weak metadata, duplicates, and destructive cleanup for operator review.