gerdur-core 2.5.0 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 2.6.0 - 2026-08-31
+
+Phase 2.4 round 2 — Flow, radios, and a user's library. All public REST, all
+memoised, all additive.
+
+### Added
+
+- **Flow / library** (take a `userId`): `getUserFlow`, `getUserFavoriteTracks`
+  (with `time_add`), `getUserFavoriteAlbums`, `getUserFavoriteArtists`,
+  `getUserPlaylists`, `getUserRadios`, `getUserChartTracks`.
+- **Radios**: `getRadios`, `getRadioTracks(radioId)`, `getRadioGenres`.
+- New types: `userFavoriteTrack`, `userFavoriteAlbum`, `userFavoriteArtist`,
+  `userPlaylistResult`, `radioResult`, `radioGenre`.
+
+### Internal
+
+- Tests run under `ts-node/register/transpile-only` (build still type-checks) —
+  the growing live-API suite was hitting the ts-node worker heap limit.
+- Live-API tests skip cleanly on Deezer's `code: 4` "Quota limit exceeded"
+  instead of failing when the suite bursts the public API.
+
 ## 2.5.0 - 2026-08-31
 
 Phase 3.1 — streaming download primitives. Additive.

package/README.md

@@ -244,6 +244,31 @@ const track = await getTrackByISRC('USUM71311296');      // "Get Lucky"
 pass the `id` to `getTrackInfo` / `getAlbumTracks` (or use the converter's
 `isrc2deezer` / `upc2deezer`, which hydrate a gw track for you).
 
+### Flow, radios & a user's library
+
+Public-profile data — pass a `userId` (`getUser().USER_ID`, a profile URL, or
+`parseInfo`). A private library is only visible to that user's own session.
+
+| Method | Returns |
+| :--- | :--- |
+| `getUserFlow(userId, limit = 40)` | **Flow** — the endless personalised mix, as tracks. |
+| `getUserFavoriteTracks(userId, limit?, index?)` | loved tracks, newest first (each with `time_add`). |
+| `getUserFavoriteAlbums(userId, limit?, index?)` | favourite albums. |
+| `getUserFavoriteArtists(userId, limit?, index?)` | favourite artists. |
+| `getUserPlaylists(userId, limit?, index?)` | the user's own + followed playlists. |
+| `getUserRadios(userId)` | radios the user favourited. |
+| `getUserChartTracks(userId, limit?)` | the user's personal top tracks. |
+| `getRadios()` | Deezer's curated radio list. |
+| `getRadioTracks(radioId)` | a radio's current tracklist — a ready-to-play source. |
+| `getRadioGenres()` | radios grouped by genre. |
+
+```js
+const me = await getUser();
+const {data: flow} = await getUserFlow(me.USER_ID);       // your Flow
+const {data: loved} = await getUserFavoriteTracks(me.USER_ID);
+const {data: eighties} = await getRadioTracks(38305);     // "The '80s"
+```
+
 ### `.getTrackDownloadUrl(track, quality);`
 
 | Parameters | Required |        Type |                        Description |

package/dist/api/index.d.ts

@@ -3,3 +3,4 @@ export * from './request';
 export * from './search';
 export * from './browse';
 export * from './preview';
+export * from './user';

package/dist/api/index.js

@@ -19,3 +19,4 @@ __exportStar(require("./request"), exports);
 __exportStar(require("./search"), exports);
 __exportStar(require("./browse"), exports);
 __exportStar(require("./preview"), exports);
+__exportStar(require("./user"), exports);

package/dist/api/user.d.ts

@@ -0,0 +1,24 @@
+import type { publicApiList, radioGenre, radioResult, searchResultTrack, userFavoriteAlbum, userFavoriteArtist, userFavoriteTrack, userPlaylistResult } from '../types';
+/**
+ * Deezer **Flow** — the endless personalised mix — for a user. Returns
+ * public-API track objects; `getTrackInfo(id)` to make one downloadable.
+ */
+export declare const getUserFlow: (userId: number | string, limit?: number) => Promise<publicApiList<searchResultTrack>>;
+/** A user's favourite (loved) tracks, newest first; each carries `time_add`. */
+export declare const getUserFavoriteTracks: (userId: number | string, limit?: number, index?: number) => Promise<publicApiList<userFavoriteTrack>>;
+/** A user's favourite albums. */
+export declare const getUserFavoriteAlbums: (userId: number | string, limit?: number, index?: number) => Promise<publicApiList<userFavoriteAlbum>>;
+/** A user's favourite artists. */
+export declare const getUserFavoriteArtists: (userId: number | string, limit?: number, index?: number) => Promise<publicApiList<userFavoriteArtist>>;
+/** A user's own + followed playlists. */
+export declare const getUserPlaylists: (userId: number | string, limit?: number, index?: number) => Promise<publicApiList<userPlaylistResult>>;
+/** The radios a user has favourited. */
+export declare const getUserRadios: (userId: number | string) => Promise<publicApiList<radioResult>>;
+/** A user's personal track chart (their most-played). */
+export declare const getUserChartTracks: (userId: number | string, limit?: number) => Promise<publicApiList<searchResultTrack>>;
+/** Deezer's curated radio list. */
+export declare const getRadios: () => Promise<publicApiList<radioResult>>;
+/** A radio's current track list — a ready-to-play (public-API) source. */
+export declare const getRadioTracks: (radioId: number | string) => Promise<publicApiList<searchResultTrack>>;
+/** Radios grouped by genre. */
+export declare const getRadioGenres: () => Promise<publicApiList<radioGenre>>;

package/dist/api/user.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRadioGenres = exports.getRadioTracks = exports.getRadios = exports.getUserChartTracks = exports.getUserRadios = exports.getUserPlaylists = exports.getUserFavoriteArtists = exports.getUserFavoriteAlbums = exports.getUserFavoriteTracks = exports.getUserFlow = void 0;
+const request_1 = require("./request");
+const withParams = (slug, params) => {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== '') {
+            search.set(key, String(value));
+        }
+    }
+    const qs = search.toString();
+    return qs ? `${slug}?${qs}` : slug;
+};
+// ─── Flow & a user's library (public REST) ───────────────────────────────────
+//
+// These take an explicit `userId` (from `getUser().USER_ID`, a profile URL, or
+// `parseInfo`). They read **public** profile data — a user whose library is
+// private only exposes it to their own authenticated session. All memoised.
+/**
+ * Deezer **Flow** — the endless personalised mix — for a user. Returns
+ * public-API track objects; `getTrackInfo(id)` to make one downloadable.
+ */
+const getUserFlow = (userId, limit = 40) => (0, request_1.requestPublicApi)(withParams(`/user/${userId}/flow`, { limit }));
+exports.getUserFlow = getUserFlow;
+/** A user's favourite (loved) tracks, newest first; each carries `time_add`. */
+const getUserFavoriteTracks = (userId, limit = 100, index = 0) => (0, request_1.requestPublicApi)(withParams(`/user/${userId}/tracks`, { limit, index }));
+exports.getUserFavoriteTracks = getUserFavoriteTracks;
+/** A user's favourite albums. */
+const getUserFavoriteAlbums = (userId, limit = 50, index = 0) => (0, request_1.requestPublicApi)(withParams(`/user/${userId}/albums`, { limit, index }));
+exports.getUserFavoriteAlbums = getUserFavoriteAlbums;
+/** A user's favourite artists. */
+const getUserFavoriteArtists = (userId, limit = 50, index = 0) => (0, request_1.requestPublicApi)(withParams(`/user/${userId}/artists`, { limit, index }));
+exports.getUserFavoriteArtists = getUserFavoriteArtists;
+/** A user's own + followed playlists. */
+const getUserPlaylists = (userId, limit = 50, index = 0) => (0, request_1.requestPublicApi)(withParams(`/user/${userId}/playlists`, { limit, index }));
+exports.getUserPlaylists = getUserPlaylists;
+/** The radios a user has favourited. */
+const getUserRadios = (userId) => (0, request_1.requestPublicApi)(`/user/${userId}/radios`);
+exports.getUserRadios = getUserRadios;
+/** A user's personal track chart (their most-played). */
+const getUserChartTracks = (userId, limit = 50) => (0, request_1.requestPublicApi)(withParams(`/user/${userId}/charts/tracks`, { limit }));
+exports.getUserChartTracks = getUserChartTracks;
+// ─── Radios (public REST) ────────────────────────────────────────────────────
+/** Deezer's curated radio list. */
+const getRadios = () => (0, request_1.requestPublicApi)('/radio');
+exports.getRadios = getRadios;
+/** A radio's current track list — a ready-to-play (public-API) source. */
+const getRadioTracks = (radioId) => (0, request_1.requestPublicApi)(`/radio/${radioId}/tracks`);
+exports.getRadioTracks = getRadioTracks;
+/** Radios grouped by genre. */
+const getRadioGenres = () => (0, request_1.requestPublicApi)('/radio/genres');
+exports.getRadioGenres = getRadioGenres;

package/dist/types/user.d.ts

@@ -1,3 +1,4 @@
+import type { searchResultTrack, searchResultArtist } from './search';
 export interface userType {
     USER_ID: string;
     EMAIL: string;
@@ -14,3 +15,82 @@ export interface userType {
     PHONE?: string;
     __TYPE__: 'user';
 }
+/** A favourite track from `/user/{id}/tracks` — public-API shape, plus `time_add`. */
+export interface userFavoriteTrack extends searchResultTrack {
+    /** unix timestamp the track was added to favourites */
+    time_add?: number;
+}
+export interface userFavoriteAlbum {
+    id: number;
+    title: string;
+    link: string;
+    cover: string;
+    cover_small?: string;
+    cover_medium?: string;
+    cover_big?: string;
+    cover_xl?: string;
+    md5_image: string;
+    nb_tracks: number;
+    release_date: string;
+    record_type: string;
+    available: boolean;
+    tracklist: string;
+    explicit_lyrics: boolean;
+    time_add?: number;
+    artist: searchResultArtist | {
+        id: number;
+        name: string;
+        tracklist?: string;
+        type: 'artist';
+    };
+    type: 'album';
+}
+export interface userFavoriteArtist extends searchResultArtist {
+    time_add?: number;
+}
+export interface userPlaylistResult {
+    id: number;
+    title: string;
+    duration: number;
+    public: boolean;
+    is_loved_track: boolean;
+    collaborative: boolean;
+    nb_tracks: number;
+    fans: number;
+    link: string;
+    picture: string;
+    picture_small?: string;
+    picture_medium?: string;
+    picture_big?: string;
+    picture_xl?: string;
+    checksum: string;
+    tracklist: string;
+    creation_date?: string;
+    time_add?: number;
+    time_mod?: number;
+    creator?: {
+        id: number;
+        name: string;
+        tracklist?: string;
+        type: 'user';
+    };
+    type: 'playlist';
+}
+export interface radioResult {
+    id: number;
+    title: string;
+    description?: string;
+    picture: string;
+    picture_small?: string;
+    picture_medium?: string;
+    picture_big?: string;
+    picture_xl?: string;
+    md5_image?: string;
+    tracklist: string;
+    type: 'radio';
+}
+export interface radioGenre {
+    id: number;
+    title: string;
+    radios: radioResult[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gerdur-core",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Core module for gerdur.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -61,7 +61,7 @@
       "!__tests__/helpers.ts"
     ],
     "require": [
-      "ts-node/register"
+      "ts-node/register/transpile-only"
     ],
     "timeout": "2m",
     "verbose": true