@bzenky/spoti 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 spoti contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# spoti
+
+A local-first command-line client for controlling Spotify through Spotify Connect.
+
+> `spoti` is an independent project and is not affiliated with, endorsed by, or sponsored by Spotify AB.
+
+`spoti` controls playback on an existing Spotify client or Connect device; it does not stream audio itself.
+
+## Requirements
+
+- Node.js 20 or newer
+- A Spotify developer application and client ID
+- Spotify Premium for playback-control commands
+- A Spotify client or Connect device available for playback
+
+## Spotify application setup
+
+Create an application in the [Spotify Developer Dashboard](https://developer.spotify.com/dashboard) and register this exact redirect URI:
+
+```text
+http://127.0.0.1:43821/callback
+```
+
+Export the application's client ID before running authentication:
+
+```bash
+export SPOTIFY_CLIENT_ID="your-client-id"
+```
+
+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"
+```
+
+The redirect URI must use HTTPS except for local development, where an explicit `http://127.0.0.1` URI is allowed. Do not use `localhost` or wildcard redirect URIs. No client secret is needed or accepted by `spoti`; authentication uses Authorization Code with PKCE.
+
+## Installation
+
+Once published to npm:
+
+```bash
+npm install --global @bzenky/spoti
+spoti --help
+```
+
+## Install for development
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+Then verify the executable:
+
+```bash
+spoti --help
+```
+
+You can also run commands without linking:
+
+```bash
+npm run dev -- --help
+npm run dev -- status
+```
+
+## Usage
+
+Authenticate once through Spotify's browser authorization page:
+
+```bash
+spoti login
+spoti status
+```
+
+Control playback:
+
+```bash
+spoti now
+spoti play "Numb"
+spoti play "Numb" --first
+spoti pause
+spoti resume
+spoti next
+spoti previous
+```
+
+Search without starting playback:
+
+```bash
+spoti search "Breaking the Habit"
+spoti search "Breaking the Habit" --limit 5
+```
+
+Remove local credentials:
+
+```bash
+spoti logout
+```
+
+When attached to an interactive terminal, `spoti play <query>` asks you to select a result. In non-interactive usage it chooses the first result automatically; `--first` makes that behavior explicit.
+
+## Credentials
+
+Credentials are stored locally in:
+
+```text
+$XDG_CONFIG_HOME/spoti/credentials.json
+```
+
+or, when `XDG_CONFIG_HOME` is not set:
+
+```text
+~/.config/spoti/credentials.json
+```
+
+The credentials file is created with user-only permissions (`0600`). Access tokens refresh automatically. 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`.
+
+## Spotify API policy
+
+`spoti` uses Spotify data only for immediate command output and playback control. It does not persist Spotify catalog content, use Spotify data for machine-learning training, or download audio. Spotify content and links remain attributed to Spotify.
+
+Endpoint work must be checked against Spotify's [official OpenAPI specification](https://developer.spotify.com/reference/web-api/open-api-schema.yaml) and [Developer Terms](https://developer.spotify.com/terms).
+
+## Development
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+npm run build
+```
+
+## Current scope
+
+Version `0.1.0` supports authentication, current playback, track search, direct track playback, pause/resume, and next/previous controls. Queue, volume, seek, shuffle, repeat, device switching, library features, JSON output, and a TUI are planned for later releases.

package/dist/app.d.ts

@@ -0,0 +1,14 @@
+import { Command } from 'commander';
+import type { AuthService } from './services/auth.service.js';
+import type { PlayerService } from './services/player.service.js';
+import type { SearchService } from './services/search.service.js';
+import { type Output } from './ui/output.js';
+import { selectTrack } from './ui/prompts.js';
+export interface AppDependencies {
+    auth: AuthService;
+    player: PlayerService;
+    search: SearchService;
+    output: Output;
+    chooseTrack?: typeof selectTrack;
+}
+export declare function createProgram(dependencies: AppDependencies): Command;

package/dist/app.js

@@ -0,0 +1,122 @@
+import { Command } from 'commander';
+import { formatPlayback, formatTrack } from './ui/output.js';
+import { selectTrack } from './ui/prompts.js';
+export function createProgram(dependencies) {
+    const program = new Command();
+    const chooseTrack = dependencies.chooseTrack ?? selectTrack;
+    program
+        .name('spoti')
+        .description('Control Spotify from your terminal')
+        .version('0.1.0');
+    program
+        .command('login')
+        .description('Log in to Spotify')
+        .action(async () => {
+        dependencies.output.log('Opening Spotify authorization in your browser…');
+        const user = await dependencies.auth.login();
+        dependencies.output.log(`✓ Logged in as ${user.displayName}`);
+    });
+    program
+        .command('logout')
+        .description('Remove locally stored Spotify credentials')
+        .action(async () => {
+        await dependencies.auth.logout();
+        dependencies.output.log('✓ Logged out');
+    });
+    program
+        .command('status')
+        .description('Show authentication status')
+        .action(async () => {
+        if (!(await dependencies.auth.isAuthenticated())) {
+            dependencies.output.log('Not logged in.\n\nRun: spoti login');
+            return;
+        }
+        const user = await dependencies.auth.getCurrentUser();
+        dependencies.output.log(`✓ Logged in as ${user.displayName}`);
+    });
+    program
+        .command('now')
+        .description('Show the current Spotify playback')
+        .action(async () => {
+        const playback = await dependencies.player.getCurrentPlayback();
+        dependencies.output.log(playback ? formatPlayback(playback) : 'Nothing is currently playing.');
+    });
+    program
+        .command('pause')
+        .description('Pause playback')
+        .action(async () => {
+        await dependencies.player.pause();
+        dependencies.output.log('⏸ Paused');
+    });
+    program
+        .command('resume')
+        .description('Resume playback')
+        .action(async () => {
+        await dependencies.player.resume();
+        dependencies.output.log('▶ Resumed');
+    });
+    program
+        .command('next')
+        .alias('n')
+        .description('Skip to the next track')
+        .action(async () => {
+        await dependencies.player.next();
+        dependencies.output.log('⏭ Skipped to next track');
+    });
+    program
+        .command('previous')
+        .alias('prev')
+        .description('Return to the previous track')
+        .action(async () => {
+        await dependencies.player.previous();
+        dependencies.output.log('⏮ Returned to previous track');
+    });
+    program
+        .command('search')
+        .description('Search Spotify tracks')
+        .argument('<query...>', 'track name to search for')
+        .option('-l, --limit <number>', 'maximum number of results', parseLimit, 10)
+        .action(async (queryParts, options) => {
+        const query = queryParts.join(' ');
+        const tracks = await dependencies.search.searchTracks(query, options.limit);
+        if (tracks.length === 0) {
+            dependencies.output.log(`No tracks found for "${query}".`);
+            return;
+        }
+        dependencies.output.log(tracks.map((track, index) => formatTrack(track, index)).join('\n'));
+    });
+    program
+        .command('play')
+        .description('Search for and play a track, or resume with no query')
+        .argument('[query...]', 'track name to search for')
+        .option('--first', 'play the first search result without prompting')
+        .action(async (queryParts, options) => {
+        const query = queryParts.join(' ').trim();
+        if (!query) {
+            await dependencies.player.resume();
+            dependencies.output.log('▶ Resumed');
+            return;
+        }
+        const tracks = await dependencies.search.searchTracks(query);
+        if (tracks.length === 0) {
+            dependencies.output.log(`No tracks found for "${query}".`);
+            return;
+        }
+        const track = options.first ? tracks[0] : await chooseTrack(tracks);
+        if (!track) {
+            dependencies.output.log('Selection cancelled.');
+            return;
+        }
+        await dependencies.player.playTrack(track.uri);
+        dependencies.output.log(`▶ Playing ${track.name} — ${track.artists.join(', ')}`);
+    });
+    return program;
+}
+function parseLimit(value) {
+    const limit = /^\d+$/.test(value) ? Number(value) : Number.NaN;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 10) {
+        throw new Error('Search limit must be an integer between 1 and 10.');
+    }
+    return limit;
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/auth/callback.d.ts

@@ -0,0 +1,7 @@
+type BrowserOpener = (url: string) => Promise<unknown>;
+export interface AuthorizationCallbackOptions {
+    timeoutMs?: number;
+    openBrowser?: BrowserOpener;
+}
+export declare function requestAuthorizationCode(authorizationUrl: string, redirectUri: string, expectedState: string, options?: AuthorizationCallbackOptions): Promise<string>;
+export {};

package/dist/auth/callback.js

@@ -0,0 +1,79 @@
+import { createServer } from 'node:http';
+import open from 'open';
+import { AppError, AuthorizationDeniedError, toError, } from '../utils/errors.js';
+import { validateRedirectUri } from './config.js';
+const DEFAULT_TIMEOUT_MS = 120_000;
+export function requestAuthorizationCode(authorizationUrl, redirectUri, expectedState, options = {}) {
+    const callbackUrl = validateRedirectUri(redirectUri);
+    const port = Number(callbackUrl.port);
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const openBrowser = options.openBrowser ?? open;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let timer;
+        const server = createServer((request, response) => {
+            const requestUrl = new URL(request.url ?? '/', callbackUrl.origin);
+            if (request.method !== 'GET' || requestUrl.pathname !== callbackUrl.pathname) {
+                response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+                response.end('Not found');
+                return;
+            }
+            const finish = (error, code) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                server.close();
+                if (error)
+                    reject(error);
+                else if (code)
+                    resolve(code);
+                else
+                    reject(new AppError('Spotify authorization returned no code.'));
+            };
+            if (requestUrl.searchParams.get('state') !== expectedState) {
+                response.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' });
+                response.end('Authorization state mismatch. You can close this window.');
+                return;
+            }
+            const authorizationError = requestUrl.searchParams.get('error');
+            if (authorizationError) {
+                const description = requestUrl.searchParams.get('error_description');
+                response.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' });
+                response.end('Spotify authorization was denied. You can close this window.');
+                finish(new AuthorizationDeniedError(description || `Spotify authorization failed: ${authorizationError}`));
+                return;
+            }
+            const code = requestUrl.searchParams.get('code');
+            if (!code) {
+                response.writeHead(400, { 'content-type': 'text/plain; charset=utf-8' });
+                response.end('No authorization code was received. You can close this window.');
+                finish(new AppError('Spotify authorization returned no code.'));
+                return;
+            }
+            response.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' });
+            response.end('Authorization complete. You can close this window.');
+            finish(null, code);
+        });
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            if (server.listening)
+                server.close();
+            reject(toError(error));
+        };
+        server.once('error', fail);
+        server.listen(port, '127.0.0.1', () => {
+            timer = setTimeout(() => {
+                fail(new AuthorizationDeniedError('Spotify authorization timed out after 2 minutes.'));
+            }, timeoutMs);
+            timer.unref();
+            void openBrowser(authorizationUrl).catch(fail);
+        });
+    });
+}
+//# sourceMappingURL=callback.js.map

package/dist/auth/callback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback.js","sourceRoot":"","sources":["../../src/auth/callback.ts"],"names":[],"mappings":"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"}

package/dist/auth/config.d.ts

@@ -0,0 +1,7 @@
+export declare const DEFAULT_REDIRECT_URI = "http://127.0.0.1:43821/callback";
+export interface AuthConfig {
+    clientId: string;
+    redirectUri: string;
+}
+export declare function loadAuthConfig(environment?: NodeJS.ProcessEnv): AuthConfig;
+export declare function validateRedirectUri(redirectUri: string): URL;

package/dist/auth/config.js

@@ -0,0 +1,31 @@
+import { ConfigurationError } from '../utils/errors.js';
+export const DEFAULT_REDIRECT_URI = 'http://127.0.0.1:43821/callback';
+export function loadAuthConfig(environment = process.env) {
+    const clientId = environment.SPOTIFY_CLIENT_ID?.trim();
+    if (!clientId) {
+        throw new ConfigurationError('SPOTIFY_CLIENT_ID is required. Set it to your Spotify application client ID.');
+    }
+    const redirectUri = environment.SPOTIFY_REDIRECT_URI?.trim() || DEFAULT_REDIRECT_URI;
+    validateRedirectUri(redirectUri);
+    return { clientId, redirectUri };
+}
+export function validateRedirectUri(redirectUri) {
+    let url;
+    try {
+        url = new URL(redirectUri);
+    }
+    catch {
+        throw new ConfigurationError('SPOTIFY_REDIRECT_URI must be a valid URL.');
+    }
+    if (url.protocol !== 'http:' ||
+        url.hostname !== '127.0.0.1' ||
+        !url.port ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash) {
+        throw new ConfigurationError('SPOTIFY_REDIRECT_URI must be an HTTP URL on 127.0.0.1 with an explicit port, path, and no query or fragment.');
+    }
+    return url;
+}
+//# sourceMappingURL=config.js.map

package/dist/auth/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/auth/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,MAAM,CAAC,MAAM,oBAAoB,GAAG,iCAAiC,CAAC;AAOtE,MAAM,UAAU,cAAc,CAC5B,cAAiC,OAAO,CAAC,GAAG;IAE5C,MAAM,QAAQ,GAAG,WAAW,CAAC,iBAAiB,EAAE,IAAI,EAAE,CAAC;IACvD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,kBAAkB,CAC1B,8EAA8E,CAC/E,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GAAG,WAAW,CAAC,oBAAoB,EAAE,IAAI,EAAE,IAAI,oBAAoB,CAAC;IACrF,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAEjC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,WAAmB;IACrD,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QACH,GAAG,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,kBAAkB,CAAC,2CAA2C,CAAC,CAAC;IAC5E,CAAC;IAED,IACE,GAAG,CAAC,QAAQ,KAAK,OAAO;QACxB,GAAG,CAAC,QAAQ,KAAK,WAAW;QAC5B,CAAC,GAAG,CAAC,IAAI;QACT,GAAG,CAAC,QAAQ;QACZ,GAAG,CAAC,QAAQ;QACZ,GAAG,CAAC,MAAM;QACV,GAAG,CAAC,IAAI,EACR,CAAC;QACD,MAAM,IAAI,kBAAkB,CAC1B,8GAA8G,CAC/G,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/auth/index.d.ts

@@ -0,0 +1,8 @@
+export { requestAuthorizationCode } from './callback.js';
+export type { AuthorizationCallbackOptions } from './callback.js';
+export { DEFAULT_REDIRECT_URI, loadAuthConfig, validateRedirectUri, } from './config.js';
+export type { AuthConfig } from './config.js';
+export { createCodeChallenge, generateOAuthState, generatePkcePair, } from './pkce.js';
+export type { PkcePair } from './pkce.js';
+export { SpotifyAuthClient } from './spotify-auth-client.js';
+export type { ExchangeCodeInput, RefreshTokenInput, SpotifyAuthApi, TokenSet, } from './spotify-auth-client.js';

package/dist/auth/index.js

@@ -0,0 +1,5 @@
+export { requestAuthorizationCode } from './callback.js';
+export { DEFAULT_REDIRECT_URI, loadAuthConfig, validateRedirectUri, } from './config.js';
+export { createCodeChallenge, generateOAuthState, generatePkcePair, } from './pkce.js';
+export { SpotifyAuthClient } from './spotify-auth-client.js';
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AAEzD,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,mBAAmB,GACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/auth/pkce.d.ts

@@ -0,0 +1,7 @@
+export interface PkcePair {
+    verifier: string;
+    challenge: string;
+}
+export declare function createCodeChallenge(verifier: string): string;
+export declare function generatePkcePair(): PkcePair;
+export declare function generateOAuthState(): string;

package/dist/auth/pkce.js

@@ -0,0 +1,15 @@
+import { createHash, randomBytes } from 'node:crypto';
+export function createCodeChallenge(verifier) {
+    return createHash('sha256').update(verifier, 'ascii').digest('base64url');
+}
+export function generatePkcePair() {
+    const verifier = randomBytes(64).toString('base64url');
+    return {
+        verifier,
+        challenge: createCodeChallenge(verifier),
+    };
+}
+export function generateOAuthState() {
+    return randomBytes(32).toString('base64url');
+}
+//# sourceMappingURL=pkce.js.map

package/dist/auth/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../../src/auth/pkce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAOtD,MAAM,UAAU,mBAAmB,CAAC,QAAgB;IAClD,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,gBAAgB;IAC9B,MAAM,QAAQ,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IACvD,OAAO;QACL,QAAQ;QACR,SAAS,EAAE,mBAAmB,CAAC,QAAQ,CAAC;KACzC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,kBAAkB;IAChC,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AAC/C,CAAC"}

package/dist/auth/spotify-auth-client.d.ts

@@ -0,0 +1,38 @@
+import type { UserProfile } from '../services/models.js';
+import { AppError } from '../utils/errors.js';
+type Sleep = (milliseconds: number) => Promise<void>;
+export interface TokenSet {
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn: number;
+}
+export interface ExchangeCodeInput {
+    clientId: string;
+    code: string;
+    redirectUri: string;
+    codeVerifier: string;
+}
+export interface RefreshTokenInput {
+    clientId: string;
+    refreshToken: string;
+}
+export declare class OAuthTokenError extends AppError {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface SpotifyAuthApi {
+    exchangeCode(input: ExchangeCodeInput): Promise<TokenSet>;
+    refreshAccessToken(input: RefreshTokenInput): Promise<TokenSet>;
+    getCurrentUser(accessToken: string): Promise<UserProfile>;
+}
+export declare class SpotifyAuthClient implements SpotifyAuthApi {
+    private readonly fetchImplementation;
+    private readonly sleeper;
+    constructor(fetchImplementation?: typeof globalThis.fetch, sleeper?: Sleep);
+    exchangeCode(input: ExchangeCodeInput): Promise<TokenSet>;
+    refreshAccessToken(input: RefreshTokenInput): Promise<TokenSet>;
+    getCurrentUser(accessToken: string): Promise<UserProfile>;
+    private requestToken;
+    private fetchWithTimeout;
+}
+export {};