@freqhole/api-client 0.2.14 → 0.3.1

package/src/domains/entities.ts

@@ -0,0 +1,304 @@
+// entities domain methods for FreqholeClient
+//
+// domain-neutral routes for entity_taxonz/playlist_itemz - any TaggableEntity
+// (video today; other domains reuse the same routes as they're added, see
+// docs/video-domain-plan.md's "add a domain" recipe).
+
+import { routes } from "../codegen/routes.js";
+import type * as s from "../codegen/schema.js";
+import type { CallFn } from "./types.js";
+
+export function createEntitiesMethods(call: CallFn) {
+  return {
+    // taxon links
+    getEntityTaxons: (params: s.GetEntityTaxonsRequest) => {
+      return call(
+        "entities",
+        "get_entity_taxons",
+        routes.entities.get_entity_taxons.resp,
+        routes.entities.get_entity_taxons.req,
+        routes.entities.get_entity_taxons.method,
+        routes.entities.get_entity_taxons.path,
+        params,
+      );
+    },
+
+    addEntityTaxon: (params: s.AddEntityTaxonRequest) => {
+      return call(
+        "entities",
+        "add_entity_taxon",
+        routes.entities.add_entity_taxon.resp,
+        routes.entities.add_entity_taxon.req,
+        routes.entities.add_entity_taxon.method,
+        routes.entities.add_entity_taxon.path,
+        params,
+      );
+    },
+
+    removeEntityTaxon: (params: s.RemoveEntityTaxonRequest) => {
+      return call(
+        "entities",
+        "remove_entity_taxon",
+        routes.entities.remove_entity_taxon.resp,
+        routes.entities.remove_entity_taxon.req,
+        routes.entities.remove_entity_taxon.method,
+        routes.entities.remove_entity_taxon.path,
+        params,
+      );
+    },
+
+    // entity urls
+    getEntityUrls: (params: s.GetEntityUrlsRequest) => {
+      return call(
+        "entities",
+        "get_entity_urls",
+        routes.entities.get_entity_urls.resp,
+        routes.entities.get_entity_urls.req,
+        routes.entities.get_entity_urls.method,
+        routes.entities.get_entity_urls.path,
+        params,
+      );
+    },
+
+    addEntityUrl: (params: s.AddEntityUrlRequest) => {
+      return call(
+        "entities",
+        "add_entity_url",
+        routes.entities.add_entity_url.resp,
+        routes.entities.add_entity_url.req,
+        routes.entities.add_entity_url.method,
+        routes.entities.add_entity_url.path,
+        params,
+      );
+    },
+
+    removeEntityUrl: (params: s.RemoveEntityUrlRequest) => {
+      return call(
+        "entities",
+        "remove_entity_url",
+        routes.entities.remove_entity_url.resp,
+        routes.entities.remove_entity_url.req,
+        routes.entities.remove_entity_url.method,
+        routes.entities.remove_entity_url.path,
+        params,
+      );
+    },
+
+    // entity images
+    getEntityImages: (params: s.GetEntityImagesRequest) => {
+      return call(
+        "entities",
+        "get_entity_images",
+        routes.entities.get_entity_images.resp,
+        routes.entities.get_entity_images.req,
+        routes.entities.get_entity_images.method,
+        routes.entities.get_entity_images.path,
+        params,
+      );
+    },
+
+    // entity tags (bulk-first; a single-entity call is just a 1-element
+    // entity_ids array)
+    getEntitiesTags: (params: s.GetEntitiesTagsRequest) => {
+      return call(
+        "entities",
+        "get_entities_tags",
+        routes.entities.get_entities_tags.resp,
+        routes.entities.get_entities_tags.req,
+        routes.entities.get_entities_tags.method,
+        routes.entities.get_entities_tags.path,
+        params,
+      );
+    },
+
+    // every tag used by at least one entity of a given type (unlike
+    // getEntitiesTags, not scoped to a specific set of entity ids) —
+    // used to drive per-domain tag filter pickers without showing tags
+    // that belong to a different domain / have zero matching entities.
+    listEntityTypeTags: (params: s.ListEntityTypeTagsRequest) => {
+      return call(
+        "entities",
+        "list_entity_type_tags",
+        routes.entities.list_entity_type_tags.resp,
+        routes.entities.list_entity_type_tags.req,
+        routes.entities.list_entity_type_tags.method,
+        routes.entities.list_entity_type_tags.path,
+        params,
+      );
+    },
+
+    addEntitiesTags: (params: s.AddEntitiesTagsRequest) => {
+      return call(
+        "entities",
+        "add_entities_tags",
+        routes.entities.add_entities_tags.resp,
+        routes.entities.add_entities_tags.req,
+        routes.entities.add_entities_tags.method,
+        routes.entities.add_entities_tags.path,
+        params,
+      );
+    },
+
+    removeEntitiesTags: (params: s.RemoveEntitiesTagsRequest) => {
+      return call(
+        "entities",
+        "remove_entities_tags",
+        routes.entities.remove_entities_tags.resp,
+        routes.entities.remove_entities_tags.req,
+        routes.entities.remove_entities_tags.method,
+        routes.entities.remove_entities_tags.path,
+        params,
+      );
+    },
+
+    // playlist items
+    listPlaylistItems: (params: s.ListPlaylistItemsRequest) => {
+      return call(
+        "entities",
+        "list_playlist_items",
+        routes.entities.list_playlist_items.resp,
+        routes.entities.list_playlist_items.req,
+        routes.entities.list_playlist_items.method,
+        routes.entities.list_playlist_items.path,
+        params,
+      );
+    },
+
+    addPlaylistItem: (params: s.AddPlaylistItemRequest) => {
+      return call(
+        "entities",
+        "add_playlist_item",
+        routes.entities.add_playlist_item.resp,
+        routes.entities.add_playlist_item.req,
+        routes.entities.add_playlist_item.method,
+        routes.entities.add_playlist_item.path,
+        params,
+      );
+    },
+
+    removePlaylistItem: (params: s.RemovePlaylistItemRequest) => {
+      return call(
+        "entities",
+        "remove_playlist_item",
+        routes.entities.remove_playlist_item.resp,
+        routes.entities.remove_playlist_item.req,
+        routes.entities.remove_playlist_item.method,
+        routes.entities.remove_playlist_item.path,
+        params,
+      );
+    },
+
+    reorderPlaylistItems: (params: s.ReorderPlaylistItemsRequest) => {
+      return call(
+        "entities",
+        "reorder_playlist_items",
+        routes.entities.reorder_playlist_items.resp,
+        routes.entities.reorder_playlist_items.req,
+        routes.entities.reorder_playlist_items.method,
+        routes.entities.reorder_playlist_items.path,
+        params,
+      );
+    },
+
+    addPlaylistItems: (params: s.AddPlaylistItemsRequest) => {
+      return call(
+        "entities",
+        "add_playlist_items",
+        routes.entities.add_playlist_items.resp,
+        routes.entities.add_playlist_items.req,
+        routes.entities.add_playlist_items.method,
+        routes.entities.add_playlist_items.path,
+        params,
+      );
+    },
+
+    removePlaylistItems: (params: s.RemovePlaylistItemsRequest) => {
+      return call(
+        "entities",
+        "remove_playlist_items",
+        routes.entities.remove_playlist_items.resp,
+        routes.entities.remove_playlist_items.req,
+        routes.entities.remove_playlist_items.method,
+        routes.entities.remove_playlist_items.path,
+        params,
+      );
+    },
+
+    // favorites (domain-agnostic set/status-check; rich music-specific
+    // listing endpoints live on client.music - see listFavorites/listBeloved)
+    setFavorite: (params: s.SetFavoriteRequest) => {
+      return call(
+        "entities",
+        "set_favorite",
+        routes.entities.set_favorite.resp,
+        routes.entities.set_favorite.req,
+        routes.entities.set_favorite.method,
+        routes.entities.set_favorite.path,
+        params,
+      );
+    },
+
+    getFavoriteStatusBulk: (params: s.GetFavoriteStatusBulkRequest) => {
+      return call(
+        "entities",
+        "get_favorite_status_bulk",
+        routes.entities.get_favorite_status_bulk.resp,
+        routes.entities.get_favorite_status_bulk.req,
+        routes.entities.get_favorite_status_bulk.method,
+        routes.entities.get_favorite_status_bulk.path,
+        params,
+      );
+    },
+
+    // ratings (domain-agnostic)
+    setRating: (params: s.SetRatingRequest) => {
+      return call(
+        "entities",
+        "set_rating",
+        routes.entities.set_rating.resp,
+        routes.entities.set_rating.req,
+        routes.entities.set_rating.method,
+        routes.entities.set_rating.path,
+        params,
+      );
+    },
+
+    removeRating: (params: s.RemoveRatingRequest) => {
+      return call(
+        "entities",
+        "remove_rating",
+        routes.entities.remove_rating.resp,
+        routes.entities.remove_rating.req,
+        routes.entities.remove_rating.method,
+        routes.entities.remove_rating.path,
+        params,
+      );
+    },
+
+    getRatingStats: (params: s.GetRatingStatsRequest) => {
+      return call(
+        "entities",
+        "get_rating_stats",
+        routes.entities.get_rating_stats.resp,
+        routes.entities.get_rating_stats.req,
+        routes.entities.get_rating_stats.method,
+        routes.entities.get_rating_stats.path,
+        params,
+      );
+    },
+
+    getRatingStatusBulk: (params: s.GetRatingStatusBulkRequest) => {
+      return call(
+        "entities",
+        "get_rating_status_bulk",
+        routes.entities.get_rating_status_bulk.resp,
+        routes.entities.get_rating_status_bulk.req,
+        routes.entities.get_rating_status_bulk.method,
+        routes.entities.get_rating_status_bulk.path,
+        params,
+      );
+    },
+  };
+}
+
+export type EntitiesMethods = ReturnType<typeof createEntitiesMethods>;

package/src/domains/favorites.types.ts

@@ -6,6 +6,8 @@ import {
   AlbumQueryResultSchema,
   ArtistQueryResultSchema,
   PlaylistQueryResultSchema,
+  VideoSchema,
+  VideoSeriesSchema,
 } from "../codegen/schema.js";
 
 // discriminated union for favorite items
@@ -31,6 +33,16 @@ const FavoriteItemSchema = z.discriminatedUnion("type", [
     favorited_at: z.number(),
     playlist: PlaylistQueryResultSchema,
   }),
+  z.object({
+    type: z.literal("video"),
+    favorited_at: z.number(),
+    video: VideoSchema,
+  }),
+  z.object({
+    type: z.literal("video_series"),
+    favorited_at: z.number(),
+    series: VideoSeriesSchema,
+  }),
 ]);
 
 export type FavoriteItem = z.infer<typeof FavoriteItemSchema>;
@@ -44,9 +56,7 @@ const ListFavoritesResponseSchema = z.object({
   limit: z.number(),
 });
 
-export type ListFavoritesResponse = z.infer<
-  typeof ListFavoritesResponseSchema
->;
+export type ListFavoritesResponse = z.infer<typeof ListFavoritesResponseSchema>;
 
 // export schemas for runtime validation if needed
 export { FavoriteItemSchema, ListFavoritesResponseSchema };

package/src/domains/music.ts

@@ -11,12 +11,15 @@ import { ListFavoritesResponseSchema } from "./favorites.types.js";
 import type { CallFn } from "./types.js";
 
 // partial schemas for update operations
-const UpdateSongsRequestPartialSchema =
-  UpdateSongsRequestSchema.partial().required({ song_ids: true });
-const UpdateArtistRequestPartialSchema =
-  UpdateArtistRequestSchema.partial().required({ artist_id: true });
-const UpdateAlbumRequestPartialSchema =
-  UpdateAlbumRequestSchema.partial().required({ album_id: true });
+const UpdateSongsRequestPartialSchema = UpdateSongsRequestSchema.partial().required({
+  song_ids: true,
+});
+const UpdateArtistRequestPartialSchema = UpdateArtistRequestSchema.partial().required({
+  artist_id: true,
+});
+const UpdateAlbumRequestPartialSchema = UpdateAlbumRequestSchema.partial().required({
+  album_id: true,
+});
 
 export function createMusicMethods(call: CallFn) {
   return {
@@ -70,9 +73,7 @@ export function createMusicMethods(call: CallFn) {
       );
     },
 
-    updateSongs: (
-      params: Partial<s.UpdateSongsRequest> & { song_ids: string[] },
-    ) => {
+    updateSongs: (params: Partial<s.UpdateSongsRequest> & { song_ids: string[] }) => {
       return call(
         "music",
         "update_songs",
@@ -157,9 +158,7 @@ export function createMusicMethods(call: CallFn) {
       );
     },
 
-    updateAlbum: (
-      params: Partial<s.UpdateAlbumRequest> & { album_id: string },
-    ) => {
+    updateAlbum: (params: Partial<s.UpdateAlbumRequest> & { album_id: string }) => {
       return call(
         "music",
         "update_album",
@@ -344,9 +343,7 @@ export function createMusicMethods(call: CallFn) {
       );
     },
 
-    updateArtist: (
-      params: Partial<s.UpdateArtistRequest> & { artist_id: string },
-    ) => {
+    updateArtist: (params: Partial<s.UpdateArtistRequest> & { artist_id: string }) => {
       return call(
         "music",
         "update_artist",
@@ -412,10 +409,7 @@ export function createMusicMethods(call: CallFn) {
     },
 
     getPlaylistEtag: (params: s.GetPlaylistRequest) => {
-      const path = routes.music.get_playlist_etag.path.replace(
-        "{id}",
-        params.id,
-      );
+      const path = routes.music.get_playlist_etag.path.replace("{id}", params.id);
       return call(
         "music",
         "get_playlist_etag",
@@ -619,44 +613,8 @@ export function createMusicMethods(call: CallFn) {
       );
     },
 
-    // ratings
-    setRating: (params: s.SetRatingRequest) => {
-      return call(
-        "music",
-        "set_rating",
-        routes.music.set_rating.resp,
-        routes.music.set_rating.req,
-        routes.music.set_rating.method,
-        routes.music.set_rating.path,
-        params,
-      );
-    },
-
-    removeRating: (params: s.RemoveRatingRequest) => {
-      return call(
-        "music",
-        "remove_rating",
-        routes.music.remove_rating.resp,
-        routes.music.remove_rating.req,
-        routes.music.remove_rating.method,
-        routes.music.remove_rating.path,
-        params,
-      );
-    },
-
-    getRatingStats: (params: s.GetRatingStatsRequest) => {
-      return call(
-        "music",
-        "get_rating_stats",
-        routes.music.get_rating_stats.resp,
-        routes.music.get_rating_stats.req,
-        routes.music.get_rating_stats.method,
-        routes.music.get_rating_stats.path,
-        params,
-      );
-    },
-
-    // favorites
+    // favorites listing (music-specific rich shapes; generic set/status-check
+    // live on client.entities)
     listFavorites: (params: s.ListFavoritesRequest) => {
       return call(
         "music",
@@ -669,18 +627,6 @@ export function createMusicMethods(call: CallFn) {
       );
     },
 
-    setFavorite: (params: s.SetFavoriteRequest) => {
-      return call(
-        "music",
-        "set_favorite",
-        routes.music.set_favorite.resp,
-        routes.music.set_favorite.req,
-        routes.music.set_favorite.method,
-        routes.music.set_favorite.path,
-        params,
-      );
-    },
-
     listBeloved: (params: s.ListBelovedRequest = {}) => {
       return call(
         "music",
@@ -706,6 +652,18 @@ export function createMusicMethods(call: CallFn) {
       );
     },
 
+    recordVideoPlay: (params: s.RecordVideoPlayRequest) => {
+      return call(
+        "music",
+        "record_video_play",
+        routes.music.record_video_play.resp,
+        routes.music.record_video_play.req,
+        routes.music.record_video_play.method,
+        routes.music.record_video_play.path,
+        params,
+      );
+    },
+
     activityFeed: (params: s.FeedRequest) => {
       return call(
         "music",
@@ -778,39 +736,40 @@ export function createMusicMethods(call: CallFn) {
       );
     },
 
-    // listen sessions
-    createListenSession: (params: s.CreateListenSessionRequest) => {
+    // playback sessions
+    createPlaybackSession: (params: s.CreatePlaybackSessionRequest) => {
       return call(
         "music",
-        "create_listen_session",
-        routes.music.create_listen_session.resp,
-        routes.music.create_listen_session.req,
-        routes.music.create_listen_session.method,
-        routes.music.create_listen_session.path,
+        "create_playback_session",
+        routes.music.create_playback_session.resp,
+        routes.music.create_playback_session.req,
+        routes.music.create_playback_session.method,
+        routes.music.create_playback_session.path,
         params,
       );
     },
 
-    getListenSession: (id: string) => {
-      const path = routes.music.get_listen_session.path.replace("{id}", id);
+    getPlaybackSession: (id: string) => {
+      const path = routes.music.get_playback_session.path.replace("{id}", id);
       return call(
         "music",
-        "get_listen_session",
-        routes.music.get_listen_session.resp,
-        routes.music.get_listen_session.req,
-        routes.music.get_listen_session.method,
+        "get_playback_session",
+        routes.music.get_playback_session.resp,
+        routes.music.get_playback_session.req,
+        routes.music.get_playback_session.method,
         path,
+        { id },
       );
     },
 
-    deleteListenSession: (id: string) => {
+    deletePlaybackSession: (id: string) => {
       return call(
         "music",
-        "delete_listen_session",
-        routes.music.delete_listen_session.resp,
-        routes.music.delete_listen_session.req,
-        routes.music.delete_listen_session.method,
-        routes.music.delete_listen_session.path,
+        "delete_playback_session",
+        routes.music.delete_playback_session.resp,
+        routes.music.delete_playback_session.req,
+        routes.music.delete_playback_session.method,
+        routes.music.delete_playback_session.path,
         { id },
       );
     },
@@ -839,66 +798,55 @@ export function createMusicMethods(call: CallFn) {
       );
     },
 
-    updateListenSessionProgress: (
-      id: string,
-      params: s.UpdateListenSessionProgressRequest,
-    ) => {
-      const path = routes.music.update_listen_session_progress.path.replace(
-        "{id}",
-        id,
-      );
+    updatePlaybackSessionProgress: (id: string, params: s.UpdatePlaybackSessionProgressRequest) => {
+      const path = routes.music.update_playback_session_progress.path.replace("{id}", id);
       return call(
         "music",
-        "update_listen_session_progress",
-        routes.music.update_listen_session_progress.resp,
-        routes.music.update_listen_session_progress.req,
-        routes.music.update_listen_session_progress.method,
+        "update_playback_session_progress",
+        routes.music.update_playback_session_progress.resp,
+        routes.music.update_playback_session_progress.req,
+        routes.music.update_playback_session_progress.method,
         path,
         params,
       );
     },
 
-    updateListenSessionStatus: (id: string, status: string) => {
-      const path = routes.music.update_listen_session_status.path
+    updatePlaybackSessionStatus: (id: string, status: string) => {
+      const path = routes.music.update_playback_session_status.path
         .replace("{id}", id)
         .replace("{status}", status);
       return call(
         "music",
-        "update_listen_session_status",
-        routes.music.update_listen_session_status.resp,
-        routes.music.update_listen_session_status.req,
-        routes.music.update_listen_session_status.method,
+        "update_playback_session_status",
+        routes.music.update_playback_session_status.resp,
+        routes.music.update_playback_session_status.req,
+        routes.music.update_playback_session_status.method,
         path,
+        { id, status },
       );
     },
 
-    updateListenSessionSongs: (
-      id: string,
-      params: s.UpdateListenSessionSongsRequest,
-    ) => {
-      const path = routes.music.update_listen_session_songs.path.replace(
-        "{id}",
-        id,
-      );
+    updatePlaybackSessionItems: (id: string, params: s.UpdatePlaybackSessionItemsRequest) => {
+      const path = routes.music.update_playback_session_items.path.replace("{id}", id);
       return call(
         "music",
-        "update_listen_session_songs",
-        routes.music.update_listen_session_songs.resp,
-        routes.music.update_listen_session_songs.req,
-        routes.music.update_listen_session_songs.method,
+        "update_playback_session_items",
+        routes.music.update_playback_session_items.resp,
+        routes.music.update_playback_session_items.req,
+        routes.music.update_playback_session_items.method,
         path,
         params,
       );
     },
 
-    listListenSessions: (params: s.ListListenSessionsRequest) => {
+    listPlaybackSessions: (params: s.ListPlaybackSessionsRequest) => {
       return call(
         "music",
-        "list_listen_sessions",
-        routes.music.list_listen_sessions.resp,
-        routes.music.list_listen_sessions.req,
-        routes.music.list_listen_sessions.method,
-        routes.music.list_listen_sessions.path,
+        "list_playback_sessions",
+        routes.music.list_playback_sessions.resp,
+        routes.music.list_playback_sessions.req,
+        routes.music.list_playback_sessions.method,
+        routes.music.list_playback_sessions.path,
         params,
       );
     },
@@ -1189,7 +1137,7 @@ export function createMusicMethods(call: CallFn) {
     // taxonomy (cross-kind labels: genre, label, mood, era, region, ...)
     // ----------------------------------------------------------------------
 
-    listTaxonKinds: () => {
+    listTaxonKinds: (params?: s.ListTaxonKindsRequest) => {
       return call(
         "music",
         "list_taxon_kinds",
@@ -1197,7 +1145,7 @@ export function createMusicMethods(call: CallFn) {
         routes.music.list_taxon_kinds.req,
         routes.music.list_taxon_kinds.method,
         routes.music.list_taxon_kinds.path,
-        undefined,
+        params,
       );
     },