sonovault 1.0.0__tar.gz

sonovault-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

sonovault-1.0.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+dist/
+build/
+.venv/
+.DS_Store

sonovault-1.0.0/LICENSE

@@ -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.

sonovault-1.0.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: sonovault
+Version: 1.0.0
+Summary: Python client for the SonoVault music metadata API — ISRC, ISWC, genre, labels, release dates, and cross-platform IDs for 90M+ tracks.
+Project-URL: Homepage, https://sonovault.now
+Project-URL: Documentation, https://sonovault.now/docs
+Project-URL: Repository, https://github.com/rekordcloud/sonovault-python
+Project-URL: Issues, https://github.com/rekordcloud/sonovault-python/issues
+Author: Rekordcloud B.V.
+License: MIT
+License-File: LICENSE
+Keywords: apple-music,audio-recognition,beatport,discogs,isrc,iswc,metadata,music,music-api,musicbrainz,spotify,tidal
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Sound/Audio
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.25
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# sonovault
+
+[![CI](https://github.com/rekordcloud/sonovault-python/actions/workflows/ci.yml/badge.svg)](https://github.com/rekordcloud/sonovault-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/sonovault)](https://pypi.org/project/sonovault/)
+
+Python 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
+pip install sonovault
+```
+
+Python 3.9+.
+
+## Quickstart
+
+```python
+from sonovault import SonoVault
+
+sv = SonoVault(api_key="YOUR_API_KEY")
+
+# Find a track's ISRC from artist + title
+page = sv.tracks.search(artist="Daft Punk", title="One More Time")
+track = page["results"][0]
+print(track["isrc"])   # "GBDUW0000053"
+print(track["genre"], track["releases"][0]["label"]["name"])
+
+# Resolve that ISRC to its ID on every platform
+links = sv.tracks.links(isrc=track["isrc"])
+for link in links["links"]:
+    print(link["source"], link["url"])  # spotify https://open.spotify.com/track/…
+
+# Recording → composition (ISWC), for royalty/publishing workflows
+work = sv.tracks.iswc(isrc=track["isrc"])
+```
+
+## Bulk resolve
+
+Resolve up to 100 lines — track names, ISRCs, or platform IDs — in one request (great for enriching play logs and library exports):
+
+```python
+batch = sv.tracks.resolve(
+    input_type="track_name",
+    items=[
+        {"artist": "Daft Punk", "title": "Harder, Better, Faster, Stronger"},
+        {"artist": "Daft Punk", "title": "Around the World"},
+    ],
+)
+for row in batch["results"]:
+    print(row["status"], row["track"] and row["track"]["isrc"])
+```
+
+## Pagination
+
+List endpoints return `{"results": [...], "next_cursor": ...}` — pass the cursor back for the next page (`next_cursor` is `None` on the last page):
+
+```python
+cursor = None
+while True:
+    page = sv.artists.releases(42, cursor=cursor)
+    # …use page["results"]
+    cursor = page.get("next_cursor")
+    if not cursor:
+        break
+```
+
+## Error handling
+
+Non-2xx responses raise `SonoVaultError`:
+
+```python
+from sonovault import SonoVaultError
+
+try:
+    sv.tracks.browse(genre="House")  # paid-tier endpoint
+except SonoVaultError as err:
+    print(err.status, err.is_forbidden, err)
+```
+
+Rate-limited responses that carry a `Retry-After` header are retried automatically (twice by default; configure with `max_retries`).
+
+## API coverage
+
+| Namespace | Methods |
+|---|---|
+| `sv.tracks` | `search`, `get`, `by_isrc`, `iswc`, `by_iswc`, `links`, `resolve`, `identify`, `identify_audio`, `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-js](https://github.com/rekordcloud/sonovault-js) — the TypeScript/Node 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

sonovault-1.0.0/README.md

@@ -0,0 +1,110 @@
+# sonovault
+
+[![CI](https://github.com/rekordcloud/sonovault-python/actions/workflows/ci.yml/badge.svg)](https://github.com/rekordcloud/sonovault-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/sonovault)](https://pypi.org/project/sonovault/)
+
+Python 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
+pip install sonovault
+```
+
+Python 3.9+.
+
+## Quickstart
+
+```python
+from sonovault import SonoVault
+
+sv = SonoVault(api_key="YOUR_API_KEY")
+
+# Find a track's ISRC from artist + title
+page = sv.tracks.search(artist="Daft Punk", title="One More Time")
+track = page["results"][0]
+print(track["isrc"])   # "GBDUW0000053"
+print(track["genre"], track["releases"][0]["label"]["name"])
+
+# Resolve that ISRC to its ID on every platform
+links = sv.tracks.links(isrc=track["isrc"])
+for link in links["links"]:
+    print(link["source"], link["url"])  # spotify https://open.spotify.com/track/…
+
+# Recording → composition (ISWC), for royalty/publishing workflows
+work = sv.tracks.iswc(isrc=track["isrc"])
+```
+
+## Bulk resolve
+
+Resolve up to 100 lines — track names, ISRCs, or platform IDs — in one request (great for enriching play logs and library exports):
+
+```python
+batch = sv.tracks.resolve(
+    input_type="track_name",
+    items=[
+        {"artist": "Daft Punk", "title": "Harder, Better, Faster, Stronger"},
+        {"artist": "Daft Punk", "title": "Around the World"},
+    ],
+)
+for row in batch["results"]:
+    print(row["status"], row["track"] and row["track"]["isrc"])
+```
+
+## Pagination
+
+List endpoints return `{"results": [...], "next_cursor": ...}` — pass the cursor back for the next page (`next_cursor` is `None` on the last page):
+
+```python
+cursor = None
+while True:
+    page = sv.artists.releases(42, cursor=cursor)
+    # …use page["results"]
+    cursor = page.get("next_cursor")
+    if not cursor:
+        break
+```
+
+## Error handling
+
+Non-2xx responses raise `SonoVaultError`:
+
+```python
+from sonovault import SonoVaultError
+
+try:
+    sv.tracks.browse(genre="House")  # paid-tier endpoint
+except SonoVaultError as err:
+    print(err.status, err.is_forbidden, err)
+```
+
+Rate-limited responses that carry a `Retry-After` header are retried automatically (twice by default; configure with `max_retries`).
+
+## API coverage
+
+| Namespace | Methods |
+|---|---|
+| `sv.tracks` | `search`, `get`, `by_isrc`, `iswc`, `by_iswc`, `links`, `resolve`, `identify`, `identify_audio`, `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-js](https://github.com/rekordcloud/sonovault-js) — the TypeScript/Node 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

sonovault-1.0.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sonovault"
+version = "1.0.0"
+description = "Python client for the SonoVault music metadata API — ISRC, ISWC, genre, labels, release dates, and cross-platform IDs for 90M+ tracks."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "Rekordcloud B.V." }]
+keywords = [
+  "music",
+  "metadata",
+  "isrc",
+  "iswc",
+  "music-api",
+  "spotify",
+  "apple-music",
+  "tidal",
+  "beatport",
+  "discogs",
+  "musicbrainz",
+  "audio-recognition",
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Multimedia :: Sound/Audio",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["requests>=2.25"]
+
+[project.urls]
+Homepage = "https://sonovault.now"
+Documentation = "https://sonovault.now/docs"
+Repository = "https://github.com/rekordcloud/sonovault-python"
+Issues = "https://github.com/rekordcloud/sonovault-python/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sonovault"]

sonovault-1.0.0/src/sonovault/__init__.py

@@ -0,0 +1,7 @@
+"""Python client for the SonoVault music metadata API — https://sonovault.now"""
+
+from .client import SonoVault
+from .errors import SonoVaultError
+
+__all__ = ["SonoVault", "SonoVaultError"]
+__version__ = "1.0.0"

sonovault-1.0.0/src/sonovault/client.py

@@ -0,0 +1,314 @@
+"""SonoVault API client.
+
+Usage:
+    from sonovault import SonoVault
+
+    sv = SonoVault(api_key="...")
+    page = sv.tracks.search(artist="Daft Punk", title="One More Time")
+    print(page["results"][0]["isrc"])
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Optional, Union
+
+import requests
+
+from .errors import SonoVaultError
+
+DEFAULT_BASE_URL = "https://api.sonovault.now"
+
+
+class SonoVault:
+    """Client for the SonoVault music metadata API (https://sonovault.now).
+
+    Args:
+        api_key: your API key — get a free one at https://sonovault.now
+            (1,000 requests/month, no credit card).
+        base_url: override the API base URL.
+        max_retries: retries on retryable 429/5xx responses. Default 2.
+        session: optional ``requests.Session`` (for pooling or testing).
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        max_retries: int = 2,
+        session: Optional[requests.Session] = None,
+    ):
+        if not api_key:
+            raise ValueError("SonoVault: api_key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._session = session or requests.Session()
+
+        self.tracks = _Tracks(self)
+        self.artists = _Artists(self)
+        self.labels = _Labels(self)
+        self.releases = _Releases(self)
+        self.genres = _Genres(self)
+        self.suggestions = _Suggestions(self)
+        self.streams = _Streams(self)
+        self.webhooks = _Webhooks(self)
+
+    # -- plumbing ---------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Any = None,
+        data: Optional[bytes] = None,
+        content_type: Optional[str] = None,
+    ) -> Any:
+        url = self._base_url + path
+        clean_params = {k: v for k, v in (params or {}).items() if v is not None}
+        headers = {"x-api-key": self._api_key}
+        if content_type:
+            headers["Content-Type"] = content_type
+
+        last_error: Optional[SonoVaultError] = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                res = self._session.request(
+                    method, url, params=clean_params, json=json, data=data,
+                    headers=headers, timeout=30,
+                )
+            except requests.RequestException as exc:
+                last_error = SonoVaultError(f"Network error: {exc}", 0)
+                continue
+
+            if res.ok:
+                if res.status_code == 204 or not res.content:
+                    return None
+                return res.json()
+
+            try:
+                body = res.json()
+            except ValueError:
+                body = None
+            message = None
+            if isinstance(body, dict):
+                message = body.get("error") or body.get("message")
+            last_error = SonoVaultError(message or f"HTTP {res.status_code}", res.status_code, body)
+
+            # Retry only transient failures. A 429 with Retry-After is a rate
+            # limit (retryable); a 429 without one is usually quota exhaustion.
+            retry_after = res.headers.get("Retry-After")
+            retryable = res.status_code >= 500 or (res.status_code == 429 and retry_after is not None)
+            if not retryable or attempt == self._max_retries:
+                raise last_error
+            time.sleep(float(retry_after) if retry_after else 0.5 * (2 ** attempt))
+
+        raise last_error or SonoVaultError("Request failed", 0)
+
+
+class _Namespace:
+    def __init__(self, client: SonoVault):
+        self._client = client
+
+
+class _Tracks(_Namespace):
+    def search(self, *, artist: str, title: str, limit: Optional[int] = None,
+               cursor: Optional[str] = None) -> Dict[str, Any]:
+        """Search by artist + title (both required — there is no free-text query)."""
+        return self._client._request("GET", "/v1/tracks/search", params={
+            "artist": artist, "title": title, "limit": limit, "cursor": cursor,
+        })
+
+    def get(self, track_id: int) -> Dict[str, Any]:
+        """Fetch a track by its SonoVault ID."""
+        return self._client._request("GET", f"/v1/tracks/{track_id}")
+
+    def by_isrc(self, isrc: str) -> Dict[str, Any]:
+        """Look up a track by any of its ISRCs."""
+        return self._client._request("GET", f"/v1/tracks/isrc/{isrc}")
+
+    def iswc(self, *, isrc: Optional[str] = None, track_id: Optional[int] = None) -> Dict[str, Any]:
+        """Recording → composition: the ISWC(s) behind a recording."""
+        return self._client._request("GET", "/v1/tracks/iswc",
+                                     params={"isrc": isrc, "id": track_id})
+
+    def by_iswc(self, iswc: str, *, limit: Optional[int] = None) -> Dict[str, Any]:
+        """Composition → recordings: every recording of a work, by ISWC."""
+        return self._client._request("GET", f"/v1/tracks/iswc/{iswc}", params={"limit": limit})
+
+    def links(self, **ids: Union[str, int]) -> Dict[str, Any]:
+        """Cross-platform IDs + deep links, from any platform ID or ISRC.
+
+        Keyword args: ``id``, ``isrc``, ``spotify_id``, ``beatport_id``,
+        ``discogs_id``, ``musicbrainz_id``, ``applemusic_id``, ``tidal_id``,
+        ``youtube_id``.
+        """
+        return self._client._request("GET", "/v1/tracks/links", params=dict(ids))
+
+    def resolve(self, *, input_type: str,
+                items: List[Union[str, Dict[str, str]]]) -> Dict[str, Any]:
+        """Resolve up to 100 track names, ISRCs, or platform IDs in one request."""
+        return self._client._request("POST", "/v1/tracks/resolve",
+                                     json={"input_type": input_type, "items": items})
+
+    def identify(self, *, fingerprint: List[int],
+                 fingerprint_duration: Optional[float] = None,
+                 top_n: Optional[int] = None) -> Dict[str, Any]:
+        """Identify a track from a Chromaprint fingerprint (``fpcalc -raw``). Paid tiers."""
+        body: Dict[str, Any] = {"fingerprint": fingerprint}
+        if fingerprint_duration is not None:
+            body["fingerprint_duration"] = fingerprint_duration
+        if top_n is not None:
+            body["top_n"] = top_n
+        return self._client._request("POST", "/v1/tracks/identify", json=body)
+
+    def identify_audio(self, audio: bytes, *, length: Optional[int] = None,
+                       top_n: Optional[int] = None) -> Dict[str, Any]:
+        """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.
+        """
+        return self._client._request(
+            "POST", "/v1/tracks/identify",
+            params={"length": length, "top_n": top_n},
+            data=audio, content_type="application/octet-stream",
+        )
+
+    def browse(self, **params: Any) -> Dict[str, Any]:
+        """Browse the catalog by ``labelId``, ``artistId``, ``genre``, ``genreId``,
+        ``year``, or ``randomize``. Paid tiers."""
+        return self._client._request("GET", "/v1/tracks/browse", params=dict(params))
+
+
+class _Artists(_Namespace):
+    def search(self, *, name: str, limit: Optional[int] = None,
+               cursor: Optional[str] = None) -> Dict[str, Any]:
+        return self._client._request("GET", "/v1/artists/search",
+                                     params={"name": name, "limit": limit, "cursor": cursor})
+
+    def get(self, artist_id: int) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/artists/{artist_id}")
+
+    def releases(self, artist_id: int, *, limit: Optional[int] = None,
+                 cursor: Optional[str] = None) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/artists/{artist_id}/releases",
+                                     params={"limit": limit, "cursor": cursor})
+
+
+class _Labels(_Namespace):
+    def search(self, *, name: str, limit: Optional[int] = None,
+               cursor: Optional[str] = None) -> Dict[str, Any]:
+        return self._client._request("GET", "/v1/labels/search",
+                                     params={"name": name, "limit": limit, "cursor": cursor})
+
+    def get(self, label_id: int) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/labels/{label_id}")
+
+    def releases(self, label_id: int, *, limit: Optional[int] = None,
+                 cursor: Optional[str] = None) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/labels/{label_id}/releases",
+                                     params={"limit": limit, "cursor": cursor})
+
+    def artists(self, label_id: int, *, limit: Optional[int] = None,
+                cursor: Optional[str] = None) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/labels/{label_id}/artists",
+                                     params={"limit": limit, "cursor": cursor})
+
+
+class _Releases(_Namespace):
+    def search(self, *, title: str, artist: Optional[str] = None,
+               limit: Optional[int] = None, cursor: Optional[str] = None) -> Dict[str, Any]:
+        return self._client._request("GET", "/v1/releases/search", params={
+            "title": title, "artist": artist, "limit": limit, "cursor": cursor,
+        })
+
+    def get(self, release_id: int) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/releases/{release_id}")
+
+    def latest(self, *, limit: Optional[int] = None,
+               cursor: Optional[str] = None) -> Dict[str, Any]:
+        """Newly released albums (``GET /v1/releases/new``). Paid tiers."""
+        return self._client._request("GET", "/v1/releases/new",
+                                     params={"limit": limit, "cursor": cursor})
+
+
+class _Genres(_Namespace):
+    def list(self) -> Dict[str, Any]:
+        """The canonical genre/subgenre hierarchy."""
+        return self._client._request("GET", "/v1/genres")
+
+
+class _Suggestions(_Namespace):
+    def submit(self, track_id: int, body: Dict[str, Any]) -> Dict[str, Any]:
+        """Suggest a metadata correction for a track. Paid tiers."""
+        return self._client._request("POST", f"/v1/tracks/{track_id}/suggestions", json=body)
+
+    def list(self, *, limit: Optional[int] = None,
+             cursor: Optional[str] = None) -> Dict[str, Any]:
+        return self._client._request("GET", "/v1/suggestions",
+                                     params={"limit": limit, "cursor": cursor})
+
+
+class _Streams(_Namespace):
+    def create(self, body: Dict[str, Any]) -> Dict[str, Any]:
+        """Start monitoring an Icecast/Shoutcast stream. Paid tiers."""
+        return self._client._request("POST", "/v1/streams", json=body)
+
+    def list(self) -> Dict[str, Any]:
+        return self._client._request("GET", "/v1/streams")
+
+    def get(self, stream_id: str) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/streams/{stream_id}")
+
+    def update(self, stream_id: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        return self._client._request("PATCH", f"/v1/streams/{stream_id}", json=body)
+
+    def history(self, stream_id: str, *, since: Optional[str] = None) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/streams/{stream_id}/history",
+                                     params={"since": since})
+
+    def report(self, *, from_: str, until: str,
+               stream_id: Optional[str] = None) -> Dict[str, Any]:
+        """Play report between two timestamps. ``from_`` maps to the ``from`` param."""
+        return self._client._request("GET", "/v1/streams/report", params={
+            "from": from_, "until": until, "stream_id": stream_id,
+        })
+
+    def live(self) -> Dict[str, Any]:
+        """What's playing right now across your monitored streams."""
+        return self._client._request("GET", "/v1/streams/live")
+
+    def stop(self, stream_id: str) -> None:
+        """Stop monitoring a stream."""
+        return self._client._request("DELETE", f"/v1/streams/{stream_id}")
+
+
+class _Webhooks(_Namespace):
+    def create(self, *, url: str, event_types: Optional[List[str]] = None,
+               description: Optional[str] = None) -> Dict[str, Any]:
+        """Register a webhook. The response includes ``secret`` once — store it."""
+        body: Dict[str, Any] = {"url": url}
+        if event_types is not None:
+            body["event_types"] = event_types
+        if description is not None:
+            body["description"] = description
+        return self._client._request("POST", "/v1/webhooks", json=body)
+
+    def list(self) -> Dict[str, Any]:
+        return self._client._request("GET", "/v1/webhooks")
+
+    def update(self, webhook_id: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        return self._client._request("PATCH", f"/v1/webhooks/{webhook_id}", json=body)
+
+    def delete(self, webhook_id: str) -> None:
+        return self._client._request("DELETE", f"/v1/webhooks/{webhook_id}")
+
+    def test(self, webhook_id: str) -> Dict[str, Any]:
+        return self._client._request("POST", f"/v1/webhooks/{webhook_id}/test")
+
+    def deliveries(self, webhook_id: str) -> Dict[str, Any]:
+        return self._client._request("GET", f"/v1/webhooks/{webhook_id}/deliveries")

sonovault-1.0.0/src/sonovault/errors.py

@@ -0,0 +1,27 @@
+class SonoVaultError(Exception):
+    """Raised for any non-2xx API response.
+
+    Attributes:
+        status: HTTP status code (0 for network errors).
+        body: parsed JSON error body, when the API returned one.
+    """
+
+    def __init__(self, message: str, status: int = 0, body=None):
+        super().__init__(message)
+        self.status = status
+        self.body = body
+
+    @property
+    def is_auth_error(self) -> bool:
+        """Missing or invalid API key."""
+        return self.status == 401
+
+    @property
+    def is_forbidden(self) -> bool:
+        """The endpoint needs a paid tier (or an admin key)."""
+        return self.status == 403
+
+    @property
+    def is_rate_limited(self) -> bool:
+        """Rate limit or monthly credit quota hit."""
+        return self.status == 429

sonovault-1.0.0/tests/test_client.py

@@ -0,0 +1,133 @@
+import json
+from unittest.mock import MagicMock
+
+import pytest
+
+from sonovault import SonoVault, SonoVaultError
+
+TRACK = {
+    "id": 123,
+    "title": "One More Time",
+    "artists": [{"id": 1, "name": "Daft Punk"}],
+    "isrc": "GBDUW0000053",
+    "releases": [],
+    "duration": 320,
+    "genre": "House",
+    "subgenre": None,
+}
+
+
+def make_response(status=200, body=None, headers=None):
+    res = MagicMock()
+    res.ok = 200 <= status < 300
+    res.status_code = status
+    res.headers = headers or {}
+    res.content = b"" if body is None else json.dumps(body).encode()
+    if body is None:
+        res.json.side_effect = ValueError("no body")
+    else:
+        res.json.return_value = body
+    return res
+
+
+def make_client(*responses):
+    session = MagicMock()
+    session.request.side_effect = list(responses)
+    return SonoVault(api_key="svk_test", session=session), session
+
+
+def test_requires_api_key():
+    with pytest.raises(ValueError):
+        SonoVault(api_key="")
+
+
+def test_search_sends_key_and_params():
+    sv, session = make_client(make_response(body={"results": [TRACK], "next_cursor": None}))
+
+    page = sv.tracks.search(artist="Daft Punk", title="One More Time", limit=5)
+
+    assert page["results"][0]["isrc"] == "GBDUW0000053"
+    method, url = session.request.call_args[0]
+    kwargs = session.request.call_args[1]
+    assert method == "GET"
+    assert url == "https://api.sonovault.now/v1/tracks/search"
+    assert kwargs["params"] == {"artist": "Daft Punk", "title": "One More Time", "limit": 5}
+    assert kwargs["headers"]["x-api-key"] == "svk_test"
+
+
+def test_none_params_are_dropped():
+    sv, session = make_client(make_response(body={"results": [], "next_cursor": None}))
+
+    sv.tracks.search(artist="Daft Punk", title="Around the World")
+
+    assert "cursor" not in session.request.call_args[1]["params"]
+    assert "limit" not in session.request.call_args[1]["params"]
+
+
+def test_resolve_posts_json_body():
+    sv, session = make_client(make_response(body={"results": [], "partial": False}))
+
+    sv.tracks.resolve(input_type="isrc", items=["GBDUW0000053"])
+
+    method, url = session.request.call_args[0]
+    assert (method, url) == ("POST", "https://api.sonovault.now/v1/tracks/resolve")
+    assert session.request.call_args[1]["json"] == {
+        "input_type": "isrc",
+        "items": ["GBDUW0000053"],
+    }
+
+
+def test_error_carries_status_and_message():
+    sv, _ = make_client(make_response(status=403, body={"error": "Paid plan required"}))
+
+    with pytest.raises(SonoVaultError) as exc:
+        sv.tracks.browse(genre="House")
+
+    assert exc.value.status == 403
+    assert exc.value.is_forbidden
+    assert "Paid plan required" in str(exc.value)
+
+
+def test_retries_429_with_retry_after():
+    sv, session = make_client(
+        make_response(status=429, body={"error": "rate limited"}, headers={"Retry-After": "0"}),
+        make_response(body=TRACK),
+    )
+
+    track = sv.tracks.get(123)
+
+    assert track["title"] == "One More Time"
+    assert session.request.call_count == 2
+
+
+def test_does_not_retry_quota_429():
+    sv, session = make_client(make_response(status=429, body={"error": "Monthly quota exceeded"}))
+
+    with pytest.raises(SonoVaultError) as exc:
+        sv.tracks.get(123)
+
+    assert exc.value.is_rate_limited
+    assert session.request.call_count == 1
+
+
+def test_stream_report_maps_from_param():
+    sv, session = make_client(make_response(body={"plays": []}))
+
+    sv.streams.report(from_="2026-07-01", until="2026-07-08")
+
+    assert session.request.call_args[1]["params"] == {"from": "2026-07-01", "until": "2026-07-08"}
+
+
+def test_delete_returns_none_on_204():
+    sv, _ = make_client(make_response(status=204))
+
+    assert sv.webhooks.delete("wh_1") is None
+
+
+def test_custom_base_url():
+    sv, session = make_client(make_response(body={"genres": []}))
+    sv2 = SonoVault(api_key="svk_test", base_url="http://localhost:3000/", session=session)
+
+    sv2.genres.list()
+
+    assert session.request.call_args[0][1] == "http://localhost:3000/v1/genres"

sonovault-1.0.0/tests/test_integration.py

@@ -0,0 +1,71 @@
+"""Live integration tests against the production API.
+
+Skipped unless SONOVAULT_API_KEY is set:
+
+    SONOVAULT_API_KEY=svk_live_… pytest tests/test_integration.py
+"""
+
+import os
+
+import pytest
+
+from sonovault import SonoVault, SonoVaultError
+
+API_KEY = os.environ.get("SONOVAULT_API_KEY")
+
+pytestmark = pytest.mark.skipif(not API_KEY, reason="SONOVAULT_API_KEY not set")
+
+
+@pytest.fixture(scope="module")
+def sv():
+    return SonoVault(api_key=API_KEY)
+
+
+def test_search_by_artist_title(sv):
+    page = sv.tracks.search(artist="Daft Punk", title="One More Time", limit=3)
+    assert page["results"]
+    track = page["results"][0]
+    assert "one more time" in track["title"].lower()
+    assert any(a["name"] == "Daft Punk" for a in track["artists"])
+    assert track["isrc"]
+
+
+def test_isrc_and_id_lookup_agree(sv):
+    page = sv.tracks.search(artist="Daft Punk", title="Around the World", limit=1)
+    found = page["results"][0]
+    assert sv.tracks.by_isrc(found["isrc"])["id"] == found["id"]
+    assert sv.tracks.get(found["id"])["title"] == found["title"]
+
+
+def test_cross_platform_links(sv):
+    page = sv.tracks.search(artist="Daft Punk", title="One More Time", limit=1)
+    links = sv.tracks.links(isrc=page["results"][0]["isrc"])
+    sources = [link["source"] for link in links["links"]]
+    assert len(sources) > 1
+    assert "spotify" in sources
+
+
+def test_recording_to_iswc(sv):
+    page = sv.tracks.search(artist="Daft Punk", title="One More Time", limit=1)
+    work = sv.tracks.iswc(isrc=page["results"][0]["isrc"])
+    assert isinstance(work.get("iswcs"), list)
+
+
+def test_bulk_resolve(sv):
+    page = sv.tracks.search(artist="Daft Punk", title="Harder, Better, Faster, Stronger", limit=1)
+    found = page["results"][0]
+    batch = sv.tracks.resolve(input_type="isrc", items=[found["isrc"]])
+    assert batch["results"][0]["status"] == "matched"
+    assert batch["results"][0]["track"]["id"] == found["id"]
+
+
+def test_genres(sv):
+    genres = sv.genres.list()["genres"]
+    assert len(genres) > 10
+
+
+def test_bad_key_is_401():
+    bad = SonoVault(api_key="svk_live_invalid")
+    with pytest.raises(SonoVaultError) as exc:
+        bad.genres.list()
+    assert exc.value.status == 401