sonovault 1.0.0 → 1.2.0

package/README.md

@@ -3,11 +3,11 @@
 [![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.
+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.
 
-- **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).
+- **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
 
@@ -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
@@ -32,16 +34,16 @@ 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/…
+  console.log(link.source, link.url); // spotify https://open.spotify.com/track/...
 }
 
-// Recording → composition (ISWC), for royalty/publishing workflows
+// Recording to composition (ISWC), for royalty and 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):
+Resolve up to 100 lines in one request: track names, ISRCs, or platform IDs. Useful for enriching play logs and library exports.
 
 ```ts
 const batch = await sv.tracks.resolve({
@@ -59,13 +61,23 @@ for (const row of batch.results) {
 
 ## Pagination
 
-List endpoints return `{ results, next_cursor }` — pass the cursor back to get the next page (`next_cursor` is `null` on the last page):
+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 {
   const page = await sv.artists.releases(42, { cursor });
-  // …use page.results
+  // ...use page.results
   cursor = page.next_cursor ?? undefined;
 } while (cursor);
 ```
@@ -86,7 +98,12 @@ try {
 }
 ```
 
-Rate-limited responses that carry a `Retry-After` header are retried automatically (twice by default; configure with `maxRetries`).
+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
 
@@ -99,15 +116,15 @@ Rate-limited responses that carry a `Retry-After` header are retried automatical
 | `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` |
+| `sv.webhooks` | `create`, `list`, `get`, `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.
+Some endpoints (audio identify, browse, 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
+- [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) and [ISWC lookup](https://sonovault.now/iswc-lookup). Browser tools built on the same API.
 
 ## License
 

package/dist/index.cjs

@@ -21,7 +21,9 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   SonoVault: () => SonoVault,
-  SonoVaultError: () => SonoVaultError
+  SonoVaultError: () => SonoVaultError,
+  paginate: () => paginate,
+  verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -47,6 +49,9 @@ var SonoVaultError = class extends Error {
   }
 };
 
+// src/version.ts
+var VERSION = "1.2.0";
+
 // src/client.ts
 var SonoVault = class {
   constructor(options) {
@@ -120,8 +125,17 @@ var SonoVault = class {
       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"),
+      /**
+       * Real-time play events for your monitored streams, as an async iterator
+       * over Server-Sent Events. Runs until you `break` or abort the signal.
+       *
+       * ```ts
+       * for await (const event of sv.streams.live()) {
+       *   console.log(event.data.track?.title);
+       * }
+       * ```
+       */
+      live: (options = {}) => this.sse("/v1/streams/live", options.signal),
       /** Stop monitoring a stream. */
       stop: (id) => this.request(`/v1/streams/${id}`, { method: "DELETE" })
     };
@@ -129,6 +143,7 @@ var SonoVault = class {
       /** 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"),
+      get: (id) => this.request(`/v1/webhooks/${id}`),
       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" }),
@@ -138,6 +153,7 @@ var SonoVault = class {
     this.apiKey = options.apiKey;
     this.baseUrl = (options.baseUrl ?? "https://api.sonovault.now").replace(/\/$/, "");
     this.maxRetries = options.maxRetries ?? 2;
+    this.timeoutMs = options.timeoutMs ?? 3e4;
     this.fetchImpl = options.fetch ?? globalThis.fetch;
   }
   async request(path, opts = {}) {
@@ -145,7 +161,10 @@ var SonoVault = class {
     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 };
+    const headers = {
+      "x-api-key": this.apiKey,
+      "User-Agent": `sonovault-js/${VERSION}`
+    };
     let body;
     if (opts.json !== void 0) {
       headers["Content-Type"] = "application/json";
@@ -158,9 +177,15 @@ var SonoVault = class {
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
       let res;
       try {
-        res = await this.fetchImpl(url, { method: opts.method ?? "GET", headers, body });
+        const signal = this.timeoutMs > 0 ? AbortSignal.timeout(this.timeoutMs) : void 0;
+        res = await this.fetchImpl(url, { method: opts.method ?? "GET", headers, body, signal });
       } catch (err) {
-        lastError = new SonoVaultError(`Network error: ${err.message}`, 0);
+        const e = err;
+        const timedOut = e.name === "TimeoutError" || e.name === "AbortError";
+        lastError = new SonoVaultError(
+          timedOut ? `Request timed out after ${this.timeoutMs}ms` : `Network error: ${e.message}`,
+          0
+        );
         continue;
       }
       if (res.ok) {
@@ -178,9 +203,94 @@ var SonoVault = class {
     }
     throw lastError ?? new SonoVaultError("Request failed", 0);
   }
+  /** Connect to an SSE endpoint and yield one parsed JSON event per `data:` frame. */
+  async *sse(path, signal) {
+    const url = new URL(this.baseUrl + path);
+    const res = await this.fetchImpl(url, {
+      headers: {
+        "x-api-key": this.apiKey,
+        "User-Agent": `sonovault-js/${VERSION}`,
+        Accept: "text/event-stream"
+      },
+      signal
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => void 0);
+      const message = body?.error ?? `HTTP ${res.status}`;
+      throw new SonoVaultError(message, res.status, body);
+    }
+    if (!res.body) throw new SonoVaultError("SSE response has no body", res.status);
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let dataLines = [];
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        let newline;
+        while ((newline = buffer.indexOf("\n")) !== -1) {
+          const line = buffer.slice(0, newline).replace(/\r$/, "");
+          buffer = buffer.slice(newline + 1);
+          if (line === "") {
+            if (dataLines.length > 0) {
+              const data = dataLines.join("\n");
+              dataLines = [];
+              try {
+                yield JSON.parse(data);
+              } catch {
+              }
+            }
+          } else if (line.startsWith("data:")) {
+            dataLines.push(line.slice(5).replace(/^ /, ""));
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+      res.body.cancel().catch(() => {
+      });
+    }
+  }
 };
+
+// src/webhooks.ts
+var import_node_crypto = require("crypto");
+function verifyWebhookSignature(options) {
+  const { secret, header, payload, toleranceSeconds = 300 } = options;
+  if (!secret || !header) return false;
+  const parts = {};
+  for (const kv of header.split(",")) {
+    const i = kv.indexOf("=");
+    if (i > 0) parts[kv.slice(0, i).trim()] = kv.slice(i + 1).trim();
+  }
+  const t = Number(parts.t);
+  const v1 = parts.v1;
+  if (!Number.isFinite(t) || !v1) return false;
+  if (toleranceSeconds > 0 && Math.abs(Math.floor(Date.now() / 1e3) - t) > toleranceSeconds) {
+    return false;
+  }
+  const body = typeof payload === "string" ? payload : payload.toString("utf8");
+  const expected = (0, import_node_crypto.createHmac)("sha256", secret).update(`${t}.${body}`).digest("hex");
+  const a = Buffer.from(v1);
+  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
+  SonoVaultError,
+  paginate,
+  verifyWebhookSignature
 });

package/dist/index.d.cts

@@ -152,10 +152,28 @@ interface Webhook {
     id: string;
     url: string;
     event_types?: string[];
-    /** Returned once, on creation — store it to verify delivery signatures. */
+    /** Returned once, on creation. Store it to verify delivery signatures. */
     secret?: string;
     [key: string]: unknown;
 }
+/**
+ * An event from the live SSE feed or a webhook delivery.
+ * Types: `stream.play.started`, `stream.offline`, `stream.online`.
+ */
+interface StreamEvent {
+    id: string;
+    type: string;
+    created: number | string;
+    data: {
+        stream_id: string;
+        started_at?: string;
+        at?: string;
+        reason?: string;
+        track?: Track;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
 
 interface SonoVaultOptions {
     /** Your API key — get a free one at https://sonovault.now (1,000 requests/month). */
@@ -164,6 +182,11 @@ interface SonoVaultOptions {
     baseUrl?: string;
     /** Retries on 429/5xx responses. Default 2; set 0 to disable. */
     maxRetries?: number;
+    /**
+     * Per-request timeout in milliseconds. Default 30000; set 0 to disable.
+     * Does not apply to `streams.live()`, which stays open indefinitely.
+     */
+    timeoutMs?: number;
     /** Custom fetch implementation (for testing or polyfills). */
     fetch?: typeof globalThis.fetch;
 }
@@ -171,9 +194,12 @@ declare class SonoVault {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly maxRetries;
+    private readonly timeoutMs;
     private readonly fetchImpl;
     constructor(options: SonoVaultOptions);
     private request;
+    /** Connect to an SSE endpoint and yield one parsed JSON event per `data:` frame. */
+    private sse;
     readonly tracks: {
         /** Search by artist + title (both required — there is no free-text query). */
         search: (params: {
@@ -307,8 +333,19 @@ declare class SonoVault {
             until: string;
             stream_id?: string;
         }) => Promise<Record<string, unknown>>;
-        /** What's playing right now across your monitored streams. */
-        live: () => Promise<Record<string, unknown>>;
+        /**
+         * Real-time play events for your monitored streams, as an async iterator
+         * over Server-Sent Events. Runs until you `break` or abort the signal.
+         *
+         * ```ts
+         * for await (const event of sv.streams.live()) {
+         *   console.log(event.data.track?.title);
+         * }
+         * ```
+         */
+        live: (options?: {
+            signal?: AbortSignal;
+        }) => AsyncGenerator<StreamEvent, any, any>;
         /** Stop monitoring a stream. */
         stop: (id: string) => Promise<void>;
     };
@@ -322,6 +359,7 @@ declare class SonoVault {
         list: () => Promise<{
             webhooks: Webhook[];
         }>;
+        get: (id: string) => Promise<Webhook>;
         update: (id: string, body: Record<string, unknown>) => Promise<Webhook>;
         delete: (id: string) => Promise<void>;
         test: (id: string) => Promise<Record<string, unknown>>;
@@ -344,4 +382,45 @@ declare class SonoVaultError extends Error {
     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 };
+/**
+ * Verify a `SonoVault-Signature` webhook header against the raw request body.
+ *
+ * The header format is `t=<unix>,v1=<hex>` where
+ * `v1 = HMAC-SHA256(secret, "<t>.<rawBody>")`. Use the `secret` returned once
+ * by `sv.webhooks.create()`. Compute over the RAW body bytes, before any JSON
+ * parsing. Constant-time compare. Rejects timestamps outside
+ * `toleranceSeconds` (default 300; pass 0 to disable the age check).
+ *
+ * ```ts
+ * app.post("/webhooks/sonovault", express.raw({ type: "application/json" }), (req, res) => {
+ *   const ok = verifyWebhookSignature({
+ *     secret: process.env.SONOVAULT_WEBHOOK_SECRET!,
+ *     header: req.header("SonoVault-Signature") ?? "",
+ *     payload: req.body,
+ *   });
+ *   if (!ok) return res.status(400).end();
+ *   res.status(200).end();
+ * });
+ * ```
+ */
+declare function verifyWebhookSignature(options: {
+    secret: string;
+    header: string;
+    payload: string | Buffer;
+    toleranceSeconds?: number;
+}): boolean;
+
+/**
+ * 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

@@ -152,10 +152,28 @@ interface Webhook {
     id: string;
     url: string;
     event_types?: string[];
-    /** Returned once, on creation — store it to verify delivery signatures. */
+    /** Returned once, on creation. Store it to verify delivery signatures. */
     secret?: string;
     [key: string]: unknown;
 }
+/**
+ * An event from the live SSE feed or a webhook delivery.
+ * Types: `stream.play.started`, `stream.offline`, `stream.online`.
+ */
+interface StreamEvent {
+    id: string;
+    type: string;
+    created: number | string;
+    data: {
+        stream_id: string;
+        started_at?: string;
+        at?: string;
+        reason?: string;
+        track?: Track;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
 
 interface SonoVaultOptions {
     /** Your API key — get a free one at https://sonovault.now (1,000 requests/month). */
@@ -164,6 +182,11 @@ interface SonoVaultOptions {
     baseUrl?: string;
     /** Retries on 429/5xx responses. Default 2; set 0 to disable. */
     maxRetries?: number;
+    /**
+     * Per-request timeout in milliseconds. Default 30000; set 0 to disable.
+     * Does not apply to `streams.live()`, which stays open indefinitely.
+     */
+    timeoutMs?: number;
     /** Custom fetch implementation (for testing or polyfills). */
     fetch?: typeof globalThis.fetch;
 }
@@ -171,9 +194,12 @@ declare class SonoVault {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly maxRetries;
+    private readonly timeoutMs;
     private readonly fetchImpl;
     constructor(options: SonoVaultOptions);
     private request;
+    /** Connect to an SSE endpoint and yield one parsed JSON event per `data:` frame. */
+    private sse;
     readonly tracks: {
         /** Search by artist + title (both required — there is no free-text query). */
         search: (params: {
@@ -307,8 +333,19 @@ declare class SonoVault {
             until: string;
             stream_id?: string;
         }) => Promise<Record<string, unknown>>;
-        /** What's playing right now across your monitored streams. */
-        live: () => Promise<Record<string, unknown>>;
+        /**
+         * Real-time play events for your monitored streams, as an async iterator
+         * over Server-Sent Events. Runs until you `break` or abort the signal.
+         *
+         * ```ts
+         * for await (const event of sv.streams.live()) {
+         *   console.log(event.data.track?.title);
+         * }
+         * ```
+         */
+        live: (options?: {
+            signal?: AbortSignal;
+        }) => AsyncGenerator<StreamEvent, any, any>;
         /** Stop monitoring a stream. */
         stop: (id: string) => Promise<void>;
     };
@@ -322,6 +359,7 @@ declare class SonoVault {
         list: () => Promise<{
             webhooks: Webhook[];
         }>;
+        get: (id: string) => Promise<Webhook>;
         update: (id: string, body: Record<string, unknown>) => Promise<Webhook>;
         delete: (id: string) => Promise<void>;
         test: (id: string) => Promise<Record<string, unknown>>;
@@ -344,4 +382,45 @@ declare class SonoVaultError extends Error {
     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 };
+/**
+ * Verify a `SonoVault-Signature` webhook header against the raw request body.
+ *
+ * The header format is `t=<unix>,v1=<hex>` where
+ * `v1 = HMAC-SHA256(secret, "<t>.<rawBody>")`. Use the `secret` returned once
+ * by `sv.webhooks.create()`. Compute over the RAW body bytes, before any JSON
+ * parsing. Constant-time compare. Rejects timestamps outside
+ * `toleranceSeconds` (default 300; pass 0 to disable the age check).
+ *
+ * ```ts
+ * app.post("/webhooks/sonovault", express.raw({ type: "application/json" }), (req, res) => {
+ *   const ok = verifyWebhookSignature({
+ *     secret: process.env.SONOVAULT_WEBHOOK_SECRET!,
+ *     header: req.header("SonoVault-Signature") ?? "",
+ *     payload: req.body,
+ *   });
+ *   if (!ok) return res.status(400).end();
+ *   res.status(200).end();
+ * });
+ * ```
+ */
+declare function verifyWebhookSignature(options: {
+    secret: string;
+    header: string;
+    payload: string | Buffer;
+    toleranceSeconds?: number;
+}): boolean;
+
+/**
+ * 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

@@ -20,6 +20,9 @@ var SonoVaultError = class extends Error {
   }
 };
 
+// src/version.ts
+var VERSION = "1.2.0";
+
 // src/client.ts
 var SonoVault = class {
   constructor(options) {
@@ -93,8 +96,17 @@ var SonoVault = class {
       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"),
+      /**
+       * Real-time play events for your monitored streams, as an async iterator
+       * over Server-Sent Events. Runs until you `break` or abort the signal.
+       *
+       * ```ts
+       * for await (const event of sv.streams.live()) {
+       *   console.log(event.data.track?.title);
+       * }
+       * ```
+       */
+      live: (options = {}) => this.sse("/v1/streams/live", options.signal),
       /** Stop monitoring a stream. */
       stop: (id) => this.request(`/v1/streams/${id}`, { method: "DELETE" })
     };
@@ -102,6 +114,7 @@ var SonoVault = class {
       /** 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"),
+      get: (id) => this.request(`/v1/webhooks/${id}`),
       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" }),
@@ -111,6 +124,7 @@ var SonoVault = class {
     this.apiKey = options.apiKey;
     this.baseUrl = (options.baseUrl ?? "https://api.sonovault.now").replace(/\/$/, "");
     this.maxRetries = options.maxRetries ?? 2;
+    this.timeoutMs = options.timeoutMs ?? 3e4;
     this.fetchImpl = options.fetch ?? globalThis.fetch;
   }
   async request(path, opts = {}) {
@@ -118,7 +132,10 @@ var SonoVault = class {
     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 };
+    const headers = {
+      "x-api-key": this.apiKey,
+      "User-Agent": `sonovault-js/${VERSION}`
+    };
     let body;
     if (opts.json !== void 0) {
       headers["Content-Type"] = "application/json";
@@ -131,9 +148,15 @@ var SonoVault = class {
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
       let res;
       try {
-        res = await this.fetchImpl(url, { method: opts.method ?? "GET", headers, body });
+        const signal = this.timeoutMs > 0 ? AbortSignal.timeout(this.timeoutMs) : void 0;
+        res = await this.fetchImpl(url, { method: opts.method ?? "GET", headers, body, signal });
       } catch (err) {
-        lastError = new SonoVaultError(`Network error: ${err.message}`, 0);
+        const e = err;
+        const timedOut = e.name === "TimeoutError" || e.name === "AbortError";
+        lastError = new SonoVaultError(
+          timedOut ? `Request timed out after ${this.timeoutMs}ms` : `Network error: ${e.message}`,
+          0
+        );
         continue;
       }
       if (res.ok) {
@@ -151,8 +174,93 @@ var SonoVault = class {
     }
     throw lastError ?? new SonoVaultError("Request failed", 0);
   }
+  /** Connect to an SSE endpoint and yield one parsed JSON event per `data:` frame. */
+  async *sse(path, signal) {
+    const url = new URL(this.baseUrl + path);
+    const res = await this.fetchImpl(url, {
+      headers: {
+        "x-api-key": this.apiKey,
+        "User-Agent": `sonovault-js/${VERSION}`,
+        Accept: "text/event-stream"
+      },
+      signal
+    });
+    if (!res.ok) {
+      const body = await res.json().catch(() => void 0);
+      const message = body?.error ?? `HTTP ${res.status}`;
+      throw new SonoVaultError(message, res.status, body);
+    }
+    if (!res.body) throw new SonoVaultError("SSE response has no body", res.status);
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let dataLines = [];
+    try {
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        let newline;
+        while ((newline = buffer.indexOf("\n")) !== -1) {
+          const line = buffer.slice(0, newline).replace(/\r$/, "");
+          buffer = buffer.slice(newline + 1);
+          if (line === "") {
+            if (dataLines.length > 0) {
+              const data = dataLines.join("\n");
+              dataLines = [];
+              try {
+                yield JSON.parse(data);
+              } catch {
+              }
+            }
+          } else if (line.startsWith("data:")) {
+            dataLines.push(line.slice(5).replace(/^ /, ""));
+          }
+        }
+      }
+    } finally {
+      reader.releaseLock();
+      res.body.cancel().catch(() => {
+      });
+    }
+  }
 };
+
+// src/webhooks.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function verifyWebhookSignature(options) {
+  const { secret, header, payload, toleranceSeconds = 300 } = options;
+  if (!secret || !header) return false;
+  const parts = {};
+  for (const kv of header.split(",")) {
+    const i = kv.indexOf("=");
+    if (i > 0) parts[kv.slice(0, i).trim()] = kv.slice(i + 1).trim();
+  }
+  const t = Number(parts.t);
+  const v1 = parts.v1;
+  if (!Number.isFinite(t) || !v1) return false;
+  if (toleranceSeconds > 0 && Math.abs(Math.floor(Date.now() / 1e3) - t) > toleranceSeconds) {
+    return false;
+  }
+  const body = typeof payload === "string" ? payload : payload.toString("utf8");
+  const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
+  const a = Buffer.from(v1);
+  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
+  SonoVaultError,
+  paginate,
+  verifyWebhookSignature
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sonovault",
-  "version": "1.0.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",