sonovault 1.1.0 → 2.0.0

package/README.md

@@ -3,7 +3,7 @@
 [![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. One call resolves them all.
+TypeScript/Node client for the **[SonoVault](https://sonovault.now)** music metadata API. 93M+ tracks with ISRC, ISWC, genre, record label, canonical release dates, and cross-platform IDs for Spotify, Apple Music, Tidal, Beatport, Discogs, and MusicBrainz. One call resolves them all.
 
 - **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).
@@ -17,6 +17,8 @@ npm install sonovault
 
 Node 18+ (uses the built-in `fetch`). ESM and CommonJS both supported.
 
+Use this library server-side. Shipping your API key in browser code exposes it to anyone who opens devtools. If a key leaks, rotate it in your [dashboard](https://sonovault.now/dashboard/keys).
+
 ## Quickstart
 
 ```ts
@@ -61,6 +63,16 @@ for (const row of batch.results) {
 
 List endpoints return `{ results, next_cursor }`. Pass the cursor back to get the next page. `next_cursor` is `null` on the last page.
 
+```ts
+import { paginate } from "sonovault";
+
+for await (const release of paginate((cursor) => sv.artists.releases(42, { cursor }))) {
+  console.log(release.title);
+}
+```
+
+Or walk the cursor yourself:
+
 ```ts
 let cursor: string | undefined;
 do {
@@ -88,11 +100,16 @@ try {
 
 Rate-limited responses that carry a `Retry-After` header are retried automatically. The default is 2 retries, configurable with `maxRetries`.
 
+
+## Examples
+
+Runnable scripts live in [`examples/`](examples/): find an ISRC, resolve cross-platform links, enrich a play log, follow live stream events over SSE, and verify webhook deliveries.
+
 ## API coverage
 
 | Namespace | Methods |
 |---|---|
-| `sv.tracks` | `search`, `get`, `byIsrc`, `iswc`, `byIswc`, `links`, `resolve`, `identify`, `identifyAudio`, `browse` |
+| `sv.tracks` | `search`, `get`, `byIsrc`, `iswc`, `byIswc`, `links`, `resolve`, `identifyAudio`, `browse` |
 | `sv.artists` | `search`, `get`, `releases` |
 | `sv.labels` | `search`, `get`, `releases`, `artists` |
 | `sv.releases` | `search`, `get`, `latest` |

package/dist/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   SonoVault: () => SonoVault,
   SonoVaultError: () => SonoVaultError,
+  paginate: () => paginate,
   verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(index_exports);
@@ -49,7 +50,7 @@ var SonoVaultError = class extends Error {
 };
 
 // src/version.ts
-var VERSION = "1.1.0";
+var VERSION = "2.0.0";
 
 // src/client.ts
 var SonoVault = class {
@@ -72,8 +73,6 @@ var SonoVault = class {
       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.
@@ -276,9 +275,20 @@ function verifyWebhookSignature(options) {
   const b = Buffer.from(expected);
   return a.length === b.length && (0, import_node_crypto.timingSafeEqual)(a, b);
 }
+
+// src/pagination.ts
+async function* paginate(fetchPage) {
+  let cursor;
+  do {
+    const page = await fetchPage(cursor);
+    for (const item of page.results) yield item;
+    cursor = page.next_cursor ?? void 0;
+  } while (cursor);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SonoVault,
   SonoVaultError,
+  paginate,
   verifyWebhookSignature
 });

package/dist/index.d.cts

@@ -120,14 +120,6 @@ interface ResolveResponse {
     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;
@@ -238,8 +230,6 @@ declare class SonoVault {
         }) => 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.
@@ -410,4 +400,17 @@ declare function verifyWebhookSignature(options: {
     toleranceSeconds?: number;
 }): 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 StreamEvent, type Track, type TrackArtist, type TrackRelease, type Webhook, verifyWebhookSignature };
+/**
+ * Iterate every item across all pages of a cursor-paginated endpoint.
+ *
+ * ```ts
+ * import { paginate } from "sonovault";
+ *
+ * for await (const release of paginate((cursor) => sv.artists.releases(42, { cursor }))) {
+ *   console.log(release.title);
+ * }
+ * ```
+ */
+declare function paginate<T>(fetchPage: (cursor: string | undefined) => Promise<Page<T>>): AsyncGenerator<T>;
+
+export { type Artist, type Genre, type IdentifyResponse, type IdentifyResult, type IswcLookupResponse, type Label, type Page, type PlatformLink, type PlatformLinksResponse, type Release, type ResolveInputType, type ResolveRequest, type ResolveResponse, type ResolveResult, SonoVault, SonoVaultError, type SonoVaultOptions, type Stream, type StreamEvent, type Track, type TrackArtist, type TrackRelease, type Webhook, paginate, verifyWebhookSignature };

package/dist/index.d.ts

@@ -120,14 +120,6 @@ interface ResolveResponse {
     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;
@@ -238,8 +230,6 @@ declare class SonoVault {
         }) => 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.
@@ -410,4 +400,17 @@ declare function verifyWebhookSignature(options: {
     toleranceSeconds?: number;
 }): 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 StreamEvent, type Track, type TrackArtist, type TrackRelease, type Webhook, verifyWebhookSignature };
+/**
+ * Iterate every item across all pages of a cursor-paginated endpoint.
+ *
+ * ```ts
+ * import { paginate } from "sonovault";
+ *
+ * for await (const release of paginate((cursor) => sv.artists.releases(42, { cursor }))) {
+ *   console.log(release.title);
+ * }
+ * ```
+ */
+declare function paginate<T>(fetchPage: (cursor: string | undefined) => Promise<Page<T>>): AsyncGenerator<T>;
+
+export { type Artist, type Genre, type IdentifyResponse, type IdentifyResult, type IswcLookupResponse, type Label, type Page, type PlatformLink, type PlatformLinksResponse, type Release, type ResolveInputType, type ResolveRequest, type ResolveResponse, type ResolveResult, SonoVault, SonoVaultError, type SonoVaultOptions, type Stream, type StreamEvent, type Track, type TrackArtist, type TrackRelease, type Webhook, paginate, verifyWebhookSignature };

package/dist/index.js

@@ -21,7 +21,7 @@ var SonoVaultError = class extends Error {
 };
 
 // src/version.ts
-var VERSION = "1.1.0";
+var VERSION = "2.0.0";
 
 // src/client.ts
 var SonoVault = class {
@@ -44,8 +44,6 @@ var SonoVault = class {
       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.
@@ -248,8 +246,19 @@ function verifyWebhookSignature(options) {
   const b = Buffer.from(expected);
   return a.length === b.length && timingSafeEqual(a, b);
 }
+
+// src/pagination.ts
+async function* paginate(fetchPage) {
+  let cursor;
+  do {
+    const page = await fetchPage(cursor);
+    for (const item of page.results) yield item;
+    cursor = page.next_cursor ?? void 0;
+  } while (cursor);
+}
 export {
   SonoVault,
   SonoVaultError,
+  paginate,
   verifyWebhookSignature
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sonovault",
-  "version": "1.1.0",
-  "description": "TypeScript/Node client for the SonoVault music metadata API — ISRC, ISWC, genre, labels, release dates, and cross-platform IDs for 90M+ tracks.",
+  "version": "2.0.0",
+  "description": "TypeScript/Node client for the SonoVault music metadata API — ISRC, ISWC, genre, labels, release dates, and cross-platform IDs for 93M+ tracks.",
   "keywords": [
     "music",
     "metadata",