Update Plex Functionality

[DannyTheHeretic]

Add Plex user switching via shared server tokens

What changed

1. Implemented SwitchUser() using Plex shared_servers endpoint

• Added XML parsing support for:
  https://plex.tv/api/servers/{machineId}/shared_servers
• Introduced PlexSharedServers / PlexSharedUser structs to match Plex’s actual response format.
• Introduced PlexSharedServers / PlexSharedUser structs to match Plex’s actual XML response format.

---

2. Replaced incorrect JSON-based assumptions with XML parsing

• Updated implementation to correctly parse Plex XML MediaContainer response
• Removed reliance on non-existent JSON formatting for /shared_servers

---

3. Improved user resolution logic

• User lookup now matches across multiple fields:
• username
• email
• name
• userID
• Handles real-world Plex inconsistencies where fields may be missing or empty for shared/home users

---

4. Introduced isolated per-user Plex client context

• SwitchUser() returns a new Plex client instance
• Deep-copies headers to prevent shared mutation between admin and user sessions
• Ensures X-Plex-Token is correctly scoped per user session

---

5. Added hub-based search resolution for library items

• Implemented Hub Search (/hubs/search) parsing and normalization
• Extracts track metadata from Plex Hub results and maps them into a consistent internal search structure
• Adds logic to filter and normalize results into PlexSearch format for downstream processing

Key improvements:

• Standardizes Plex hub response (Hub -> Metadata) into a unified search model
• Improves matching reliability for tracks across:
• title
• album
• artist
• file path
• duration tolerance matching
• Enables deterministic selection of correct ratingKey / key for playlist operations

---

6. Ensured correct token source for user impersonation

• Uses accessToken from /shared_servers

---

Why this change was necessary

1. Plex uses server-scoped access tokens, not global login tokens

Previously, tokens were incorrectly assumed to be interchangeable between:

• admin accounts
• shared users
• server operations

However Plex enforces strict separation:

• Admin token → server discovery + management
• Shared user token (accessToken) → required for user-scoped mutations (playlists, edits, etc.)

Without correct switching, Plex returns:

• 401 Unauthorized on /playlists and similar endpoints

---

2. /shared_servers is the only valid source of per-user server tokens

Provides:

• authoritative user → server token mapping
• per-user library permissions
• required data for impersonation-style access

Other endpoints do not provide usable per-user server tokens.

---

3. Hub search is required for reliable media resolution

Plex search APIs are inconsistent across libraries and media types. Using /hubs/search ensures:

• consistent metadata structure
• better ranking and matching than raw library queries
• access to richer contextual metadata (artist, album, file path, duration)

This is required for reliably mapping:

• track input → Plex ratingKey / key

---

Result

After these changes:

• User switching works via correct Plex per-user tokens
• Playlist creation works under correct user context
• Admin and user auth contexts are cleanly separated

[DannyTheHeretic]

also, if you want to test it, i have a build on my ghcr,
dannytheheretic/explo:latest