sonovault 2.0.0 → 4.0.0

package/README.md

@@ -37,6 +37,12 @@ for (const link of links) {
   console.log(link.source, link.url); // spotify https://open.spotify.com/track/...
 }
 
+// An album's tracklist, in playing order
+const release = await sv.releases.get(7);
+for (const t of release.tracks ?? []) {
+  console.log(t.disc_number, t.track_number, t.title); // 1 1 One More Time
+}
+
 // Recording to composition (ISWC), for royalty and publishing workflows
 const work = await sv.tracks.iswc({ isrc: "GBDUW0000053" });
 ```

package/dist/index.cjs

@@ -50,7 +50,7 @@ var SonoVaultError = class extends Error {
 };
 
 // src/version.ts
-var VERSION = "2.0.0";
+var VERSION = "4.0.0";
 
 // src/client.ts
 var SonoVault = class {

package/dist/index.d.cts

@@ -30,8 +30,36 @@ 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 track as embedded in a release, from `GET /v1/releases/:id`.
+ *
+ * Same as {@link Track} minus the `releases` array (the release is the object
+ * you are already looking at), plus this track's position on that release.
+ */
+interface ReleaseTrack {
+    id: number;
+    title: string;
+    artists: TrackArtist[];
+    isrc: string | null;
+    duration: number | null;
+    /** Canonical genres. Empty array when the track is unclassified. */
+    genre: string[];
+    /** Canonical subgenres. Empty array when none apply. */
+    subgenre: string[];
+    /** Disc the track sits on, counting from 1. Null when the position is unknown. */
+    disc_number: number | null;
+    /**
+     * Position on this release, counting from 1 within its disc. A position
+     * belongs to the pairing of track and release rather than to the track, so
+     * the same recording can be track 6 on an album and track 2 on a
+     * compilation. Null when the position is unknown.
+     */
+    track_number: number | null;
 }
 /** A cursor-paginated page. `next_cursor` is null on the last page. */
 interface Page<T> {
@@ -41,6 +69,18 @@ interface Page<T> {
 interface Artist {
     id: number;
     name: string;
+    /** Country of origin, in English. Null when unknown. */
+    country?: string | null;
+    /** Year the artist or group started, or birth year for a solo act. */
+    formation_year?: number | null;
+    /** Full ISO date, present only when day-level precision is known. */
+    formation_date?: string | null;
+    /** Platform to handle or URL. Which keys appear varies by artist. */
+    social_links?: Record<string, string> | null;
+    /** Wikidata entity ID, e.g. `Q185828`. Null when unmapped. */
+    wikidata_id?: string | null;
+    /** MusicBrainz artist MBID. Null when unmapped. */
+    musicbrainz_id?: string | null;
     [key: string]: unknown;
 }
 interface Label {
@@ -60,16 +100,33 @@ interface Release {
         name: string;
     } | null;
     release_date?: string | null;
-    tracks?: Track[];
+    /**
+     * MusicBrainz release MBIDs, sorted. An array rather than a single value
+     * because a SonoVault release groups every edition of an album and each
+     * edition carries its own MBID, so you can pick the edition you need. Empty
+     * when unmapped. Only returned by `releases.get()`.
+     */
+    musicbrainz_release_ids?: string[];
+    /**
+     * MusicBrainz release-group MBIDs: the identity of the album across all its
+     * editions, as opposed to any one pressing. Usually a single entry. Empty
+     * when unmapped. Only returned by `releases.get()`.
+     */
+    musicbrainz_release_group_ids?: string[];
+    /**
+     * The tracklist, in playing order (disc, then track number), with any track
+     * whose position is unknown last.
+     */
+    tracks?: ReleaseTrack[];
     [key: string]: unknown;
 }
 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 +138,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;
 }
@@ -135,11 +194,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;
@@ -313,8 +405,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>>;
@@ -413,4 +505,4 @@ declare function verifyWebhookSignature(options: {
  */
 declare function paginate<T>(fetchPage: (cursor: string | undefined) => Promise<Page<T>>): AsyncGenerator<T>;
 
-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 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 ReleaseTrack, 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,36 @@ 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 track as embedded in a release, from `GET /v1/releases/:id`.
+ *
+ * Same as {@link Track} minus the `releases` array (the release is the object
+ * you are already looking at), plus this track's position on that release.
+ */
+interface ReleaseTrack {
+    id: number;
+    title: string;
+    artists: TrackArtist[];
+    isrc: string | null;
+    duration: number | null;
+    /** Canonical genres. Empty array when the track is unclassified. */
+    genre: string[];
+    /** Canonical subgenres. Empty array when none apply. */
+    subgenre: string[];
+    /** Disc the track sits on, counting from 1. Null when the position is unknown. */
+    disc_number: number | null;
+    /**
+     * Position on this release, counting from 1 within its disc. A position
+     * belongs to the pairing of track and release rather than to the track, so
+     * the same recording can be track 6 on an album and track 2 on a
+     * compilation. Null when the position is unknown.
+     */
+    track_number: number | null;
 }
 /** A cursor-paginated page. `next_cursor` is null on the last page. */
 interface Page<T> {
@@ -41,6 +69,18 @@ interface Page<T> {
 interface Artist {
     id: number;
     name: string;
+    /** Country of origin, in English. Null when unknown. */
+    country?: string | null;
+    /** Year the artist or group started, or birth year for a solo act. */
+    formation_year?: number | null;
+    /** Full ISO date, present only when day-level precision is known. */
+    formation_date?: string | null;
+    /** Platform to handle or URL. Which keys appear varies by artist. */
+    social_links?: Record<string, string> | null;
+    /** Wikidata entity ID, e.g. `Q185828`. Null when unmapped. */
+    wikidata_id?: string | null;
+    /** MusicBrainz artist MBID. Null when unmapped. */
+    musicbrainz_id?: string | null;
     [key: string]: unknown;
 }
 interface Label {
@@ -60,16 +100,33 @@ interface Release {
         name: string;
     } | null;
     release_date?: string | null;
-    tracks?: Track[];
+    /**
+     * MusicBrainz release MBIDs, sorted. An array rather than a single value
+     * because a SonoVault release groups every edition of an album and each
+     * edition carries its own MBID, so you can pick the edition you need. Empty
+     * when unmapped. Only returned by `releases.get()`.
+     */
+    musicbrainz_release_ids?: string[];
+    /**
+     * MusicBrainz release-group MBIDs: the identity of the album across all its
+     * editions, as opposed to any one pressing. Usually a single entry. Empty
+     * when unmapped. Only returned by `releases.get()`.
+     */
+    musicbrainz_release_group_ids?: string[];
+    /**
+     * The tracklist, in playing order (disc, then track number), with any track
+     * whose position is unknown last.
+     */
+    tracks?: ReleaseTrack[];
     [key: string]: unknown;
 }
 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 +138,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;
 }
@@ -135,11 +194,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;
@@ -313,8 +405,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>>;
@@ -413,4 +505,4 @@ declare function verifyWebhookSignature(options: {
  */
 declare function paginate<T>(fetchPage: (cursor: string | undefined) => Promise<Page<T>>): AsyncGenerator<T>;
 
-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 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 ReleaseTrack, 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 = "2.0.0";
+var VERSION = "4.0.0";
 
 // src/client.ts
 var SonoVault = class {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sonovault",
-  "version": "2.0.0",
+  "version": "4.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",