q-fi-core 2.3.1

package/CHANGELOG.md

@@ -0,0 +1,109 @@
+# Changelog
+
+## 2.3.1 - 2026-08-30
+
+### Changed
+
+- Renamed the package from `@soulwax/d-fi-core` to the unscoped **`q-fi-core`** ("q" = quality). No API changes. Update imports from `@soulwax/d-fi-core` → `q-fi-core` and `@soulwax/d-fi-core/types` → `q-fi-core/types`.
+
+## 2.3.0 - 2026-05-28
+
+### Changed
+
+- Completed the Tier 3 performance rollup for the core release line.
+- Reused HTTP connections, removed the common media URL HEAD probe, optimized decrypt buffer handling, and avoided redundant metadata writer buffer wrapping.
+
+## 2.2.5 - 2026-05-28
+
+### Changed
+
+- Avoided redundant output buffer wrapping in FLAC and MP3 metadata writers.
+
+## 2.2.4 - 2026-05-28
+
+### Changed
+
+- Reworked encrypted audio decryption to copy buffers directly instead of round-tripping chunks through binary strings.
+
+## 2.2.3 - 2026-05-28
+
+### Changed
+
+- Skipped the extra HEAD size probe for media-server download URLs and reused track metadata for the reported size.
+
+## 2.2.2 - 2026-05-28
+
+### Changed
+
+- Reused HTTP and HTTPS connections with shared keep-alive agents in the internal transport.
+
+## 2.2.1 - 2026-05-28
+
+### Changed
+
+- Cleanup.
+
+## 2.2.0 - 2026-04-01
+
+### Changed
+
+- Promoted the transport migration to the next minor publish line for `q-fi-core`, keeping the scoped package metadata and published `types/` subpath aligned for npm consumers.
+- Reused Spotify anonymous tokens until expiry so Spotify URL parsing does not refetch a token on every request during a single process lifetime.
+- Documented direct type imports from `q-fi-core/types` in the README for downstream TypeScript consumers.
+
+### Fixed
+
+- Stabilized live AVA coverage by explicitly skipping auth-gated and upstream-unavailable fixtures instead of failing the full publish verification run.
+- Excluded shared test helpers from AVA discovery so release validation exits cleanly with the real test status.
+
+## 2.1.0 - 2026-04-01
+
+### Changed
+
+- Removed the `axios` dependency in favor of an internal Node HTTP client with explicit JSON, text, binary, timeout, and redirect handling.
+- Kept Deezer, Tidal, Spotify, YouTube, artwork, and Musixmatch requests on the same public library surface while making the transport layer dependency-light for publish.
+- Updated the README download example and integration tests to use buffer-safe native Node networking instead of axios.
+- Added a published `types/` subpath so consumers can resolve shared declarations from `q-fi-core/types`.
+
+### Fixed
+
+- Preserved binary downloads for encrypted audio, artwork, and test fixtures without relying on axios `arraybuffer` semantics.
+- Preserved Deezer gateway retry behavior for auth refresh, gateway token refresh, and rate-limit backoff after the transport migration.
+
+## 2.0.2 - 2026-03-26
+
+### Changed
+
+- Added an explicit npm package page link to the README for `q-fi-core`.
+- Made the release lint scripts use the nested package's own ESLint config and plugin resolution.
+
+### Fixed
+
+- Published a fresh patch release so the scoped package page reflects the current package metadata and README content.
+
+## 2.0.1 - 2026-03-26
+
+### Changed
+
+- Updated the npm license metadata to use a valid `SEE LICENSE IN LICENSE` expression.
+
+### Fixed
+
+- Corrected the README download example to use `trackData.trackUrl`.
+- Aligned the README copyright and license note with the repository's current LICENSE file.
+- Updated package ownership metadata to identify Christian Kling as the main developer.
+
+## 2.0.0 - 2026-03-26
+
+### Changed
+
+- Renamed the npm package to `q-fi-core`.
+- Updated package metadata to use the GitHub repository at `https://github.com/soulwax/q-fi-core`.
+- Limited published npm package contents to runtime artifacts and release metadata.
+- Moved the publish build hook to `prepublishOnly` so registry publishing no longer depends on install-time build behavior.
+
+### Fixed
+
+- Updated README and docs examples to use the scoped package name for install and import statements.
+- Replaced the README FAQ link with a repository-local path so it follows the current default branch automatically.
+- Allowed publish-time linting to work on Windows checkouts without normalizing the entire repository to LF first.

package/LICENSE

@@ -0,0 +1 @@
+# Copyright Christian Kling 2024

package/README.md

@@ -0,0 +1,186 @@
+# q-fi-core
+
+q-fi (the **q** is for **quality**; formerly `d-fi`) is a streaming music downloader. This core module is designed to be used on future version of hexmusic, dabox server cluster and other services.
+The source repository lives at <https://github.com/soulwax/q-fi-core>, and the npm package is published as `q-fi-core`.
+The npm package page is <https://www.npmjs.com/package/q-fi-core>.
+
+## Installation
+
+```bash
+npm i q-fi-core
+```
+
+```bash
+yarn add q-fi-core
+```
+
+```bash
+pnpm add q-fi-core
+```
+
+Type declarations are also published under the `q-fi-core/types` subpath for consumers that want to import the shared library types directly.
+
+## Usage
+
+Here's a simple example to download tracks.
+
+```ts
+import fs from 'fs';
+import {get} from 'https';
+import * as api from 'q-fi-core';
+
+const downloadBuffer = (url: string) =>
+  new Promise<Buffer>((resolve, reject) => {
+    get(url, (response) => {
+      const chunks: Buffer[] = [];
+      response.on('data', (chunk) => chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)));
+      response.on('end', () => resolve(Buffer.concat(chunks)));
+      response.on('error', reject);
+    }).on('error', reject);
+  });
+
+// Init api with arl from cookie
+await api.initDeezerApi(arl_cookie);
+
+// Verify user
+try {
+  const user = await api.getUser();
+  // Successfully logged in
+  console.log('Logged in as ' + user.BLOG_NAME);
+} catch (err) {
+  // Invalid arl cookie set
+  console.error(err.message);
+}
+
+// GET Track Object
+const track = await api.getTrackInfo(song_id);
+
+// Parse download URL for 128kbps
+const trackData = await api.getTrackDownloadUrl(track, 1);
+
+// Download track
+const data = await downloadBuffer(trackData.trackUrl);
+
+// Decrypt track if needed
+const outFile = trackData.isEncrypted ? api.decryptDownload(data, track.SNG_ID) : data;
+
+// Add id3 metadata
+const trackWithMetadata = await api.addTrackTags(outFile, track, 500);
+
+// Save file to disk
+fs.writeFileSync(track.SNG_TITLE + '.mp3', trackWithMetadata);
+```
+
+### [Read FAQ](docs/faq.md)
+
+## Methods
+
+All method returns `Object` or throws `Error`. Make sure to catch error on your side.
+
+### `.initDeezerApi(arl_cookie);`
+
+> It is recommended that you first init the app with this method using your arl cookie.
+
+| Parameters   | Required |     Type |
+| ------------ | :------: | -------: |
+| `arl_cookie` |   Yes    | `string` |
+
+### `.getTrackInfo(track_id);`
+
+| Parameters | Required |     Type |
+| ---------- | :------: | -------: |
+| `track_id` |   Yes    | `string` |
+
+### `.getLyrics(track_id);`
+
+| Parameters | Required |     Type |
+| ---------- | :------: | -------: |
+| `track_id` |   Yes    | `string` |
+
+### `.getAlbumInfo(album_id);`
+
+| Parameters | Required |     Type |
+| ---------- | :------: | -------: |
+| `album_id` |   Yes    | `string` |
+
+### `.getAlbumTracks(album_id);`
+
+| Parameters | Required |     Type |
+| ---------- | :------: | -------: |
+| `album_id` |   Yes    | `string` |
+
+### `.getPlaylistInfo(playlist_id);`
+
+| Parameters    | Required |     Type |
+| ------------- | :------: | -------: |
+| `playlist_id` |   Yes    | `string` |
+
+### `.getPlaylistTracks(playlist_id);`
+
+| Parameters    | Required |     Type |
+| ------------- | :------: | -------: |
+| `playlist_id` |   Yes    | `string` |
+
+### `.getArtistInfo(artist_id);`
+
+| Parameters  | Required |     Type |
+| ----------- | :------: | -------: |
+| `artist_id` |   Yes    | `string` |
+
+### `.getDiscography(artist_id, limit);`
+
+| Parameters  | Required |     Type | Default |             Description |
+| ----------- | :------: | -------: | ------: | ----------------------: |
+| `artist_id` |   Yes    | `string` |       - |               artist id |
+| `limit`     |    No    | `number` |     500 | maximum tracks to fetch |
+
+### `.getProfile(user_id);`
+
+| Parameters | Required |     Type |
+| ---------- | :------: | -------: |
+| `user_id`  |   Yes    | `string` |
+
+### `.searchAlternative(artist_name, song_name);`
+
+| Parameters    | Required |     Type |
+| ------------- | :------: | -------: |
+| `artist_name` |   Yes    | `string` |
+| `song_name`   |   Yes    | `string` |
+
+### `.searchMusic(query, types, limit);`
+
+| Parameters | Required |     Type |   Default |                     Description |
+| ---------- | :------: | -------: | --------: | ------------------------------: |
+| `query`    |   Yes    | `string` |         - |                    search query |
+| `types`    |    No    |  `array` | ['TRACK'] |           array of search types |
+| `limit`    |    No    | `number` |        15 | maximum item to fetch per types |
+
+### `.getTrackDownloadUrl(track, quality);`
+
+| Parameters | Required |        Type |                        Description |
+| ---------- | :------: | ----------: | ---------------------------------: |
+| `track`    |   Yes    |    `string` |                       track object |
+| `quality`  |   Yes    | `1, 3 or 9` | 1 = 128kbps, 3 = 320kbps, 9 = flac |
+
+### `.decryptDownload(data, song_id);`
+
+| Parameters | Required |     Type |            Description |
+| ---------- | :------: | -------: | ---------------------: |
+| `data`     |   Yes    | `buffer` | downloaded song buffer |
+| `song_id`  |   Yes    | `string` |               track id |
+
+### `.addTrackTags(data, track,coverSize)`
+
+| Parameters  | Required |      Type |            Description |
+| ----------- | :------: | --------: | ---------------------: |
+| `data`      |   Yes    |  `buffer` | downloaded song buffer |
+| `track`     |   Yes    |  `string` |           track object |
+| `coverSize` |    No    | `56-1800` |         cover art size |
+
+###
+
+> We are not responsible for any misuse of this library by any third party. Please make sure to respect the artists and the music industry when using this library.
+
+> Made with :heart: by the Bluesix Team. If you want to contribute, please read the [contributing guidelines](.github/CONTRIBUTING.md) first.
+
+Copyright © 2026 Christian Kling, Saskia Falkenhagen, Jens Arnolds

package/dist/api/api.d.ts

@@ -0,0 +1,78 @@
+import type { albumType, trackType, lyricsType, albumTracksType, showType, playlistInfo, playlistTracksType, playlistChannelType, channelSearchType, artistInfoType, discographyType, profileType, searchType, trackTypePublicApi, albumTypePublicApi, userType } from '../types';
+/**
+ * @param {String} sng_id song id
+ */
+export declare const getTrackInfoPublicApi: (sng_id: string) => Promise<trackTypePublicApi>;
+/**
+ * @param {String} alb_id album id
+ */
+export declare const getAlbumInfoPublicApi: (alb_id: string) => Promise<albumTypePublicApi>;
+/**
+ * @param {String} sng_id song id
+ */
+export declare const getTrackInfo: (sng_id: string) => Promise<trackType>;
+/**
+ * @param {String} sng_id song id
+ */
+export declare const getLyrics: (sng_id: string) => Promise<lyricsType>;
+/**
+ * @param {String} alb_id album id
+ */
+export declare const getAlbumInfo: (alb_id: string) => Promise<albumType>;
+/**
+ * @param {String} alb_id user id
+ */
+export declare const getAlbumTracks: (alb_id: string) => Promise<albumTracksType>;
+/**
+ * @param {String} playlist_id playlist id
+ */
+export declare const getPlaylistInfo: (playlist_id: string) => Promise<playlistInfo>;
+/**
+ * @param {String} playlist_id playlist id
+ */
+export declare const getPlaylistTracks: (playlist_id: string) => Promise<playlistTracksType>;
+/**
+ * @param {String} art_id artist id
+ */
+export declare const getArtistInfo: (art_id: string) => Promise<artistInfoType>;
+/**
+ * @param {String} art_id artist id
+ * @param {String} nb number of total song to fetch
+ */
+export declare const getDiscography: (art_id: string, nb?: number) => Promise<discographyType>;
+/**
+ * @param {String} user_id user id
+ */
+export declare const getProfile: (user_id: string) => Promise<profileType>;
+/**
+ * @param {String} artist artist name
+ * @param {String} song song name
+ * @param {String} nb number of items to fetch
+ */
+export declare const searchAlternative: (artist: string, song: string, nb?: number) => Promise<searchType>;
+type searchTypesProp = 'ALBUM' | 'ARTIST' | 'TRACK' | 'PLAYLIST' | 'RADIO' | 'SHOW' | 'USER' | 'LIVESTREAM' | 'CHANNEL';
+/**
+ * @param {String} query search query
+ * @param {Array} types search types
+ * @param {Number} nb number of items to fetch
+ */
+export declare const searchMusic: (query: string, types?: searchTypesProp[], nb?: number) => Promise<searchType>;
+/**
+ * Get details about current user
+ */
+export declare const getUser: () => Promise<userType>;
+/**
+ * Get list of channles
+ */
+export declare const getChannelList: () => Promise<channelSearchType>;
+/**
+ * @param {String} SHOW_ID show id
+ * @param {Number} NB number of items to fetch
+ * @param {Number} START start index
+ */
+export declare const getShowInfo: (SHOW_ID: string, NB?: number, START?: number) => Promise<showType>;
+/**
+ * Get details about a playlist channel
+ */
+export declare const getPlaylistChannel: (page: string) => Promise<playlistChannelType>;
+export {};

package/dist/api/api.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPlaylistChannel = exports.getShowInfo = exports.getChannelList = exports.getUser = exports.searchMusic = exports.searchAlternative = exports.getProfile = exports.getDiscography = exports.getArtistInfo = exports.getPlaylistTracks = exports.getPlaylistInfo = exports.getAlbumTracks = exports.getAlbumInfo = exports.getLyrics = exports.getTrackInfo = exports.getAlbumInfoPublicApi = exports.getTrackInfoPublicApi = void 0;
+const request_1 = require("./request");
+/**
+ * @param {String} sng_id song id
+ */
+const getTrackInfoPublicApi = (sng_id) => (0, request_1.requestPublicApi)('/track/' + sng_id);
+exports.getTrackInfoPublicApi = getTrackInfoPublicApi;
+/**
+ * @param {String} alb_id album id
+ */
+const getAlbumInfoPublicApi = (alb_id) => (0, request_1.requestPublicApi)('/album/' + alb_id);
+exports.getAlbumInfoPublicApi = getAlbumInfoPublicApi;
+/**
+ * @param {String} sng_id song id
+ */
+const getTrackInfo = (sng_id) => (0, request_1.request)({ sng_id }, 'song.getData');
+exports.getTrackInfo = getTrackInfo;
+/**
+ * @param {String} sng_id song id
+ */
+const getLyrics = (sng_id) => (0, request_1.request)({ sng_id }, 'song.getLyrics');
+exports.getLyrics = getLyrics;
+/**
+ * @param {String} alb_id album id
+ */
+const getAlbumInfo = (alb_id) => (0, request_1.request)({ alb_id }, 'album.getData');
+exports.getAlbumInfo = getAlbumInfo;
+/**
+ * @param {String} alb_id user id
+ */
+const getAlbumTracks = async (alb_id) => (0, request_1.request)({ alb_id, lang: 'us', nb: -1 }, 'song.getListByAlbum');
+exports.getAlbumTracks = getAlbumTracks;
+/**
+ * @param {String} playlist_id playlist id
+ */
+const getPlaylistInfo = (playlist_id) => (0, request_1.request)({ playlist_id, lang: 'en' }, 'playlist.getData');
+exports.getPlaylistInfo = getPlaylistInfo;
+/**
+ * @param {String} playlist_id playlist id
+ */
+const getPlaylistTracks = async (playlist_id) => {
+    const playlistTracks = await (0, request_1.request)({ playlist_id, lang: 'en', nb: -1, start: 0, tab: 0, tags: true, header: true }, 'playlist.getSongs');
+    playlistTracks.data = playlistTracks.data.map((track, index) => {
+        track.TRACK_POSITION = index + 1;
+        return track;
+    });
+    return playlistTracks;
+};
+exports.getPlaylistTracks = getPlaylistTracks;
+/**
+ * @param {String} art_id artist id
+ */
+const getArtistInfo = (art_id) => (0, request_1.request)({ art_id, filter_role_id: [0], lang: 'en', tab: 0, nb: -1, start: 0 }, 'artist.getData');
+exports.getArtistInfo = getArtistInfo;
+/**
+ * @param {String} art_id artist id
+ * @param {String} nb number of total song to fetch
+ */
+const getDiscography = (art_id, nb = 500) => (0, request_1.request)({ art_id, filter_role_id: [0], lang: 'en', nb, nb_songs: -1, start: 0 }, 'album.getDiscography');
+exports.getDiscography = getDiscography;
+/**
+ * @param {String} user_id user id
+ */
+const getProfile = (user_id) => (0, request_1.request)({ user_id, tab: 'loved', nb: -1 }, 'mobile.pageUser');
+exports.getProfile = getProfile;
+/**
+ * @param {String} artist artist name
+ * @param {String} song song name
+ * @param {String} nb number of items to fetch
+ */
+const searchAlternative = (artist, song, nb = 10) => (0, request_1.request)({
+    query: `artist:'${artist}' track:'${song}'`,
+    types: ['TRACK'],
+    nb,
+}, 'mobile_suggest');
+exports.searchAlternative = searchAlternative;
+/**
+ * @param {String} query search query
+ * @param {Array} types search types
+ * @param {Number} nb number of items to fetch
+ */
+const searchMusic = (query, types = ['TRACK'], nb = 15) => (0, request_1.requestLight)({ query, start: 0, nb, suggest: true, artist_suggest: true, top_tracks: true }, 'deezer.pageSearch');
+exports.searchMusic = searchMusic;
+/**
+ * Get details about current user
+ */
+const getUser = async () => (0, request_1.requestGet)('user_getInfo');
+exports.getUser = getUser;
+/**
+ * Get list of channles
+ */
+const getChannelList = async () => (0, request_1.request)({}, 'search_getChannels');
+exports.getChannelList = getChannelList;
+/**
+ * @param {String} SHOW_ID show id
+ * @param {Number} NB number of items to fetch
+ * @param {Number} START start index
+ */
+const getShowInfo = (SHOW_ID, NB = 1000, START = 0) => (0, request_1.request)({
+    SHOW_ID,
+    NB,
+    START,
+}, 'mobile.pageShow');
+exports.getShowInfo = getShowInfo;
+/**
+ * Get details about a playlist channel
+ */
+const getPlaylistChannel = async (page) => {
+    const gateway_input = {
+        page,
+        version: '2.3',
+        support: {
+            'long-card-horizontal-grid': ['album', 'playlist', 'radio', 'show'],
+            ads: [],
+            message: [],
+            highlight: ['generic', 'album', 'artist', 'playlist', 'radio', 'app'],
+            'deeplink-list': ['generic', 'deeplink'],
+            grid: [
+                'generic',
+                'album',
+                'artist',
+                'playlist',
+                'radio',
+                'channel',
+                'show',
+                'page',
+                'smarttracklist',
+                'flow',
+                'video-link',
+            ],
+            slideshow: ['album', 'artist', 'playlist', 'radio', 'show', 'channel', 'video-link', 'external-link'],
+            'large-card': ['generic', 'album', 'artist', 'playlist', 'radio', 'show', 'external-link', 'video-link'],
+            'item-highlight': ['radio', 'app'],
+            'small-horizontal-grid': ['album', 'artist', 'playlist', 'radio', 'channel', 'show'],
+            'grid-preview-two': [
+                'generic',
+                'album',
+                'artist',
+                'playlist',
+                'radio',
+                'channel',
+                'show',
+                'page',
+                'smarttracklist',
+                'flow',
+                'video-link',
+            ],
+            list: ['generic', 'album', 'artist', 'playlist', 'radio', 'show', 'video-link', 'channel', 'episode'],
+            'grid-preview-one': [
+                'generic',
+                'album',
+                'artist',
+                'playlist',
+                'radio',
+                'channel',
+                'show',
+                'page',
+                'smarttracklist',
+                'flow',
+                'video-link',
+            ],
+            'horizontal-grid': [
+                'generic',
+                'album',
+                'artist',
+                'playlist',
+                'radio',
+                'channel',
+                'show',
+                'video-link',
+                'smarttracklist',
+                'flow',
+            ],
+        },
+        lang: 'en',
+        timezone_offset: '6',
+    };
+    return await (0, request_1.requestGet)('app_page_get', { gateway_input }, page);
+};
+exports.getPlaylistChannel = getPlaylistChannel;

package/dist/api/cache.d.ts

@@ -0,0 +1,3 @@
+import FastLRU from '../lib/fast-lru';
+declare const lru: FastLRU;
+export default lru;

package/dist/api/cache.js

@@ -0,0 +1,12 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fast_lru_1 = __importDefault(require("../lib/fast-lru"));
+// Expire cache in 60 minutes
+const lru = new fast_lru_1.default({
+    maxSize: 1000,
+    ttl: 60 * 60000,
+});
+exports.default = lru;

package/dist/api/index.d.ts

@@ -0,0 +1,2 @@
+export * from './api';
+export * from './request';

package/dist/api/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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 });
+__exportStar(require("./api"), exports);
+__exportStar(require("./request"), exports);

package/dist/api/request.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Make POST requests to deezer api
+ * @param {Object} body post body
+ * @param {String} method request method
+ */
+export declare const request: (body: object, method: string) => Promise<any>;
+/**
+ * Make POST requests to deezer api
+ * @param {Object} body post body
+ * @param {String} method request method
+ */
+export declare const requestLight: (body: object, method: string) => Promise<any>;
+/**
+ * Make GET requests to deezer public api
+ * @param {String} method request method
+ * @param {Object} params request parameters
+ */
+export declare const requestGet: (method: string, params?: Record<string, any>, key?: string) => Promise<any>;
+/**
+ * Make GET requests to deezer public api
+ * @param {String} slug endpoint
+ */
+export declare const requestPublicApi: (slug: string) => Promise<any>;