pi-spotify-widget 0.1.0

package/extensions/index.ts

@@ -0,0 +1,413 @@
+/**
+ * pi-spotify-widget - Pi coding-agent extension
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { isConfigured } from "../lib/auth-store.ts";
+import {
+  formatSecretSafeStatus,
+  login,
+  logout,
+  openExternalUrl,
+} from "../lib/spotify-auth.ts";
+import {
+  fetchCurrentlyPlaying,
+  pausePlayback,
+  playTrackUri,
+  resumePlayback,
+  skipToNext,
+  skipToPrevious,
+  spotifyUrlToTrackUri,
+} from "../lib/spotify-api.ts";
+import {
+  toPlaybackSnapshot,
+  type PlaybackSnapshot,
+} from "../lib/playback-snapshot.ts";
+import {
+  formatPlaybackHelpMarkdown,
+  playbackCommandById,
+} from "../lib/playback-commands.ts";
+import {
+  computeRefreshDelayMs,
+  shouldRefreshAtTrackEnd,
+  trackIdentity,
+} from "../lib/refresh-schedule.ts";
+import {
+  REDIRECT_URI,
+  resolveClientId,
+  saveStoredClientId,
+  SPOTIFY_DASHBOARD_URL,
+  WIDGET_ID,
+} from "../lib/spotify-config.ts";
+import { openSpotifySharePost } from "../lib/x-share.ts";
+import {
+  renderError,
+  renderIdle,
+  renderNoAuth,
+  renderSnapshot,
+} from "../lib/widget-render.ts";
+
+type SetWidget = (id: string, lines: string[] | undefined) => void;
+type Theme = {
+  fg: (color: "accent" | "dim" | "muted" | "success" | "error", text: string) => string;
+};
+
+type WidgetCtx = {
+  hasUI: boolean;
+  ui: {
+    notify: (msg: string, level: "info" | "warning" | "error") => void;
+    setWidget: SetWidget;
+    setStatus: (key: string, text: string | undefined) => void;
+    theme: Theme;
+  };
+};
+
+const COMMANDS = [
+  ["login", "open Spotify Developer Dashboard, enter Client ID, OAuth PKCE login"],
+  ["status", "show secret-safe Spotify auth status"],
+  ["logout", "remove stored Spotify tokens"],
+  ["refresh", "force playback snapshot fetch"],
+  ["prev", "skip to previous track"],
+  ["next", "skip to next track"],
+  ["pause", "pause playback"],
+  ["play", "resume playback"],
+  ["help", "show playback command list for AI/user"],
+  ["share", "open X compose with now playing (soccer-widget style)"],
+  ["play-uri", "play a Spotify track URL or URI"],
+] as const;
+
+const DISPLAY_TICK_MS = 1000;
+const TRACK_END_FETCH_COOLDOWN_MS = 800;
+
+let refreshTimer: ReturnType<typeof setTimeout> | null = null;
+let displayTimer: ReturnType<typeof setInterval> | null = null;
+let lastSnapshot: PlaybackSnapshot | null = null;
+let lastTrackEndFetchAt = 0;
+let widgetCtx: WidgetCtx | null = null;
+
+function clearRefreshTimer(): void {
+  if (refreshTimer) {
+    clearTimeout(refreshTimer);
+    refreshTimer = null;
+  }
+}
+
+function clearDisplayTimer(): void {
+  if (displayTimer) {
+    clearInterval(displayTimer);
+    displayTimer = null;
+  }
+}
+
+function clearAllTimers(): void {
+  clearRefreshTimer();
+  clearDisplayTimer();
+  widgetCtx = null;
+}
+
+function isStaleContextError(error: unknown): boolean {
+  return error instanceof Error && error.message.includes("This extension ctx is stale");
+}
+
+function showText(
+  ctx: { ui: { notify: (msg: string, level: "info" | "warning" | "error") => void } },
+  text: string,
+  level: "info" | "warning" | "error" = "info",
+): void {
+  const firstLine = text.split(/\r?\n/)[0] ?? text;
+  ctx.ui.notify(firstLine, level);
+}
+
+function formatStatusMarkdown(): string {
+  return ["### Spotify status", "", "```text", formatSecretSafeStatus(), "```"].join("\n");
+}
+
+function statusFooterText(): string | undefined {
+  if (!isConfigured()) return "Spotify: not logged in";
+  const line = formatSecretSafeStatus().split(/\r?\n/).find((entry) => entry.startsWith("expires:"));
+  return line ? `Spotify · ${line.replace("expires: ", "expires ")}` : "Spotify · logged in";
+}
+
+async function showCommandOutput(
+  pi: ExtensionAPI,
+  ctx: ExtensionCommandContext,
+  kind: string,
+  content: string,
+  level: "info" | "warning" | "error" = "info",
+): Promise<void> {
+  showText(ctx, content, level);
+  pi.sendMessage({ customType: "spotify-widget", content, display: true, details: { kind } });
+}
+
+function clientIdGuideText(): string {
+  return [
+    "Spotify Developer setup:",
+    `1. Open: ${SPOTIFY_DASHBOARD_URL}`,
+    "2. Create an app in the Spotify Developer Dashboard.",
+    `3. Add redirect URI: ${REDIRECT_URI}`,
+    "4. Copy the Client ID (Client Secret is not needed for PKCE).",
+    "5. Paste the Client ID into the Pi prompt below.",
+  ].join("\n");
+}
+
+async function ensureClientIdForLogin(ctx: ExtensionCommandContext): Promise<string | undefined> {
+  if (!ctx.hasUI) throw new Error("Spotify login requires interactive UI. Run /spotify:login inside Pi.");
+  let clientId = resolveClientId();
+  if (clientId) {
+    showText(ctx, "Client ID is already saved. Opening Spotify authorization in your browser.", "info");
+    return clientId;
+  }
+  showText(ctx, clientIdGuideText(), "info");
+  openExternalUrl(SPOTIFY_DASHBOARD_URL);
+  const entered = await ctx.ui.input("Spotify Client ID:", "paste Client ID from Developer Dashboard");
+  clientId = String(entered ?? "").trim();
+  if (!clientId) {
+    showText(ctx, "Spotify Client ID was not saved.", "warning");
+    return undefined;
+  }
+  saveStoredClientId(clientId);
+  showText(ctx, "Saved Spotify Client ID for pi-spotify-widget.");
+  return clientId;
+}
+
+function applySnapshotToWidget(setWidget: SetWidget, theme: Theme, snapshot: PlaybackSnapshot | null, stale = false): void {
+  if (!snapshot?.track) {
+    const idle: PlaybackSnapshot = snapshot ?? { track: "", artist: "", isPlaying: false, fetchedAt: Date.now() };
+    setWidget(WIDGET_ID, renderIdle(idle, theme, { stale }));
+    return;
+  }
+  setWidget(WIDGET_ID, renderSnapshot(snapshot, theme, { stale }));
+}
+
+async function refreshWidget(setWidget: SetWidget, theme: Theme): Promise<void> {
+  if (!isConfigured()) {
+    lastSnapshot = null;
+    setWidget(WIDGET_ID, renderNoAuth(theme));
+    return;
+  }
+  const previousIdentity = trackIdentity(lastSnapshot);
+  try {
+    const raw = await fetchCurrentlyPlaying();
+    const snapshot = toPlaybackSnapshot(raw);
+    if (snapshot) {
+      lastSnapshot = snapshot;
+      applySnapshotToWidget(setWidget, theme, snapshot);
+    } else {
+      lastSnapshot = { track: "", artist: "", isPlaying: false, fetchedAt: Date.now() };
+      applySnapshotToWidget(setWidget, theme, lastSnapshot);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (lastSnapshot?.track || lastSnapshot) {
+      applySnapshotToWidget(setWidget, theme, lastSnapshot, true);
+      return;
+    }
+    setWidget(WIDGET_ID, renderError(message, theme));
+    return;
+  }
+  const nextIdentity = trackIdentity(lastSnapshot);
+  if (previousIdentity && nextIdentity && previousIdentity !== nextIdentity) scheduleNextRefresh(0);
+}
+
+function scheduleNextRefresh(delayOverrideMs?: number): void {
+  clearRefreshTimer();
+  if (!widgetCtx) return;
+  const delay = delayOverrideMs ?? computeRefreshDelayMs(lastSnapshot);
+  const run = () => {
+    if (!widgetCtx) return;
+    void refreshWidget((id, lines) => widgetCtx!.ui.setWidget(id, lines), widgetCtx.ui.theme)
+      .catch((error) => {
+        if (isStaleContextError(error)) { clearRefreshTimer(); return; }
+        const message = error instanceof Error ? error.message : String(error);
+        try { widgetCtx?.ui.setWidget(WIDGET_ID, renderError(message, widgetCtx.ui.theme)); } catch { /* ignore */ }
+      })
+      .finally(() => scheduleNextRefresh());
+  };
+  if (delay <= 0) { run(); return; }
+  refreshTimer = setTimeout(run, delay);
+  refreshTimer.unref?.();
+}
+
+function resetDisplayTimer(ctx: WidgetCtx): void {
+  clearDisplayTimer();
+  displayTimer = setInterval(() => {
+    if (!lastSnapshot) return;
+    try {
+      ctx.ui.setWidget(WIDGET_ID, lastSnapshot.track ? renderSnapshot(lastSnapshot, ctx.ui.theme) : renderIdle(lastSnapshot, ctx.ui.theme));
+    } catch (error) {
+      if (isStaleContextError(error)) clearDisplayTimer();
+    }
+    if (!lastSnapshot.isPlaying || !lastSnapshot.track) return;
+    if (!shouldRefreshAtTrackEnd(lastSnapshot)) return;
+    const now = Date.now();
+    if (now - lastTrackEndFetchAt < TRACK_END_FETCH_COOLDOWN_MS) return;
+    lastTrackEndFetchAt = now;
+    void refreshWidget((id, lines) => ctx.ui.setWidget(id, lines), ctx.ui.theme).finally(() => scheduleNextRefresh());
+  }, DISPLAY_TICK_MS);
+  displayTimer.unref?.();
+}
+
+function bindWidgetContext(ctx: WidgetCtx): void {
+  widgetCtx = ctx;
+  scheduleNextRefresh();
+  resetDisplayTimer(ctx);
+}
+
+async function runPlaybackControl(command: "prev" | "next" | "pause" | "play"): Promise<string> {
+  if (command === "prev") { await skipToPrevious(); return "Spotify: previous track."; }
+  if (command === "next") { await skipToNext(); return "Spotify: next track."; }
+  if (command === "pause") { await pausePlayback(); return "Spotify: paused."; }
+  await resumePlayback();
+  return "Spotify: resumed.";
+}
+
+function shareOutputMarkdown(result: { mode: "api" | "intent"; text: string; tweetUrl?: string; intentUrl?: string }): string {
+  if (result.mode === "api") {
+    const parts = ["### Shared on X", "", "```text", result.text, "```"];
+    if (result.tweetUrl) parts.push("", `Posted: ${result.tweetUrl}`);
+    return parts.join("\n");
+  }
+  const parts = [
+    "### Share on X",
+    "",
+    "ブラウザで X の投稿画面を開きます。開かない場合は次の URL をクリックしてください:",
+    "",
+  ];
+  if (result.intentUrl) parts.push(result.intentUrl, "");
+  parts.push("```text", result.text, "```");
+  return parts.join("\n");
+}
+
+async function handleSpotifyCommand(pi: ExtensionAPI, args: string, ctx: WidgetCtx): Promise<void> {
+  const theme = ctx.ui.theme;
+  const trimmed = String(args ?? "").trim();
+  const [commandRaw] = trimmed.split(/\s+/).filter(Boolean);
+  const command = (commandRaw ?? "").toLowerCase();
+
+  if (command === "login") {
+    try {
+      const clientId = await ensureClientIdForLogin(ctx as ExtensionCommandContext);
+      if (!clientId) return;
+      await login({
+        clientId,
+        onAuthorizeUrl: (authorizeUrl) => {
+          void showCommandOutput(pi, ctx as ExtensionCommandContext, "authorize-url", ["### Spotify authorization", "", authorizeUrl].join("\n"));
+        },
+      });
+      showText(ctx, "Spotify login successful.");
+      await refreshWidget((id, lines) => ctx.ui.setWidget(id, lines), theme);
+      scheduleNextRefresh(0);
+    } catch (error) {
+      showText(ctx, `Spotify login failed: ${error instanceof Error ? error.message : String(error)}`, "warning");
+    }
+    return;
+  }
+
+  if (command === "status") {
+    await showCommandOutput(pi, ctx as ExtensionCommandContext, "status", formatStatusMarkdown());
+    ctx.ui.setStatus("spotify", statusFooterText());
+    return;
+  }
+
+  if (command === "logout") {
+    logout();
+    lastSnapshot = null;
+    ctx.ui.setWidget(WIDGET_ID, renderNoAuth(theme));
+    showText(ctx, "Spotify logout complete.");
+    scheduleNextRefresh();
+    return;
+  }
+
+  if (command === "refresh") {
+    await refreshWidget((id, lines) => ctx.ui.setWidget(id, lines), theme);
+    scheduleNextRefresh(0);
+    showText(ctx, "Spotify playback snapshot refreshed.");
+    return;
+  }
+
+  if (command === "help") {
+    await showCommandOutput(pi, ctx as ExtensionCommandContext, "help", formatPlaybackHelpMarkdown());
+    return;
+  }
+
+  if (command === "share") {
+    try {
+      let snapshot = lastSnapshot;
+      if (!snapshot?.track) {
+        await refreshWidget((id, lines) => ctx.ui.setWidget(id, lines), theme);
+        snapshot = lastSnapshot;
+      }
+      if (!snapshot?.track) {
+        showText(ctx, "Nothing playing to share.", "warning");
+        return;
+      }
+      const customPrefix = trimmed.slice(command.length).trim();
+      const result = openSpotifySharePost(snapshot, { customPrefix: customPrefix || undefined });
+      await showCommandOutput(pi, ctx as ExtensionCommandContext, "share", shareOutputMarkdown(result));
+      showText(ctx, "Opening X compose. Screenshot upload is manual.");
+    } catch (error) {
+      showText(ctx, error instanceof Error ? error.message : String(error), "warning");
+    }
+    return;
+  }
+
+  if (command === "play-uri" || command === "playuri") {
+    try {
+      const uriArg = trimmed.slice(command.length).trim();
+      if (!uriArg) {
+        showText(ctx, "Usage: /spotify:play-uri <spotify-track-url-or-uri>", "warning");
+        return;
+      }
+      await playTrackUri(spotifyUrlToTrackUri(uriArg));
+      await refreshWidget((id, lines) => ctx.ui.setWidget(id, lines), theme);
+      scheduleNextRefresh(0);
+      showText(ctx, "Spotify: playing requested track.");
+    } catch (error) {
+      showText(ctx, error instanceof Error ? error.message : String(error), "warning");
+    }
+    return;
+  }
+
+  const playback = playbackCommandById(command);
+  if (playback) {
+    try {
+      showText(ctx, await runPlaybackControl(playback.id));
+      await refreshWidget((id, lines) => ctx.ui.setWidget(id, lines), theme);
+      scheduleNextRefresh(0);
+    } catch (error) {
+      showText(ctx, error instanceof Error ? error.message : String(error), "warning");
+    }
+    return;
+  }
+
+  showText(ctx, `Unknown Spotify command: ${command || "(empty)"}. Try /spotify:help.`, "warning");
+}
+
+export const __testing = {
+  clearAllTimers,
+  clearDisplayTimer,
+  clearRefreshTimer,
+  getLastSnapshot: () => lastSnapshot,
+  refreshWidget,
+  resetLastSnapshot: () => { lastSnapshot = null; },
+  scheduleNextRefresh,
+};
+
+export default function spotifyWidgetExtension(pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, ctx) => {
+    if (!ctx.hasUI) return;
+    await refreshWidget((id, lines) => ctx.ui.setWidget(id, lines), ctx.ui.theme);
+    bindWidgetContext(ctx);
+  });
+  pi.on("session_shutdown", () => clearAllTimers());
+  for (const [command, description] of COMMANDS) {
+    pi.registerCommand(`spotify:${command}`, {
+      description: `Spotify: ${description}.`,
+      handler: async (args, ctx) => {
+        if (!ctx.hasUI) return;
+        const suffix = String(args ?? "").trim();
+        await handleSpotifyCommand(pi, suffix ? `${command} ${suffix}` : command, ctx);
+      },
+    });
+  }
+}

package/lib/auth-store.ts

@@ -0,0 +1,83 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { AUTH_FILE_NAME } from "./spotify-config.ts";
+
+export interface SpotifyAuthRecord {
+  accessToken: string;
+  refreshToken: string;
+  expiresAt: number;
+  scope: string;
+  updatedAt: string;
+}
+
+export function getAgentDir(): string {
+  const override = process.env.PI_SPOTIFY_AGENT_DIR?.trim();
+  if (override) return override;
+  return join(homedir(), ".pi", "agent");
+}
+
+export function getAuthFilePath(): string {
+  return join(getAgentDir(), AUTH_FILE_NAME);
+}
+
+export function authFileExists(): boolean {
+  return existsSync(getAuthFilePath());
+}
+
+function ensureAgentDir(): void {
+  try {
+    mkdirSync(getAgentDir(), { recursive: true });
+  } catch {
+    // ignore
+  }
+}
+
+export function loadAuth(): SpotifyAuthRecord | null {
+  const file = getAuthFilePath();
+  try {
+    if (!existsSync(file)) return null;
+    const parsed = JSON.parse(readFileSync(file, "utf-8")) as Partial<SpotifyAuthRecord>;
+    if (
+      typeof parsed.accessToken !== "string"
+      || typeof parsed.refreshToken !== "string"
+      || typeof parsed.expiresAt !== "number"
+    ) {
+      return null;
+    }
+    return {
+      accessToken: parsed.accessToken,
+      refreshToken: parsed.refreshToken,
+      expiresAt: parsed.expiresAt,
+      scope: typeof parsed.scope === "string" ? parsed.scope : "",
+      updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : new Date().toISOString(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function saveAuth(record: SpotifyAuthRecord): void {
+  ensureAgentDir();
+  const file = getAuthFilePath();
+  writeFileSync(file, JSON.stringify(record, null, 2), "utf-8");
+  try {
+    chmodSync(file, 0o600);
+  } catch {
+    // ignore chmod errors on platforms without POSIX modes
+  }
+}
+
+export function clearAuth(): void {
+  const file = getAuthFilePath();
+  try {
+    if (existsSync(file)) rmSync(file);
+  } catch {
+    // ignore
+  }
+}
+
+export function isConfigured(): boolean {
+  const auth = loadAuth();
+  return Boolean(auth?.accessToken && auth.refreshToken);
+}

package/lib/playback-commands.ts

@@ -0,0 +1,93 @@
+export type PlaybackCommandId = "prev" | "next" | "pause" | "play";
+
+export interface PlaybackCommandSpec {
+  id: PlaybackCommandId;
+  command: string;
+  spotifyAction: string;
+  description: string;
+  userPhrases: string[];
+}
+
+export const PLAYBACK_COMMANDS: PlaybackCommandSpec[] = [
+  {
+    id: "prev",
+    command: "/spotify:prev",
+    spotifyAction: "skip to previous track",
+    description: "前の曲に戻る",
+    userPhrases: ["前の曲", "前へ", "戻して", "previous track", "go back", "last song"],
+  },
+  {
+    id: "next",
+    command: "/spotify:next",
+    spotifyAction: "skip to next track",
+    description: "次の曲に進む",
+    userPhrases: ["次の曲", "次へ", "スキップ", "skip", "next track", "next song"],
+  },
+  {
+    id: "pause",
+    command: "/spotify:pause",
+    spotifyAction: "pause playback",
+    description: "再生を一時停止する（停止）",
+    userPhrases: ["止めて", "停止", "ストップ", "一時停止", "pause", "stop", "stop music"],
+  },
+  {
+    id: "play",
+    command: "/spotify:play",
+    spotifyAction: "resume playback",
+    description: "再生を再開する",
+    userPhrases: ["再生", "再開", "play", "resume", "continue", "再生して"],
+  },
+];
+
+
+export const DISCOVERY_COMMANDS = [
+  {
+    command: "/spotify:share",
+    description: "Now Playing を X に投稿（API 設定時）または共有画面を開く",
+    userPhrases: ["シェア", "Xに投稿", "post to X", "tweet", "share this song"],
+  },
+  {
+    command: "/spotify:play-uri",
+    description: "Spotify 曲 URL / URI を指定して再生",
+    userPhrases: ["この曲再生", "play this link", "play uri"],
+  },
+] as const;
+
+export function playbackCommandById(id: string): PlaybackCommandSpec | undefined {
+  const normalized = id.trim().toLowerCase();
+  return PLAYBACK_COMMANDS.find((entry) => entry.id === normalized);
+}
+
+export function formatPlaybackHelpMarkdown(): string {
+  const rows = PLAYBACK_COMMANDS.map((entry) => {
+    const phrases = entry.userPhrases.slice(0, 4).join(" · ");
+    return `| ${entry.command} | ${entry.description} | ${phrases} |`;
+  });
+
+  return [
+    "### Spotify playback controls",
+    "",
+    "ユーザーが曲操作や再生/停止を依頼したら、下表から意図に最も近い **Pi コマンド** を1つ選んで実行してください。",
+    "推測が曖昧なときは `/spotify:help` の一覧を参照するか、ユーザーに確認してください。",
+    "",
+    "| Command | Action | Example user phrases |",
+    "|---|---|---|",
+    ...rows,
+    "",
+    "Discovery / share:",
+    ...DISCOVERY_COMMANDS.map((entry) => `| ${entry.command} | ${entry.description} | ${entry.userPhrases.slice(0, 4).join(" · ")} |`),
+    "",
+    "Other useful commands:",
+    "- `/spotify:refresh` — Now Playing を即時更新",
+    "- `/spotify:status` — 認証状態（token 値は出さない）",
+    "",
+    "Note: playback control requires `user-modify-playback-state` scope. If controls fail after an upgrade, run `/spotify:login` again.",
+  ].join("\n");
+}
+
+export function formatPlaybackHelpText(): string {
+  return PLAYBACK_COMMANDS.map((entry) => {
+    const phrases = entry.userPhrases.join(", ");
+    return `${entry.command} — ${entry.description} (${phrases})`;
+  }).join("\n");
+}

package/lib/playback-snapshot.ts

@@ -0,0 +1,86 @@
+export interface PlaybackSnapshot {
+  track: string;
+  artist: string;
+  isPlaying: boolean;
+  progressMs?: number;
+  durationMs?: number;
+  trackId?: string;
+  spotifyUrl?: string;
+  artistIds?: string[];
+  fetchedAt: number;
+}
+
+interface SpotifyArtist {
+  id?: string;
+  name?: string;
+}
+
+interface SpotifyTrackItem {
+  id?: string;
+  name?: string;
+  duration_ms?: number;
+  external_urls?: { spotify?: string };
+  artists?: SpotifyArtist[];
+}
+
+export interface SpotifyCurrentlyPlayingRaw {
+  is_playing?: boolean;
+  progress_ms?: number;
+  item?: SpotifyTrackItem | null;
+}
+
+function artistNames(item: SpotifyTrackItem | null | undefined): string {
+  const artists = Array.isArray(item?.artists)
+    ? item!.artists!
+      .map((artist) => (typeof artist?.name === "string" ? artist.name.trim() : ""))
+      .filter(Boolean)
+    : [];
+  return artists.join(", ") || "Unknown artist";
+}
+
+function artistIds(item: SpotifyTrackItem | null | undefined): string[] {
+  if (!Array.isArray(item?.artists)) return [];
+  return item.artists
+    .map((artist) => (typeof artist?.id === "string" ? artist.id.trim() : ""))
+    .filter(Boolean);
+}
+
+export function toPlaybackSnapshot(
+  raw: SpotifyCurrentlyPlayingRaw | null | undefined,
+  fetchedAt = Date.now(),
+): PlaybackSnapshot | null {
+  if (!raw?.item) return null;
+
+  const track = typeof raw.item.name === "string" ? raw.item.name.trim() : "";
+  if (!track) return null;
+
+  const snapshot: PlaybackSnapshot = {
+    track,
+    artist: artistNames(raw.item),
+    isPlaying: Boolean(raw.is_playing),
+    fetchedAt,
+  };
+
+  if (typeof raw.progress_ms === "number" && Number.isFinite(raw.progress_ms)) {
+    snapshot.progressMs = raw.progress_ms;
+  }
+  if (typeof raw.item.duration_ms === "number" && Number.isFinite(raw.item.duration_ms)) {
+    snapshot.durationMs = raw.item.duration_ms;
+  }
+  if (typeof raw.item.id === "string" && raw.item.id.trim()) {
+    snapshot.trackId = raw.item.id.trim();
+  }
+  if (typeof raw.item.external_urls?.spotify === "string" && raw.item.external_urls.spotify.trim()) {
+    snapshot.spotifyUrl = raw.item.external_urls.spotify.trim();
+  } else if (snapshot.trackId) {
+    snapshot.spotifyUrl = `https://open.spotify.com/track/${snapshot.trackId}`;
+  }
+  const ids = artistIds(raw.item);
+  if (ids.length > 0) snapshot.artistIds = ids;
+
+  return snapshot;
+}
+
+export const __testing = {
+  toPlaybackSnapshot,
+};