sonovault 1.1.0 → 1.2.0

package/README.md

@@ -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,6 +100,11 @@ 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 |

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 = "1.2.0";
 
 // src/client.ts
 var SonoVault = class {
@@ -276,9 +277,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

@@ -410,4 +410,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 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, paginate, verifyWebhookSignature };

package/dist/index.d.ts

@@ -410,4 +410,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 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, 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 = "1.2.0";
 
 // src/client.ts
 var SonoVault = class {
@@ -248,8 +248,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,6 +1,6 @@
 {
   "name": "sonovault",
-  "version": "1.1.0",
+  "version": "1.2.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",