npm - sonovault - Versions diffs - 1.0.0 - Mend

sonovault 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Rekordcloud B.V.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md ADDED Viewed

@@ -0,0 +1,114 @@
+# sonovault
+[![CI](https://github.com/rekordcloud/sonovault-js/actions/workflows/ci.yml/badge.svg)](https://github.com/rekordcloud/sonovault-js/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/sonovault)](https://www.npmjs.com/package/sonovault)
+TypeScript/Node client for the **[SonoVault](https://sonovault.now)** music metadata API — 90M+ tracks with ISRC, ISWC, genre, record label, canonical release dates, and cross-platform IDs for Spotify, Apple Music, Tidal, Beatport, Discogs, and MusicBrainz, resolved in a single call.
+- **One key, no OAuth** — a single `x-api-key` header, no approval queue.
+- **Free tier** — 1,000 requests/month, no credit card: [get an API key](https://sonovault.now).
+- **Docs** — full API reference at [sonovault.now/docs](https://sonovault.now/docs).
+## Install
+```bash
+npm install sonovault
+```
+Node 18+ (uses the built-in `fetch`). ESM and CommonJS both supported.
+## Quickstart
+```ts
+import { SonoVault } from "sonovault";
+const sv = new SonoVault({ apiKey: process.env.SONOVAULT_API_KEY! });
+// Find a track's ISRC from artist + title
+const { results } = await sv.tracks.search({ artist: "Daft Punk", title: "One More Time" });
+console.log(results[0].isrc); // "GBDUW0000053"
+console.log(results[0].genre, results[0].releases[0]?.label?.name);
+// Resolve that ISRC to its ID on every platform
+const { links } = await sv.tracks.links({ isrc: "GBDUW0000053" });
+for (const link of links) {
+  console.log(link.source, link.url); // spotify https://open.spotify.com/track/…
+}
+// Recording → composition (ISWC), for royalty/publishing workflows
+const work = await sv.tracks.iswc({ isrc: "GBDUW0000053" });
+```
+## Bulk resolve
+Resolve up to 100 lines — track names, ISRCs, or platform IDs — in one request (great for enriching play logs and library exports):
+```ts
+const batch = await sv.tracks.resolve({
+  input_type: "track_name",
+  items: [
+    { artist: "Daft Punk", title: "Harder, Better, Faster, Stronger" },
+    { artist: "Daft Punk", title: "Around the World" },
+  ],
+});
+for (const row of batch.results) {
+  console.log(row.status, row.track?.isrc, row.track?.releases[0]?.label?.name);
+}
+```
+## Pagination
+List endpoints return `{ results, next_cursor }` — pass the cursor back to get the next page (`next_cursor` is `null` on the last page):
+```ts
+let cursor: string | undefined;
+do {
+  const page = await sv.artists.releases(42, { cursor });
+  // …use page.results
+  cursor = page.next_cursor ?? undefined;
+} while (cursor);
+```
+## Error handling
+Non-2xx responses throw a typed `SonoVaultError`:
+```ts
+import { SonoVaultError } from "sonovault";
+try {
+  await sv.tracks.browse({ genre: "House" }); // paid-tier endpoint
+} catch (err) {
+  if (err instanceof SonoVaultError) {
+    console.log(err.status, err.isForbidden, err.message);
+  }
+}
+```
+Rate-limited responses that carry a `Retry-After` header are retried automatically (twice by default; configure with `maxRetries`).
+## API coverage
+| Namespace | Methods |
+|---|---|
+| `sv.tracks` | `search`, `get`, `byIsrc`, `iswc`, `byIswc`, `links`, `resolve`, `identify`, `identifyAudio`, `browse` |
+| `sv.artists` | `search`, `get`, `releases` |
+| `sv.labels` | `search`, `get`, `releases`, `artists` |
+| `sv.releases` | `search`, `get`, `latest` |
+| `sv.genres` | `list` |
+| `sv.suggestions` | `submit`, `list` |
+| `sv.streams` | `create`, `list`, `get`, `update`, `history`, `report`, `live`, `stop` |
+| `sv.webhooks` | `create`, `list`, `update`, `delete`, `test`, `deliveries` |
+Some endpoints (audio identify, browse, charts, stream monitoring) need a paid tier — see [pricing](https://sonovault.now/pricing). Everything else works on the free tier.
+## Related
+- [SonoVault API docs](https://sonovault.now/docs) — full endpoint reference with examples in 8 languages
+- [sonovault-python](https://github.com/rekordcloud/sonovault-python) — the Python client
+- [Free ISRC lookup](https://sonovault.now/isrc-lookup) · [ISWC lookup](https://sonovault.now/iswc-lookup) — browser tools built on the same API
+## License
+MIT

package/dist/index.cjs ADDED Viewed

@@ -0,0 +1,186 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  SonoVault: () => SonoVault,
+  SonoVaultError: () => SonoVaultError
+});
+module.exports = __toCommonJS(index_exports);
+// src/error.ts
+var SonoVaultError = class extends Error {
+  constructor(message, status, body = void 0) {
+    super(message);
+    this.name = "SonoVaultError";
+    this.status = status;
+    this.body = body;
+  }
+  /** Missing or invalid API key. */
+  get isAuthError() {
+    return this.status === 401;
+  }
+  /** The endpoint needs a paid tier (or an admin key). */
+  get isForbidden() {
+    return this.status === 403;
+  }
+  /** Rate limit or monthly credit quota hit. */
+  get isRateLimited() {
+    return this.status === 429;
+  }
+};
+// src/client.ts
+var SonoVault = class {
+  constructor(options) {
+    this.tracks = {
+      /** Search by artist + title (both required — there is no free-text query). */
+      search: (params) => this.request("/v1/tracks/search", { query: params }),
+      /** Fetch a track by its SonoVault ID. */
+      get: (id) => this.request(`/v1/tracks/${id}`),
+      /** Look up a track by any of its ISRCs. */
+      byIsrc: (isrc) => this.request(`/v1/tracks/isrc/${encodeURIComponent(isrc)}`),
+      /** Recording → composition: the ISWC(s) behind a recording, by ISRC or track ID. */
+      iswc: (params) => this.request("/v1/tracks/iswc", { query: params }),
+      /** Composition → recordings: every recording of a work, by ISWC. */
+      byIswc: (iswc, params = {}) => this.request(
+        `/v1/tracks/iswc/${encodeURIComponent(iswc)}`,
+        { query: params }
+      ),
+      /** Cross-platform IDs + deep links for a track, resolved from any platform's ID or an ISRC. */
+      links: (params) => this.request("/v1/tracks/links", { query: params }),
+      /** Resolve up to 100 track names, ISRCs, or platform IDs in one request. */
+      resolve: (body) => this.request("/v1/tracks/resolve", { method: "POST", json: body }),
+      /** Identify a track from a Chromaprint fingerprint (`fpcalc -raw`). Paid tiers. */
+      identify: (body) => this.request("/v1/tracks/identify", { method: "POST", json: body }),
+      /**
+       * Identify a track from raw audio bytes (any ffmpeg-decodable format).
+       * Send the whole track when you can — the matching section is often mid-track.
+       * Paid tiers; costs 10 + ceil(MB) credits.
+       */
+      identifyAudio: (audio, params = {}) => this.request("/v1/tracks/identify", {
+        method: "POST",
+        query: params,
+        raw: { body: audio, contentType: "application/octet-stream" }
+      }),
+      /** Browse the catalog by label, artist, genre, or year. Paid tiers. */
+      browse: (params) => this.request("/v1/tracks/browse", { query: params })
+    };
+    this.artists = {
+      search: (params) => this.request("/v1/artists/search", { query: params }),
+      get: (id) => this.request(`/v1/artists/${id}`),
+      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}`),
+      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}`),
+      /** Newly released albums (GET /v1/releases/new). Paid tiers. */
+      latest: (params = {}) => this.request("/v1/releases/new", { query: params })
+    };
+    this.genres = {
+      /** The canonical genre/subgenre hierarchy. */
+      list: () => this.request("/v1/genres")
+    };
+    this.suggestions = {
+      /** Suggest a metadata correction for a track. Paid tiers. */
+      submit: (trackId, body) => this.request(`/v1/tracks/${trackId}/suggestions`, {
+        method: "POST",
+        json: body
+      }),
+      list: (params = {}) => this.request("/v1/suggestions", { query: params })
+    };
+    this.streams = {
+      /** Start monitoring an Icecast/Shoutcast stream. Paid tiers. */
+      create: (body) => this.request("/v1/streams", { method: "POST", json: body }),
+      list: () => this.request("/v1/streams"),
+      get: (id) => this.request(`/v1/streams/${id}`),
+      update: (id, body) => this.request(`/v1/streams/${id}`, { method: "PATCH", json: body }),
+      history: (id, params = {}) => this.request(`/v1/streams/${id}/history`, { query: params }),
+      report: (params) => this.request("/v1/streams/report", { query: params }),
+      /** What's playing right now across your monitored streams. */
+      live: () => this.request("/v1/streams/live"),
+      /** Stop monitoring a stream. */
+      stop: (id) => this.request(`/v1/streams/${id}`, { method: "DELETE" })
+    };
+    this.webhooks = {
+      /** Register an endpoint for stream events. The response includes `secret` once — store it. */
+      create: (body) => this.request("/v1/webhooks", { method: "POST", json: body }),
+      list: () => this.request("/v1/webhooks"),
+      update: (id, body) => this.request(`/v1/webhooks/${id}`, { method: "PATCH", json: body }),
+      delete: (id) => this.request(`/v1/webhooks/${id}`, { method: "DELETE" }),
+      test: (id) => this.request(`/v1/webhooks/${id}/test`, { method: "POST" }),
+      deliveries: (id) => this.request(`/v1/webhooks/${id}/deliveries`)
+    };
+    if (!options?.apiKey) throw new Error("SonoVault: apiKey is required");
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? "https://api.sonovault.now").replace(/\/$/, "");
+    this.maxRetries = options.maxRetries ?? 2;
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+  }
+  async request(path, opts = {}) {
+    const url = new URL(this.baseUrl + path);
+    for (const [key, value] of Object.entries(opts.query ?? {})) {
+      if (value !== void 0) url.searchParams.set(key, String(value));
+    }
+    const headers = { "x-api-key": this.apiKey };
+    let body;
+    if (opts.json !== void 0) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(opts.json);
+    } else if (opts.raw) {
+      headers["Content-Type"] = opts.raw.contentType;
+      body = opts.raw.body;
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      let res;
+      try {
+        res = await this.fetchImpl(url, { method: opts.method ?? "GET", headers, body });
+      } catch (err) {
+        lastError = new SonoVaultError(`Network error: ${err.message}`, 0);
+        continue;
+      }
+      if (res.ok) {
+        if (res.status === 204) return void 0;
+        return await res.json();
+      }
+      const errBody = await res.json().catch(() => void 0);
+      const message = errBody?.error ?? errBody?.message ?? `HTTP ${res.status}`;
+      lastError = new SonoVaultError(message, res.status, errBody);
+      const retryAfter = res.headers.get("retry-after");
+      const retryable = res.status >= 500 || res.status === 429 && retryAfter !== null;
+      if (!retryable || attempt === this.maxRetries) throw lastError;
+      const delayMs = retryAfter ? Number(retryAfter) * 1e3 : 500 * 2 ** attempt;
+      await new Promise((r) => setTimeout(r, delayMs));
+    }
+    throw lastError ?? new SonoVaultError("Request failed", 0);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SonoVault,
+  SonoVaultError
+});

package/dist/index.d.cts ADDED Viewed

@@ -0,0 +1,347 @@
+/** An artist credit on a track. */
+interface TrackArtist {
+    id: number;
+    name: string;
+    is_primary?: boolean;
+    is_remixer?: boolean;
+}
+/** A release a track appears on, with its artist, label, and release date. */
+interface TrackRelease {
+    id: number;
+    title: string;
+    artist: {
+        id: number;
+        name: string;
+    };
+    label: {
+        id: number;
+        name: string;
+    } | null;
+    release_date: string | null;
+}
+/**
+ * The public track shape returned by search, lookups, and resolve.
+ * Note: audio features (BPM, key, energy, …) are not exposed on the public API.
+ */
+interface Track {
+    id: number;
+    title: string;
+    releases: TrackRelease[];
+    artists: TrackArtist[];
+    isrc: string | null;
+    duration: number | null;
+    genre: string | null;
+    subgenre: string | null;
+}
+/** A cursor-paginated page. `next_cursor` is null on the last page. */
+interface Page<T> {
+    results: T[];
+    next_cursor: string | null;
+}
+interface Artist {
+    id: number;
+    name: string;
+    [key: string]: unknown;
+}
+interface Label {
+    id: number;
+    name: string;
+    [key: string]: unknown;
+}
+interface Release {
+    id: number;
+    title: string;
+    artist?: {
+        id: number;
+        name: string;
+    };
+    label?: {
+        id: number;
+        name: string;
+    } | null;
+    release_date?: string | null;
+    tracks?: Track[];
+    [key: string]: unknown;
+}
+interface Genre {
+    id: number;
+    name: string;
+    subgenres?: {
+        id: number;
+        name: string;
+    }[];
+    [key: string]: unknown;
+}
+/** A track's ID on an external platform, with a deep link. */
+interface PlatformLink {
+    source: string;
+    external_id: string;
+    url: string | null;
+}
+interface PlatformLinksResponse {
+    track_id: number;
+    title: string;
+    links: PlatformLink[];
+    [key: string]: unknown;
+}
+/** ISWC entries for a recording (one recording can carry several work codes). */
+interface IswcLookupResponse {
+    sonovault_id?: number;
+    isrc?: string;
+    iswcs?: {
+        iswc: string;
+        title: string | null;
+    }[];
+    [key: string]: unknown;
+}
+type ResolveInputType = "track_name" | "isrc" | "sonovault_id" | "spotify_id" | "applemusic_id" | "tidal_id" | "beatport_id" | "discogs_id" | "musicbrainz_id";
+interface ResolveRequest {
+    input_type: ResolveInputType;
+    /** 1–100 entries. `{ artist, title }` objects for `track_name`, strings otherwise. */
+    items: (string | {
+        artist: string;
+        title: string;
+    })[];
+}
+interface ResolveResult {
+    input: string | {
+        artist: string;
+        title: string;
+    };
+    status: "matched" | "not_found" | "skipped_no_credits";
+    track: Track | null;
+    links: PlatformLink[];
+}
+interface ResolveResponse {
+    results: ResolveResult[];
+    partial: boolean;
+    processed: number;
+    credits_used: number;
+    credits_remaining: number;
+    message: string | null;
+}
+interface IdentifyRequest {
+    /** 50–50,000 integers from `fpcalc -raw` (Chromaprint). */
+    fingerprint: number[];
+    /** Clip duration in seconds. */
+    fingerprint_duration?: number;
+    /** Max results to return, 1–25. */
+    top_n?: number;
+}
+interface IdentifyResult {
+    id: number;
+    title: string;
+    artists: TrackArtist[];
+    /** 0–1; higher means a more certain match. */
+    confidence: number;
+}
+interface IdentifyResponse {
+    matched: boolean;
+    results: IdentifyResult[];
+    credits_charged: number;
+    [key: string]: unknown;
+}
+interface Stream {
+    id: string;
+    url?: string;
+    name?: string;
+    status?: string;
+    [key: string]: unknown;
+}
+interface Webhook {
+    id: string;
+    url: string;
+    event_types?: string[];
+    /** Returned once, on creation — store it to verify delivery signatures. */
+    secret?: string;
+    [key: string]: unknown;
+}
+interface SonoVaultOptions {
+    /** Your API key — get a free one at https://sonovault.now (1,000 requests/month). */
+    apiKey: string;
+    /** Override the API base URL. Defaults to https://api.sonovault.now. */
+    baseUrl?: string;
+    /** Retries on 429/5xx responses. Default 2; set 0 to disable. */
+    maxRetries?: number;
+    /** Custom fetch implementation (for testing or polyfills). */
+    fetch?: typeof globalThis.fetch;
+}
+declare class SonoVault {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(options: SonoVaultOptions);
+    private request;
+    readonly tracks: {
+        /** Search by artist + title (both required — there is no free-text query). */
+        search: (params: {
+            artist: string;
+            title: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Track>>;
+        /** Fetch a track by its SonoVault ID. */
+        get: (id: number) => Promise<Track>;
+        /** Look up a track by any of its ISRCs. */
+        byIsrc: (isrc: string) => Promise<Track>;
+        /** Recording → composition: the ISWC(s) behind a recording, by ISRC or track ID. */
+        iswc: (params: {
+            isrc?: string;
+            id?: number;
+        }) => Promise<IswcLookupResponse>;
+        /** Composition → recordings: every recording of a work, by ISWC. */
+        byIswc: (iswc: string, params?: {
+            limit?: number;
+        }) => Promise<{
+            iswc: string;
+            results: Track[];
+        }>;
+        /** Cross-platform IDs + deep links for a track, resolved from any platform's ID or an ISRC. */
+        links: (params: {
+            id?: number;
+            isrc?: string;
+            spotify_id?: string;
+            beatport_id?: string;
+            discogs_id?: string;
+            musicbrainz_id?: string;
+            applemusic_id?: string;
+            tidal_id?: string;
+            youtube_id?: string;
+        }) => Promise<PlatformLinksResponse>;
+        /** Resolve up to 100 track names, ISRCs, or platform IDs in one request. */
+        resolve: (body: ResolveRequest) => Promise<ResolveResponse>;
+        /** Identify a track from a Chromaprint fingerprint (`fpcalc -raw`). Paid tiers. */
+        identify: (body: IdentifyRequest) => Promise<IdentifyResponse>;
+        /**
+         * Identify a track from raw audio bytes (any ffmpeg-decodable format).
+         * Send the whole track when you can — the matching section is often mid-track.
+         * Paid tiers; costs 10 + ceil(MB) credits.
+         */
+        identifyAudio: (audio: ArrayBuffer | Uint8Array | Blob, params?: {
+            length?: number;
+            top_n?: number;
+        }) => Promise<IdentifyResponse>;
+        /** Browse the catalog by label, artist, genre, or year. Paid tiers. */
+        browse: (params: {
+            labelId?: number;
+            artistId?: number;
+            genre?: string;
+            genreId?: number;
+            year?: number;
+            randomize?: boolean;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Track>>;
+    };
+    readonly artists: {
+        search: (params: {
+            name: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Artist>>;
+        get: (id: number) => Promise<Artist>;
+        releases: (id: number, params?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Release>>;
+    };
+    readonly labels: {
+        search: (params: {
+            name: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Label>>;
+        get: (id: number) => Promise<Label>;
+        releases: (id: number, params?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Release>>;
+        artists: (id: number, params?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Artist>>;
+    };
+    readonly releases: {
+        search: (params: {
+            title: string;
+            artist?: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Release>>;
+        get: (id: number) => Promise<Release>;
+        /** Newly released albums (GET /v1/releases/new). Paid tiers. */
+        latest: (params?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Release>>;
+    };
+    readonly genres: {
+        /** The canonical genre/subgenre hierarchy. */
+        list: () => Promise<{
+            genres: Genre[];
+        }>;
+    };
+    readonly suggestions: {
+        /** Suggest a metadata correction for a track. Paid tiers. */
+        submit: (trackId: number, body: Record<string, unknown>) => Promise<Record<string, unknown>>;
+        list: (params?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Record<string, unknown>>>;
+    };
+    readonly streams: {
+        /** Start monitoring an Icecast/Shoutcast stream. Paid tiers. */
+        create: (body: Record<string, unknown>) => Promise<Stream>;
+        list: () => Promise<{
+            streams: Stream[];
+        }>;
+        get: (id: string) => Promise<Stream>;
+        update: (id: string, body: Record<string, unknown>) => Promise<Stream>;
+        history: (id: string, params?: {
+            since?: string;
+        }) => Promise<Record<string, unknown>>;
+        report: (params: {
+            from: string;
+            until: string;
+            stream_id?: string;
+        }) => Promise<Record<string, unknown>>;
+        /** What's playing right now across your monitored streams. */
+        live: () => Promise<Record<string, unknown>>;
+        /** Stop monitoring a stream. */
+        stop: (id: string) => Promise<void>;
+    };
+    readonly webhooks: {
+        /** Register an endpoint for stream events. The response includes `secret` once — store it. */
+        create: (body: {
+            url: string;
+            event_types?: string[];
+            description?: string;
+        }) => Promise<Webhook>;
+        list: () => Promise<{
+            webhooks: Webhook[];
+        }>;
+        update: (id: string, body: Record<string, unknown>) => Promise<Webhook>;
+        delete: (id: string) => Promise<void>;
+        test: (id: string) => Promise<Record<string, unknown>>;
+        deliveries: (id: string) => Promise<Record<string, unknown>>;
+    };
+}
+/** Error thrown for any non-2xx API response. */
+declare class SonoVaultError extends Error {
+    /** HTTP status code, or 0 for network errors. */
+    readonly status: number;
+    /** Parsed JSON error body, when the API returned one. */
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+    /** Missing or invalid API key. */
+    get isAuthError(): boolean;
+    /** The endpoint needs a paid tier (or an admin key). */
+    get isForbidden(): boolean;
+    /** Rate limit or monthly credit quota hit. */
+    get isRateLimited(): boolean;
+}
+export { type Artist, type Genre, type IdentifyRequest, 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 Track, type TrackArtist, type TrackRelease, type Webhook };

package/dist/index.d.ts ADDED Viewed

@@ -0,0 +1,347 @@
+/** An artist credit on a track. */
+interface TrackArtist {
+    id: number;
+    name: string;
+    is_primary?: boolean;
+    is_remixer?: boolean;
+}
+/** A release a track appears on, with its artist, label, and release date. */
+interface TrackRelease {
+    id: number;
+    title: string;
+    artist: {
+        id: number;
+        name: string;
+    };
+    label: {
+        id: number;
+        name: string;
+    } | null;
+    release_date: string | null;
+}
+/**
+ * The public track shape returned by search, lookups, and resolve.
+ * Note: audio features (BPM, key, energy, …) are not exposed on the public API.
+ */
+interface Track {
+    id: number;
+    title: string;
+    releases: TrackRelease[];
+    artists: TrackArtist[];
+    isrc: string | null;
+    duration: number | null;
+    genre: string | null;
+    subgenre: string | null;
+}
+/** A cursor-paginated page. `next_cursor` is null on the last page. */
+interface Page<T> {
+    results: T[];
+    next_cursor: string | null;
+}
+interface Artist {
+    id: number;
+    name: string;
+    [key: string]: unknown;
+}
+interface Label {
+    id: number;
+    name: string;
+    [key: string]: unknown;
+}
+interface Release {
+    id: number;
+    title: string;
+    artist?: {
+        id: number;
+        name: string;
+    };
+    label?: {
+        id: number;
+        name: string;
+    } | null;
+    release_date?: string | null;
+    tracks?: Track[];
+    [key: string]: unknown;
+}
+interface Genre {
+    id: number;
+    name: string;
+    subgenres?: {
+        id: number;
+        name: string;
+    }[];
+    [key: string]: unknown;
+}
+/** A track's ID on an external platform, with a deep link. */
+interface PlatformLink {
+    source: string;
+    external_id: string;
+    url: string | null;
+}
+interface PlatformLinksResponse {
+    track_id: number;
+    title: string;
+    links: PlatformLink[];
+    [key: string]: unknown;
+}
+/** ISWC entries for a recording (one recording can carry several work codes). */
+interface IswcLookupResponse {
+    sonovault_id?: number;
+    isrc?: string;
+    iswcs?: {
+        iswc: string;
+        title: string | null;
+    }[];
+    [key: string]: unknown;
+}
+type ResolveInputType = "track_name" | "isrc" | "sonovault_id" | "spotify_id" | "applemusic_id" | "tidal_id" | "beatport_id" | "discogs_id" | "musicbrainz_id";
+interface ResolveRequest {
+    input_type: ResolveInputType;
+    /** 1–100 entries. `{ artist, title }` objects for `track_name`, strings otherwise. */
+    items: (string | {
+        artist: string;
+        title: string;
+    })[];
+}
+interface ResolveResult {
+    input: string | {
+        artist: string;
+        title: string;
+    };
+    status: "matched" | "not_found" | "skipped_no_credits";
+    track: Track | null;
+    links: PlatformLink[];
+}
+interface ResolveResponse {
+    results: ResolveResult[];
+    partial: boolean;
+    processed: number;
+    credits_used: number;
+    credits_remaining: number;
+    message: string | null;
+}
+interface IdentifyRequest {
+    /** 50–50,000 integers from `fpcalc -raw` (Chromaprint). */
+    fingerprint: number[];
+    /** Clip duration in seconds. */
+    fingerprint_duration?: number;
+    /** Max results to return, 1–25. */
+    top_n?: number;
+}
+interface IdentifyResult {
+    id: number;
+    title: string;
+    artists: TrackArtist[];
+    /** 0–1; higher means a more certain match. */
+    confidence: number;
+}
+interface IdentifyResponse {
+    matched: boolean;
+    results: IdentifyResult[];
+    credits_charged: number;
+    [key: string]: unknown;
+}
+interface Stream {
+    id: string;
+    url?: string;
+    name?: string;
+    status?: string;
+    [key: string]: unknown;
+}
+interface Webhook {
+    id: string;
+    url: string;
+    event_types?: string[];
+    /** Returned once, on creation — store it to verify delivery signatures. */
+    secret?: string;
+    [key: string]: unknown;
+}
+interface SonoVaultOptions {
+    /** Your API key — get a free one at https://sonovault.now (1,000 requests/month). */
+    apiKey: string;
+    /** Override the API base URL. Defaults to https://api.sonovault.now. */
+    baseUrl?: string;
+    /** Retries on 429/5xx responses. Default 2; set 0 to disable. */
+    maxRetries?: number;
+    /** Custom fetch implementation (for testing or polyfills). */
+    fetch?: typeof globalThis.fetch;
+}
+declare class SonoVault {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(options: SonoVaultOptions);
+    private request;
+    readonly tracks: {
+        /** Search by artist + title (both required — there is no free-text query). */
+        search: (params: {
+            artist: string;
+            title: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Track>>;
+        /** Fetch a track by its SonoVault ID. */
+        get: (id: number) => Promise<Track>;
+        /** Look up a track by any of its ISRCs. */
+        byIsrc: (isrc: string) => Promise<Track>;
+        /** Recording → composition: the ISWC(s) behind a recording, by ISRC or track ID. */
+        iswc: (params: {
+            isrc?: string;
+            id?: number;
+        }) => Promise<IswcLookupResponse>;
+        /** Composition → recordings: every recording of a work, by ISWC. */
+        byIswc: (iswc: string, params?: {
+            limit?: number;
+        }) => Promise<{
+            iswc: string;
+            results: Track[];
+        }>;
+        /** Cross-platform IDs + deep links for a track, resolved from any platform's ID or an ISRC. */
+        links: (params: {
+            id?: number;
+            isrc?: string;
+            spotify_id?: string;
+            beatport_id?: string;
+            discogs_id?: string;
+            musicbrainz_id?: string;
+            applemusic_id?: string;
+            tidal_id?: string;
+            youtube_id?: string;
+        }) => Promise<PlatformLinksResponse>;
+        /** Resolve up to 100 track names, ISRCs, or platform IDs in one request. */
+        resolve: (body: ResolveRequest) => Promise<ResolveResponse>;
+        /** Identify a track from a Chromaprint fingerprint (`fpcalc -raw`). Paid tiers. */
+        identify: (body: IdentifyRequest) => Promise<IdentifyResponse>;
+        /**
+         * Identify a track from raw audio bytes (any ffmpeg-decodable format).
+         * Send the whole track when you can — the matching section is often mid-track.
+         * Paid tiers; costs 10 + ceil(MB) credits.
+         */
+        identifyAudio: (audio: ArrayBuffer | Uint8Array | Blob, params?: {
+            length?: number;
+            top_n?: number;
+        }) => Promise<IdentifyResponse>;
+        /** Browse the catalog by label, artist, genre, or year. Paid tiers. */
+        browse: (params: {
+            labelId?: number;
+            artistId?: number;
+            genre?: string;
+            genreId?: number;
+            year?: number;
+            randomize?: boolean;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Track>>;
+    };
+    readonly artists: {
+        search: (params: {
+            name: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Artist>>;
+        get: (id: number) => Promise<Artist>;
+        releases: (id: number, params?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Release>>;
+    };
+    readonly labels: {
+        search: (params: {
+            name: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Label>>;
+        get: (id: number) => Promise<Label>;
+        releases: (id: number, params?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Release>>;
+        artists: (id: number, params?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Artist>>;
+    };
+    readonly releases: {
+        search: (params: {
+            title: string;
+            artist?: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Release>>;
+        get: (id: number) => Promise<Release>;
+        /** Newly released albums (GET /v1/releases/new). Paid tiers. */
+        latest: (params?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Release>>;
+    };
+    readonly genres: {
+        /** The canonical genre/subgenre hierarchy. */
+        list: () => Promise<{
+            genres: Genre[];
+        }>;
+    };
+    readonly suggestions: {
+        /** Suggest a metadata correction for a track. Paid tiers. */
+        submit: (trackId: number, body: Record<string, unknown>) => Promise<Record<string, unknown>>;
+        list: (params?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Record<string, unknown>>>;
+    };
+    readonly streams: {
+        /** Start monitoring an Icecast/Shoutcast stream. Paid tiers. */
+        create: (body: Record<string, unknown>) => Promise<Stream>;
+        list: () => Promise<{
+            streams: Stream[];
+        }>;
+        get: (id: string) => Promise<Stream>;
+        update: (id: string, body: Record<string, unknown>) => Promise<Stream>;
+        history: (id: string, params?: {
+            since?: string;
+        }) => Promise<Record<string, unknown>>;
+        report: (params: {
+            from: string;
+            until: string;
+            stream_id?: string;
+        }) => Promise<Record<string, unknown>>;
+        /** What's playing right now across your monitored streams. */
+        live: () => Promise<Record<string, unknown>>;
+        /** Stop monitoring a stream. */
+        stop: (id: string) => Promise<void>;
+    };
+    readonly webhooks: {
+        /** Register an endpoint for stream events. The response includes `secret` once — store it. */
+        create: (body: {
+            url: string;
+            event_types?: string[];
+            description?: string;
+        }) => Promise<Webhook>;
+        list: () => Promise<{
+            webhooks: Webhook[];
+        }>;
+        update: (id: string, body: Record<string, unknown>) => Promise<Webhook>;
+        delete: (id: string) => Promise<void>;
+        test: (id: string) => Promise<Record<string, unknown>>;
+        deliveries: (id: string) => Promise<Record<string, unknown>>;
+    };
+}
+/** Error thrown for any non-2xx API response. */
+declare class SonoVaultError extends Error {
+    /** HTTP status code, or 0 for network errors. */
+    readonly status: number;
+    /** Parsed JSON error body, when the API returned one. */
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+    /** Missing or invalid API key. */
+    get isAuthError(): boolean;
+    /** The endpoint needs a paid tier (or an admin key). */
+    get isForbidden(): boolean;
+    /** Rate limit or monthly credit quota hit. */
+    get isRateLimited(): boolean;
+}
+export { type Artist, type Genre, type IdentifyRequest, 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 Track, type TrackArtist, type TrackRelease, type Webhook };

package/dist/index.js ADDED Viewed

@@ -0,0 +1,158 @@
+// src/error.ts
+var SonoVaultError = class extends Error {
+  constructor(message, status, body = void 0) {
+    super(message);
+    this.name = "SonoVaultError";
+    this.status = status;
+    this.body = body;
+  }
+  /** Missing or invalid API key. */
+  get isAuthError() {
+    return this.status === 401;
+  }
+  /** The endpoint needs a paid tier (or an admin key). */
+  get isForbidden() {
+    return this.status === 403;
+  }
+  /** Rate limit or monthly credit quota hit. */
+  get isRateLimited() {
+    return this.status === 429;
+  }
+};
+// src/client.ts
+var SonoVault = class {
+  constructor(options) {
+    this.tracks = {
+      /** Search by artist + title (both required — there is no free-text query). */
+      search: (params) => this.request("/v1/tracks/search", { query: params }),
+      /** Fetch a track by its SonoVault ID. */
+      get: (id) => this.request(`/v1/tracks/${id}`),
+      /** Look up a track by any of its ISRCs. */
+      byIsrc: (isrc) => this.request(`/v1/tracks/isrc/${encodeURIComponent(isrc)}`),
+      /** Recording → composition: the ISWC(s) behind a recording, by ISRC or track ID. */
+      iswc: (params) => this.request("/v1/tracks/iswc", { query: params }),
+      /** Composition → recordings: every recording of a work, by ISWC. */
+      byIswc: (iswc, params = {}) => this.request(
+        `/v1/tracks/iswc/${encodeURIComponent(iswc)}`,
+        { query: params }
+      ),
+      /** Cross-platform IDs + deep links for a track, resolved from any platform's ID or an ISRC. */
+      links: (params) => this.request("/v1/tracks/links", { query: params }),
+      /** Resolve up to 100 track names, ISRCs, or platform IDs in one request. */
+      resolve: (body) => this.request("/v1/tracks/resolve", { method: "POST", json: body }),
+      /** Identify a track from a Chromaprint fingerprint (`fpcalc -raw`). Paid tiers. */
+      identify: (body) => this.request("/v1/tracks/identify", { method: "POST", json: body }),
+      /**
+       * Identify a track from raw audio bytes (any ffmpeg-decodable format).
+       * Send the whole track when you can — the matching section is often mid-track.
+       * Paid tiers; costs 10 + ceil(MB) credits.
+       */
+      identifyAudio: (audio, params = {}) => this.request("/v1/tracks/identify", {
+        method: "POST",
+        query: params,
+        raw: { body: audio, contentType: "application/octet-stream" }
+      }),
+      /** Browse the catalog by label, artist, genre, or year. Paid tiers. */
+      browse: (params) => this.request("/v1/tracks/browse", { query: params })
+    };
+    this.artists = {
+      search: (params) => this.request("/v1/artists/search", { query: params }),
+      get: (id) => this.request(`/v1/artists/${id}`),
+      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}`),
+      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}`),
+      /** Newly released albums (GET /v1/releases/new). Paid tiers. */
+      latest: (params = {}) => this.request("/v1/releases/new", { query: params })
+    };
+    this.genres = {
+      /** The canonical genre/subgenre hierarchy. */
+      list: () => this.request("/v1/genres")
+    };
+    this.suggestions = {
+      /** Suggest a metadata correction for a track. Paid tiers. */
+      submit: (trackId, body) => this.request(`/v1/tracks/${trackId}/suggestions`, {
+        method: "POST",
+        json: body
+      }),
+      list: (params = {}) => this.request("/v1/suggestions", { query: params })
+    };
+    this.streams = {
+      /** Start monitoring an Icecast/Shoutcast stream. Paid tiers. */
+      create: (body) => this.request("/v1/streams", { method: "POST", json: body }),
+      list: () => this.request("/v1/streams"),
+      get: (id) => this.request(`/v1/streams/${id}`),
+      update: (id, body) => this.request(`/v1/streams/${id}`, { method: "PATCH", json: body }),
+      history: (id, params = {}) => this.request(`/v1/streams/${id}/history`, { query: params }),
+      report: (params) => this.request("/v1/streams/report", { query: params }),
+      /** What's playing right now across your monitored streams. */
+      live: () => this.request("/v1/streams/live"),
+      /** Stop monitoring a stream. */
+      stop: (id) => this.request(`/v1/streams/${id}`, { method: "DELETE" })
+    };
+    this.webhooks = {
+      /** Register an endpoint for stream events. The response includes `secret` once — store it. */
+      create: (body) => this.request("/v1/webhooks", { method: "POST", json: body }),
+      list: () => this.request("/v1/webhooks"),
+      update: (id, body) => this.request(`/v1/webhooks/${id}`, { method: "PATCH", json: body }),
+      delete: (id) => this.request(`/v1/webhooks/${id}`, { method: "DELETE" }),
+      test: (id) => this.request(`/v1/webhooks/${id}/test`, { method: "POST" }),
+      deliveries: (id) => this.request(`/v1/webhooks/${id}/deliveries`)
+    };
+    if (!options?.apiKey) throw new Error("SonoVault: apiKey is required");
+    this.apiKey = options.apiKey;
+    this.baseUrl = (options.baseUrl ?? "https://api.sonovault.now").replace(/\/$/, "");
+    this.maxRetries = options.maxRetries ?? 2;
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+  }
+  async request(path, opts = {}) {
+    const url = new URL(this.baseUrl + path);
+    for (const [key, value] of Object.entries(opts.query ?? {})) {
+      if (value !== void 0) url.searchParams.set(key, String(value));
+    }
+    const headers = { "x-api-key": this.apiKey };
+    let body;
+    if (opts.json !== void 0) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(opts.json);
+    } else if (opts.raw) {
+      headers["Content-Type"] = opts.raw.contentType;
+      body = opts.raw.body;
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      let res;
+      try {
+        res = await this.fetchImpl(url, { method: opts.method ?? "GET", headers, body });
+      } catch (err) {
+        lastError = new SonoVaultError(`Network error: ${err.message}`, 0);
+        continue;
+      }
+      if (res.ok) {
+        if (res.status === 204) return void 0;
+        return await res.json();
+      }
+      const errBody = await res.json().catch(() => void 0);
+      const message = errBody?.error ?? errBody?.message ?? `HTTP ${res.status}`;
+      lastError = new SonoVaultError(message, res.status, errBody);
+      const retryAfter = res.headers.get("retry-after");
+      const retryable = res.status >= 500 || res.status === 429 && retryAfter !== null;
+      if (!retryable || attempt === this.maxRetries) throw lastError;
+      const delayMs = retryAfter ? Number(retryAfter) * 1e3 : 500 * 2 ** attempt;
+      await new Promise((r) => setTimeout(r, delayMs));
+    }
+    throw lastError ?? new SonoVaultError("Request failed", 0);
+  }
+};
+export {
+  SonoVault,
+  SonoVaultError
+};

package/package.json ADDED Viewed

@@ -0,0 +1,55 @@
+{
+  "name": "sonovault",
+  "version": "1.0.0",
+  "description": "TypeScript/Node client for the SonoVault music metadata API — ISRC, ISWC, genre, labels, release dates, and cross-platform IDs for 90M+ tracks.",
+  "keywords": [
+    "music",
+    "metadata",
+    "isrc",
+    "iswc",
+    "music-api",
+    "spotify",
+    "apple-music",
+    "tidal",
+    "beatport",
+    "discogs",
+    "musicbrainz",
+    "audio-recognition"
+  ],
+  "homepage": "https://sonovault.now",
+  "bugs": "https://github.com/rekordcloud/sonovault-js/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rekordcloud/sonovault-js.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.0.0"
+  }
+}