sonovault 3.0.0 → 4.1.0

package/README.md

@@ -37,6 +37,18 @@ 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
+}
+
+// One record groups every edition of an album, so pick the one you mean
+for (const e of release.editions ?? []) {
+  console.log(e.id, e.format, e.release_date, e.track_count); // 16216 cd 2001-03-12 14
+}
+const deluxe = await sv.releases.get(7, { edition: 16216 });
+
 // 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 = "3.0.0";
+var VERSION = "4.1.0";
 
 // src/client.ts
 var SonoVault = class {
@@ -99,7 +99,12 @@ var SonoVault = class {
     };
     this.releases = {
       search: (params) => this.request("/v1/releases/search", { query: params }),
-      get: (id) => this.request(`/v1/releases/${id}`),
+      /**
+       * One release with its tracklist and the editions behind it. Pass
+       * `edition` (an `id` from the response's `editions`) to render that
+       * edition's track numbering instead of the default consensus.
+       */
+      get: (id, params = {}) => this.request(`/v1/releases/${id}`, { query: params }),
       /** Newly released albums (GET /v1/releases/new). Paid tiers. */
       latest: (params = {}) => this.request("/v1/releases/new", { query: params })
     };

package/dist/index.d.cts

@@ -35,6 +35,32 @@ interface Track {
     /** 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> {
     results: T[];
@@ -43,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 {
@@ -62,9 +100,84 @@ 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. Numbering comes from the edition named by
+     * `edition`, or from a consensus across the release's editions when none was
+     * named.
+     */
+    tracks?: ReleaseTrack[];
+    /**
+     * The real editions behind this release, at most 20. A SonoVault release
+     * groups every edition of an album onto one record, so the single, the
+     * album, the deluxe and the box set share one ID; these are the editions
+     * behind it. Chosen so each is a genuinely different edition rather than
+     * twenty pressings of the same one. Only returned by `releases.get()`.
+     */
+    editions?: ReleaseEdition[];
+    /**
+     * The edition whose numbering `tracks` uses. `null` unless an edition was
+     * requested. Only returned by `releases.get()`.
+     */
+    edition?: number | null;
     [key: string]: unknown;
 }
+/**
+ * One real edition behind a release: a specific pressing, issue or digital
+ * album as one provider describes it. Pass its `id` to
+ * `releases.get(id, { edition })` to render that edition's track numbering.
+ */
+interface ReleaseEdition {
+    id: number;
+    /** The provider describing this edition. */
+    source: "spotify" | "discogs" | "musicbrainz";
+    /** The edition's ID at that provider. */
+    external_id: string;
+    /**
+     * The provider's identity for the album across all its editions: a
+     * MusicBrainz release-group MBID or a Discogs master ID. `null` for Spotify,
+     * which has no such concept.
+     */
+    group_external_id: string | null;
+    /** The edition's own title, which often carries what makes it distinct. */
+    title: string | null;
+    edition_kind: "album" | "single" | "ep" | "compilation" | "live" | "remix" | "soundtrack" | "other" | null;
+    format: "cd" | "vinyl" | "cassette" | "digital" | "dvd" | "mixed" | "other" | null;
+    /** `false` for a release the provider marks unofficial, such as a bootleg. */
+    official: boolean | null;
+    /**
+     * The edition's release date, `YYYY-MM-DD`. Read it with `date_precision`: a
+     * month-precision date is reported as the first of the month.
+     */
+    release_date: string | null;
+    date_precision: "day" | "month" | "year" | null;
+    /** Barcode or UPC, digits only, so editions can be matched across providers. */
+    barcode: string | null;
+    /** Where the edition was issued, as the provider names it. Not an ISO code. */
+    country: string | null;
+    /** How many discs, records or tapes the edition spans. */
+    medium_count: number | null;
+    /**
+     * The provider's own total for the edition, including tracks SonoVault does
+     * not hold. Compare with `tracks_on_row` to see the gap.
+     */
+    track_count: number | null;
+    /** How many of this release's tracks sit on the edition. */
+    tracks_on_row: number;
+}
 interface Genre {
     id: number;
     name: string;
@@ -323,7 +436,14 @@ declare class SonoVault {
             limit?: number;
             cursor?: string;
         }) => Promise<Page<Release>>;
-        get: (id: number) => Promise<Release>;
+        /**
+         * One release with its tracklist and the editions behind it. Pass
+         * `edition` (an `id` from the response's `editions`) to render that
+         * edition's track numbering instead of the default consensus.
+         */
+        get: (id: number, params?: {
+            edition?: number;
+        }) => Promise<Release>;
         /** Newly released albums (GET /v1/releases/new). Paid tiers. */
         latest: (params?: {
             limit?: number;
@@ -450,4 +570,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 StreamStatus, type StreamUpdateResponse, 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 ReleaseEdition, 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

@@ -35,6 +35,32 @@ interface Track {
     /** 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> {
     results: T[];
@@ -43,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 {
@@ -62,9 +100,84 @@ 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. Numbering comes from the edition named by
+     * `edition`, or from a consensus across the release's editions when none was
+     * named.
+     */
+    tracks?: ReleaseTrack[];
+    /**
+     * The real editions behind this release, at most 20. A SonoVault release
+     * groups every edition of an album onto one record, so the single, the
+     * album, the deluxe and the box set share one ID; these are the editions
+     * behind it. Chosen so each is a genuinely different edition rather than
+     * twenty pressings of the same one. Only returned by `releases.get()`.
+     */
+    editions?: ReleaseEdition[];
+    /**
+     * The edition whose numbering `tracks` uses. `null` unless an edition was
+     * requested. Only returned by `releases.get()`.
+     */
+    edition?: number | null;
     [key: string]: unknown;
 }
+/**
+ * One real edition behind a release: a specific pressing, issue or digital
+ * album as one provider describes it. Pass its `id` to
+ * `releases.get(id, { edition })` to render that edition's track numbering.
+ */
+interface ReleaseEdition {
+    id: number;
+    /** The provider describing this edition. */
+    source: "spotify" | "discogs" | "musicbrainz";
+    /** The edition's ID at that provider. */
+    external_id: string;
+    /**
+     * The provider's identity for the album across all its editions: a
+     * MusicBrainz release-group MBID or a Discogs master ID. `null` for Spotify,
+     * which has no such concept.
+     */
+    group_external_id: string | null;
+    /** The edition's own title, which often carries what makes it distinct. */
+    title: string | null;
+    edition_kind: "album" | "single" | "ep" | "compilation" | "live" | "remix" | "soundtrack" | "other" | null;
+    format: "cd" | "vinyl" | "cassette" | "digital" | "dvd" | "mixed" | "other" | null;
+    /** `false` for a release the provider marks unofficial, such as a bootleg. */
+    official: boolean | null;
+    /**
+     * The edition's release date, `YYYY-MM-DD`. Read it with `date_precision`: a
+     * month-precision date is reported as the first of the month.
+     */
+    release_date: string | null;
+    date_precision: "day" | "month" | "year" | null;
+    /** Barcode or UPC, digits only, so editions can be matched across providers. */
+    barcode: string | null;
+    /** Where the edition was issued, as the provider names it. Not an ISO code. */
+    country: string | null;
+    /** How many discs, records or tapes the edition spans. */
+    medium_count: number | null;
+    /**
+     * The provider's own total for the edition, including tracks SonoVault does
+     * not hold. Compare with `tracks_on_row` to see the gap.
+     */
+    track_count: number | null;
+    /** How many of this release's tracks sit on the edition. */
+    tracks_on_row: number;
+}
 interface Genre {
     id: number;
     name: string;
@@ -323,7 +436,14 @@ declare class SonoVault {
             limit?: number;
             cursor?: string;
         }) => Promise<Page<Release>>;
-        get: (id: number) => Promise<Release>;
+        /**
+         * One release with its tracklist and the editions behind it. Pass
+         * `edition` (an `id` from the response's `editions`) to render that
+         * edition's track numbering instead of the default consensus.
+         */
+        get: (id: number, params?: {
+            edition?: number;
+        }) => Promise<Release>;
         /** Newly released albums (GET /v1/releases/new). Paid tiers. */
         latest: (params?: {
             limit?: number;
@@ -450,4 +570,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 StreamStatus, type StreamUpdateResponse, 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 ReleaseEdition, 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 = "3.0.0";
+var VERSION = "4.1.0";
 
 // src/client.ts
 var SonoVault = class {
@@ -70,7 +70,12 @@ var SonoVault = class {
     };
     this.releases = {
       search: (params) => this.request("/v1/releases/search", { query: params }),
-      get: (id) => this.request(`/v1/releases/${id}`),
+      /**
+       * One release with its tracklist and the editions behind it. Pass
+       * `edition` (an `id` from the response's `editions`) to render that
+       * edition's track numbering instead of the default consensus.
+       */
+      get: (id, params = {}) => this.request(`/v1/releases/${id}`, { query: params }),
       /** Newly released albums (GET /v1/releases/new). Paid tiers. */
       latest: (params = {}) => this.request("/v1/releases/new", { query: params })
     };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sonovault",
-  "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.",
+  "version": "4.1.0",
+  "description": "TypeScript/Node client for the SonoVault music metadata API \u2014 ISRC, ISWC, genre, labels, release dates, and cross-platform IDs for 93M+ tracks.",
   "keywords": [
     "music",
     "metadata",