immich integration

[slothful-vassal]

Summary

• when uploading/importing a trail, waypoints will be created based on available immich photos (check for time and gps match)
• when editing/creating a trail, waypoints can be enriched with immich photos or waypoints can be created based on immich photos
• immich photos can be persisted in wanderer db or just a link to the immich asset will be stored
• there are two available link modes: for private trails only, for all trails
• when immich assets are not stored in wanderer db: to reduce immich api calls especially for public trails, the photos are server side cached on first request
• when changing the storage mode, the will be asked to download the affected immich assets or to keep the existing links
• immich api key permissions: asset.read, asset.view, asset.download

Important

New asset collection introduced. All existing photos will be moved and linked to this asset collection (one way migration - no roll back available). Users have to ensure they have a full backup.

exif-js replaced with ExifReader

Screenshots

Tests

Migration / Upgrade

• Fresh DB and existing DB. Run migrations against a brand-new database and against a copy of an existing one. Expect: the assets collection is created, installed_plugins.type accepts assets, and existing trail plugins keep working.

Plugin Settings & Discovery

• Listing and sorting. Open Settings → Plugins. Expect: plugins sorted alphabetically first by type, then by name; Immich shows up as an asset plugin.
• Configure / save / enable. Configure Immich, save, and toggle it on. Expect: settings persist across reload; the plugin can be enabled and disabled.

Immich Connection

• Minimal API-key scopes. Use an Immich key with only user.read, asset.read, asset.view, asset.download. Expect: connection check and photo previews work without any broader permission.
• Error cases. Try an invalid URL, invalid API key, and a key missing permissions. Expect: an understandable error message; no half-created or broken plugin instance is left behind.

Photo Import & Auto-Attach

• Auto-attach default. On a fresh instance with no explicit auto-attach config, import/upload a trail with nearby (time/location) Immich photos. Expect: matching photos auto-attach (the default is enabled / opt-out).
• Explicit auto-attach off. Disable auto-attach for a provider and re-import. Expect: no photos are attached automatically.
• Relevance. Expect: only geotagged photos matching the trail in time and location are suggested/attached; unrelated photos are not.

Trail Editor & Waypoints

• Photo picker. In the trail editor, search Immich photos, load thumbnails, import selected photos, save, and reopen the trail. Expect: imported photos persist and render.
• Waypoint flow. For a waypoint with coordinates, show and attach matching Immich photos; also create photo waypoints directly from Immich photos.
• Failed / empty import. Trigger an import-to-waypoint that fails or returns no photos (e.g. Immich errors mid-import). Expect: no orphaned/empty waypoint is left behind.

Photo Storage Modes & Visibility

• Store in wanderer (copy). Expect: photo downloaded into wanderer immediately; works regardless of trail privacy.
• Link remote references On a private trail, expect: photo stays a remote link and is fetched on demand. The same linked photo must not be retrievable by an anonymous user or a different user.
• Shared private trail. Share a private trail (with a linked photo) with another user. Expect: the share recipient can view the photo (fetched via the author's Immich instance); non-recipients still cannot.
• Publish transition. Make a private trail with linked private photos public. Expect: the linked photos are materialized during publish; if Immich is unreachable, publishing is blocked with a clear error rather than leaving a broken or externally-dependent public photo.

Remote Asset Lifecycle

• Missing. Delete a linked photo in Immich, then access it / run repair. Expect: status becomes missing; no broken image leaks; repair reports it.
• Inaccessible. Make Immich temporarily unreachable, then access a linked photo. Expect: status becomes inaccessible; recovers via repair once Immich is reachable again.
• Disable guard + cleanup. Disable the Immich plugin while linked remote photos still exist. Expect: the disable is guarded with a clear message ("Plugin has linked remote photos…"), and the materialize/delete flow resolves it so that no broken photos remain afterward.

Trail Merge

• Merge with assets. Merge two trails that both have (remote-linked) photos. Expect: assets are reassigned to the target trail, no orphaned assets remain, and the photo count in the merge stats is correct.

Regression Smoke

• Existing trail plugins. Briefly exercise an existing trail-plugin flow (save/sync komoot, Hammerhead, or Strava) to catch regressions in the generic plugin changes.

[slothful-vassal]

back to draft: try to implement as plugin