hottub/docs/uploaders-endpoint-plan.md

Uploaders Endpoint Plan

Summary

Implement POST /api/uploaders using the Hot Tub uploader profile contract and ship it framework-first. The server will expose shared uploader request/response types, a provider hook for uploader lookup, endpoint routing in src/api.rs, and a first real provider implementation in hsex.

Implementation

• Add dedicated uploader API types in src/uploaders.rs:
  • UploadersRequest
  • UploaderProfile
  • UploaderChannelStat
  • UploaderVideoRef
  • UploaderLayoutRow
• Keep camelCase as the canonical serialized shape.
• Accept documented decode aliases:
  • uploader_id
  • uploader_name
  • profile_content
  • profile_picture_url
  • video_ids
  • horizontal_videos
• Add POST /api/uploaders in src/api.rs.
• Validate that at least one of uploaderId or uploaderName is present.
• Return:
  • 400 for invalid request
  • 404 for no match
  • 500 for provider execution failure
• Add Provider::get_uploader(...) with a default Ok(None) implementation.
• Add a guarded uploader execution helper in src/providers/mod.rs.
• Use canonical uploader IDs in the format <channel>:<provider-local-id>.
• Implement the first provider-backed uploader profile in src/providers/hsex.rs.

Hsex Strategy

• Resolve uploader lookup by canonical uploader ID or exact uploader name.
• Reuse existing uploader archive discovery and archive page fetching.
• Build uploader profile metadata from uploader archive pages.
• Populate videos with UploaderVideoRef values derived from existing VideoItems.
• Always return layout.
• When profileContent == true, return:
  • videos
  • tapes: []
  • playlists: []
  • a "For You" horizontal row plus the default videos row
• When profileContent == false, return metadata and layout only.

Tests

• Request alias decoding for uploader request fields.
• Response alias decoding for avatar and layout row compatibility fields.
• Endpoint helper tests for request validation and provider routing.
• Hsex uploader ID generation and uploader page parsing coverage.

Assumptions

• The first ship focuses on the endpoint framework and one real provider implementation.
• Providers without explicit uploader support remain unsupported by /api/uploaders.
• Name-based resolution uses exact display-name matching.
• videoCount and totalViews are best-effort when the upstream site does not expose authoritative profile totals.