labelsentry 1.0.0__tar.gz

labelsentry-1.0.0/.gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+__pycache__/
+*.egg-info/
+.venv/

labelsentry-1.0.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.5
+Name: labelsentry
+Version: 1.0.0
+Summary: The LabelSentry API for Python
+Project-URL: Documentation, https://labelsentry.com/docs/api
+Project-URL: Source, https://github.com/LabelSentrycom/labelsentry-sdks
+License-Expression: MIT
+Requires-Python: >=3.9
+Requires-Dist: typing-extensions>=4.7; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# labelsentry
+
+The LabelSentry API for Python 3.9 and newer, with no dependencies beyond the standard library.
+
+```python
+from labelsentry import LabelSentry, LabelSentryError
+
+ls = LabelSentry()  # reads LABELSENTRY_KEY
+
+artist = ls.artists.create({"spotify_url": "https://open.spotify.com/artist/..."})
+ls.artists.verify(artist["id"], {"method": "attest", "confirmed": True})
+
+for release in ls.releases.list(state="down"):
+    print(release["name"], release["tracks_offline"])
+
+try:
+    ls.changes.resolve("not-a-change")
+except LabelSentryError as e:
+    print(e.status, e.code, e.request_id)
+```
+
+Lists are iterators that fetch the next page when they reach the end of one.

labelsentry-1.0.0/README.md

@@ -0,0 +1,22 @@
+# labelsentry
+
+The LabelSentry API for Python 3.9 and newer, with no dependencies beyond the standard library.
+
+```python
+from labelsentry import LabelSentry, LabelSentryError
+
+ls = LabelSentry()  # reads LABELSENTRY_KEY
+
+artist = ls.artists.create({"spotify_url": "https://open.spotify.com/artist/..."})
+ls.artists.verify(artist["id"], {"method": "attest", "confirmed": True})
+
+for release in ls.releases.list(state="down"):
+    print(release["name"], release["tracks_offline"])
+
+try:
+    ls.changes.resolve("not-a-change")
+except LabelSentryError as e:
+    print(e.status, e.code, e.request_id)
+```
+
+Lists are iterators that fetch the next page when they reach the end of one.

labelsentry-1.0.0/labelsentry/__init__.py

@@ -0,0 +1,8 @@
+"""The LabelSentry API for Python."""
+
+from .client import DEFAULT_BASE_URL, VERSION, LabelSentry
+from .errors import LabelSentryError
+from .webhooks import verify_webhook
+
+__all__ = ["LabelSentry", "LabelSentryError", "verify_webhook", "DEFAULT_BASE_URL", "VERSION"]
+__version__ = VERSION

labelsentry-1.0.0/labelsentry/client.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import json
+import os
+import random
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from typing import Any, Dict, Iterator, Optional
+
+from .errors import LabelSentryError
+from .operations import RESOURCES
+
+DEFAULT_BASE_URL = "https://public-api.labelsentry.com/v1"
+VERSION = "1.0.0"
+
+
+class LabelSentry:
+    """The LabelSentry API.
+
+    >>> ls = LabelSentry()  # reads LABELSENTRY_KEY
+    >>> for change in ls.changes.list(severity="critical"):
+    ...     print(change["summary"])
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, base_url: Optional[str] = None,
+                 max_retries: int = 3, timeout: float = 30.0) -> None:
+        key = api_key or os.environ.get("LABELSENTRY_KEY")
+        if not key:
+            raise ValueError("No API key: pass one or set LABELSENTRY_KEY.")
+        self._key = key
+        self.base_url = (base_url or os.environ.get("LABELSENTRY_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+        for name, cls in RESOURCES.items():
+            setattr(self, name, cls(self))
+
+    def _url(self, path: str, query: Optional[Dict[str, Any]]) -> str:
+        params = {k: v for k, v in (query or {}).items() if v not in (None, "")}
+        return self.base_url + path + ("?" + urllib.parse.urlencode(params) if params else "")
+
+    def _send(self, method: str, path: str, query: Optional[Dict[str, Any]] = None, body: Any = None) -> bytes:
+        headers = {
+            "Authorization": f"Bearer {self._key}",
+            "Accept": "application/json",
+            "User-Agent": f"labelsentry-python/{VERSION}",
+        }
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode()
+            headers["Content-Type"] = "application/json"
+        if method == "POST":
+            headers["Idempotency-Key"] = str(uuid.uuid4())
+        attempt = 0
+        while True:
+            req = urllib.request.Request(self._url(path, query), data=data, headers=headers, method=method)
+            try:
+                with urllib.request.urlopen(req, timeout=self.timeout) as res:
+                    return res.read()
+            except urllib.error.HTTPError as err:
+                if (err.code == 429 or err.code >= 500) and attempt < self.max_retries:
+                    time.sleep(_wait(err.headers.get("Retry-After"), attempt))
+                    attempt += 1
+                    continue
+                raise LabelSentryError.from_response(err.code, err.read(), err.headers) from None
+            except urllib.error.URLError:
+                if attempt < self.max_retries:
+                    time.sleep(_wait(None, attempt))
+                    attempt += 1
+                    continue
+                raise
+
+    def _request(self, method: str, path: str, *, query: Optional[Dict[str, Any]] = None,
+                 body: Any = None, unwrap: bool = True) -> Any:
+        out = json.loads(self._send(method, path, query, body) or b"{}")
+        return out.get("data") if unwrap else out
+
+    def _text(self, method: str, path: str, query: Optional[Dict[str, Any]] = None) -> str:
+        return self._send(method, path, query).decode()
+
+    def _page(self, path: str, query: Optional[Dict[str, Any]]) -> Iterator[Any]:
+        cursor = None
+        while True:
+            q = dict(query or {})
+            q["cursor"] = cursor
+            page = json.loads(self._send("GET", path, q))
+            yield from page["data"]
+            cursor = page.get("next_cursor")
+            if not cursor:
+                return
+
+
+def _wait(retry_after: Optional[str], attempt: int) -> float:
+    try:
+        return min(float(retry_after), 60.0)
+    except (TypeError, ValueError):
+        return 0.5 * 2 ** attempt + random.random() / 10

labelsentry-1.0.0/labelsentry/errors.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Mapping, Optional
+
+
+class LabelSentryError(Exception):
+    """An answer the API refused, with what it said about why."""
+
+    def __init__(self, status: int, code: str, message: str, request_id: str = "",
+                 field: Optional[str] = None, docs_url: str = "") -> None:
+        super().__init__(message)
+        self.status, self.code, self.message = status, code, message
+        self.request_id, self.field, self.docs_url = request_id, field, docs_url
+
+    def __str__(self) -> str:
+        return f"{self.status} {self.code}: {self.message}"
+
+    @classmethod
+    def from_response(cls, status: int, body: bytes, headers: Mapping[str, Any]) -> "LabelSentryError":
+        try:
+            e = json.loads(body).get("error", {})
+        except ValueError:
+            e = {}
+        return cls(status, e.get("code", f"http_{status}"), e.get("message", "request failed"),
+                   e.get("request_id") or headers.get("X-Request-Id", ""), e.get("field"), e.get("docs_url", ""))

labelsentry-1.0.0/labelsentry/models.py

@@ -0,0 +1,522 @@
+"""Generated by scripts/generate.py from openapi.json. Do not edit."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, TypedDict
+
+try:
+    from typing import NotRequired
+except ImportError:  # Python before 3.11
+    from typing_extensions import NotRequired
+
+
+class AddArtist(TypedDict, total=False):
+    spotify_id: str
+    spotify_url: str
+
+
+class AlertDelivery(TypedDict):
+    attempts: int
+    change_id: str
+    created_at: str
+    delivered_at: NotRequired[Optional[str]]
+    destination_id: str
+    id: str
+    object: str
+    status: str
+
+
+class Artist(TypedDict):
+    added_at: str
+    followers: NotRequired[Optional[int]]
+    id: str
+    image_url: str
+    label_tag: str
+    last_checked_at: NotRequired[Optional[str]]
+    monthly_listeners: NotRequired[Optional[int]]
+    name: str
+    object: str
+    spotify_id: str
+    spotify_verified: bool
+    status: str
+    world_rank: NotRequired[Optional[int]]
+
+
+class ArtistSearchResult(TypedDict):
+    followers: int
+    image_url: str
+    monthly_listeners: int
+    name: str
+    object: str
+    spotify_id: str
+    spotify_verified: bool
+
+
+class ArtistStats(TypedDict):
+    artist_id: str
+    days: int
+    followers: List["DayValue"]
+    listeners: List["DayValue"]
+    object: str
+
+
+class AuditEntry(TypedDict):
+    action: str
+    actor_user_id: str
+    created_at: str
+    id: str
+    ip: str
+    object: str
+    target: Dict[str, Any]
+
+
+class Change(TypedDict):
+    artist: "Ref"
+    confirmed_at: str
+    dashboard_url: str
+    detail: str
+    details: Dict[str, Any]
+    entity: "Entity"
+    id: str
+    label: str
+    object: str
+    severity: str
+    status: str
+    summary: str
+    type: str
+
+
+class ChangeType(TypedDict):
+    beta: str
+    id: str
+    label: str
+    object: str
+    severity: str
+
+
+class DayValue(TypedDict):
+    day: str
+    value: int
+
+
+class Deleted(TypedDict):
+    deleted: bool
+    id: str
+    object: str
+
+
+class Destination(TypedDict):
+    active: bool
+    created_at: str
+    disabled_reason: str
+    id: str
+    kind: str
+    last_success_at: NotRequired[Optional[str]]
+    name: str
+    object: str
+    target: str
+
+
+class DestinationInput(TypedDict, total=False):
+    config: Dict[str, Any]
+    kind: str
+    name: str
+
+
+class DestinationPatch(TypedDict, total=False):
+    config: Dict[str, Any]
+    name: str
+
+
+class Entity(TypedDict):
+    id: str
+    name: str
+    type: str
+
+
+class Event(TypedDict):
+    created_at: str
+    data: Dict[str, Any]
+    id: str
+    object: str
+    type: str
+
+
+class Export(TypedDict):
+    created_at: str
+    download_url: str
+    error: str
+    expires_at: str
+    finished_at: NotRequired[Optional[str]]
+    format: str
+    id: str
+    kind: str
+    object: str
+    status: str
+
+
+class ExportInput(TypedDict, total=False):
+    days: int
+    format: str
+    kind: str
+
+
+class Impact(TypedDict):
+    artist: "Ref"
+    change_id: str
+    days_gone: int
+    lost: NotRequired[Optional[int]]
+    name: str
+    type: str
+
+
+class Import(TypedDict):
+    object: str
+    results: List["ImportResult"]
+    verified: int
+
+
+class ImportArtists(TypedDict, total=False):
+    artists: List["ImportRow"]
+
+
+class ImportResult(TypedDict):
+    artist_id: str
+    error: str
+    name: str
+    spotify_id: str
+    status: str
+
+
+class ImportRow(TypedDict, total=False):
+    confirmed: bool
+    ref: str
+
+
+class Invite(TypedDict):
+    created_at: str
+    email: str
+    expires_at: str
+    id: str
+    object: str
+    role: str
+
+
+class InviteInput(TypedDict, total=False):
+    email: str
+    role: str
+
+
+class Key(TypedDict):
+    artist_ids: List[str]
+    created_at: str
+    expires_at: NotRequired[Optional[str]]
+    id: str
+    name: str
+    object: str
+    prefix: str
+    scopes: List[str]
+
+
+class Limit(TypedDict):
+    limit: int
+    used: int
+
+
+class Me(TypedDict):
+    key: "Key"
+    object: str
+    organization: "Organization"
+    usage: "Usage"
+
+
+class Member(TypedDict):
+    display_name: str
+    email: str
+    joined_at: str
+    object: str
+    role: str
+    user_id: str
+    username: str
+
+
+class Milestone(TypedDict):
+    artist: str
+    eta_days: NotRequired[Optional[int]]
+    kind: str
+    name: str
+    reached: bool
+    target: int
+    value: int
+
+
+class Mover(TypedDict):
+    artist: "Ref"
+    last_7_days: int
+    name: str
+    previous_7_days: int
+    track_id: str
+
+
+class OrgPatch(TypedDict, total=False):
+    name: str
+
+
+class Organization(TypedDict):
+    created_at: str
+    id: str
+    logo_url: str
+    name: str
+    object: str
+    plan: str
+    slug: str
+
+
+class Overview(TypedDict):
+    artist_id: str
+    days: int
+    falling: List["Mover"]
+    followers: int
+    impacts: List["Impact"]
+    listeners: int
+    milestones: List["Milestone"]
+    object: str
+    rising: List["Mover"]
+    streams: int
+    streams_daily: List["DayValue"]
+    streams_prev: NotRequired[Optional[int]]
+
+
+class Plan(TypedDict):
+    api: bool
+    artists: int
+    history_retention_days: int
+    id: str
+    object: str
+    releases_per_artist: int
+    requests_per_hour: int
+    seats: int
+    webhook_endpoints: int
+
+
+class Proof(TypedDict):
+    created_at: str
+    id: str
+    licensor: str
+    link: str
+    object: str
+    release_id: str
+    territory: str
+    title: str
+    valid_until: str
+
+
+class ProofInput(TypedDict, total=False):
+    licensor: str
+    link: str
+    territory: str
+    title: str
+    valid_until: str
+
+
+class Ref(TypedDict):
+    id: str
+    name: str
+    spotify_id: NotRequired[str]
+
+
+class Release(TypedDict):
+    artist: "Ref"
+    c_line: str
+    id: str
+    image_url: str
+    label: str
+    name: str
+    object: str
+    p_line: str
+    proofs: int
+    release_date: str
+    spotify_id: str
+    state: str
+    tracks_offline: int
+    tracks_total: int
+    type: str
+    upc: str
+
+
+class ResolveMany(TypedDict, total=False):
+    ids: List[str]
+    resolved: bool
+
+
+class ResolveResult(TypedDict):
+    ids: List[str]
+    object: str
+    resolved: bool
+
+
+class RoleInput(TypedDict, total=False):
+    role: str
+
+
+class Rule(TypedDict):
+    active: bool
+    artist_ids: List[str]
+    change_types: List[str]
+    created_at: str
+    destination_id: str
+    digest: str
+    id: str
+    label_tag: str
+    locale: NotRequired[Optional[str]]
+    min_severity: str
+    object: str
+
+
+class RuleInput(TypedDict, total=False):
+    artist_ids: List[str]
+    change_types: List[str]
+    destination_id: str
+    digest: str
+    locale: Optional[str]
+    min_severity: str
+
+
+class RulePatch(TypedDict, total=False):
+    active: Optional[bool]
+    artist_ids: Optional[List[str]]
+    change_types: Optional[List[str]]
+    destination_id: Optional[str]
+    digest: Optional[str]
+    locale: Optional[str]
+    min_severity: Optional[str]
+
+
+class TestResult(TypedDict):
+    error: str
+    object: str
+    ok: bool
+
+
+ToolInput = Dict[str, Any]
+
+
+class Track(TypedDict):
+    artist: "Ref"
+    artists: List[str]
+    disc_number: int
+    duration_ms: int
+    explicit: bool
+    id: str
+    isrc: str
+    name: str
+    object: str
+    playable: bool
+    playcount: int
+    release: "Ref"
+    removed_at: NotRequired[Optional[str]]
+    spotify_id: str
+    track_number: int
+
+
+class TrackPlays(TypedDict):
+    days: int
+    object: str
+    plays: List["DayValue"]
+    track_id: str
+
+
+class Trend(TypedDict):
+    artist_id: str
+    buckets: List["TrendBucket"]
+    days: int
+    estimated: bool
+    grain: str
+    object: str
+    songs: List["TrendSong"]
+    streams_prev: NotRequired[Optional[int]]
+
+
+TrendBucket = TypedDict("TrendBucket", {"followers": NotRequired[Optional[int]], "from": str, "listeners": NotRequired[Optional[int]], "streams": int, "streams_total": int, "to": str})
+
+
+class TrendSong(TypedDict):
+    artist: "Ref"
+    name: str
+    plays: List[int]
+    plays_prev: NotRequired[Optional[int]]
+    spotify_id: str
+    total: int
+    track_id: str
+
+
+class Usage(TypedDict):
+    api_rate_per_hour: int
+    artists: "Limit"
+    history_retention_days: int
+    object: str
+    plan: str
+    requests_per_hour: int
+    seats: "Limit"
+    webhook_endpoints: "Limit"
+    writes_per_minute: int
+
+
+class Verification(TypedDict):
+    artist_id: str
+    attest_allowed: bool
+    code: str
+    method: str
+    object: str
+    status: str
+
+
+class Verify(TypedDict, total=False):
+    confirmed: bool
+    method: str
+
+
+class WebhookDelivery(TypedDict):
+    attempts: int
+    created_at: str
+    delivered_at: NotRequired[Optional[str]]
+    duration_ms: NotRequired[Optional[int]]
+    endpoint_id: str
+    error: str
+    event_id: str
+    event_type: str
+    id: str
+    next_attempt_at: NotRequired[Optional[str]]
+    object: str
+    response_status: NotRequired[Optional[int]]
+    status: str
+
+
+class WebhookEndpoint(TypedDict):
+    artist_ids: List[str]
+    created_at: str
+    description: str
+    events: List[str]
+    failing_since: NotRequired[Optional[str]]
+    id: str
+    object: str
+    pause_reason: str
+    paused: bool
+    secret: NotRequired[str]
+    url: str
+
+
+class WebhookInput(TypedDict, total=False):
+    artist_ids: List[str]
+    description: str
+    events: List[str]
+    url: str
+
+
+class WebhookPatch(TypedDict, total=False):
+    artist_ids: Optional[List[str]]
+    description: Optional[str]
+    events: Optional[List[str]]
+    paused: Optional[bool]
+    url: Optional[str]
+

labelsentry-1.0.0/labelsentry/operations.py

@@ -0,0 +1,373 @@
+"""Generated by scripts/generate.py from openapi.json. Do not edit."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Dict, Iterator, Optional
+
+from . import models as m
+
+if TYPE_CHECKING:
+    from .client import LabelSentry
+
+
+class Artists:
+    def __init__(self, client: "LabelSentry") -> None:
+        self._client = client
+
+    def check_verification(self, id: str) -> m.Verification:
+        """Look for the code in the Spotify biography now. Needs ``verification:write``."""
+        return self._client._request("POST", f"/artists/{id}/verification/check", query=None, body=None, unwrap=True)
+
+    def create(self, body: m.AddArtist) -> m.Artist:
+        """Add an artist by Spotify id or link. Needs ``artists:write``."""
+        return self._client._request("POST", "/artists", query=None, body=body, unwrap=True)
+
+    def get(self, id: str) -> m.Artist:
+        """One artist. Needs ``artists:read``."""
+        return self._client._request("GET", f"/artists/{id}", query=None, body=None, unwrap=True)
+
+    def import_(self, body: m.ImportArtists) -> m.Import:
+        """Add up to 500 artists at once, verified directly (Business). Needs ``artists:write``."""
+        return self._client._request("POST", "/artists/import", query=None, body=body, unwrap=True)
+
+    def list(self, *, status: Optional[str] = None, limit: Optional[int] = None) -> Iterator[m.Artist]:
+        """The roster. Needs ``artists:read``."""
+        return self._client._page("/artists", {"status": status, "limit": limit})
+
+    def releases(self, id: str, *, limit: Optional[int] = None) -> Iterator[m.Release]:
+        """An artist's releases, newest first. Needs ``catalog:read``."""
+        return self._client._page(f"/artists/{id}/releases", {"limit": limit})
+
+    def remove(self, id: str) -> m.Deleted:
+        """Remove an artist from the roster. Needs ``artists:write``."""
+        return self._client._request("DELETE", f"/artists/{id}", query=None, body=None, unwrap=True)
+
+    def search(self, *, q: Optional[str] = None) -> Iterator[m.ArtistSearchResult]:
+        """Search Spotify for an artist to add. Needs ``artists:write``."""
+        return self._client._page("/artists/search", {"q": q})
+
+    def stats(self, id: str, *, days: Optional[int] = None) -> m.ArtistStats:
+        """An artist's listeners and followers per day. Needs ``stats:read``."""
+        return self._client._request("GET", f"/artists/{id}/stats", query={"days": days}, body=None, unwrap=True)
+
+    def verification(self, id: str) -> m.Verification:
+        """Where an artist's verification stands. Needs ``artists:read``."""
+        return self._client._request("GET", f"/artists/{id}/verification", query=None, body=None, unwrap=True)
+
+    def verify(self, id: str, body: m.Verify) -> m.Verification:
+        """Verify an artist: confirm the rights, check the biography code, or directly. Needs ``verification:write``."""
+        return self._client._request("POST", f"/artists/{id}/verification", query=None, body=body, unwrap=True)
+
+
+class Audit:
+    def __init__(self, client: "LabelSentry") -> None:
+        self._client = client
+
+    def list(self, *, limit: Optional[int] = None) -> Iterator[m.AuditEntry]:
+        """Who did what and when, API keys included. Needs ``audit:read``."""
+        return self._client._page("/audit", {"limit": limit})
+
+
+class Changes:
+    def __init__(self, client: "LabelSentry") -> None:
+        self._client = client
+
+    def get(self, id: str) -> m.Change:
+        """One change with its details. Needs ``changes:read``."""
+        return self._client._request("GET", f"/changes/{id}", query=None, body=None, unwrap=True)
+
+    def list(self, *, artist_id: Optional[str] = None, type: Optional[str] = None, severity: Optional[str] = None, status: Optional[str] = None, since: Optional[str] = None, until: Optional[str] = None, limit: Optional[int] = None) -> Iterator[m.Change]:
+        """Changes, newest first. Needs ``changes:read``."""
+        return self._client._page("/changes", {"artist_id": artist_id, "type": type, "severity": severity, "status": status, "since": since, "until": until, "limit": limit})
+
+    def reopen(self, id: str) -> m.Change:
+        """Open a resolved change again. Needs ``changes:write``."""
+        return self._client._request("DELETE", f"/changes/{id}/resolve", query=None, body=None, unwrap=True)
+
+    def resolve(self, id: str) -> m.Change:
+        """Mark a change as resolved. Needs ``changes:write``."""
+        return self._client._request("POST", f"/changes/{id}/resolve", query=None, body=None, unwrap=True)
+
+    def resolve_many(self, body: m.ResolveMany) -> m.ResolveResult:
+        """Resolve or reopen up to 200 changes. Needs ``changes:write``."""
+        return self._client._request("POST", "/changes/resolve", query=None, body=body, unwrap=True)
+
+    def types(self) -> Iterator[m.ChangeType]:
+        """Every change type with its severity. Needs ``changes:read``."""
+        return self._client._page("/change-types", None)
+
+
+class Destinations:
+    def __init__(self, client: "LabelSentry") -> None:
+        self._client = client
+
+    def create(self, body: m.DestinationInput) -> m.Destination:
+        """Add a destination. Needs ``alerts:write``."""
+        return self._client._request("POST", "/destinations", query=None, body=body, unwrap=True)
+
+    def deliveries(self, *, destination_id: Optional[str] = None, limit: Optional[int] = None) -> Iterator[m.AlertDelivery]:
+        """Alerts sent, newest first. Needs ``alerts:read``."""
+        return self._client._page("/deliveries", {"destination_id": destination_id, "limit": limit})
+
+    def list(self) -> Iterator[m.Destination]:
+        """Where alerts go. Needs ``alerts:read``."""
+        return self._client._page("/destinations", None)
+
+    def remove(self, id: str) -> m.Deleted:
+        """Delete a destination and its rules. Needs ``alerts:write``."""
+        return self._client._request("DELETE", f"/destinations/{id}", query=None, body=None, unwrap=True)
+
+    def test(self, id: str) -> m.TestResult:
+        """Send a test alert. Needs ``alerts:write``."""
+        return self._client._request("POST", f"/destinations/{id}/test", query=None, body=None, unwrap=True)
+
+    def update(self, id: str, body: m.DestinationPatch) -> m.Destination:
+        """Rename, change or pause a destination. Needs ``alerts:write``."""
+        return self._client._request("PATCH", f"/destinations/{id}", query=None, body=body, unwrap=True)
+
+
+class Events:
+    def __init__(self, client: "LabelSentry") -> None:
+        self._client = client
+
+    def get(self, id: str) -> m.Event:
+        """One event. Needs ``changes:read``."""
+        return self._client._request("GET", f"/events/{id}", query=None, body=None, unwrap=True)
+
+    def list(self, *, type: Optional[str] = None, artist_id: Optional[str] = None, since: Optional[str] = None, order: Optional[str] = None, limit: Optional[int] = None) -> Iterator[m.Event]:
+        """Events of the last 30 days, the same ones webhooks send. Needs ``changes:read``."""
+        return self._client._page("/events", {"type": type, "artist_id": artist_id, "since": since, "order": order, "limit": limit})
+
+
+class Exports:
+    def __init__(self, client: "LabelSentry") -> None:
+        self._client = client
+
+    def create(self, body: m.ExportInput) -> m.Export:
+        """Start an export; export.ready is sent when it is done. Needs ``exports:write``."""
+        return self._client._request("POST", "/exports", query=None, body=body, unwrap=True)
+
+    def download(self, id: str) -> str:
+        """The export's file, CSV or JSON. Needs ``exports:write``."""
+        return self._client._text("GET", f"/exports/{id}/download", None)
+
+    def get(self, id: str) -> m.Export:
+        """Where an export stands. Needs ``exports:write``."""
+        return self._client._request("GET", f"/exports/{id}", query=None, body=None, unwrap=True)
+
+
+class Invites:
+    def __init__(self, client: "LabelSentry") -> None:
+        self._client = client
+
+    def create(self, body: m.InviteInput) -> m.Invite:
+        """Invite someone by email. Needs ``members:write``."""
+        return self._client._request("POST", "/invites", query=None, body=body, unwrap=True)
+
+    def list(self) -> Iterator[m.Invite]:
+        """Open invites. Needs ``members:read``."""
+        return self._client._page("/invites", None)
+
+    def revoke(self, id: str) -> m.Deleted:
+        """Withdraw an invite. Needs ``members:write``."""
+        return self._client._request("DELETE", f"/invites/{id}", query=None, body=None, unwrap=True)
+
+
+class Members:
+    def __init__(self, client: "LabelSentry") -> None:
+        self._client = client
+
+    def list(self) -> Iterator[m.Member]:
+        """Members with their role. Needs ``members:read``."""
+        return self._client._page("/members", None)
+
+    def remove(self, id: str) -> m.Deleted:
+        """Remove a member. Needs ``members:write``."""
+        return self._client._request("DELETE", f"/members/{id}", query=None, body=None, unwrap=True)
+
+    def update(self, id: str, body: m.RoleInput) -> m.Member:
+        """Change a member's role. Needs ``members:write``."""
+        return self._client._request("PATCH", f"/members/{id}", query=None, body=body, unwrap=True)
+
+
+class Organization:
+    def __init__(self, client: "LabelSentry") -> None:
+        self._client = client
+
+    def get(self) -> m.Organization:
+        """The organization. Needs ``organization:read``."""
+        return self._client._request("GET", "/organization", query=None, body=None, unwrap=True)
+
+    def me(self) -> m.Me:
+        """The key, its rights, the organization and its usage."""
+        return self._client._request("GET", "/me", query=None, body=None, unwrap=True)
+
+    def plans(self) -> Iterator[m.Plan]:
+        """Every plan with its limits. Needs ``organization:read``."""
+        return self._client._page("/plans", None)
+
+    def update(self, body: m.OrgPatch) -> m.Organization:
+        """Rename the organization. Needs ``organization:write``."""
+        return self._client._request("PATCH", "/organization", query=None, body=body, unwrap=True)
+
+    def usage(self) -> m.Usage:
+        """Artists, seats, requests and endpoints used against the plan. Needs ``organization:read``."""
+        return self._client._request("GET", "/usage", query=None, body=None, unwrap=True)
+
+
+class Proofs:
+    def __init__(self, client: "LabelSentry") -> None:
+        self._client = client
+
+    def remove(self, id: str) -> m.Deleted:
+        """Remove a proof. Needs ``catalog:write``."""
+        return self._client._request("DELETE", f"/proofs/{id}", query=None, body=None, unwrap=True)
+
+    def update(self, id: str, body: m.ProofInput) -> m.Proof:
+        """Change a proof. Needs ``catalog:write``."""
+        return self._client._request("PATCH", f"/proofs/{id}", query=None, body=body, unwrap=True)
+
+
+class Releases:
+    def __init__(self, client: "LabelSentry") -> None:
+        self._client = client
+
+    def add_proof(self, id: str, body: m.ProofInput) -> m.Proof:
+        """Note a proof of rights on a release. Needs ``catalog:write``."""
+        return self._client._request("POST", f"/releases/{id}/proofs", query=None, body=body, unwrap=True)
+
+    def get(self, id: str) -> m.Release:
+        """One release. Needs ``catalog:read``."""
+        return self._client._request("GET", f"/releases/{id}", query=None, body=None, unwrap=True)
+
+    def list(self, *, artist_id: Optional[str] = None, state: Optional[str] = None, type: Optional[str] = None, label: Optional[str] = None, from_: Optional[str] = None, to: Optional[str] = None, q: Optional[str] = None, limit: Optional[int] = None) -> Iterator[m.Release]:
+        """Every release of the roster. Needs ``catalog:read``."""
+        return self._client._page("/releases", {"artist_id": artist_id, "state": state, "type": type, "label": label, "from": from_, "to": to, "q": q, "limit": limit})
+
+    def proofs(self, id: str) -> Iterator[m.Proof]:
+        """Proofs of rights noted on a release. Needs ``catalog:read``."""
+        return self._client._page(f"/releases/{id}/proofs", None)
+
+    def tracks(self, id: str) -> Iterator[m.Track]:
+        """A release's tracks in their order. Needs ``catalog:read``."""
+        return self._client._page(f"/releases/{id}/tracks", None)
+
+
+class Rules:
+    def __init__(self, client: "LabelSentry") -> None:
+        self._client = client
+
+    def create(self, body: m.RuleInput) -> m.Rule:
+        """Add a rule. Needs ``alerts:write``."""
+        return self._client._request("POST", "/rules", query=None, body=body, unwrap=True)
+
+    def list(self) -> Iterator[m.Rule]:
+        """Which changes go to which destination, and when. Needs ``alerts:read``."""
+        return self._client._page("/rules", None)
+
+    def remove(self, id: str) -> m.Deleted:
+        """Delete a rule. Needs ``alerts:write``."""
+        return self._client._request("DELETE", f"/rules/{id}", query=None, body=None, unwrap=True)
+
+    def update(self, id: str, body: m.RulePatch) -> m.Rule:
+        """Change a rule. Needs ``alerts:write``."""
+        return self._client._request("PATCH", f"/rules/{id}", query=None, body=body, unwrap=True)
+
+
+class Stats:
+    def __init__(self, client: "LabelSentry") -> None:
+        self._client = client
+
+    def overview(self, *, days: Optional[int] = None, artist_id: Optional[str] = None) -> m.Overview:
+        """What stands out: offline losses, risers, fallers, milestones. Needs ``stats:read``."""
+        return self._client._request("GET", "/stats/overview", query={"days": days, "artist_id": artist_id}, body=None, unwrap=True)
+
+    def trend(self, *, days: Optional[int] = None, artist_id: Optional[str] = None) -> m.Trend:
+        """Streams, listeners and followers over 7, 28 or 90 days, with every song. Needs ``stats:read``."""
+        return self._client._request("GET", "/stats/trend", query={"days": days, "artist_id": artist_id}, body=None, unwrap=True)
+
+
+class Tools:
+    def __init__(self, client: "LabelSentry") -> None:
+        self._client = client
+
+    def history(self) -> Dict[str, Any]:
+        """Earlier tool queries. Needs ``tools:use``."""
+        return self._client._request("GET", "/tools/history", query=None, body=None, unwrap=False)
+
+    def list(self, body: m.ToolInput) -> Dict[str, Any]:
+        """ISRC by Track, for a list. Needs ``tools:use``."""
+        return self._client._request("POST", "/tools/list", query=None, body=body, unwrap=False)
+
+    def lookup(self, body: m.ToolInput) -> Dict[str, Any]:
+        """Metadata Lookup for a track or release link. Needs ``tools:use``."""
+        return self._client._request("POST", "/tools/lookup", query=None, body=body, unwrap=False)
+
+    def reverse(self, body: m.ToolInput) -> Dict[str, Any]:
+        """Track by ISRC. Needs ``tools:use``."""
+        return self._client._request("POST", "/tools/reverse", query=None, body=body, unwrap=False)
+
+    def usage(self) -> Dict[str, Any]:
+        """Allowance and use of the tools. Needs ``tools:use``."""
+        return self._client._request("GET", "/tools", query=None, body=None, unwrap=False)
+
+
+class Tracks:
+    def __init__(self, client: "LabelSentry") -> None:
+        self._client = client
+
+    def get(self, id: str) -> m.Track:
+        """One track. Needs ``catalog:read``."""
+        return self._client._request("GET", f"/tracks/{id}", query=None, body=None, unwrap=True)
+
+    def list(self, *, isrc: Optional[str] = None, artist_id: Optional[str] = None, limit: Optional[int] = None) -> Iterator[m.Track]:
+        """Find tracks by ISRC or artist. Needs ``catalog:read``."""
+        return self._client._page("/tracks", {"isrc": isrc, "artist_id": artist_id, "limit": limit})
+
+    def plays(self, id: str, *, days: Optional[int] = None) -> m.TrackPlays:
+        """A track's plays per day, or per week over 90 days. Needs ``stats:read``."""
+        return self._client._request("GET", f"/tracks/{id}/plays", query={"days": days}, body=None, unwrap=True)
+
+
+class Webhooks:
+    def __init__(self, client: "LabelSentry") -> None:
+        self._client = client
+
+    def create(self, body: m.WebhookInput) -> m.WebhookEndpoint:
+        """Add an endpoint; the secret is in this answer only. Needs ``webhooks:write``."""
+        return self._client._request("POST", "/webhooks", query=None, body=body, unwrap=True)
+
+    def deliveries(self, id: str, *, limit: Optional[int] = None) -> Iterator[m.WebhookDelivery]:
+        """Deliveries to an endpoint, newest first. Needs ``webhooks:read``."""
+        return self._client._page(f"/webhooks/{id}/deliveries", {"limit": limit})
+
+    def get(self, id: str) -> m.WebhookEndpoint:
+        """One endpoint. Needs ``webhooks:read``."""
+        return self._client._request("GET", f"/webhooks/{id}", query=None, body=None, unwrap=True)
+
+    def list(self) -> Iterator[m.WebhookEndpoint]:
+        """Webhook endpoints. Needs ``webhooks:read``."""
+        return self._client._page("/webhooks", None)
+
+    def redeliver(self, id: str) -> m.WebhookDelivery:
+        """Send a delivery again. Needs ``webhooks:write``."""
+        return self._client._request("POST", f"/webhooks/deliveries/{id}/redeliver", query=None, body=None, unwrap=True)
+
+    def remove(self, id: str) -> m.Deleted:
+        """Delete an endpoint. Needs ``webhooks:write``."""
+        return self._client._request("DELETE", f"/webhooks/{id}", query=None, body=None, unwrap=True)
+
+    def rotate_secret(self, id: str) -> m.WebhookEndpoint:
+        """New secret; the old one still signs for 24 hours. Needs ``webhooks:write``."""
+        return self._client._request("POST", f"/webhooks/{id}/rotate-secret", query=None, body=None, unwrap=True)
+
+    def test(self, id: str) -> m.WebhookDelivery:
+        """Send a ping event. Needs ``webhooks:write``."""
+        return self._client._request("POST", f"/webhooks/{id}/test", query=None, body=None, unwrap=True)
+
+    def update(self, id: str, body: m.WebhookPatch) -> m.WebhookEndpoint:
+        """Change events, artists or address, pause or resume. Needs ``webhooks:write``."""
+        return self._client._request("PATCH", f"/webhooks/{id}", query=None, body=body, unwrap=True)
+
+
+RESOURCES = {"artists": Artists, "audit": Audit, "changes": Changes, "destinations": Destinations, "events": Events, "exports": Exports, "invites": Invites, "members": Members, "organization": Organization, "proofs": Proofs, "releases": Releases, "rules": Rules, "stats": Stats, "tools": Tools, "tracks": Tracks, "webhooks": Webhooks}

labelsentry-1.0.0/labelsentry/webhooks.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Optional, Union
+
+from .models import Event
+
+TOLERANCE = 300
+"""How old a delivery may be before it is refused, in seconds."""
+
+
+def verify_webhook(raw_body: Union[str, bytes], signature: str, secret: str, now: Optional[float] = None) -> Event:
+    """Checks the X-LabelSentry-Signature header against the raw request body
+    and returns the event. Raises ValueError when it does not match or is too
+    old. Pass the body exactly as received, before parsing it."""
+    body = raw_body.decode() if isinstance(raw_body, bytes) else raw_body
+    t, sigs = "", []
+    for part in signature.split(","):
+        k, _, v = part.partition("=")
+        if k == "t":
+            t = v
+        elif k == "v1":
+            sigs.append(v)
+    if not t or not sigs:
+        raise ValueError("malformed signature header")
+    if abs((now or time.time()) - int(t)) > TOLERANCE:
+        raise ValueError("delivery is too old")
+    want = hmac.new(secret.encode(), f"{t}.{body}".encode(), hashlib.sha256).hexdigest()
+    if not any(hmac.compare_digest(want, s) for s in sigs):
+        raise ValueError("signature does not match")
+    return json.loads(body)

labelsentry-1.0.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "labelsentry"
+version = "1.0.0"
+description = "The LabelSentry API for Python"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+dependencies = ["typing_extensions>=4.7; python_version < '3.11'"]
+
+[project.urls]
+Documentation = "https://labelsentry.com/docs/api"
+Source = "https://github.com/LabelSentrycom/labelsentry-sdks"
+
+[tool.hatch.build.targets.wheel]
+packages = ["labelsentry"]

labelsentry-1.0.0/tests/test_sdk.py

@@ -0,0 +1,65 @@
+import hashlib
+import hmac
+import json
+import sys
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+from labelsentry import LabelSentry, LabelSentryError, verify_webhook  # noqa: E402
+
+
+class Handler(BaseHTTPRequestHandler):
+    calls = 0
+
+    def log_message(self, *args):
+        pass
+
+    def _send(self, status, body, headers=None):
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        for k, v in (headers or {}).items():
+            self.send_header(k, v)
+        self.end_headers()
+        self.wfile.write(json.dumps(body).encode())
+
+    def do_GET(self):
+        Handler.calls += 1
+        if Handler.calls == 1:
+            return self._send(429, {}, {"Retry-After": "0"})
+        if "cursor=c2" in self.path:
+            return self._send(200, {"data": [{"id": "a2", "name": "Two"}], "next_cursor": None})
+        return self._send(200, {"data": [{"id": "a1", "name": "One"}], "next_cursor": "c2"})
+
+    def do_POST(self):
+        assert self.headers.get("Idempotency-Key")
+        self._send(404, {"error": {"code": "not_found", "message": "no change", "request_id": "req_1"}})
+
+
+class SDKTest(unittest.TestCase):
+    def test_pages_retries_errors(self):
+        srv = HTTPServer(("127.0.0.1", 0), Handler)
+        threading.Thread(target=srv.serve_forever, daemon=True).start()
+        ls = LabelSentry("k", base_url=f"http://127.0.0.1:{srv.server_port}")
+        self.assertEqual([a["name"] for a in ls.artists.list()], ["One", "Two"])
+        with self.assertRaises(LabelSentryError) as cm:
+            ls.changes.resolve("x")
+        self.assertEqual((cm.exception.code, cm.exception.request_id), ("not_found", "req_1"))
+        srv.shutdown()
+
+    def test_verify_webhook(self):
+        body = json.dumps({"id": "e1", "type": "ping", "created_at": "2026-10-22T00:00:00Z", "data": {}})
+        t = 1792700000
+        sig = hmac.new(b"whsec_a", f"{t}.{body}".encode(), hashlib.sha256).hexdigest()
+        header = f"t={t},v1={sig}"
+        self.assertEqual(verify_webhook(body, header, "whsec_a", now=t)["type"], "ping")
+        with self.assertRaises(ValueError):
+            verify_webhook(body, header, "whsec_b", now=t)
+        with self.assertRaises(ValueError):
+            verify_webhook(body, header, "whsec_a", now=t + 3600)
+
+
+if __name__ == "__main__":
+    unittest.main()