spotifify 0.1.1

package/src/spotify/api.ts

@@ -0,0 +1,155 @@
+import { chunk } from "../util/retry.ts";
+import { SpotifyHttpError, type SpotifyClient } from "./client.ts";
+import type { SpotifyPlaylist, SpotifyPlaylistItem, SpotifyTrack } from "./types.ts";
+
+// Spotify moved playlist entries to `/playlists/{id}/items` (entry field `item`) and the library to
+// `/me/library?uris=`; the legacy `/tracks` and `/me/tracks/contains` paths answer 403 for newer apps.
+const ITEM_FIELDS = "next,total,items(added_at,is_local,item(id,uri,name,is_local,duration_ms,artists(id,name),album(id,name)))";
+
+/** Playlist item batch limit for add/remove/replace. */
+const ITEMS_BATCH = 100;
+/** `/me/library` batch limit (probed: 41+ uris → 400 "Too many uris requested"). */
+const LIBRARY_BATCH = 40;
+
+/** Typed façade over the ~15 endpoints this tool needs. Every write returns the resulting snapshot_id. */
+export class SpotifyApi {
+  constructor(readonly client: SpotifyClient) {}
+
+  async me(): Promise<{ id: string; country: string }> {
+    const { id, country } = await this.client.request<{ id: string; country?: string }>("GET", "/v1/me");
+    if (!country) throw new Error("Spotify profile has no country: the token lacks user-read-private; run `spotifify auth spotify`");
+    return { id, country };
+  }
+
+  /** Concrete ISO market for search: config value, or the account country when configured as "from_token". */
+  async resolveMarket(configured: string): Promise<string> {
+    return configured === "from_token" ? (await this.me()).country : configured;
+  }
+
+  async searchTracks(q: string, market: string, limit = 10): Promise<SpotifyTrack[]> {
+    const res = await this.client.request<{ tracks: { items: SpotifyTrack[] } }>("GET", "/v1/search", {
+      query: { q, type: "track", market, limit },
+    });
+    return res.tracks.items;
+  }
+
+  /** null on 404 (deleted / never existed). */
+  async getTrack(id: string, market: string): Promise<SpotifyTrack | null> {
+    try {
+      return await this.client.request<SpotifyTrack>("GET", `/v1/tracks/${id}`, { query: { market } });
+    } catch (e) {
+      if (e instanceof SpotifyHttpError && e.status === 404) return null;
+      throw e;
+    }
+  }
+
+  listMyPlaylists(): Promise<SpotifyPlaylist[]> {
+    return this.client.paginate<SpotifyPlaylist>("/v1/me/playlists", { limit: 50 });
+  }
+
+  /** null on 404 (deleted playlist). */
+  async getPlaylist(id: string): Promise<SpotifyPlaylist | null> {
+    try {
+      return await this.client.request<SpotifyPlaylist>("GET", `/v1/playlists/${id}`);
+    } catch (e) {
+      if (e instanceof SpotifyHttpError && e.status === 404) return null;
+      throw e;
+    }
+  }
+
+  /** Always private. Uses `/me/playlists`: the legacy `/users/{id}/playlists` path answers 403 for development-mode apps. */
+  createPlaylist(name: string, description: string): Promise<SpotifyPlaylist> {
+    return this.client.request<SpotifyPlaylist>("POST", "/v1/me/playlists", { body: { name, public: false, description } });
+  }
+
+  async renamePlaylist(id: string, name: string): Promise<void> {
+    await this.client.request<void>("PUT", `/v1/playlists/${id}`, { body: { name } });
+  }
+
+  getPlaylistItems(id: string): Promise<SpotifyPlaylistItem[]> {
+    return this.client.paginate<SpotifyPlaylistItem>(`/v1/playlists/${id}/items`, { limit: 50, fields: ITEM_FIELDS });
+  }
+
+  /** ≤100 per request; `position` advances by batch size so the whole run lands contiguously. Returns the last snapshot_id. */
+  async addPlaylistItems(id: string, uris: string[], position?: number): Promise<string> {
+    let snapshot = "";
+    let at = position;
+    for (const batch of chunk(uris, ITEMS_BATCH)) {
+      const res = await this.client.request<{ snapshot_id: string }>("POST", `/v1/playlists/${id}/items`, {
+        body: at === undefined ? { uris: batch } : { uris: batch, position: at },
+      });
+      snapshot = res.snapshot_id;
+      if (at !== undefined) at += batch.length;
+    }
+    return snapshot;
+  }
+
+  /**
+   * ≤100 per request. Catalog tracks are removed by URI; local files must be removed by position only
+   * (`/items` answers 400 "Invalid base62 id" for a `spotify:local:` URI). Positions are removed highest
+   * first with chained snapshot ids, so earlier indexes never shift underneath later batches.
+   */
+  async removePlaylistItems(id: string, items: Array<{ uri: string; positions?: number[] }>, snapshotId: string): Promise<string> {
+    let snapshot = snapshotId;
+    const positions = items.flatMap((x) => x.positions ?? []).sort((a, b) => b - a);
+    const uris = items.filter((x) => x.positions === undefined).map((x) => ({ uri: x.uri }));
+    for (const batch of chunk(positions, ITEMS_BATCH)) {
+      const res = await this.client.request<{ snapshot_id: string }>("DELETE", `/v1/playlists/${id}/items`, {
+        body: { positions: batch, snapshot_id: snapshot },
+      });
+      snapshot = res.snapshot_id;
+    }
+    for (const batch of chunk(uris, ITEMS_BATCH)) {
+      const res = await this.client.request<{ snapshot_id: string }>("DELETE", `/v1/playlists/${id}/items`, {
+        body: { items: batch, snapshot_id: snapshot },
+      });
+      snapshot = res.snapshot_id;
+    }
+    return snapshot;
+  }
+
+  async reorderPlaylistItems(id: string, rangeStart: number, insertBefore: number, snapshotId: string, rangeLength = 1): Promise<string> {
+    const res = await this.client.request<{ snapshot_id: string }>("PUT", `/v1/playlists/${id}/items`, {
+      body: { range_start: rangeStart, insert_before: insertBefore, range_length: rangeLength, snapshot_id: snapshotId },
+    });
+    return res.snapshot_id;
+  }
+
+  /** PUT the first ≤100 (which also clears the playlist), then append the rest. */
+  async replacePlaylistItems(id: string, uris: string[]): Promise<string> {
+    const res = await this.client.request<{ snapshot_id: string }>("PUT", `/v1/playlists/${id}/items`, {
+      body: { uris: uris.slice(0, ITEMS_BATCH) },
+    });
+    const rest = uris.slice(ITEMS_BATCH);
+    return rest.length === 0 ? res.snapshot_id : this.addPlaylistItems(id, rest);
+  }
+
+  /** ≤50 per request; result aligns with `ids` order. */
+  async checkSaved(ids: string[]): Promise<boolean[]> {
+    const out: boolean[] = [];
+    for (const batch of chunk(ids, LIBRARY_BATCH)) {
+      out.push(...(await this.client.request<boolean[]>("GET", "/v1/me/library/contains", { query: { uris: batch.map(trackUri).join(",") } })));
+    }
+    return out;
+  }
+
+  /** Every saved track id, paginated 50 at a time. Fallback for accounts where `contains` is unavailable. */
+  async listSavedTrackIds(): Promise<Set<string>> {
+    const items = await this.client.paginate<{ track: { id: string | null } | null }>("/v1/me/tracks", { limit: LIBRARY_BATCH });
+    const ids = new Set<string>();
+    for (const it of items) if (it.track?.id) ids.add(it.track.id);
+    return ids;
+  }
+
+  async saveTracks(ids: string[]): Promise<void> {
+    for (const batch of chunk(ids, LIBRARY_BATCH)) await this.client.request<void>("PUT", "/v1/me/library", { query: { uris: batch.map(trackUri).join(",") } });
+  }
+
+  async removeSavedTracks(ids: string[]): Promise<void> {
+    for (const batch of chunk(ids, LIBRARY_BATCH)) await this.client.request<void>("DELETE", "/v1/me/library", { query: { uris: batch.map(trackUri).join(",") } });
+  }
+}
+
+function trackUri(id: string): string {
+  return id.startsWith("spotify:") ? id : `spotify:track:${id}`;
+}

package/src/spotify/auth.ts

@@ -0,0 +1,121 @@
+import { log } from "../util/log.ts";
+import { openExternal } from "../util/open.ts";
+import { SCOPES, type SpotifyTokens } from "./types.ts";
+
+const ACCOUNTS = "https://accounts.spotify.com";
+/** Refresh this long before the token actually expires so in-flight requests never race the deadline. */
+const EXPIRY_MARGIN_MS = 30_000;
+
+export interface TokenStore {
+  load(): SpotifyTokens | null;
+  save(t: SpotifyTokens): void;
+}
+
+/** Refresh rejected (invalid_grant) or no stored tokens: the user must run `auth spotify` again. */
+export class AuthExpiredError extends Error {
+  constructor(message = "Spotify authorization expired; run `spotifify auth spotify`") {
+    super(message);
+    this.name = "AuthExpiredError";
+  }
+}
+
+interface TokenResponse {
+  access_token: string;
+  refresh_token?: string;
+  expires_in: number;
+  scope?: string;
+}
+
+function base64url(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+async function postToken(form: Record<string, string>, previous?: SpotifyTokens): Promise<SpotifyTokens> {
+  const res = await fetch(`${ACCOUNTS}/api/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(form).toString(),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    if (res.status === 400 && text.includes("invalid_grant")) throw new AuthExpiredError(`Spotify token refresh rejected: ${text}`);
+    throw new Error(`Spotify token endpoint ${res.status}: ${text}`);
+  }
+  const body = JSON.parse(text) as TokenResponse;
+  const refresh = body.refresh_token ?? previous?.refresh_token;
+  if (!refresh) throw new Error("Spotify token response carried no refresh_token");
+  return {
+    access_token: body.access_token,
+    refresh_token: refresh,
+    expires_at: Date.now() + body.expires_in * 1000 - EXPIRY_MARGIN_MS,
+    scope: body.scope ?? previous?.scope ?? SCOPES.join(" "),
+  };
+}
+
+/** Authorization Code + PKCE via a one-shot loopback server; resolves once tokens are exchanged and saved. */
+export async function loginPkce(opts: { clientId: string; port: number; store: TokenStore }): Promise<SpotifyTokens> {
+  const verifier = base64url(crypto.getRandomValues(new Uint8Array(64)));
+  const challenge = base64url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))));
+  const state = base64url(crypto.getRandomValues(new Uint8Array(16)));
+  const redirectUri = `http://127.0.0.1:${opts.port}/callback`;
+
+  const { promise: code, resolve, reject } = Promise.withResolvers<string>();
+  const server = Bun.serve({
+    hostname: "127.0.0.1",
+    port: opts.port,
+    fetch(req) {
+      const url = new URL(req.url);
+      if (url.pathname !== "/callback") return new Response("Not found", { status: 404 });
+      const error = url.searchParams.get("error");
+      const got = url.searchParams.get("code");
+      if (url.searchParams.get("state") !== state) {
+        reject(new Error("Spotify callback state mismatch"));
+        return new Response("State mismatch. You can close this tab.", { status: 400 });
+      }
+      if (error || !got) {
+        reject(new Error(`Spotify authorization failed: ${error ?? "no code"}`));
+        return new Response(`Authorization failed: ${error ?? "no code"}. You can close this tab.`, { status: 400 });
+      }
+      resolve(got);
+      return new Response("Spotifify: authorization complete. You can close this tab.", { headers: { "Content-Type": "text/plain" } });
+    },
+  });
+
+  const authorize = new URL(`${ACCOUNTS}/authorize`);
+  authorize.search = new URLSearchParams({
+    client_id: opts.clientId,
+    response_type: "code",
+    redirect_uri: redirectUri,
+    scope: SCOPES.join(" "),
+    state,
+    code_challenge_method: "S256",
+    code_challenge: challenge,
+  }).toString();
+
+  log.info(`Open this URL to authorize Spotify:\n${authorize.href}`);
+  openExternal(authorize.href);
+
+  try {
+    const tokens = await postToken({
+      client_id: opts.clientId,
+      grant_type: "authorization_code",
+      code: await code,
+      redirect_uri: redirectUri,
+      code_verifier: verifier,
+    });
+    opts.store.save(tokens);
+    return tokens;
+  } finally {
+    server.stop(true);
+  }
+}
+
+/** PKCE refresh responses may omit `refresh_token`; the previous one is kept in that case. */
+export async function refreshTokens(clientId: string, refreshToken: string): Promise<SpotifyTokens> {
+  return postToken({ client_id: clientId, grant_type: "refresh_token", refresh_token: refreshToken }, {
+    access_token: "",
+    refresh_token: refreshToken,
+    expires_at: 0,
+    scope: "",
+  });
+}

package/src/spotify/client.ts

@@ -0,0 +1,120 @@
+import { log } from "../util/log.ts";
+import { RetryableError, withRetry } from "../util/retry.ts";
+import { AuthExpiredError, refreshTokens, type TokenStore } from "./auth.ts";
+import type { Paging, SpotifyTokens } from "./types.ts";
+
+const API = "https://api.spotify.com";
+const ATTEMPTS = 5;
+
+export type Query = Record<string, string | number | undefined>;
+
+export class SpotifyHttpError extends Error {
+  constructor(
+    readonly status: number,
+    readonly body: string,
+    method: string,
+    url: string,
+  ) {
+    super(`Spotify ${method} ${url} → ${status}: ${body}`);
+    this.name = "SpotifyHttpError";
+  }
+}
+
+/** Longest 429 back-off we sleep through in-process; anything longer (Spotify hands out ~24 h for quota exhaustion) aborts the phase. */
+const MAX_RETRY_AFTER_MS = 120_000;
+
+/** 429 with a Retry-After beyond MAX_RETRY_AFTER_MS: callers should stop, persist `untilMs`, and continue next run. */
+export class SpotifyRateLimitedError extends Error {
+  constructor(
+    readonly untilMs: number,
+    path: string,
+  ) {
+    super(`Spotify rate limited on ${path} until ${new Date(untilMs).toISOString()}`);
+    this.name = "SpotifyRateLimitedError";
+  }
+}
+
+/** Thin fetch wrapper: bearer injection, proactive + reactive refresh, 429/5xx retry, JSON decoding. */
+export class SpotifyClient {
+  private readonly clientId: string;
+  private readonly store: TokenStore;
+  private refreshing: Promise<SpotifyTokens> | null = null;
+
+  constructor(opts: { clientId: string; store: TokenStore }) {
+    this.clientId = opts.clientId;
+    this.store = opts.store;
+  }
+
+  async request<T>(method: "GET" | "POST" | "PUT" | "DELETE", path: string, opts: { query?: Query; body?: unknown } = {}): Promise<T> {
+    // SPOTIFIFY_SPOTIFY_API lets an in-process fake stand in for the Web API in end-to-end tests.
+    const url = new URL(path.startsWith("http") ? path : (process.env.SPOTIFIFY_SPOTIFY_API ?? API) + path);
+    if (opts.query) {
+      for (const [k, v] of Object.entries(opts.query)) if (v !== undefined) url.searchParams.set(k, String(v));
+    }
+    const body = opts.body === undefined ? undefined : JSON.stringify(opts.body);
+
+    let retriedAuth = false;
+    return withRetry(
+      async () => {
+        const token = await this.accessToken();
+        const res = await fetch(url, {
+          method,
+          headers: { Authorization: `Bearer ${token}`, ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
+          body,
+        });
+        const text = await res.text();
+        if (res.ok) return (text === "" ? undefined : JSON.parse(text)) as T;
+
+        if (res.status === 401 && !retriedAuth) {
+          retriedAuth = true;
+          await this.refresh();
+          throw new RetryableError("401; refreshed token", 0);
+        }
+        if (res.status === 429) {
+          const secs = Number(res.headers.get("Retry-After") ?? "1");
+          const waitMs = (Number.isFinite(secs) ? secs : 1) * 1000;
+          if (waitMs > MAX_RETRY_AFTER_MS) throw new SpotifyRateLimitedError(Date.now() + waitMs, url.pathname);
+          log.warn(`Spotify rate limited; waiting ${secs}s`, { method, path: url.pathname });
+          throw new RetryableError(`429 on ${method} ${url.pathname}`, waitMs);
+        }
+        if (res.status >= 500) throw new RetryableError(`${res.status} on ${method} ${url.pathname}`);
+        throw new SpotifyHttpError(res.status, text, method, url.pathname);
+      },
+      { attempts: ATTEMPTS },
+    );
+  }
+
+  /** Follows `Paging.next` until exhausted. */
+  async paginate<T>(path: string, query?: Query): Promise<T[]> {
+    const out: T[] = [];
+    let page = await this.request<Paging<T>>("GET", path, { query });
+    for (;;) {
+      out.push(...page.items);
+      if (page.next === null) return out;
+      page = await this.request<Paging<T>>("GET", page.next);
+    }
+  }
+
+  private async accessToken(): Promise<string> {
+    const tokens = this.store.load();
+    if (tokens === null) throw new AuthExpiredError();
+    if (tokens.expires_at > Date.now()) return tokens.access_token;
+    return (await this.refresh()).access_token;
+  }
+
+  /** Concurrent callers share one refresh so a burst of expired requests does not spam the token endpoint. */
+  private refresh(): Promise<SpotifyTokens> {
+    if (this.refreshing) return this.refreshing;
+    const tokens = this.store.load();
+    if (tokens === null) throw new AuthExpiredError();
+    this.refreshing = refreshTokens(this.clientId, tokens.refresh_token)
+      .then((fresh) => {
+        this.store.save(fresh);
+        return fresh;
+      })
+      .finally(() => {
+        this.refreshing = null;
+      });
+    return this.refreshing;
+  }
+}

package/src/spotify/localUri.ts

@@ -0,0 +1,48 @@
+/**
+ * Spotify desktop derives a local file's identity from its tags and its own duration computation:
+ *   spotify:local:{artist}:{album}:{title}:{durationSec}
+ * Segments are percent-encoded with spaces as "+". The client normalizes whatever is pasted into this
+ * form (a three-segment paste comes back from the API as `…:0`) and only links an entry to a file when
+ * every segment — the whole-second duration included — equals what its index computed (see
+ * `sync/duration.ts`). Encoding details drift across client versions (it writes "(" as "%28"), so
+ * remote URIs are compared via `canonicalLocalUri`.
+ */
+
+export interface LocalUriParts {
+  artist: string;
+  album: string;
+  title: string;
+  /** null only for a bare three-segment uri, which the client never produces itself */
+  durationSec: number | null;
+}
+
+const PREFIX = "spotify:local:";
+
+export function buildLocalUri(p: LocalUriParts): string {
+  const seg = (s: string) => encodeURIComponent(s).replace(/%20/g, "+");
+  const base = `${PREFIX}${seg(p.artist)}:${seg(p.album)}:${seg(p.title)}`;
+  return p.durationSec === null ? base : `${base}:${p.durationSec}`;
+}
+
+export function parseLocalUri(uri: string): LocalUriParts | null {
+  if (!uri.startsWith(PREFIX)) return null;
+  const segs = uri.slice(PREFIX.length).split(":");
+  if (segs.length !== 3 && segs.length !== 4) return null;
+  let durationSec: number | null = null;
+  if (segs.length === 4) {
+    durationSec = Number(segs[3]);
+    if (!Number.isInteger(durationSec) || durationSec < 0) return null;
+  }
+  try {
+    const dec = (s: string) => decodeURIComponent(s.replace(/\+/g, " "));
+    return { artist: dec(segs[0]!), album: dec(segs[1]!), title: dec(segs[2]!), durationSec };
+  } catch {
+    return null;
+  }
+}
+
+/** Normal form used for equality between `local_export.local_uri` and remote playlist items. */
+export function canonicalLocalUri(uri: string): string | null {
+  const parts = parseLocalUri(uri);
+  return parts === null ? null : buildLocalUri(parts);
+}

package/src/spotify/types.ts

@@ -0,0 +1,61 @@
+/** Minimal Web API shapes this tool reads. Field names follow the API verbatim. */
+
+export interface SpotifyArtist {
+  id: string | null;
+  name: string;
+}
+
+export interface SpotifyTrack {
+  id: string | null;
+  uri: string;
+  name: string;
+  artists: SpotifyArtist[];
+  album: { id: string | null; name: string };
+  duration_ms: number;
+  is_local: boolean;
+  /** present only when the request carried `market` */
+  is_playable?: boolean;
+  external_ids?: { isrc?: string };
+  linked_from?: { id: string; uri: string };
+}
+
+/** Entry of `GET /playlists/{id}/items`; the payload lives under `item` (`track` in the retired `/tracks` API). */
+export interface SpotifyPlaylistItem {
+  added_at: string;
+  is_local: boolean;
+  item: SpotifyTrack | null;
+}
+
+export interface SpotifyPlaylist {
+  id: string;
+  name: string;
+  description: string | null;
+  snapshot_id: string;
+  owner: { id: string };
+}
+
+export interface Paging<T> {
+  items: T[];
+  next: string | null;
+  total: number;
+}
+
+export interface SpotifyTokens {
+  access_token: string;
+  refresh_token: string;
+  /** unix ms */
+  expires_at: number;
+  scope: string;
+}
+
+export const SCOPES = [
+  "playlist-read-private",
+  "playlist-modify-private",
+  "playlist-modify-public",
+  "user-library-read",
+  "user-library-modify",
+  // `/v1/me.country` and market-restricted search need this; without it search answers 403 "Insufficient client scope".
+  "user-read-private",
+] as const;
+
+export const MANAGED_DESCRIPTION = "Managed by Spotifify";

package/src/state/db.ts

@@ -0,0 +1,42 @@
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+import schemaV1 from "./schema.sql" with { type: "text" };
+
+// Append-only. Each entry runs once, in order, inside a transaction; user_version tracks progress.
+const MIGRATIONS: readonly string[] = [
+  schemaV1,
+  // v2: small key/value store (e.g. Spotify rate-limit deadline carried across runs)
+  "CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)",
+];
+
+export const SCHEMA_VERSION = MIGRATIONS.length;
+
+export function openDatabase(dir: string): Database {
+  mkdirSync(dir, { recursive: true });
+  const db = new Database(join(dir, "state.db"), { create: true, strict: true });
+  db.exec("PRAGMA journal_mode = WAL");
+  db.exec("PRAGMA foreign_keys = ON");
+  db.exec("PRAGMA busy_timeout = 5000");
+  migrate(db);
+  return db;
+}
+
+export function schemaVersion(db: Database): number {
+  const row = db.query<{ user_version: number }, []>("PRAGMA user_version").get();
+  return row?.user_version ?? 0;
+}
+
+function migrate(db: Database): void {
+  const current = schemaVersion(db);
+  if (current > SCHEMA_VERSION) {
+    throw new Error(`state.db schema v${current} is newer than this build (v${SCHEMA_VERSION})`);
+  }
+  for (let v = current; v < SCHEMA_VERSION; v++) {
+    const sql = MIGRATIONS[v]!;
+    db.transaction(() => {
+      db.exec(sql);
+      db.exec(`PRAGMA user_version = ${v + 1}`);
+    })();
+  }
+}