spotify-turntable 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felix Arbucias
+
+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

@@ -1,3 +1,208 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# spotify-turntable
+
+A little record player that shows what you're playing on Spotify, live. The record spins and the tonearm drops while music plays. When you're not listening, it can play from a playlist (or your Liked Songs) like a radio station, so visitors always see something spinning. Visitors can press play to listen right on your site.
+
+Made for personal sites and portfolios. React on the front, any JavaScript server on the back, and no database.
+
+- **Live:** polls Spotify every ~15 s and moves the progress bar smoothly between polls.
+- **House rotation:** when you're idle, every visitor hears the same song at the same moment, like a radio station.
+- **Cheap on rate limits:** results are cached in memory and at the CDN, so many visitors share a handful of Spotify calls.
+- **Secrets stay on the server:** the browser only ever sees track names and artwork.
+- **Accessible:** keyboard support, honours `prefers-reduced-motion`, and turns into a compact pill on phones.
+
+## Try it in two minutes
+
+```bash
+git clone https://github.com/felixArbucias/portfolio
+cd portfolio/packages/spotify-turntable
+npm install
+npm run auth     # connect your Spotify account (walks you through it)
+npm run dev      # open the printed URL
+```
+
+No Spotify yet? Open `?demo=live` or `?demo=rotation` to see it with sample songs.
+
+## Add it to your site
+
+### 1. Install
+
+```bash
+npm install spotify-turntable
+```
+
+### 2. Connect your Spotify account (once)
+
+```bash
+npx spotify-turntable auth
+```
+
+It walks you through it:
+
+1. Create an app at <https://developer.spotify.com/dashboard>. Add the redirect URI `http://127.0.0.1:8888/callback` and tick **Web API**.
+2. Paste the **Client ID** and **Client Secret** when asked.
+3. Approve access in the browser tab that opens.
+
+It then writes everything to `.env.local`:
+
+```bash
+SPOTIFY_CLIENT_ID=…
+SPOTIFY_CLIENT_SECRET=…
+SPOTIFY_REFRESH_TOKEN=…
+SPOTIFY_FALLBACK_PLAYLIST=liked   # optional, see "House rotation"
+```
+
+Make sure `.env.local` is in your `.gitignore` (the command warns you if it isn't). When you deploy, add the same four values as environment variables on your host (Vercel, Netlify, …).
+
+> New Spotify apps run in development mode. That works for your own account, which is all a personal site needs, but Spotify currently requires the app owner to have Premium.
+
+### 3. Add the endpoint
+
+The component asks your own server for `/api/now-playing`, and the server talks to Spotify. Pick your setup:
+
+**Vite (dev and preview)**
+
+```js
+// vite.config.js
+import react from "@vitejs/plugin-react";
+import { spotifyTurntable } from "spotify-turntable/vite";
+
+export default { plugins: [react(), spotifyTurntable()] };
+```
+
+**Vercel (Vite, Create React App, plain HTML…)**
+
+```js
+// api/now-playing.js
+import { nowPlayingHandler } from "spotify-turntable/server";
+export default nowPlayingHandler();
+```
+
+**Next.js (App Router)**
+
+```js
+// app/api/now-playing/route.js
+import { nowPlayingFetchHandler } from "spotify-turntable/server";
+export const GET = nowPlayingFetchHandler();
+export const dynamic = "force-dynamic";
+```
+
+**Express**
+
+```js
+import { nowPlayingHandler } from "spotify-turntable/server";
+app.get("/api/now-playing", nowPlayingHandler());
+```
+
+**Anything else.** `nowPlayingFetchHandler()` is a standard `(Request) => Response` handler: use it with Netlify Functions, Cloudflare Workers, Deno or Bun. Or call `getNowPlaying(process.env)` yourself and return the JSON.
+
+### 4. Drop in the component
+
+```jsx
+import { Turntable } from "spotify-turntable";
+import "spotify-turntable/style.css";
+
+export default function Layout() {
+  return <Turntable floating />; // pinned to the top-right corner
+}
+```
+
+That's it. Restart your dev server and it shows whatever you're playing.
+
+## Options
+
+```jsx
+<Turntable
+  floating              // pin to the top-right corner (otherwise it renders in place)
+  endpoint="/api/now-playing"
+  labels={{ rotation: "Felix's rotation", playing: "On the deck" }}
+  fallbackUrl="https://open.spotify.com/user/you"  // where the card links when nothing has played
+  demo="rotation"       // "live" | "rotation": sample data, no Spotify needed
+/>
+```
+
+All label keys: `loading`, `playing`, `rotation`, `paused`, `recent`, `idle`, `unconfigured`, `offline`.
+
+**Share one poller.** If other parts of your page also want to know what's playing:
+
+```jsx
+import { Turntable, useNowPlaying } from "spotify-turntable";
+
+const np = useNowPlaying(); // { state, track, playlist, progressMs, playedAt, demo }
+<Turntable np={np} />
+<MyOtherWidget song={np.track} />
+```
+
+**Theme.** Override the CSS variables on `.deck`:
+
+```css
+.deck {
+  --deck-card: #fffdf9;   /* card background */
+  --deck-edge: #ece7df;   /* border */
+  --deck-ink: #1a1a1a;    /* text */
+  --deck-soft: #6b6b6b;   /* secondary text */
+  --deck-line: #e7e3dc;   /* progress track */
+  --deck-label: #e9dfcf;  /* record centre label */
+  --deck-vinyl: 150px;    /* overall size */
+}
+```
+
+## House rotation
+
+Set `SPOTIFY_FALLBACK_PLAYLIST` to keep the record spinning while you're offline:
+
+| Value | What happens |
+|---|---|
+| `liked` | Rotates through your **Liked Songs**. Visitors can play each song, but Liked Songs has no public playlist link. |
+| a playlist link or ID | Rotates through that playlist and offers an "Open the whole rotation" link. The playlist must belong to (or be collaborative with) the connected account. |
+| empty | Shows what you paused on, or the last song you played. |
+
+## What the card shows
+
+1. **Now spinning:** what you're playing right now (songs and podcasts).
+2. **House rotation:** nothing playing, so it plays from your fallback playlist.
+3. **On pause / Last spun:** no rotation set, so it shows the last thing you played.
+4. **Not connected:** no credentials yet (in development it tells you to run the auth command).
+
+## The JSON
+
+`GET /api/now-playing` (add `?demo=live` or `?demo=rotation` for sample data):
+
+```json
+{
+  "configured": true,
+  "mode": "live",
+  "isPlaying": true,
+  "track": {
+    "id": "…", "type": "track", "title": "…", "artist": "…", "album": "…",
+    "albumArt": "https://i.scdn.co/…", "url": "https://open.spotify.com/track/…",
+    "durationMs": 214000, "progressMs": 81234
+  },
+  "playlist": null,
+  "playedAt": null,
+  "fetchedAt": 1793370000000
+}
+```
+
+`mode` is one of `live`, `rotation`, `paused`, `recent`, `idle`, `unconfigured` or `error`.
+
+## How it works
+
+It uses only the official [Spotify Web API](https://developer.spotify.com/documentation/web-api). There's no SDK and nothing in between:
+
+- `npx spotify-turntable auth` runs Spotify's standard login flow once and saves a **refresh token**.
+- On each request, the server swaps that for a short-lived access token (cached for about an hour). It then reads `currently-playing`, falls back to your rotation (`/playlists/{id}/items` or `/me/tracks`), and finally to `recently-played`.
+- In-memory caches (player about 12 s, recent about 60 s, playlist about 6 h) and `Cache-Control` headers keep Spotify calls low. If Spotify rate-limits it, it waits and keeps showing the last good result.
+- The play button opens Spotify's official embed player.
+
+Scopes requested: `user-read-currently-playing`, `user-read-recently-played`, `user-read-playback-state`, `playlist-read-private`, `playlist-read-collaborative`, `user-library-read`. Everything is read-only.
+
+## Develop
+
+```bash
+npm test         # mocked Spotify, never hits the network
+npm run dev      # example app on http://localhost:5173
+```
+
+## License
+
+MIT © Felix Arbucias. Not affiliated with Spotify.

package/bin/spotify-turntable.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+/*
+ * npx spotify-turntable auth
+ *
+ * One-time setup: asks for your Spotify app's Client ID / Secret (if they aren't already in your
+ * env file), opens Spotify's consent screen, and writes SPOTIFY_REFRESH_TOKEN (plus the rest)
+ * into .env.local. Nothing is sent anywhere except Spotify.
+ */
+import http from "node:http";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout, argv, exit } from "node:process";
+import { parseEnv, upsertEnv } from "../src/env-file.js";
+
+const SCOPES = [
+  "user-read-currently-playing",
+  "user-read-recently-played",
+  "user-read-playback-state",
+  "playlist-read-private", // private / collaborative SPOTIFY_FALLBACK_PLAYLIST
+  "playlist-read-collaborative",
+  "user-library-read", // SPOTIFY_FALLBACK_PLAYLIST=liked
+].join(" ");
+
+const HELP = `spotify-turntable
+
+Usage
+  npx spotify-turntable auth [options]   Connect your Spotify account (writes .env.local)
+  npx spotify-turntable help
+
+Options
+  --env-file <path>   File to read and update (default: .env.local)
+  --port <n>          Local callback port (default: 8888)
+  --print             Only print the values; don't write any file
+`;
+
+function flag(name, fallback) {
+  const i = argv.indexOf(`--${name}`);
+  return i > -1 && argv[i + 1] && !argv[i + 1].startsWith("--") ? argv[i + 1] : fallback;
+}
+
+const command = argv[2] && !argv[2].startsWith("--") ? argv[2] : "auth";
+if (command === "help" || argv.includes("--help") || argv.includes("-h")) {
+  stdout.write(HELP);
+  exit(0);
+}
+if (command !== "auth") {
+  console.error(`Unknown command "${command}".\n`);
+  stdout.write(HELP);
+  exit(1);
+}
+
+const ENV_FILE = flag("env-file", ".env.local");
+const PORT = Number(flag("port", 8888));
+const PRINT_ONLY = argv.includes("--print");
+const REDIRECT_URI = `http://127.0.0.1:${PORT}/callback`;
+
+const read = (file) => (existsSync(file) ? readFileSync(file, "utf8") : "");
+
+function isGitIgnored(file) {
+  const rules = read(".gitignore").split(/\r?\n/).map((l) => l.trim());
+  const name = file.replace(/^\.\//, "");
+  return rules.some((r) => r === name || r === `/${name}` || r === "*.local" || r === ".env*" || r === ".env.*");
+}
+
+function openBrowser(url) {
+  try {
+    const [cmd, args] =
+      process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url.replace(/&/g, "^&")]]
+        : [process.platform === "darwin" ? "open" : "xdg-open", [url]];
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    // The URL is printed too.
+  }
+}
+
+async function exchangeCode(code, clientId, clientSecret) {
+  const res = await fetch("https://accounts.spotify.com/api/token", {
+    method: "POST",
+    headers: {
+      Authorization: `Basic ${btoa(`${clientId}:${clientSecret}`)}`,
+      "Content-Type": "application/x-www-form-urlencoded",
+    },
+    body: new URLSearchParams({ grant_type: "authorization_code", code, redirect_uri: REDIRECT_URI }).toString(),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok || !data.refresh_token) {
+    const reason = data.error_description || data.error || "no refresh_token";
+    const hint = data.error === "invalid_client" ? " (check the Client ID / Secret)" : "";
+    throw new Error(`Token exchange failed (${res.status}): ${reason}${hint}`);
+  }
+  return data.refresh_token;
+}
+
+function authorize(clientId, clientSecret) {
+  const state = randomBytes(12).toString("hex");
+  const url =
+    "https://accounts.spotify.com/authorize?" +
+    new URLSearchParams({ response_type: "code", client_id: clientId, scope: SCOPES, redirect_uri: REDIRECT_URI, state, show_dialog: "true" });
+
+  return new Promise((resolve, reject) => {
+    const server = http.createServer(async (req, res) => {
+      const u = new URL(req.url, REDIRECT_URI);
+      if (u.pathname !== "/callback") return res.writeHead(404).end();
+      const finish = (status, body, err, token) => {
+        res.writeHead(status, { "Content-Type": "text/plain; charset=utf-8" }).end(body);
+        server.close();
+        if (err) reject(err);
+        else resolve(token);
+      };
+      if (u.searchParams.get("error")) return finish(400, "Authorization was cancelled. You can close this tab.", new Error(`Spotify said: ${u.searchParams.get("error")}`));
+      if (u.searchParams.get("state") !== state) return finish(400, "State mismatch. Run the command again.", new Error("State mismatch"));
+      try {
+        const token = await exchangeCode(u.searchParams.get("code") || "", clientId, clientSecret);
+        finish(200, "Connected! Head back to your terminal. You can close this tab.", null, token);
+      } catch (err) {
+        finish(500, "Token exchange failed. Check your terminal.", err);
+      }
+    });
+    server.on("error", (err) => reject(err.code === "EADDRINUSE" ? new Error(`Port ${PORT} is busy. Try --port 8889 (and add that redirect URI in Spotify).`) : err));
+    server.listen(PORT, "127.0.0.1", () => {
+      console.log("\nOpening Spotify so you can approve access (or open this link yourself):\n");
+      console.log(`  ${url}\n`);
+      openBrowser(url);
+    });
+  });
+}
+
+async function main() {
+  const fileEnv = { ...parseEnv(read(".env")), ...parseEnv(read(ENV_FILE)) };
+  const env = { ...fileEnv, ...process.env };
+  let clientId = env.SPOTIFY_CLIENT_ID;
+  let clientSecret = env.SPOTIFY_CLIENT_SECRET;
+  let playlist = env.SPOTIFY_FALLBACK_PLAYLIST;
+
+  console.log("spotify-turntable · connect your Spotify account\n");
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    if (!clientId || !clientSecret) {
+      console.log("1. Go to https://developer.spotify.com/dashboard and create an app.");
+      console.log(`2. In the app's settings, add this Redirect URI:  ${REDIRECT_URI}`);
+      console.log("   (tick \"Web API\" when it asks which APIs you'll use)");
+      console.log("3. Copy the Client ID and Client Secret below.\n");
+      while (!clientId) clientId = (await rl.question("Client ID: ")).trim();
+      while (!clientSecret) clientSecret = (await rl.question("Client Secret: ")).trim();
+    } else {
+      console.log(`Using the Client ID from ${ENV_FILE}. Make sure ${REDIRECT_URI} is a Redirect URI in your Spotify app.`);
+    }
+    if (playlist === undefined && stdin.isTTY) {
+      console.log("\nWhen you're not playing anything, the turntable can play from a rotation like a radio station.");
+      playlist = (await rl.question("Paste a playlist link, type \"liked\" for your Liked Songs, or press Enter to skip: ")).trim();
+    }
+  } finally {
+    rl.close();
+  }
+
+  const refreshToken = await authorize(clientId, clientSecret);
+  const values = { SPOTIFY_CLIENT_ID: clientId, SPOTIFY_CLIENT_SECRET: clientSecret, SPOTIFY_REFRESH_TOKEN: refreshToken };
+  if (playlist) values.SPOTIFY_FALLBACK_PLAYLIST = playlist;
+
+  if (PRINT_ONLY) {
+    console.log("\nConnected. Add these to your environment (keep them secret):\n");
+    for (const [k, v] of Object.entries(values)) console.log(`${k}=${v}`);
+  } else {
+    writeFileSync(ENV_FILE, upsertEnv(read(ENV_FILE), values));
+    console.log(`\nConnected! Saved your credentials to ${ENV_FILE}.`);
+    if (existsSync(".git") && !isGitIgnored(ENV_FILE)) {
+      console.log(`\n⚠  ${ENV_FILE} doesn't look git-ignored. Add it to .gitignore so you never commit your secret.`);
+    }
+  }
+  console.log("\nRestart your dev server and the turntable will be live.");
+  console.log("Deploying? Add the same SPOTIFY_* values as environment variables on your host (Vercel, Netlify…).");
+}
+
+main().catch((err) => {
+  console.error(`\n${err.message}`);
+  exit(1);
+});

package/package.json

@@ -1,6 +1,69 @@
-{
-  "name": "spotify-turntable",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "spotify-turntable",
+  "version": "0.1.0",
+  "description": "A live record-player card for whatever you're playing on Spotify. Drop in a React component, add your credentials, done.",
+  "keywords": [
+    "spotify",
+    "now-playing",
+    "react",
+    "turntable",
+    "portfolio",
+    "widget",
+    "vite",
+    "nextjs"
+  ],
+  "license": "MIT",
+  "author": "Felix Arbucias",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/felixArbucias/portfolio.git",
+    "directory": "packages/spotify-turntable"
+  },
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": "./src/client/index.js",
+    "./server": "./src/server/index.js",
+    "./vite": "./src/vite.js",
+    "./style.css": "./src/style.css",
+    "./package.json": "./package.json"
+  },
+  "main": "./src/client/index.js",
+  "bin": {
+    "spotify-turntable": "bin/spotify-turntable.mjs"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "auth": "node bin/spotify-turntable.mjs auth",
+    "dev": "vite example",
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "vite": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@vitejs/plugin-react": "^4.3.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "vite": "^5.4.1"
+  }
+}