selin-vinyl-api 0.1.0__tar.gz

selin_vinyl_api-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Quantum Protection Security Services LLC (Selin)
+
+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.

selin_vinyl_api-0.1.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: selin-vinyl-api
+Version: 0.1.0
+Summary: Official Python client for the Selin Vinyl API: music metadata, matching, credits and cover art.
+License: MIT
+Project-URL: Homepage, https://selin-ai.com/vinyl-api
+Project-URL: Documentation, https://vinyl-api.selin-ai.com/docs
+Keywords: music,metadata,musicbrainz,isrc,upc,api,selin,vinyl
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# selin-vinyl-api (Python)
+
+Official client for the [Selin Vinyl API](https://vinyl-api.selin-ai.com/docs): artists, albums, tracklists, ISRC and barcode lookups, credits, cover art and track matching, built on MusicBrainz and Wikidata (CC0) plus Selin's own listening data.
+
+No dependencies (standard library only). Python 3.9+.
+
+```sh
+pip install selin-vinyl-api
+```
+
+Get a free key at <https://selin-ai.com/vinyl-api>.
+
+```python
+from selin_vinyl import VinylAPI, VinylAPIError
+
+vinyl = VinylAPI(api_key="vk_...")   # or set VINYL_API_KEY
+
+artists = vinyl.search_artists("prince", limit=3)["artists"]
+album = vinyl.get_album_tracks("<release-group id>", credits=True)
+
+# Which recording is this? The matching tool for library imports.
+match = vinyl.match_track("Purple Rain", artist="Prince", duration_ms=520000)["match"]
+
+# Up to 50 lookups in one request.
+results = vinyl.batch([
+    {"id": "a", "type": "isrc", "value": "USWB11602075"},
+    {"id": "b", "type": "upc", "value": "602547924139"},
+])["results"]
+```
+
+Methods are the API's operations in snake_case: `search_artists`, `get_artist`, `list_artist_releases`, `list_artist_credits`, `lookup_artist`, `search_albums`, `get_album`, `get_album_tracks`, `get_album_artwork`, `lookup_album`, `list_new_releases`, `lookup_upc`, `search_tracks`, `lookup_isrc`, `get_recording`, `match_track`, `batch`, `get_artist_chart`, `get_usage`, `get_plans`. Each returns the parsed JSON; the [API reference](https://vinyl-api.selin-ai.com/docs) documents every field.
+
+## Errors, limits and retries
+
+```python
+try:
+    vinyl.get_artist(artist_id)
+except VinylAPIError as e:
+    print(e.status, e.code, e.retry_after)
+
+vinyl.rate_limit   # {"limit", "remaining", "quota_limit", "quota_used"} from the last response
+```
+
+A `429` is retried automatically after the `Retry-After` wait (up to `max_retries`, default 2); gateway errors on GETs are retried with backoff. Constructor options: `base_url`, `max_retries`, `timeout`.
+
+## Attribution
+
+Show the `attribution` string the API returns wherever you display its data. Wikipedia biographies are CC BY-SA 4.0 (credit and link back); cover art and artist photos belong to their rights holders.
+
+MIT licensed.

selin_vinyl_api-0.1.0/README.md

@@ -0,0 +1,50 @@
+# selin-vinyl-api (Python)
+
+Official client for the [Selin Vinyl API](https://vinyl-api.selin-ai.com/docs): artists, albums, tracklists, ISRC and barcode lookups, credits, cover art and track matching, built on MusicBrainz and Wikidata (CC0) plus Selin's own listening data.
+
+No dependencies (standard library only). Python 3.9+.
+
+```sh
+pip install selin-vinyl-api
+```
+
+Get a free key at <https://selin-ai.com/vinyl-api>.
+
+```python
+from selin_vinyl import VinylAPI, VinylAPIError
+
+vinyl = VinylAPI(api_key="vk_...")   # or set VINYL_API_KEY
+
+artists = vinyl.search_artists("prince", limit=3)["artists"]
+album = vinyl.get_album_tracks("<release-group id>", credits=True)
+
+# Which recording is this? The matching tool for library imports.
+match = vinyl.match_track("Purple Rain", artist="Prince", duration_ms=520000)["match"]
+
+# Up to 50 lookups in one request.
+results = vinyl.batch([
+    {"id": "a", "type": "isrc", "value": "USWB11602075"},
+    {"id": "b", "type": "upc", "value": "602547924139"},
+])["results"]
+```
+
+Methods are the API's operations in snake_case: `search_artists`, `get_artist`, `list_artist_releases`, `list_artist_credits`, `lookup_artist`, `search_albums`, `get_album`, `get_album_tracks`, `get_album_artwork`, `lookup_album`, `list_new_releases`, `lookup_upc`, `search_tracks`, `lookup_isrc`, `get_recording`, `match_track`, `batch`, `get_artist_chart`, `get_usage`, `get_plans`. Each returns the parsed JSON; the [API reference](https://vinyl-api.selin-ai.com/docs) documents every field.
+
+## Errors, limits and retries
+
+```python
+try:
+    vinyl.get_artist(artist_id)
+except VinylAPIError as e:
+    print(e.status, e.code, e.retry_after)
+
+vinyl.rate_limit   # {"limit", "remaining", "quota_limit", "quota_used"} from the last response
+```
+
+A `429` is retried automatically after the `Retry-After` wait (up to `max_retries`, default 2); gateway errors on GETs are retried with backoff. Constructor options: `base_url`, `max_retries`, `timeout`.
+
+## Attribution
+
+Show the `attribution` string the API returns wherever you display its data. Wikipedia biographies are CC BY-SA 4.0 (credit and link back); cover art and artist photos belong to their rights holders.
+
+MIT licensed.

selin_vinyl_api-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "selin-vinyl-api"
+version = "0.1.0"
+description = "Official Python client for the Selin Vinyl API: music metadata, matching, credits and cover art."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = ["music", "metadata", "musicbrainz", "isrc", "upc", "api", "selin", "vinyl"]
+classifiers = ["Programming Language :: Python :: 3", "Typing :: Typed", "License :: OSI Approved :: MIT License"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://selin-ai.com/vinyl-api"
+Documentation = "https://vinyl-api.selin-ai.com/docs"
+
+[tool.setuptools]
+packages = ["selin_vinyl"]
+[tool.setuptools.package-data]
+selin_vinyl = ["py.typed"]

selin_vinyl_api-0.1.0/selin_vinyl/__init__.py

@@ -0,0 +1,7 @@
+"""Selin Vinyl API client."""
+__version__ = "0.1.0"
+
+from ._transport import VinylAPIError  # noqa: E402
+from .client import VinylAPI  # noqa: E402
+
+__all__ = ["VinylAPI", "VinylAPIError", "__version__"]

selin_vinyl_api-0.1.0/selin_vinyl/_transport.py

@@ -0,0 +1,85 @@
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Optional
+
+from . import __version__
+
+
+class VinylAPIError(Exception):
+    """The API answered with an error status."""
+
+    def __init__(self, status: int, code: str, body: Any = None, retry_after: Optional[float] = None):
+        super().__init__(f"Vinyl API {status}: {code}")
+        self.status = status
+        self.code = code  # the API's error message or code, e.g. "not_found"
+        self.body = body
+        self.retry_after = retry_after  # seconds to wait before retrying, on a 429
+
+
+def _num(v: Optional[str]) -> Optional[int]:
+    try:
+        return int(v) if v not in (None, "") else None
+    except ValueError:
+        return None
+
+
+class Transport:
+    def __init__(self, api_key: Optional[str] = None, *, base_url: Optional[str] = None, max_retries: int = 2, timeout: float = 30.0):
+        self.api_key = api_key or os.environ.get("VINYL_API_KEY")
+        self.base_url = (base_url or os.environ.get("VINYL_API_URL") or "https://vinyl-api.selin-ai.com").rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+        #: Rate-limit and quota numbers from the most recent response.
+        self.rate_limit: Dict[str, Optional[int]] = {}
+
+    def _request(self, method: str, route: str, *, query: Dict[str, Any], body: Any, auth: bool, timeout: Optional[float]) -> Any:
+        if auth and not self.api_key:
+            raise ValueError("No API key: pass api_key=... or set VINYL_API_KEY. Get a free key at https://selin-ai.com/vinyl-api")
+        qs = urllib.parse.urlencode({k: ("true" if v is True else "false" if v is False else v) for k, v in query.items() if v is not None})
+        url = self.base_url + route + ("?" + qs if qs else "")
+        headers = {"accept": "application/json", "user-agent": f"selin-vinyl-api-python/{__version__}"}
+        if self.api_key:
+            headers["x-api-key"] = self.api_key
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode()
+            headers["content-type"] = "application/json"
+
+        attempt = 0
+        while True:
+            req = urllib.request.Request(url, data=data, method=method, headers=headers)
+            try:
+                with urllib.request.urlopen(req, timeout=timeout or self.timeout) as res:
+                    self._remember(res.headers)
+                    return json.loads(res.read().decode())
+            except urllib.error.HTTPError as e:
+                self._remember(e.headers)
+                text = e.read().decode(errors="replace")
+                try:
+                    parsed: Any = json.loads(text)
+                except ValueError:
+                    parsed = text
+                retry_after = _num(e.headers.get("retry-after"))
+                code = parsed.get("error") if isinstance(parsed, dict) and parsed.get("error") else e.reason
+                transient = (retry_after or 1) <= 30 if e.code == 429 else (method == "GET" and e.code in (502, 503, 504))
+                if attempt < self.max_retries and transient:
+                    time.sleep((retry_after or 1) if e.code == 429 else 0.4 * 2 ** attempt)
+                    attempt += 1
+                    continue
+                raise VinylAPIError(e.code, str(code), parsed, retry_after) from None
+            except (urllib.error.URLError, TimeoutError):
+                if attempt < self.max_retries and method == "GET":
+                    time.sleep(0.4 * 2 ** attempt)
+                    attempt += 1
+                    continue
+                raise
+
+    def _remember(self, h: Any) -> None:
+        self.rate_limit = {
+            "limit": _num(h.get("x-ratelimit-limit")), "remaining": _num(h.get("x-ratelimit-remaining")),
+            "quota_limit": _num(h.get("x-quota-limit")), "quota_used": _num(h.get("x-quota-used")),
+        }

selin_vinyl_api-0.1.0/selin_vinyl/client.py

@@ -0,0 +1,348 @@
+# GENERATED by sdk/generate.js from the OpenAPI description. Do not edit by hand.
+from __future__ import annotations
+
+from typing import Any, Optional
+from urllib.parse import quote
+
+from ._transport import Transport
+
+
+class VinylAPI(Transport):
+    """Client for the Selin Vinyl API (https://vinyl-api.selin-ai.com/docs).
+
+    >>> vinyl = VinylAPI(api_key="vk_...")   # or set VINYL_API_KEY
+    >>> vinyl.search_artists("prince", limit=3)["artists"][0]["name"]
+    'Prince'
+    """
+
+    def search_artists(self, q: str, limit: Optional[int] = None, *, timeout: Optional[float] = None) -> Any:
+        """Search artists.
+        
+        Best match first: exact name, then prefix, then fuzzy, preferring artists with more releases.
+        
+        ``GET /v1/artists/search``
+        
+        Args:
+            q: Artist name (2+ characters).
+            limit: How many results to return (1-25).
+        """
+        return self._request("GET", "/v1/artists/search",
+                             query={"q": q, "limit": limit},
+                             body=None, auth=True, timeout=timeout)
+
+    def get_artist(self, id: str, *, timeout: Optional[float] = None) -> Any:
+        """Get an artist.
+        
+        Profile, members, release counts, genres, listening stats and Wikipedia/Wikidata enrichment.
+        
+        ``GET /v1/artists/{id}``
+        
+        Args:
+            id: The artist's MusicBrainz id (UUID).
+        """
+        return self._request("GET", "/v1/artists/{id}".format(id=quote(str(id), safe="")),
+                             query={},
+                             body=None, auth=True, timeout=timeout)
+
+    def list_artist_releases(self, id: str, type: Optional[str] = None, studio: Optional[bool] = None, limit: Optional[int] = None, offset: Optional[int] = None, *, timeout: Optional[float] = None) -> Any:
+        """List an artist's releases.
+        
+        Albums, EPs and singles, newest first.
+        
+        ``GET /v1/artists/{id}/releases``
+        
+        Args:
+            id: The artist's MusicBrainz id (UUID).
+            type: Album, EP or single (default: all).
+            studio: Hide live, compilation, remix and other secondary types (`studio=true`; `1` also works).
+            limit: How many results to return (1-200).
+            offset: How many results to skip, for paging.
+        """
+        return self._request("GET", "/v1/artists/{id}/releases".format(id=quote(str(id), safe="")),
+                             query={"type": type, "studio": studio, "limit": limit, "offset": offset},
+                             body=None, auth=True, timeout=timeout)
+
+    def list_artist_credits(self, id: str, role: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None, *, timeout: Optional[float] = None) -> Any:
+        """Recordings an artist is credited on.
+        
+        Producer, engineer, mix, mastering, arranger, remixer, performer and other credited roles.
+        
+        ``GET /v1/artists/{id}/credits``
+        
+        Args:
+            id: The artist's MusicBrainz id (UUID).
+            role: Only this role.
+            limit: How many results to return (1-100).
+            offset: How many results to skip, for paging.
+        """
+        return self._request("GET", "/v1/artists/{id}/credits".format(id=quote(str(id), safe="")),
+                             query={"role": role, "limit": limit, "offset": offset},
+                             body=None, auth=True, timeout=timeout)
+
+    def lookup_artist(self, spotify: Optional[str] = None, apple: Optional[str] = None, deezer: Optional[str] = None, *, timeout: Optional[float] = None) -> Any:
+        """Find an artist by another service's id.
+        
+        Cross-reference from a Spotify, Apple Music or Deezer artist id to the MusicBrainz artist.
+        
+        ``GET /v1/lookup/artist``
+        
+        Args:
+            spotify: Spotify artist id.
+            apple: Apple Music artist id.
+            deezer: Deezer artist id.
+        """
+        return self._request("GET", "/v1/lookup/artist",
+                             query={"spotify": spotify, "apple": apple, "deezer": deezer},
+                             body=None, auth=True, timeout=timeout)
+
+    def search_albums(self, q: str, artist: Optional[str] = None, type: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None, *, timeout: Optional[float] = None) -> Any:
+        """Search albums, EPs and singles.
+        
+        Ranks exact titles, studio releases and releases with a tracklist first, then popularity.
+        
+        ``GET /v1/release-groups/search``
+        
+        Args:
+            q: Title (2+ characters).
+            artist: Narrow to an artist: a MusicBrainz id or part of the name.
+            type: Only this kind of release.
+            limit: How many results to return (1-25).
+            offset: How many results to skip, for paging.
+        """
+        return self._request("GET", "/v1/release-groups/search",
+                             query={"q": q, "artist": artist, "type": type, "limit": limit, "offset": offset},
+                             body=None, auth=True, timeout=timeout)
+
+    def get_album(self, id: str, *, timeout: Optional[float] = None) -> Any:
+        """Get a release group.
+        
+        One album, EP or single with its credited artists.
+        
+        ``GET /v1/release-groups/{id}``
+        
+        Args:
+            id: The release group's MusicBrainz id (UUID).
+        """
+        return self._request("GET", "/v1/release-groups/{id}".format(id=quote(str(id), safe="")),
+                             query={},
+                             body=None, auth=True, timeout=timeout)
+
+    def get_album_tracks(self, id: str, credits: Optional[bool] = None, *, timeout: Optional[float] = None) -> Any:
+        """Get an album's tracklist.
+        
+        The tracklist of the representative release (the earliest official edition), with recording ids and ISRCs.
+        
+        ``GET /v1/release-groups/{id}/tracks``
+        
+        Args:
+            id: The release group's MusicBrainz id (UUID).
+            credits: Attach credits to every track (`credits=true`; `1` also works).
+        """
+        return self._request("GET", "/v1/release-groups/{id}/tracks".format(id=quote(str(id), safe="")),
+                             query={"credits": credits},
+                             body=None, auth=True, timeout=timeout)
+
+    def get_album_artwork(self, id: str, *, timeout: Optional[float] = None) -> Any:
+        """Get cover art.
+        
+        Cover art links from the Cover Art Archive. Verifies the image exists (cached 30 days).
+        
+        ``GET /v1/release-groups/{id}/artwork``
+        
+        Args:
+            id: The release group's MusicBrainz id (UUID).
+        """
+        return self._request("GET", "/v1/release-groups/{id}/artwork".format(id=quote(str(id), safe="")),
+                             query={},
+                             body=None, auth=True, timeout=timeout)
+
+    def lookup_album(self, artist: str, title: str, year: Optional[int] = None, *, timeout: Optional[float] = None) -> Any:
+        """Find an artist's album by title.
+        
+        Punctuation and case insensitive; deluxe/remaster suffixes ignored; prefers the year given. Only groups with a tracklist.
+        
+        ``GET /v1/lookup/album``
+        
+        Args:
+            artist: The artist's MusicBrainz id.
+            title: Album title.
+            year: Preferred release year.
+        """
+        return self._request("GET", "/v1/lookup/album",
+                             query={"artist": artist, "title": title, "year": year},
+                             body=None, auth=True, timeout=timeout)
+
+    def list_new_releases(self, days: Optional[int] = None, type: Optional[str] = None, all: Optional[bool] = None, limit: Optional[int] = None, offset: Optional[int] = None, *, timeout: Optional[float] = None) -> Any:
+        """New releases.
+        
+        The latest albums, EPs and singles in the catalogue, newest first.
+        
+        ``GET /v1/releases/new``
+        
+        Args:
+            days: Look back this many days (1-90).
+            type: Only this kind of release.
+            all: Include live, compilation, remix and other secondary types (`all=true`; `1` also works).
+            limit: How many results to return (1-100).
+            offset: How many results to skip, for paging.
+        """
+        return self._request("GET", "/v1/releases/new",
+                             query={"days": days, "type": type, "all": all, "limit": limit, "offset": offset},
+                             body=None, auth=True, timeout=timeout)
+
+    def lookup_upc(self, code: str, *, timeout: Optional[float] = None) -> Any:
+        """Look up a release by barcode.
+        
+        UPC-A, EAN-13 and GTIN-14 spellings of the same barcode all work.
+        
+        ``GET /v1/lookup/upc/{code}``
+        
+        Args:
+            code: The barcode (8-14 digits).
+        """
+        return self._request("GET", "/v1/lookup/upc/{code}".format(code=quote(str(code), safe="")),
+                             query={},
+                             body=None, auth=True, timeout=timeout)
+
+    def search_tracks(self, q: str, artist: Optional[str] = None, limit: Optional[int] = None, offset: Optional[int] = None, *, timeout: Optional[float] = None) -> Any:
+        """Search tracks.
+        
+        Find recordings by title, optionally narrowed by artist. Common titles are ranked by artist popularity.
+        
+        ``GET /v1/tracks/search``
+        
+        Args:
+            q: Title (2+ characters).
+            artist: Artist name to narrow the search.
+            limit: How many results to return (1-25).
+            offset: How many results to skip, for paging.
+        """
+        return self._request("GET", "/v1/tracks/search",
+                             query={"q": q, "artist": artist, "limit": limit, "offset": offset},
+                             body=None, auth=True, timeout=timeout)
+
+    def lookup_isrc(self, isrc: str, *, timeout: Optional[float] = None) -> Any:
+        """Look up a track by ISRC.
+        
+        The recording and every album, EP or single we hold it on.
+        
+        ``GET /v1/tracks/isrc/{isrc}``
+        
+        Args:
+            isrc: A 12-character ISRC (hyphens ignored).
+        """
+        return self._request("GET", "/v1/tracks/isrc/{isrc}".format(isrc=quote(str(isrc), safe="")),
+                             query={},
+                             body=None, auth=True, timeout=timeout)
+
+    def get_recording(self, id: str, *, timeout: Optional[float] = None) -> Any:
+        """Get a recording.
+        
+        A recording with its ISRCs, the releases it appears on and its credits.
+        
+        ``GET /v1/recordings/{id}``
+        
+        Args:
+            id: The recording's MusicBrainz id (UUID).
+        """
+        return self._request("GET", "/v1/recordings/{id}".format(id=quote(str(id), safe="")),
+                             query={},
+                             body=None, auth=True, timeout=timeout)
+
+    def match_track(self, title: str, artist: Optional[str] = None, album: Optional[str] = None, duration_ms: Optional[int] = None, duration: Optional[float] = None, *, timeout: Optional[float] = None) -> Any:
+        """Match a track.
+        
+        Identify the recording behind a title, artist, album and duration: the matching tool for library imports and playlists. "(Remastered)" style suffixes are ignored. Weights: title 55%, artist 30%, album 10%, duration 5%.
+        
+        ``GET /v1/match``
+        
+        Args:
+            title: Track title.
+            artist: Artist name.
+            album: Album name.
+            duration_ms: Duration in milliseconds.
+            duration: Duration in seconds (alternative).
+        """
+        return self._request("GET", "/v1/match",
+                             query={"title": title, "artist": artist, "album": album, "durationMs": duration_ms, "duration": duration},
+                             body=None, auth=True, timeout=timeout)
+
+    def batch(self, requests: list, *, timeout: Optional[float] = None) -> Any:
+        """Batch lookups.
+        
+        Up to 50 ISRC, UPC, match and artist-lookup requests in one call. Each lookup counts as one request against your plan. Results come back in request order; a lookup that fails has an `error` instead of a `result`.
+        
+        ``POST /v1/batch``
+        
+        Args:
+            requests: Up to 50 lookups. Each counts as one request against your plan.
+        """
+        return self._request("POST", "/v1/batch",
+                             query={},
+                             body={"requests": requests}, auth=True, timeout=timeout)
+
+    def get_artist_chart(self, days: Optional[int] = None, limit: Optional[int] = None, *, timeout: Optional[float] = None) -> Any:
+        """Artist chart.
+        
+        Artists ranked by distinct listeners on Selin (then plays) over the last N days.
+        
+        ``GET /v1/charts/artists``
+        
+        Args:
+            days: Window in days (1-90).
+            limit: How many results to return (1-100).
+        """
+        return self._request("GET", "/v1/charts/artists",
+                             query={"days": days, "limit": limit},
+                             body=None, auth=True, timeout=timeout)
+
+    def get_usage(self, *, timeout: Optional[float] = None) -> Any:
+        """Your usage.
+        
+        This month's request count and the last 30 days by endpoint, for the key making the call.
+        
+        ``GET /v1/usage``
+        """
+        return self._request("GET", "/v1/usage",
+                             query={},
+                             body=None, auth=True, timeout=timeout)
+
+    def get_plans(self, *, timeout: Optional[float] = None) -> Any:
+        """Plans and prices.
+        
+        No key needed.
+        
+        ``GET /portal/config``
+        """
+        return self._request("GET", "/portal/config",
+                             query={},
+                             body=None, auth=False, timeout=timeout)
+
+    def signup(self, name: str, email: str, *, timeout: Optional[float] = None) -> Any:
+        """Get a free key.
+        
+        Creates a free key (one per email, a few per network per day). The key is shown once.
+        
+        ``POST /portal/signup``
+        
+        Args:
+            name: Your name or company.
+            email: Your email.
+        """
+        return self._request("POST", "/portal/signup",
+                             query={},
+                             body={"name": name, "email": email}, auth=False, timeout=timeout)
+
+    def start_checkout(self, tier: str, *, timeout: Optional[float] = None) -> Any:
+        """Upgrade your plan.
+        
+        Starts a Stripe Checkout for a paid plan; authenticated with your own key. Your key upgrades automatically once payment completes.
+        
+        ``POST /portal/checkout``
+        
+        Args:
+            tier: The plan to buy.
+        """
+        return self._request("POST", "/portal/checkout",
+                             query={},
+                             body={"tier": tier}, auth=True, timeout=timeout)

selin_vinyl_api-0.1.0/selin_vinyl_api.egg-info/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: selin-vinyl-api
+Version: 0.1.0
+Summary: Official Python client for the Selin Vinyl API: music metadata, matching, credits and cover art.
+License: MIT
+Project-URL: Homepage, https://selin-ai.com/vinyl-api
+Project-URL: Documentation, https://vinyl-api.selin-ai.com/docs
+Keywords: music,metadata,musicbrainz,isrc,upc,api,selin,vinyl
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# selin-vinyl-api (Python)
+
+Official client for the [Selin Vinyl API](https://vinyl-api.selin-ai.com/docs): artists, albums, tracklists, ISRC and barcode lookups, credits, cover art and track matching, built on MusicBrainz and Wikidata (CC0) plus Selin's own listening data.
+
+No dependencies (standard library only). Python 3.9+.
+
+```sh
+pip install selin-vinyl-api
+```
+
+Get a free key at <https://selin-ai.com/vinyl-api>.
+
+```python
+from selin_vinyl import VinylAPI, VinylAPIError
+
+vinyl = VinylAPI(api_key="vk_...")   # or set VINYL_API_KEY
+
+artists = vinyl.search_artists("prince", limit=3)["artists"]
+album = vinyl.get_album_tracks("<release-group id>", credits=True)
+
+# Which recording is this? The matching tool for library imports.
+match = vinyl.match_track("Purple Rain", artist="Prince", duration_ms=520000)["match"]
+
+# Up to 50 lookups in one request.
+results = vinyl.batch([
+    {"id": "a", "type": "isrc", "value": "USWB11602075"},
+    {"id": "b", "type": "upc", "value": "602547924139"},
+])["results"]
+```
+
+Methods are the API's operations in snake_case: `search_artists`, `get_artist`, `list_artist_releases`, `list_artist_credits`, `lookup_artist`, `search_albums`, `get_album`, `get_album_tracks`, `get_album_artwork`, `lookup_album`, `list_new_releases`, `lookup_upc`, `search_tracks`, `lookup_isrc`, `get_recording`, `match_track`, `batch`, `get_artist_chart`, `get_usage`, `get_plans`. Each returns the parsed JSON; the [API reference](https://vinyl-api.selin-ai.com/docs) documents every field.
+
+## Errors, limits and retries
+
+```python
+try:
+    vinyl.get_artist(artist_id)
+except VinylAPIError as e:
+    print(e.status, e.code, e.retry_after)
+
+vinyl.rate_limit   # {"limit", "remaining", "quota_limit", "quota_used"} from the last response
+```
+
+A `429` is retried automatically after the `Retry-After` wait (up to `max_retries`, default 2); gateway errors on GETs are retried with backoff. Constructor options: `base_url`, `max_retries`, `timeout`.
+
+## Attribution
+
+Show the `attribution` string the API returns wherever you display its data. Wikipedia biographies are CC BY-SA 4.0 (credit and link back); cover art and artist photos belong to their rights holders.
+
+MIT licensed.

selin_vinyl_api-0.1.0/selin_vinyl_api.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+selin_vinyl/__init__.py
+selin_vinyl/_transport.py
+selin_vinyl/client.py
+selin_vinyl/py.typed
+selin_vinyl_api.egg-info/PKG-INFO
+selin_vinyl_api.egg-info/SOURCES.txt
+selin_vinyl_api.egg-info/dependency_links.txt
+selin_vinyl_api.egg-info/top_level.txt

selin_vinyl_api-0.1.0/selin_vinyl_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

selin_vinyl_api-0.1.0/selin_vinyl_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+selin_vinyl

selin_vinyl_api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+