@audiofool/moondog 0.1.0 → 0.2.0-beta.2

package/src/integrations/spotify/authentication.mjs

@@ -2,6 +2,7 @@ import { spawn } from "node:child_process";
 import {
   createHash,
   randomBytes,
+  randomUUID,
   timingSafeEqual,
 } from "node:crypto";
 import { createServer } from "node:http";
@@ -21,9 +22,12 @@ export const SPOTIFY_DEFAULT_SCOPES = Object.freeze([
   "user-modify-playback-state",
   "playlist-read-private",
   "playlist-modify-private",
+  "playlist-modify-public",
   "user-library-read",
   "user-library-modify",
   "user-read-recently-played",
+  "user-top-read",
+  "user-follow-read",
 ]);
 
 export class SpotifyAuthenticationError extends Error {
@@ -240,7 +244,12 @@ function validateStoredCredential(value) {
     value.refreshExpiresAt <= 0 ||
     value.tokenType !== "Bearer" ||
     typeof value.scope !== "string" ||
-    value.scope.length === 0
+    value.scope.length === 0 ||
+    (value.refreshAttempt !== undefined && (
+      !value.refreshAttempt ||
+      !/^[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/u.test(value.refreshAttempt.id) ||
+      !Number.isSafeInteger(value.refreshAttempt.startedAt) || value.refreshAttempt.startedAt <= 0
+    ))
   ) {
     throw safeError(
       "spotify_credential_invalid",
@@ -643,7 +652,11 @@ export function createSpotifyAuthentication({
   redirectUri = SPOTIFY_DEFAULT_REDIRECT_URI,
   scopes = SPOTIFY_DEFAULT_SCOPES,
   now = Date.now,
+  refreshTimeoutMs = 15_000,
 } = {}) {
+  if (!Number.isSafeInteger(refreshTimeoutMs) || refreshTimeoutMs < 1 || refreshTimeoutMs > 30_000) {
+    throw safeError("spotify_refresh_timeout_invalid", "Spotify refresh timeout must be between 1 and 30000 ms.");
+  }
   assertNonEmptyString(
     clientId,
     "spotify_client_id_invalid",
@@ -664,24 +677,37 @@ export function createSpotifyAuthentication({
   }
   const redirect = normalizeRedirectUri(redirectUri);
   const requestedScopes = normalizeScopes(scopes);
+  let generation = 0;
+  let refreshTask = null;
+  let mutationTail = Promise.resolve();
+  const mutateCredential = (operation) => {
+    const result = mutationTail.then(operation);
+    mutationTail = result.catch(() => {});
+    return result;
+  };
 
   const readCredential = async (options = {}) => {
+    assertNotAborted(options.signal);
     let value;
     try {
       value = await credentialStore.read(options);
     } catch {
+      assertNotAborted(options.signal);
       throw safeError(
         "spotify_credential_store_failed",
         "Spotify credential storage could not be read.",
       );
     }
+    assertNotAborted(options.signal);
     return value === undefined ? undefined : validateStoredCredential(value);
   };
 
   const writeCredential = async (credential, options = {}) => {
+    assertNotAborted(options.signal);
     try {
       await credentialStore.write(structuredClone(credential), options);
     } catch {
+      assertNotAborted(options.signal);
       throw safeError(
         "spotify_credential_store_failed",
         "Spotify credential storage could not be updated.",
@@ -689,9 +715,115 @@ export function createSpotifyAuthentication({
     }
   };
 
+  // The timer bounds lock acquisition and the token exchange. A token service
+  // may ignore abort: race only its response, never the locked transaction.
+  const waitForExchange = (promise, signal) => new Promise((resolve, reject) => {
+    const onAbort = () => reject(signal.reason ?? abortError());
+    signal.addEventListener("abort", onAbort, { once: true });
+    Promise.resolve(promise).then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+    if (signal.aborted) onAbort();
+  });
+  const credentialMatches = (a, b) => ["type", "accessToken", "refreshToken", "accessExpiresAt", "refreshExpiresAt", "tokenType", "scope"]
+    .every((key) => a?.[key] === b?.[key]);
+
+  const forceRefreshAccessToken = async ({ signal, rejectedAccessToken, proactive = false } = {}) => {
+    assertNotAborted(signal);
+    const credential = await readCredential({ signal });
+    if (!credential) throw safeError("spotify_auth_not_configured", "Spotify is not authenticated.");
+    const usable = (value) => value.accessExpiresAt > now() + ACCESS_TOKEN_REFRESH_WINDOW_MS;
+    if (!credential.refreshAttempt && usable(credential) &&
+        ((rejectedAccessToken && rejectedAccessToken !== credential.accessToken) || proactive)) {
+      return credential.accessToken;
+    }
+    if (typeof credentialStore.modify !== "function") {
+      throw safeError("spotify_refresh_coordination_unavailable", "Spotify refresh requires coordinated credential storage. Run /spotify login with the supported credential store.");
+    }
+    if (refreshTask && (refreshTask.controller.signal.aborted || refreshTask.generation !== generation)) refreshTask = null;
+    if (!refreshTask) {
+      const task = { controller: new AbortController(), waiters: 0, generation, started: false, credential, rejectedAccessToken };
+      const sharedSignal = task.controller.signal;
+      const timer = setTimeout(() => task.controller.abort(safeError(
+        "spotify_refresh_timeout", "Spotify refresh timed out. Run /spotify login if the refresh was interrupted.",
+      )), refreshTimeoutMs);
+      task.promise = mutateCredential(async () => {
+        try {
+          const stored = await credentialStore.modify(async (value, transaction) => {
+            assertNotAborted(sharedSignal);
+            if (!value) throw safeError("spotify_auth_not_configured", "Spotify is not authenticated.");
+            const current = validateStoredCredential(value);
+            // This check precedes *all* token reuse. A durable marker left
+            // after crash/timeout fences every process until explicit login.
+            if (current.refreshAttempt) {
+              throw safeError("spotify_refresh_uncertain", "A previous Spotify refresh was interrupted. Run /spotify login to authorize again; no refresh was retried.");
+            }
+            const mayReuse = rejectedAccessToken
+              ? current.accessToken !== rejectedAccessToken
+              : proactive || !credentialMatches(current, credential);
+            if (usable(current) && mayReuse) return undefined;
+            if (generation !== task.generation) throw safeError("spotify_auth_changed", "Spotify authentication changed during refresh.");
+            if (typeof transaction?.checkpoint !== "function") {
+              throw safeError("spotify_refresh_coordination_unavailable", "Spotify refresh requires durable coordinated credential storage.");
+            }
+            // Persist intent before dispatch. Do not abandon rotation merely
+            // because the last caller stops waiting: drain under the deadline.
+            task.started = true;
+            await transaction.checkpoint({ ...current, refreshAttempt: { id: randomUUID(), startedAt: now() } });
+            assertNotAborted(sharedSignal);
+            const refreshed = await waitForExchange(refreshSpotifyAccessToken({
+              clientId, refreshToken: current.refreshToken,
+              refreshExpiresAt: current.refreshExpiresAt, scopes: current.scope,
+              fetchImpl, signal: sharedSignal, now,
+            }), sharedSignal);
+            assertNotAborted(sharedSignal);
+            if (generation !== task.generation) throw safeError("spotify_auth_changed", "Spotify authentication changed during refresh.");
+            return refreshed;
+          }, { signal: sharedSignal });
+          return validateStoredCredential(stored).accessToken;
+        } catch (error) {
+          if (sharedSignal.aborted) throw sharedSignal.reason ?? abortError();
+          if (error instanceof SpotifyAuthenticationError) throw error;
+          throw safeError("spotify_credential_store_failed", "Spotify credential refresh could not be persisted. Run /spotify login if the refresh was interrupted.");
+        }
+      }).finally(() => { clearTimeout(timer); if (refreshTask === task) refreshTask = null; });
+      refreshTask = task;
+    }
+    const task = refreshTask;
+    task.waiters += 1;
+    return new Promise((resolve, reject) => {
+      let finished = false;
+      const finish = (error, value) => {
+        if (finished) return;
+        finished = true;
+        signal?.removeEventListener("abort", onAbort);
+        task.controller.signal.removeEventListener("abort", onSharedAbort);
+        task.waiters -= 1;
+        if (error) reject(error); else resolve(value);
+      };
+      const onAbort = () => {
+        finish(abortError());
+        if (task.waiters === 0 && !task.started) task.controller.abort(abortError());
+      };
+      const onSharedAbort = () => finish(task.controller.signal.reason ?? abortError());
+      signal?.addEventListener("abort", onAbort, { once: true });
+      task.controller.signal.addEventListener("abort", onSharedAbort, { once: true });
+      task.promise.then((value) => {
+        // A caller may have observed a newer token while this task waited for
+        // the lock. Do not satisfy its rejected-token refresh with that token.
+        if (!finished && value === rejectedAccessToken &&
+            task.credential.accessToken !== rejectedAccessToken && task.rejectedAccessToken !== rejectedAccessToken) {
+          finish(null, forceRefreshAccessToken({ signal, rejectedAccessToken, proactive }));
+        } else finish(null, value);
+      }, (error) => finish(error));
+      if (signal?.aborted) onAbort();
+      if (task.controller.signal.aborted) onSharedAbort();
+    });
+  };
+
   return {
     async login({ signal, onAuthorizationUrl } = {}) {
       assertNotAborted(signal);
+      const loginGeneration = ++generation;
+      refreshTask?.controller.abort();
       if (
         onAuthorizationUrl !== undefined &&
         typeof onAuthorizationUrl !== "function"
@@ -738,7 +870,12 @@ export function createSpotifyAuthentication({
           signal,
           now,
         });
-        await writeCredential(credential, { signal });
+        await mutateCredential(async () => {
+          if (generation !== loginGeneration) {
+            throw safeError("spotify_auth_changed", "Spotify authentication changed during login.");
+          }
+          await writeCredential(credential, { signal });
+        });
         return publicStatus(credential);
       } finally {
         await listener.close();
@@ -759,26 +896,23 @@ export function createSpotifyAuthentication({
           "Spotify is not authenticated.",
         );
       }
-      if (credential.accessExpiresAt > now() + ACCESS_TOKEN_REFRESH_WINDOW_MS) {
+      if (!credential.refreshAttempt && credential.accessExpiresAt > now() + ACCESS_TOKEN_REFRESH_WINDOW_MS) {
         return credential.accessToken;
       }
-      const refreshed = await refreshSpotifyAccessToken({
-        clientId,
-        refreshToken: credential.refreshToken,
-        refreshExpiresAt: credential.refreshExpiresAt,
-        scopes: credential.scope,
-        fetchImpl,
-        signal,
-        now,
-      });
-      await writeCredential(refreshed, { signal });
-      return refreshed.accessToken;
+      return forceRefreshAccessToken({ signal, proactive: true });
+    },
+
+    // A late 401 for an old token reuses the refresh that already replaced it.
+    async refreshAccessToken({ signal, rejectedAccessToken } = {}) {
+      return forceRefreshAccessToken({ signal, rejectedAccessToken });
     },
 
     async logout({ signal } = {}) {
       assertNotAborted(signal);
+      generation += 1;
+      refreshTask?.controller.abort();
       try {
-        await credentialStore.delete({ signal });
+        await mutateCredential(() => credentialStore.delete({ signal }));
       } catch {
         throw safeError(
           "spotify_credential_store_failed",

package/src/integrations/spotify/catalog-resolver.mjs

@@ -523,17 +523,18 @@ export function createSpotifyCatalogResolver({ client, cache = null, now = Date.
     throw new TypeError("The Spotify resolution cache interface is invalid.");
   }
 
-  async function searchAndMatch(track) {
+  async function searchAndMatch(track, { signal } = {}) {
     const queries = [
       fieldedSearchQuery(track),
       plainSearchQuery(track),
     ];
     let fallback = null;
     for (const query of queries) {
+      signal?.throwIfAborted();
       const result = await client.searchTracks({
         query,
         limit: SPOTIFY_CATALOG_RESOLVER_LIMITS.searchResultsMax,
-      });
+      }, { signal });
       const items = Array.isArray(result?.items) ? result.items : [];
       const match = bestCandidate(track, items);
       if (!match) continue;
@@ -554,7 +555,8 @@ export function createSpotifyCatalogResolver({ client, cache = null, now = Date.
   }
 
   return Object.freeze({
-    async resolve(tracks) {
+    async resolve(tracks, { signal } = {}) {
+      signal?.throwIfAborted();
       if (!Array.isArray(tracks) || tracks.length < 1) {
         fail("invalid_tracks", "At least one track is required for resolution.");
       }
@@ -626,7 +628,8 @@ export function createSpotifyCatalogResolver({ client, cache = null, now = Date.
           }
           let entry = cache ? await cache.get(cacheKey) : null;
           if (!entry) {
-            entry = await searchAndMatch(track);
+            entry = await searchAndMatch(track, { signal });
+            signal?.throwIfAborted();
             if (entry.status === "resolved" && cache) {
               await cache.put(cacheKey, entry, now());
             }
@@ -635,6 +638,7 @@ export function createSpotifyCatalogResolver({ client, cache = null, now = Date.
         }),
       );
 
+      signal?.throwIfAborted();
       const resolutions = prepared.map((track) => {
         const entry = entriesByKey.get(resolutionKey(track));
         return {

package/src/integrations/spotify/connection.mjs

@@ -79,7 +79,8 @@ export async function openSpotifyConnection({
   });
   const client = createSpotifyWebApiClient({
     fetchImpl,
-    tokenProvider: () => authentication.getAccessToken(),
+    tokenProvider: (options) => authentication.getAccessToken(options),
+    refreshAccessToken: (options) => authentication.refreshAccessToken(options),
   });
   const service = createSpotifyService({ client });
   const resolver = createSpotifyCatalogResolver({

package/src/integrations/spotify/credential-store.mjs

@@ -11,6 +11,10 @@ export function createSpotifyCredentialStore({
       return credentialStore.read(providerId, options);
     },
 
+    async modify(operation, options) {
+      return credentialStore.modify(providerId, operation, options);
+    },
+
     async write(credential, options) {
       return credentialStore.modify(
         providerId,

package/src/integrations/spotify/extended-streaming-history.mjs

@@ -31,8 +31,8 @@ export const SPOTIFY_EXTENDED_HISTORY_LIMITS = Object.freeze({
 });
 
 const execFileAsync = promisify(execFile);
-const audioMemberPattern =
-  /^Spotify Extended Streaming History\/Streaming_History_Audio_([0-9]{4})(?:_([0-9]+))?\.json$/u;
+const historyMemberPattern =
+  /^Spotify Extended Streaming History\/Streaming_History_(?:Audio|Video)_([0-9]{4})(?:_([0-9]+))?\.json$/u;
 const trackUriPattern = /^spotify:track:([A-Za-z0-9]{22})$/u;
 const sha256Pattern = /^[a-f0-9]{64}$/u;
 const unsafeTextPattern =
@@ -222,7 +222,7 @@ function normalizedMemberNames(memberNames) {
   const normalized = memberNames.map((value) => {
     if (
       typeof value !== "string" ||
-      !/^Streaming_History_Audio_[0-9]{4}(?:_[0-9]+)?\.json$/u.test(value)
+      !/^Streaming_History_(?:Audio|Video)_[0-9]{4}(?:_[0-9]+)?\.json$/u.test(value)
     ) {
       fail("Spotify Extended History member names are invalid.");
     }
@@ -418,12 +418,12 @@ async function unzip(args, maximumBytes) {
   }
 }
 
-function selectedAudioMembers(listing) {
+function selectedHistoryMembers(listing) {
   const selected = listing
     .split(/\r?\n/u)
     .filter(Boolean)
     .map((name) => {
-      const match = audioMemberPattern.exec(name);
+      const match = historyMemberPattern.exec(name);
       return match
         ? {
             name,
@@ -439,13 +439,13 @@ function selectedAudioMembers(listing) {
         : left.year - right.year,
     );
   if (selected.length < 1) {
-    fail("The ZIP does not contain Spotify Extended History audio files.");
+    fail("The ZIP does not contain Spotify Extended History audio/video files.");
   }
   if (selected.length > SPOTIFY_EXTENDED_HISTORY_LIMITS.maximumHistoryMembers) {
-    fail("The ZIP contains too many Spotify Extended History audio files.");
+    fail("The ZIP contains too many Spotify Extended History audio/video files.");
   }
   if (new Set(selected.map(({ name }) => name)).size !== selected.length) {
-    fail("The ZIP contains duplicate Spotify Extended History audio files.");
+    fail("The ZIP contains duplicate Spotify Extended History audio/video files.");
   }
   return selected;
 }
@@ -481,7 +481,7 @@ export async function readSpotifyExtendedStreamingHistoryArchive({
   }
 
   const listing = await unzip(["-Z1", resolvedPath], 1024 * 1024);
-  const members = selectedAudioMembers(listing);
+  const members = selectedHistoryMembers(listing);
   const records = [];
   let totalJsonBytes = 0;
   for (const member of members) {
@@ -500,12 +500,12 @@ export async function readSpotifyExtendedStreamingHistoryArchive({
       parsed = JSON.parse(jsonText.replace(/^\uFEFF/u, ""));
     } catch {
       fail(
-        `Spotify Extended History audio file for ${member.year} is invalid JSON.`,
+        `Spotify Extended History audio/video file for ${member.year} is invalid JSON.`,
       );
     }
     if (!Array.isArray(parsed)) {
       fail(
-        `Spotify Extended History audio file for ${member.year} is not an array.`,
+        `Spotify Extended History audio/video file for ${member.year} is not an array.`,
       );
     }
     records.push(...parsed);

package/src/integrations/spotify/history-archive.mjs

@@ -45,7 +45,7 @@ export async function readSpotifyHistoryArchive(options = {}) {
   const hasExtendedHistory = listing
     .split(/\r?\n/u)
     .some((name) =>
-      /^Spotify Extended Streaming History\/Streaming_History_Audio_[0-9]{4}(?:_[0-9]+)?\.json$/u.test(
+      /^Spotify Extended Streaming History\/Streaming_History_(?:Audio|Video)_[0-9]{4}(?:_[0-9]+)?\.json$/u.test(
         name,
       ),
     );

package/src/integrations/spotify/library-snapshot.mjs

@@ -0,0 +1,227 @@
+import { createHash } from "node:crypto";
+
+import { isUuid, uuidV5 } from "../../core/uuid-v5.mjs";
+import { spotifyEntityRefId, spotifyProfileEvidenceKey, spotifyResolvedTrackRef } from "./account-data-profile.mjs";
+
+export const SPOTIFY_LIBRARY_SOURCE = "spotify.web_api_library";
+export const SPOTIFY_LIBRARY_FORMAT = "spotify_web_api_library_v1";
+export const SPOTIFY_LIBRARY_SYSTEM = "spotify_web_api";
+// Read-only access for a library import; playback control is never requested.
+export const SPOTIFY_LIBRARY_SCOPES = Object.freeze([
+  "user-read-recently-played", "user-library-read", "user-follow-read", "user-top-read", "playlist-read-private",
+]);
+export const SPOTIFY_LIBRARY_LIMITS = Object.freeze({
+  savedTracks: 10_000, savedAlbums: 2_000, followedArtists: 2_000,
+  playlists: 200, itemsPerPlaylist: 2_000, playlistItems: 20_000, topItems: 50,
+});
+const TOP_PERIODS = Object.freeze({
+  short_term: "the last four weeks", medium_term: "the last six months", long_term: "about the last year",
+});
+const IMPORT_NAMESPACE = "77b3424f-3dd4-4fd9-ac70-42a6b9397dae";
+const EVIDENCE_NAMESPACE = "2efe152f-5455-4de6-b88f-09597719abb5";
+const BATCH_NAMESPACE = "d2b37594-838e-452b-8810-f6052f510e65";
+const MEMBERS = ["saved_tracks", "saved_albums", "followed_artists", "playlists", "top_items"];
+
+function idFromUri(uri, type) {
+  const match = typeof uri === "string" ? new RegExp(`^spotify:${type}:([A-Za-z0-9]{22})$`, "u").exec(uri) : null;
+  return match?.[1] ?? null;
+}
+
+function track(item, extra = {}) {
+  const id = item?.id ?? idFromUri(item?.uri, "track");
+  if (!id || !item.name || !Array.isArray(item.artists) || !item.artists.length) return null;
+  return { id, name: item.name, artists: item.artists, ...(item.album ? { album: item.album } : {}), ...extra };
+}
+
+async function pages(read, cap, onPage) {
+  const items = [];
+  let cursor = { offset: 0 };
+  for (;;) {
+    const page = await read(cursor);
+    for (const item of page.items ?? []) {
+      if (items.length >= cap) return { items, truncated: true };
+      items.push(item);
+    }
+    onPage?.(items.length);
+    if (!page.has_more) return { items, truncated: false };
+    if (page.next_after) { cursor = { after: page.next_after }; continue; }
+    // Playlist pages report their offset and size rather than a next offset.
+    const next = Number.isSafeInteger(page.next_offset) ? page.next_offset
+      : Number.isSafeInteger(page.offset) && Number.isSafeInteger(page.limit) ? page.offset + page.limit : null;
+    if (next === null || next <= (cursor.offset ?? -1)) return { items, truncated: true };
+    cursor = { offset: next };
+  }
+}
+
+const clip = value => Array.from(value).slice(0, 512).join("");
+
+/**
+ * Read the listener's Spotify library through the authorized client: saved
+ * tracks and albums, followed artists, their own playlists, and Spotify's top
+ * artists and tracks. Every read is bounded; a playlist that cannot be read is
+ * skipped and counted rather than failing the whole snapshot.
+ */
+export async function readSpotifyLibrarySnapshot(client, { signal, onProgress = () => {}, limits = SPOTIFY_LIBRARY_LIMITS } = {}) {
+  const progress = (stage, count) => { signal?.throwIfAborted(); onProgress({ stage, count }); };
+  const account = await client.getAccount({ signal });
+  const saved = await pages(({ offset }) => client.getSavedItems({ type: "tracks", limit: 50, offset }, { signal }),
+    limits.savedTracks, count => progress("saved_tracks", count));
+  const albums = await pages(({ offset }) => client.getSavedItems({ type: "albums", limit: 50, offset }, { signal }),
+    limits.savedAlbums, count => progress("saved_albums", count));
+  const artists = await pages(({ after }) => client.getFollowedArtists({ limit: 50, ...(after ? { after } : {}) }, { signal }),
+    limits.followedArtists, count => progress("followed_artists", count));
+  const listed = await pages(({ offset }) => client.getCurrentUserPlaylists({ limit: 50, offset }, { signal }),
+    limits.playlists, count => progress("playlists", count));
+  const playlists = [];
+  let playlistItems = 0;
+  let skippedPlaylists = 0;
+  let truncatedPlaylistItems = false;
+  // Followed playlists are someone else's curation; only the listener's own count.
+  for (const playlist of listed.items.filter(item => account.account_id && item.owner_id === account.account_id)) {
+    if (playlistItems >= limits.playlistItems) { truncatedPlaylistItems = true; break; }
+    try {
+      const read = await pages(({ offset }) => client.getPlaylistItems({ playlistId: playlist.id, limit: 50, offset }, { signal }),
+        Math.min(limits.itemsPerPlaylist, limits.playlistItems - playlistItems));
+      truncatedPlaylistItems ||= read.truncated;
+      const tracks = read.items.flatMap((entry, index) => {
+        if (entry.is_local || entry.item?.type !== "track") return [];
+        const value = track(entry.item, { position: index + 1, ...(entry.added_at ? { added_at: entry.added_at } : {}) });
+        return value ? [value] : [];
+      });
+      playlistItems += read.items.length;
+      playlists.push({ id: playlist.id, name: playlist.name, tracks });
+      progress("playlist_items", playlistItems);
+    } catch (error) {
+      if (error?.name === "AbortError" || signal?.aborted) throw error;
+      skippedPlaylists++;
+    }
+  }
+  const top = { artists: {}, tracks: {} };
+  for (const type of ["artists", "tracks"]) {
+    for (const timeRange of Object.keys(TOP_PERIODS)) {
+      const result = await client.getTopItems({ type, timeRange, limit: limits.topItems }, { signal });
+      top[type][timeRange] = (result.items ?? []).flatMap((item, index) => {
+        const rank = item.affinity_rank ?? index + 1;
+        if (type === "tracks") {
+          const value = track(item, { rank });
+          return value ? [value] : [];
+        }
+        return item.name ? [{ name: item.name, rank, ...(idFromUri(item.uri, "artist") ? { id: idFromUri(item.uri, "artist") } : {}) }] : [];
+      });
+      progress("top_items", Object.values(top).reduce((sum, ranges) => sum + Object.values(ranges).flat().length, 0));
+    }
+  }
+  return {
+    saved_tracks: saved.items.flatMap(item => track(item, item.added_at ? { added_at: item.added_at } : {}) ?? []),
+    saved_albums: albums.items.flatMap(item => {
+      const id = idFromUri(item.uri, "album");
+      return id && item.name ? [{ id, name: item.name, artists: item.artists ?? [], ...(item.added_at ? { added_at: item.added_at } : {}) }] : [];
+    }),
+    followed_artists: artists.items.flatMap(item => {
+      const id = idFromUri(item.uri, "artist");
+      return id && item.name ? [{ id, name: item.name }] : [];
+    }),
+    playlists,
+    top_artists: top.artists,
+    top_tracks: top.tracks,
+    truncated: { saved_tracks: saved.truncated, saved_albums: albums.truncated, followed_artists: artists.truncated,
+      playlists: listed.truncated, playlist_items: truncatedPlaylistItems },
+    skipped_playlists: skippedPlaylists,
+  };
+}
+
+function digestOf(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export function projectSpotifyLibrarySnapshot({ subjectId, snapshot, capturedAt = new Date().toISOString() } = {}) {
+  if (!isUuid(subjectId)) throw new TypeError("A trusted subject ID is required.");
+  subjectId = subjectId.toLowerCase();
+  capturedAt = new Date(capturedAt).toISOString();
+  // An identical library is the same import, so a repeated sync changes nothing.
+  const content = JSON.stringify({ format: SPOTIFY_LIBRARY_FORMAT, ...snapshot });
+  const digest = digestOf(content);
+  const size = Buffer.byteLength(content);
+  const profileImportId = uuidV5(`${subjectId}\0${digest}\0${SPOTIFY_LIBRARY_FORMAT}`, IMPORT_NAMESPACE);
+  const tracks = new Map();
+  const evidence = [];
+  const notAfterCapture = value => (value && value <= capturedAt ? value : capturedAt);
+  const addTrack = item => {
+    const artist = clip(item.artists.join(", "));
+    const ref = spotifyResolvedTrackRef({ id: item.id, title: item.name, artist, album: item.album, observedAt: capturedAt });
+    if (!tracks.has(ref.track_ref_id)) tracks.set(ref.track_ref_id, ref);
+    return { entity_type: "track", entity_ref_id: ref.track_ref_id, track_ref_id: ref.track_ref_id, track_ref_revision: 1,
+      label: item.name, artist_credit: artist, ...(item.album ? { release: item.album } : {}) };
+  };
+  const add = ({ kind, logicalKey, strength, entity, member, observedAt = capturedAt, attributes = {} }) => {
+    const evidenceKey = spotifyProfileEvidenceKey(subjectId, kind, logicalKey);
+    evidence.push({
+      schema_version: 1, profile_evidence_id: uuidV5(`${digest}\0${evidenceKey}`, EVIDENCE_NAMESPACE),
+      evidence_key: evidenceKey, subject_id: subjectId, evidence_kind: kind, direction: "supports",
+      strength_class: strength, entity, observed_at: notAfterCapture(observedAt), attributes,
+      provenance: { source_kind: "import", source_system: SPOTIFY_LIBRARY_SYSTEM, source_member: member,
+        captured_at: capturedAt, profile_import_id: profileImportId },
+    });
+  };
+  for (const [index, item] of snapshot.saved_tracks.entries()) {
+    add({ kind: "library_track_saved", logicalKey: `saved-track\0${item.id}`, strength: "explicit", entity: addTrack(item),
+      member: "saved_tracks", observedAt: item.added_at, attributes: { source_position: index + 1 } });
+  }
+  for (const [index, item] of snapshot.saved_albums.entries()) {
+    add({ kind: "library_album_saved", logicalKey: `saved-album\0${item.id}`, strength: "explicit", member: "saved_albums",
+      entity: { entity_type: "album", entity_ref_id: spotifyEntityRefId("album", item.id), label: item.name,
+        ...(item.artists.length ? { artist_credit: clip(item.artists.join(", ")) } : {}) },
+      observedAt: item.added_at, attributes: { source_position: index + 1 } });
+  }
+  for (const [index, item] of snapshot.followed_artists.entries()) {
+    add({ kind: "library_artist_followed", logicalKey: `followed-artist\0${item.id}`, strength: "explicit", member: "followed_artists",
+      entity: { entity_type: "artist", entity_ref_id: spotifyEntityRefId("artist", item.id), label: item.name },
+      attributes: { source_position: index + 1 } });
+  }
+  for (const playlist of snapshot.playlists) {
+    const playlistRef = spotifyEntityRefId("playlist", playlist.id);
+    for (const item of playlist.tracks) {
+      add({ kind: "playlist_track_added", logicalKey: `playlist-track\0${playlistRef}\0${item.id}\0${item.position}`,
+        strength: "curated", entity: addTrack(item), member: "playlists", observedAt: item.added_at,
+        attributes: { playlist_ref_id: playlistRef, playlist_name: playlist.name, playlist_position: item.position } });
+    }
+  }
+  for (const [timeRange, period] of Object.entries(TOP_PERIODS)) {
+    for (const item of snapshot.top_artists[timeRange] ?? []) {
+      add({ kind: "top_artist_ranked", logicalKey: `top-artist\0${timeRange}\0${item.id ?? item.name}`, strength: "provider_derived",
+        member: "top_items", entity: { entity_type: "artist",
+          entity_ref_id: item.id ? spotifyEntityRefId("artist", item.id) : uuidV5(`artist\0${item.name}`, EVIDENCE_NAMESPACE), label: item.name },
+        attributes: { rank: item.rank, period, time_range: timeRange } });
+    }
+    for (const item of snapshot.top_tracks[timeRange] ?? []) {
+      add({ kind: "top_track_ranked", logicalKey: `top-track\0${timeRange}\0${item.id}`, strength: "provider_derived",
+        member: "top_items", entity: addTrack(item), attributes: { rank: item.rank, period, time_range: timeRange } });
+    }
+  }
+  if (!evidence.length) throw new Error("Your Spotify library looks empty, so there is nothing to import yet.");
+  const manifest = { subject_id: subjectId, source_format: SPOTIFY_LIBRARY_FORMAT, archive_sha256: digest,
+    archive_size_bytes: size, member_names: MEMBERS, imported_at: capturedAt };
+  const unique = values => new Set(values).size;
+  return {
+    bundle: {
+      source_key: SPOTIFY_LIBRARY_SOURCE, captured_at: capturedAt, cursor_after_ms: null,
+      track_refs: [...tracks.values()], listening_events: [],
+      import_batch: { ...manifest, import_batch_id: uuidV5(`${subjectId}\0${digest}`, BATCH_NAMESPACE),
+        data_scope: "account_library_snapshot", input_records: 0, earliest_occurred_at: null, latest_occurred_at: null },
+      profile_import: { ...manifest, profile_import_id: profileImportId, source_key: SPOTIFY_LIBRARY_SOURCE, input_records: evidence.length },
+      profile_evidence: evidence,
+    },
+    preview: {
+      kind: "spotify-library", sourceLabel: "Your Spotify library", capturedAt,
+      savedTracks: snapshot.saved_tracks.length, savedAlbums: snapshot.saved_albums.length,
+      followedArtists: snapshot.followed_artists.length, playlists: snapshot.playlists.length,
+      playlistTracks: snapshot.playlists.reduce((sum, playlist) => sum + playlist.tracks.length, 0),
+      topArtists: unique(Object.values(snapshot.top_artists).flat().map(item => item.id ?? item.name)),
+      topTracks: unique(Object.values(snapshot.top_tracks).flat().map(item => item.id)),
+      tracks: tracks.size, profileEvidence: evidence.length,
+      truncated: Object.entries(snapshot.truncated ?? {}).filter(([, value]) => value).map(([key]) => key),
+      skippedPlaylists: snapshot.skipped_playlists ?? 0,
+      scopeNote: "What you keep and follow, your own playlists, and the artists and tracks Spotify ranks highest for you. It shows what you keep, not every play.",
+    },
+  };
+}

package/src/integrations/spotify/recent-activity.mjs

@@ -192,6 +192,8 @@ export function projectSpotifyRecentActivity({
     source_key: SPOTIFY_RECENT_ACTIVITY_SOURCE,
     captured_at: normalizedCapturedAt,
     cursor_after_ms: cursorAfterMs > 0 ? cursorAfterMs : null,
+    // Spotify keeps only the last 50 plays: a full read may have lost older ones.
+    window_full: page.items.length >= 50 || page.has_more === true,
     track_refs: [...trackRefs.values()],
     listening_events: [...listeningEvents.values()],
   };