plx-converter 0.1.0 → 0.1.2

package/dist/config.js

@@ -3,65 +3,74 @@ import { homedir, platform } from 'node:os';
 import { join } from 'node:path';
 import 'dotenv/config';
 import { fetchBrowserCredentials } from './browser.js';
+// The env override for each provider. The variable name is historical per provider; the value it
+// carries is still opaque here.
+const ENV_VAR = { deezer: 'DEEZER_ARL', spotify: 'SPOTIFY_DC', ytmusic: 'YTMUSIC_COOKIE' };
+// The pre-provider-keyed shape stored one named field per cookie. These are deliberately not
+// migrated (see #1): they are ignored, dropped on the next write, and the user re-fetches or
+// re-pastes — which costs one browser dialog.
+const LEGACY_KEYS = ['deezerArl', 'spotifyDc'];
 export function configDir() {
     if (platform() === 'win32')
         return join(process.env.APPDATA ?? join(homedir(), 'AppData', 'Roaming'), 'plx');
     return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'plx');
 }
 const file = () => join(configDir(), 'credentials.json');
-export async function loadConfig(requireDeezer = true) {
-    let stored = {};
-    try {
-        stored = JSON.parse(await readFile(file(), 'utf8'));
+async function loadStored() { try {
+    return JSON.parse(await readFile(file(), 'utf8'));
+}
+catch {
+    return {};
+} }
+export async function loadConfig() {
+    const stored = await loadStored();
+    const credentials = { ...(stored.credentials ?? {}) };
+    for (const [provider, envVar] of Object.entries(ENV_VAR)) {
+        const value = process.env[envVar];
+        if (value)
+            credentials[provider] = value;
     }
-    catch { /* first run */ }
-    const cfg = { deezerArl: process.env.DEEZER_ARL ?? stored.deezerArl ?? '', spotifyDc: process.env.SPOTIFY_DC ?? stored.spotifyDc ?? '', recentUrls: stored.recentUrls ?? [] };
-    if (requireDeezer && !cfg.deezerArl)
-        throw new Error('Konfigurasi kurang: DEEZER_ARL');
-    return cfg;
+    const legacyCredentials = !stored.credentials && LEGACY_KEYS.some((key) => typeof stored[key] === 'string' && stored[key]);
+    return { credentials, recentUrls: stored.recentUrls ?? [], legacyCredentials };
+}
+// The credential for one provider, or '' when there is none. Callers decide whether they need it.
+export function credential(cfg, provider) { return cfg.credentials[provider] ?? ''; }
+export async function saveCredential(cfg, provider, value) {
+    cfg.credentials[provider] = value;
+    await write({ credentials: cfg.credentials });
 }
 export async function saveRecentUrl(url) {
     const stored = await loadStored();
     const list = Array.isArray(stored.recentUrls) ? stored.recentUrls : [];
-    const next = [url, ...list.filter((u) => u !== url)].slice(0, 10);
-    await saveCredentials({ recentUrls: next });
+    await write({ recentUrls: [url, ...list.filter((u) => u !== url)].slice(0, 10) });
 }
-export async function saveCredentials(values) {
+async function write(patch) {
     await mkdir(configDir(), { recursive: true, mode: 0o700 });
     const current = await loadStored();
-    await writeFile(file(), JSON.stringify({ ...current, ...values }, null, 2), { mode: 0o600 });
+    for (const key of LEGACY_KEYS)
+        delete current[key]; // clean the old shape out on first write
+    await writeFile(file(), JSON.stringify({ ...current, ...patch }, null, 2), { mode: 0o600 });
     try {
         await chmod(file(), 0o600);
     }
     catch { /* Windows */ }
 }
-async function loadStored() { try {
-    return JSON.parse(await readFile(file(), 'utf8'));
-}
-catch {
-    return {};
-} }
-// Semi-auto: fill credentials from a logged-in browser (pops the macOS Keychain
-// "Allow" dialog on first use), persist what's found, and return the field names
-// filled. By default only fills *missing* fields (env vars and stored credentials
-// win); pass overwrite=true to refetch and replace whatever the browser has. Never
-// throws — a denied keychain / TCC block just fills nothing, and the caller falls
-// back to the manual paste prompt.
+// Semi-auto: fill credentials from a logged-in browser (pops the macOS Keychain "Allow" dialog on
+// first use), persist what's found, and return the provider names filled. By default only fills
+// providers with no credential yet (env vars and stored credentials win); pass overwrite=true to
+// refetch and replace. Never throws — a denied keychain / TCC block just fills nothing, and the
+// caller falls back to the manual paste prompt.
 export async function tryAutoFillCredentials(cfg, overwrite = false) {
+    if (!overwrite && Object.keys(ENV_VAR).every((provider) => cfg.credentials[provider]))
+        return [];
     const filled = [];
-    const want = overwrite || !cfg.deezerArl || !cfg.spotifyDc;
-    if (!want)
-        return filled;
-    const found = fetchBrowserCredentials();
-    if ((overwrite || !cfg.deezerArl) && found.arl) {
-        cfg.deezerArl = found.arl;
-        filled.push('deezerArl');
-    }
-    if ((overwrite || !cfg.spotifyDc) && found.spDc) {
-        cfg.spotifyDc = found.spDc;
-        filled.push('spotifyDc');
+    for (const [provider, value] of Object.entries(fetchBrowserCredentials())) {
+        if (!value || (!overwrite && cfg.credentials[provider]))
+            continue;
+        cfg.credentials[provider] = value;
+        filled.push(provider);
     }
     if (filled.length)
-        await saveCredentials({ deezerArl: cfg.deezerArl, spotifyDc: cfg.spotifyDc });
+        await write({ credentials: cfg.credentials });
     return filled;
 }

package/dist/conversion.js

@@ -0,0 +1,143 @@
+import { matchCandidates } from './matcher.js';
+import { writeCsv } from './csv.js';
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// One conversion path for every direction: read the playlist from `source`, match each track into
+// `target`, report. Both providers are parameters, so N providers give N×(N−1) directions without
+// a line of direction-specific code.
+//
+// Where the target can resolve a track by identifier, each match is re-resolved and compared to the
+// source track; a match that diverges is still written but flagged in the report. Where the target
+// can reorder, the target order is synced to the source; where it cannot, the conversion still
+// completes by appending (ADR 0002).
+export class Conversion {
+    source;
+    target;
+    output;
+    rows = [];
+    constructor(source, target, output) {
+        this.source = source;
+        this.target = target;
+        this.output = output;
+    }
+    // Every row carries the direction that produced it, so the file still makes sense a month later
+    // and a report from one of six directions is not mistaken for another.
+    record(row) { this.rows.push({ ...row, source: this.source.name, target: this.target.name }); }
+    async matchPlaylist(playlist, dryRun = false) {
+        let result;
+        try {
+            result = await this.source.readPlaylist(playlist.uri);
+        }
+        catch (error) {
+            // The message, not the name: every throw in this codebase is a plain Error, so `error.name` is
+            // always the literal "Error" and the one diagnostic the report carries would say nothing. It
+            // is also where a refusal explains itself — a mix, say — so it has to reach the user.
+            const reason = error instanceof Error ? error.message : String(error);
+            this.record({ playlist: playlist.name, title: '', artist: '', isrc: null, matched: false, note: `failed to read playlist: ${reason}` });
+            console.log(`[${playlist.name}] ✗ ${reason}`);
+            return { matchedIds: [], total: 0, truncated: false };
+        }
+        if (result.truncated) {
+            // The provider hit its own read cap; how many it managed is the only limit the path knows.
+            this.record({ playlist: playlist.name, title: '', artist: '', isrc: null, matched: false, note: `WARNING: truncated at ${result.tracks.length} tracks; remainder not converted` });
+            console.log(`[${playlist.name}] ⚠️ Truncated at ${result.tracks.length} tracks.`);
+        }
+        // Entries the source refused to convert are recorded before the matched ones, as their own kind
+        // of row: they were never searched for, so calling them "no match" would misreport them.
+        for (const entry of result.skipped ?? []) {
+            this.record({ playlist: playlist.name, title: entry.name, artist: entry.artist, isrc: null, matched: false, note: 'skipped: music video (channel name is not a reliable artist)' });
+        }
+        if (result.skipped?.length)
+            console.log(`[${playlist.name}] ${result.skipped.length} music video${result.skipped.length === 1 ? '' : 's'} skipped.`);
+        const matchedIds = [];
+        let verified = 0;
+        for (let i = 0; i < result.tracks.length; i += 1) {
+            const track = result.tracks[i];
+            let match = null;
+            for (let attempt = 0; attempt < 3; attempt += 1) {
+                try {
+                    match = await this.target.search(track);
+                    break;
+                }
+                catch (error) {
+                    if (attempt === 2)
+                        console.log(`  ⚠️ search failed: ${error instanceof Error ? error.message : 'error'}`);
+                    else
+                        await sleep(2 ** attempt * 1000);
+                }
+            }
+            if (match) {
+                const flag = await this.verify(track, match);
+                if (this.target.resolveTrack && flag === null)
+                    verified += 1;
+                matchedIds.push(match.id);
+                this.record({ playlist: playlist.name, title: track.name, artist: track.artist, isrc: null, matched: true, target_id: match.id, method: match.method, note: [flag, dryRun ? 'dry-run' : null].filter(Boolean).join('; ') || null });
+                console.log(`  [${i + 1}/${result.tracks.length}] ✓ ${match.method} — ${track.name} — ${track.artist}${flag ? ` — ${flag}` : ''}`);
+            }
+            else {
+                this.record({ playlist: playlist.name, title: track.name, artist: track.artist, isrc: null, matched: false, note: dryRun ? 'dry-run: no match' : 'no match' });
+                console.log(`  [${i + 1}/${result.tracks.length}] ✗ not found — ${track.name} — ${track.artist}`);
+            }
+            await sleep(300);
+        }
+        const missed = result.tracks.length - matchedIds.length;
+        console.log(this.target.resolveTrack
+            ? `[${playlist.name}] ${matchedIds.length}/${result.tracks.length} matched (${verified} verified${missed ? `, ${missed} match failed` : ''}).`
+            : `[${playlist.name}] ${matchedIds.length}/${result.tracks.length} tracks matched.`);
+        return { matchedIds, total: result.tracks.length, truncated: result.truncated };
+    }
+    // Resolve the match back from the target and re-check it against the source track (precision).
+    // Returns null when it verifies — or the target cannot resolve at all — and a report flag otherwise.
+    async verify(track, match) {
+        if (!this.target.resolveTrack)
+            return null;
+        try {
+            const meta = await this.target.resolveTrack(match.id);
+            const same = matchCandidates(track.name, track.artist, track.durationMs, [{ id: match.id, title: meta.name, artist: meta.artist, duration: meta.durationMs != null ? Math.round(meta.durationMs / 1000) : null }]);
+            return same ? null : '⚠️ recheck (possibly wrong track)';
+        }
+        catch {
+            return '⚠️ verification failed';
+        }
+    }
+    async writePlaylist(name, ids, title = `[plx] ${name}`) {
+        if (!ids.length) {
+            console.log(`[${name}] No matching tracks — playlist not created.`);
+            return;
+        }
+        const unique = [...new Set(ids)];
+        await this.addInChunks(await this.target.createPlaylist(title), unique);
+        console.log(`[${name}] ${this.target.name} playlist created: ${title} (${unique.length} tracks)`);
+    }
+    // Append to an existing playlist, skipping tracks already present (dedupe), then reorder if the
+    // target can. A target that cannot reorder ends here — appended, not order-synced.
+    async writeToExisting(name, playlistId, ids) {
+        if (!ids.length) {
+            console.log(`[${name}] No matching tracks.`);
+            return;
+        }
+        const existing = await this.target.getPlaylistTrackIds(playlistId);
+        // Dedupe within the batch too — Deezer rejects any chunk containing a repeated id.
+        const unique = [...new Set(ids)];
+        const batchDupes = ids.length - unique.length;
+        const alreadyThere = unique.filter((id) => existing.has(id)).length;
+        const toAdd = unique.filter((id) => !existing.has(id));
+        const added = toAdd.length ? await this.addInChunks(playlistId, toAdd) : 0;
+        const parts = [];
+        if (alreadyThere)
+            parts.push(`${alreadyThere} already present`);
+        if (batchDupes)
+            parts.push(`${batchDupes} duplicates removed`);
+        console.log(`[${name}] ${added} new tracks added${parts.length ? ` (${parts.join(', ')})` : ''}.`);
+        if (await this.target.reorder?.(playlistId, ids))
+            console.log(`[${name}] playlist order synced to source.`);
+    }
+    async addInChunks(playlistId, ids) {
+        let added = 0;
+        for (let start = 0; start < ids.length; start += 100) {
+            added += await this.target.addTracks(playlistId, ids.slice(start, start + 100));
+            await sleep(200);
+        }
+        return added;
+    }
+    async writeReport() { await writeCsv(this.output, this.rows); }
+}

package/dist/csv.js

@@ -1,5 +1,5 @@
 import { writeFile } from 'node:fs/promises';
-const fields = ['playlist', 'title', 'artist', 'isrc', 'matched', 'deezer_id', 'method', 'note'];
+const fields = ['playlist', 'source', 'target', 'title', 'artist', 'isrc', 'matched', 'target_id', 'method', 'note'];
 const cell = (value) => {
     const text = value == null ? '' : String(value);
     return /[",\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;

package/dist/deezer.js

@@ -34,6 +34,7 @@ function jwtExpiryMs(jwt) {
 }
 export class DeezerClient {
     arl;
+    name = 'Deezer';
     jwt;
     jwtExpiresAt = 0;
     constructor(arl) {
@@ -98,9 +99,9 @@ export class DeezerClient {
         const x = await this.gql('mutation AddTracksToPlaylist($playlistId:String!,$trackIds:[String!]!){addTracksToPlaylist(input:{playlistId:$playlistId,trackIds:$trackIds}){__typename ... on PlaylistAddTracksOutput{addedTrackIds} ... on PlaylistAddTracksError{isNotAllowed}}}', 'AddTracksToPlaylist', { playlistId: id, trackIds });
         const out = x.addTracksToPlaylist;
         if (out.__typename === 'PlaylistAddTracksError')
-            throw new Error(out.isNotAllowed ? 'Tidak diizinkan mengubah playlist ini (bukan milikmu / hanya di-follow)' : 'Gagal menambah lagu');
+            throw new Error(out.isNotAllowed ? 'Not allowed to modify this playlist (not yours / follow-only)' : 'Failed to add tracks');
         if (!out.addedTrackIds || out.addedTrackIds.length !== trackIds.length)
-            throw new Error(`Hanya ${out.addedTrackIds?.length ?? 0}/${trackIds.length} lagu yang benar-benar ditambahkan`);
+            throw new Error(`Only ${out.addedTrackIds?.length ?? 0}/${trackIds.length} tracks were actually added`);
         return out.addedTrackIds.length;
     }
     // The user's own playlists. ponytail: capped at first 50 — personal use, paginate only if someone hits it.
@@ -125,8 +126,9 @@ export class DeezerClient {
             after = data.playlist.tracks.pageInfo.endCursor;
         }
     }
-    // Full track metadata (title/artist/duration) in playlist order — source read for the reverse flow.
-    async getPlaylistTracks(playlistId) {
+    // Full track metadata (title/artist/duration) in playlist order — the source read.
+    // Deezer paginates the whole playlist, so a read is never truncated.
+    async readPlaylist(playlistId) {
         const tracks = [];
         let after = null;
         for (;;) {
@@ -134,7 +136,7 @@ export class DeezerClient {
             for (const e of data.playlist.tracks.edges)
                 tracks.push({ name: e.node.title, artist: e.node.contributorNames[0] ?? '', durationMs: e.node.duration * 1000 });
             if (!data.playlist.tracks.pageInfo.hasNextPage || !data.playlist.tracks.pageInfo.endCursor)
-                return tracks;
+                return { tracks, truncated: false };
             after = data.playlist.tracks.pageInfo.endCursor;
         }
     }
@@ -142,4 +144,23 @@ export class DeezerClient {
     async moveTrack(playlistId, trackId, afterTrackId) {
         await this.gql('mutation MoveTrackInPlaylist($playlistId:String!,$trackId:String!,$afterTrackId:String){moveTrackInPlaylist(input:{playlistId:$playlistId,trackId:$trackId,afterTrackId:$afterTrackId}){__typename}}', 'MoveTrackInPlaylist', { playlistId, trackId, afterTrackId });
     }
+    // Reorder capability (ADR 0002). Moves each desired track into place from the front, so the
+    // matched tracks end up in source order. Deezer moves by track id, so no per-item handle is needed.
+    // Skips when the matched tracks are already in *relative* order: tracks already in the target that
+    // aren't in `trackIds` keep their positions and may stay interleaved. Resolves true if it moved.
+    async reorder(playlistId, trackIds) {
+        const desired = [...new Set(trackIds)].filter((id) => id);
+        if (desired.length < 2)
+            return false;
+        const current = await this.getPlaylistTrackOrder(playlistId);
+        const movable = new Set(desired);
+        const kept = current.filter((id) => movable.has(id));
+        if (kept.length === desired.length && desired.every((id, i) => kept[i] === id))
+            return false;
+        for (let i = 0; i < desired.length; i += 1) {
+            await this.moveTrack(playlistId, desired[i], i === 0 ? null : desired[i - 1]);
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        return true;
+    }
 }

package/dist/matcher.js

@@ -22,4 +22,30 @@ export function matchCandidates(title, artist, durationMs, candidates) {
     }
     return null;
 }
-export function matchTrack(track, candidates) { return matchCandidates(track.name, track.artist, track.durationMs, candidates); }
+// Match rules for a music video, used only after the catalog has produced nothing.
+//
+// A music video's stated artist is usually the uploading channel, so the artist rule relaxes from
+// equality to containment: the source artist must appear somewhere in the video's title or channel
+// name. That is a much weaker guard, so in exchange the duration tolerance becomes **mandatory**
+// rather than optional — a candidate with no duration is rejected outright. Duration is what
+// separates the same recording uploaded as a video from someone else's cover of it.
+export function matchVideoCandidates(title, artist, durationMs, candidates) {
+    if (durationMs == null)
+        return null; // nothing left to guard with
+    const nt = normalize(stripFeat(title));
+    const na = artistKey(firstArtist(artist));
+    if (!nt || !na)
+        return null;
+    for (const c of candidates) {
+        if (c.duration == null || !matchDurationMs(durationMs, c.duration))
+            continue;
+        const ct = normalize(c.title);
+        // The source artist has to show up somewhere attributable — the video's title or its channel.
+        if (!artistKey(c.title).includes(na) && !artistKey(c.artist).includes(na))
+            continue;
+        if (!ct.includes(nt) && !nt.includes(ct))
+            continue;
+        return { id: c.id, title: c.title, artist: c.artist, method: 'video' };
+    }
+    return null;
+}

package/dist/registry.js

@@ -0,0 +1,67 @@
+import { DeezerClient, resolveDeezerPlaylistId } from './deezer.js';
+import { SpotifyProvider, anonymousToken, authenticatedToken, parsePlaylistId, playlistName } from './spotify.js';
+import { parsePlaylistRef, validateSession } from './ytmusic.js';
+import { YtMusicProvider } from './ytmusic-provider.js';
+const spotify = {
+    key: 'spotify',
+    label: 'Spotify',
+    matches: ['open.spotify.com', 'spotify:playlist:'],
+    credentialLabel: 'Spotify sp_dc',
+    credentialHint: 'login open.spotify.com → F12 → Application → Cookies → sp_dc → copy value',
+    loginSite: 'Spotify (open.spotify.com)',
+    anonymousRead: true,
+    parseRef: async (ref) => parsePlaylistId(ref),
+    playlistName,
+    // An sp_dc mints a full search+write token; without one the anonymous token still reads public
+    // playlists, which is what makes a credential-free dry run possible.
+    create: async (cred) => new SpotifyProvider(cred ? await authenticatedToken(cred) : await anonymousToken()),
+    validate: async (cred) => { await authenticatedToken(cred); return 'session accepted'; },
+};
+const deezer = {
+    key: 'deezer',
+    label: 'Deezer',
+    matches: ['deezer.com', 'link.deezer.com'],
+    credentialLabel: 'Deezer ARL',
+    credentialHint: 'login deezer.com → F12 → Application → Cookies → arl → copy value',
+    loginSite: 'Deezer (deezer.com)',
+    // Deezer's search is public, but reading a *playlist* goes through the authenticated GraphQL API.
+    anonymousRead: false,
+    parseRef: resolveDeezerPlaylistId,
+    playlistName: async (id) => id,
+    validate: async (cred) => `account ${(await new DeezerClient(cred).getMe()).id}`,
+    create: async (cred) => {
+        const client = new DeezerClient(cred);
+        // Fail fast on an expired ARL rather than midway through a conversion. With no credential at
+        // all this is a search-only client — enough for a dry run, since Deezer's search is public.
+        if (cred)
+            await client.getMe();
+        return client;
+    },
+};
+const ytmusic = {
+    key: 'ytmusic',
+    label: 'YouTube Music',
+    // A YouTube Music playlist id *is* a YouTube playlist id, so both hosts name the same thing.
+    matches: ['music.youtube.com', 'youtube.com'],
+    credentialLabel: 'YouTube Music cookies',
+    credentialHint: 'login music.youtube.com → F12 → Network → any request → Request Headers → copy the whole "cookie:" value',
+    loginSite: 'YouTube Music (music.youtube.com)',
+    anonymousRead: false,
+    parseRef: async (ref) => parsePlaylistRef(ref),
+    // The title needs an authenticated browse, so YtMusicProvider resolves it; this is the fallback.
+    playlistName: async (id) => id,
+    create: async (cred) => new YtMusicProvider(cred),
+    validate: validateSession,
+};
+export const PROVIDERS = [spotify, deezer, ytmusic];
+export function providerFor(key) {
+    return PROVIDERS.find((p) => p.key === key.toLowerCase());
+}
+// The keys valid after --to.
+export const targetKeys = () => PROVIDERS.map((p) => p.key);
+// Which provider a playlist link belongs to. The link already names its service, so a command line
+// that gives one never has to restate the source.
+export function inferSource(link) {
+    const ref = link.trim().toLowerCase();
+    return PROVIDERS.find((p) => p.matches.some((m) => ref.includes(m)));
+}

package/dist/spotify.js

@@ -1,6 +1,7 @@
 import { createHmac } from 'node:crypto';
 import { z } from 'zod';
 import { browserHeaders, fetchJson, fetchText } from './http.js';
+import { matchCandidates, searchQuery } from './matcher.js';
 const PATHFINDER_URL = 'https://api-partner.spotify.com/pathfinder/v1/query';
 const FETCH_PLAYLIST_SHA = 'a65e12194ed5fc443a1cdebed5fabe33ca5b07b987185d63c72483867ad13cb4';
 export const EMBED_TRACK_LIMIT = 100;
@@ -87,7 +88,7 @@ export function parsePlaylistId(ref) {
     return input;
 }
 // Resolve a spotify:track:ID URI to its real title/artist/duration via the anonymous
-// embed endpoint — used to verify reverse-flow matches (precision check).
+// embed endpoint — used to verify matches into a Spotify target (precision check).
 export async function resolveTrackMeta(uri) {
     const id = uri.split(':').pop() ?? uri;
     const entity = (await nextData(`https://open.spotify.com/embed/track/${id}`)).props?.pageProps?.state?.data?.entity;
@@ -98,7 +99,7 @@ export async function resolveTrackMeta(uri) {
         durationMs: typeof entity?.duration === 'number' ? entity.duration : null,
     };
 }
-// --- Authenticated write (reverse flow: Deezer → Spotify) ---
+// --- Authenticated search + write (Spotify as a conversion target) ---
 const PATHFINDER_V2_URL = 'https://api-partner.spotify.com/pathfinder/v2/query';
 const SPCLIENT_URL = 'https://spclient.wg.spotify.com';
 // Persisted-query hashes for write/search — captured from the web player; they rotate (see CONTINUATION.md).
@@ -155,7 +156,7 @@ async function tokenFromSpDc(spDc) {
 }
 // Authenticated write token from an sp_dc cookie (full web-player scope: search + write).
 export function authenticatedToken(spDc) { return tokenFromSpDc(spDc); }
-// Spotify search, shaped as DeezerCandidate (duration in seconds) so matchCandidates is reusable.
+// Spotify search, shaped as Candidate (duration in seconds) so matchCandidates is reusable.
 export async function searchTrack(term, token) {
     const body = { variables: { searchTerm: term, offset: 0, limit: 10, numberOfTopResults: 10, includePreReleases: false, includeAudiobooks: false, includeAuthors: false }, operationName: 'searchTracks', extensions: { persistedQuery: { version: 1, sha256Hash: SEARCH_TRACKS_SHA } } };
     const raw = await fetchJson(PATHFINDER_V2_URL, { method: 'POST', headers: writeHeaders(token), body: JSON.stringify(body) });
@@ -205,7 +206,33 @@ export async function listPlaylists(token) {
         return [{ uri: d.uri, name: d.name }];
     });
 }
-// Track URIs currently in a playlist — for dedupe on the reverse flow. Reuses the proven v1 fetchPlaylist read path.
+// Spotify identifies a playlist by bare id on the read paths and by URI on the write paths, so the
+// provider normalizes whichever form it is handed (URL, URI, or raw id) at the boundary.
+const playlistUri = (ref) => `spotify:playlist:${parsePlaylistId(ref)}`;
+// Spotify as a Provider. `token` is anonymous (read-only) or minted from sp_dc (search + write);
+// a conversion only ever asks for what its direction needs. No reorder — Spotify exposes no move
+// primitive in the endpoints plx uses, so a Spotify target is dedupe-and-append (ADR 0002).
+export class SpotifyProvider {
+    token;
+    name = 'Spotify';
+    constructor(token) {
+        this.token = token;
+    }
+    readPlaylist(ref) { return readPlaylist(parsePlaylistId(ref), this.token); }
+    async search(track) {
+        const candidates = await searchTrack(searchQuery(track.name, track.artist), this.token);
+        return matchCandidates(track.name, track.artist, track.durationMs, candidates);
+    }
+    createPlaylist(title) { return createPlaylist(title, this.token); }
+    // Returns the count submitted, not one the service confirmed: addToPlaylist reports transport
+    // errors only, so a silently dropped (relinked/unavailable) uri is still counted. Deezer's
+    // addTracks does validate what it accepted — the two differ on how much this number is worth.
+    async addTracks(ref, trackUris) { await addTracks(playlistUri(ref), trackUris, this.token); return trackUris.length; }
+    async getPlaylistTrackIds(ref) { return new Set(await fetchTrackUris(parsePlaylistId(ref), this.token)); }
+    async listPlaylists() { return (await listPlaylists(this.token)).map((p) => ({ id: p.uri, title: p.name })); }
+    resolveTrack(uri) { return resolveTrackMeta(uri); }
+}
+// Track URIs currently in a playlist — for dedupe against an existing target. Reuses the proven v1 fetchPlaylist read path.
 export async function fetchTrackUris(id, token) {
     const uris = [];
     for (let offset = 0;;) {

package/dist/ytmusic-parse.js

@@ -0,0 +1,75 @@
+// Only a catalog release (ATV) counts as a song. Everything else — an official music video, an
+// official-source upload, a user upload, a podcast — is a video whose stated artist is the channel.
+// An entry with no type at all is an unavailable/removed track and is treated the same way.
+const SONG_TYPE = 'MUSIC_VIDEO_TYPE_ATV';
+const runsText = (t) => t?.runs?.map((r) => r.text ?? '').join('') ?? '';
+// "3:49" → 229, "1:02:03" → 3723. Anything that is not a clock reading is null, *not* zero — a
+// playlist read has a duration column and a search result does not, and callers tell the two apart
+// by null. Returning 0 for an empty column silently swallows the fallback.
+export function parseDuration(text) {
+    const trimmed = text.trim();
+    if (!/^\d+(:[0-5]?\d)+$/.test(trimmed))
+        return null;
+    return trimmed.split(':').map(Number).reduce((total, part) => total * 60 + part, 0);
+}
+// Every musicResponsiveListItemRenderer anywhere in the response. The path to them differs between
+// a playlist browse, a search, and a continuation, and none of those paths is stable, so this walks.
+export function renderers(node, found = []) {
+    if (!node || typeof node !== 'object')
+        return found;
+    const record = node;
+    if (record.musicResponsiveListItemRenderer)
+        found.push(record.musicResponsiveListItemRenderer);
+    for (const child of Object.values(record))
+        renderers(child, found);
+    return found;
+}
+// The continuation token for the next page, if the response has one.
+export function continuationToken(node) {
+    if (!node || typeof node !== 'object')
+        return null;
+    const record = node;
+    const token = record.continuationItemRenderer
+        ?.continuationEndpoint?.continuationCommand?.token;
+    if (token)
+        return token;
+    for (const child of Object.values(record)) {
+        const found = continuationToken(child);
+        if (found)
+            return found;
+    }
+    return null;
+}
+export function playlistTitle(response) {
+    const micro = response?.microformat;
+    return micro?.microformatDataRenderer?.title ?? '';
+}
+function parseItem(renderer) {
+    const watch = renderer.overlay?.musicItemThumbnailOverlayRenderer?.content?.musicPlayButtonRenderer?.playNavigationEndpoint?.watchEndpoint;
+    const videoId = renderer.playlistItemData?.videoId ?? watch?.videoId;
+    if (!videoId)
+        return null;
+    const columns = renderer.flexColumns?.map((c) => runsText(c.musicResponsiveListItemFlexColumnRenderer?.text)) ?? [];
+    const title = columns[0] ?? '';
+    if (!title)
+        return null;
+    // A playlist read puts the duration in its own fixed column. A search result has no fixed column
+    // and instead trails it on the subtitle line: "Artist • Album • 3:49" (song), or
+    // "Channel • 178M views • 4:10" (video). Either way the duration is the last •-separated part.
+    const fixed = runsText(renderer.fixedColumns?.[0]?.musicResponsiveListItemFixedColumnRenderer?.text);
+    const subtitleParts = (columns[1] ?? '').split('•').map((s) => s.trim()).filter(Boolean);
+    const trailing = subtitleParts.length > 1 ? subtitleParts[subtitleParts.length - 1] : '';
+    const durationSec = parseDuration(fixed) ?? parseDuration(trailing);
+    return {
+        videoId,
+        setVideoId: renderer.playlistItemData?.playlistSetVideoId,
+        title,
+        artist: subtitleParts[0] ?? '',
+        durationSec,
+        isSong: watch?.watchEndpointMusicSupportedConfigs?.watchEndpointMusicConfig?.musicVideoType === SONG_TYPE,
+    };
+}
+export function parseItems(response) {
+    return renderers(response).flatMap((r) => parseItem(r) ?? []);
+}
+export const toCandidate = (item) => ({ id: item.videoId, title: item.title, artist: item.artist, duration: item.durationSec });