feat: add check_audiobook_ids, podcast batch episodes, and music together group query

Author: jdaberkow

CLAUDE.md

@@ -68,7 +68,7 @@ Always run `make lint` after a code change to ensure the new code adheres to the
 deezer-python-gql/
 ├── deezer_python_gql/           # Package source
 │   ├── __init__.py              # Public API — exports DeezerGQLClient
-│   ├── base_client.py           # Hand-written: ARL→JWT auth, execute(), get_data()
+│   ├── base_client.py           # Hand-written: ARL→JWT auth, execute(), get_data(), check_audiobook_ids()
 │   ├── py.typed                 # PEP 561 marker for type checkers
 │   └── generated/               # AUTO-GENERATED by ariadne-codegen — never edit manually
 │       ├── __init__.py
@@ -324,6 +324,16 @@ async with httpx.AsyncClient() as http:
 
 If no `http_client` is provided, the base client creates (and closes) a throwaway `httpx.AsyncClient` per request. This works but is inefficient for high-volume usage like library syncs.
 
+### Audiobook ID Checking
+
+The `check_audiobook_ids(album_ids)` method on `DeezerBaseClient` batch-checks whether album IDs are actually audiobooks. It builds a single aliased GraphQL query:
+
+```graphql
+{ a0: audiobook(audiobookId: "123") { id displayTitle } a1: audiobook(audiobookId: "456") { id displayTitle } }
+```
+
+**Important**: Querying only `{ id }` is insufficient — the API echoes back the input ID for *any* valid album, regardless of whether it's an audiobook. The `displayTitle` field returns `null` (with `AudiobookNotFoundError`) for non-audiobooks, so the method checks `displayTitle is not None` to distinguish real audiobooks.
+
 ## Key Configuration
 
 - **Python**: 3.12+ required (tested on 3.12, 3.13)
@@ -410,12 +420,13 @@ Use comments only to explain "why", not "what". Reserve inline comments for comp
 
 Tests are organized into four layers:
 
-| Layer                  | Tests | What's validated                                                                   |
-| ---------------------- | ----- | ---------------------------------------------------------------------------------- |
-| **Client setup**       | 3     | Import, instantiation with ARL, presence of all generated methods                  |
-| **Auth flow** (mocked) | 5     | JWT acquisition, token reuse, refresh on expiry, cookie domain, text/plain parsing |
-| **Error handling**     | 5     | HTTP errors, invalid JSON, missing data key, GraphQL errors, success path          |
-| **Model smoke tests**  | 61    | One per query/mutation — fixture parses correctly with key fields accessible       |
+| Layer                     | Tests | What's validated                                                                   |
+| ------------------------- | ----- | ---------------------------------------------------------------------------------- |
+| **Client setup**          | 3     | Import, instantiation with ARL, presence of all generated methods                  |
+| **Auth flow** (mocked)    | 5     | JWT acquisition, token reuse, refresh on expiry, cookie domain, text/plain parsing |
+| **Error handling**        | 5     | HTTP errors, invalid JSON, missing data key, GraphQL errors, success path          |
+| **Model smoke tests**     | 62    | One per query/mutation — fixture parses correctly with key fields accessible       |
+| **Audiobook ID checking** | 2     | Batch alias query returns correct subset; empty input returns empty set            |
 
 ### Auth Flow Tests
 

README.md

@@ -156,6 +156,12 @@ asyncio.run(main())
 | `music_together_update_group_settings(...)`       | Update group settings (name, family mode)   |
 | `music_together_generate_group_name()`            | Generate a random group name                |
 
+### Utilities
+
+| Method                           | Description                                                      |
+| -------------------------------- | ---------------------------------------------------------------- |
+| `check_audiobook_ids(album_ids)` | Batch-check which album IDs are audiobooks (single GraphQL call) |
+
 All methods return fully-typed Pydantic models generated from the GraphQL schema.
 
 ## Development

deezer_python_gql/base_client.py

@@ -257,3 +257,35 @@ async def _ensure_jwt(self) -> str:
         logger.debug("JWT acquired, expires at %s", self._jwt_expires_at)
 
         return self._jwt
+
+    async def check_audiobook_ids(self, album_ids: list[str]) -> set[str]:
+        """Check which album IDs are also valid audiobooks on Deezer.
+
+        Uses GraphQL aliases to batch-check many IDs in a single request.
+        Returns the subset of IDs that are audiobooks (i.e., the audiobook
+        query returns non-null for them).
+
+        :param album_ids: List of Deezer album/audiobook IDs to check.
+        """
+        if not album_ids:
+            return set()
+
+        # Query displayTitle alongside id — querying only { id } echoes back the
+        # input without validating that the ID is actually an audiobook.
+        parts = [
+            f'a{i}: audiobook(audiobookId: "{aid}") {{ id displayTitle }}'
+            for i, aid in enumerate(album_ids)
+        ]
+        query = "{ " + " ".join(parts) + " }"
+
+        resp = await self.execute(query)
+        data = self.get_data(resp)
+
+        audiobook_ids: set[str] = set()
+        for i, aid in enumerate(album_ids):
+            node = data.get(f"a{i}")
+            # The API echoes back {id} for any valid album, so we must check
+            # a real audiobook field like displayTitle to distinguish.
+            if node is not None and node.get("displayTitle") is not None:
+                audiobook_ids.add(aid)
+        return audiobook_ids

deezer_python_gql/generated/__init__.py

@@ -299,6 +299,10 @@
     GetMusicTogetherGroup,
     GetMusicTogetherGroupMusicTogetherGroup,
     GetMusicTogetherGroupMusicTogetherGroupCuratedTracklist,
+    GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracks,
+    GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracksEdges,
+    GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracksEdgesNode,
+    GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracksPageInfo,
     GetMusicTogetherGroupMusicTogetherGroupMembers,
     GetMusicTogetherGroupMusicTogetherGroupMembersEdges,
     GetMusicTogetherGroupMusicTogetherGroupMembersEdgesAffinity,
@@ -365,6 +369,10 @@
     GetPodcastEpisodeBookmarksMePodcastEpisodeBookmarksEdgesNodeEpisodePodcast,
     GetPodcastEpisodeBookmarksMePodcastEpisodeBookmarksPageInfo,
 )
+from .get_podcast_episodes_by_ids import (
+    GetPodcastEpisodesByIds,
+    GetPodcastEpisodesByIdsPodcastEpisodesByIds,
+)
 from .get_recently_played import (
     GetRecentlyPlayed,
     GetRecentlyPlayedMe,
@@ -812,6 +820,10 @@
     "GetMusicTogetherGroup",
     "GetMusicTogetherGroupMusicTogetherGroup",
     "GetMusicTogetherGroupMusicTogetherGroupCuratedTracklist",
+    "GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracks",
+    "GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracksEdges",
+    "GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracksEdgesNode",
+    "GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracksPageInfo",
     "GetMusicTogetherGroupMusicTogetherGroupMembers",
     "GetMusicTogetherGroupMusicTogetherGroupMembersEdges",
     "GetMusicTogetherGroupMusicTogetherGroupMembersEdgesAffinity",
@@ -859,6 +871,8 @@
     "GetPodcastEpisodePodcastEpisodePodcast",
     "GetPodcastEpisodePodcastEpisodeUrlDeezerUrl",
     "GetPodcastEpisodePodcastEpisodeUrlUrl",
+    "GetPodcastEpisodesByIds",
+    "GetPodcastEpisodesByIdsPodcastEpisodesByIds",
     "GetPodcastPodcast",
     "GetPodcastPodcastEpisodes",
     "GetPodcastPodcastEpisodesEdges",

deezer_python_gql/generated/base_client.py

@@ -259,3 +259,35 @@ async def _ensure_jwt(self) -> str:
         logger.debug("JWT acquired, expires at %s", self._jwt_expires_at)
 
         return self._jwt
+
+    async def check_audiobook_ids(self, album_ids: list[str]) -> set[str]:
+        """Check which album IDs are also valid audiobooks on Deezer.
+
+        Uses GraphQL aliases to batch-check many IDs in a single request.
+        Returns the subset of IDs that are audiobooks (i.e., the audiobook
+        query returns non-null for them).
+
+        :param album_ids: List of Deezer album/audiobook IDs to check.
+        """
+        if not album_ids:
+            return set()
+
+        # Query displayTitle alongside id — querying only { id } echoes back the
+        # input without validating that the ID is actually an audiobook.
+        parts = [
+            f'a{i}: audiobook(audiobookId: "{aid}") {{ id displayTitle }}'
+            for i, aid in enumerate(album_ids)
+        ]
+        query = "{ " + " ".join(parts) + " }"
+
+        resp = await self.execute(query)
+        data = self.get_data(resp)
+
+        audiobook_ids: set[str] = set()
+        for i, aid in enumerate(album_ids):
+            node = data.get(f"a{i}")
+            # The API echoes back {id} for any valid album, so we must check
+            # a real audiobook field like displayTitle to distinguish.
+            if node is not None and node.get("displayTitle") is not None:
+                audiobook_ids.add(aid)
+        return audiobook_ids

deezer_python_gql/generated/client.py

@@ -83,6 +83,10 @@
     GetPodcastEpisodeBookmarks,
     GetPodcastEpisodeBookmarksMe,
 )
+from .get_podcast_episodes_by_ids import (
+    GetPodcastEpisodesByIds,
+    GetPodcastEpisodesByIdsPodcastEpisodesByIds,
+)
 from .get_recently_played import GetRecentlyPlayed, GetRecentlyPlayedMe
 from .get_recommendations import GetRecommendations, GetRecommendationsMe
 from .get_similar_tracks import GetSimilarTracks, GetSimilarTracksTrack
@@ -2069,6 +2073,17 @@ async def get_music_together_group(
                 }
                 curatedTracklist {
                   ...PlaylistFields
+                  tracks(first: $tracksFirst, after: $tracksAfter) {
+                    edges {
+                      cursor
+                      node {
+                        ...TrackFields
+                      }
+                    }
+                    pageInfo {
+                      ...PageInfoFields
+                    }
+                  }
                 }
               }
             }
@@ -2303,6 +2318,7 @@ async def get_podcast(
             query GetPodcast($podcastId: String!, $episodesFirst: Int = 50, $episodesAfter: String, $episodeOrder: PodcastEpisodeOrder = LATEST) {
               podcast(podcastId: $podcastId) {
                 ...PodcastFields
+                rawEpisodes
                 isAdvertisingAllowed
                 isDownloadAllowed
                 rights {
@@ -2515,6 +2531,45 @@ async def get_podcast_episode_bookmarks(
         data = self.get_data(response)
         return GetPodcastEpisodeBookmarks.model_validate(data).me
 
+    async def get_podcast_episodes_by_ids(
+        self, ids: list[str], **kwargs: Any
+    ) -> list[Optional[GetPodcastEpisodesByIdsPodcastEpisodesByIds]]:
+        query = gql("""
+            query GetPodcastEpisodesByIds($ids: [String!]!) {
+              podcastEpisodesByIds(ids: $ids) {
+                ...PodcastEpisodeFields
+              }
+            }
+
+            fragment PodcastEpisodeFields on PodcastEpisode {
+              id
+              title
+              description
+              duration
+              cover {
+                id
+                urls(pictureRequest: {width: 264, height: 264})
+              }
+              publicationDate
+              media {
+                url
+                codec {
+                  type
+                  bitrate
+                }
+              }
+            }
+            """)
+        variables: dict[str, object] = {"ids": ids}
+        response = await self.execute(
+            query=query,
+            operation_name="GetPodcastEpisodesByIds",
+            variables=variables,
+            **kwargs
+        )
+        data = self.get_data(response)
+        return GetPodcastEpisodesByIds.model_validate(data).podcast_episodes_by_ids
+
     async def get_recently_played(
         self, first: Union[Optional[int], UnsetType] = UNSET, **kwargs: Any
     ) -> Optional[GetRecentlyPlayedMe]:

deezer_python_gql/generated/get_music_together_group.py

@@ -148,6 +148,32 @@ class GetMusicTogetherGroupMusicTogetherGroupSuggestedTracklistTracklistTracksPa
 
 
 class GetMusicTogetherGroupMusicTogetherGroupCuratedTracklist(PlaylistFields):
+    tracks: "GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracks"
+
+
+class GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracks(BaseModel):
+    edges: list["GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracksEdges"]
+    page_info: (
+        "GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracksPageInfo"
+    ) = Field(alias="pageInfo")
+
+
+class GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracksEdges(BaseModel):
+    cursor: str
+    node: Optional[
+        "GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracksEdgesNode"
+    ]
+
+
+class GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracksEdgesNode(
+    TrackFields
+):
+    pass
+
+
+class GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracksPageInfo(
+    PageInfoFields
+):
     pass
 
 
@@ -163,3 +189,6 @@ class GetMusicTogetherGroupMusicTogetherGroupCuratedTracklist(PlaylistFields):
 GetMusicTogetherGroupMusicTogetherGroupSuggestedTracklistTracklistTracksEdgesMetadata.model_rebuild()
 GetMusicTogetherGroupMusicTogetherGroupSuggestedTracklistTracklistTracksEdgesMetadataMusicTogether.model_rebuild()
 GetMusicTogetherGroupMusicTogetherGroupSuggestedTracklistTracklistTracksEdgesMetadataMusicTogetherTrackOrigin.model_rebuild()
+GetMusicTogetherGroupMusicTogetherGroupCuratedTracklist.model_rebuild()
+GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracks.model_rebuild()
+GetMusicTogetherGroupMusicTogetherGroupCuratedTracklistTracksEdges.model_rebuild()

deezer_python_gql/generated/get_podcast.py

@@ -14,6 +14,7 @@ class GetPodcast(BaseModel):
 
 
 class GetPodcastPodcast(PodcastFields):
+    raw_episodes: list[str] = Field(alias="rawEpisodes")
     is_advertising_allowed: bool = Field(alias="isAdvertisingAllowed")
     is_download_allowed: bool = Field(alias="isDownloadAllowed")
     rights: "GetPodcastPodcastRights"

deezer_python_gql/generated/get_podcast_episodes_by_ids.py

@@ -0,0 +1,22 @@
+# Generated by ariadne-codegen
+# Source: queries
+
+from typing import Optional
+
+from pydantic import Field
+
+from .base_model import BaseModel
+from .fragments import PodcastEpisodeFields
+
+
+class GetPodcastEpisodesByIds(BaseModel):
+    podcast_episodes_by_ids: list[
+        Optional["GetPodcastEpisodesByIdsPodcastEpisodesByIds"]
+    ] = Field(alias="podcastEpisodesByIds")
+
+
+class GetPodcastEpisodesByIdsPodcastEpisodesByIds(PodcastEpisodeFields):
+    pass
+
+
+GetPodcastEpisodesByIds.model_rebuild()

queries/get_music_together_group.graphql

@@ -66,6 +66,17 @@ query GetMusicTogetherGroup(
     }
     curatedTracklist {
       ...PlaylistFields
+      tracks(first: $tracksFirst, after: $tracksAfter) {
+        edges {
+          cursor
+          node {
+            ...TrackFields
+          }
+        }
+        pageInfo {
+          ...PageInfoFields
+        }
+      }
     }
   }
 }