@mediaryorg/contracts 1.0.10 → 2.0.1

package/generated/media_request/v1/media_request.ts

@@ -0,0 +1,223 @@
+// Code generated by protoc-gen-ts_proto. DO NOT EDIT.
+// versions:
+//   protoc-gen-ts_proto  v2.11.6
+//   protoc               v3.21.12
+// source: media_request/v1/media_request.proto
+
+/* eslint-disable */
+import { GrpcMethod, GrpcStreamMethod } from "@nestjs/microservices";
+import { Observable } from "rxjs";
+import { MediaData, MediaSource } from "../../media/v1/media";
+
+export const protobufPackage = "media_request.v1";
+
+/** Mirrors prisma enum ModerationType. */
+export enum ModerationStatus {
+  MODERATION_STATUS_UNSPECIFIED = 0,
+  MODERATION_STATUS_PENDING = 1,
+  MODERATION_STATUS_APPROVED = 2,
+  MODERATION_STATUS_REJECTED = 3,
+  UNRECOGNIZED = -1,
+}
+
+/**
+ * Lightweight reference to the user who acted on the request.
+ * Populated by the gateway / user-service when needed; kept self-contained.
+ */
+export interface MediaRequestUserRef {
+  id: string;
+  displayName: string;
+  picture: string;
+}
+
+export interface MediaRequest {
+  id: string;
+  status: ModerationStatus;
+  mediaData: MediaData | undefined;
+  searchableTitle: string;
+  externalIdsJson: string;
+  comment: string;
+  moderatorNote: string;
+  duplicateCheckStatus: string;
+  possibleDuplicatesJson: string;
+  requestedById: string;
+  requestedBy: MediaRequestUserRef | undefined;
+  moderatedById: string;
+  moderatedBy: MediaRequestUserRef | undefined;
+  approvedMediaId: string;
+  collectionId: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateMediaRequestRequest {
+  userId: string;
+  /** Currently only CUSTOM is accepted (TMDB content goes through search flow). */
+  source?: MediaSource | undefined;
+  mediaData: MediaData | undefined;
+  collectionId: string;
+  comment?: string | undefined;
+}
+
+export interface CreateMediaRequestResponse {
+  request: MediaRequest | undefined;
+}
+
+export interface GetUserRequestsRequest {
+  userId: string;
+  status?: ModerationStatus | undefined;
+}
+
+export interface GetUserRequestsResponse {
+  items: MediaRequest[];
+}
+
+export interface GetMediaRequestByIdRequest {
+  requestId: string;
+}
+
+export interface GetMediaRequestByIdResponse {
+  request: MediaRequest | undefined;
+}
+
+export interface ListMediaRequestsRequest {
+  status?: ModerationStatus | undefined;
+  source?: MediaSource | undefined;
+  collectionId?: string | undefined;
+  search?: string | undefined;
+  requestedById?: string | undefined;
+  moderatedById?: string | undefined;
+  year?: number | undefined;
+  page: number;
+  limit: number;
+  sortBy: string;
+  sortOrder: string;
+}
+
+export interface MediaRequestPaginationMeta {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+  hasNextPage: boolean;
+  hasPrevPage: boolean;
+}
+
+export interface ListMediaRequestsResponse {
+  data: MediaRequest[];
+  meta: MediaRequestPaginationMeta | undefined;
+}
+
+export interface UpdateMediaRequestRequest {
+  requestId: string;
+  /** Only PENDING requests can be updated. */
+  mediaData?: MediaData | undefined;
+}
+
+export interface UpdateMediaRequestResponse {
+  request: MediaRequest | undefined;
+}
+
+export interface ModerateMediaRequestRequest {
+  requestId: string;
+  moderatorId: string;
+  /** APPROVED or REJECTED. */
+  status: ModerationStatus;
+  moderatorNote?: string | undefined;
+}
+
+export interface ModerateMediaRequestResponse {
+  request:
+    | MediaRequest
+    | undefined;
+  /** Populated when status == APPROVED. References media in media-service. */
+  approvedMediaId: string;
+}
+
+export interface DeleteMediaRequestRequest {
+  requestId: string;
+}
+
+export interface DeleteMediaRequestResponse {
+}
+
+export const MEDIA_REQUEST_V1_PACKAGE_NAME = "media_request.v1";
+
+export interface MediaRequestServiceClient {
+  /** User-facing endpoints. */
+
+  createMediaRequest(request: CreateMediaRequestRequest): Observable<CreateMediaRequestResponse>;
+
+  getUserRequests(request: GetUserRequestsRequest): Observable<GetUserRequestsResponse>;
+
+  getMediaRequestById(request: GetMediaRequestByIdRequest): Observable<GetMediaRequestByIdResponse>;
+
+  /** Admin / moderator endpoints. */
+
+  listMediaRequests(request: ListMediaRequestsRequest): Observable<ListMediaRequestsResponse>;
+
+  updateMediaRequest(request: UpdateMediaRequestRequest): Observable<UpdateMediaRequestResponse>;
+
+  moderateMediaRequest(request: ModerateMediaRequestRequest): Observable<ModerateMediaRequestResponse>;
+
+  deleteMediaRequest(request: DeleteMediaRequestRequest): Observable<DeleteMediaRequestResponse>;
+}
+
+export interface MediaRequestServiceController {
+  /** User-facing endpoints. */
+
+  createMediaRequest(
+    request: CreateMediaRequestRequest,
+  ): Promise<CreateMediaRequestResponse> | Observable<CreateMediaRequestResponse> | CreateMediaRequestResponse;
+
+  getUserRequests(
+    request: GetUserRequestsRequest,
+  ): Promise<GetUserRequestsResponse> | Observable<GetUserRequestsResponse> | GetUserRequestsResponse;
+
+  getMediaRequestById(
+    request: GetMediaRequestByIdRequest,
+  ): Promise<GetMediaRequestByIdResponse> | Observable<GetMediaRequestByIdResponse> | GetMediaRequestByIdResponse;
+
+  /** Admin / moderator endpoints. */
+
+  listMediaRequests(
+    request: ListMediaRequestsRequest,
+  ): Promise<ListMediaRequestsResponse> | Observable<ListMediaRequestsResponse> | ListMediaRequestsResponse;
+
+  updateMediaRequest(
+    request: UpdateMediaRequestRequest,
+  ): Promise<UpdateMediaRequestResponse> | Observable<UpdateMediaRequestResponse> | UpdateMediaRequestResponse;
+
+  moderateMediaRequest(
+    request: ModerateMediaRequestRequest,
+  ): Promise<ModerateMediaRequestResponse> | Observable<ModerateMediaRequestResponse> | ModerateMediaRequestResponse;
+
+  deleteMediaRequest(
+    request: DeleteMediaRequestRequest,
+  ): Promise<DeleteMediaRequestResponse> | Observable<DeleteMediaRequestResponse> | DeleteMediaRequestResponse;
+}
+
+export function MediaRequestServiceControllerMethods() {
+  return function (constructor: Function) {
+    const grpcMethods: string[] = [
+      "createMediaRequest",
+      "getUserRequests",
+      "getMediaRequestById",
+      "listMediaRequests",
+      "updateMediaRequest",
+      "moderateMediaRequest",
+      "deleteMediaRequest",
+    ];
+    for (const method of grpcMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcMethod("MediaRequestService", method)(constructor.prototype[method], method, descriptor);
+    }
+    const grpcStreamMethods: string[] = [];
+    for (const method of grpcStreamMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcStreamMethod("MediaRequestService", method)(constructor.prototype[method], method, descriptor);
+    }
+  };
+}
+
+export const MEDIA_REQUEST_SERVICE_NAME = "MediaRequestService";

package/generated/recommendation/v1/recommendation.ts

@@ -0,0 +1,126 @@
+// Code generated by protoc-gen-ts_proto. DO NOT EDIT.
+// versions:
+//   protoc-gen-ts_proto  v2.11.6
+//   protoc               v3.21.12
+// source: recommendation/v1/recommendation.proto
+
+/* eslint-disable */
+import { GrpcMethod, GrpcStreamMethod } from "@nestjs/microservices";
+import { Observable } from "rxjs";
+import { SearchMediaType } from "../../search/v1/search";
+
+export const protobufPackage = "recommendation.v1";
+
+export interface MediaRecommendationItem {
+  mediaType: SearchMediaType;
+  title: string;
+  year?: number | undefined;
+  genres: string[];
+  rating?:
+    | number
+    | undefined;
+  /** Absolute HTTPS poster URL (already passed through ImageService). */
+  posterUrl: string;
+}
+
+export interface RecommendationBlock {
+  visible: boolean;
+  items: MediaRecommendationItem[];
+}
+
+export interface GetHomeRecommendationsRequest {
+  /** Empty string => anonymous request (only trending + topRated are filled). */
+  userId: string;
+}
+
+export interface GetHomeRecommendationsResponse {
+  trending: RecommendationBlock | undefined;
+  topRated: RecommendationBlock | undefined;
+  recommendedForYou: RecommendationBlock | undefined;
+  fromYourLibrary: RecommendationBlock | undefined;
+}
+
+export interface RefreshGlobalBlocksRequest {
+}
+
+export interface RefreshGlobalBlocksResponse {
+  trendingCount: number;
+  topRatedCount: number;
+}
+
+export interface RefreshUserRecommendationsRequest {
+  userId: string;
+}
+
+export interface RefreshUserRecommendationsResponse {
+  itemsCount: number;
+}
+
+export const RECOMMENDATION_V1_PACKAGE_NAME = "recommendation.v1";
+
+export interface RecommendationServiceClient {
+  /**
+   * Bundles all four blocks shown on the home screen (trending / topRated /
+   * recommendedForYou / fromYourLibrary). When `user_id` is empty only the
+   * global blocks are populated.
+   */
+
+  getHomeRecommendations(request: GetHomeRecommendationsRequest): Observable<GetHomeRecommendationsResponse>;
+
+  /** Force-refresh the global cached blocks (used by the cron job). */
+
+  refreshGlobalBlocks(request: RefreshGlobalBlocksRequest): Observable<RefreshGlobalBlocksResponse>;
+
+  /** Force-refresh a personal block for a given user. */
+
+  refreshUserRecommendations(
+    request: RefreshUserRecommendationsRequest,
+  ): Observable<RefreshUserRecommendationsResponse>;
+}
+
+export interface RecommendationServiceController {
+  /**
+   * Bundles all four blocks shown on the home screen (trending / topRated /
+   * recommendedForYou / fromYourLibrary). When `user_id` is empty only the
+   * global blocks are populated.
+   */
+
+  getHomeRecommendations(
+    request: GetHomeRecommendationsRequest,
+  ):
+    | Promise<GetHomeRecommendationsResponse>
+    | Observable<GetHomeRecommendationsResponse>
+    | GetHomeRecommendationsResponse;
+
+  /** Force-refresh the global cached blocks (used by the cron job). */
+
+  refreshGlobalBlocks(
+    request: RefreshGlobalBlocksRequest,
+  ): Promise<RefreshGlobalBlocksResponse> | Observable<RefreshGlobalBlocksResponse> | RefreshGlobalBlocksResponse;
+
+  /** Force-refresh a personal block for a given user. */
+
+  refreshUserRecommendations(
+    request: RefreshUserRecommendationsRequest,
+  ):
+    | Promise<RefreshUserRecommendationsResponse>
+    | Observable<RefreshUserRecommendationsResponse>
+    | RefreshUserRecommendationsResponse;
+}
+
+export function RecommendationServiceControllerMethods() {
+  return function (constructor: Function) {
+    const grpcMethods: string[] = ["getHomeRecommendations", "refreshGlobalBlocks", "refreshUserRecommendations"];
+    for (const method of grpcMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcMethod("RecommendationService", method)(constructor.prototype[method], method, descriptor);
+    }
+    const grpcStreamMethods: string[] = [];
+    for (const method of grpcStreamMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcStreamMethod("RecommendationService", method)(constructor.prototype[method], method, descriptor);
+    }
+  };
+}
+
+export const RECOMMENDATION_SERVICE_NAME = "RecommendationService";

package/generated/search/v1/search.ts

@@ -0,0 +1,103 @@
+// Code generated by protoc-gen-ts_proto. DO NOT EDIT.
+// versions:
+//   protoc-gen-ts_proto  v2.11.6
+//   protoc               v3.21.12
+// source: search/v1/search.proto
+
+/* eslint-disable */
+import { GrpcMethod, GrpcStreamMethod } from "@nestjs/microservices";
+import { Observable } from "rxjs";
+
+export const protobufPackage = "search.v1";
+
+/** Logical media types accepted by `mediaType` filter and returned in `type`. */
+export 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,
+  UNRECOGNIZED = -1,
+}
+
+/** Origin of the result. "local" means the row already lives in our database. */
+export 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,
+  UNRECOGNIZED = -1,
+}
+
+export interface SearchResult {
+  /** External id (or local Media.id when source == LOCAL). */
+  id: string;
+  title: string;
+  subtitle: string;
+  description: string;
+  imageUrl: string;
+  /** Year as string because some sources return imprecise dates ("2020-.."). */
+  year: string;
+  rating?: number | undefined;
+  genres: string[];
+  type: SearchMediaType;
+  source: SearchSource;
+  externalId: string;
+}
+
+export interface SearchRequest {
+  query: string;
+  mediaType?: SearchMediaType | undefined;
+}
+
+export interface SearchResponse {
+  results: SearchResult[];
+  totalResults: number;
+  hasMore: boolean;
+}
+
+export const SEARCH_V1_PACKAGE_NAME = "search.v1";
+
+export interface SearchServiceClient {
+  /**
+   * Cross-source search aggregator (TMDB, Google Books, AniList, MangaDex, IGDB,
+   * RAWG, Open Library + local db). Mirrors GET /search?query=&mediaType=.
+   */
+
+  search(request: SearchRequest): Observable<SearchResponse>;
+}
+
+export interface SearchServiceController {
+  /**
+   * Cross-source search aggregator (TMDB, Google Books, AniList, MangaDex, IGDB,
+   * RAWG, Open Library + local db). Mirrors GET /search?query=&mediaType=.
+   */
+
+  search(request: SearchRequest): Promise<SearchResponse> | Observable<SearchResponse> | SearchResponse;
+}
+
+export function SearchServiceControllerMethods() {
+  return function (constructor: Function) {
+    const grpcMethods: string[] = ["search"];
+    for (const method of grpcMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcMethod("SearchService", method)(constructor.prototype[method], method, descriptor);
+    }
+    const grpcStreamMethods: string[] = [];
+    for (const method of grpcStreamMethods) {
+      const descriptor: any = Reflect.getOwnPropertyDescriptor(constructor.prototype, method);
+      GrpcStreamMethod("SearchService", method)(constructor.prototype[method], method, descriptor);
+    }
+  };
+}
+
+export const SEARCH_SERVICE_NAME = "SearchService";

package/package.json

@@ -1,13 +1,13 @@
 {
     "name": "@mediaryorg/contracts",
-    "version": "1.0.10",
+    "version": "2.0.1",
     "description": "Protobuf definitions and generated TypeScript types",
     "main": "./dist/index.js",
     "types": "./dist/index.d.ts",
     "scripts": {
         "generate": "npm run generate:win",
-        "generate:win": "protoc -I .\\proto .\\proto\\auth\\v1\\auth.proto .\\proto\\user\\v1\\user.proto .\\proto\\profile\\v1\\profile.proto --plugin=protoc-gen-ts_proto=.\\node_modules\\.bin\\protoc-gen-ts_proto.cmd --ts_proto_out=.\\generated --ts_proto_opt=nestJs=true,package=omit",
-        "generate:ci": "protoc -I ./proto ./proto/auth/v1/auth.proto ./proto/user/v1/user.proto ./proto/profile/v1/profile.proto --plugin=protoc-gen-ts_proto=./node_modules/.bin/protoc-gen-ts_proto --ts_proto_out=./generated --ts_proto_opt=nestJs=true,package=omit",
+        "generate:win": "protoc -I .\\proto .\\proto\\auth\\v1\\auth.proto .\\proto\\user\\v1\\user.proto .\\proto\\profile\\v1\\profile.proto .\\proto\\media\\v1\\media.proto .\\proto\\collection\\v1\\collection.proto .\\proto\\library\\v1\\library.proto .\\proto\\favorite\\v1\\favorite.proto .\\proto\\media_request\\v1\\media_request.proto .\\proto\\image\\v1\\image.proto .\\proto\\search\\v1\\search.proto .\\proto\\recommendation\\v1\\recommendation.proto --plugin=protoc-gen-ts_proto=.\\node_modules\\.bin\\protoc-gen-ts_proto.cmd --ts_proto_out=.\\generated --ts_proto_opt=nestJs=true,package=omit",
+        "generate:ci": "protoc -I ./proto ./proto/auth/v1/auth.proto ./proto/user/v1/user.proto ./proto/profile/v1/profile.proto ./proto/media/v1/media.proto ./proto/collection/v1/collection.proto ./proto/library/v1/library.proto ./proto/favorite/v1/favorite.proto ./proto/media_request/v1/media_request.proto ./proto/image/v1/image.proto ./proto/search/v1/search.proto ./proto/recommendation/v1/recommendation.proto --plugin=protoc-gen-ts_proto=./node_modules/.bin/protoc-gen-ts_proto --ts_proto_out=./generated --ts_proto_opt=nestJs=true,package=omit",
         "build": "tsc -p tsconfig.build.json"
     },
     "files": [

package/proto/auth/v1/auth.proto

@@ -21,6 +21,9 @@ service AuthService {
   rpc AdminLogin(AdminLoginRequest) returns (AdminLoginResponse);
   rpc AdminLogout(AdminLogoutRequest) returns (AdminLogoutResponse);
   rpc AdminValidateSession(AdminValidateSessionRequest) returns (AdminValidateSessionResponse);
+
+  // Called by user-service after identity fields change (e.g. email, role) so active sessions stay in sync.
+  rpc ApplyUserIdentitySnapshot(ApplyUserIdentitySnapshotRequest) returns (ApplyUserIdentitySnapshotResponse);
 }
 
 // Identity-only view of a user emitted by auth-service.
@@ -151,3 +154,9 @@ message AdminValidateSessionResponse {
   bool valid = 1;
   AuthUser user = 2;
 }
+
+message ApplyUserIdentitySnapshotRequest {
+  AuthUser user = 1;
+}
+
+message ApplyUserIdentitySnapshotResponse {}

package/proto/collection/v1/collection.proto

@@ -0,0 +1,120 @@
+syntax = "proto3";
+
+package collection.v1;
+
+service CollectionService {
+  // Global catalog of media collections (Movies, Series, Books, Manga, Manhwa, Anime, Games, KDramas).
+  rpc ListCollections(ListCollectionsRequest) returns (ListCollectionsResponse);
+  rpc GetCollectionById(GetCollectionByIdRequest) returns (GetCollectionByIdResponse);
+  rpc GetCollectionByName(GetCollectionByNameRequest) returns (GetCollectionByNameResponse);
+  rpc SeedInitialCollections(SeedInitialCollectionsRequest) returns (SeedInitialCollectionsResponse);
+
+  // Per-user enabled collections.
+  rpc GetUserCollections(GetUserCollectionsRequest) returns (GetUserCollectionsResponse);
+  rpc GetAllCollectionsWithUserStatus(GetAllCollectionsWithUserStatusRequest) returns (GetAllCollectionsWithUserStatusResponse);
+  rpc GetAvailableCollections(GetAvailableCollectionsRequest) returns (GetAvailableCollectionsResponse);
+  rpc AddCollectionToUser(AddCollectionToUserRequest) returns (AddCollectionToUserResponse);
+  rpc RemoveCollectionFromUser(RemoveCollectionFromUserRequest) returns (RemoveCollectionFromUserResponse);
+  rpc InitializeDefaultCollections(InitializeDefaultCollectionsRequest) returns (InitializeDefaultCollectionsResponse);
+}
+
+message Collection {
+  string id = 1;
+  string name = 2;
+  string created_at = 3;
+  string updated_at = 4;
+  // Number of Media records linked to the collection (returned by list/get).
+  int32 media_count = 5;
+}
+
+message CollectionWithUserStatus {
+  Collection collection = 1;
+  bool is_added = 2;
+}
+
+message UserCollection {
+  string id = 1;
+  string user_id = 2;
+  string collection_id = 3;
+  Collection collection = 4;
+  string created_at = 5;
+  string updated_at = 6;
+}
+
+message ListCollectionsRequest {}
+
+message ListCollectionsResponse {
+  repeated Collection items = 1;
+}
+
+message GetCollectionByIdRequest {
+  string collection_id = 1;
+}
+
+message GetCollectionByIdResponse {
+  Collection collection = 1;
+}
+
+message GetCollectionByNameRequest {
+  string name = 1;
+}
+
+message GetCollectionByNameResponse {
+  Collection collection = 1;
+}
+
+message SeedInitialCollectionsRequest {}
+
+message SeedInitialCollectionsResponse {
+  repeated Collection items = 1;
+}
+
+message GetUserCollectionsRequest {
+  string user_id = 1;
+}
+
+message GetUserCollectionsResponse {
+  repeated Collection items = 1;
+}
+
+message GetAllCollectionsWithUserStatusRequest {
+  string user_id = 1;
+}
+
+message GetAllCollectionsWithUserStatusResponse {
+  repeated CollectionWithUserStatus items = 1;
+}
+
+message GetAvailableCollectionsRequest {
+  string user_id = 1;
+}
+
+message GetAvailableCollectionsResponse {
+  repeated Collection items = 1;
+}
+
+message AddCollectionToUserRequest {
+  string user_id = 1;
+  string collection_id = 2;
+}
+
+message AddCollectionToUserResponse {
+  UserCollection user_collection = 1;
+}
+
+message RemoveCollectionFromUserRequest {
+  string user_id = 1;
+  string collection_id = 2;
+}
+
+message RemoveCollectionFromUserResponse {
+  string collection_id = 1;
+}
+
+message InitializeDefaultCollectionsRequest {
+  string user_id = 1;
+}
+
+message InitializeDefaultCollectionsResponse {
+  repeated UserCollection items = 1;
+}

package/proto/favorite/v1/favorite.proto

@@ -0,0 +1,79 @@
+syntax = "proto3";
+
+package favorite.v1;
+
+service FavoriteService {
+  rpc CheckMultipleFavorites(CheckMultipleFavoritesRequest) returns (CheckMultipleFavoritesResponse);
+  rpc ToggleFavorite(ToggleFavoriteRequest) returns (ToggleFavoriteResponse);
+  rpc IsFavorite(IsFavoriteRequest) returns (IsFavoriteResponse);
+  rpc ListUserFavorites(ListUserFavoritesRequest) returns (ListUserFavoritesResponse);
+  rpc RemoveAllForMedia(RemoveAllForMediaRequest) returns (RemoveAllForMediaResponse);
+}
+
+message Favorite {
+  string id = 1;
+  string user_id = 2;
+  string media_id = 3;
+  string created_at = 4;
+}
+
+message CheckMultipleFavoritesRequest {
+  string user_id = 1;
+  repeated string media_ids = 2;
+}
+
+// `results` is a `media_id -> bool` map (matches the legacy REST shape).
+message CheckMultipleFavoritesResponse {
+  map<string, bool> results = 1;
+}
+
+message ToggleFavoriteRequest {
+  string user_id = 1;
+  string media_id = 2;
+}
+
+message ToggleFavoriteResponse {
+  bool is_in_favorites = 1;
+}
+
+message IsFavoriteRequest {
+  string user_id = 1;
+  string media_id = 2;
+}
+
+message IsFavoriteResponse {
+  bool is_in_favorites = 1;
+}
+
+message ListUserFavoritesRequest {
+  string user_id = 1;
+  optional string search = 2;
+  optional string collection_id = 3;
+  int32 page = 4;
+  int32 limit = 5;
+  string sort_by = 6;
+  string sort_order = 7;
+}
+
+message FavoritePaginationMeta {
+  int32 page = 1;
+  int32 limit = 2;
+  int32 total = 3;
+  int32 total_pages = 4;
+  bool has_next_page = 5;
+  bool has_prev_page = 6;
+}
+
+message ListUserFavoritesResponse {
+  repeated Favorite data = 1;
+  FavoritePaginationMeta meta = 2;
+}
+
+// Used as a side-effect by library/media when content disappears.
+message RemoveAllForMediaRequest {
+  string media_id = 1;
+}
+
+message RemoveAllForMediaResponse {
+  int32 removed_count = 1;
+}