uploaders

docs/uploaders-endpoint-plan.md

@@ -0,0 +1,60 @@
+# 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 `VideoItem`s.
+- 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.