@audiofool/moondog 0.1.0

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

@@ -0,0 +1,59 @@
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { readSpotifyAccountDataHistoryArchive } from "./account-data-history.mjs";
+import { readSpotifyExtendedStreamingHistoryArchive } from "./extended-streaming-history.mjs";
+
+const execFileAsync = promisify(execFile);
+
+function fail(message, code = "spotify_history_archive_invalid") {
+  const error = new Error(message);
+  error.code = code;
+  throw error;
+}
+
+export async function readSpotifyHistoryArchive(options = {}) {
+  if (typeof options.archivePath !== "string" || !options.archivePath.trim()) {
+    fail("A Spotify history ZIP path is required.");
+  }
+  const archivePath = path.resolve(options.archivePath);
+  let listing;
+  try {
+    ({ stdout: listing } = await execFileAsync(
+      "/usr/bin/unzip",
+      ["-Z1", archivePath],
+      {
+        encoding: "utf8",
+        maxBuffer: 1024 * 1024,
+        windowsHide: true,
+      },
+    ));
+  } catch {
+    fail(
+      "The Spotify history ZIP could not be read safely.",
+      "spotify_history_archive_unreadable",
+    );
+  }
+  const hasAccountData = listing
+    .split(/\r?\n/u)
+    .some((name) =>
+      /^Spotify Account Data\/StreamingHistory_music_[0-9]+\.json$/u.test(
+        name,
+      ),
+    );
+  const hasExtendedHistory = listing
+    .split(/\r?\n/u)
+    .some((name) =>
+      /^Spotify Extended Streaming History\/Streaming_History_Audio_[0-9]{4}(?:_[0-9]+)?\.json$/u.test(
+        name,
+      ),
+    );
+  if (hasAccountData === hasExtendedHistory) {
+    fail("The ZIP does not contain one unambiguous Spotify history format.");
+  }
+  const reader = hasExtendedHistory
+    ? readSpotifyExtendedStreamingHistoryArchive
+    : readSpotifyAccountDataHistoryArchive;
+  return reader({ ...options, archivePath });
+}

package/src/integrations/spotify/index.mjs

@@ -0,0 +1,80 @@
+export {
+  SPOTIFY_WEB_API_BASE_URL,
+  SPOTIFY_WEB_API_LIMITS,
+  SpotifyWebApiError,
+  createSpotifyWebApiClient,
+} from "./web-api-client.mjs";
+
+export {
+  SPOTIFY_SERVICE_LIMITS,
+  SpotifyServiceError,
+  createSpotifyService,
+} from "./service.mjs";
+
+export {
+  SPOTIFY_DEFAULT_REDIRECT_URI,
+  SPOTIFY_DEFAULT_SCOPES,
+  SpotifyAuthenticationError,
+  createSpotifyAuthentication,
+} from "./authentication.mjs";
+
+export { createSpotifyCredentialStore } from "./credential-store.mjs";
+export { openSpotifyConnection } from "./connection.mjs";
+
+export {
+  SPOTIFY_CATALOG_RESOLVER_LIMITS,
+  SpotifyCatalogResolverError,
+  createSpotifyCatalogResolver,
+} from "./catalog-resolver.mjs";
+
+export {
+  SPOTIFY_RESOLUTION_CACHE_KEY_VERSION,
+  SPOTIFY_RESOLUTION_CACHE_SCHEMA_VERSION,
+  createInMemorySpotifyResolutionCache,
+  defaultSpotifyResolutionCachePath,
+  openSpotifyResolutionCache,
+  resolveSpotifyResolutionCachePath,
+  spotifyResolutionCacheKey,
+} from "./resolution-cache.mjs";
+
+export {
+  SPOTIFY_LISTENING_EVENT_NAMESPACE,
+  SPOTIFY_RECENT_ACTIVITY_SOURCE,
+  SPOTIFY_TRACK_NAMESPACE,
+  projectSpotifyRecentActivity,
+} from "./recent-activity.mjs";
+
+export {
+  SPOTIFY_ACCOUNT_DATA_BATCH_NAMESPACE,
+  SPOTIFY_ACCOUNT_DATA_EVENT_NAMESPACE,
+  SPOTIFY_ACCOUNT_DATA_HISTORY_FORMAT,
+  SPOTIFY_ACCOUNT_DATA_HISTORY_LIMITS,
+  SPOTIFY_ACCOUNT_DATA_HISTORY_SCOPE,
+  SPOTIFY_ACCOUNT_DATA_HISTORY_SOURCE,
+  SPOTIFY_ACCOUNT_DATA_TRACK_NAMESPACE,
+  SpotifyAccountDataHistoryError,
+  projectSpotifyAccountDataHistory,
+  readSpotifyAccountDataHistoryArchive,
+  spotifyAccountDataEventIdentity,
+  spotifyAccountDataTrackIdentity,
+} from "./account-data-history.mjs";
+
+export {
+  SPOTIFY_EXTENDED_HISTORY_BATCH_NAMESPACE,
+  SPOTIFY_EXTENDED_HISTORY_EVENT_NAMESPACE,
+  SPOTIFY_EXTENDED_HISTORY_FORMAT,
+  SPOTIFY_EXTENDED_HISTORY_LIMITS,
+  SPOTIFY_EXTENDED_HISTORY_SCOPE,
+  SPOTIFY_EXTENDED_HISTORY_SOURCE,
+  SpotifyExtendedHistoryError,
+  projectSpotifyExtendedStreamingHistory,
+  readSpotifyExtendedStreamingHistoryArchive,
+} from "./extended-streaming-history.mjs";
+
+export { readSpotifyHistoryArchive } from "./history-archive.mjs";
+
+export {
+  readSpotifyConfiguration,
+  resolveSpotifySettingsFile,
+  writeSpotifyConfiguration,
+} from "./settings.mjs";

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

@@ -0,0 +1,198 @@
+import { createHash } from "node:crypto";
+
+import { isUuid, uuidV5 } from "../../core/uuid-v5.mjs";
+
+export const SPOTIFY_RECENT_ACTIVITY_SOURCE = "spotify.recently_played";
+export const SPOTIFY_TRACK_NAMESPACE =
+  "e76578a4-0c61-50e2-91f9-b312ea986a92";
+export const SPOTIFY_LISTENING_EVENT_NAMESPACE =
+  "b8c8dbbf-2e67-51ae-99e5-744daf9f8c10";
+
+const isrcPattern = /^[A-Z]{2}[A-Z0-9]{3}[0-9]{7}$/u;
+const releaseDatePattern = /^(?:[0-9]{4}|[0-9]{4}-(?:0[1-9]|1[0-2])|[0-9]{4}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01]))$/u;
+const contextTypes = new Set(["album", "playlist", "artist"]);
+
+function fail(message) {
+  throw new TypeError(message);
+}
+
+function timestamp(value, label) {
+  if (typeof value !== "string") fail(`${label} is invalid`);
+  const milliseconds = Date.parse(value);
+  if (!Number.isFinite(milliseconds)) fail(`${label} is invalid`);
+  const normalized = new Date(milliseconds).toISOString();
+  if (normalized !== value) fail(`${label} must be a normalized UTC timestamp`);
+  return normalized;
+}
+
+function cleanText(value, maximum, label) {
+  if (typeof value !== "string") fail(`${label} is invalid`);
+  const cleaned = value.replace(/\s+/gu, " ").trim();
+  if (!cleaned || Array.from(cleaned).length > maximum) {
+    fail(`${label} is invalid`);
+  }
+  return cleaned;
+}
+
+function clippedText(value, maximum) {
+  return Array.from(value).slice(0, maximum).join("");
+}
+
+function validReleaseDate(value) {
+  if (typeof value !== "string" || !releaseDatePattern.test(value)) {
+    return false;
+  }
+  if (value.length < 10) return true;
+  const milliseconds = Date.parse(`${value}T00:00:00.000Z`);
+  return (
+    Number.isFinite(milliseconds) &&
+    new Date(milliseconds).toISOString().slice(0, 10) === value
+  );
+}
+
+function safeExternalUrl(value) {
+  if (typeof value !== "string") return undefined;
+  try {
+    const url = new URL(value);
+    if (
+      url.protocol !== "https:" ||
+      url.search.length > 0 ||
+      url.hash.length > 0 ||
+      url.username.length > 0 ||
+      url.password.length > 0
+    ) {
+      return undefined;
+    }
+    return url.toString();
+  } catch {
+    return undefined;
+  }
+}
+
+function trackRecord(item) {
+  const track = item.track;
+  const playedAt = timestamp(item.played_at, "Spotify played_at");
+  const externalId = cleanText(track.id, 128, "Spotify track ID");
+  const title = cleanText(track.name, 512, "Spotify track title");
+  const artists = Array.isArray(track.artists)
+    ? track.artists
+        .map((artist) => cleanText(artist, 512, "Spotify artist name"))
+        .slice(0, 5)
+    : [];
+  if (artists.length === 0) fail("Spotify track artists are invalid");
+  const release = cleanText(track.album, 512, "Spotify release title");
+  const externalRef = {
+    system: "spotify",
+    entity_type: "spotify.track",
+    external_id: externalId,
+  };
+  const url = safeExternalUrl(track.external_url);
+  if (url) externalRef.url = url;
+  const record = {
+    schema_version: 1,
+    track_ref_id: uuidV5(externalId, SPOTIFY_TRACK_NAMESPACE),
+    revision: 1,
+    identity_status: "resolved",
+    display_label: clippedText(`${title} - ${artists.join(", ")}`, 512),
+    title,
+    artist_credits: artists.map((name) => ({ name, role: "unknown" })),
+    release: { title: release },
+    external_refs: [externalRef],
+    created_at: playedAt,
+    resolved_at: playedAt,
+  };
+  if (Number.isInteger(track.duration_ms) && track.duration_ms >= 0) {
+    record.duration_ms = track.duration_ms;
+  }
+  if (typeof track.isrc === "string" && isrcPattern.test(track.isrc)) {
+    record.isrc = track.isrc;
+  }
+  if (
+    validReleaseDate(track.release_date)
+  ) {
+    record.release.release_date = track.release_date;
+  }
+  return record;
+}
+
+function eventRecord(item, trackRef, subjectId, capturedAt) {
+  const occurredAt = timestamp(item.played_at, "Spotify played_at");
+  if (Date.parse(capturedAt) < Date.parse(occurredAt)) {
+    fail("Spotify play time is later than its capture time");
+  }
+  const fingerprint = createHash("sha256")
+    .update("spotify\0")
+    .update(subjectId)
+    .update("\0")
+    .update(item.track.id)
+    .update("\0")
+    .update(occurredAt)
+    .digest("hex");
+  const contextType = contextTypes.has(item.context_type)
+    ? item.context_type
+    : "unknown";
+  return {
+    schema_version: 1,
+    listening_event_id: uuidV5(
+      fingerprint,
+      SPOTIFY_LISTENING_EVENT_NAMESPACE,
+    ),
+    subject_id: subjectId,
+    track_ref_id: trackRef.track_ref_id,
+    track_ref_revision: trackRef.revision,
+    event_type: "play_observed",
+    occurred_at: occurredAt,
+    ingested_at: capturedAt,
+    interaction_mode: "unknown",
+    context: { context_type: contextType },
+    provenance: {
+      source_kind: "tool",
+      captured_at: capturedAt,
+      external_ref: {
+        system: "spotify",
+        entity_type: "spotify.play_history",
+        external_id: fingerprint,
+      },
+    },
+    deduplication_key: fingerprint,
+  };
+}
+
+export function projectSpotifyRecentActivity({
+  subjectId,
+  page,
+  capturedAt = new Date().toISOString(),
+} = {}) {
+  if (!isUuid(subjectId)) fail("A trusted subject ID is required");
+  const normalizedCapturedAt = timestamp(capturedAt, "Capture timestamp");
+  if (!page || page.provider !== "spotify" || !Array.isArray(page.items)) {
+    fail("A normalized Spotify recent activity page is required");
+  }
+  if (page.items.length > 50) fail("Spotify recent activity is not bounded");
+
+  const trackRefs = new Map();
+  const listeningEvents = new Map();
+  let cursorAfterMs = Number.isSafeInteger(page.cursor_after_ms)
+    ? page.cursor_after_ms
+    : 0;
+  for (const item of page.items) {
+    const trackRef = trackRecord(item);
+    trackRefs.set(trackRef.track_ref_id, trackRef);
+    const event = eventRecord(
+      item,
+      trackRef,
+      subjectId.toLowerCase(),
+      normalizedCapturedAt,
+    );
+    listeningEvents.set(event.listening_event_id, event);
+    cursorAfterMs = Math.max(cursorAfterMs, Date.parse(event.occurred_at));
+  }
+
+  return {
+    source_key: SPOTIFY_RECENT_ACTIVITY_SOURCE,
+    captured_at: normalizedCapturedAt,
+    cursor_after_ms: cursorAfterMs > 0 ? cursorAfterMs : null,
+    track_refs: [...trackRefs.values()],
+    listening_events: [...listeningEvents.values()],
+  };
+}

package/src/integrations/spotify/resolution-cache.mjs

@@ -0,0 +1,260 @@
+import { createHash } from "node:crypto";
+import { chmod, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+export const SPOTIFY_RESOLUTION_CACHE_SCHEMA_VERSION = 1;
+export const SPOTIFY_RESOLUTION_CACHE_KEY_VERSION = 2;
+
+export function resolveSpotifyResolutionCachePath(environment = process.env) {
+  const configuredState = environment.MOONDOG_STATE_HOME?.trim();
+  if (configuredState) {
+    if (!path.isAbsolute(configuredState)) {
+      throw new TypeError("MOONDOG_STATE_HOME must be an absolute path");
+    }
+    return path.join(path.resolve(configuredState), "spotify-resolution-cache.sqlite");
+  }
+
+  const configuredConfig = environment.MOONDOG_CONFIG_HOME?.trim();
+  if (configuredConfig) {
+    if (!path.isAbsolute(configuredConfig)) {
+      throw new TypeError("MOONDOG_CONFIG_HOME must be an absolute path");
+    }
+    return path.join(
+      path.resolve(configuredConfig),
+      "spotify-resolution-cache.sqlite",
+    );
+  }
+
+  const xdgState = environment.XDG_STATE_HOME?.trim();
+  if (xdgState && path.isAbsolute(xdgState)) {
+    return path.join(
+      path.resolve(xdgState),
+      "moondog",
+      "spotify-resolution-cache.sqlite",
+    );
+  }
+
+  return path.join(
+    homedir(),
+    ".local",
+    "state",
+    "moondog",
+    "spotify-resolution-cache.sqlite",
+  );
+}
+
+export const defaultSpotifyResolutionCachePath =
+  resolveSpotifyResolutionCachePath();
+
+const schema = `
+CREATE TABLE IF NOT EXISTS track_resolutions (
+  cache_key TEXT PRIMARY KEY,
+  status TEXT NOT NULL,
+  match_quality TEXT,
+  matched_title TEXT,
+  matched_artists TEXT,
+  matched_album TEXT,
+  matched_duration_ms INTEGER,
+  spotify_track_id TEXT,
+  spotify_uri TEXT,
+  resolved_at_ms INTEGER NOT NULL
+);
+`;
+
+const matchQualityValues = new Set(["alternate_master", "exact", "standard"]);
+
+function isPlainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function cleanStoredText(value, maximum) {
+  if (typeof value !== "string") return null;
+  const cleaned = value.replace(/\s+/gu, " ").trim();
+  if (!cleaned) return null;
+  return Array.from(cleaned).slice(0, maximum).join("");
+}
+
+export function spotifyResolutionCacheKey(track) {
+  if (
+    !isPlainObject(track) ||
+    typeof track.title !== "string" ||
+    typeof track.artist_credit !== "string" ||
+    typeof track.release !== "string"
+  ) {
+    throw new TypeError("A track title, artist credit, and release are required.");
+  }
+  const normalized = [
+    `spotify-resolution/${SPOTIFY_RESOLUTION_CACHE_KEY_VERSION}`,
+    track.title,
+    track.artist_credit,
+    track.release,
+  ]
+    .map((value) => value.normalize("NFKC").toLocaleLowerCase("und").replace(/\s+/gu, " ").trim())
+    .join("|");
+  return createHash("sha256").update(normalized).digest("hex");
+}
+
+function serializeArtists(value) {
+  if (!Array.isArray(value)) return null;
+  const artists = value
+    .filter((artist) => typeof artist === "string" && artist.trim())
+    .map((artist) => cleanStoredText(artist, 256))
+    .filter(Boolean)
+    .slice(0, 5);
+  return artists.length > 0 ? JSON.stringify(artists) : null;
+}
+
+function parseArtists(value) {
+  if (typeof value !== "string" || !value.trim()) return undefined;
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed.slice(0, 5) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function rowToEntry(row) {
+  if (!row || row.status !== "resolved") return null;
+  const entry = {
+    status: "resolved",
+    match_quality: matchQualityValues.has(row.match_quality)
+      ? row.match_quality
+      : "standard",
+  };
+  if (row.matched_title) entry.matched = { title: row.matched_title };
+  const artists = parseArtists(row.matched_artists);
+  if (artists) entry.matched.artists = artists;
+  if (row.matched_album) entry.matched.album = row.matched_album;
+  if (Number.isInteger(row.matched_duration_ms)) {
+    entry.matched.duration_ms = row.matched_duration_ms;
+  }
+  if (row.spotify_track_id && row.spotify_uri) {
+    entry.spotify = {
+      track_id: row.spotify_track_id,
+      uri: row.spotify_uri,
+    };
+  }
+  if (!entry.spotify) return null;
+  return entry;
+}
+
+export class SpotifyResolutionCache {
+  #database;
+  #closed = false;
+
+  constructor(database) {
+    this.#database = database;
+  }
+
+  async get(cacheKey) {
+    if (this.#closed) return null;
+    const row = this.#database
+      .prepare("SELECT * FROM track_resolutions WHERE cache_key = ?")
+      .get(cacheKey);
+    return rowToEntry(row);
+  }
+
+  async put(cacheKey, entry, resolvedAtMs = Date.now()) {
+    if (this.#closed) return;
+    if (!isPlainObject(entry) || entry.status !== "resolved") return;
+    const matched = isPlainObject(entry.matched) ? entry.matched : {};
+    const spotify = isPlainObject(entry.spotify) ? entry.spotify : {};
+    this.#database
+      .prepare(
+        `INSERT OR REPLACE INTO track_resolutions (
+          cache_key, status, match_quality, matched_title, matched_artists,
+          matched_album, matched_duration_ms, spotify_track_id, spotify_uri,
+          resolved_at_ms
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      )
+      .run(
+        cacheKey,
+        "resolved",
+        matchQualityValues.has(entry.match_quality)
+          ? entry.match_quality
+          : "standard",
+        cleanStoredText(matched.title, 512),
+        serializeArtists(matched.artists),
+        cleanStoredText(matched.album, 512),
+        Number.isInteger(matched.duration_ms) ? matched.duration_ms : null,
+        cleanStoredText(spotify.track_id, 128),
+        cleanStoredText(spotify.uri, 256),
+        Number.isInteger(resolvedAtMs) ? resolvedAtMs : Date.now(),
+      );
+  }
+
+  close() {
+    if (this.#closed) return;
+    this.#closed = true;
+    this.#database.close();
+  }
+}
+
+let databaseConstructorPromise;
+
+function databaseConstructor() {
+  databaseConstructorPromise ??= import("node:sqlite").then(
+    ({ DatabaseSync }) => DatabaseSync,
+  );
+  return databaseConstructorPromise;
+}
+
+export async function openSpotifyResolutionCache({
+  databasePath = defaultSpotifyResolutionCachePath,
+  environment = process.env,
+} = {}) {
+  const resolvedPath =
+    databasePath === defaultSpotifyResolutionCachePath
+      ? resolveSpotifyResolutionCachePath(environment)
+      : databasePath;
+  const parent = path.dirname(path.resolve(resolvedPath));
+  await mkdir(parent, { recursive: true, mode: 0o700 });
+  if (process.platform !== "win32") await chmod(parent, 0o700);
+
+  const DatabaseSync = await databaseConstructor();
+  const database = new DatabaseSync(path.resolve(resolvedPath));
+  try {
+    database.exec("PRAGMA busy_timeout = 5000");
+    database.exec("PRAGMA journal_mode = WAL");
+    database.exec("PRAGMA trusted_schema = OFF");
+    const currentVersion = database.prepare("PRAGMA user_version").get()
+      .user_version;
+    if (
+      !Number.isInteger(currentVersion) ||
+      currentVersion < 0 ||
+      currentVersion > SPOTIFY_RESOLUTION_CACHE_SCHEMA_VERSION
+    ) {
+      throw new Error("Spotify resolution cache schema is incompatible");
+    }
+    database.exec(schema);
+    if (currentVersion < SPOTIFY_RESOLUTION_CACHE_SCHEMA_VERSION) {
+      database.exec(
+        `PRAGMA user_version = ${SPOTIFY_RESOLUTION_CACHE_SCHEMA_VERSION}`,
+      );
+    }
+    if (process.platform !== "win32") {
+      await chmod(path.resolve(resolvedPath), 0o600);
+    }
+    return new SpotifyResolutionCache(database);
+  } catch (error) {
+    database.close();
+    throw error;
+  }
+}
+
+export function createInMemorySpotifyResolutionCache() {
+  const entries = new Map();
+  return {
+    async get(cacheKey) {
+      return entries.get(cacheKey) ?? null;
+    },
+    async put(cacheKey, entry) {
+      entries.set(cacheKey, structuredClone(entry));
+    },
+    async close() {},
+  };
+}