gerdur-core 2.4.0 → 2.6.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # 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.
+
+### Added
+
+- **`streamTrackDownload(track, quality, options?)`** — download a track as a
+  stream of decrypted audio (`get_url` → CDN fetch → stripe-decrypt `Transform`
+  → your sink). Peak memory is ~one 2048-byte stripe regardless of file size or
+  concurrency. `options.onProgress(received, total)`; `options.resumeFrom`
+  (bytes, 2048-aligned) sends a `Range` header and resumes stripe decryption
+  in phase. Verified byte-identical to the buffered `decryptDownload` path,
+  resume included.
+- **`createDecryptStream(sngId, startChunk?)`** — a Node `Transform` wrapping the
+  stripe cipher, for composing your own pipelines. `TrackDecryptStream` gained a
+  `startChunk` constructor arg.
+- **`getStream(url, {rangeStart?})`** — a content-decoded response stream from
+  the internal HTTP client (`gunzip` / `brotli` / `inflate` handled), following
+  redirects, rejecting `HttpStatusError` on non-2xx.
+
+Streaming the tag write (in-place FLAC metadata-block rewrite) is still open.
+
 ## 2.4.0 - 2026-08-31
 
 Phase 3.3 — deterministic retries and typed errors.

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 |
@@ -289,6 +314,34 @@ Useful for "audition before download" and for CI that shouldn't pull full tracks
 | `data`     |   Yes    | `buffer` | downloaded song buffer |
 | `song_id`  |   Yes    | `string` |               track id |
 
+### Streaming download
+
+For large files / high concurrency — peak memory is ~one 2048-byte stripe
+instead of 2× the file.
+
+- **`streamTrackDownload(track, quality, options?)`** → `{stream, size, startedAt, isEncrypted}`.
+  `stream` is decrypted audio bytes (`get_url` → CDN fetch → stripe-decrypt
+  `Transform` → your sink). `options.onProgress(received, total)`;
+  `options.resumeFrom` (bytes, rounded down to a 2048 boundary) sends a `Range`
+  header and resumes stripe-decryption in phase.
+- **`createDecryptStream(sngId, startChunk?)`** → a `Transform` for your own `pipeline`.
+- **`getStream(url, {rangeStart?})`** → `{stream, headers, status}` — a raw,
+  content-decoded response stream.
+
+```js
+import {pipeline} from 'stream/promises';
+import {createWriteStream} from 'fs';
+
+const {stream} = await streamTrackDownload(track, 9, {
+  onProgress: (got, total) => process.stdout.write(`\r${((got / total) * 100) | 0}%`),
+});
+await pipeline(stream, createWriteStream('track.flac'));
+```
+
+Streaming the **tag write** (rewriting the FLAC metadata block in place, no
+full-file `Buffer.concat`) is not done yet — buffer the result and call
+`addTrackTags`, or tag the file afterward.
+
 ### `.addTrackTags(data, track, options?)`
 
 Resolves album info, credits, lyrics and artwork from Deezer and writes them into

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/index.d.ts

@@ -5,5 +5,7 @@ export * from './api';
 export * from './converter';
 export * from './lib/decrypt';
 export * from './lib/get-url';
-export { httpAgent, httpsAgent, getBuffer, getJson, getText } from './lib/http';
+export * from './lib/stream-download';
+export { httpAgent, httpsAgent, getBuffer, getJson, getText, getStream } from './lib/http';
+export type { StreamResponse } from './lib/http';
 export * from './metadata-writer';

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getText = exports.getJson = exports.getBuffer = exports.httpsAgent = exports.httpAgent = exports.DeezerError = exports.RETRY_POLICY = exports.initDeezerApi = void 0;
+exports.getStream = exports.getText = exports.getJson = exports.getBuffer = exports.httpsAgent = exports.httpAgent = exports.DeezerError = exports.RETRY_POLICY = exports.initDeezerApi = void 0;
 var request_1 = require("./lib/request");
 Object.defineProperty(exports, "initDeezerApi", { enumerable: true, get: function () { return request_1.initDeezerApi; } });
 Object.defineProperty(exports, "RETRY_POLICY", { enumerable: true, get: function () { return request_1.RETRY_POLICY; } });
@@ -24,10 +24,12 @@ __exportStar(require("./api"), exports);
 __exportStar(require("./converter"), exports);
 __exportStar(require("./lib/decrypt"), exports);
 __exportStar(require("./lib/get-url"), exports);
+__exportStar(require("./lib/stream-download"), exports);
 var http_1 = require("./lib/http");
 Object.defineProperty(exports, "httpAgent", { enumerable: true, get: function () { return http_1.httpAgent; } });
 Object.defineProperty(exports, "httpsAgent", { enumerable: true, get: function () { return http_1.httpsAgent; } });
 Object.defineProperty(exports, "getBuffer", { enumerable: true, get: function () { return http_1.getBuffer; } });
 Object.defineProperty(exports, "getJson", { enumerable: true, get: function () { return http_1.getJson; } });
 Object.defineProperty(exports, "getText", { enumerable: true, get: function () { return http_1.getText; } });
+Object.defineProperty(exports, "getStream", { enumerable: true, get: function () { return http_1.getStream; } });
 __exportStar(require("./metadata-writer"), exports);

package/dist/lib/decrypt.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+import { Transform } from 'stream';
 import type { trackType } from '../types';
 export declare const getSongFileName: ({ MD5_ORIGIN, SNG_ID, MEDIA_VERSION }: trackType, quality: number) => string;
 /**
@@ -19,9 +20,21 @@ export declare class TrackDecryptStream {
     private readonly bf;
     private carry;
     private chunkIndex;
-    constructor(trackId: string);
+    /**
+     * @param trackId    `SNG_ID`
+     * @param startChunk the 2048-byte chunk index the first byte you'll `write()`
+     *                   corresponds to — non-zero when resuming a `Range` download
+     *                   (`resumeFromByte / 2048`). Per-chunk IVs make this exact.
+     */
+    constructor(trackId: string, startChunk?: number);
     /** Returns the decrypted bytes for every complete 2048-byte stripe now available. */
     write(part: Buffer): Buffer;
     /** The trailing partial chunk (always plaintext). */
     final(): Buffer;
 }
+/**
+ * A Node `Transform` that decrypts a Deezer download stripe-by-stripe as bytes
+ * flow through it — `fetch(url) → createDecryptStream(sngId) → sink`, constant
+ * memory. `startChunk` (`resumeFromByte / 2048`) supports resumed `Range` fetches.
+ */
+export declare const createDecryptStream: (trackId: string, startChunk?: number) => Transform;

package/dist/lib/decrypt.js

@@ -3,8 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TrackDecryptStream = exports.decryptDownload = exports.getSongFileName = void 0;
+exports.createDecryptStream = exports.TrackDecryptStream = exports.decryptDownload = exports.getSongFileName = void 0;
 const crypto_1 = __importDefault(require("crypto"));
+const stream_1 = require("stream");
 const blowfish_1 = require("./blowfish");
 const md5 = (data, type = 'ascii') => {
     const md5sum = crypto_1.default.createHash('md5');
@@ -66,10 +67,16 @@ exports.decryptDownload = decryptDownload;
  * and the CPU work hides behind the (slower) network read.
  */
 class TrackDecryptStream {
-    constructor(trackId) {
+    /**
+     * @param trackId    `SNG_ID`
+     * @param startChunk the 2048-byte chunk index the first byte you'll `write()`
+     *                   corresponds to — non-zero when resuming a `Range` download
+     *                   (`resumeFromByte / 2048`). Per-chunk IVs make this exact.
+     */
+    constructor(trackId, startChunk = 0) {
         this.carry = Buffer.alloc(0);
-        this.chunkIndex = 0;
         this.bf = new blowfish_1.Blowfish(getBlowfishKey(trackId));
+        this.chunkIndex = startChunk;
     }
     /** Returns the decrypted bytes for every complete 2048-byte stripe now available. */
     write(part) {
@@ -100,3 +107,25 @@ class TrackDecryptStream {
     }
 }
 exports.TrackDecryptStream = TrackDecryptStream;
+/**
+ * A Node `Transform` that decrypts a Deezer download stripe-by-stripe as bytes
+ * flow through it — `fetch(url) → createDecryptStream(sngId) → sink`, constant
+ * memory. `startChunk` (`resumeFromByte / 2048`) supports resumed `Range` fetches.
+ */
+const createDecryptStream = (trackId, startChunk = 0) => {
+    const engine = new TrackDecryptStream(trackId, startChunk);
+    return new stream_1.Transform({
+        transform(chunk, _enc, cb) {
+            try {
+                cb(null, engine.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+            }
+            catch (err) {
+                cb(err);
+            }
+        },
+        flush(cb) {
+            cb(null, engine.final());
+        },
+    });
+};
+exports.createDecryptStream = createDecryptStream;

package/dist/lib/http.d.ts

@@ -1,8 +1,10 @@
 /// <reference types="node" />
 /// <reference types="node" />
 /// <reference types="node" />
+/// <reference types="node" />
 import { Agent as HttpAgent, IncomingHttpHeaders } from 'http';
 import { Agent as HttpsAgent } from 'https';
+import { Readable } from 'stream';
 type HttpMethod = 'GET' | 'POST' | 'HEAD';
 type ResponseType = 'buffer' | 'json' | 'text';
 type QueryValue = string | number | boolean | null | undefined;
@@ -63,6 +65,21 @@ export declare class HttpClient {
     head(url: string, config?: Omit<HttpRequestConfig, 'responseType'>): Promise<HttpResponse<Buffer>>;
     private request;
 }
+export interface StreamResponse {
+    /** the response body as a Readable — content-decoded (gzip/br/deflate unwrapped) */
+    stream: Readable;
+    headers: IncomingHttpHeaders;
+    status: number;
+    /** the final URL after redirects */
+    url: string;
+}
+/**
+ * Stream a URL's body (for large downloads — constant memory). Optionally send a
+ * `Range` header to resume from `rangeStart` bytes.
+ */
+export declare const getStream: (url: string, config?: HttpRequestConfig & {
+    rangeStart?: number;
+}) => Promise<StreamResponse>;
 export declare const getBuffer: (url: string, config?: HttpRequestConfig) => Promise<Buffer>;
 export declare const getJson: <T = unknown>(url: string, config?: HttpRequestConfig) => Promise<T>;
 export declare const getText: (url: string, config?: HttpRequestConfig) => Promise<string>;

package/dist/lib/http.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.headRequest = exports.getText = exports.getJson = exports.getBuffer = exports.HttpClient = exports.HttpStatusError = exports.httpsAgent = exports.httpAgent = void 0;
+exports.headRequest = exports.getText = exports.getJson = exports.getBuffer = exports.getStream = exports.HttpClient = exports.HttpStatusError = exports.httpsAgent = exports.httpAgent = void 0;
 const http_1 = require("http");
 const https_1 = require("https");
 const zlib_1 = require("zlib");
@@ -172,6 +172,80 @@ const requestRaw = async (config, redirectCount = 0) => {
         req.end();
     });
 };
+/**
+ * Like a GET, but resolves with the response **stream** instead of a buffered
+ * body — for large downloads that should not sit in memory. Follows redirects;
+ * rejects with `HttpStatusError` on a non-2xx (buffering only the small error
+ * body). The caller owns the returned stream and must consume or destroy it.
+ */
+const streamRaw = async (config, redirectCount = 0) => {
+    const requestUrl = buildUrl(config.url, config.baseURL, config.params);
+    const headers = normalizeHeaders(config.headers);
+    return await new Promise((resolve, reject) => {
+        var _a;
+        const isHttps = requestUrl.protocol === 'https:';
+        const requestFn = isHttps ? https_1.request : http_1.request;
+        const req = requestFn({
+            agent: isHttps ? exports.httpsAgent : exports.httpAgent,
+            headers,
+            hostname: requestUrl.hostname,
+            method: 'GET',
+            path: requestUrl.pathname + requestUrl.search,
+            port: requestUrl.port,
+            protocol: requestUrl.protocol,
+        }, (response) => {
+            var _a, _b, _c;
+            const status = (_a = response.statusCode) !== null && _a !== void 0 ? _a : 0;
+            const locationHeader = response.headers.location;
+            const location = Array.isArray(locationHeader) ? locationHeader[0] : locationHeader;
+            if (location && isRedirectStatus(status) && redirectCount < ((_b = config.maxRedirects) !== null && _b !== void 0 ? _b : 5)) {
+                response.resume();
+                streamRaw({ ...config, baseURL: undefined, url: new URL(location, requestUrl).toString() }, redirectCount + 1)
+                    .then(resolve)
+                    .catch(reject);
+                return;
+            }
+            if (status < 200 || status >= 300) {
+                const chunks = [];
+                response.on('data', (c) => chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c)));
+                response.on('end', () => reject(new HttpStatusError(status, response.headers, Buffer.concat(chunks))));
+                response.on('error', reject);
+                return;
+            }
+            const encoding = String((_c = response.headers['content-encoding']) !== null && _c !== void 0 ? _c : '').toLowerCase();
+            let stream = response;
+            if (encoding === 'gzip') {
+                stream = response.pipe((0, zlib_1.createGunzip)());
+            }
+            else if (encoding === 'br') {
+                stream = response.pipe((0, zlib_1.createBrotliDecompress)());
+            }
+            else if (encoding === 'deflate') {
+                stream = response.pipe((0, zlib_1.createInflate)());
+            }
+            response.on('error', (err) => stream.destroy(err));
+            resolve({ stream, headers: response.headers, status, url: requestUrl.toString() });
+        });
+        req.on('error', reject);
+        req.setTimeout((_a = config.timeout) !== null && _a !== void 0 ? _a : 30000, () => {
+            var _a;
+            req.destroy(new Error(`Request timed out after ${(_a = config.timeout) !== null && _a !== void 0 ? _a : 30000}ms`));
+        });
+        req.end();
+    });
+};
+/**
+ * Stream a URL's body (for large downloads — constant memory). Optionally send a
+ * `Range` header to resume from `rangeStart` bytes.
+ */
+const getStream = async (url, config = {}) => {
+    const headers = { ...config.headers };
+    if (config.rangeStart && config.rangeStart > 0) {
+        headers.Range = `bytes=${config.rangeStart}-`;
+    }
+    return streamRaw({ url, headers, params: config.params, timeout: config.timeout });
+};
+exports.getStream = getStream;
 const buildUrl = (url, baseURL, params) => {
     const parsedUrl = new URL(resolveUrl(url, baseURL));
     if (params) {

package/dist/lib/stream-download.d.ts

@@ -0,0 +1,37 @@
+/// <reference types="node" />
+import { Readable } from 'stream';
+import type { trackType } from '../types';
+export interface StreamTrackOptions {
+    /**
+     * Resume from this many bytes already on disk. Rounded **down** to a 2048-byte
+     * boundary so stripe decryption stays aligned; the returned `startedAt` tells
+     * you where the stream actually begins.
+     */
+    resumeFrom?: number;
+    /** progress callback — `(bytesReceived, totalBytes)`; `total` is 0 when unknown */
+    onProgress?: (received: number, total: number) => void;
+}
+export interface TrackStream {
+    /** decrypted audio bytes, ready to pipe to a file or a tag muxer */
+    stream: Readable;
+    /** total size of the (decrypted) file in bytes, or 0 if Deezer didn't say */
+    size: number;
+    /** byte offset the stream starts at (0, or the aligned `resumeFrom`) */
+    startedAt: number;
+    /** `false` for `cipher: NONE` content — the stream is the raw file */
+    isEncrypted: boolean;
+}
+/**
+ * Download a track as a **stream** of decrypted audio — `get_url` → CDN fetch →
+ * stripe-decrypt transform → your sink. Peak memory is ~one 2048-byte stripe
+ * regardless of file size or how many run concurrently.
+ *
+ * Buffer-and-tag still works: `pipeline(ts.stream, fs.createWriteStream(tmp))`,
+ * then read the temp file back for `addTrackTags`. Streaming the tag write
+ * itself (especially FLAC) is not done yet.
+ *
+ * @throws the same `WrongLicense` / `GeoBlocked` / `ExpiredTrackToken` /
+ *   `DeezerError` as `getTrackDownloadUrl`, plus `Error('unavailable')` when the
+ *   track+quality can't be resolved at all.
+ */
+export declare const streamTrackDownload: (track: trackType, quality: number, options?: StreamTrackOptions) => Promise<TrackStream>;

package/dist/lib/stream-download.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.streamTrackDownload = void 0;
+const stream_1 = require("stream");
+const decrypt_1 = require("./decrypt");
+const http_1 = require("./http");
+const get_url_1 = require("./get-url");
+const CHUNK = 2048;
+/**
+ * Download a track as a **stream** of decrypted audio — `get_url` → CDN fetch →
+ * stripe-decrypt transform → your sink. Peak memory is ~one 2048-byte stripe
+ * regardless of file size or how many run concurrently.
+ *
+ * Buffer-and-tag still works: `pipeline(ts.stream, fs.createWriteStream(tmp))`,
+ * then read the temp file back for `addTrackTags`. Streaming the tag write
+ * itself (especially FLAC) is not done yet.
+ *
+ * @throws the same `WrongLicense` / `GeoBlocked` / `ExpiredTrackToken` /
+ *   `DeezerError` as `getTrackDownloadUrl`, plus `Error('unavailable')` when the
+ *   track+quality can't be resolved at all.
+ */
+const streamTrackDownload = async (track, quality, options = {}) => {
+    const resolved = await (0, get_url_1.getTrackDownloadUrl)(track, quality);
+    if (!resolved) {
+        throw new Error(`Track ${track.SNG_ID} is unavailable at quality ${quality}`);
+    }
+    const startedAt = options.resumeFrom ? Math.floor(options.resumeFrom / CHUNK) * CHUNK : 0;
+    const { stream: raw, headers } = await (0, http_1.getStream)(resolved.trackUrl, { rangeStart: startedAt });
+    const contentLength = Number(headers['content-length']) || 0;
+    const size = resolved.fileSize || (contentLength ? contentLength + startedAt : 0);
+    let received = startedAt;
+    if (options.onProgress) {
+        const meter = new stream_1.PassThrough();
+        raw.on('data', (c) => {
+            var _a;
+            received += c.length;
+            (_a = options.onProgress) === null || _a === void 0 ? void 0 : _a.call(options, received, size);
+        });
+        raw.pipe(meter);
+        return {
+            stream: resolved.isEncrypted ? meter.pipe((0, decrypt_1.createDecryptStream)(track.SNG_ID, startedAt / CHUNK)) : meter,
+            size,
+            startedAt,
+            isEncrypted: resolved.isEncrypted,
+        };
+    }
+    return {
+        stream: resolved.isEncrypted ? raw.pipe((0, decrypt_1.createDecryptStream)(track.SNG_ID, startedAt / CHUNK)) : raw,
+        size,
+        startedAt,
+        isEncrypted: resolved.isEncrypted,
+    };
+};
+exports.streamTrackDownload = streamTrackDownload;

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.4.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