@audiofool/moondog 0.1.0

package/src/profile/music-import-bundle.mjs

@@ -0,0 +1,91 @@
+import { createHash } from "node:crypto";
+import { isUuid, uuidV5 } from "../core/uuid-v5.mjs";
+import { MUSIC_PROVIDER_LABELS } from "./music-providers.mjs";
+
+const namespace = "c9a85706-bf02-4f1d-b7e0-49e10d25a6be";
+export const musicHash = (value) => createHash("sha256").update(value).digest("hex");
+const id = (...parts) => uuidV5(JSON.stringify(parts), namespace);
+export const musicText = (value) => typeof value === "string" ? Array.from(value.normalize("NFC")
+  .replace(/[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/gu, " ")
+  .replace(/\s+/gu, " ").trim()).slice(0, 512).join("") : "";
+
+/** Shared normalized boundary. Collections never manufacture listening events. */
+export function prepareMusicBundle({ provider, subjectId, capturedAt, rows, digest, size, members, skipped = 0, scopeNote, fileName }) {
+  if (!MUSIC_PROVIDER_LABELS[provider] || !isUuid(subjectId)) throw new Error("Invalid music import identity.");
+  subjectId = subjectId.toLowerCase();
+  capturedAt = new Date(capturedAt).toISOString();
+  const sourceKey = `${provider}.music_import`;
+  const format = `${provider}_music_v1`;
+  const batchId = id(provider, subjectId, digest, "batch");
+  const profileId = id(provider, subjectId, digest, "profile");
+  const tracks = new Map();
+  const events = new Map();
+  const evidence = new Map();
+  for (const row of rows) {
+    const title = musicText(row.title);
+    const artist = musicText(row.artist);
+    const album = musicText(row.album);
+    if (!row.id || !title) { skipped += 1; continue; }
+    const trackId = id(provider, "track", row.id);
+    const track = {
+      schema_version: 1, track_ref_id: trackId, revision: 1, identity_status: "provisional",
+      display_label: musicText(artist ? `${title} - ${artist}` : title), title,
+      ...(artist ? { artist_credits: [{ name: artist, role: "unknown" }] } : {}),
+      ...(album ? { release: { title: album } } : {}),
+      external_refs: [{ system: provider, entity_type: `${provider}.track`, external_id: String(row.id) }],
+      created_at: capturedAt,
+    };
+    // Prefer supplied library metadata to a history record's video title.
+    if (!tracks.has(trackId) || (artist && !tracks.get(trackId).artist_credits)) tracks.set(trackId, track);
+    if (row.occurredAt) {
+      const at = new Date(row.occurredAt).toISOString();
+      const key = musicHash(JSON.stringify([provider, subjectId, row.id, at]));
+      events.set(key, {
+        schema_version: 1, listening_event_id: id(key, "event"), subject_id: subjectId,
+        track_ref_id: trackId, track_ref_revision: 1, event_type: "play_observed",
+        occurred_at: at, ingested_at: capturedAt, interaction_mode: "unknown", context: { context_type: "unknown" },
+        provenance: { source_kind: "import", captured_at: capturedAt, import_batch_id: batchId,
+          external_ref: { system: provider, entity_type: `${provider}.play`, external_id: key } },
+        deduplication_key: key,
+      });
+    } else {
+      const kind = row.playlistId ? "playlist_track_added" : "library_track_saved";
+      const key = musicHash(JSON.stringify([provider, subjectId, kind, row.playlistId ?? "library", row.id]));
+      evidence.set(key, {
+        schema_version: 1, profile_evidence_id: id(profileId, key), evidence_key: key, subject_id: subjectId,
+        evidence_kind: kind, direction: "supports", strength_class: row.playlistId ? "curated" : "explicit",
+        entity: { entity_type: "track", entity_ref_id: trackId, track_ref_id: trackId, track_ref_revision: 1,
+          label: title, ...(artist ? { artist_credit: artist } : {}), ...(album ? { release: album } : {}) },
+        observed_at: capturedAt,
+        attributes: row.playlistId ? { playlist_name: musicText(row.playlistName) || "Selected playlist",
+          playlist_position: row.position ?? 1, playlist_id: String(row.playlistId), selected_public_playlist: true } : {},
+        provenance: { source_kind: "import", source_system: provider, source_member: row.member,
+          profile_import_id: profileId, captured_at: capturedAt },
+      });
+    }
+  }
+  if (!events.size && !evidence.size) throw new Error("No supported music records found. Choose a music library CSV, YouTube Music watch-history JSON, or a non-empty public playlist.");
+  const dates = [...events.values()].map((event) => event.occurred_at).sort();
+  const manifest = { subject_id: subjectId, source_format: format, archive_sha256: digest,
+    archive_size_bytes: size, member_names: members, imported_at: capturedAt };
+  return {
+    provider,
+    bundle: {
+      source_key: sourceKey, captured_at: capturedAt, cursor_after_ms: null,
+      track_refs: [...tracks.values()], listening_events: [...events.values()],
+      import_batch: { ...manifest, import_batch_id: batchId, data_scope: "selected_music_records",
+        input_records: events.size, earliest_occurred_at: dates[0] ?? null, latest_occurred_at: dates.at(-1) ?? null },
+      ...(evidence.size ? {
+        profile_import: { ...manifest, profile_import_id: profileId, source_key: sourceKey, input_records: evidence.size },
+        profile_evidence: [...evidence.values()],
+      } : {}),
+    },
+    preview: {
+      kind: events.size ? "history" : "collection", sourceLabel: MUSIC_PROVIDER_LABELS[provider], fileName,
+      tracks: tracks.size, listeningEvents: events.size, profileEvidence: evidence.size,
+      skippedRecords: skipped, eventsWithPlayedMs: 0, earliestListeningAt: dates[0], latestListeningAt: dates.at(-1),
+      sampleTracks: [...tracks.values()].slice(0, 3).map((track) => track.display_label),
+      capturedAt, scopeNote,
+    },
+  };
+}

package/src/profile/music-providers.mjs

@@ -0,0 +1,25 @@
+export const MUSIC_PROVIDER_LABELS = Object.freeze({
+  spotify_account_data: "Spotify",
+  youtube_music: "YouTube Music",
+  qq_music: "QQ Music",
+  netease: "NetEase Cloud Music",
+});
+
+export function musicProviderLabel(system) {
+  return MUSIC_PROVIDER_LABELS[system] ?? "Imported music";
+}
+
+export function collectionCoverage(coverage) {
+  const spotify = coverage.collection_sources?.find((source) => source.system === "spotify_account_data");
+  return {
+    collection_tracks: coverage.collection_tracks ?? 0,
+    collection_sources: coverage.collection_sources ?? [],
+    saved_tracks: coverage.saved_tracks,
+    playlist_memberships: coverage.playlist_memberships,
+    spotify_profile_evidence: spotify?.evidence_records ?? 0,
+    spotify_saved_tracks: spotify?.saved_tracks ?? 0,
+    spotify_saved_albums: spotify?.saved_albums ?? 0,
+    spotify_followed_artists: spotify?.followed_artists ?? 0,
+    spotify_playlist_memberships: spotify?.playlist_memberships ?? 0,
+  };
+}

package/src/profile/spotify-archive-catalog-hints.mjs

@@ -0,0 +1,210 @@
+import { randomUUID } from "node:crypto";
+
+import { readSpotifyHistoryArchive } from "../integrations/spotify/history-archive.mjs";
+
+const supportedSourceFormats = new Set([
+  "spotify_account_data_streaming_history_v1",
+  "spotify_extended_streaming_history_music_v1",
+]);
+const maximumImportedRecords = 500_000;
+const maximumReleaseHints = 3;
+const unsafeTextPattern =
+  /[\u0000-\u001f\u007f-\u009f\u202a-\u202e\u2066-\u2069]/gu;
+
+function fail(message) {
+  const error = new Error(message);
+  error.code = "spotify_archive_catalog_hint_invalid";
+  throw error;
+}
+
+function cleanText(value, maximum, field) {
+  if (typeof value !== "string") fail(`The Spotify archive ${field} is invalid.`);
+  const cleaned = value
+    .normalize("NFC")
+    .replace(unsafeTextPattern, " ")
+    .replace(/\s+/gu, " ")
+    .trim();
+  if (!cleaned || Array.from(cleaned).length > maximum) {
+    fail(`The Spotify archive ${field} is invalid.`);
+  }
+  return cleaned;
+}
+
+function normalizeIdentity(value) {
+  return cleanText(value, 512, "artist name")
+    .normalize("NFKC")
+    .toLocaleLowerCase("und");
+}
+
+function normalizedReleaseKey(value) {
+  return value === null
+    ? null
+    : value.normalize("NFKC").toLocaleLowerCase("und");
+}
+
+function boundedArray(value, field) {
+  if (!Array.isArray(value) || value.length > maximumImportedRecords) {
+    fail(`The Spotify archive ${field} is invalid.`);
+  }
+  return value;
+}
+
+function timestampScore(value) {
+  if (typeof value !== "string") return 0;
+  const score = Date.parse(value);
+  return Number.isFinite(score) ? score : 0;
+}
+
+function numericPlayedMs(value) {
+  return Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+
+function compareHints(left, right) {
+  if (left.eventCount !== right.eventCount) {
+    return right.eventCount - left.eventCount;
+  }
+  if (left.playedMs !== right.playedMs) return right.playedMs - left.playedMs;
+  if (left.latestAt !== right.latestAt) return right.latestAt - left.latestAt;
+  if (left.trackIds.size !== right.trackIds.size) {
+    return right.trackIds.size - left.trackIds.size;
+  }
+  return left.title.localeCompare(right.title, "und");
+}
+
+export async function deriveArtistReleaseHintsFromSpotifyArchive({
+  archivePath,
+  artistName,
+  capturedAt = new Date().toISOString(),
+  maximumHints = maximumReleaseHints,
+  historyArchiveImporter = readSpotifyHistoryArchive,
+} = {}) {
+  if (typeof archivePath !== "string" || !archivePath.trim()) {
+    throw new TypeError("A Spotify history ZIP path is required.");
+  }
+  const normalizedArtist = normalizeIdentity(artistName);
+  if (
+    typeof capturedAt !== "string" ||
+    !Number.isFinite(Date.parse(capturedAt))
+  ) {
+    throw new TypeError("The Spotify archive capture time is invalid.");
+  }
+  if (
+    !Number.isInteger(maximumHints) ||
+    maximumHints < 1 ||
+    maximumHints > maximumReleaseHints
+  ) {
+    throw new TypeError("The Spotify archive release-hint limit is invalid.");
+  }
+  if (typeof historyArchiveImporter !== "function") {
+    throw new TypeError("A Spotify history archive reader is required.");
+  }
+
+  const bundle = await historyArchiveImporter({
+    archivePath,
+    subjectId: randomUUID(),
+    capturedAt: new Date(capturedAt).toISOString(),
+  });
+  if (!bundle || typeof bundle !== "object" || Array.isArray(bundle)) {
+    fail("The Spotify archive import result is invalid.");
+  }
+  const sourceFormat = cleanText(
+    bundle.import_batch?.source_format,
+    128,
+    "source format",
+  );
+  if (!supportedSourceFormats.has(sourceFormat)) {
+    fail("The Spotify archive source format is unsupported.");
+  }
+
+  const matchingTracks = new Map();
+  for (const trackRef of boundedArray(bundle.track_refs, "track references")) {
+    if (!trackRef || typeof trackRef !== "object" || Array.isArray(trackRef)) {
+      fail("The Spotify archive track reference is invalid.");
+    }
+    const artistCredits = boundedArray(trackRef.artist_credits, "artist credits");
+    const exactArtist = artistCredits.some(
+      (credit) =>
+        credit &&
+        typeof credit === "object" &&
+        !Array.isArray(credit) &&
+        normalizeIdentity(credit.name) === normalizedArtist,
+    );
+    if (!exactArtist) continue;
+    const trackRefId = cleanText(trackRef.track_ref_id, 128, "track reference ID");
+    const releaseTitle = trackRef.release?.title;
+    const normalizedRelease =
+      typeof releaseTitle === "string" && releaseTitle.trim()
+        ? cleanText(releaseTitle, 512, "release title")
+        : null;
+    const existing = matchingTracks.get(trackRefId);
+    if (
+      existing &&
+      existing.releaseTitle !== null &&
+      normalizedRelease !== null &&
+      normalizedReleaseKey(existing.releaseTitle) !==
+        normalizedReleaseKey(normalizedRelease)
+    ) {
+      fail("The Spotify archive track identity is inconsistent.");
+    }
+    if (existing) {
+      existing.releaseTitle ??= normalizedRelease;
+      existing.createdAt = Math.max(
+        existing.createdAt,
+        timestampScore(trackRef.created_at),
+      );
+      continue;
+    }
+    matchingTracks.set(trackRefId, {
+      releaseTitle: normalizedRelease,
+      createdAt: timestampScore(trackRef.created_at),
+      eventCount: 0,
+      playedMs: 0,
+      latestAt: 0,
+    });
+  }
+
+  let exactArtistEventCount = 0;
+  for (const event of boundedArray(bundle.listening_events, "listening events")) {
+    if (!event || typeof event !== "object" || Array.isArray(event)) {
+      fail("The Spotify archive listening event is invalid.");
+    }
+    const track = matchingTracks.get(event.track_ref_id);
+    if (!track) continue;
+    exactArtistEventCount += 1;
+    track.eventCount += 1;
+    track.playedMs += numericPlayedMs(event.played_ms);
+    track.latestAt = Math.max(track.latestAt, timestampScore(event.occurred_at));
+  }
+
+  const releases = new Map();
+  for (const [trackRefId, track] of matchingTracks) {
+    if (!track.releaseTitle) continue;
+    const key = normalizedReleaseKey(track.releaseTitle);
+    const release = releases.get(key) ?? {
+      title: track.releaseTitle,
+      trackIds: new Set(),
+      eventCount: 0,
+      playedMs: 0,
+      latestAt: 0,
+    };
+    release.trackIds.add(trackRefId);
+    release.eventCount += track.eventCount;
+    release.playedMs += track.playedMs;
+    release.latestAt = Math.max(
+      release.latestAt,
+      track.latestAt,
+      track.createdAt,
+    );
+    releases.set(key, release);
+  }
+
+  return {
+    source_format: sourceFormat,
+    exact_artist_track_count: matchingTracks.size,
+    exact_artist_event_count: exactArtistEventCount,
+    release_titles: [...releases.values()]
+      .sort(compareHints)
+      .slice(0, maximumHints)
+      .map((release) => release.title),
+  };
+}