@mediaryorg/contracts 1.0.10 → 2.0.1

package/proto/image/v1/image.proto

@@ -0,0 +1,73 @@
+syntax = "proto3";
+
+package image.v1;
+
+service ImageService {
+  // Returns the binary image (proxied + optionally resized).
+  // Useful when the gateway streams it back to the client. Size hints are
+  // advisory; the implementation may ignore them.
+  rpc ProxyImage(ProxyImageRequest) returns (ProxyImageResponse);
+
+  // Resolves a TMDB poster path (e.g. "/abc.jpg") to an absolute URL.
+  rpc GetTmdbPosterUrl(GetTmdbPosterUrlRequest) returns (GetTmdbPosterUrlResponse);
+
+  // Uploads a single image to object storage (R2) and returns its public URL.
+  rpc UploadImage(UploadImageRequest) returns (UploadImageResponse);
+
+  // Removes an image from object storage by its public URL or key.
+  rpc DeleteImage(DeleteImageRequest) returns (DeleteImageResponse);
+}
+
+// TMDB poster size variants accepted by the legacy controller.
+enum TmdbPosterSize {
+  TMDB_POSTER_SIZE_UNSPECIFIED = 0;
+  TMDB_POSTER_SIZE_W92 = 1;
+  TMDB_POSTER_SIZE_W154 = 2;
+  TMDB_POSTER_SIZE_W185 = 3;
+  TMDB_POSTER_SIZE_W342 = 4;
+  TMDB_POSTER_SIZE_W500 = 5;
+  TMDB_POSTER_SIZE_W780 = 6;
+  TMDB_POSTER_SIZE_ORIGINAL = 7;
+}
+
+message ProxyImageRequest {
+  string url = 1;
+  optional int32 width = 2;
+  optional int32 height = 3;
+}
+
+message ProxyImageResponse {
+  bytes data = 1;
+  string content_type = 2;
+  int64 content_length = 3;
+}
+
+message GetTmdbPosterUrlRequest {
+  string poster_path = 1;
+  TmdbPosterSize size = 2;
+}
+
+message GetTmdbPosterUrlResponse {
+  string url = 1;
+}
+
+message UploadImageRequest {
+  // Raw file bytes. Allowed mime types: image/jpeg, image/png, image/webp.
+  // Max size: 4 MiB.
+  bytes data = 1;
+  string original_name = 2;
+  string mime_type = 3;
+}
+
+message UploadImageResponse {
+  string url = 1;
+  string original_name = 2;
+  int64 size = 3;
+}
+
+message DeleteImageRequest {
+  // Either a full URL (with public-host prefix) or just the storage key.
+  string url_or_key = 1;
+}
+
+message DeleteImageResponse {}

package/proto/library/v1/library.proto

@@ -0,0 +1,144 @@
+syntax = "proto3";
+
+package library.v1;
+
+import "media/v1/media.proto";
+
+service LibraryService {
+  rpc AddFromSearch(AddFromSearchRequest) returns (AddFromSearchResponse);
+  rpc GetUserLibrary(GetUserLibraryRequest) returns (GetUserLibraryResponse);
+  rpc GetLibraryItem(GetLibraryItemRequest) returns (GetLibraryItemResponse);
+  rpc UpdateLibraryItem(UpdateLibraryItemRequest) returns (UpdateLibraryItemResponse);
+  rpc RemoveFromLibrary(RemoveFromLibraryRequest) returns (RemoveFromLibraryResponse);
+  rpc IsInLibrary(IsInLibraryRequest) returns (IsInLibraryResponse);
+  rpc GetGenres(GetGenresRequest) returns (GetGenresResponse);
+}
+
+// Mirrors prisma enum Status (PLANNED/IN_PROGRESS/COMPLETED/DROPPED).
+enum LibraryItemStatus {
+  LIBRARY_ITEM_STATUS_UNSPECIFIED = 0;
+  LIBRARY_ITEM_STATUS_PLANNED = 1;
+  LIBRARY_ITEM_STATUS_IN_PROGRESS = 2;
+  LIBRARY_ITEM_STATUS_COMPLETED = 3;
+  LIBRARY_ITEM_STATUS_DROPPED = 4;
+}
+
+message LibraryItem {
+  string id = 1;
+  string user_id = 2;
+  string media_id = 3;
+  LibraryItemStatus status = 4;
+  optional double rating = 5;
+  optional string notes = 6;
+  string added_at = 7;
+  string updated_at = 8;
+  // Embedded media snapshot for the read paths (denormalized view).
+  media.v1.Media media = 9;
+  // Pre-aggregated counts to avoid extra round-trips on the gateway side.
+  int32 library_count = 10;
+  int32 reviews_count = 11;
+  bool is_favorite = 12;
+}
+
+// Compact search hit accepted by AddFromSearch (mirrors AddFromSearchDto.searchResult).
+message LibrarySearchHit {
+  string id = 1;
+  string title = 2;
+  optional string subtitle = 3;
+  optional string image_url = 4;
+  optional string year = 5;
+  string type = 6;
+  string source = 7;
+  optional string external_id = 8;
+  optional double rating = 9;
+  repeated string genres = 10;
+}
+
+message AddFromSearchRequest {
+  string user_id = 1;
+  LibrarySearchHit search_result = 2;
+  optional LibraryItemStatus status = 3;
+  optional double rating = 4;
+  optional string notes = 5;
+}
+
+message AddFromSearchResponse {
+  LibraryItem item = 1;
+}
+
+message GetUserLibraryRequest {
+  string user_id = 1;
+  repeated LibraryItemStatus statuses = 2;
+  optional string collection_name = 3;
+  optional media.v1.MediaSource source = 4;
+  optional string search = 5;
+  repeated string genres = 6;
+  optional double min_rating = 7;
+  optional double max_rating = 8;
+  optional int32 min_year = 9;
+  optional int32 max_year = 10;
+  int32 page = 11;
+  int32 limit = 12;
+  // addedAt | rating | title | releaseYear | favorites
+  string sort_by = 13;
+  string sort_order = 14;
+}
+
+message LibraryPaginationMeta {
+  int32 page = 1;
+  int32 limit = 2;
+  int32 total = 3;
+  int32 total_pages = 4;
+  bool has_next_page = 5;
+  bool has_prev_page = 6;
+}
+
+message GetUserLibraryResponse {
+  repeated LibraryItem data = 1;
+  LibraryPaginationMeta meta = 2;
+}
+
+message GetLibraryItemRequest {
+  string user_id = 1;
+  string media_id = 2;
+}
+
+message GetLibraryItemResponse {
+  LibraryItem item = 1;
+}
+
+message UpdateLibraryItemRequest {
+  string user_id = 1;
+  string media_id = 2;
+  optional LibraryItemStatus status = 3;
+  optional double rating = 4;
+  optional string notes = 5;
+}
+
+message UpdateLibraryItemResponse {
+  LibraryItem item = 1;
+}
+
+message RemoveFromLibraryRequest {
+  string user_id = 1;
+  string media_id = 2;
+}
+
+message RemoveFromLibraryResponse {}
+
+message IsInLibraryRequest {
+  string user_id = 1;
+  string media_id = 2;
+}
+
+message IsInLibraryResponse {
+  bool is_in_library = 1;
+}
+
+message GetGenresRequest {
+  string user_id = 1;
+}
+
+message GetGenresResponse {
+  repeated string genres = 1;
+}

package/proto/media/v1/media.proto

@@ -0,0 +1,197 @@
+syntax = "proto3";
+
+package media.v1;
+
+service MediaService {
+  rpc CreateMedia(CreateMediaRequest) returns (CreateMediaResponse);
+  rpc GetMediaById(GetMediaByIdRequest) returns (GetMediaByIdResponse);
+  rpc GetMediaByExternalId(GetMediaByExternalIdRequest) returns (GetMediaByExternalIdResponse);
+  rpc FindDuplicates(FindDuplicatesRequest) returns (FindDuplicatesResponse);
+  rpc GetMediaStats(GetMediaStatsRequest) returns (GetMediaStatsResponse);
+  rpc UpdateMedia(UpdateMediaRequest) returns (UpdateMediaResponse);
+  rpc DeleteMedia(DeleteMediaRequest) returns (DeleteMediaResponse);
+  rpc ListMedia(ListMediaRequest) returns (ListMediaResponse);
+
+  // Cross-service: ensure media exists for a search hit.
+  // Used by library/favorites/recommendation flows so they don't need to write
+  // into the media database directly.
+  rpc EnsureMediaFromSearch(EnsureMediaFromSearchRequest) returns (EnsureMediaFromSearchResponse);
+}
+
+// MediaSource mirrors prisma enum MediaSource.
+enum MediaSource {
+  MEDIA_SOURCE_UNSPECIFIED = 0;
+  MEDIA_SOURCE_TMDB = 1;
+  MEDIA_SOURCE_GOOGLE_BOOKS = 2;
+  MEDIA_SOURCE_MAL = 3;
+  MEDIA_SOURCE_CUSTOM = 4;
+}
+
+// MediaData is the structured payload kept as JSON in the legacy database.
+// `custom_fields_json` contains the type-specific customFields object as a
+// JSON-encoded string so callers can extend without breaking the schema.
+message MediaData {
+  string title = 1;
+  string original_title = 2;
+  string description = 3;
+  int32 year = 4;
+  string poster_url = 5;
+  repeated string genres = 6;
+  double rating = 7;
+  string release_date = 8;
+  string country = 9;
+  string original_language = 10;
+  string custom_fields_json = 11;
+}
+
+message Media {
+  string id = 1;
+  MediaSource source = 2;
+  string external_id = 3;
+  MediaData media_data = 4;
+  string searchable_title = 5;
+  string external_ids_json = 6;
+  string collection_id = 7;
+  string added_by_id = 8;
+  string created_at = 9;
+  string updated_at = 10;
+}
+
+message MediaCounts {
+  int32 library = 1;
+  int32 reviews = 2;
+  int32 favorites = 3;
+}
+
+message MediaWithCounts {
+  Media media = 1;
+  MediaCounts counts = 2;
+}
+
+message CreateMediaRequest {
+  MediaSource source = 1;
+  string external_id = 2;
+  MediaData media_data = 3;
+  string collection_id = 4;
+  string added_by_id = 5;
+}
+
+message CreateMediaResponse {
+  Media media = 1;
+}
+
+message GetMediaByIdRequest {
+  string media_id = 1;
+}
+
+message RatingDistributionEntry {
+  double rating = 1;
+  int32 count = 2;
+}
+
+message GetMediaByIdResponse {
+  Media media = 1;
+  MediaCounts counts = 2;
+  double average_rating = 3;
+  int32 total_reviews = 4;
+}
+
+message GetMediaByExternalIdRequest {
+  MediaSource source = 1;
+  string external_id = 2;
+}
+
+message GetMediaByExternalIdResponse {
+  Media media = 1;
+}
+
+message FindDuplicatesRequest {
+  string title = 1;
+  string external_id = 2;
+}
+
+message FindDuplicatesResponse {
+  repeated Media items = 1;
+}
+
+message GetMediaStatsRequest {
+  string media_id = 1;
+}
+
+message MediaStats {
+  double average_rating = 1;
+  int32 total_reviews = 2;
+  repeated RatingDistributionEntry rating_distribution = 3;
+}
+
+message GetMediaStatsResponse {
+  Media media = 1;
+  MediaStats stats = 2;
+}
+
+message UpdateMediaRequest {
+  string media_id = 1;
+  optional MediaSource source = 2;
+  optional string external_id = 3;
+  optional MediaData media_data = 4;
+  optional string collection_id = 5;
+}
+
+message UpdateMediaResponse {
+  Media media = 1;
+}
+
+message DeleteMediaRequest {
+  string media_id = 1;
+}
+
+message DeleteMediaResponse {}
+
+message ListMediaRequest {
+  optional string search = 1;
+  optional string collection_id = 2;
+  optional MediaSource source = 3;
+  optional int32 year = 4;
+  int32 page = 5;
+  int32 limit = 6;
+  string sort_by = 7;
+  string sort_order = 8;
+}
+
+message PaginationMeta {
+  int32 page = 1;
+  int32 limit = 2;
+  int32 total = 3;
+  int32 total_pages = 4;
+  bool has_next_page = 5;
+  bool has_prev_page = 6;
+}
+
+message ListMediaResponse {
+  repeated MediaWithCounts data = 1;
+  PaginationMeta meta = 2;
+}
+
+message EnsureMediaFromSearchRequest {
+  // Source identifier coming from search-service results
+  // ("tmdb", "google_books", "mangadex", ..., or "local" for already-existing)
+  string source = 1;
+  // External id within that source (or media id when source == "local")
+  string external_id = 2;
+  // Search media type label ("movie"|"series"|"book"|"anime"|"manga"|"manhwa"|"game"|"kdrama")
+  string media_type = 3;
+  string title = 4;
+  string subtitle = 5;
+  string image_url = 6;
+  string year = 7;
+  optional double rating = 8;
+  repeated string genres = 9;
+  // User who initiated the action (becomes addedBy on creation).
+  string requested_by_user_id = 10;
+}
+
+message EnsureMediaFromSearchResponse {
+  Media media = 1;
+  // True when the media row was just created, false when reused.
+  bool created = 2;
+}

package/proto/media_request/v1/media_request.proto

@@ -0,0 +1,142 @@
+syntax = "proto3";
+
+package media_request.v1;
+
+import "media/v1/media.proto";
+
+service MediaRequestService {
+  // User-facing endpoints.
+  rpc CreateMediaRequest(CreateMediaRequestRequest) returns (CreateMediaRequestResponse);
+  rpc GetUserRequests(GetUserRequestsRequest) returns (GetUserRequestsResponse);
+  rpc GetMediaRequestById(GetMediaRequestByIdRequest) returns (GetMediaRequestByIdResponse);
+
+  // Admin / moderator endpoints.
+  rpc ListMediaRequests(ListMediaRequestsRequest) returns (ListMediaRequestsResponse);
+  rpc UpdateMediaRequest(UpdateMediaRequestRequest) returns (UpdateMediaRequestResponse);
+  rpc ModerateMediaRequest(ModerateMediaRequestRequest) returns (ModerateMediaRequestResponse);
+  rpc DeleteMediaRequest(DeleteMediaRequestRequest) returns (DeleteMediaRequestResponse);
+}
+
+// Mirrors prisma enum ModerationType.
+enum ModerationStatus {
+  MODERATION_STATUS_UNSPECIFIED = 0;
+  MODERATION_STATUS_PENDING = 1;
+  MODERATION_STATUS_APPROVED = 2;
+  MODERATION_STATUS_REJECTED = 3;
+}
+
+// Lightweight reference to the user who acted on the request.
+// Populated by the gateway / user-service when needed; kept self-contained.
+message MediaRequestUserRef {
+  string id = 1;
+  string display_name = 2;
+  string picture = 3;
+}
+
+message MediaRequest {
+  string id = 1;
+  ModerationStatus status = 2;
+  media.v1.MediaData media_data = 3;
+  string searchable_title = 4;
+  string external_ids_json = 5;
+  string comment = 6;
+  string moderator_note = 7;
+  string duplicate_check_status = 8;
+  string possible_duplicates_json = 9;
+  string requested_by_id = 10;
+  MediaRequestUserRef requested_by = 11;
+  string moderated_by_id = 12;
+  MediaRequestUserRef moderated_by = 13;
+  string approved_media_id = 14;
+  string collection_id = 15;
+  string created_at = 16;
+  string updated_at = 17;
+}
+
+message CreateMediaRequestRequest {
+  string user_id = 1;
+  // Currently only CUSTOM is accepted (TMDB content goes through search flow).
+  optional media.v1.MediaSource source = 2;
+  media.v1.MediaData media_data = 3;
+  string collection_id = 4;
+  optional string comment = 5;
+}
+
+message CreateMediaRequestResponse {
+  MediaRequest request = 1;
+}
+
+message GetUserRequestsRequest {
+  string user_id = 1;
+  optional ModerationStatus status = 2;
+}
+
+message GetUserRequestsResponse {
+  repeated MediaRequest items = 1;
+}
+
+message GetMediaRequestByIdRequest {
+  string request_id = 1;
+}
+
+message GetMediaRequestByIdResponse {
+  MediaRequest request = 1;
+}
+
+message ListMediaRequestsRequest {
+  optional ModerationStatus status = 1;
+  optional media.v1.MediaSource source = 2;
+  optional string collection_id = 3;
+  optional string search = 4;
+  optional string requested_by_id = 5;
+  optional string moderated_by_id = 6;
+  optional int32 year = 7;
+  int32 page = 8;
+  int32 limit = 9;
+  string sort_by = 10;
+  string sort_order = 11;
+}
+
+message MediaRequestPaginationMeta {
+  int32 page = 1;
+  int32 limit = 2;
+  int32 total = 3;
+  int32 total_pages = 4;
+  bool has_next_page = 5;
+  bool has_prev_page = 6;
+}
+
+message ListMediaRequestsResponse {
+  repeated MediaRequest data = 1;
+  MediaRequestPaginationMeta meta = 2;
+}
+
+message UpdateMediaRequestRequest {
+  string request_id = 1;
+  // Only PENDING requests can be updated.
+  optional media.v1.MediaData media_data = 2;
+}
+
+message UpdateMediaRequestResponse {
+  MediaRequest request = 1;
+}
+
+message ModerateMediaRequestRequest {
+  string request_id = 1;
+  string moderator_id = 2;
+  // APPROVED or REJECTED.
+  ModerationStatus status = 3;
+  optional string moderator_note = 4;
+}
+
+message ModerateMediaRequestResponse {
+  MediaRequest request = 1;
+  // Populated when status == APPROVED. References media in media-service.
+  string approved_media_id = 2;
+}
+
+message DeleteMediaRequestRequest {
+  string request_id = 1;
+}
+
+message DeleteMediaRequestResponse {}

package/proto/recommendation/v1/recommendation.proto

@@ -0,0 +1,60 @@
+syntax = "proto3";
+
+package recommendation.v1;
+
+import "search/v1/search.proto";
+
+service RecommendationService {
+  // Bundles all four blocks shown on the home screen (trending / topRated /
+  // recommendedForYou / fromYourLibrary). When `user_id` is empty only the
+  // global blocks are populated.
+  rpc GetHomeRecommendations(GetHomeRecommendationsRequest) returns (GetHomeRecommendationsResponse);
+
+  // Force-refresh the global cached blocks (used by the cron job).
+  rpc RefreshGlobalBlocks(RefreshGlobalBlocksRequest) returns (RefreshGlobalBlocksResponse);
+
+  // Force-refresh a personal block for a given user.
+  rpc RefreshUserRecommendations(RefreshUserRecommendationsRequest) returns (RefreshUserRecommendationsResponse);
+}
+
+message MediaRecommendationItem {
+  search.v1.SearchMediaType media_type = 1;
+  string title = 2;
+  optional int32 year = 3;
+  repeated string genres = 4;
+  optional double rating = 5;
+  // Absolute HTTPS poster URL (already passed through ImageService).
+  string poster_url = 6;
+}
+
+message RecommendationBlock {
+  bool visible = 1;
+  repeated MediaRecommendationItem items = 2;
+}
+
+message GetHomeRecommendationsRequest {
+  // Empty string => anonymous request (only trending + topRated are filled).
+  string user_id = 1;
+}
+
+message GetHomeRecommendationsResponse {
+  RecommendationBlock trending = 1;
+  RecommendationBlock top_rated = 2;
+  RecommendationBlock recommended_for_you = 3;
+  RecommendationBlock from_your_library = 4;
+}
+
+message RefreshGlobalBlocksRequest {}
+
+message RefreshGlobalBlocksResponse {
+  int32 trending_count = 1;
+  int32 top_rated_count = 2;
+}
+
+message RefreshUserRecommendationsRequest {
+  string user_id = 1;
+}
+
+message RefreshUserRecommendationsResponse {
+  int32 items_count = 1;
+}

package/proto/search/v1/search.proto

@@ -0,0 +1,62 @@
+syntax = "proto3";
+
+package search.v1;
+
+service SearchService {
+  // Cross-source search aggregator (TMDB, Google Books, AniList, MangaDex, IGDB,
+  // RAWG, Open Library + local db). Mirrors GET /search?query=&mediaType=.
+  rpc Search(SearchRequest) returns (SearchResponse);
+}
+
+// Logical media types accepted by `mediaType` filter and returned in `type`.
+enum SearchMediaType {
+  SEARCH_MEDIA_TYPE_UNSPECIFIED = 0;
+  SEARCH_MEDIA_TYPE_MOVIE = 1;
+  SEARCH_MEDIA_TYPE_SERIES = 2;
+  SEARCH_MEDIA_TYPE_BOOK = 3;
+  SEARCH_MEDIA_TYPE_ANIME = 4;
+  SEARCH_MEDIA_TYPE_MANGA = 5;
+  SEARCH_MEDIA_TYPE_MANHWA = 6;
+  SEARCH_MEDIA_TYPE_GAME = 7;
+  SEARCH_MEDIA_TYPE_KDRAMA = 8;
+}
+
+// Origin of the result. "local" means the row already lives in our database.
+enum SearchSource {
+  SEARCH_SOURCE_UNSPECIFIED = 0;
+  SEARCH_SOURCE_TMDB = 1;
+  SEARCH_SOURCE_GOOGLE_BOOKS = 2;
+  SEARCH_SOURCE_OPEN_LIBRARY = 3;
+  SEARCH_SOURCE_ANILIST = 4;
+  SEARCH_SOURCE_MANGADEX = 5;
+  SEARCH_SOURCE_IGDB = 6;
+  SEARCH_SOURCE_RAWG = 7;
+  SEARCH_SOURCE_LOCAL = 8;
+}
+
+message SearchResult {
+  // External id (or local Media.id when source == LOCAL).
+  string id = 1;
+  string title = 2;
+  string subtitle = 3;
+  string description = 4;
+  string image_url = 5;
+  // Year as string because some sources return imprecise dates ("2020-..").
+  string year = 6;
+  optional double rating = 7;
+  repeated string genres = 8;
+  SearchMediaType type = 9;
+  SearchSource source = 10;
+  string external_id = 11;
+}
+
+message SearchRequest {
+  string query = 1;
+  optional SearchMediaType media_type = 2;
+}
+
+message SearchResponse {
+  repeated SearchResult results = 1;
+  int32 total_results = 2;
+  bool has_more = 3;
+}