@bzenky/spoti 0.2.0 → 0.4.0

package/README.md

@@ -21,13 +21,27 @@ Create an application in the [Spotify Developer Dashboard](https://developer.spo
 http://127.0.0.1:43821/callback
 ```
 
-Export the application's client ID before running authentication:
+After installing `spoti`, save the application's client ID once:
+
+```bash
+spoti setup
+spoti login
+```
+
+When developing from source, use:
+
+```bash
+npm run dev -- setup
+npm run dev -- login
+```
+
+The setup command stores the public client ID in your local `spoti` configuration. For temporary sessions, CI, or an explicit override, you can still use:
 
 ```bash
 export SPOTIFY_CLIENT_ID="your-client-id"
 ```
 
-To use a different local callback, register it in the same Spotify application and set:
+The environment variable takes precedence over the stored value. To use a different local callback, register it in the same Spotify application and set:
 
 ```bash
 export SPOTIFY_REDIRECT_URI="http://127.0.0.1:5000/callback"
@@ -67,6 +81,21 @@ npm run dev -- status
 
 ## Usage
 
+Run `spoti` with no command to see the complete command overview:
+
+```bash
+spoti
+```
+
+Open the interactive multi-category search explicitly:
+
+```bash
+spoti interactive
+# alias: spoti i
+```
+
+Type a query and press Enter. Use `Tab` or left/right to switch between tracks, albums, artists, and playlists; use up/down to select; press Enter to play; press Esc to exit. The terminal is restored even when a request fails.
+
 Authenticate once through Spotify's browser authorization page:
 
 ```bash
@@ -90,15 +119,23 @@ spoti previous
 spoti volume 50
 spoti volume +10
 spoti volume -10
+spoti shuffle on
+spoti shuffle off
+spoti repeat off
+spoti repeat track
+spoti repeat context
 ```
 
 Manage playback devices:
 
 ```bash
 spoti devices
+spoti device 2
 spoti device "My Computer"
 ```
 
+Use the displayed one-based number, exact device name, or Spotify device ID.
+
 When playback has no active device, `spoti play` and `spoti resume` automatically target it if exactly one controllable device is available.
 
 Seek within the current track:
@@ -124,6 +161,49 @@ spoti search "Breaking the Habit"
 spoti search "Breaking the Habit" --limit 5
 ```
 
+Search, inspect, and play Spotify contexts:
+
+```bash
+spoti album "Meteora"
+spoti artist "Linkin Park"
+spoti playlists
+spoti playlist 1
+spoti playlist "Workout"
+spoti play track "Numb"
+spoti play album "Meteora"
+spoti play artist "Linkin Park"
+spoti play playlist "Workout"
+spoti play playlist 1
+```
+
+User playlists are sorted consistently by name, so the displayed number can be reused with `spoti playlist <number>` or `spoti play playlist <number>`.
+
+In an interactive terminal, `spoti album` can play the entire album or a selected track after showing its details. `spoti artist` can play the artist context or let you select one of the artist’s albums, and `spoti playlist` can start the selected playlist. Non-interactive runs remain display-only and never start playback implicitly.
+
+`spoti play <query>` remains shorthand for track playback. The words `track`, `album`, `artist`, and `playlist` are treated as explicit types when followed by another argument. For a track query that starts with one of those reserved words, use `spoti play track <query>` (or quote the complete query as one shell argument). Context commands support `--first` to skip interactive selection.
+
+Manage and inspect your Spotify library:
+
+```bash
+spoti liked
+spoti liked --limit 10
+spoti like
+spoti unlike
+spoti recent
+spoti recent --limit 10
+```
+
+`spoti like` and `spoti unlike` operate on the currently playing track. Episodes, advertisements, local files, and unavailable items are ignored safely.
+
+Check for updates or install the latest npm release:
+
+```bash
+spoti update --check
+spoti update
+```
+
+`spoti update` asks for confirmation before installing the exact version returned by the update check. It never installs an update silently. Normal commands use a cached update result and refresh it in a detached process at most once every 24 hours, so npm availability does not delay or break Spotify controls.
+
 Remove local credentials:
 
 ```bash
@@ -134,6 +214,39 @@ When attached to an interactive terminal, `spoti play <query>` asks you to selec
 
 Watch mode continuously refreshes the current track and progress until `Ctrl+C` is pressed. `--watch` enables it for one command, while `--no-watch` overrides a saved preference.
 
+
+### Command aliases
+
+Common aliases include:
+
+```text
+i     interactive  p     play       pa    pause
+r     resume       np    now        q     queue      s     search
+vol   volume     dev   device     devs  devices
+pl    playlist   pls   playlists  rep   repeat
+rec   recent     n     next       prev  previous
+```
+
+### Shell completions
+
+Generate a static completion script without invoking Spotify or making network requests:
+
+```bash
+spoti completion bash
+spoti completion zsh
+spoti completion fish
+```
+
+For the current shell session:
+
+```bash
+source <(spoti completion bash) # Bash
+source <(spoti completion zsh)  # Zsh
+spoti completion fish | source  # Fish
+```
+
+Interactive network operations display a spinner on stderr. Indicators remain disabled outside a TTY.
+
 ## Configuration
 
 View all settings:
@@ -145,9 +258,13 @@ spoti config
 Read, update, or reset settings:
 
 ```bash
+spoti config get spotifyClientId
+spoti config set spotifyClientId "your-client-id"
 spoti config get watchAfterPlay
 spoti config set watchAfterPlay true
 spoti config set refreshIntervalMs 2000
+spoti config unset spotifyClientId
+spoti config path
 spoti config reset
 ```
 
@@ -155,6 +272,7 @@ Available settings:
 
 | Setting | Default | Description |
 | --- | ---: | --- |
+| `spotifyClientId` | `null` | Public Spotify application client ID saved by `spoti setup`. |
 | `watchAfterPlay` | `false` | Keep `spoti play` open in watch mode after playback starts. |
 | `refreshIntervalMs` | `1000` | Watch refresh interval from `1000` to `30000` milliseconds. |
 
@@ -174,7 +292,7 @@ or, when `XDG_CONFIG_HOME` is not set:
 ~/.config/spoti/credentials.json
 ```
 
-The credentials file is created with user-only permissions (`0600`). Access tokens refresh automatically. Version `0.2.0` adds the `user-read-currently-playing` scope for queue access; credentials created by `0.1.0` require one new `spoti login` authorization. Keep `SPOTIFY_CLIENT_ID` available in the environment because Spotify requires it during token refresh. Never provide or store a Spotify client secret in `spoti`.
+The credentials file is created with user-only permissions (`0600`). Access tokens refresh automatically using the environment client ID when present, otherwise the client ID saved by `spoti setup`. Version `0.3.0` adds minimum permissions for private playlist listing, liked-track access, library modification, and recently played tracks. Existing installations will be asked to run `spoti login` once after upgrading. Never provide or store a Spotify client secret in `spoti`.
 
 ## Spotify API policy
 
@@ -206,4 +324,4 @@ The release workflow attaches the npm package tarball and a `SHA256SUMS` file, a
 
 ## Current scope
 
-Version `0.2.0` supports authentication, track search and playback, current playback and watch mode, pause/resume, next/previous, persistent configuration, volume and seek controls, queue management, device listing and selection, and automatic single-device fallback. Shuffle, repeat, album/artist/playlist context playback, library features, JSON output, update notifications, and a TUI are planned for later releases.
+Version `0.3.0` supports authentication and persistent client-ID setup; track, album, artist, and playlist discovery and playback; guided playback actions; current playback and watch mode; player, queue, library, device, and update controls. The current development branch adds explicit interactive search, aliases, loading indicators, shell completions, configuration polish, and Node 24-based GitHub Actions. A full Ink-based TUI remains planned for `v1.0.0`.

package/dist/app.d.ts

@@ -1,22 +1,44 @@
 import { Command } from 'commander';
 import type { AuthService } from './services/auth.service.js';
+import type { CatalogService } from './services/catalog.service.js';
 import type { DeviceService } from './services/device.service.js';
+import type { LibraryService } from './services/library.service.js';
 import type { PlayerService } from './services/player.service.js';
+import type { PlaylistService } from './services/playlist.service.js';
 import type { QueueService } from './services/queue.service.js';
+import type { RecentService } from './services/recent.service.js';
 import type { SearchService } from './services/search.service.js';
+import { type UpdateService } from './services/update.service.js';
 import { type ConfigStore } from './storage/config.js';
 import { type Output } from './ui/output.js';
-import { selectTrack } from './ui/prompts.js';
+import { confirmUpdate, promptSpotifyClientId, selectAlbum, selectAlbumAction, selectArtist, selectArtistAction, selectPlaylist, selectPlaylistAction, selectTrack } from './ui/prompts.js';
+import { type ProgressRunner } from './ui/progress.js';
+import { type InteractiveSearchResult } from './ui/interactive-search.js';
 import { type PlaybackWatcher } from './ui/watch.js';
 export interface AppDependencies {
     auth: AuthService;
+    catalog: CatalogService;
     player: PlayerService;
     search: SearchService;
+    playlist: PlaylistService;
+    library: LibraryService;
+    recent: RecentService;
     device: DeviceService;
     queue: QueueService;
+    update: UpdateService;
     config: ConfigStore;
     output: Output;
     chooseTrack?: typeof selectTrack;
+    chooseAlbum?: typeof selectAlbum;
+    chooseArtist?: typeof selectArtist;
+    choosePlaylist?: typeof selectPlaylist;
+    chooseAlbumAction?: typeof selectAlbumAction;
+    chooseArtistAction?: typeof selectArtistAction;
+    choosePlaylistAction?: typeof selectPlaylistAction;
+    requestSpotifyClientId?: typeof promptSpotifyClientId;
+    confirmUpdate?: typeof confirmUpdate;
+    interactiveSearch?: () => Promise<InteractiveSearchResult>;
+    progress?: ProgressRunner;
     watchPlayback?: PlaybackWatcher;
 }
 export declare function createProgram(dependencies: AppDependencies): Command;