simklcli 0.1.0__py3-none-any.whl

simklcli-0.1.0.dist-info/METADATA

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: simklcli
+Version: 0.1.0
+Summary: Track movies, shows, and anime on Simkl from the command line.
+Author: Javier Ochoa
+License: MIT License
+        
+        Copyright (c) 2026 Javier Ochoa
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: filelock<4,>=3.18
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: keyring<26,>=25
+Requires-Dist: platformdirs<5,>=4.3
+Requires-Dist: rich<15,>=14
+Requires-Dist: typer<1,>=0.27
+Description-Content-Type: text/markdown
+
+# simklcli
+
+`simklcli` is a public command-line client for the core Simkl tracking loop:
+authentication, catalog search and lookup, Library management, Watched State,
+and User Ratings. The PyPI distribution exposes the shorter `simkl` command.
+
+The CLI supports Simkl PIN Authorization, catalog search and lookup, Library
+management, Watched State, and User Ratings. It reconciles account state online
+and retains a dated Library Snapshot for explicit offline reads.
+
+## Install
+
+Python 3.11 or newer is required. Once the first release is published, install
+the supported package with:
+
+```sh
+uv tool install simklcli
+# or: pipx install simklcli
+```
+
+## Authentication
+
+The CLI ships with simklcli's public AUTH V2 app ID, so no developer
+registration is needed:
+
+```sh
+simkl auth login
+simkl auth status --check
+simkl search "Cowboy Bebop" --kind anime
+simkl library list
+simkl library list --offline
+```
+
+From a checkout, run the same commands through `uv sync --locked` and
+`uv run simkl …`.
+
+Login uses the V2 device-based PIN Authorization flow. Open the printed link
+and approve the application on Simkl; no client secret, redirect URL, or PKCE
+parameters are used by this flow. The client ID is public by design: on its
+own it reaches only public catalog data, and every user-scoped request also
+needs that user's Access Token.
+
+To use your own app instead, register an **AUTH V2** application as
+**TV, devices & command line** at
+[Simkl Developer Settings](https://simkl.com/settings/developer/) and set
+`SIMKL_CLIENT_ID` to its public ID before logging in. The issuing app ID is
+stored with each credential, so later invocations keep using it without the
+environment variable. An override must match the app that issued the stored
+tokens.
+
+```sh
+simkl auth login
+simkl auth status
+simkl auth status --check
+simkl auth logout
+```
+
+Login stores the Access Token and Refresh Token together in the OS keyring.
+If the platform has no usable keyring, plaintext storage must be
+selected explicitly with `simkl auth login --storage file`. Set
+`SIMKL_ACCESS_TOKEN` for a non-persisted automation override; it takes
+precedence over local credentials and must come from the built-in app or from
+the app named by `SIMKL_CLIENT_ID`.
+Environment overrides are not refreshed or persisted; supply a fresh Access
+Token when it expires. The old embedded V1 client ID has been removed.
+
+Access Tokens last seven days; the CLI refreshes shortly before expiry or once
+after an explicit token rejection. Refresh Tokens last 180 days with sliding
+expiry. Refresh and storage changes share an account lock across processes.
+Search and External ID resolution require sign-in. An anonymous known-ID lookup
+is available with `simkl lookup simkl:<id> --kind movie|show|anime`.
+
+An existing V1 account reconnects through `simkl auth login` without first
+logging out: approval must match the recorded account, and its Library Snapshot
+is retained. A failed or cancelled login preserves the existing credentials.
+Expired or revoked grants require explicit login and keep offline snapshots.
+See the [migration guide](docs/auth-v2-migration.md) for local verification.
+
+Logout removes local credentials and the Library Snapshot and makes a
+best-effort request to revoke the stored V2 grant. `--local-only` skips that
+request. Simkl acknowledges revocation without revealing whether a token was
+valid; the CLI reports acknowledgement rather than proof of revocation.
+
+Use `simkl auth status --json` for a single machine-readable stdout payload.
+The default status check is local-only; `--check` explicitly validates the
+Access Token with Simkl and refreshes the display name.
+
+## Development
+
+```sh
+uv sync --locked
+uv run ruff check .
+uv run mypy src tests scripts
+uv run pytest
+uv build --no-sources
+```
+
+## Tracking
+
+```sh
+simkl search "Cowboy Bebop" --kind anime
+simkl lookup imdb:tt0133093
+simkl lookup tmdb:603 --kind movie
+simkl library list --kind anime --status watching
+simkl library set-status simkl:3708 plan-to-watch
+simkl watched mark simkl:3708 --episode 1 --at 2026-08-08T20:00:00Z
+simkl watched mark simkl:3708 --all --yes
+simkl watched unmark simkl:3708 --episode 1
+simkl rating set simkl:3708 9
+simkl rating remove simkl:3708
+simkl library remove simkl:3708 --yes
+simkl library list --offline --json
+simkl library repair
+```
+
+Media References accept `simkl:<id>`, supported provider-qualified External
+IDs, or title text with optional `--kind` and `--year`. TMDB IDs require
+`--kind movie` or `--kind show`. An ambiguous title returns candidates and fails
+in scripts; interactive terminals can select a candidate. Search accepts
+`--page` (1–20) and `--limit` (1–50 results per media kind).
+
+Movies and standalone Anime take no Episode selectors. Shows require
+`--season N --episode N`; episodic Anime uses `--episode N` without a Season.
+Both accept `--all`; Shows also accept `--season N --all`. Bulk marks select
+aired Episodes. `--episode-id tvdb:<id>` or `--episode-id anidb:<id>` accepts an
+episode-level External ID with a parent Media Reference. When a response to
+such a write is lost, parent state alone cannot prove which Episode changed,
+so the CLI reports an unknown outcome instead of encouraging a blind retry.
+
+`watched mark --rewatch` explicitly records another Viewing and requires
+Simkl PRO or VIP. Use `--rewatch-id` to resume a specific known session.
+Unmark Watched preserves Library membership, List Status, and User Rating;
+`library remove` deletes all three along with Watched State.
+Simkl makes Completed Movies watched automatically, so `watched unmark` rejects
+that case before changing anything. Use an explicit `library set-status` move
+to `plan-to-watch` or `dropped` to clear a Movie's Watched State while keeping
+its User Rating.
+
+Every command accepts `--json`: stdout contains one JSON result, diagnostics
+go to stderr, and prompts are disabled. Whole-item removal, bulk updates, and
+logout require `--yes` in JSON or noninteractive use. User Ratings range from
+1 to 10 and apply to Movies, Shows, and Anime.
+
+Environment-token accounts can read their snapshots offline after one online
+Library read validates their identity. Only a token fingerprint and account ID
+are retained for that association; the Access Token is never persisted.
+
+Online Library reads check activities, merge changed List Status and rating
+state, and compare IDs when removals occur. Offline reads require a complete
+snapshot and report its age. Focused writes work before that first complete
+read. A successful remote write followed by failed reconciliation reports
+success and dirty local state; the next online read reconciles it. No writes
+are queued or automatically replayed.
+
+## Releases
+
+The [release guide](docs/releasing.md) describes the mandatory live smoke,
+restoration backup, GitHub environments, PyPI Trusted Publishing, and version
+tag checks. Merge-gating tests use authored HTTPX responses and never contact
+Simkl; the manually triggered smoke is the only live test workflow.
+
+## Project map
+
+- [`docs/spec.md`](docs/spec.md) — build-ready v1 product and engineering specification
+- [`CONTEXT.md`](CONTEXT.md) — canonical domain vocabulary
+- [`docs/adr/`](docs/adr/) — architectural decisions
+- [`docs/research/`](docs/research/) — cited API and prior-art research
+- [`src/simklcli/`](src/simklcli/) — installable tracking CLI
+- [`tests/`](tests/) — offline unit, HTTPX transport, and Typer CLI tests
+- [`prototypes/command-surface/`](prototypes/command-surface/) — runnable Typer command-surface prototype
+
+Run the prototype from the repository root:
+
+```sh
+./prototypes/command-surface/run surface
+./prototypes/command-surface/run --help
+```
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

simklcli-0.1.0.dist-info/RECORD

@@ -0,0 +1,20 @@
+simklcli/__init__.py,sha256=6dywuJOhdI4NoXIu6i_yUqiPjZiyRLiWdIgBNFOlTkE,47
+simklcli/__main__.py,sha256=9COydJZB76bwe42rh0BUe6U4DbBdgzI1-mq9DqxDR4s,67
+simklcli/api.py,sha256=V2rxL-ApGAFmDwf5_wU6qKCIVji5dRMi7VT7six2Fc0,16052
+simklcli/catalog.py,sha256=iQyz3h3vvlTk_6l_h4giLQVI3tRZj9Zle9UlCMPzPpE,6926
+simklcli/cli.py,sha256=o4gP61MTI1Hh7ScGJym129XoCxqeCM27Tz09CnVhTlw,20375
+simklcli/commands.py,sha256=4MMgc1IDqDN_rl0HkFyOi5rSq_s6DCLAPh0wk1U_Kjc,17203
+simklcli/filesystem.py,sha256=DTDTERLHK-u1051hrOJPerKauX0BpbbCkmL56_f_nho,925
+simklcli/media.py,sha256=X3dnJPtG1B5RFVckfcdyjze2lZTbyW15yU2pKa6SAUc,6650
+simklcli/output.py,sha256=wow9jcoaws4sRaeSnqeMi2bsBbSrcEFAu4lyfCB6QHQ,1818
+simklcli/rate_control.py,sha256=UzIjZ_ADzw1BnX4CwlhHzJ7pvhjgd-B82_wfG9La1wo,3831
+simklcli/runtime.py,sha256=aOWe0FCzNXoGJoRnxrXUcbdixqr9vNL1yQsLngZ6-Q0,9668
+simklcli/snapshots.py,sha256=_A0wNpXJ7Lw54SgFJmmCY1pvxs3PG89GzVOly4XnLNA,6891
+simklcli/storage.py,sha256=0I8VoFznfqXsS0OsxvsxEzaFWswD40AfxP422Kecup4,13685
+simklcli/targets.py,sha256=Zj5fhZqJ9_cLSid13hWM6V-wRjekZc4e13n1iLWOYyI,5163
+simklcli/tracking.py,sha256=adIAuV7-NmvcfgdQJkVwBS7Dl18oSS7Eqo5oZct-Etc,20913
+simklcli-0.1.0.dist-info/METADATA,sha256=iODURbeL1co1vs_YVcOTfJ2reLHMZK8SkmqI0q5orpQ,9389
+simklcli-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+simklcli-0.1.0.dist-info/entry_points.txt,sha256=83TaZ6LnJDx60INKPBTGj43KmVFMWSbD2HN6_2ca4GM,43
+simklcli-0.1.0.dist-info/licenses/LICENSE,sha256=n_CWabjY_86040ujq4X0r5VBTGNM9KriO2cK5JvdmnI,1069
+simklcli-0.1.0.dist-info/RECORD,,

simklcli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

simklcli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+simkl = simklcli.cli:app

simklcli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Ochoa
+
+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.