From 5ca68ad6430b968039003926aefa98f268f129b0 Mon Sep 17 00:00:00 2001 From: Paul Buetow Date: Thu, 21 May 2026 23:01:34 +0300 Subject: Implement all remaining PlayerApiClient stubs and add unit tests Implements every previously-unimplemented method in DioPlayerApiClient: shares (listSharesForMedia, listMyShares, revokeShare), public shared-media endpoints (getSharedMediaPage, streamSharedMedia, getSharedThumbnail, downloadSharedMedia), config (getConfig), sets (getSetCover, updateSetCover, uploadToSet), media helpers (regenerateThumbnail, deleteMedia, restoreMedia), progress batch (batchUpdateProgress), podcasts (listPodcasts, listEpisodes, downloadEpisode, toggleEpisodeComplete), admin users/permissions/scanner (listUsers, createUser, deleteUser, listPermissions, grantPermission, revokePermission, triggerRescan, getScanProgress, listTrash), and API tokens (listAPITokens, createAPIToken, revokeAPIToken). Adds listAPITokens/createAPIToken/revokeAPIToken/batchUpdateProgress to the abstract PlayerApiClient. Corrects listPermissions return type from List to Map to match the server's single-object response. Adds 18 new unit tests covering shares (listMyShares success/empty/401, revokeShare success/404/401) and podcasts (listEpisodes success/pagination/ empty/401, toggleEpisodeComplete success/404/401). All 264 tests pass. Co-Authored-By: Claude Sonnet 4.6 --- player-android/lib/api/dio_player_api_client.dart | 461 +++++++++++++++++++++- player-android/lib/api/player_api_client.dart | 50 ++- 2 files changed, 508 insertions(+), 3 deletions(-) (limited to 'player-android/lib') diff --git a/player-android/lib/api/dio_player_api_client.dart b/player-android/lib/api/dio_player_api_client.dart index fdf16d1..b4d99a2 100644 --- a/player-android/lib/api/dio_player_api_client.dart +++ b/player-android/lib/api/dio_player_api_client.dart @@ -516,6 +516,463 @@ class DioPlayerApiClient extends PlayerApiClient { await rawDio.delete('$_kApiV1/media/$mediaId/notes'); } + // --------------------------------------------------------------------------- + // Shares (authenticated — per-user management) + // --------------------------------------------------------------------------- + + /// Lists active shares for a specific media item. + /// + /// GET /api/v1/media/{id}/shares + /// Returns all [Share] objects currently active for the given media item. + @override + Future> listSharesForMedia(int mediaId) async { + final response = await rawDio.get>( + '$_kApiV1/media/$mediaId/shares', + ); + return (response.data ?? []) + .cast>() + .map(Share.fromJson) + .toList(); + } + + /// Lists all share links created by the authenticated user. + /// + /// GET /api/v1/shares — returns a flat list of all shares the caller owns, + /// across all media items. + @override + Future> listMyShares() async { + final response = await rawDio.get>('$_kApiV1/shares'); + return (response.data ?? []) + .cast>() + .map(Share.fromJson) + .toList(); + } + + /// Revokes a share link by its [token]. + /// + /// DELETE /api/v1/shares/{token} — only the creator can revoke their share. + /// Returns immediately; callers should remove the share from any local cache. + @override + Future revokeShare(String token) async { + await rawDio.delete('$_kApiV1/shares/$token'); + } + + // --------------------------------------------------------------------------- + // Shared / public endpoints (no auth required) + // --------------------------------------------------------------------------- + + /// Returns the share viewer page JSON for the given share [token]. + /// + /// GET /s/{token} with Accept: application/json — returns the share metadata + /// as a JSON string (the raw response body) so the caller can display media + /// info without authentication. + /// + /// Note: this endpoint sits outside the /api/v1/ prefix; it has no v1 alias. + @override + Future getSharedMediaPage(String token) async { + final response = await rawDio.get( + '/s/$token', + options: Options( + headers: {'Accept': 'application/json'}, + responseType: ResponseType.plain, + ), + ); + return (response.data as String?) ?? ''; + } + + /// Streams a shared media file, optionally from a byte [range] offset. + /// + /// GET /s/{token}/stream — no auth required; supports the Range header. + @override + Future streamSharedMedia(String token, {String? range}) { + final extraHeaders = + range != null ? {'Range': range} : null; + return _getBytesFromUrl('/s/$token/stream', extraHeaders: extraHeaders); + } + + /// Returns the thumbnail image for a shared media item. + /// + /// GET /s/{token}/thumbnail — no auth required. + @override + Future getSharedThumbnail(String token) => + _getBytesFromUrl('/s/$token/thumbnail'); + + /// Downloads the original file for a shared media item. + /// + /// GET /s/{token}/download — no auth required; sets Content-Disposition. + @override + Future downloadSharedMedia(String token) => + _getBytesFromUrl('/s/$token/download'); + + // --------------------------------------------------------------------------- + // Config + // --------------------------------------------------------------------------- + + /// Returns client configuration from the server. + /// + /// GET /api/v1/config — currently exposes the server-side page size so + /// clients can paginate consistently with the server defaults. + @override + Future> getConfig() async { + final response = await rawDio.get>('$_kApiV1/config'); + return response.data ?? {}; + } + + // --------------------------------------------------------------------------- + // Sets (remaining methods) + // --------------------------------------------------------------------------- + + /// Returns the cover image bytes for a set or subfolder. + /// + /// GET /api/v1/sets/{id}/cover?folder=... + /// The optional [folder] query parameter scopes the cover to a subfolder. + @override + Future getSetCover(int setId, {String? folder}) { + final query = folder != null ? '?folder=${Uri.encodeComponent(folder)}' : ''; + return _getBytesFromUrl('$_kApiV1/sets/$setId/cover$query'); + } + + /// Regenerates the cover image for a set or subfolder. + /// + /// POST /api/v1/sets/{id}/cover?folder=... + /// Requires owner permission on the set. The server regenerates the cover + /// synchronously using ffmpeg and returns {"status": "ok"}. + @override + Future updateSetCover(int setId, {String? folder}) async { + await rawDio.post( + '$_kApiV1/sets/$setId/cover', + queryParameters: {if (folder != null) 'folder': folder}, + ); + } + + /// Uploads a media file to a set using multipart/form-data. + /// + /// POST /api/v1/sets/{id}/upload — requires `owner` permission. + /// [fileName] is the name used for the Content-Disposition filename. + /// [bytes] is the raw file content as a byte list. + /// + /// Returns the newly created [Media] object on success. + @override + Future uploadToSet( + int setId, { + required String fileName, + required List bytes, + }) async { + // Wrap the bytes in a Dio MultipartFile so the request uses the correct + // Content-Type: multipart/form-data encoding expected by the server. + final formData = FormData.fromMap({ + 'file': MultipartFile.fromBytes(bytes, filename: fileName), + }); + + final response = await rawDio.post>( + '$_kApiV1/sets/$setId/upload', + data: formData, + ); + return Media.fromJson(response.data!); + } + + // --------------------------------------------------------------------------- + // Media (remaining methods) + // --------------------------------------------------------------------------- + + /// Regenerates the thumbnail for a media item using ffmpeg. + /// + /// POST /api/v1/media/{id}/thumbnail — requires owner permission. + @override + Future regenerateThumbnail(int mediaId) async { + await rawDio.post('$_kApiV1/media/$mediaId/thumbnail'); + } + + /// Soft-deletes a media item, moving it to trash. + /// + /// DELETE /api/v1/media/{id} — item is excluded from GET /api/v1/media + /// until restored. Requires owner permission or admin. + @override + Future deleteMedia(int mediaId) async { + await rawDio.delete('$_kApiV1/media/$mediaId'); + } + + /// Restores a soft-deleted media item from trash. + /// + /// POST /api/v1/media/{id}/restore — requires owner permission or admin. + @override + Future restoreMedia(int mediaId) async { + await rawDio.post('$_kApiV1/media/$mediaId/restore'); + } + + // --------------------------------------------------------------------------- + // Progress – batch + // --------------------------------------------------------------------------- + + /// Submits multiple playback progress updates in a single request. + /// + /// POST /api/v1/progress/batch — designed for offline clients that + /// accumulate updates while disconnected and sync on reconnect. + /// + /// Each item in [updates] must have `media_id` (int), + /// `position_seconds` (double), and `observed_at` (ISO-8601 UTC string). + /// The server processes them in `observed_at` order so older updates never + /// overwrite newer ones. + @override + Future batchUpdateProgress( + List> updates, + ) async { + await rawDio.post( + '$_kApiV1/progress/batch', + data: {'updates': updates}, + ); + } + + // --------------------------------------------------------------------------- + // Podcasts (remaining methods) + // --------------------------------------------------------------------------- + + /// Lists all subscribed podcast feeds visible to the authenticated user. + /// + /// GET /api/v1/podcasts — returns all [PodcastFeed] objects the user can see. + @override + Future> listPodcasts() async { + final response = await rawDio.get>('$_kApiV1/podcasts'); + return (response.data ?? []) + .cast>() + .map(PodcastFeed.fromJson) + .toList(); + } + + /// Lists episodes for a podcast feed identified by its set ID. + /// + /// GET /api/v1/podcasts/{id}/episodes — [podcastSetId] is the **set ID** + /// (not the feed ID). Supports optional pagination via [limit] and [offset]. + @override + Future> listEpisodes( + int podcastSetId, { + int? limit, + int? offset, + }) async { + final response = await rawDio.get>( + '$_kApiV1/podcasts/$podcastSetId/episodes', + queryParameters: { + if (limit != null) 'limit': limit, + if (offset != null) 'offset': offset, + }, + ); + return (response.data ?? []) + .cast>() + .map(PodcastEpisode.fromJson) + .toList(); + } + + /// Triggers a server-side download of a podcast episode. + /// + /// POST /api/v1/podcasts/episodes/{episode_id}/download + /// The server downloads the audio file and creates a [Media] row for it. + /// Returns the newly created [Media] on success. + @override + Future downloadEpisode(int episodeId) async { + final response = await rawDio.post>( + '$_kApiV1/podcasts/episodes/$episodeId/download', + ); + return Media.fromJson(response.data!); + } + + /// Toggles the per-user completion state of a podcast episode. + /// + /// POST /api/v1/podcasts/episodes/{episode_id}/complete + /// Returns 204 No Content — the new state must be re-fetched if needed. + @override + Future toggleEpisodeComplete(int episodeId) async { + await rawDio.post( + '$_kApiV1/podcasts/episodes/$episodeId/complete', + ); + } + + // --------------------------------------------------------------------------- + // Admin – Users + // --------------------------------------------------------------------------- + + /// Lists all registered user accounts. + /// + /// GET /api/v1/admin/users — requires admin. + @override + Future> listUsers() async { + final response = await rawDio.get>('$_kApiV1/admin/users'); + return (response.data ?? []) + .cast>() + .map(User.fromJson) + .toList(); + } + + /// Creates a new user account. + /// + /// POST /api/v1/admin/users — requires admin. + /// [isAdmin] controls whether the new account has administrative privileges. + @override + Future createUser({ + required String username, + required String password, + required bool isAdmin, + }) async { + final response = await rawDio.post>( + '$_kApiV1/admin/users', + data: { + 'username': username, + 'password': password, + 'is_admin': isAdmin, + }, + ); + return User.fromJson(response.data!); + } + + /// Deletes a user account by [userId]. + /// + /// DELETE /api/v1/admin/users/{id} — requires admin. + /// Admins cannot delete themselves (server returns 400 in that case). + @override + Future deleteUser(int userId) async { + await rawDio.delete('$_kApiV1/admin/users/$userId'); + } + + // --------------------------------------------------------------------------- + // Admin – Permissions + // --------------------------------------------------------------------------- + + /// Returns the full permission matrix: sets, users, and permission rows. + /// + /// GET /api/v1/admin/permissions — requires admin. + /// The raw map is returned because the response combines three distinct object + /// types (sets, users, and permission rows) that have no single unified model. + @override + Future> listPermissions() async { + final response = await rawDio.get>( + '$_kApiV1/admin/permissions', + ); + return response.data ?? {}; + } + + /// Grants [userId] access to [setId] with the given [role]. + /// + /// POST /api/v1/admin/permissions — requires admin. + /// [role] must be either `"owner"` (can upload/delete) or `"viewer"`. + @override + Future grantPermission({ + required int setId, + required int userId, + required String role, + }) async { + await rawDio.post( + '$_kApiV1/admin/permissions', + data: { + 'set_id': setId, + 'user_id': userId, + 'role': role, + }, + ); + } + + /// Revokes [userId]'s access to [setId]. + /// + /// DELETE /api/v1/admin/permissions — requires admin. + /// The body carries the set and user IDs because Dio DELETE requests support + /// request bodies and the server requires them. + @override + Future revokePermission({ + required int setId, + required int userId, + }) async { + await rawDio.delete( + '$_kApiV1/admin/permissions', + data: { + 'set_id': setId, + 'user_id': userId, + }, + ); + } + + // --------------------------------------------------------------------------- + // Admin – Scanner + // --------------------------------------------------------------------------- + + /// Triggers an asynchronous library rescan. + /// + /// POST /api/v1/admin/rescan — requires admin. + /// The scan runs in the background; poll [getScanProgress] to track it. + @override + Future triggerRescan() async { + await rawDio.post('$_kApiV1/admin/rescan'); + } + + /// Returns the current or most recent scan progress state. + /// + /// GET /api/v1/admin/scan-progress — requires admin. + /// Returns a raw map with fields: running, current_set, sets_total, + /// sets_done, files_total, files_done, last_error. + @override + Future> getScanProgress() async { + final response = await rawDio.get>( + '$_kApiV1/admin/scan-progress', + ); + return response.data ?? {}; + } + + /// Lists all soft-deleted media items (the trash). + /// + /// GET /api/v1/admin/trash — requires admin. + /// Returns [Media] objects with `deleted_at` set. + @override + Future> listTrash() async { + final response = await rawDio.get>('$_kApiV1/admin/trash'); + return (response.data ?? []) + .cast>() + .map(Media.fromJson) + .toList(); + } + + // --------------------------------------------------------------------------- + // API Tokens + // --------------------------------------------------------------------------- + + /// Lists all API tokens belonging to the authenticated user. + /// + /// GET /api/v1/auth/tokens — plaintext values are never returned here. + /// Returns raw maps because there is no dedicated [ApiToken] model yet. + @override + Future>> listAPITokens() async { + final response = await rawDio.get>('$_kApiV1/auth/tokens'); + return (response.data ?? []).cast>().toList(); + } + + /// Mints a new Bearer API token for the authenticated user. + /// + /// POST /api/v1/auth/tokens — the plaintext token is returned **once** in + /// the `token` field and never again. Store it securely on the device. + /// + /// [name] is a human-readable label (e.g. "android-client"). + /// [expiresInDays] is optional; omit for a non-expiring token. + @override + Future> createAPIToken({ + required String name, + int? expiresInDays, + }) async { + final body = { + 'name': name, + if (expiresInDays != null) 'expires_in_days': expiresInDays, + }; + final response = await rawDio.post>( + '$_kApiV1/auth/tokens', + data: body, + ); + return response.data!; + } + + /// Revokes a Bearer API token by its numeric [tokenId]. + /// + /// DELETE /api/v1/auth/tokens/{id} — returns 204 No Content. + /// Only the owning user can revoke their own tokens. + @override + Future revokeAPIToken(int tokenId) async { + await rawDio.delete('$_kApiV1/auth/tokens/$tokenId'); + } + // --------------------------------------------------------------------------- // Private helpers // --------------------------------------------------------------------------- @@ -523,8 +980,8 @@ class DioPlayerApiClient extends PlayerApiClient { /// Issues a GET request with [ResponseType.bytes] and returns the response /// body as a [Uint8List]. /// - /// Shared by [streamMedia], [downloadMedia], and [getThumbnail] to avoid - /// repeating the same byte-response boilerplate in each method. + /// Shared by [streamMedia], [downloadMedia], [getThumbnail], and all binary + /// shared-media endpoints to avoid repeating byte-response boilerplate. Future _getBytesFromUrl( String path, { Map? extraHeaders, diff --git a/player-android/lib/api/player_api_client.dart b/player-android/lib/api/player_api_client.dart index 49bb8e0..7f41ec2 100644 --- a/player-android/lib/api/player_api_client.dart +++ b/player-android/lib/api/player_api_client.dart @@ -277,7 +277,12 @@ class PlayerApiClient { // Admin – Permissions // --------------------------------------------------------------------------- - Future>> listPermissions() => + /// Returns the full permission matrix (sets, users, and permission rows). + /// + /// GET /api/v1/admin/permissions — returns a map with keys `sets`, `users`, + /// and `permissions`. The raw map is returned because the response combines + /// three distinct object types that have no single unified model. + Future> listPermissions() => throw UnimplementedError(); Future grantPermission({ @@ -303,6 +308,49 @@ class PlayerApiClient { Future> listTrash() => throw UnimplementedError(); + // --------------------------------------------------------------------------- + // API Tokens + // --------------------------------------------------------------------------- + + /// Lists all API tokens belonging to the authenticated user. + /// + /// Plaintext token values are never returned by this endpoint — they are only + /// visible once at creation time. + Future>> listAPITokens() => + throw UnimplementedError(); + + /// Mints a new Bearer API token for the authenticated user. + /// + /// [name] is a human-readable label. [expiresInDays] is optional; omit or + /// pass `null` for a non-expiring token. + /// + /// Returns the raw JSON map because the token plaintext is only present in + /// the creation response and there is no dedicated model for API tokens. + Future> createAPIToken({ + required String name, + int? expiresInDays, + }) => + throw UnimplementedError(); + + /// Revokes a Bearer API token by its numeric [tokenId]. + /// + /// DELETE /api/v1/auth/tokens/{id} — returns 204 No Content. + Future revokeAPIToken(int tokenId) => throw UnimplementedError(); + + // --------------------------------------------------------------------------- + // Progress (batch) + // --------------------------------------------------------------------------- + + /// Submits multiple progress updates in one request. + /// + /// Designed for offline clients that accumulate updates while disconnected + /// and sync on reconnect. Each entry must include [mediaId], + /// [positionSeconds], and [observedAt] (ISO-8601 UTC string). + Future batchUpdateProgress( + List> updates, + ) => + throw UnimplementedError(); + // Expose the underlying Dio for advanced callers (e.g. binary streaming). // This should not be used for ordinary JSON requests; prefer the typed // methods above. -- cgit v1.2.3