pi-spotify-widget 0.1.0

package/lib/refresh-schedule.ts

@@ -0,0 +1,46 @@
+import type { PlaybackSnapshot } from "./playback-snapshot.ts";
+import { effectiveProgressMs } from "./widget-render.ts";
+
+export const POLL_IDLE_MS = 10_000;
+export const POLL_PAUSED_MS = 15_000;
+export const POLL_PLAYING_MS = 5_000;
+export const POLL_NEAR_END_MS = 1_500;
+export const NEAR_END_THRESHOLD_MS = 5_000;
+export const TRACK_END_GRACE_MS = 500;
+
+export function remainingMs(snapshot: PlaybackSnapshot, now = Date.now()): number | null {
+  if (!snapshot.isPlaying) return null;
+  const progress = effectiveProgressMs(snapshot, now);
+  if (progress === undefined) return null;
+  if (typeof snapshot.durationMs !== "number" || snapshot.durationMs <= 0) return null;
+  return snapshot.durationMs - progress;
+}
+
+export function computeRefreshDelayMs(snapshot: PlaybackSnapshot | null, now = Date.now()): number {
+  if (!snapshot?.track) return POLL_IDLE_MS;
+  if (!snapshot.isPlaying) return POLL_PAUSED_MS;
+
+  const remaining = remainingMs(snapshot, now);
+  if (remaining === null) return POLL_PLAYING_MS;
+  if (remaining <= NEAR_END_THRESHOLD_MS) return POLL_NEAR_END_MS;
+  return POLL_PLAYING_MS;
+}
+
+export function shouldRefreshAtTrackEnd(snapshot: PlaybackSnapshot, now = Date.now()): boolean {
+  if (!snapshot.isPlaying || !snapshot.track) return false;
+  const remaining = remainingMs(snapshot, now);
+  if (remaining === null) return false;
+  return remaining <= TRACK_END_GRACE_MS;
+}
+
+export function trackIdentity(snapshot: PlaybackSnapshot | null): string {
+  if (!snapshot?.track) return "";
+  return `${snapshot.track}::${snapshot.artist}`;
+}
+
+export const __testing = {
+  remainingMs,
+  computeRefreshDelayMs,
+  shouldRefreshAtTrackEnd,
+  trackIdentity,
+};

package/lib/spotify-api.ts

@@ -0,0 +1,147 @@
+import { getValidAccessToken, refreshAccessToken, setLastFetchAt } from "./spotify-auth.ts";
+import { loadAuth } from "./auth-store.ts";
+import { SPOTIFY_API_BASE } from "./spotify-config.ts";
+import type { SpotifyCurrentlyPlayingRaw } from "./playback-snapshot.ts";
+
+export interface FetchOptions {
+  fetchFn?: typeof fetch;
+}
+
+async function authorizedRequest(
+  method: string,
+  path: string,
+  accessToken: string,
+  fetchFn: typeof fetch,
+  body?: unknown,
+): Promise<Response> {
+  const init: RequestInit = {
+    method,
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+    },
+  };
+  if (body !== undefined) {
+    init.headers = {
+      ...init.headers,
+      "Content-Type": "application/json",
+    };
+    init.body = JSON.stringify(body);
+  }
+  return fetchFn(`${SPOTIFY_API_BASE}${path}`, init);
+}
+
+async function withAuthorizedRetry(
+  method: string,
+  path: string,
+  options: FetchOptions = {},
+  body?: unknown,
+): Promise<Response> {
+  const fetchFn = options.fetchFn ?? fetch;
+  let accessToken = await getValidAccessToken({ fetchFn });
+  if (!accessToken) {
+    throw new Error("Spotify is not authenticated. Run /spotify:login.");
+  }
+
+  let res = await authorizedRequest(method, path, accessToken, fetchFn, body);
+
+  if (res.status === 401) {
+    const auth = loadAuth();
+    if (!auth) {
+      throw new Error("Spotify is not authenticated. Run /spotify:login.");
+    }
+    try {
+      const refreshed = await refreshAccessToken(auth, { fetchFn });
+      accessToken = refreshed.accessToken;
+      res = await authorizedRequest(method, path, accessToken, fetchFn, body);
+    } catch {
+      throw new Error("Spotify token refresh failed. Run /spotify:login again.");
+    }
+  }
+
+  return res;
+}
+
+function assertPlaybackControlOk(res: Response, action: string): void {
+  if (res.status === 204 || res.status === 200) return;
+  if (res.status === 403) {
+    throw new Error(`Spotify ${action} failed: no active device. Open Spotify on a device and try again.`);
+  }
+  throw new Error(`Spotify ${action} failed (HTTP ${res.status}).`);
+}
+
+export async function fetchCurrentlyPlaying(
+  options: FetchOptions = {},
+): Promise<SpotifyCurrentlyPlayingRaw | null> {
+  const fetchFn = options.fetchFn ?? fetch;
+  const accessToken = await getValidAccessToken({ fetchFn });
+  if (!accessToken) return null;
+
+  let res = await authorizedRequest("GET", "/me/player/currently-playing", accessToken, fetchFn);
+
+  if (res.status === 401) {
+    const auth = loadAuth();
+    if (!auth) return null;
+    try {
+      const refreshed = await refreshAccessToken(auth, { fetchFn });
+      res = await authorizedRequest("GET", "/me/player/currently-playing", refreshed.accessToken, fetchFn);
+    } catch {
+      return null;
+    }
+  }
+
+  if (res.status === 204 || res.status === 404) {
+    setLastFetchAt(Date.now());
+    return null;
+  }
+
+  if (!res.ok) {
+    throw new Error(`Spotify currently-playing request failed (HTTP ${res.status})`);
+  }
+
+  const raw = await res.json() as SpotifyCurrentlyPlayingRaw;
+  setLastFetchAt(Date.now());
+  return raw;
+}
+
+export async function skipToNext(options: FetchOptions = {}): Promise<void> {
+  const res = await withAuthorizedRetry("POST", "/me/player/next", options);
+  assertPlaybackControlOk(res, "skip to next track");
+}
+
+export async function skipToPrevious(options: FetchOptions = {}): Promise<void> {
+  const res = await withAuthorizedRetry("POST", "/me/player/previous", options);
+  assertPlaybackControlOk(res, "skip to previous track");
+}
+
+export async function pausePlayback(options: FetchOptions = {}): Promise<void> {
+  const res = await withAuthorizedRetry("PUT", "/me/player/pause", options);
+  assertPlaybackControlOk(res, "pause");
+}
+
+export async function resumePlayback(options: FetchOptions = {}): Promise<void> {
+  const res = await withAuthorizedRetry("PUT", "/me/player/play", options, {});
+  assertPlaybackControlOk(res, "resume");
+}
+
+export async function playTrackUri(trackUri: string, options: FetchOptions = {}): Promise<void> {
+  const uri = trackUri.trim();
+  if (!uri.startsWith("spotify:track:")) {
+    throw new Error("Expected a Spotify track URI like spotify:track:... or pass a track URL via /spotify:play-uri.");
+  }
+  const res = await withAuthorizedRetry("PUT", "/me/player/play", options, { uris: [uri] });
+  assertPlaybackControlOk(res, "play track");
+}
+
+export function spotifyUrlToTrackUri(urlOrUri: string): string {
+  const value = urlOrUri.trim();
+  if (value.startsWith("spotify:track:")) return value;
+  const match = value.match(/open\.spotify\.com\/track\/([A-Za-z0-9]+)/);
+  if (match?.[1]) return `spotify:track:${match[1]}`;
+  throw new Error("Could not parse Spotify track URL or URI.");
+}
+
+export const __testing = {
+  authorizedRequest,
+  assertPlaybackControlOk,
+  withAuthorizedRetry,
+};

package/lib/spotify-auth.ts

@@ -0,0 +1,352 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import { spawn } from "node:child_process";
+import { URL } from "node:url";
+import {
+  clearAuth,
+  authFileExists,
+  getAuthFilePath,
+  isConfigured,
+  loadAuth,
+  saveAuth,
+  type SpotifyAuthRecord,
+} from "./auth-store.ts";
+import {
+  CALLBACK_HOST,
+  CALLBACK_PATH,
+  CALLBACK_PORT,
+  LOGIN_TIMEOUT_MS,
+  REDIRECT_URI,
+  clientIdStatusText,
+  requireClientId,
+  resolveClientId,
+  scopeString,
+  SPOTIFY_AUTH_URL,
+  SPOTIFY_TOKEN_URL,
+  TOKEN_REFRESH_BUFFER_MS,
+} from "./spotify-config.ts";
+
+export interface SecretSafeStatus {
+  configured: boolean;
+  expired: boolean;
+  expiresInText: string;
+  authFilePath: string;
+  source: "spotify-web-api";
+  lastFetchText: string;
+}
+
+let lastFetchAt: number | null = null;
+
+export function setLastFetchAt(timestamp: number | null): void {
+  lastFetchAt = timestamp;
+}
+
+export function getLastFetchAt(): number | null {
+  return lastFetchAt;
+}
+
+export function generateCodeVerifier(): string {
+  return randomBytes(32).toString("base64url");
+}
+
+export function generateCodeChallenge(verifier: string): string {
+  return createHash("sha256").update(verifier).digest("base64url");
+}
+
+export function isExpired(auth: SpotifyAuthRecord, now = Date.now()): boolean {
+  return auth.expiresAt <= now;
+}
+
+export function needsRefresh(auth: SpotifyAuthRecord, now = Date.now()): boolean {
+  return auth.expiresAt - now <= TOKEN_REFRESH_BUFFER_MS;
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function ageText(timestamp: number | null): string {
+  if (!timestamp) return "never";
+  const seconds = Math.max(0, Math.floor((Date.now() - timestamp) / 1000));
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h ago`;
+}
+
+function expiresInText(auth: SpotifyAuthRecord | null, now = Date.now()): string {
+  if (!auth) return "n/a";
+  const diffMs = auth.expiresAt - now;
+  if (diffMs <= 0) return "expired";
+  const minutes = Math.ceil(diffMs / 60_000);
+  if (minutes < 60) return `in ${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  const remMinutes = minutes % 60;
+  return remMinutes > 0 ? `in ${hours}h ${remMinutes}m` : `in ${hours}h`;
+}
+
+export function formatSecretSafeStatus(now = Date.now()): string {
+  const auth = loadAuth();
+  const status: SecretSafeStatus = {
+    configured: isConfigured(),
+    expired: auth ? isExpired(auth, now) : false,
+    expiresInText: expiresInText(auth, now),
+    authFilePath: getAuthFilePath(),
+    source: "spotify-web-api",
+    lastFetchText: ageText(lastFetchAt),
+  };
+
+  const authFileState = authFileExists()
+    ? (status.configured ? "present" : "present but invalid or incomplete")
+    : "missing";
+  const lines = [
+    clientIdStatusText(),
+    `oauth: ${status.configured ? "connected" : "not connected"}`,
+    `configured: ${status.configured ? "yes" : "no"}`,
+    `expires: ${status.expiresInText}`,
+    `lastFetch: ${status.lastFetchText}`,
+    `source: ${status.source}`,
+    `auth file: ${status.authFilePath} (${authFileState})`,
+  ];
+  if (!status.configured && resolveClientId()) {
+    lines.push("next: run /spotify:login and approve access in the browser");
+  }
+  return lines.join("\n");
+}
+
+export function openExternalUrl(url: string): void {
+  if (process.env.PI_SPOTIFY_DISABLE_OPEN === "1") return;
+
+  // Windows `cmd start` truncates URLs at `&`, which breaks Spotify OAuth query strings.
+  if (process.platform === "win32") {
+    const child = spawn(
+      "powershell",
+      ["-NoProfile", "-Command", `Start-Process ${JSON.stringify(url)}`],
+      { detached: true, stdio: "ignore", shell: false },
+    );
+    child.unref?.();
+    return;
+  }
+
+  const command = process.platform === "darwin" ? "open" : "xdg-open";
+  const child = spawn(command, [url], { detached: true, stdio: "ignore", shell: false });
+  child.unref?.();
+}
+
+function buildAuthorizeUrl(clientId: string, codeChallenge: string, state: string): string {
+  const params = new URLSearchParams({
+    client_id: clientId,
+    response_type: "code",
+    redirect_uri: REDIRECT_URI,
+    scope: scopeString(),
+    code_challenge_method: "S256",
+    code_challenge: codeChallenge,
+    state,
+  });
+  return `${SPOTIFY_AUTH_URL}?${params.toString()}`;
+}
+
+interface TokenResponse {
+  access_token: string;
+  refresh_token?: string;
+  expires_in: number;
+  scope?: string;
+}
+
+async function exchangeToken(
+  body: URLSearchParams,
+  fetchFn: typeof fetch = fetch,
+): Promise<TokenResponse> {
+  const res = await fetchFn(SPOTIFY_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body,
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => "");
+    throw new Error(`Spotify token exchange failed (HTTP ${res.status})${text ? `: ${text.slice(0, 120)}` : ""}`);
+  }
+  return res.json() as Promise<TokenResponse>;
+}
+
+function authFromTokenResponse(
+  token: TokenResponse,
+  previous?: SpotifyAuthRecord | null,
+): SpotifyAuthRecord {
+  const refreshToken = token.refresh_token ?? previous?.refreshToken;
+  if (!refreshToken) {
+    throw new Error("Spotify token response did not include a refresh token.");
+  }
+  return {
+    accessToken: token.access_token,
+    refreshToken,
+    expiresAt: Date.now() + token.expires_in * 1000,
+    scope: token.scope ?? previous?.scope ?? scopeString(),
+    updatedAt: nowIso(),
+  };
+}
+
+function parseCallbackRequest(req: IncomingMessage): { code?: string; error?: string; state?: string } {
+  const host = req.headers.host ?? `${CALLBACK_HOST}:${CALLBACK_PORT}`;
+  const url = new URL(req.url ?? "/", `http://${host}`);
+  return {
+    code: url.searchParams.get("code") ?? undefined,
+    error: url.searchParams.get("error") ?? undefined,
+    state: url.searchParams.get("state") ?? undefined,
+  };
+}
+
+function sendCallbackPage(res: ServerResponse, title: string, message: string): void {
+  const html = `<!doctype html><html><head><meta charset="utf-8"><title>${title}</title></head><body><p>${message}</p><p>You can close this tab and return to Pi.</p></body></html>`;
+  res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+  res.end(html);
+}
+
+export interface LoginOptions {
+  clientId?: string;
+  fetchFn?: typeof fetch;
+  openUrl?: (url: string) => void;
+  onAuthorizeUrl?: (url: string) => void;
+}
+
+export async function login(options: LoginOptions = {}): Promise<void> {
+  const clientId = options.clientId?.trim() || requireClientId();
+  const fetchFn = options.fetchFn ?? fetch;
+  const openUrl = options.openUrl ?? openExternalUrl;
+  const verifier = generateCodeVerifier();
+  const challenge = generateCodeChallenge(verifier);
+  const state = randomBytes(16).toString("hex");
+
+  const code = await new Promise<string>((resolve, reject) => {
+    const server = createServer((req, res) => {
+      if ((req.url ?? "").split("?")[0] !== CALLBACK_PATH) {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+
+      const parsed = parseCallbackRequest(req);
+      if (parsed.state && parsed.state !== state) {
+        sendCallbackPage(res, "Spotify login failed", "State mismatch. Return to Pi and run /spotify:login again.");
+        server.close();
+        reject(new Error("OAuth state mismatch. Run /spotify:login again."));
+        return;
+      }
+      if (parsed.error) {
+        sendCallbackPage(res, "Spotify login failed", "Authorization was denied or failed.");
+        server.close();
+        reject(new Error(`Spotify authorization failed: ${parsed.error}`));
+        return;
+      }
+      if (!parsed.code) {
+        sendCallbackPage(res, "Spotify login failed", "Missing authorization code.");
+        server.close();
+        reject(new Error("Spotify callback did not include an authorization code."));
+        return;
+      }
+
+      sendCallbackPage(res, "Spotify login successful", "Authorization complete.");
+      server.close();
+      resolve(parsed.code);
+    });
+
+    server.on("error", (error: NodeJS.ErrnoException) => {
+      if (error.code === "EADDRINUSE") {
+        reject(new Error(
+          `Port ${CALLBACK_PORT} is already in use. Close the other app using it and run /spotify:login again.`,
+        ));
+        return;
+      }
+      reject(error);
+    });
+
+    server.listen(CALLBACK_PORT, CALLBACK_HOST, () => {
+      const authorizeUrl = buildAuthorizeUrl(clientId, challenge, state);
+      options.onAuthorizeUrl?.(authorizeUrl);
+      openUrl(authorizeUrl);
+    });
+
+    setTimeout(() => {
+      server.close();
+      reject(new Error("Spotify login timed out after 5 minutes. Run /spotify:login to try again."));
+    }, LOGIN_TIMEOUT_MS).unref?.();
+  });
+
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: REDIRECT_URI,
+    client_id: clientId,
+    code_verifier: verifier,
+  });
+  const token = await exchangeToken(body, fetchFn);
+  saveAuth(authFromTokenResponse(token));
+}
+
+export interface RefreshOptions {
+  fetchFn?: typeof fetch;
+}
+
+export async function refreshAccessToken(
+  auth: SpotifyAuthRecord,
+  options: RefreshOptions = {},
+): Promise<SpotifyAuthRecord> {
+  const fetchFn = options.fetchFn ?? fetch;
+  const clientId = requireClientId();
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: auth.refreshToken,
+    client_id: clientId,
+  });
+  const token = await exchangeToken(body, fetchFn);
+  const next = authFromTokenResponse(token, auth);
+  saveAuth(next);
+  return next;
+}
+
+export async function refreshIfNeeded(options: RefreshOptions = {}): Promise<SpotifyAuthRecord | null> {
+  const auth = loadAuth();
+  if (!auth) return null;
+  if (!needsRefresh(auth)) return auth;
+  try {
+    return await refreshAccessToken(auth, options);
+  } catch {
+    clearAuth();
+    return null;
+  }
+}
+
+export async function getValidAccessToken(options: RefreshOptions = {}): Promise<string | null> {
+  const auth = await refreshIfNeeded(options);
+  if (!auth) return null;
+  if (isExpired(auth)) {
+    try {
+      const refreshed = await refreshAccessToken(auth, options);
+      return refreshed.accessToken;
+    } catch {
+      clearAuth();
+      return null;
+    }
+  }
+  return auth.accessToken;
+}
+
+export function logout(): void {
+  clearAuth();
+  lastFetchAt = null;
+}
+
+export const __testing = {
+  ageText,
+  authFromTokenResponse,
+  buildAuthorizeUrl,
+  exchangeToken,
+  expiresInText,
+  generateCodeChallenge,
+  generateCodeVerifier,
+  isExpired,
+  needsRefresh,
+  parseCallbackRequest,
+  resolveClientId,
+};

package/lib/spotify-config.ts

@@ -0,0 +1,128 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "./auth-store.ts";
+
+export const BUNDLED_CLIENT_ID = "";
+export const SPOTIFY_DASHBOARD_URL = "https://developer.spotify.com/dashboard";
+
+export const REDIRECT_URI = "http://127.0.0.1:8888/callback";
+export const CALLBACK_HOST = "127.0.0.1";
+export const CALLBACK_PORT = 8888;
+export const CALLBACK_PATH = "/callback";
+
+export const SCOPES = [
+  "user-read-playback-state",
+  "user-read-currently-playing",
+  "user-modify-playback-state",
+] as const;
+
+export const SPOTIFY_AUTH_URL = "https://accounts.spotify.com/authorize";
+export const SPOTIFY_TOKEN_URL = "https://accounts.spotify.com/api/token";
+export const SPOTIFY_API_BASE = "https://api.spotify.com/v1";
+
+export const TOKEN_REFRESH_BUFFER_MS = 5 * 60 * 1000;
+export const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+/** @deprecated use refresh-schedule constants */
+export const POLL_INTERVAL_MS = 5 * 1000;
+
+export const AUTH_FILE_NAME = "pi-spotify-widget-auth.json";
+export const CONFIG_FILE_NAME = "pi-spotify-widget-config.json";
+export const WIDGET_ID = "pi-spotify-widget";
+
+export type ClientIdSource = "environment" | "stored" | "bundled" | "missing";
+
+export interface SpotifyClientConfigRecord {
+  clientId: string;
+  updatedAt: string;
+}
+
+export function getConfigFilePath(): string {
+  return join(getAgentDir(), CONFIG_FILE_NAME);
+}
+
+function ensureAgentDir(): void {
+  try {
+    mkdirSync(getAgentDir(), { recursive: true });
+  } catch {
+    // ignore
+  }
+}
+
+export function loadStoredClientId(): string | undefined {
+  const file = getConfigFilePath();
+  try {
+    if (!existsSync(file)) return undefined;
+    const parsed = JSON.parse(readFileSync(file, "utf-8")) as Partial<SpotifyClientConfigRecord>;
+    const trimmed = typeof parsed.clientId === "string" ? parsed.clientId.trim() : "";
+    return trimmed || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function saveStoredClientId(clientId: string): void {
+  ensureAgentDir();
+  const file = getConfigFilePath();
+  const record: SpotifyClientConfigRecord = {
+    clientId: clientId.trim(),
+    updatedAt: new Date().toISOString(),
+  };
+  writeFileSync(file, JSON.stringify(record, null, 2), "utf-8");
+  try {
+    chmodSync(file, 0o600);
+  } catch {
+    // ignore chmod errors on platforms without POSIX modes
+  }
+}
+
+export function clearStoredClientId(): void {
+  const file = getConfigFilePath();
+  try {
+    if (existsSync(file)) rmSync(file);
+  } catch {
+    // ignore
+  }
+}
+
+export function resolveClientIdSource(env: NodeJS.ProcessEnv = process.env): ClientIdSource {
+  if (env.PI_SPOTIFY_CLIENT_ID?.trim()) return "environment";
+  if (loadStoredClientId()) return "stored";
+  if (BUNDLED_CLIENT_ID) return "bundled";
+  return "missing";
+}
+
+export function resolveClientId(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.PI_SPOTIFY_CLIENT_ID?.trim();
+  if (override) return override;
+  const stored = loadStoredClientId();
+  if (stored) return stored;
+  return BUNDLED_CLIENT_ID;
+}
+
+export function clientIdStatusText(env: NodeJS.ProcessEnv = process.env): string {
+  const source = resolveClientIdSource(env);
+  if (source === "environment") {
+    return "Spotify Client ID: configured via PI_SPOTIFY_CLIENT_ID environment variable.";
+  }
+  if (source === "stored") {
+    return "Spotify Client ID: configured via /spotify:login.";
+  }
+  if (source === "bundled") {
+    return "Spotify Client ID: configured via bundled app.";
+  }
+  return "Spotify Client ID: not configured. Run /spotify:login.";
+}
+
+export function requireClientId(env: NodeJS.ProcessEnv = process.env): string {
+  const clientId = resolveClientId(env);
+  if (!clientId) {
+    throw new Error(
+      "Spotify Client ID is not configured. Run /spotify:login to open the Spotify Developer Dashboard and enter your Client ID.",
+    );
+  }
+  return clientId;
+}
+
+export function scopeString(): string {
+  return SCOPES.join(" ");
+}