sonovault 4.0.0 → 4.2.0

package/README.md

@@ -43,8 +43,17 @@ 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" });
+
+// What a label released on one day (from / until are inclusive YYYY-MM-DD)
+const friday = await sv.labels.releases(1, { from: "2026-09-11", until: "2026-09-11" });
 ```
 
 ## Bulk resolve

package/dist/index.cjs

@@ -50,7 +50,7 @@ var SonoVaultError = class extends Error {
 };
 
 // src/version.ts
-var VERSION = "4.0.0";
+var VERSION = "4.2.0";
 
 // src/client.ts
 var SonoVault = class {
@@ -89,17 +89,27 @@ var SonoVault = class {
     this.artists = {
       search: (params) => this.request("/v1/artists/search", { query: params }),
       get: (id) => this.request(`/v1/artists/${id}`),
+      /** An artist's releases, newest first. `from` / `until` are inclusive `YYYY-MM-DD` release dates. */
       releases: (id, params = {}) => this.request(`/v1/artists/${id}/releases`, { query: params })
     };
     this.labels = {
       search: (params) => this.request("/v1/labels/search", { query: params }),
       get: (id) => this.request(`/v1/labels/${id}`),
+      /**
+       * A label's releases, newest first. `from` / `until` are inclusive `YYYY-MM-DD`
+       * release dates, so `{ from: "2026-09-11", until: "2026-09-11" }` lists one day.
+       */
       releases: (id, params = {}) => this.request(`/v1/labels/${id}/releases`, { query: params }),
       artists: (id, params = {}) => this.request(`/v1/labels/${id}/artists`, { query: params })
     };
     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

@@ -66,6 +66,15 @@ interface Page<T> {
     results: T[];
     next_cursor: string | null;
 }
+/** Query params for an artist's or a label's release list. */
+type ReleaseListParams = {
+    limit?: number;
+    cursor?: string;
+    /** Only releases dated on or after this day (`YYYY-MM-DD`). Undated releases are left out when `from` or `until` is set. */
+    from?: string;
+    /** Only releases dated on or before this day (`YYYY-MM-DD`). Pass the same day as `from` for a single release date. */
+    until?: string;
+};
 interface Artist {
     id: number;
     name: string;
@@ -115,11 +124,79 @@ interface Release {
     musicbrainz_release_group_ids?: string[];
     /**
      * The tracklist, in playing order (disc, then track number), with any track
-     * whose position is unknown last.
+     * 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;
+    /**
+     * The label that issued this pressing, as the provider names it. Pressings of
+     * one album often differ: the UK original and a US reissue each carry their own.
+     */
+    label: {
+        id: number;
+        name: string;
+    } | null;
+    /** The pressing's catalog number, from Discogs and MusicBrainz. */
+    catalog_no: string | null;
+}
 interface Genre {
     id: number;
     name: string;
@@ -350,10 +427,8 @@ declare class SonoVault {
             cursor?: string;
         }) => Promise<Page<Artist>>;
         get: (id: number) => Promise<Artist>;
-        releases: (id: number, params?: {
-            limit?: number;
-            cursor?: string;
-        }) => Promise<Page<Release>>;
+        /** An artist's releases, newest first. `from` / `until` are inclusive `YYYY-MM-DD` release dates. */
+        releases: (id: number, params?: ReleaseListParams) => Promise<Page<Release>>;
     };
     readonly labels: {
         search: (params: {
@@ -362,10 +437,11 @@ declare class SonoVault {
             cursor?: string;
         }) => Promise<Page<Label>>;
         get: (id: number) => Promise<Label>;
-        releases: (id: number, params?: {
-            limit?: number;
-            cursor?: string;
-        }) => Promise<Page<Release>>;
+        /**
+         * A label's releases, newest first. `from` / `until` are inclusive `YYYY-MM-DD`
+         * release dates, so `{ from: "2026-09-11", until: "2026-09-11" }` lists one day.
+         */
+        releases: (id: number, params?: ReleaseListParams) => Promise<Page<Release>>;
         artists: (id: number, params?: {
             limit?: number;
             cursor?: string;
@@ -378,7 +454,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;
@@ -505,4 +588,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 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 };
+export { type Artist, type Genre, type IdentifyResponse, type IdentifyResult, type IswcLookupResponse, type Label, type Page, type PlatformLink, type PlatformLinksResponse, type Release, type ReleaseEdition, type ReleaseListParams, 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

@@ -66,6 +66,15 @@ interface Page<T> {
     results: T[];
     next_cursor: string | null;
 }
+/** Query params for an artist's or a label's release list. */
+type ReleaseListParams = {
+    limit?: number;
+    cursor?: string;
+    /** Only releases dated on or after this day (`YYYY-MM-DD`). Undated releases are left out when `from` or `until` is set. */
+    from?: string;
+    /** Only releases dated on or before this day (`YYYY-MM-DD`). Pass the same day as `from` for a single release date. */
+    until?: string;
+};
 interface Artist {
     id: number;
     name: string;
@@ -115,11 +124,79 @@ interface Release {
     musicbrainz_release_group_ids?: string[];
     /**
      * The tracklist, in playing order (disc, then track number), with any track
-     * whose position is unknown last.
+     * 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;
+    /**
+     * The label that issued this pressing, as the provider names it. Pressings of
+     * one album often differ: the UK original and a US reissue each carry their own.
+     */
+    label: {
+        id: number;
+        name: string;
+    } | null;
+    /** The pressing's catalog number, from Discogs and MusicBrainz. */
+    catalog_no: string | null;
+}
 interface Genre {
     id: number;
     name: string;
@@ -350,10 +427,8 @@ declare class SonoVault {
             cursor?: string;
         }) => Promise<Page<Artist>>;
         get: (id: number) => Promise<Artist>;
-        releases: (id: number, params?: {
-            limit?: number;
-            cursor?: string;
-        }) => Promise<Page<Release>>;
+        /** An artist's releases, newest first. `from` / `until` are inclusive `YYYY-MM-DD` release dates. */
+        releases: (id: number, params?: ReleaseListParams) => Promise<Page<Release>>;
     };
     readonly labels: {
         search: (params: {
@@ -362,10 +437,11 @@ declare class SonoVault {
             cursor?: string;
         }) => Promise<Page<Label>>;
         get: (id: number) => Promise<Label>;
-        releases: (id: number, params?: {
-            limit?: number;
-            cursor?: string;
-        }) => Promise<Page<Release>>;
+        /**
+         * A label's releases, newest first. `from` / `until` are inclusive `YYYY-MM-DD`
+         * release dates, so `{ from: "2026-09-11", until: "2026-09-11" }` lists one day.
+         */
+        releases: (id: number, params?: ReleaseListParams) => Promise<Page<Release>>;
         artists: (id: number, params?: {
             limit?: number;
             cursor?: string;
@@ -378,7 +454,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;
@@ -505,4 +588,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 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 };
+export { type Artist, type Genre, type IdentifyResponse, type IdentifyResult, type IswcLookupResponse, type Label, type Page, type PlatformLink, type PlatformLinksResponse, type Release, type ReleaseEdition, type ReleaseListParams, 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 = "4.0.0";
+var VERSION = "4.2.0";
 
 // src/client.ts
 var SonoVault = class {
@@ -60,17 +60,27 @@ var SonoVault = class {
     this.artists = {
       search: (params) => this.request("/v1/artists/search", { query: params }),
       get: (id) => this.request(`/v1/artists/${id}`),
+      /** An artist's releases, newest first. `from` / `until` are inclusive `YYYY-MM-DD` release dates. */
       releases: (id, params = {}) => this.request(`/v1/artists/${id}/releases`, { query: params })
     };
     this.labels = {
       search: (params) => this.request("/v1/labels/search", { query: params }),
       get: (id) => this.request(`/v1/labels/${id}`),
+      /**
+       * A label's releases, newest first. `from` / `until` are inclusive `YYYY-MM-DD`
+       * release dates, so `{ from: "2026-09-11", until: "2026-09-11" }` lists one day.
+       */
       releases: (id, params = {}) => this.request(`/v1/labels/${id}/releases`, { query: params }),
       artists: (id, params = {}) => this.request(`/v1/labels/${id}/artists`, { query: params })
     };
     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": "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.",
+  "version": "4.2.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",