sonovault 2.0.0 → 3.0.0

package/dist/index.cjs

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

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;
 }
@@ -135,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;
@@ -313,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>>;
@@ -413,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 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;
 }
@@ -135,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;
@@ -313,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>>;
@@ -413,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 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 = "2.0.0";
+var VERSION = "3.0.0";
 
 // src/client.ts
 var SonoVault = class {

package/package.json

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