simklcli 0.1.0__py3-none-any.whl

simklcli/output.py

@@ -0,0 +1,55 @@
+"""Keep argument-validation failures machine readable when --json is requested."""
+
+from __future__ import annotations
+
+import json
+import sys
+from collections.abc import Sequence
+from typing import Any
+
+from typer import Abort
+from typer import _click as click
+from typer.core import TyperGroup
+
+
+class JsonGroup(TyperGroup):
+    def main(
+        self,
+        args: Sequence[str] | None = None,
+        prog_name: str | None = None,
+        complete_var: str | None = None,
+        standalone_mode: bool = True,
+        windows_expand_args: bool = True,
+        **extra: Any,
+    ) -> Any:
+        arguments = list(sys.argv[1:] if args is None else args)
+        try:
+            result = super().main(
+                args=arguments,
+                prog_name=prog_name,
+                complete_var=complete_var,
+                standalone_mode=False,
+                windows_expand_args=windows_expand_args,
+                **extra,
+            )
+        except click.ClickException as exc:
+            if "--json" in arguments:
+                click.echo(
+                    json.dumps({"error": "invalid_arguments", "message": exc.format_message()})
+                )
+            exc.show()
+            if standalone_mode:
+                raise SystemExit(exc.exit_code) from None
+            raise
+        except Abort as exc:
+            if "--json" in arguments:
+                click.echo(json.dumps({"error": "cancelled", "message": "Aborted."}))
+            click.echo("Aborted!", err=True)
+            if standalone_mode:
+                raise SystemExit(
+                    130 if isinstance(exc.__cause__, KeyboardInterrupt) else 1
+                ) from None
+            raise
+        if standalone_mode:
+            raise SystemExit(result if isinstance(result, int) else 0)
+        return result

simklcli/rate_control.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+from filelock import FileLock
+
+from simklcli.filesystem import atomic_write_json
+
+
+class CrossProcessRateGate:
+    """Space Simkl requests across processes by application or account scope."""
+
+    def __init__(
+        self,
+        root: Path,
+        *,
+        client_id: str,
+        clock: Callable[[], float] = time.time,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self._root = root
+        self._client_id = client_id
+        self._clock = clock
+        self._sleep = sleep
+        self._accounts: dict[str, int] = {}
+
+    def bind_account(self, access_token: str, account_id: int) -> None:
+        # Carry the initial token-validation cadence into the validated account gate.
+        self._root.mkdir(mode=0o700, parents=True, exist_ok=True)
+        token_key = hashlib.sha256(f"account:{access_token}".encode()).hexdigest()
+        account_key = hashlib.sha256(f"account:{account_id}".encode()).hexdigest()
+        path = self._root / f"{account_key}.json"
+        with FileLock(self._root / f"{account_key}.lock", mode=0o600):
+            state = _read_state(path)
+            token_state = _read_state(self._root / f"{token_key}.json")
+            for field, value in token_state.items():
+                state[field] = max(value, state.get(field, value))
+            atomic_write_json(path, state)
+            atomic_write_json(self._root / f"{token_key}.account.json", {"account_id": account_id})
+        self._accounts[access_token] = account_id
+
+    def remembered_account_id(self, access_token: str) -> int | None:
+        key = hashlib.sha256(f"account:{access_token}".encode()).hexdigest()
+        try:
+            payload = json.loads((self._root / f"{key}.account.json").read_text(encoding="utf-8"))
+            account_id = payload["account_id"]
+            if isinstance(account_id, int) and not isinstance(account_id, bool) and account_id > 0:
+                return account_id
+        except (OSError, KeyError, TypeError, ValueError):
+            pass
+        return None
+
+    @contextmanager
+    def limit(self, method: str, access_token: str | None) -> Iterator[None]:
+        interval = 1.0 if method == "POST" else 0.1
+        account_id = (
+            None
+            if access_token is None
+            else (self._accounts.get(access_token) or self.remembered_account_id(access_token))
+        )
+        scope = (
+            f"account:{account_id if account_id is not None else access_token}"
+            if access_token is not None
+            else f"application:{self._client_id}"
+        )
+        key = hashlib.sha256(scope.encode()).hexdigest()
+        self._root.mkdir(mode=0o700, parents=True, exist_ok=True)
+        state_path = self._root / f"{key}.json"
+        lock = FileLock(self._root / f"{key}.lock")
+        with lock:
+            state = _read_state(state_path)
+            field = "last_post" if method == "POST" else "last_get"
+            previous = state.get(field)
+            if previous is not None:
+                delay = previous + interval - self._clock()
+                if delay > 0:
+                    self._sleep(delay)
+            state[field] = self._clock()
+            atomic_write_json(state_path, state)
+            yield
+
+
+def _read_state(path: Path) -> dict[str, float]:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, OSError, ValueError):
+        return {}
+    if not isinstance(payload, dict):
+        return {}
+    return {
+        key: float(value)
+        for key, value in payload.items()
+        if key in {"last_get", "last_post"} and isinstance(value, int | float)
+    }

simklcli/runtime.py

@@ -0,0 +1,242 @@
+from __future__ import annotations
+
+import os
+import time
+import webbrowser
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import httpx
+import keyring
+from platformdirs import user_config_path, user_data_path
+
+from simklcli.rate_control import CrossProcessRateGate
+from simklcli.snapshots import LibrarySnapshotStore
+from simklcli.storage import (
+    Credential,
+    CredentialRepository,
+    CredentialStorageError,
+    EmptyKeyring,
+    Keyring,
+)
+
+if TYPE_CHECKING:
+    from simklcli.api import SimklClient
+
+
+# Public AUTH V2 "TV, devices & command line" app ID for simklcli. It carries no
+# secret: Simkl refuses user-scoped requests without a user Access Token.
+DEFAULT_CLIENT_ID = "6d50d4e07aa47b6409a4cd0c2b16729fab7ddc7f5c111fcba7d0001ac054c164"
+
+
+@dataclass
+class Runtime:
+    credentials: CredentialRepository
+    snapshots: LibrarySnapshotStore
+    environ: Mapping[str, str]
+    data_dir: Path
+    transport: httpx.BaseTransport | None
+    rate_gate: CrossProcessRateGate | None
+    sleep: Callable[[float], None]
+    monotonic: Callable[[], float]
+    open_browser: Callable[[str], bool]
+    interactive: bool
+    clock: Callable[[], float] = time.time
+
+    def client_id(self) -> str:
+        configured = self.environ.get("SIMKL_CLIENT_ID", "").strip()
+        if configured:
+            return configured
+        if not self.environ.get("SIMKL_ACCESS_TOKEN", "").strip():
+            try:
+                stored = self.credentials.read()
+            except CredentialStorageError:
+                stored = None
+            if stored is not None and stored.client_id:
+                return stored.client_id
+        return DEFAULT_CLIENT_ID
+
+    def identity_gate(self) -> CrossProcessRateGate:
+        return self.rate_gate or CrossProcessRateGate(
+            self.data_dir / "rate-gates",
+            client_id=self.client_id(),
+        )
+
+    def api_client(self) -> SimklClient:
+        from simklcli.api import SimklClient
+
+        if self.rate_gate is not None and not self.environ.get("SIMKL_ACCESS_TOKEN", "").strip():
+            try:
+                stored = self.credentials.read()
+            except CredentialStorageError:
+                stored = None
+            if stored is not None and stored.account is not None:
+                self.rate_gate.bind_account(stored.access_token, stored.account.id)
+        return SimklClient(
+            client_id=self.client_id(),
+            transport=self.transport,
+            sleep=self.sleep,
+            rate_gate=self.rate_gate,
+            clock=self.clock,
+        )
+
+    def authenticated_client(self) -> tuple[Credential, SimklClient]:
+        from simklcli.api import SimklResponseError
+        from simklcli.storage import CredentialSource
+
+        credential = self.active_credential()
+        if credential is None:
+            raise SimklResponseError(
+                "No Access Token is available. Run simkl auth login explicitly."
+            )
+        if credential.source is not CredentialSource.ENVIRONMENT and credential.account is None:
+            raise SimklResponseError(
+                "The active credential has no validated Authenticated Account."
+            )
+        if credential.legacy or credential.invalidated:
+            raise SimklResponseError(
+                "This account requires AUTH V2 authorization. Run simkl auth login; "
+                "the Library Snapshot will be retained."
+            )
+        if credential.source is CredentialSource.ENVIRONMENT:
+            # Recognize genuine V1 credentials without accepting them on a V2 registration.
+            token = credential.access_token
+            if len(token) == 64 and all(c in "0123456789abcdef" for c in token):
+                raise SimklResponseError("SIMKL_ACCESS_TOKEN is a V1 token; authorize your V2 app.")
+        elif credential.client_id != self.client_id():
+            raise SimklResponseError(
+                "SIMKL_CLIENT_ID differs from the stored token's app; restore it or log out "
+                "before authorizing a different app."
+            )
+        api = self.api_client()
+        refresh = None
+        if credential.source is not CredentialSource.ENVIRONMENT:
+            refresh = self._refresh_credential
+            if credential.expires_at is not None and credential.expires_at <= self.clock() + 60:
+                self._refresh_credential(credential.access_token)
+                credential = self.credentials.read() or credential
+        api.configure_auth(credential.access_token, refresh)
+        if self.rate_gate is not None and credential.account is not None:
+            self.rate_gate.bind_account(credential.access_token, credential.account.id)
+        return credential, api
+
+    def _refresh_credential(self, failed_token: str) -> str:
+        from simklcli.api import InvalidAccessTokenError, OAuthGrantError, SimklResponseError
+
+        with self.credentials.account_transaction():
+            credential = self.credentials.read()
+            if credential is None or credential.invalidated or credential.refresh_token is None:
+                raise InvalidAccessTokenError(
+                    "Refresh credentials are unavailable; authorize again."
+                )
+            if credential.client_id != self.client_id():
+                raise SimklResponseError(
+                    "The stored token belongs to a different client registration."
+                )
+            # Another invocation may already have refreshed while this one waited for the lock.
+            if credential.access_token != failed_token:
+                return credential.access_token
+            if (
+                credential.refresh_expires_at is None
+                or credential.refresh_expires_at <= self.clock()
+            ):
+                raise InvalidAccessTokenError("The Refresh Token expired; authorize again.")
+            api = self.api_client()
+            try:
+                pair = api.refresh_tokens(credential.refresh_token)
+            except OAuthGrantError as exc:
+                if exc.error == "invalid_grant":
+                    raise InvalidAccessTokenError(
+                        "The Refresh Token is invalid or revoked."
+                    ) from exc
+                raise
+            account = api.get_authenticated_account(pair.access_token)
+            if credential.account is None or account.id != credential.account.id:
+                raise SimklResponseError(
+                    "Refreshed credentials did not match the Authenticated Account."
+                )
+            updated = replace(
+                credential,
+                access_token=pair.access_token,
+                refresh_token=pair.refresh_token,
+                expires_at=pair.expires_at,
+                refresh_expires_at=pair.refresh_expires_at,
+                scope=pair.scope,
+                account=account,
+            )
+            self.credentials.save(updated)
+            if self.rate_gate is not None:
+                self.rate_gate.bind_account(pair.access_token, account.id)
+            return pair.access_token
+
+    def active_credential(self) -> Credential | None:
+        token = self.environ.get("SIMKL_ACCESS_TOKEN", "").strip()
+        if token:
+            from simklcli.storage import CredentialSource
+
+            return Credential(
+                access_token=token,
+                source=CredentialSource.ENVIRONMENT,
+                account=None,
+            )
+        return self.credentials.read()
+
+    @classmethod
+    def for_testing(
+        cls,
+        *,
+        config_dir: Path,
+        data_dir: Path,
+        environ: Mapping[str, str] | None = None,
+        transport: httpx.BaseTransport | None = None,
+        rate_gate: CrossProcessRateGate | None = None,
+        sleep: Callable[[float], None] = time.sleep,
+        monotonic: Callable[[], float] = time.monotonic,
+        open_browser: Callable[[str], bool] = webbrowser.open,
+        interactive: bool = False,
+        clock: Callable[[], float] = time.time,
+    ) -> Runtime:
+        return cls(
+            credentials=CredentialRepository(config_dir, EmptyKeyring()),
+            snapshots=LibrarySnapshotStore(data_dir),
+            environ={"SIMKL_CLIENT_ID": "test-v2-client", **(environ or {})},
+            data_dir=data_dir,
+            transport=transport or httpx.MockTransport(_unexpected_test_request),
+            rate_gate=rate_gate,
+            sleep=sleep,
+            monotonic=monotonic,
+            open_browser=open_browser,
+            interactive=interactive,
+            clock=clock,
+        )
+
+
+def default_runtime() -> Runtime:
+    config_dir = Path(user_config_path("simklcli", appauthor=False))
+    data_dir = Path(user_data_path("simklcli", appauthor=False))
+    backend: Keyring = keyring.get_keyring()
+    client_id = os.environ.get("SIMKL_CLIENT_ID", "").strip() or DEFAULT_CLIENT_ID
+    return Runtime(
+        credentials=CredentialRepository(config_dir, backend),
+        snapshots=LibrarySnapshotStore(data_dir),
+        environ=os.environ,
+        data_dir=data_dir,
+        transport=None,
+        rate_gate=CrossProcessRateGate(data_dir / "rate-gates", client_id=client_id),
+        sleep=time.sleep,
+        monotonic=time.monotonic,
+        open_browser=webbrowser.open,
+        interactive=_is_interactive(),
+    )
+
+
+def _unexpected_test_request(request: httpx.Request) -> httpx.Response:
+    raise AssertionError(f"No authored response exists for {request.method} {request.url.path}.")
+
+
+def _is_interactive() -> bool:
+    import sys
+
+    return sys.stdin.isatty() and sys.stdout.isatty()

simklcli/snapshots.py

@@ -0,0 +1,162 @@
+import json
+from collections.abc import Iterator
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from filelock import FileLock
+
+from simklcli.filesystem import atomic_write_bytes, atomic_write_json
+from simklcli.media import LibraryEntry, ListStatus, Media, MediaKind, WatchedEpisode, positive_int
+
+
+@dataclass
+class LibrarySnapshot:
+    account_id: int
+    entries: dict[int, LibraryEntry] = field(default_factory=dict)
+    activities: dict[str, Any] = field(default_factory=dict)
+    complete: bool = False
+    dirty: bool = False
+    reconciled_at: float = 0.0
+
+    def payload(self) -> dict[str, Any]:
+        return {
+            "version": 1,
+            "account_id": self.account_id,
+            "entries": [entry.payload() for entry in self.entries.values()],
+            "activities": self.activities,
+            "complete": self.complete,
+            "dirty": self.dirty,
+            "reconciled_at": self.reconciled_at,
+        }
+
+
+class LibrarySnapshotStore:
+    """Own per-account Library Snapshot paths and locking."""
+
+    def __init__(self, data_dir: Path) -> None:
+        self._data_dir = data_dir
+        self._locks: dict[int, FileLock] = {}
+
+    def lock(self, account_id: int) -> FileLock:
+        lock_dir = self._data_dir / "snapshot-locks"
+        lock_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
+        if account_id not in self._locks:
+            self._locks[account_id] = FileLock(lock_dir / f"{account_id}.lock", mode=0o600)
+        return self._locks[account_id]
+
+    def load(self, account_id: int) -> LibrarySnapshot | None:
+        with self.lock(account_id):
+            try:
+                payload = json.loads(self.path(account_id).read_text(encoding="utf-8"))
+                if payload["version"] != 1 or payload["account_id"] != account_id:
+                    return None
+                if (
+                    not isinstance(payload["complete"], bool)
+                    or not isinstance(payload["dirty"], bool)
+                    or not isinstance(payload["activities"], dict)
+                    or not isinstance(payload["reconciled_at"], int | float)
+                ):
+                    return None
+                entries = {}
+                for row in payload["entries"]:
+                    kind = MediaKind(row["kind"])
+                    item = Media.from_catalog(
+                        {
+                            "ids": {"simkl": row["simkl_id"]},
+                            "title": row["title"],
+                            "year": row["year"],
+                        },
+                        kind,
+                    )
+                    # Reuse the API validators and strip any unexpected catalog fields.
+                    parsed = LibraryEntry.from_server(
+                        {
+                            "movie" if kind is MediaKind.MOVIE else "show": {
+                                "ids": {"simkl": item.simkl_id},
+                                "title": item.title,
+                                "year": item.year,
+                            },
+                            "status": ListStatus(row["list_status"]).api_value,
+                            "user_rating": row["user_rating"],
+                            "last_watched_at": row["last_watched_at"],
+                            "watched_episodes_count": row["watched_episodes_count"],
+                            "seasons": [
+                                {
+                                    "number": e["season"] if e["season"] is not None else 1,
+                                    "episodes": [
+                                        {"number": e["number"], "watched_at": e["watched_at"]}
+                                    ],
+                                }
+                                for e in row["episodes"]
+                            ],
+                        },
+                        kind,
+                    )
+                    if not isinstance(row["watched"], bool):
+                        return None
+                    entries[item.simkl_id] = LibraryEntry(
+                        item,
+                        parsed.list_status,
+                        row["watched"],
+                        parsed.last_watched_at,
+                        parsed.user_rating,
+                        tuple(
+                            WatchedEpisode(positive_int(e["number"]), e["season"], e["watched_at"])
+                            for e in row["episodes"]
+                        ),
+                        parsed.watched_episodes_count,
+                    )
+                if payload["complete"] and "all" not in payload["activities"]:
+                    return None
+                return LibrarySnapshot(
+                    account_id,
+                    entries,
+                    payload["activities"],
+                    payload["complete"],
+                    payload["dirty"] or self.dirty_path(account_id).exists(),
+                    payload["reconciled_at"],
+                )
+            except (OSError, ValueError, KeyError, TypeError, AttributeError):
+                return None
+
+    def save(self, snapshot: LibrarySnapshot) -> None:
+        with self.lock(snapshot.account_id):
+            atomic_write_json(self.path(snapshot.account_id), snapshot.payload())
+            if not snapshot.dirty:
+                self.dirty_path(snapshot.account_id).unlink(missing_ok=True)
+
+    def path(self, account_id: int) -> Path:
+        return self._data_dir / "accounts" / str(account_id) / "library.json"
+
+    def dirty_path(self, account_id: int) -> Path:
+        return self._data_dir / "snapshot-locks" / f"{account_id}.dirty"
+
+    def mark_dirty(self, account_id: int) -> None:
+        with self.lock(account_id):
+            atomic_write_bytes(self.dirty_path(account_id), b"1")
+
+    def delete(self, account_id: int) -> None:
+        with self.lock(account_id):
+            self.path(account_id).unlink(missing_ok=True)
+            self.dirty_path(account_id).unlink(missing_ok=True)
+
+    @contextmanager
+    def reversible_delete(self, account_id: int) -> Iterator[None]:
+        """Delete a snapshot, restoring it if the surrounding update fails."""
+        with self.lock(account_id):
+            path = self.path(account_id)
+            previous_content = path.read_bytes() if path.exists() else None
+            dirty_path = self.dirty_path(account_id)
+            was_dirty = dirty_path.exists()
+            try:
+                path.unlink(missing_ok=True)
+                dirty_path.unlink(missing_ok=True)
+                yield
+            except BaseException:
+                if previous_content is not None:
+                    atomic_write_bytes(path, previous_content)
+                if was_dirty:
+                    atomic_write_bytes(dirty_path, b"1")
+                raise