musiciwant 1.0.0

package/README.md

@@ -0,0 +1,49 @@
+# musiciwant (JavaScript / TypeScript)
+
+Tiny, zero-dependency client for the [Music I Want API](https://musiciwant.com/developers) — independent sensory + musical analysis for ~19,000 songs. BPM, dynamic range, sudden changes, texture, vocal style, a 0–100 **intensity** score, moods, use-case fits, and **misophonia** flags no other public API carries.
+
+An honest alternative to the data that disappeared when Spotify deprecated its Audio Features API.
+
+## Install
+
+```bash
+npm install musiciwant
+```
+
+## Quickstart
+
+```js
+const { MusicIWant } = require('musiciwant');
+
+const miw = new MusicIWant(); // works key-less at 100 req/day/IP
+
+const { song } = await miw.song({ title: 'Black', artist: 'Pearl Jam' });
+console.log(song.bpm, song.dynamic_range, song.intensity, song.sensory_level);
+// 76 7 47 "moderate"
+
+const { results } = await miw.search('radiohead');
+```
+
+## A free key (2,000 requests/day)
+
+```js
+const { key } = await MusicIWant.getKey('you@example.com');
+const miw = new MusicIWant({ apiKey: key });
+await miw.usage(); // { tier, requests_today, remaining_today, ... }
+```
+
+Or set `MUSICIWANT_API_KEY` in your environment and the client picks it up.
+
+## Tiers
+
+| Tier | Limit | How |
+| --- | --- | --- |
+| anonymous | 100 req/day/IP | nothing |
+| free | 2,000 req/day | `MusicIWant.getKey(email)` |
+| pro | 100,000 req/day | $19/mo — see [docs](https://musiciwant.com/developers) |
+
+Bulk dataset licensing for apps, platforms, and research: [musiciwant.com/developers](https://musiciwant.com/developers#data).
+
+## License
+
+MIT (client code). The song data is © Music I Want, free to use with attribution; bulk/commercial use is licensed separately.

package/index.d.ts

@@ -0,0 +1,86 @@
+export interface Song {
+  slug: string;
+  title: string;
+  artist: string;
+  album: string | null;
+  year: number | null;
+  bpm: number | null;
+  /** "safe" | "moderate" | "intense" */
+  sensory_level: string;
+  /** 1–10: distance between the quietest and loudest moments */
+  dynamic_range: number;
+  /** "none" | "mild" | "moderate" | "frequent" | "extreme" */
+  sudden_changes: string;
+  /** "smooth" | "layered" | "complex" | "harsh" | "abrasive" */
+  texture: string;
+  /** "high" | "medium" | "low" */
+  predictability: string;
+  /** "instrumental" | "soft vocals" | "spoken word" | "dynamic vocals" | "screaming" */
+  vocal_style: string;
+  sensory_notes: string | null;
+  /** Misophonia flags: "none" | "mild" | "present" */
+  miso_mouth: string;
+  miso_clicks: string;
+  miso_breathing: string;
+  miso_repetitive: string;
+  age_min: number | null;
+  age_max: number | null;
+  age_confidence: number | null;
+  lyrical_content: string | null;
+  /** 0–100 single sensory-load score. Unique to Music I Want. */
+  intensity: number | null;
+  spotify_id: string | null;
+  youtube_id: string | null;
+  spotify_url: string | null;
+  youtube_url: string | null;
+  /** Present on single-song lookups. */
+  moods?: string[];
+  /** Present on single-song lookups. */
+  recommended_for?: string[];
+  url: string;
+}
+
+export interface SongResponse { found: boolean; song?: Song; error?: string; }
+export interface SearchResponse { count: number; results: Song[]; }
+export interface UsageResponse {
+  tier: string; requests_today: number; limit_per_day: number;
+  remaining_today: number; total_requests: number; member_since: string;
+}
+export interface KeyResponse { key: string; tier: string; limit_per_day?: number; }
+
+export interface ClientOptions { apiKey?: string; baseUrl?: string; fetch?: typeof fetch; }
+
+export class MusicIWantError extends Error {
+  status: number;
+  body: any;
+}
+
+export interface GentlerResponse {
+  found: boolean;
+  already_gentle?: boolean;
+  original?: Song;
+  alternatives?: (Song & { shared_moods?: string[] })[];
+  error?: string;
+}
+export interface DecadeStat { decade: number; mean_intensity: number; n: number; }
+export interface GenreStat { genre: string; mean_intensity: number; n: number; }
+export interface StatsResponse {
+  total_songs: number;
+  mean_intensity: number;
+  sensory_level_split: { safe: number; moderate: number; intense: number };
+  by_decade: DecadeStat[];
+  gentlest_genres: GenreStat[];
+  most_intense_genres: GenreStat[];
+}
+
+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>;
+  usage(): Promise<UsageResponse>;
+  static getKey(email: string, opts?: ClientOptions): Promise<KeyResponse>;
+}
+
+export default MusicIWant;

package/index.js

@@ -0,0 +1,103 @@
+'use strict';
+/**
+ * musiciwant — tiny, zero-dependency client for the Music I Want API.
+ * Independent sensory + musical analysis for ~19,000 songs: BPM, dynamic range,
+ * sudden changes, texture, vocal style, a 0–100 intensity score, moods,
+ * use-case fits, and misophonia flags. An honest alternative to the music
+ * features that vanished when Spotify deprecated its Audio Features API.
+ *
+ * Docs: https://musiciwant.com/developers
+ * Free key (2,000 req/day): MusicIWant.getKey('you@example.com')
+ */
+
+const BASE = 'https://musiciwant.com';
+
+class MusicIWantError extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.name = 'MusicIWantError';
+    this.status = status;
+    this.body = body;
+  }
+}
+
+class MusicIWant {
+  /** @param {{apiKey?: string, baseUrl?: string, fetch?: Function}} [opts] */
+  constructor(opts = {}) {
+    this.apiKey = opts.apiKey || process.env.MUSICIWANT_API_KEY || null;
+    this.baseUrl = (opts.baseUrl || BASE).replace(/\/$/, '');
+    this._fetch = opts.fetch || (typeof fetch !== 'undefined' ? fetch : null);
+    if (!this._fetch) throw new Error('No fetch available. Use Node 18+ or pass opts.fetch.');
+  }
+
+  async _get(path, params = {}) {
+    const url = new URL(this.baseUrl + path);
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== undefined && v !== null && v !== '') url.searchParams.set(k, String(v));
+    }
+    const headers = { 'Accept': 'application/json' };
+    if (this.apiKey) headers['X-API-Key'] = this.apiKey;
+    const res = await this._fetch(url.toString(), { headers });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      throw new MusicIWantError((body && body.error) || ('HTTP ' + res.status), res.status, body);
+    }
+    return body;
+  }
+
+  /**
+   * Full analysis for one song. Provide {title, artist} or {slug}.
+   * @returns {Promise<object>} { found, song }
+   */
+  song({ title, artist, slug } = {}) {
+    if (!title && !slug) throw new Error('song() needs { title, artist } or { slug }');
+    return this._get('/api/v1/song', { title, artist, slug });
+  }
+
+  /** Search by title or artist. @returns {Promise<object>} { count, results } */
+  search(q) {
+    if (!q || String(q).trim().length < 2) throw new Error('search(q) needs 2+ characters');
+    return this._get('/api/v1/search', { q });
+  }
+
+  /**
+   * Songs with the same emotional feel but a lower sensory intensity.
+   * Provide {title, artist} or {slug}. @returns {Promise<object>} { found, original, alternatives }
+   */
+  gentler({ title, artist, slug } = {}) {
+    if (!title && !slug) throw new Error('gentler() needs { title, artist } or { slug }');
+    return this._get('/api/v1/gentler', { title, artist, slug });
+  }
+
+  /** Aggregate catalog statistics (level split, intensity by decade, genre extremes). */
+  stats() {
+    return this._get('/api/v1/stats', {});
+  }
+
+  /** Current key's tier + remaining quota. Requires an apiKey. */
+  usage() {
+    if (!this.apiKey) throw new Error('usage() requires an apiKey');
+    return this._get('/api/v1/usage', {});
+  }
+
+  /**
+   * Mint a free key (2,000 req/day) for an email. Static — no instance needed.
+   * @returns {Promise<{key:string, tier:string}>}
+   */
+  static async getKey(email, opts = {}) {
+    const base = (opts.baseUrl || BASE).replace(/\/$/, '');
+    const f = opts.fetch || (typeof fetch !== 'undefined' ? fetch : null);
+    if (!f) throw new Error('No fetch available. Use Node 18+ or pass opts.fetch.');
+    const res = await f(base + '/api/v1/keys', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email })
+    });
+    const body = await res.json().catch(() => ({}));
+    if (!res.ok) throw new MusicIWantError((body && body.error) || ('HTTP ' + res.status), res.status, body);
+    return body;
+  }
+}
+
+module.exports = { MusicIWant, MusicIWantError, default: MusicIWant };
+module.exports.MusicIWant = MusicIWant;

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "musiciwant",
+  "version": "1.0.0",
+  "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",
+  "type": "commonjs",
+  "files": ["index.js", "index.d.ts", "README.md"],
+  "scripts": {
+    "test": "node test.js"
+  },
+  "keywords": [
+    "music", "bpm", "tempo", "audio-features", "spotify-alternative",
+    "music-analysis", "dynamic-range", "misophonia", "sensory", "playlist",
+    "music-data", "api-client"
+  ],
+  "homepage": "https://musiciwant.com/developers",
+  "repository": { "type": "git", "url": "git+https://github.com/musiciwant/musiciwant-api.git", "directory": "packages/js" },
+  "bugs": { "url": "https://github.com/musiciwant/musiciwant-api/issues" },
+  "author": "Music I Want",
+  "license": "MIT",
+  "engines": { "node": ">=18" }
+}