gerdur 0.0.0-probe → 1.0.1

package/dist/src/gerdur.js

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const os_1 = require("os");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const commander_1 = require("commander");
+const gradient_string_1 = __importDefault(require("gradient-string"));
+const gerdur_core_1 = require("gerdur-core");
+const prompts_1 = __importDefault(require("prompts"));
+const log_update_1 = __importDefault(require("log-update"));
+const p_queue_1 = __importDefault(require("p-queue"));
+const chalk_1 = __importDefault(require("chalk"));
+const true_case_path_1 = require("true-case-path");
+const signale_1 = __importDefault(require("./lib/signale"));
+const download_track_1 = __importDefault(require("./lib/download-track"));
+const config_1 = __importDefault(require("./lib/config"));
+const update_check_1 = __importDefault(require("./lib/update-check"));
+const auto_updater_1 = __importDefault(require("./lib/auto-updater"));
+const arl_setup_1 = require("./lib/arl-setup");
+const util_1 = require("./lib/util");
+const package_json_1 = __importDefault(require("../package.json"));
+// App info
+console.log((0, gradient_string_1.default)('red', 'yellow', 'orange')(`             ♥ gerdur - ${package_json_1.default.version} ♥         `) +
+    '\n' +
+    (0, gradient_string_1.default)('orange', 'yellow', 'red')(' ──────────────────────────────────────────────') +
+    '\n' +
+    (0, gradient_string_1.default)('red', 'yellow', 'orange')(' │ repo   https://github.com/soulwax/gerdur   │ ') +
+    '\n' +
+    (0, gradient_string_1.default)('red', 'yellow', 'orange')(' │ github https://github.com/soulwax        │ ') +
+    '\n' +
+    (0, gradient_string_1.default)('red', 'yellow', 'orange')(' ──────────────────────────────────────────────'));
+const cmd = new commander_1.Command()
+    .option('-q, --quality <quality>', 'The quality of the files to download: 128/320/flac ')
+    .option('-o, --output <template>', 'Output filename template')
+    .option('-u, --url <url>', 'Deezer album/artist/playlist/track url')
+    .option('-i, --input-file <file>', 'Downloads all urls listed in text file')
+    .option('-c, --concurrency <number>', 'Download concurrency for album, artists and playlist')
+    .option('-a, --set-arl <string>', 'Set arl cookie')
+    .option('-s, --setup', 'Run guided first-time setup (enter your arl cookie)')
+    .option('--experimental-login', 'Deprecated: email/password login is now offered by default')
+    .option('-w, --overwrite', 'Re-download and overwrite files that already exist')
+    .option('-d, --headless', 'Run in headless mode for scripting automation', false)
+    .option('-conf, --config-file <file>', 'Custom location to your config file', 'gerdur.config.json')
+    .option('-rfp, --resolve-full-path', 'Use absolute path for playlists')
+    .option('-cp, --create-playlist', 'Force create a playlist file for non playlists');
+if (process.pkg) {
+    cmd.option('-U, --update', 'Update this program to latest version');
+}
+const options = cmd.parse(process.argv).opts();
+// Support a bare `gerdur setup` subcommand as an alias for `--setup`.
+if (cmd.args[0] && cmd.args[0].toLowerCase() === 'setup') {
+    options.setup = true;
+    cmd.args.shift();
+}
+if (!options.url && cmd.args[0]) {
+    options.url = cmd.args[0];
+}
+if (options.headless && !options.quality) {
+    console.error(signale_1.default.error('Missing parameters --quality'));
+    console.error(signale_1.default.note('Quality must be provided with headless mode'));
+    process.exit(1);
+}
+if (options.headless && !options.url && !options.inputFile) {
+    console.error(signale_1.default.error('Missing parameters --url'));
+    console.error(signale_1.default.note('URL must be provided with headless mode'));
+    process.exit(1);
+}
+const conf = new config_1.default(options.configFile);
+if (conf.userConfigLocation) {
+    console.log(signale_1.default.info('Config loaded --> ' + conf.userConfigLocation));
+}
+const queue = new p_queue_1.default({ concurrency: Number(options.concurrency || conf.get('concurrency')) });
+const urlRegex = /https?:\/\/.*\w+\.\w+\/\w+/;
+const onCancel = () => {
+    console.info(signale_1.default.note('Aborted!'));
+    process.exit();
+};
+const startDownload = async (saveLayout, url, skipPrompt) => {
+    try {
+        if (!options.quality) {
+            const { musicQuality } = await (0, prompts_1.default)([
+                {
+                    type: 'select',
+                    name: 'musicQuality',
+                    message: 'Select music quality:',
+                    choices: [
+                        { title: 'MP3  - 128 kbps', value: '128' },
+                        { title: 'MP3  - 320 kbps', value: '320' },
+                        { title: 'FLAC - 1411 kbps', value: 'flac' },
+                    ],
+                    initial: 1,
+                },
+            ], { onCancel });
+            options.quality = musicQuality;
+        }
+        if (!url) {
+            const { query } = await (0, prompts_1.default)([
+                {
+                    type: 'text',
+                    name: 'query',
+                    message: 'Enter URL or search:',
+                    validate: (value) => (value ? true : false),
+                },
+            ], { onCancel });
+            url = query;
+        }
+        let searchData = null;
+        if (!url.match(urlRegex)) {
+            if (options.headless) {
+                throw new Error('Please provide a valid URL. Unknown URL: ' + url);
+            }
+            if (url.startsWith('artist:')) {
+                const { ARTIST } = await (0, gerdur_core_1.searchMusic)(url.replace('artist:', ''), ['ARTIST'], 50);
+                const choice = await (0, prompts_1.default)([
+                    {
+                        type: 'select',
+                        name: 'items',
+                        message: `Select one artist. (found ${ARTIST.data.length} artists)`,
+                        choices: ARTIST.data.map((a) => ({
+                            title: a.ART_NAME,
+                            value: a,
+                            description: `${a.NB_FAN} fans`,
+                        })),
+                    },
+                ], { onCancel });
+                console.log(signale_1.default.info('Fetching data. Please hold on.'));
+                url = `https://deezer.com/us/artist/${choice.items.ART_ID}`;
+            }
+            else if (url.startsWith('album:')) {
+                const { ALBUM } = await (0, gerdur_core_1.searchMusic)(url.replace('album:', ''), ['ALBUM'], 50);
+                const choice = await (0, prompts_1.default)([
+                    {
+                        type: 'select',
+                        name: 'items',
+                        message: `Select one album. (found ${ALBUM.data.length} albums)`,
+                        choices: ALBUM.data.map((a) => ({
+                            title: a.ALB_TITLE,
+                            value: a,
+                            description: `by ${a.ART_NAME}, ${a.NUMBER_TRACK} tracks`,
+                        })),
+                    },
+                ], { onCancel });
+                url = `https://deezer.com/us/album/${choice.items.ALB_ID}`;
+            }
+            else if (url.startsWith('playlist:')) {
+                const { PLAYLIST } = await (0, gerdur_core_1.searchMusic)(url.replace('playlist:', ''), ['PLAYLIST'], 50);
+                const choice = await (0, prompts_1.default)([
+                    {
+                        type: 'select',
+                        name: 'items',
+                        message: `Select one playlist. (found ${PLAYLIST.data.length} playlists)`,
+                        choices: PLAYLIST.data.map((p) => ({
+                            title: p.TITLE,
+                            value: p,
+                            description: `by ${p.PARENT_USERNAME}, ${p.NB_SONG} tracks`,
+                        })),
+                    },
+                ], { onCancel });
+                url = `https://deezer.com/us/playlist/${choice.items.PLAYLIST_ID}`;
+            }
+            else {
+                const { TRACK } = await (0, gerdur_core_1.searchMusic)(url, ['TRACK']);
+                searchData = {
+                    info: { type: 'track', id: url },
+                    linktype: 'track',
+                    linkinfo: {},
+                    tracks: TRACK.data.map((t) => {
+                        if (t.VERSION && !t.SNG_TITLE.includes(t.VERSION)) {
+                            t.SNG_TITLE += ' ' + t.VERSION;
+                        }
+                        return t;
+                    }),
+                };
+            }
+        }
+        else if (url.match(/playlist|artist/)) {
+            console.log(signale_1.default.info('Fetching data. Please hold on.'));
+        }
+        const data = searchData ? searchData : await (0, gerdur_core_1.parseInfo)(url);
+        if (!options.headless && data.tracks.length > 1) {
+            const choices = await (0, prompts_1.default)([
+                {
+                    type: 'multiselect',
+                    name: 'items',
+                    message: `Select songs to download. Total of ${data.tracks.length} tracks.`,
+                    choices: data.tracks.map((t) => ({
+                        title: t.SNG_TITLE,
+                        value: t,
+                        description: `Artist: ${t.ART_NAME}\nAlbum: ${t.ALB_TITLE}\nDuration: ${(0, util_1.formatSecondsReadable)(Number(t.DURATION))}`,
+                    })),
+                },
+            ], { onCancel });
+            data.tracks = choices.items;
+        }
+        if (data && data.tracks.length > 0) {
+            console.log(signale_1.default.info(`Proceeding to download ${data.tracks.length} tracks. Be patient.`));
+            if (data.linktype === 'playlist') {
+                const filteredTracks = data.tracks.filter((item, index, self) => index === self.findIndex((t) => t.SNG_ID === item.SNG_ID));
+                const duplicateTracks = data.tracks.length - filteredTracks.length;
+                if (duplicateTracks > 0) {
+                    data.tracks = filteredTracks
+                        .sort((a, b) => a.TRACK_POSITION - b.TRACK_POSITION)
+                        .map((t, i) => {
+                        t.TRACK_POSITION = i + 1;
+                        return t;
+                    });
+                    console.log(signale_1.default.warn(`Removed ${duplicateTracks} duplicate ${duplicateTracks > 1 ? 'tracks' : 'track'}.`));
+                }
+            }
+            const coverSizes = conf.get('coverSize');
+            const trackNumber = conf.get('trackNumber', true);
+            const fallbackTrack = conf.get('fallbackTrack', true);
+            const fallbackQuality = conf.get('fallbackQuality', true);
+            const overwrite = options.overwrite ?? conf.get('overwrite', false);
+            const resolveFullPath = options.resolveFullPath ?? conf.get('playlist.resolveFullPath');
+            const savedFiles = [];
+            let m3u8 = [];
+            await queue.addAll(data.tracks.map((track, index) => {
+                return async () => {
+                    const savedPath = await (0, download_track_1.default)({
+                        track,
+                        quality: options.quality,
+                        info: data.linkinfo,
+                        coverSizes,
+                        path: options.output ? options.output : saveLayout[data.linktype],
+                        totalTracks: data ? data.tracks.length : 10,
+                        trackNumber,
+                        fallbackTrack,
+                        fallbackQuality,
+                        overwrite,
+                        message: `(${index}/${data.tracks.length})`,
+                    });
+                    // Add to saved list
+                    if (savedPath) {
+                        m3u8.push((0, path_1.resolve)(process.env.SIMULATE ? savedPath : (0, true_case_path_1.trueCasePathSync)(savedPath)));
+                        savedFiles.push(savedPath);
+                    }
+                };
+            }));
+            // Display downloaded location
+            if (savedFiles.length > 0) {
+                const savedIn = new Set(savedFiles.map((l) => (0, path_1.dirname)(l)));
+                console.log(signale_1.default.info('Saved in ' + [...savedIn].map((d) => chalk_1.default.bgGreen(d)).join(', ')));
+            }
+            if ((options.createPlaylist || data.linktype === 'playlist') && !process.env.SIMULATE && m3u8.length > 1) {
+                const playlistDir = (0, util_1.commonPath)([...new Set(savedFiles.map(path_1.dirname))]);
+                const playlistFile = (0, path_1.join)(playlistDir, (0, util_1.sanitizeFilename)(data.linkinfo.TITLE || data.linkinfo.ALB_TITLE));
+                if (!resolveFullPath) {
+                    const resolvedPlaylistDir = (0, path_1.resolve)(playlistDir) + path_1.sep;
+                    m3u8 = m3u8.map((file) => file.replace(resolvedPlaylistDir, ''));
+                }
+                const m3u8Content = '#EXTM3U' + os_1.EOL + m3u8.sort().join(os_1.EOL);
+                (0, fs_1.writeFileSync)(playlistFile + '.m3u8', m3u8Content, { encoding: 'utf-8' });
+            }
+        }
+        else {
+            console.log(signale_1.default.info('No items to download!'));
+        }
+    }
+    catch (err) {
+        console.error(signale_1.default.error(err.message));
+    }
+    // Ask for new download
+    if (!options.headless && !skipPrompt) {
+        startDownload(saveLayout, '', skipPrompt);
+    }
+};
+/**
+ * Application init.
+ */
+const initApp = async () => {
+    if (options.setup) {
+        await (0, arl_setup_1.runSetup)(conf, options.headless, options.experimentalLogin);
+        return;
+    }
+    if (options.setArl) {
+        const configPath = conf.set('cookies.arl', options.setArl);
+        console.log(signale_1.default.info('cookies.arl set to --> ' + options.setArl));
+        console.log(signale_1.default.note(configPath));
+        process.exit();
+    }
+    (0, log_update_1.default)(signale_1.default.pending('Initializing session...'));
+    let arl = await (0, arl_setup_1.ensureArl)(conf, options.headless, options.experimentalLogin);
+    const login = async (cookie) => {
+        (0, log_update_1.default)(signale_1.default.pending('Verifying session...'));
+        await (0, gerdur_core_1.initDeezerApi)(cookie);
+        return (0, gerdur_core_1.getUser)();
+    };
+    let user;
+    try {
+        user = await login(arl);
+    }
+    catch (err) {
+        log_update_1.default.clear();
+        const newArl = await (0, arl_setup_1.recoverFromLoginFailure)(conf, options.headless, err, options.experimentalLogin);
+        if (!newArl) {
+            throw err;
+        }
+        arl = newArl;
+        user = await login(arl);
+    }
+    (0, log_update_1.default)(signale_1.default.success('Logged in as ' + user.BLOG_NAME));
+    log_update_1.default.done();
+    const saveLayout = conf.get('saveLayout');
+    if (options.inputFile) {
+        const urls = (0, fs_1.readFileSync)(options.inputFile, 'utf-8')
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line.match(urlRegex));
+        if (!options.quality && !options.headless) {
+            for (const url of urls) {
+                console.log(signale_1.default.info('Starting download: ' + url));
+                await startDownload(saveLayout, url, true);
+            }
+        }
+        else {
+            await Promise.all(urls.map((url) => {
+                console.log(signale_1.default.info('Starting download: ' + url));
+                return startDownload(saveLayout, url, true);
+            }));
+        }
+    }
+    else {
+        startDownload(saveLayout, options.url, false);
+    }
+};
+if (options.update) {
+    (0, auto_updater_1.default)(package_json_1.default).catch((err) => {
+        console.error(signale_1.default.error(err.message));
+        process.exit(1);
+    });
+}
+else {
+    // Check for update
+    (0, update_check_1.default)(package_json_1.default);
+    // Init interface
+    initApp().catch((err) => {
+        console.error(signale_1.default.error(err.message));
+        process.exit(1);
+    });
+}

package/dist/src/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Public library entry point for `gerdur`.
+ *
+ * This module is safe to `import`/`require` from other packages — unlike the
+ * CLI entry (`gerdur.ts`), importing it has no side effects (no banner, no
+ * argument parsing, no process exit). All functions are silent; progress is
+ * surfaced through optional callbacks.
+ *
+ * @example High-level usage
+ * ```ts
+ * import {createSession} from 'gerdur';
+ *
+ * const session = await createSession({email: 'you@example.com', password: 'secret'});
+ * await session.downloadUrl('https://deezer.com/album/302127', 'flac', {
+ *   output: 'Music/{ALB_TITLE}/{SNG_TITLE}',
+ *   onProgress: ({index, total, track}) => console.log(`${index + 1}/${total} ${track.SNG_TITLE}`),
+ * });
+ * ```
+ *
+ * @example Low-level usage
+ * ```ts
+ * import {getArl, getTrackBuffer} from 'gerdur';
+ * import {initDeezerApi, getTrackInfo} from 'gerdur';
+ *
+ * const arl = await getArl('you@example.com', 'secret');
+ * await initDeezerApi(arl);
+ * const track = await getTrackInfo('3135556');
+ * const mp3 = await getTrackBuffer(track, '320'); // Buffer, not written to disk
+ * ```
+ */
+import { loginWithEmail } from './lib/email-login';
+import type { LoginResult } from './lib/email-login';
+export { loginWithEmail };
+export type { LoginResult };
+/**
+ * Thrown by {@link getArl} when an email/password login does not yield an arl.
+ * `reason` mirrors the failure reason from {@link LoginResult}.
+ */
+export declare class LoginError extends Error {
+    readonly reason: Exclude<LoginResult, {
+        ok: true;
+    }>['reason'];
+    constructor(reason: Exclude<LoginResult, {
+        ok: true;
+    }>['reason'], message: string);
+}
+/**
+ * Fetch a Deezer `arl` from email and password.
+ *
+ * Convenience wrapper around {@link loginWithEmail} that returns the arl string
+ * directly and throws a {@link LoginError} on failure. The password is never
+ * persisted or logged by this call.
+ *
+ * @throws {LoginError} If authentication fails or no arl could be retrieved.
+ */
+export declare const getArl: (email: string, password: string) => Promise<string>;
+export { createSession, Session } from './lib/session';
+export type { SessionOptions, DownloadTracksOptions, SearchType } from './lib/session';
+export { getTrackBuffer, downloadTrackToFile } from './lib/api-download';
+export type { Quality, GetTrackBufferOptions, DownloadTrackOptions, DownloadResult } from './lib/api-download';
+export { default as Config, globalConfigPath, resolveConfigFile } from './lib/config';
+export { initDeezerApi, parseInfo, searchMusic, getUser, getTrackInfo, getAlbumInfo, getAlbumTracks, getPlaylistInfo, getPlaylistTracks, getArtistInfo, getDiscography, getLyrics, getTrackDownloadUrl, GeoBlocked, } from 'gerdur-core';

package/dist/src/index.js

@@ -0,0 +1,101 @@
+"use strict";
+/**
+ * Public library entry point for `gerdur`.
+ *
+ * This module is safe to `import`/`require` from other packages — unlike the
+ * CLI entry (`gerdur.ts`), importing it has no side effects (no banner, no
+ * argument parsing, no process exit). All functions are silent; progress is
+ * surfaced through optional callbacks.
+ *
+ * @example High-level usage
+ * ```ts
+ * import {createSession} from 'gerdur';
+ *
+ * const session = await createSession({email: 'you@example.com', password: 'secret'});
+ * await session.downloadUrl('https://deezer.com/album/302127', 'flac', {
+ *   output: 'Music/{ALB_TITLE}/{SNG_TITLE}',
+ *   onProgress: ({index, total, track}) => console.log(`${index + 1}/${total} ${track.SNG_TITLE}`),
+ * });
+ * ```
+ *
+ * @example Low-level usage
+ * ```ts
+ * import {getArl, getTrackBuffer} from 'gerdur';
+ * import {initDeezerApi, getTrackInfo} from 'gerdur';
+ *
+ * const arl = await getArl('you@example.com', 'secret');
+ * await initDeezerApi(arl);
+ * const track = await getTrackInfo('3135556');
+ * const mp3 = await getTrackBuffer(track, '320'); // Buffer, not written to disk
+ * ```
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GeoBlocked = exports.getTrackDownloadUrl = exports.getLyrics = exports.getDiscography = exports.getArtistInfo = exports.getPlaylistTracks = exports.getPlaylistInfo = exports.getAlbumTracks = exports.getAlbumInfo = exports.getTrackInfo = exports.getUser = exports.searchMusic = exports.parseInfo = exports.initDeezerApi = exports.resolveConfigFile = exports.globalConfigPath = exports.Config = exports.downloadTrackToFile = exports.getTrackBuffer = exports.Session = exports.createSession = exports.getArl = exports.LoginError = exports.loginWithEmail = void 0;
+// ─── Authentication ────────────────────────────────────────────────────────
+const email_login_1 = require("./lib/email-login");
+Object.defineProperty(exports, "loginWithEmail", { enumerable: true, get: function () { return email_login_1.loginWithEmail; } });
+/**
+ * Thrown by {@link getArl} when an email/password login does not yield an arl.
+ * `reason` mirrors the failure reason from {@link LoginResult}.
+ */
+class LoginError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'LoginError';
+        this.reason = reason;
+    }
+}
+exports.LoginError = LoginError;
+/**
+ * Fetch a Deezer `arl` from email and password.
+ *
+ * Convenience wrapper around {@link loginWithEmail} that returns the arl string
+ * directly and throws a {@link LoginError} on failure. The password is never
+ * persisted or logged by this call.
+ *
+ * @throws {LoginError} If authentication fails or no arl could be retrieved.
+ */
+const getArl = async (email, password) => {
+    const result = await (0, email_login_1.loginWithEmail)(email, password);
+    if (result.ok) {
+        return result.arl;
+    }
+    throw new LoginError(result.reason, result.message);
+};
+exports.getArl = getArl;
+// ─── High-level session ──────────────────────────────────────────────────────
+var session_1 = require("./lib/session");
+Object.defineProperty(exports, "createSession", { enumerable: true, get: function () { return session_1.createSession; } });
+Object.defineProperty(exports, "Session", { enumerable: true, get: function () { return session_1.Session; } });
+// ─── Download primitives ─────────────────────────────────────────────────────
+var api_download_1 = require("./lib/api-download");
+Object.defineProperty(exports, "getTrackBuffer", { enumerable: true, get: function () { return api_download_1.getTrackBuffer; } });
+Object.defineProperty(exports, "downloadTrackToFile", { enumerable: true, get: function () { return api_download_1.downloadTrackToFile; } });
+// ─── Config ──────────────────────────────────────────────────────────────────
+// The same config the CLI uses (env var, global path resolution, arl storage).
+var config_1 = require("./lib/config");
+Object.defineProperty(exports, "Config", { enumerable: true, get: function () { return __importDefault(config_1).default; } });
+Object.defineProperty(exports, "globalConfigPath", { enumerable: true, get: function () { return config_1.globalConfigPath; } });
+Object.defineProperty(exports, "resolveConfigFile", { enumerable: true, get: function () { return config_1.resolveConfigFile; } });
+// ─── Re-exported core query functions ────────────────────────────────────────
+// Convenience re-exports so consumers don't need `gerdur-core` directly.
+// After `initDeezerApi(arl)` (or `createSession`) these are ready to use.
+var gerdur_core_1 = require("gerdur-core");
+Object.defineProperty(exports, "initDeezerApi", { enumerable: true, get: function () { return gerdur_core_1.initDeezerApi; } });
+Object.defineProperty(exports, "parseInfo", { enumerable: true, get: function () { return gerdur_core_1.parseInfo; } });
+Object.defineProperty(exports, "searchMusic", { enumerable: true, get: function () { return gerdur_core_1.searchMusic; } });
+Object.defineProperty(exports, "getUser", { enumerable: true, get: function () { return gerdur_core_1.getUser; } });
+Object.defineProperty(exports, "getTrackInfo", { enumerable: true, get: function () { return gerdur_core_1.getTrackInfo; } });
+Object.defineProperty(exports, "getAlbumInfo", { enumerable: true, get: function () { return gerdur_core_1.getAlbumInfo; } });
+Object.defineProperty(exports, "getAlbumTracks", { enumerable: true, get: function () { return gerdur_core_1.getAlbumTracks; } });
+Object.defineProperty(exports, "getPlaylistInfo", { enumerable: true, get: function () { return gerdur_core_1.getPlaylistInfo; } });
+Object.defineProperty(exports, "getPlaylistTracks", { enumerable: true, get: function () { return gerdur_core_1.getPlaylistTracks; } });
+Object.defineProperty(exports, "getArtistInfo", { enumerable: true, get: function () { return gerdur_core_1.getArtistInfo; } });
+Object.defineProperty(exports, "getDiscography", { enumerable: true, get: function () { return gerdur_core_1.getDiscography; } });
+Object.defineProperty(exports, "getLyrics", { enumerable: true, get: function () { return gerdur_core_1.getLyrics; } });
+Object.defineProperty(exports, "getTrackDownloadUrl", { enumerable: true, get: function () { return gerdur_core_1.getTrackDownloadUrl; } });
+Object.defineProperty(exports, "GeoBlocked", { enumerable: true, get: function () { return gerdur_core_1.GeoBlocked; } });

package/dist/src/lib/api-download.d.ts

@@ -0,0 +1,54 @@
+/// <reference types="node" />
+import type { trackType } from 'gerdur-core/types';
+/** Music quality accepted by the API. */
+export type Quality = '128' | '320' | 'flac' | 1 | 3 | 9;
+export interface GetTrackBufferOptions {
+    /** Album cover size (px) embedded in tags. Default 500. */
+    coverSize?: number;
+    /**
+     * If the requested quality is unavailable, try lower qualities (320 -> 128)
+     * before giving up. Default true.
+     */
+    fallbackQuality?: boolean;
+}
+/**
+ * Download, decrypt, and tag a single track entirely in memory.
+ *
+ * Returns the ready-to-write audio Buffer (MP3 or FLAC), or `null` if the track
+ * is not available for download. Nothing is written to disk and nothing is
+ * logged.
+ *
+ * @param track Track info (e.g. from `getTrackInfo` or `parseUrl`).
+ * @param quality '128' | '320' | 'flac' (or numeric 1 | 3 | 9).
+ */
+export declare const getTrackBuffer: (track: trackType, quality?: Quality, { coverSize, fallbackQuality }?: GetTrackBufferOptions) => Promise<Buffer | null>;
+export interface DownloadTrackOptions extends GetTrackBufferOptions {
+    /**
+     * Output file path or a `saveLayout` template (e.g. `{ART_NAME} - {SNG_TITLE}`).
+     * The correct extension (`.mp3` / `.flac`) is appended automatically.
+     * Default: `{ART_NAME} - {SNG_TITLE}`.
+     */
+    output?: string;
+    /** Album info used to resolve album-level template tokens. */
+    albumInfo?: {
+        [key: string]: any;
+    };
+    /** Prefix the filename with the track number. Default false. */
+    trackNumber?: boolean;
+    /** Re-download even if the destination file already exists. Default false. */
+    overwrite?: boolean;
+}
+export interface DownloadResult {
+    /** The path the file was written to (or would have been, if skipped). */
+    path: string;
+    /** True if the file was written; false if skipped because it already existed. */
+    written: boolean;
+}
+/**
+ * Download a single track to disk (silent). Resolves the destination path from
+ * the `output` template, skips existing files unless `overwrite` is set, and
+ * creates parent directories as needed.
+ *
+ * Returns `{path, written}`, or `null` if the track was not available.
+ */
+export declare const downloadTrackToFile: (track: trackType, quality?: Quality, options?: DownloadTrackOptions) => Promise<DownloadResult | null>;

package/dist/src/lib/api-download.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.downloadTrackToFile = exports.getTrackBuffer = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const got_1 = __importDefault(require("got"));
+const gerdur_core_1 = require("gerdur-core");
+const decrypt_1 = require("./decrypt");
+const util_1 = require("./util");
+const QUALITY_MAP = {
+    '1': { q: 1, ext: '.mp3', size: 'FILESIZE_MP3_128' },
+    '128': { q: 1, ext: '.mp3', size: 'FILESIZE_MP3_128' },
+    '3': { q: 3, ext: '.mp3', size: 'FILESIZE_MP3_320' },
+    '320': { q: 3, ext: '.mp3', size: 'FILESIZE_MP3_320' },
+    '9': { q: 9, ext: '.flac', size: 'FILESIZE_FLAC' },
+    flac: { q: 9, ext: '.flac', size: 'FILESIZE_FLAC' },
+};
+const resolveQuality = (quality) => {
+    const key = String(quality).toLowerCase();
+    return QUALITY_MAP[key] ?? QUALITY_MAP['320'];
+};
+/**
+ * Download, decrypt, and tag a single track entirely in memory.
+ *
+ * Returns the ready-to-write audio Buffer (MP3 or FLAC), or `null` if the track
+ * is not available for download. Nothing is written to disk and nothing is
+ * logged.
+ *
+ * @param track Track info (e.g. from `getTrackInfo` or `parseUrl`).
+ * @param quality '128' | '320' | 'flac' (or numeric 1 | 3 | 9).
+ */
+const getTrackBuffer = async (track, quality = '320', { coverSize = 500, fallbackQuality = true } = {}) => {
+    const order = fallbackQuality ? [quality, '320', '128'] : [quality];
+    const tried = new Set();
+    for (const q of order) {
+        const { q: qNum } = resolveQuality(q);
+        if (tried.has(qNum)) {
+            continue;
+        }
+        tried.add(qNum);
+        let trackData;
+        try {
+            trackData = await (0, gerdur_core_1.getTrackDownloadUrl)(track, qNum);
+        }
+        catch (err) {
+            if (err instanceof gerdur_core_1.GeoBlocked) {
+                throw err;
+            }
+            trackData = null;
+        }
+        if (!trackData) {
+            continue;
+        }
+        const { body } = await (0, got_1.default)(trackData.trackUrl, { responseType: 'buffer' });
+        const decrypted = trackData.isEncrypted ? (0, decrypt_1.decryptDownload)(body, track.SNG_ID) : body;
+        return (0, gerdur_core_1.addTrackTags)(decrypted, track, coverSize);
+    }
+    return null;
+};
+exports.getTrackBuffer = getTrackBuffer;
+/**
+ * Download a single track to disk (silent). Resolves the destination path from
+ * the `output` template, skips existing files unless `overwrite` is set, and
+ * creates parent directories as needed.
+ *
+ * Returns `{path, written}`, or `null` if the track was not available.
+ */
+const downloadTrackToFile = async (track, quality = '320', options = {}) => {
+    const { output = '{ART_NAME} - {SNG_TITLE}', albumInfo = {}, trackNumber = false, overwrite = false } = options;
+    const { ext } = resolveQuality(quality);
+    const savePath = (0, util_1.saveLayout)({ track, album: albumInfo, path: output, trackNumber, minimumIntegerDigits: 2 }) + ext;
+    if ((0, fs_1.existsSync)(savePath) && !overwrite) {
+        return { path: savePath, written: false };
+    }
+    const buffer = await (0, exports.getTrackBuffer)(track, quality, options);
+    if (!buffer) {
+        return null;
+    }
+    const dir = (0, path_1.dirname)(savePath);
+    if (dir && !(0, fs_1.existsSync)(dir)) {
+        (0, fs_1.mkdirSync)(dir, { recursive: true });
+    }
+    (0, fs_1.writeFileSync)(savePath, buffer);
+    return { path: savePath, written: true };
+};
+exports.downloadTrackToFile = downloadTrackToFile;