sonovault 1.2.0 → 3.0.0

package/README.md

@@ -3,7 +3,7 @@
 [![CI](https://github.com/rekordcloud/sonovault-js/actions/workflows/ci.yml/badge.svg)](https://github.com/rekordcloud/sonovault-js/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/sonovault)](https://www.npmjs.com/package/sonovault)
 
-TypeScript/Node client for the **[SonoVault](https://sonovault.now)** music metadata API. 90M+ tracks with ISRC, ISWC, genre, record label, canonical release dates, and cross-platform IDs for Spotify, Apple Music, Tidal, Beatport, Discogs, and MusicBrainz. One call resolves them all.
+TypeScript/Node client for the **[SonoVault](https://sonovault.now)** music metadata API. 93M+ tracks with ISRC, ISWC, genre, record label, canonical release dates, and cross-platform IDs for Spotify, Apple Music, Tidal, Beatport, Discogs, and MusicBrainz. One call resolves them all.
 
 - **One key, no OAuth.** A single `x-api-key` header, no approval queue.
 - **Free tier.** 1,000 requests/month, no credit card: [get an API key](https://sonovault.now).
@@ -109,7 +109,7 @@ Runnable scripts live in [`examples/`](examples/): find an ISRC, resolve cross-p
 
 | Namespace | Methods |
 |---|---|
-| `sv.tracks` | `search`, `get`, `byIsrc`, `iswc`, `byIswc`, `links`, `resolve`, `identify`, `identifyAudio`, `browse` |
+| `sv.tracks` | `search`, `get`, `byIsrc`, `iswc`, `byIswc`, `links`, `resolve`, `identifyAudio`, `browse` |
 | `sv.artists` | `search`, `get`, `releases` |
 | `sv.labels` | `search`, `get`, `releases`, `artists` |
 | `sv.releases` | `search`, `get`, `latest` |

package/dist/index.cjs

@@ -50,7 +50,7 @@ var SonoVaultError = class extends Error {
 };
 
 // src/version.ts
-var VERSION = "1.2.0";
+var VERSION = "3.0.0";
 
 // src/client.ts
 var SonoVault = class {
@@ -73,8 +73,6 @@ var SonoVault = class {
       links: (params) => this.request("/v1/tracks/links", { query: params }),
       /** Resolve up to 100 track names, ISRCs, or platform IDs in one request. */
       resolve: (body) => this.request("/v1/tracks/resolve", { method: "POST", json: body }),
-      /** Identify a track from a Chromaprint fingerprint (`fpcalc -raw`). Paid tiers. */
-      identify: (body) => this.request("/v1/tracks/identify", { method: "POST", json: body }),
       /**
        * Identify a track from raw audio bytes (any ffmpeg-decodable format).
        * Send the whole track when you can — the matching section is often mid-track.

package/dist/index.d.cts

@@ -30,8 +30,10 @@ interface Track {
     artists: TrackArtist[];
     isrc: string | null;
     duration: number | null;
-    genre: string | null;
-    subgenre: string | null;
+    /** Canonical genres. Empty array when the track is unclassified. */
+    genre: string[];
+    /** Canonical subgenres. Empty array when none apply. */
+    subgenre: string[];
 }
 /** A cursor-paginated page. `next_cursor` is null on the last page. */
 interface Page<T> {
@@ -66,10 +68,10 @@ interface Release {
 interface Genre {
     id: number;
     name: string;
-    subgenres?: {
-        id: number;
-        name: string;
-    }[];
+    /** Whether this is a top-level genre or a subgenre. */
+    type: "main" | "subgenre";
+    /** Name of the parent genre; null for a top-level genre. */
+    parent: string | null;
     [key: string]: unknown;
 }
 /** A track's ID on an external platform, with a deep link. */
@@ -81,6 +83,8 @@ interface PlatformLink {
 interface PlatformLinksResponse {
     track_id: number;
     title: string;
+    /** One representative ISRC for the track; null when none is known. */
+    isrc: string | null;
     links: PlatformLink[];
     [key: string]: unknown;
 }
@@ -120,14 +124,6 @@ interface ResolveResponse {
     credits_remaining: number;
     message: string | null;
 }
-interface IdentifyRequest {
-    /** 50–50,000 integers from `fpcalc -raw` (Chromaprint). */
-    fingerprint: number[];
-    /** Clip duration in seconds. */
-    fingerprint_duration?: number;
-    /** Max results to return, 1–25. */
-    top_n?: number;
-}
 interface IdentifyResult {
     id: number;
     title: string;
@@ -143,11 +139,44 @@ interface IdentifyResponse {
 }
 interface Stream {
     id: string;
-    url?: string;
-    name?: string;
-    status?: string;
+    url: string;
+    name: string | null;
+    status: "active" | "stopped";
+    detection_mode: "precise" | "balanced" | "broad";
+    /** Whether we email you when this stream goes down and when it recovers. */
+    outage_notifications: boolean;
+    created_at: string;
+    stopped_at: string | null;
     [key: string]: unknown;
 }
+/**
+ * A stream's live state, as returned by `streams.get()`: the stream fields plus
+ * what is playing right now.
+ */
+interface StreamStatus extends Stream {
+    /** What the monitor is doing now: `pending`, `running`, `errored` or `stopped`. */
+    runtime_status: string;
+    /** Why it is in that state (e.g. an auth wall on the host); null when it is fine. */
+    status_reason: string | null;
+    /** Null during ad breaks, talk, or audio we cannot place. */
+    now_playing: {
+        track: Track;
+        started_at: string;
+    } | null;
+    last_recognized_at: string | null;
+    /** Recognition tuning hint in force; null means auto (all recognisers). */
+    format: "electronic" | "classical" | "pop" | null;
+}
+/**
+ * The response to `streams.update()`. The API echoes back only the fields you
+ * changed, so everything but `id` is optional.
+ */
+interface StreamUpdateResponse {
+    id: string;
+    format?: "electronic" | "classical" | "pop" | null;
+    detection_mode?: "precise" | "balanced" | "broad";
+    outage_notifications?: boolean;
+}
 interface Webhook {
     id: string;
     url: string;
@@ -238,8 +267,6 @@ declare class SonoVault {
         }) => Promise<PlatformLinksResponse>;
         /** Resolve up to 100 track names, ISRCs, or platform IDs in one request. */
         resolve: (body: ResolveRequest) => Promise<ResolveResponse>;
-        /** Identify a track from a Chromaprint fingerprint (`fpcalc -raw`). Paid tiers. */
-        identify: (body: IdentifyRequest) => Promise<IdentifyResponse>;
         /**
          * Identify a track from raw audio bytes (any ffmpeg-decodable format).
          * Send the whole track when you can — the matching section is often mid-track.
@@ -323,8 +350,8 @@ declare class SonoVault {
         list: () => Promise<{
             streams: Stream[];
         }>;
-        get: (id: string) => Promise<Stream>;
-        update: (id: string, body: Record<string, unknown>) => Promise<Stream>;
+        get: (id: string) => Promise<StreamStatus>;
+        update: (id: string, body: Record<string, unknown>) => Promise<StreamUpdateResponse>;
         history: (id: string, params?: {
             since?: string;
         }) => Promise<Record<string, unknown>>;
@@ -423,4 +450,4 @@ declare function verifyWebhookSignature(options: {
  */
 declare function paginate<T>(fetchPage: (cursor: string | undefined) => Promise<Page<T>>): AsyncGenerator<T>;
 
-export { type Artist, type Genre, type IdentifyRequest, type IdentifyResponse, type IdentifyResult, type IswcLookupResponse, type Label, type Page, type PlatformLink, type PlatformLinksResponse, type Release, type ResolveInputType, type ResolveRequest, type ResolveResponse, type ResolveResult, SonoVault, SonoVaultError, type SonoVaultOptions, type Stream, type StreamEvent, type Track, type TrackArtist, type TrackRelease, type Webhook, paginate, verifyWebhookSignature };
+export { type Artist, type Genre, type IdentifyResponse, type IdentifyResult, type IswcLookupResponse, type Label, type Page, type PlatformLink, type PlatformLinksResponse, type Release, type ResolveInputType, type ResolveRequest, type ResolveResponse, type ResolveResult, SonoVault, SonoVaultError, type SonoVaultOptions, type Stream, type StreamEvent, type StreamStatus, type StreamUpdateResponse, type Track, type TrackArtist, type TrackRelease, type Webhook, paginate, verifyWebhookSignature };

package/dist/index.d.ts

@@ -30,8 +30,10 @@ interface Track {
     artists: TrackArtist[];
     isrc: string | null;
     duration: number | null;
-    genre: string | null;
-    subgenre: string | null;
+    /** Canonical genres. Empty array when the track is unclassified. */
+    genre: string[];
+    /** Canonical subgenres. Empty array when none apply. */
+    subgenre: string[];
 }
 /** A cursor-paginated page. `next_cursor` is null on the last page. */
 interface Page<T> {
@@ -66,10 +68,10 @@ interface Release {
 interface Genre {
     id: number;
     name: string;
-    subgenres?: {
-        id: number;
-        name: string;
-    }[];
+    /** Whether this is a top-level genre or a subgenre. */
+    type: "main" | "subgenre";
+    /** Name of the parent genre; null for a top-level genre. */
+    parent: string | null;
     [key: string]: unknown;
 }
 /** A track's ID on an external platform, with a deep link. */
@@ -81,6 +83,8 @@ interface PlatformLink {
 interface PlatformLinksResponse {
     track_id: number;
     title: string;
+    /** One representative ISRC for the track; null when none is known. */
+    isrc: string | null;
     links: PlatformLink[];
     [key: string]: unknown;
 }
@@ -120,14 +124,6 @@ interface ResolveResponse {
     credits_remaining: number;
     message: string | null;
 }
-interface IdentifyRequest {
-    /** 50–50,000 integers from `fpcalc -raw` (Chromaprint). */
-    fingerprint: number[];
-    /** Clip duration in seconds. */
-    fingerprint_duration?: number;
-    /** Max results to return, 1–25. */
-    top_n?: number;
-}
 interface IdentifyResult {
     id: number;
     title: string;
@@ -143,11 +139,44 @@ interface IdentifyResponse {
 }
 interface Stream {
     id: string;
-    url?: string;
-    name?: string;
-    status?: string;
+    url: string;
+    name: string | null;
+    status: "active" | "stopped";
+    detection_mode: "precise" | "balanced" | "broad";
+    /** Whether we email you when this stream goes down and when it recovers. */
+    outage_notifications: boolean;
+    created_at: string;
+    stopped_at: string | null;
     [key: string]: unknown;
 }
+/**
+ * A stream's live state, as returned by `streams.get()`: the stream fields plus
+ * what is playing right now.
+ */
+interface StreamStatus extends Stream {
+    /** What the monitor is doing now: `pending`, `running`, `errored` or `stopped`. */
+    runtime_status: string;
+    /** Why it is in that state (e.g. an auth wall on the host); null when it is fine. */
+    status_reason: string | null;
+    /** Null during ad breaks, talk, or audio we cannot place. */
+    now_playing: {
+        track: Track;
+        started_at: string;
+    } | null;
+    last_recognized_at: string | null;
+    /** Recognition tuning hint in force; null means auto (all recognisers). */
+    format: "electronic" | "classical" | "pop" | null;
+}
+/**
+ * The response to `streams.update()`. The API echoes back only the fields you
+ * changed, so everything but `id` is optional.
+ */
+interface StreamUpdateResponse {
+    id: string;
+    format?: "electronic" | "classical" | "pop" | null;
+    detection_mode?: "precise" | "balanced" | "broad";
+    outage_notifications?: boolean;
+}
 interface Webhook {
     id: string;
     url: string;
@@ -238,8 +267,6 @@ declare class SonoVault {
         }) => Promise<PlatformLinksResponse>;
         /** Resolve up to 100 track names, ISRCs, or platform IDs in one request. */
         resolve: (body: ResolveRequest) => Promise<ResolveResponse>;
-        /** Identify a track from a Chromaprint fingerprint (`fpcalc -raw`). Paid tiers. */
-        identify: (body: IdentifyRequest) => Promise<IdentifyResponse>;
         /**
          * Identify a track from raw audio bytes (any ffmpeg-decodable format).
          * Send the whole track when you can — the matching section is often mid-track.
@@ -323,8 +350,8 @@ declare class SonoVault {
         list: () => Promise<{
             streams: Stream[];
         }>;
-        get: (id: string) => Promise<Stream>;
-        update: (id: string, body: Record<string, unknown>) => Promise<Stream>;
+        get: (id: string) => Promise<StreamStatus>;
+        update: (id: string, body: Record<string, unknown>) => Promise<StreamUpdateResponse>;
         history: (id: string, params?: {
             since?: string;
         }) => Promise<Record<string, unknown>>;
@@ -423,4 +450,4 @@ declare function verifyWebhookSignature(options: {
  */
 declare function paginate<T>(fetchPage: (cursor: string | undefined) => Promise<Page<T>>): AsyncGenerator<T>;
 
-export { type Artist, type Genre, type IdentifyRequest, type IdentifyResponse, type IdentifyResult, type IswcLookupResponse, type Label, type Page, type PlatformLink, type PlatformLinksResponse, type Release, type ResolveInputType, type ResolveRequest, type ResolveResponse, type ResolveResult, SonoVault, SonoVaultError, type SonoVaultOptions, type Stream, type StreamEvent, type Track, type TrackArtist, type TrackRelease, type Webhook, paginate, verifyWebhookSignature };
+export { type Artist, type Genre, type IdentifyResponse, type IdentifyResult, type IswcLookupResponse, type Label, type Page, type PlatformLink, type PlatformLinksResponse, type Release, type ResolveInputType, type ResolveRequest, type ResolveResponse, type ResolveResult, SonoVault, SonoVaultError, type SonoVaultOptions, type Stream, type StreamEvent, type StreamStatus, type StreamUpdateResponse, type Track, type TrackArtist, type TrackRelease, type Webhook, paginate, verifyWebhookSignature };

package/dist/index.js

@@ -21,7 +21,7 @@ var SonoVaultError = class extends Error {
 };
 
 // src/version.ts
-var VERSION = "1.2.0";
+var VERSION = "3.0.0";
 
 // src/client.ts
 var SonoVault = class {
@@ -44,8 +44,6 @@ var SonoVault = class {
       links: (params) => this.request("/v1/tracks/links", { query: params }),
       /** Resolve up to 100 track names, ISRCs, or platform IDs in one request. */
       resolve: (body) => this.request("/v1/tracks/resolve", { method: "POST", json: body }),
-      /** Identify a track from a Chromaprint fingerprint (`fpcalc -raw`). Paid tiers. */
-      identify: (body) => this.request("/v1/tracks/identify", { method: "POST", json: body }),
       /**
        * Identify a track from raw audio bytes (any ffmpeg-decodable format).
        * Send the whole track when you can — the matching section is often mid-track.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sonovault",
-  "version": "1.2.0",
-  "description": "TypeScript/Node client for the SonoVault music metadata API — ISRC, ISWC, genre, labels, release dates, and cross-platform IDs for 90M+ tracks.",
+  "version": "3.0.0",
+  "description": "TypeScript/Node client for the SonoVault music metadata API — ISRC, ISWC, genre, labels, release dates, and cross-platform IDs for 93M+ tracks.",
   "keywords": [
     "music",
     "metadata",