morille 0.1.0

package/dist/spotify/lyrics.d.ts

@@ -0,0 +1,25 @@
+export type LyricLine = {
+    timeMs: number;
+    text: string;
+};
+export type Lyrics = {
+    synced: LyricLine[];
+    plain: string | null;
+};
+/**
+ * Fetches lyrics for a track from LRCLIB (https://lrclib.net).
+ * Deduplicates concurrent requests for the same track - if a fetch is already
+ * in flight, returns the same promise instead of starting a new request.
+ * @param trackName - Name of the track
+ * @param artistName - Name of the artist
+ * @param durationMs - Duration of the track in milliseconds
+ * @returns Lyrics object, or null if not found
+ */
+export declare function fetchLyrics(trackName: string, artistName: string, durationMs: number): Promise<Lyrics | null>;
+/**
+ * Finds the index of the current lyric line based on playback progress.
+ * @param lines - Sorted array of synced lyric lines
+ * @param progressMs - Current playback position in milliseconds
+ * @returns Index of the current line, or -1 if before the first line
+ */
+export declare function getCurrentLineIndex(lines: LyricLine[], progressMs: number, offsetMs?: number): number;

package/dist/spotify/lyrics.js

@@ -0,0 +1,130 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { CONFIG_DIR } from '../config.js';
+import { fetchWithRetry } from './fetch-with-retry.js';
+const LYRICS_CACHE_DIR = join(CONFIG_DIR, 'lyrics-cache');
+function getCachePath(trackName, artistName) {
+    const hash = createHash('sha256').update(`${trackName}::${artistName}`).digest('hex').slice(0, 16);
+    return join(LYRICS_CACHE_DIR, `${hash}.json`);
+}
+function readDiskCache(trackName, artistName) {
+    const path = getCachePath(trackName, artistName);
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeDiskCache(trackName, artistName, lyrics) {
+    mkdirSync(LYRICS_CACHE_DIR, {
+        recursive: true,
+    });
+    writeFileSync(getCachePath(trackName, artistName), JSON.stringify(lyrics));
+}
+/**
+ * Parses a single LRC-format line into a timestamped lyric.
+ * Format: "[mm:ss.xx] text"
+ * @returns Parsed lyric line, or null if the line doesn't match
+ */
+function parseLrcLine(line) {
+    const match = /^\[(\d{2}):(\d{2})\.(\d{2,3})\]\s*(.*)$/.exec(line);
+    if (!match)
+        return null;
+    const minutes = Number.parseInt(match[1], 10);
+    const seconds = Number.parseInt(match[2], 10);
+    const centiseconds = match[3].length === 2 ? Number.parseInt(match[3], 10) * 10 : Number.parseInt(match[3], 10);
+    const timeMs = minutes * 60_000 + seconds * 1000 + centiseconds;
+    const text = match[4];
+    return {
+        timeMs,
+        text,
+    };
+}
+/**
+ * Parses a full LRC-format string into an array of timestamped lyrics.
+ * @param lrc - LRC format string with one "[mm:ss.xx] text" per line
+ * @returns Sorted array of lyric lines
+ */
+function parseLrc(lrc) {
+    const lines = [];
+    for (const line of lrc.split('\n')) {
+        const parsed = parseLrcLine(line.trim());
+        if (parsed) {
+            lines.push(parsed);
+        }
+    }
+    return lines.sort((a, b) => a.timeMs - b.timeMs);
+}
+const inflight = new Map();
+/**
+ * Fetches lyrics for a track from LRCLIB (https://lrclib.net).
+ * Deduplicates concurrent requests for the same track - if a fetch is already
+ * in flight, returns the same promise instead of starting a new request.
+ * @param trackName - Name of the track
+ * @param artistName - Name of the artist
+ * @param durationMs - Duration of the track in milliseconds
+ * @returns Lyrics object, or null if not found
+ */
+export function fetchLyrics(trackName, artistName, durationMs) {
+    const cached = readDiskCache(trackName, artistName);
+    if (cached)
+        return Promise.resolve(cached);
+    const key = `${trackName}::${artistName}`;
+    const pending = inflight.get(key);
+    if (pending)
+        return pending;
+    const promise = doFetch(trackName, artistName, durationMs).finally(() => {
+        inflight.delete(key);
+    });
+    inflight.set(key, promise);
+    return promise;
+}
+async function doFetch(trackName, artistName, durationMs) {
+    const durationSecs = Math.round(durationMs / 1000);
+    const params = new URLSearchParams({
+        track_name: trackName,
+        artist_name: artistName,
+        duration: durationSecs.toString(),
+    });
+    try {
+        const response = await fetchWithRetry(`https://lrclib.net/api/get?${params.toString()}`);
+        if (!response.ok)
+            return null;
+        const data = (await response.json());
+        const synced = data.syncedLyrics ? parseLrc(data.syncedLyrics) : [];
+        const plain = data.plainLyrics ?? null;
+        if (synced.length === 0 && !plain)
+            return null;
+        const lyrics = {
+            synced,
+            plain,
+        };
+        writeDiskCache(trackName, artistName, lyrics);
+        return lyrics;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Finds the index of the current lyric line based on playback progress.
+ * @param lines - Sorted array of synced lyric lines
+ * @param progressMs - Current playback position in milliseconds
+ * @returns Index of the current line, or -1 if before the first line
+ */
+export function getCurrentLineIndex(lines, progressMs, offsetMs = 0) {
+    let index = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].timeMs - offsetMs <= progressMs) {
+            index = i;
+        }
+        else {
+            break;
+        }
+    }
+    return index;
+}

package/dist/spotify/playback.d.ts

@@ -0,0 +1,115 @@
+import type { PlaybackState, SpotifyApi } from '@spotify/web-api-ts-sdk';
+export type RepeatMode = 'off' | 'context' | 'track';
+export type PlaybackContext = {
+    type: string;
+    uri: string;
+};
+export type TrackInfo = {
+    name: string;
+    artist: string;
+    album: string;
+    isPlaying: boolean;
+    progressMs: number;
+    durationMs: number;
+    deviceId: string | null;
+    volume: number | null;
+    shuffle: boolean;
+    repeat: RepeatMode;
+    albumImageUrl: string | null;
+    context: PlaybackContext | null;
+    uri: string;
+};
+/**
+ * Fetches the current playback state from Spotify.
+ * @param client - Authenticated Spotify API client
+ * @returns The current playback state, or `null` if no device is active
+ */
+export declare function getPlaybackState(client: SpotifyApi): Promise<PlaybackState | null>;
+/**
+ * Resumes playback on the specified device.
+ * @param client - Authenticated Spotify API client
+ * @param deviceId - Target device ID
+ */
+export declare function play(client: SpotifyApi, deviceId: string): Promise<void>;
+/**
+ * Plays a specific track within a playlist/album/collection context.
+ * Uses URI-based offset to jump directly to the track in one API call.
+ * @param client - Authenticated Spotify API client
+ * @param deviceId - Target device ID
+ * @param contextUri - Spotify URI of the context (e.g. "spotify:playlist:..." or "spotify:album:...")
+ * @param trackUri - Spotify URI of the track to play within the context
+ */
+export declare function playInContext(client: SpotifyApi, deviceId: string, contextUri: string, trackUri: string): Promise<void>;
+/**
+ * Starts playback of an entire context (album, playlist, or collection) from the beginning.
+ * @param client - Authenticated Spotify API client
+ * @param deviceId - Target device ID
+ * @param contextUri - Spotify URI of the context (e.g. "spotify:album:..." or "spotify:playlist:...")
+ */
+export declare function playContext(client: SpotifyApi, deviceId: string, contextUri: string): Promise<void>;
+/**
+ * Starts playback of a specific track by URI on the specified device.
+ * @param client - Authenticated Spotify API client
+ * @param deviceId - Target device ID
+ * @param uri - Spotify URI of the track to play (e.g. "spotify:track:...")
+ */
+export declare function playUri(client: SpotifyApi, deviceId: string, uri: string): Promise<void>;
+/**
+ * Pauses playback on the specified device.
+ * @param client - Authenticated Spotify API client
+ * @param deviceId - Target device ID
+ */
+export declare function pause(client: SpotifyApi, deviceId: string): Promise<void>;
+/**
+ * Skips to the next track on the specified device.
+ * @param client - Authenticated Spotify API client
+ * @param deviceId - Target device ID
+ */
+export declare function skipNext(client: SpotifyApi, deviceId: string): Promise<void>;
+/**
+ * Skips to the previous track on the specified device.
+ * @param client - Authenticated Spotify API client
+ * @param deviceId - Target device ID
+ */
+export declare function skipPrevious(client: SpotifyApi, deviceId: string): Promise<void>;
+/**
+ * Seeks to a position in the currently playing track.
+ * @param client - Authenticated Spotify API client
+ * @param positionMs - Position in milliseconds to seek to
+ * @param deviceId - Target device ID
+ */
+export declare function seek(client: SpotifyApi, positionMs: number, deviceId?: string): Promise<void>;
+/**
+ * Sets the playback volume.
+ * @param client - Authenticated Spotify API client
+ * @param volumePercent - Volume level from 0 to 100
+ * @param deviceId - Target device ID
+ */
+export declare function setVolume(client: SpotifyApi, volumePercent: number, deviceId?: string): Promise<void>;
+/**
+ * Sets the shuffle mode.
+ * @param client - Authenticated Spotify API client
+ * @param state - Whether shuffle should be enabled
+ * @param deviceId - Target device ID
+ */
+export declare function setShuffle(client: SpotifyApi, state: boolean, deviceId?: string): Promise<void>;
+/**
+ * Sets the repeat mode.
+ * @param client - Authenticated Spotify API client
+ * @param state - Repeat mode: 'off', 'context' (playlist/album), or 'track'
+ * @param deviceId - Target device ID
+ */
+export declare function setRepeat(client: SpotifyApi, state: RepeatMode, deviceId?: string): Promise<void>;
+/**
+ * Toggles playback between playing and paused on the active device.
+ * @param client - Authenticated Spotify API client
+ * @returns `true` if playback is now playing, `false` if paused
+ * @throws When no active Spotify device is found
+ */
+export declare function togglePlayback(client: SpotifyApi): Promise<boolean>;
+/**
+ * Fetches simplified info about the currently playing track.
+ * @param client - Authenticated Spotify API client
+ * @returns Current track info, or `null` if nothing is playing
+ */
+export declare function getCurrentTrackInfo(client: SpotifyApi): Promise<TrackInfo | null>;

package/dist/spotify/playback.js

@@ -0,0 +1,201 @@
+/**
+ * Fetches the current playback state from Spotify.
+ * @param client - Authenticated Spotify API client
+ * @returns The current playback state, or `null` if no device is active
+ */
+export async function getPlaybackState(client) {
+    try {
+        const state = await client.player.getPlaybackState();
+        return state ?? null;
+    }
+    catch (err) {
+        // The SDK's deserializer calls JSON.parse on any non-204 response.
+        // Spotify can briefly return non-JSON bodies during state transitions
+        // (e.g. right after pause/skip). Treat parse failures as "no state available".
+        if (err instanceof SyntaxError) {
+            return null;
+        }
+        throw err;
+    }
+}
+/**
+ * Resumes playback on the specified device.
+ * @param client - Authenticated Spotify API client
+ * @param deviceId - Target device ID
+ */
+export async function play(client, deviceId) {
+    await ignoreSdkParseError(() => client.player.startResumePlayback(deviceId));
+}
+/**
+ * Plays a specific track within a playlist/album/collection context.
+ * Uses URI-based offset to jump directly to the track in one API call.
+ * @param client - Authenticated Spotify API client
+ * @param deviceId - Target device ID
+ * @param contextUri - Spotify URI of the context (e.g. "spotify:playlist:..." or "spotify:album:...")
+ * @param trackUri - Spotify URI of the track to play within the context
+ */
+export async function playInContext(client, deviceId, contextUri, trackUri) {
+    await ignoreSdkParseError(() => client.player.startResumePlayback(deviceId, contextUri, undefined, {
+        uri: trackUri,
+    }));
+}
+/**
+ * Starts playback of an entire context (album, playlist, or collection) from the beginning.
+ * @param client - Authenticated Spotify API client
+ * @param deviceId - Target device ID
+ * @param contextUri - Spotify URI of the context (e.g. "spotify:album:..." or "spotify:playlist:...")
+ */
+export async function playContext(client, deviceId, contextUri) {
+    await ignoreSdkParseError(() => client.player.startResumePlayback(deviceId, contextUri));
+}
+/**
+ * Starts playback of a specific track by URI on the specified device.
+ * @param client - Authenticated Spotify API client
+ * @param deviceId - Target device ID
+ * @param uri - Spotify URI of the track to play (e.g. "spotify:track:...")
+ */
+export async function playUri(client, deviceId, uri) {
+    await ignoreSdkParseError(() => client.player.startResumePlayback(deviceId, undefined, [
+        uri,
+    ]));
+}
+/**
+ * Pauses playback on the specified device.
+ * @param client - Authenticated Spotify API client
+ * @param deviceId - Target device ID
+ */
+export async function pause(client, deviceId) {
+    await ignoreSdkParseError(() => client.player.pausePlayback(deviceId));
+}
+/**
+ * Skips to the next track on the specified device.
+ * @param client - Authenticated Spotify API client
+ * @param deviceId - Target device ID
+ */
+export async function skipNext(client, deviceId) {
+    await ignoreSdkParseError(() => client.player.skipToNext(deviceId));
+}
+/**
+ * Skips to the previous track on the specified device.
+ * @param client - Authenticated Spotify API client
+ * @param deviceId - Target device ID
+ */
+export async function skipPrevious(client, deviceId) {
+    await ignoreSdkParseError(() => client.player.skipToPrevious(deviceId));
+}
+/**
+ * Seeks to a position in the currently playing track.
+ * @param client - Authenticated Spotify API client
+ * @param positionMs - Position in milliseconds to seek to
+ * @param deviceId - Target device ID
+ */
+export async function seek(client, positionMs, deviceId) {
+    await ignoreSdkParseError(() => client.player.seekToPosition(positionMs, deviceId));
+}
+/**
+ * Sets the playback volume.
+ * @param client - Authenticated Spotify API client
+ * @param volumePercent - Volume level from 0 to 100
+ * @param deviceId - Target device ID
+ */
+export async function setVolume(client, volumePercent, deviceId) {
+    await ignoreSdkParseError(() => client.player.setPlaybackVolume(volumePercent, deviceId));
+}
+/**
+ * Sets the shuffle mode.
+ * @param client - Authenticated Spotify API client
+ * @param state - Whether shuffle should be enabled
+ * @param deviceId - Target device ID
+ */
+export async function setShuffle(client, state, deviceId) {
+    await ignoreSdkParseError(() => client.player.togglePlaybackShuffle(state, deviceId));
+}
+/**
+ * Sets the repeat mode.
+ * @param client - Authenticated Spotify API client
+ * @param state - Repeat mode: 'off', 'context' (playlist/album), or 'track'
+ * @param deviceId - Target device ID
+ */
+export async function setRepeat(client, state, deviceId) {
+    await ignoreSdkParseError(() => client.player.setRepeatMode(state, deviceId));
+}
+/**
+ * Wraps an SDK call to swallow SyntaxErrors from the deserializer.
+ * The SDK calls JSON.parse on any non-204 response body. Spotify's player
+ * control endpoints sometimes return 200 with a non-JSON body instead of 204,
+ * which causes a SyntaxError. The action still succeeds server-side.
+ */
+async function ignoreSdkParseError(fn) {
+    try {
+        await fn();
+    }
+    catch (err) {
+        if (err instanceof SyntaxError) {
+            return;
+        }
+        // Translate the SDK's misleading 403 message for player restriction errors
+        if (err instanceof Error && err.message.includes('Restriction violated')) {
+            console.error('Action failed due to Spotify playback restrictions:', err);
+            throw new Error('Action not available for the current playback context');
+        }
+        console.error('Unexpected error during playback control:', err);
+        throw err;
+    }
+}
+/**
+ * Toggles playback between playing and paused on the active device.
+ * @param client - Authenticated Spotify API client
+ * @returns `true` if playback is now playing, `false` if paused
+ * @throws When no active Spotify device is found
+ */
+export async function togglePlayback(client) {
+    const state = await getPlaybackState(client);
+    if (!state) {
+        throw new Error('No active Spotify device found. Start playing on any Spotify client first.');
+    }
+    const deviceId = state.device.id;
+    if (!deviceId) {
+        throw new Error('Active device has no ID.');
+    }
+    if (state.is_playing) {
+        await pause(client, deviceId);
+        return false;
+    }
+    await play(client, deviceId);
+    return true;
+}
+/**
+ * Fetches simplified info about the currently playing track.
+ * @param client - Authenticated Spotify API client
+ * @returns Current track info, or `null` if nothing is playing
+ */
+export async function getCurrentTrackInfo(client) {
+    const state = await getPlaybackState(client);
+    if (!state?.item) {
+        return null;
+    }
+    const { item } = state;
+    const artist = 'artists' in item ? item.artists.map((a) => a.name).join(', ') : 'Unknown';
+    const album = 'album' in item ? item.album.name : '';
+    const albumImageUrl = 'album' in item && item.album.images.length > 0 ? item.album.images[item.album.images.length - 1].url : null;
+    return {
+        name: item.name,
+        artist,
+        album,
+        isPlaying: state.is_playing,
+        progressMs: state.progress_ms,
+        durationMs: item.duration_ms,
+        deviceId: state.device.id,
+        volume: state.device.volume_percent,
+        shuffle: state.shuffle_state,
+        repeat: state.repeat_state,
+        albumImageUrl,
+        context: state.context
+            ? {
+                type: state.context.type,
+                uri: state.context.uri,
+            }
+            : null,
+        uri: item.uri,
+    };
+}

package/dist/spotify/search.d.ts

@@ -0,0 +1,79 @@
+import type { SpotifyApi } from '@spotify/web-api-ts-sdk';
+export type SearchResultTrack = {
+    name: string;
+    artist: string;
+    album: string;
+    uri: string;
+    durationMs: number;
+    albumUri: string;
+};
+export type SearchResultAlbum = {
+    name: string;
+    artist: string;
+    uri: string;
+    id: string;
+    imageUrl: string | null;
+    totalTracks: number;
+};
+export type SearchResultPlaylist = {
+    name: string;
+    owner: string;
+    uri: string;
+    id: string;
+    totalTracks: number;
+};
+export type SearchResultArtist = {
+    name: string;
+    uri: string;
+    id: string;
+};
+export type SearchResults = {
+    tracks: SearchResultTrack[];
+    albums: SearchResultAlbum[];
+    artists: SearchResultArtist[];
+    playlists: SearchResultPlaylist[];
+};
+export type BrowseTrack = {
+    name: string;
+    artist: string;
+    uri: string;
+    durationMs: number;
+};
+export type AlbumDetail = {
+    name: string;
+    artist: string;
+    uri: string;
+    tracks: BrowseTrack[];
+};
+export type PlaylistDetail = {
+    name: string;
+    owner: string;
+    uri: string;
+    tracks: BrowseTrack[];
+};
+export declare function searchSpotify(client: SpotifyApi, query: string, limit?: number): Promise<SearchResults>;
+/**
+ * Fetches full album details including track list.
+ * @param client - Authenticated Spotify API client
+ * @param albumId - Spotify album ID
+ * @returns Album metadata and track list
+ */
+export declare function fetchAlbumTracks(client: SpotifyApi, albumId: string): Promise<AlbumDetail>;
+/**
+ * Fetches full playlist details including track list.
+ * @param client - Authenticated Spotify API client
+ * @param playlistId - Spotify playlist ID
+ * @returns Playlist metadata and track list
+ */
+export declare function fetchPlaylistTracks(client: SpotifyApi, playlistId: string): Promise<PlaylistDetail>;
+/**
+ * Fetches the current user's playlists.
+ * @param client - Authenticated Spotify API client
+ * @param limit - Max number of playlists to return (default: USER_PLAYLISTS_LIMIT)
+ * @param offset - Pagination offset
+ * @returns List of simplified playlist items and total count
+ */
+export declare function fetchUserPlaylists(client: SpotifyApi, limit?: number, offset?: number): Promise<{
+    items: SearchResultPlaylist[];
+    total: number;
+}>;

package/dist/spotify/search.js

@@ -0,0 +1,143 @@
+import { SEARCH_RESULTS_LIMIT, USER_PLAYLISTS_LIMIT } from '../config.js';
+/**
+ * Searches Spotify for tracks, albums, artists, and playlists matching the query.
+ * @param client - Authenticated Spotify API client
+ * @param query - Search query string
+ * @param limit - Max results per category (default: SEARCH_RESULTS_LIMIT)
+ * @returns Categorized search results
+ */
+// Multi-type search reliably rejects values above this with `400 Invalid limit`,
+// even though the Spotify docs claim `max=50` for single-type searches.
+const MULTI_TYPE_SEARCH_MAX_LIMIT = 20;
+export async function searchSpotify(client, query, limit = SEARCH_RESULTS_LIMIT) {
+    const safeLimit = Math.max(1, Math.min(limit, MULTI_TYPE_SEARCH_MAX_LIMIT));
+    const data = await client.search(query, [
+        'track',
+        'album',
+        'artist',
+        'playlist',
+    ], undefined, safeLimit);
+    // SDK returns null when the access token is empty or an error is silently handled
+    if (!data) {
+        return {
+            tracks: [],
+            albums: [],
+            artists: [],
+            playlists: [],
+        };
+    }
+    // Spotify search can return null entries in items arrays — filter them out
+    const tracks = (data.tracks?.items ?? []).filter(Boolean).map((t) => ({
+        name: t.name,
+        artist: t.artists.map((a) => a.name).join(', '),
+        album: t.album.name,
+        uri: t.uri,
+        durationMs: t.duration_ms,
+        albumUri: t.album.uri,
+    }));
+    const albums = (data.albums?.items ?? []).filter(Boolean).map((a) => ({
+        name: a.name,
+        artist: a.artists.map((ar) => ar.name).join(', '),
+        uri: a.uri,
+        id: a.id,
+        imageUrl: a.images.length > 0 ? a.images[a.images.length - 1].url : null,
+        totalTracks: a.total_tracks,
+    }));
+    const artists = (data.artists?.items ?? []).filter(Boolean).map((ar) => ({
+        name: ar.name,
+        uri: ar.uri,
+        id: ar.id,
+    }));
+    // SDK types search playlists as PlaylistBase (no tracks field),
+    // but the API response includes tracks.total — cast to access it.
+    const playlists = (data.playlists?.items ?? []).filter(Boolean).map((p) => {
+        const trackRef = p.tracks;
+        return {
+            name: p.name,
+            owner: p.owner.display_name ?? p.owner.id,
+            uri: p.uri,
+            id: p.id,
+            totalTracks: trackRef?.total ?? 0,
+        };
+    });
+    return {
+        tracks,
+        albums,
+        artists,
+        playlists,
+    };
+}
+/**
+ * Fetches full album details including track list.
+ * @param client - Authenticated Spotify API client
+ * @param albumId - Spotify album ID
+ * @returns Album metadata and track list
+ */
+export async function fetchAlbumTracks(client, albumId) {
+    const album = await client.albums.get(albumId);
+    if (!album)
+        throw new Error('Failed to fetch album');
+    return {
+        name: album.name,
+        artist: album.artists.map((a) => a.name).join(', '),
+        uri: album.uri,
+        tracks: album.tracks.items.filter(Boolean).map((t) => ({
+            name: t.name,
+            artist: t.artists.map((a) => a.name).join(', '),
+            uri: t.uri,
+            durationMs: t.duration_ms,
+        })),
+    };
+}
+/**
+ * Fetches full playlist details including track list.
+ * @param client - Authenticated Spotify API client
+ * @param playlistId - Spotify playlist ID
+ * @returns Playlist metadata and track list
+ */
+export async function fetchPlaylistTracks(client, playlistId) {
+    const playlist = await client.playlists.getPlaylist(playlistId);
+    if (!playlist)
+        throw new Error('Failed to fetch playlist');
+    return {
+        name: playlist.name,
+        owner: playlist.owner.display_name ?? playlist.owner.id,
+        uri: playlist.uri,
+        tracks: playlist.tracks.items
+            .filter((item) => item.track)
+            .map((item) => {
+            const t = item.track;
+            return {
+                name: t.name,
+                artist: 'artists' in t ? t.artists.map((a) => a.name).join(', ') : 'Unknown',
+                uri: t.uri,
+                durationMs: t.duration_ms,
+            };
+        }),
+    };
+}
+/**
+ * Fetches the current user's playlists.
+ * @param client - Authenticated Spotify API client
+ * @param limit - Max number of playlists to return (default: USER_PLAYLISTS_LIMIT)
+ * @param offset - Pagination offset
+ * @returns List of simplified playlist items and total count
+ */
+export async function fetchUserPlaylists(client, limit = USER_PLAYLISTS_LIMIT, offset = 0) {
+    const page = await client.currentUser.playlists.playlists(limit, offset);
+    if (!page)
+        return {
+            items: [],
+            total: 0,
+        };
+    return {
+        items: page.items.filter(Boolean).map((p) => ({
+            name: p.name,
+            owner: p.owner.display_name ?? p.owner.id,
+            uri: p.uri,
+            id: p.id,
+            totalTracks: p.tracks?.total ?? 0,
+        })),
+        total: page.total,
+    };
+}