musiciwant 1.0.0 → 1.1.1

package/index.d.ts

@@ -33,10 +33,18 @@ export interface Song {
   youtube_id: string | null;
   spotify_url: string | null;
   youtube_url: string | null;
+  /** ISRC (MusicBrainz-sourced; null until a confident match exists — never fabricated). */
+  isrc: string | null;
+  /** First release date (MusicBrainz). */
+  release_date: string | null;
+  /** Genres/tags (MusicBrainz). */
+  genres: string[];
   /** Present on single-song lookups. */
   moods?: string[];
   /** Present on single-song lookups. */
   recommended_for?: string[];
+  /** All-platform listen links. Present on single-song lookups. */
+  listen?: Record<string, string>;
   url: string;
 }
 
@@ -73,12 +81,39 @@ export interface StatsResponse {
   most_intense_genres: GenreStat[];
 }
 
+export interface FilterOptions {
+  minBpm?: number; maxBpm?: number; minIntensity?: number; maxIntensity?: number;
+  maxDynamicRange?: number; sensoryLevel?: 'safe' | 'moderate' | 'intense';
+  suddenChanges?: string | string[]; vocalStyle?: string; mood?: string;
+  misoSafe?: boolean; limit?: number; offset?: number;
+}
+export interface FilterResponse { count: number; results: Song[]; }
+export type SongRef = { title: string; artist?: string } | { slug: string };
+export interface BatchResponse { count: number; results: { query: SongRef; found: boolean; song: Song | null }[]; }
+export interface PlaylistTrack { query: SongRef; matched: boolean; title?: string; artist?: string; slug?: string; intensity?: number; sensory_level?: string; }
+export interface PlaylistResponse {
+  tracks: PlaylistTrack[];
+  stats: { avg: number; max_jump: number; ambushes: number[]; peak_index: number; calm_index: number } | null;
+  unmatched: number;
+}
+export interface FingerprintResponse {
+  found: boolean;
+  song?: { title: string; artist: string; slug: string };
+  vector?: Record<string, number>;
+  vector_array?: number[];
+  dims?: string[];
+}
+
 export class MusicIWant {
   constructor(opts?: ClientOptions);
   song(params: { title: string; artist?: string } | { slug: string }): Promise<SongResponse>;
   search(q: string): Promise<SearchResponse>;
   gentler(params: { title: string; artist?: string } | { slug: string }): Promise<GentlerResponse>;
   stats(): Promise<StatsResponse>;
+  filter(opts?: FilterOptions): Promise<FilterResponse>;
+  batch(songs: SongRef[]): Promise<BatchResponse>;
+  playlist(songs: SongRef[]): Promise<PlaylistResponse>;
+  fingerprint(params: { title: string; artist?: string } | { slug: string }): Promise<FingerprintResponse>;
   usage(): Promise<UsageResponse>;
   static getKey(email: string, opts?: ClientOptions): Promise<KeyResponse>;
 }

package/index.js

@@ -74,6 +74,60 @@ class MusicIWant {
     return this._get('/api/v1/stats', {});
   }
 
+  /**
+   * Query the catalog by feel. All options optional: { minBpm, maxBpm,
+   * minIntensity, maxIntensity, maxDynamicRange, sensoryLevel, suddenChanges
+   * (string or array), vocalStyle, mood, misoSafe (bool), limit, offset }.
+   * @returns {Promise<object>} { count, results }
+   */
+  filter(opts = {}) {
+    const sc = Array.isArray(opts.suddenChanges) ? opts.suddenChanges.join(',') : opts.suddenChanges;
+    return this._get('/api/v1/filter', {
+      min_bpm: opts.minBpm, max_bpm: opts.maxBpm,
+      min_intensity: opts.minIntensity, max_intensity: opts.maxIntensity,
+      max_dynamic_range: opts.maxDynamicRange, sensory_level: opts.sensoryLevel,
+      sudden_changes: sc, vocal_style: opts.vocalStyle, mood: opts.mood,
+      miso_safe: opts.misoSafe ? 'true' : undefined,
+      limit: opts.limit, offset: opts.offset
+    });
+  }
+
+  /**
+   * Batch lookup (up to 100). songs: array of { title, artist } or { slug }.
+   * @returns {Promise<object>} { count, results: [{ query, found, song }] }
+   */
+  batch(songs) {
+    if (!Array.isArray(songs) || !songs.length) throw new Error('batch(songs) needs a non-empty array');
+    return this._post('/api/v1/songs', { songs });
+  }
+
+  /**
+   * Sensory shape of an ordered playlist (up to 60). songs: array of
+   * { title, artist } or { slug }. @returns {Promise<object>} { tracks, stats, unmatched }
+   */
+  playlist(songs) {
+    if (!Array.isArray(songs) || !songs.length) throw new Error('playlist(songs) needs a non-empty array');
+    return this._post('/api/v1/playlist', { songs });
+  }
+
+  /**
+   * Normalized 0–1 feature vector (the Spotify audio-features replacement).
+   * Provide {title, artist} or {slug}. @returns {Promise<object>} { found, song, vector, vector_array, dims }
+   */
+  fingerprint({ title, artist, slug } = {}) {
+    if (!title && !slug) throw new Error('fingerprint() needs { title, artist } or { slug }');
+    return this._get('/api/v1/fingerprint', { title, artist, slug });
+  }
+
+  async _post(path, body) {
+    const headers = { 'Accept': 'application/json', 'Content-Type': 'application/json' };
+    if (this.apiKey) headers['X-API-Key'] = this.apiKey;
+    const res = await this._fetch(this.baseUrl + path, { method: 'POST', headers, body: JSON.stringify(body) });
+    const out = await res.json().catch(() => ({}));
+    if (!res.ok) throw new MusicIWantError((out && out.error) || ('HTTP ' + res.status), res.status, out);
+    return out;
+  }
+
   /** Current key's tier + remaining quota. Requires an apiKey. */
   usage() {
     if (!this.apiKey) throw new Error('usage() requires an apiKey');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "musiciwant",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Independent music analysis API client — BPM, dynamic range, sensory intensity, moods, misophonia flags. A Spotify Audio Features alternative.",
   "main": "index.js",
   "types": "index.d.ts",