feat: Untappd source plugin

[jschloman]

Summary

Add an UntappdPlugin source plugin that loads a user's beer check-in history from their Untappd data export. Untappd check-ins carry both a beer identity (brewery + beer name) and a venue location, making it a natural what-when plugin with preserved venue coordinates for optional where-when enrichment.

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: untappd.com → Profile → Settings → Export Data → "Export Check-ins to CSV" (immediate download)

Format: CSV

Key fields available:

Field	Maps to
beer_name	sublabel
brewery_name	label
beer_type	category
created_at (ISO UTC)	timestamp
rating_score	preserve as rating
venue_name	preserve as venue_name
venue_lat / venue_lng	preserve as venue_lat / venue_lng
comment	preserve
flavor_profiles	preserve
serving_type	preserve
photo_url	preserve

Plugin spec

• PLUGIN_TYPE: what-when
• PLUGIN_ID: untappd
• DISPLAY_NAME: Untappd Beer Check-ins
• Config fields: checkins_csv (path to exported CSV)
• Parse created_at ISO string to Unix timestamp
• label → brewery name, sublabel → beer name, category → beer style/type

Normalized output schema

timestamp       int       Unix timestamp (UTC) of check-in
label           str       Brewery name
sublabel        str       Beer name
category        str       Beer style (e.g. "IPA", "Stout")
source_id       str       "untappd"
rating          float     User rating (0.25–5.0, NaN if unrated)
venue_name      str       Venue name (empty string if no venue tagged)
venue_lat       float     Venue latitude (NaN if no venue)
venue_lng       float     Venue longitude (NaN if no venue)

Acceptance criteria

• UntappdPlugin registered via @register and added to load_builtin_plugins()
• created_at parsed correctly to Unix timestamp
• Check-ins without a venue produce NaN for venue_lat / venue_lng
• validate_schema() passes on output
• Unit tests covering: basic load, unrated check-in, check-in without venue, empty CSV
• 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