feat: Audible source plugin

[jschloman]

Summary

Add an AudiblePlugin source plugin that loads a user's audiobook listening history from their Amazon/Audible data export. This is the audio companion to the Goodreads and StoryGraph plugins, completing book-format coverage across physical, digital, and audio reading.

Architecture

This plugin follows the project-wide source plugin contract:

1. Download-then-display — the plugin reads only from a previously downloaded local export file. No outbound network or API calls are made at Streamlit runtime. If the data file is absent, fetch() raises FileNotFoundError with a message directing the user to obtain and place the export file.

2. Data sovereignty — the plugin has no knowledge of other sources. fetch() returns only this source's canonical DataFrame. No filtering, joining, or merging with other sources is performed here; that is the exclusive responsibility of DataBroker.

Data export

How to get: amazon.com/hz/privacy-central → "Request your data" → select "Audible" → submit (email notification when ready, typically 2–5 days)

Format: ZIP containing CSV files, including:

• Audible.Library.csv — full purchase/library list with acquisition dates
• Audible.Listening.csv (if available) — per-session listening activity with timestamps and progress

Key fields in Audible.Library.csv:

Field	Maps to
PurchaseDate (YYYY-MM-DD)	timestamp (acquisition date)
Title	sublabel
Author	label
Narrated	preserve as narrator
RuntimeSeconds	preserve as duration_s
ASIN	preserve

Key fields in Audible.Listening.csv (richer but not always present):

Field	Maps to
EventDate	timestamp (actual listen date — prefer over purchase date)
Title	sublabel
AuthorName	label
ProgressPercent	preserve
ListeningLengthSeconds	preserve as session_s

Plugin spec

• PLUGIN_TYPE: what-when
• PLUGIN_ID: audible
• DISPLAY_NAME: Audible Audiobooks
• Config fields: export_dir (path to the unzipped Audible export directory)
• Prefer Audible.Listening.csv when present (actual listen dates); fall back to Audible.Library.csv (purchase dates)
• Parse date strings to Unix timestamps (midnight UTC)
• category → "audiobook"

Normalized output schema

timestamp       int       Unix timestamp (listen date if available, else purchase date)
label           str       Author name
sublabel        str       Book title
category        str       "audiobook"
source_id       str       "audible"
duration_s      int       Total runtime in seconds (NaN if unknown)
narrator        str       Narrator name (preserved from library export)

Acceptance criteria

• AudiblePlugin registered via @register and added to load_builtin_plugins()
• Uses Audible.Listening.csv when present, falls back to Audible.Library.csv
• Date fields parsed correctly from both file variants
• validate_schema() passes on output
• Unit tests covering: library-only export, listening export, fallback behaviour, missing duration, empty export dir
• Plugin contains zero HTTP/network code — reads only from the local export file
• Plugin contains zero references to other source plugins, their schemas, or join keys
• All existing tests continue to pass