hoenir 0.0.0-probe → 1.6.2

package/CHANGELOG.md

@@ -0,0 +1,167 @@
+# Changelog
+
+## 1.6.2 - 2026-08-30
+
+### Changed
+
+- Renamed the package from `@soulwax/d-fi` to the unscoped **`hoenir`**. The CLI command, config file (`hoenir.config.json`), global config dir (`~/.config/hoenir/`), and env vars (`HOENIR_ARL` / `HOENIR_EMAIL` / `HOENIR_PASSWORD`) are renamed to match — existing `d-fi` configs and `D_FI_*` env vars are no longer read. Update `import`/`require` from `@soulwax/d-fi` → `hoenir`.
+- Depends on `hoenir-core@^2.3.1` (was `@soulwax/d-fi-core`).
+
+## 1.6.1 - 2026-07-12
+
+### Added
+
+- `docs/api.md` — a complete programmatic API reference.
+- `examples/` — runnable Node scripts for the API (login, search, track-info, in-memory buffer, download-url), reading credentials from env vars.
+
+### Docs
+
+- README links to the API reference and examples.
+
+## 1.6.0 - 2026-07-12
+
+### Added
+
+- **Expanded programmatic API** — the package is now a full library, not just login helpers:
+  - `createSession({arl} | {email, password})` returning a `Session` with `parseUrl`, `search`, `getUser`, `getTrackBuffer`, `downloadTrack`, `downloadTracks`, and `downloadUrl`.
+  - `downloadTracks` / `downloadUrl` run with bounded `concurrency` and report progress via an `onProgress` callback (silent otherwise), returning one `{path, written} | null` per track.
+  - Download primitives: `getTrackBuffer(track, quality)` (returns a tagged audio Buffer without writing to disk) and `downloadTrackToFile(track, quality, options)`.
+  - Re-exported core query functions (`parseInfo`, `searchMusic`, `getUser`, `getTrackInfo`, `getAlbumInfo`, `getAlbumTracks`, `getPlaylistInfo`, `getPlaylistTracks`, `getArtistInfo`, `getDiscography`, `getLyrics`, `getTrackDownloadUrl`, `GeoBlocked`) so consumers don't need `hoenir-core` directly.
+  - Config helpers `globalConfigPath` and `resolveConfigFile` alongside the existing `Config`.
+
+### Fixed
+
+- The in-memory decrypt path now falls back to a pure-JS Blowfish implementation when OpenSSL 3 (Node 17+) disables the legacy `bf-cbc` cipher, matching the CLI. This makes programmatic downloads work out of the box on modern Node.
+
+## 1.5.0 - 2026-07-12
+
+### Added
+
+- **Programmatic API.** The package now has a side-effect-free library entry point, so it can be used as a dependency: `import {getArl, loginWithEmail, LoginError, Config} from 'hoenir'`. Importing no longer runs the CLI. Ships `main`, `types`, and `exports`.
+- `getArl(email, password)` — convenience that returns the arl or throws `LoginError`.
+- `loginWithEmail(email, password)` — returns a typed `LoginResult` (`ok`/`reason`/`message`).
+
+### Changed
+
+- Email/password login now uses Deezer's mobile OAuth flow (`connect.deezer.com`) and works reliably, instead of the bot-blocked web form. It is now offered as the first option in guided setup (no longer hidden behind a flag), and used automatically for headless runs when `HOENIR_EMAIL`/`HOENIR_PASSWORD` are set and no arl is configured.
+- `--experimental-login` is now a deprecated no-op (email login is on by default); the flag is still accepted for compatibility.
+
+### Security
+
+- Passwords are used only to authenticate and are never written to disk or logged; only the fetched arl is persisted (unless the user explicitly opts in to storing credentials).
+
+## 1.4.2 - 2026-07-12
+
+### Added
+
+- Experimental email/password login (`--experimental-login`): attempts to fetch your `arl` from your Deezer credentials so you don't have to copy the cookie manually. This is best-effort — Deezer bot-protects scripted logins, so it commonly fails and falls back to pasting an `arl`. Only the fetched `arl` is persisted; the password is never written to disk unless you explicitly opt in.
+- `HOENIR_EMAIL` / `HOENIR_PASSWORD` env vars and optional `cookies.email` / `cookies.password` config for non-interactive experimental login.
+
+### Notes
+
+- Email/password login is **off by default**; without `--experimental-login`, setup only offers the reliable "paste your arl" flow, unchanged from 1.4.1.
+
+## 1.4.1 - 2026-07-12
+
+### Added
+
+- Guided `arl` setup on the first interactive run: when no `arl` is configured (or the bundled default is still in use), `hoenir` now explains where to find the cookie and prompts you to paste it, then saves it automatically.
+- Interactive recovery when login fails: if the session cannot be verified (expired/invalid `arl`), `hoenir` offers to enter a fresh `arl` and retries instead of just erroring out.
+- `hoenir setup` / `--setup` (`-s`): on-demand guided setup to (re)enter your `arl` cookie at any time.
+- `HOENIR_ARL` environment variable: use an `arl` without a config file; it takes precedence over the config and is never written to disk (handy for CI, containers, and one-offs).
+- Global config location: when no project-local `hoenir.config.json` exists, config is read from and saved to `$XDG_CONFIG_HOME/hoenir/hoenir.config.json` (or `~/.config/hoenir/hoenir.config.json`), so a saved `arl` works from any directory.
+- `--overwrite` (`-w`) flag and `overwrite` config option to re-download and overwrite existing files (default remains to skip them).
+
+### Changed
+
+- Headless (`-d`), piped, and other non-interactive runs are unchanged — they never prompt and continue to use the configured `arl` (or `HOENIR_ARL`).
+
+## 1.3.2 - 2026-07-09
+
+### Changed
+
+- Updated build scripts to be more os agnostic
+
+## 1.3.1 - 2026-05-28
+
+### Changed
+
+- Updated the project screenshot asset.
+
+## 1.3.0 - 2026-05-28
+
+### Changed
+
+- Completed the Tier 1-3 performance rollup for the CLI release line.
+- Streamed encrypted tmpfile reads through the decrypt worker in fixed-size chunks instead of reading the whole encrypted file into memory first.
+
+## 1.2.6 - 2026-05-28
+
+### Changed
+
+- Parallelized `--input-file` URL handling when quality is already provided, while keeping interactive quality prompts sequential.
+
+## 1.2.5 - 2026-05-28
+
+### Changed
+
+- Offloaded encrypted track decryption to a small worker thread pool so parallel downloads are not blocked by CPU-bound decrypt work.
+- Kept a pure-JS decrypt fallback for Node/OpenSSL builds where `bf-cbc` is unavailable.
+
+## 1.2.4 - 2026-05-28
+
+### Changed
+
+- Switched CLI audio decryption to prefer the core implementation.
+
+## 1.2.3 - 2026-05-28
+
+### Changed
+
+- Added a GitHub Actions workflow for npm publishing at `.github/workflows/publish.yml`.
+- Bumped the package version to `1.2.3` for the release.
+
+## 1.2.2 - 2026-05-28
+
+### Changed
+
+- Minor CLI banner and documentation cleanup.
+
+## 1.2.0 - 2026-04-01
+
+### Changed
+
+- Bumped the CLI dependency to `hoenir-core@^2.2.0` so the published command-line package picks up the native HTTP transport release line.
+- Switched internal type imports to the published `hoenir-core/types` subpath instead of reaching into `dist/` internals.
+
+### Fixed
+
+- Revalidated the CLI against the packed core artifact before publish so release verification matches the package shape that npm consumers install.
+
+## 1.1.0 - 2026-04-01
+
+### Changed
+
+- Updated the CLI package to depend on the scoped core library package `hoenir-core`.
+- Updated runtime and type imports to use the scoped core package name consistently, including the published `hoenir-core/types` subpath.
+
+### Fixed
+
+- Removed the last documentation link that still pointed at the old `hoenir/hoenir-core` repository path.
+- Prepared the CLI package for the next scoped publish line without reintroducing the old unscoped dependency tree.
+- Corrected the npm license metadata to use a valid `SEE LICENSE IN LICENSE` expression.
+
+## 1.0.6 - 2026-03-26
+
+### Changed
+
+- Updated npm package metadata to use the GitHub repository at `https://github.com/soulwax/hoenir`.
+- Limited the published npm package contents to runtime artifacts and release metadata.
+- Updated README and docs links to use the current GitHub repository URLs.
+
+### Fixed
+
+- Corrected the repository URLs used in the README and CLI output.
+- Fixed the auto-updater release API endpoint to target `soulwax/hoenir` on GitHub.
+- Corrected npm and yarn install/update instructions to use the scoped package name `hoenir`.
+- Made the test runner Windows-safe without adding dependencies.

package/LICENSE

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

package/README.md

@@ -1,3 +1,237 @@
 # hoenir
 
-Name probe. Real release to follow.
+<img src="https://raw.githubusercontent.com/soulwax/hoenir/main/.github/assets/logo.png" alt="hoenir logo" width="200" height="200" style="display: block; margin-left: auto; margin-right: auto;" />
+
+> A crucial component of darkfloor streaming service systems.
+> Source repository: https://github.com/soulwax/hoenir
+>
+> **hoenir** — the Norse god who gave the first humans _óðr_: mind, spirit, the power of expression. Formerly `d-fi` / `@soulwax/d-fi`.
+
+![Screenshot](https://raw.githubusercontent.com/soulwax/hoenir/main/.github/assets/screenshot.png)
+
+**hoenir is a program for downloading music from streaming music services. Remember that the artists and studios put a lot of work into making music - purchase the original music to support them.**
+
+## v2 Migration Guide
+
+Please read [here](https://github.com/soulwax/hoenir/blob/main/docs/migration_v2.md) before contributing to the v2 branch.
+
+## Features
+
+- _Supports downloading tracks, albums, artists, and playlists_
+- _Allows music quality selection (**128 kbps**, **320 kbps** and **FLAC**)_
+- _Auto tagging **MP3** & **FLAC** (including album cover and lyrics)_
+- _Support downloading from both links and via searching_
+
+## Supported Sites
+
+### _Deezer_, _Spotify_ and _Tidal_
+
+- _Tracks_
+- _Albums_
+- _Audiobook_
+- _Playlists_
+- _Artists_
+
+> Note that Spotify and Tidal tracks will be sourced from Deezer using ISRC matching and UPC for albums. Also Spotify artist tracks are limited upto 10 items.
+
+## Install
+
+### _Method 1_
+
+First install `nodejs` following [this tutorial](https://nodejs.org/en/download/package-manager/)
+
+Once `nodejs` installation is complete run this command.
+
+    npm i -g hoenir # may require sudo on linux and macOS
+
+or if you are using yarn
+
+    yarn global add hoenir
+
+or pnpm
+
+    pnpm add -g hoenir
+
+Now you can run using command `hoenir` to start.
+
+### First run — getting your `arl`
+
+`hoenir` logs in to Deezer using an `arl` cookie. On the **first interactive run** (just
+running `hoenir` with no `--headless`/scripting flags), if you have not configured an `arl`
+yet, `hoenir` walks you through it: it prints where to find the cookie and prompts you to
+paste it, then saves it for you. It will also offer to re-enter the `arl` if login fails
+because the cookie has expired.
+
+To get your `arl` manually:
+
+1. Open [https://www.deezer.com](https://www.deezer.com) in your browser and log in.
+2. Open DevTools (`F12`) → **Application** → **Cookies** → `deezer.com`.
+3. Copy the value of the `arl` cookie (a long hex string).
+
+You can set or update it any time without the prompt:
+
+    hoenir --set-arl <your_arl>
+
+Or run the guided setup at any time:
+
+    hoenir setup        # same as: hoenir --setup
+
+#### Log in with email & password
+
+`hoenir` can fetch your `arl` automatically from your Deezer email and password, so you
+never have to open DevTools. The guided setup offers it as the first option:
+
+    hoenir setup
+
+Only the fetched `arl` is stored; your password is never written to disk unless you
+explicitly opt in when prompted. For headless use, supply `HOENIR_EMAIL` and
+`HOENIR_PASSWORD` env vars and `hoenir` will log in automatically when no `arl` is set:
+
+    HOENIR_EMAIL=you@example.com HOENIR_PASSWORD=secret hoenir -q 320 -u <url>
+
+> Login uses Deezer's mobile OAuth flow. If it ever fails (bad credentials or a change
+> on Deezer's side), `hoenir` falls back to asking you to paste an `arl`.
+
+### Zero-config usage (env var & global config)
+
+`hoenir` works from **any directory** without a per-folder config file:
+
+- Set the `HOENIR_ARL` environment variable and `hoenir` will use it (it takes precedence over
+  the config file, and is never written to disk). Handy for CI, containers, and one-offs:
+
+      HOENIR_ARL=<your_arl> hoenir -q 320 -u <url>
+
+- When you save an `arl` (via `setup` or `--set-arl`) and there is no `hoenir.config.json` in
+  the current directory, `hoenir` stores it in a **global** location
+  (`$XDG_CONFIG_HOME/hoenir/hoenir.config.json`, or `~/.config/hoenir/hoenir.config.json`) so it is
+  reused everywhere. A `hoenir.config.json` in the current directory still takes precedence.
+
+> Scripted, headless (`-d`), and non-interactive (piped) runs never prompt — they behave
+> exactly as before and simply use the configured `arl` (or `HOENIR_ARL`).
+
+### _Method 2_
+
+Download pre-built binary from [here](https://github.com/soulwax/hoenir/releases) and then double click on Windows to run. For Linux and macOS user, first open your choice of terminal and the execute with `./hoenir`
+
+## CLI Parameters
+
+All options are optional. You can suppress prompts via providing `quality` and `url` if you are using scripts. You can also use config file. Read the docs [here](https://github.com/soulwax/hoenir/blob/main/docs/config.md) for more info.
+
+| Parameter             |      Short      |                                                    Supported values                                                     |                                                                  Description                                                                  |
+| :-------------------- | :-------------: | :---------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------: |
+| `--quality`           |      `-q`       |                                                      128/320/flac                                                       |                                                     The quality of the files to download                                                      |
+| `--output`            |      `-o`       | Output file format according to `saveLayout`. See more [here](https://github.com/soulwax/hoenir/blob/main/docs/config.md) |                                                       The path to download the files to                                                       |
+| `--url`               | `-u or nothing` |                                             album/artist/playlist/track url                                             |                                                              Downloads from url                                                               |
+| `--input-file`        |      `-i`       |                          Downloads all urls listed in text file. Example: `hoenir -i links.txt`                           |                                                              Downloads from url                                                               |
+| `--concurrency`       |  `-c` 1 to 50   |                                               Downloads X songs at a time                                               |                                                                                                                                               |
+| `--set-arl`           |      `-a`       |                                                      `arl` string                                                       |                                                                Set arl cookies                                                                |
+| `--setup`             |      `-s`       |                                                        _Nothing_                                                        |                                Run guided setup to enter your `arl` cookie. Also available as `hoenir setup`.                                    |
+| `--overwrite`         |      `-w`       |                                                        _Nothing_                                                        |                                     Re-download and overwrite existing files (default is to skip them).                                        |
+| `--experimental-login`|     _None_      |                                                        _Nothing_                                                        |                  Enable experimental email/password login to fetch an `arl` (often blocked by Deezer; falls back to arl paste).                |
+| `--headless`          |      `-d`       |                                                        _Nothing_                                                        | Run in headless mode. You must provide both `--url` and `--quality` if you run in headless mode. This mode is meant for scripting automation. |
+| `--resolve-full-path` |     `-rfp`      |                                                        _Nothing_                                                        |                                               Create playlist file with absolute path location                                                |
+| `--create-playlist`   |      `-cp`      |                                                        _Nothing_                                                        |                                                    Create playlist for albums and artists                                                     |
+| `--config-file`       |     `-conf`     |                               Config location. Example: `hoenir -conf my-hoenir.config.json`                                |                                                    Specify custom location to config file                                                     |
+| `--update`            |      `-U`       |                                                        _Nothing_                                                        |                                                       Download new update (binary only)                                                       |
+| `--help`              |      `-h`       |                                                        _Nothing_                                                        |                                                              Shows the CLI help                                                               |
+
+## Search Parameters
+
+|   Prefix    |   Description   |
+| :---------: | :-------------: |
+|  `artist:`  |  Search artist  |
+|  `album:`   |  Search album   |
+| `playlist:` | Search playlist |
+
+## Programmatic API
+
+When installed as a dependency, `hoenir` exposes a side-effect-free API
+(importing it does **not** print the banner or parse CLI args, and nothing logs to the
+console — progress is delivered via callbacks). CommonJS and ESM both work.
+
+> **Full reference:** [docs/api.md](https://github.com/soulwax/hoenir/blob/main/docs/api.md) ·
+> **Runnable examples:** [examples/](https://github.com/soulwax/hoenir/tree/main/examples)
+
+### High-level: sessions
+
+The quickest path from credentials to files. `createSession` logs in (with an `arl` or
+email/password), verifies the session, and returns helpers for querying and downloading:
+
+```ts
+import {createSession} from 'hoenir';
+
+const session = await createSession({email: 'you@example.com', password: 'secret'});
+// ...or: createSession({arl: '...'})
+
+// Resolve any Deezer / Spotify / Tidal URL and download it:
+await session.downloadUrl('https://deezer.com/album/302127', 'flac', {
+  output: 'Music/{ALB_TITLE}/{SNG_TITLE}',
+  concurrency: 4,
+  onProgress: ({index, total, track, result}) =>
+    console.log(`${index + 1}/${total} ${track.SNG_TITLE} -> ${result?.path ?? 'unavailable'}`),
+});
+
+// Or work with the pieces:
+const {tracks} = await session.parseUrl('https://deezer.com/track/3135556');
+const found = await session.search('daft punk', ['TRACK'], 10);
+const results = await session.downloadTracks(tracks, '320', {output: '{ART_NAME} - {SNG_TITLE}'});
+```
+
+Session methods: `parseUrl`, `search`, `getUser`, `getTrackBuffer`, `downloadTrack`,
+`downloadTracks`, `downloadUrl`. Every download call is silent; `downloadTracks` /
+`downloadUrl` accept `concurrency` and an `onProgress` callback and return one
+`{path, written} | null` per track.
+
+### Low-level: primitives
+
+```ts
+import {getArl, initDeezerApi, getTrackInfo, getTrackBuffer, downloadTrackToFile} from 'hoenir';
+
+const arl = await getArl('you@example.com', 'secret'); // throws LoginError on failure
+await initDeezerApi(arl);
+
+const track = await getTrackInfo('3135556');
+
+// Get the tagged audio as a Buffer without touching the disk:
+const mp3 = await getTrackBuffer(track, '320');
+
+// ...or write it straight to a file:
+const {path, written} = (await downloadTrackToFile(track, 'flac', {output: '{ART_NAME} - {SNG_TITLE}'}))!;
+```
+
+### Re-exported query functions
+
+So you don't need `hoenir-core` as a second dependency (call after `initDeezerApi`
+or `createSession`):
+
+`parseInfo`, `searchMusic`, `getUser`, `getTrackInfo`, `getAlbumInfo`, `getAlbumTracks`,
+`getPlaylistInfo`, `getPlaylistTracks`, `getArtistInfo`, `getDiscography`, `getLyrics`,
+`getTrackDownloadUrl`, `GeoBlocked`.
+
+### Auth & config helpers
+
+```ts
+import {loginWithEmail, LoginError, Config, globalConfigPath} from 'hoenir';
+
+const result = await loginWithEmail('you@example.com', 'password');
+if (result.ok) console.log(result.arl);
+else console.error(result.reason, result.message); // 'wrong-credentials' | 'no-arl' | 'network' | 'unknown'
+
+const conf = new Config();      // same config file the CLI uses
+conf.set('cookies.arl', result.ok ? result.arl : '');
+```
+
+Passwords passed to these functions are used only to authenticate and are never written
+to disk or logged; only the resulting `arl` is returned or stored.
+
+### Disclaimer
+
+> I am not responsible in any way for the usage of others.
+
+---
+
+> Made with :heart: by the Bluesix Team. If you want to contribute, please read the [contributing guidelines](.github/CONTRIBUTING.md) first.
+
+### License
+
+Copyright © 2026 Christian Kling, Saskia Falkenhagen, Jens Arnolds

package/dist/package.json

@@ -0,0 +1,90 @@
+{
+    "name": "hoenir",
+    "version": "1.6.2",
+    "description": "The crucial streaming module for dabox systems.",
+    "author": "Christian Kling",
+    "license": "SEE LICENSE IN LICENSE",
+    "scripts": {
+        "lint": "eslint .",
+        "prepublishOnly": "eslint . && tsc",
+        "prebuild": "eslint .",
+        "build": "tsc",
+        "postinstall": "node setup-termux.js",
+        "dev": "ts-node src/hoenir.ts",
+        "test": "node scripts/run-ava.cjs"
+    },
+    "bin": {
+        "hoenir": "dist/src/hoenir.js"
+    },
+    "main": "dist/src/index.js",
+    "types": "dist/src/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/src/index.d.ts",
+            "default": "./dist/src/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist/**/*",
+        "setup-termux.js",
+        "CHANGELOG.md"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/soulwax/hoenir.git"
+    },
+    "homepage": "https://github.com/soulwax/hoenir#readme",
+    "bugs": {
+        "url": "https://github.com/soulwax/hoenir/issues"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "engines": {
+        "node": ">=12"
+    },
+    "dependencies": {
+        "adm-zip": "^0.5.16",
+        "chalk": "^4.1.2",
+        "commander": "^9.5.0",
+        "hoenir-core": "^2.3.1",
+        "dot-prop": "^6.0.1",
+        "egoroof-blowfish": "^4.0.2",
+        "got": "^11.8.6",
+        "gradient-string": "^2.0.2",
+        "log-update": "^4.0.0",
+        "p-queue": "^6.6.2",
+        "prompts": "^2.4.2",
+        "true-case-path": "^2.2.1",
+        "update-check": "^1.5.4"
+    },
+    "devDependencies": {
+        "@types/adm-zip": "^0.4.34",
+        "@types/gradient-string": "^1.1.6",
+        "@types/node": "^17.0.45",
+        "@types/prompts": "^2.4.9",
+        "@typescript-eslint/eslint-plugin": "^5.62.0",
+        "@typescript-eslint/parser": "^5.62.0",
+        "ava": "^4.3.3",
+        "eslint": "^8.57.1",
+        "eslint-plugin-prettier": "^4.2.5",
+        "prettier": "^2.8.8",
+        "ts-node": "^10.9.2",
+        "typescript": "^4.9.5"
+    },
+    "ava": {
+        "extensions": [
+            "ts"
+        ],
+        "files": [
+            "!dist"
+        ],
+        "require": [
+            "ts-node/register"
+        ],
+        "timeout": "5m",
+        "serial": true,
+        "verbose": true
+    }
+}

package/dist/src/hoenir.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};