sonovault 4.0.0 → 4.1.0

package/README.md

@@ -43,6 +43,12 @@ 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 = "4.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

@@ -115,11 +115,69 @@ 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;
+}
 interface Genre {
     id: number;
     name: string;
@@ -378,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;
@@ -505,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 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 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

@@ -115,11 +115,69 @@ 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;
+}
 interface Genre {
     id: number;
     name: string;
@@ -378,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;
@@ -505,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 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 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.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": "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.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",