scholarinboxcli 0.1.0__tar.gz → 0.1.1__tar.gz

scholarinboxcli-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,17 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv python install 3.11
+      - run: uv run scholarinboxcli --help
+      - run: uv run --with pytest pytest -q

scholarinboxcli-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv python install 3.11
+      - run: uv build
+      - run: uv publish --trusted-publishing=automatic --check-url https://pypi.org/simple/scholarinboxcli/

scholarinboxcli-0.1.1/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.1] - 2026-02-01
+
+### Added
+
+- Added `LICENSE` (MIT) file.
+- Added CI workflow (`.github/workflows/ci.yml`) for help smoke-check + pytest.
+- Added offline smoke tests for CLI commands with mocked client behavior.
+- Added logic-focused collection resolution unit tests (exact/prefix/contains/ambiguity/fallbacks).
+- Added mocked API client tests for bookmark payload/fallback behavior and conference explorer calls.
+- Added Keep a Changelog style `CHANGELOG.md`.
+
+### Changed
+
+- Refactored CLI into focused command modules (`auth`, `papers`, `bookmarks`, `collections`, `conferences`).
+- Moved collection name/ID resolution into a dedicated service module.
+- Centralized API endpoint constants in `api/endpoints.py`.
+- Reduced command boilerplate via shared `with_client()` helper for client lifecycle and error handling.
+
+## [0.1.0] - 2026-02-01
+
+### Added
+
+- Initial `scholarinboxcli` command-line interface with Typer + Rich and JSON output.
+- Auth commands: `auth login`, `auth status`, `auth logout`.
+- Research workflow commands: `digest`, `trending`, `search`, `semantic`, `interactions`.
+- Bookmark commands: `bookmark list`, `bookmark add`, `bookmark remove`.
+- Collection commands: `collection list/create/rename/delete/add/remove/papers/similar`.
+- Conference commands: `conference list`, `conference explore`.
+- Collection name resolution by ID or name, including fallback ID map lookup.
+- README quickstart, command examples, tested-command matrix, and release instructions.
+- GitHub Actions trusted-publishing workflow for tag-based PyPI release.
+- Project tagline and CLI help examples for humans and agents.
+
+### Changed
+
+- Standardized JSON output to pretty-printed format for both `--json` and piped output.
+- Simplified `conference explore` to list-style behavior by removing ineffective query/sort options.
+
+### Fixed
+
+- Bookmark add/remove payloads aligned with the web API endpoint behavior.
+- Collection name-to-ID resolution improved for cases where list endpoints omit IDs.
+
+### Removed
+
+- Tracked Python bytecode artifacts (`.pyc`) removed from repository history and ignored via `.gitignore`.
+
+[Unreleased]: https://github.com/mrshu/scholarinboxcli/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/mrshu/scholarinboxcli/releases/tag/v0.1.1
+[0.1.0]: https://github.com/mrshu/scholarinboxcli/releases/tag/v0.1.0

scholarinboxcli-0.1.1/LICENSE

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

{scholarinboxcli-0.1.0 → scholarinboxcli-0.1.1}/PKG-INFO

@@ -1,8 +1,9 @@
 Metadata-Version: 2.4
 Name: scholarinboxcli
-Version: 0.1.0
+Version: 0.1.1
 Summary: CLI for Scholar Inbox (authenticated web API)
 License-Expression: MIT
+License-File: LICENSE
 Keywords: bibliography,cli,research,scholar
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
@@ -234,3 +235,9 @@ If using an API token:
 export TWINE_USERNAME=__token__
 export TWINE_PASSWORD=<your-pypi-token>
 ```
+
+Automated publish is also configured via GitHub Actions:
+
+- Workflow: `.github/workflows/publish.yml`
+- Trigger: push a tag matching `v*` (for example `v0.1.1`)
+- Auth: PyPI Trusted Publishing (OIDC)

{scholarinboxcli-0.1.0 → scholarinboxcli-0.1.1}/README.md

@@ -213,3 +213,9 @@ If using an API token:
 export TWINE_USERNAME=__token__
 export TWINE_PASSWORD=<your-pypi-token>
 ```
+
+Automated publish is also configured via GitHub Actions:
+
+- Workflow: `.github/workflows/publish.yml`
+- Trigger: push a tag matching `v*` (for example `v0.1.1`)
+- Auth: PyPI Trusted Publishing (OIDC)

{scholarinboxcli-0.1.0 → scholarinboxcli-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "scholarinboxcli"
-version = "0.1.0"
+version = "0.1.1"
 description = "CLI for Scholar Inbox (authenticated web API)"
 readme = "README.md"
 requires-python = ">=3.10"

scholarinboxcli-0.1.1/src/scholarinboxcli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

{scholarinboxcli-0.1.0 → scholarinboxcli-0.1.1}/src/scholarinboxcli/api/client.py

@@ -13,6 +13,7 @@ from typing import Any
 import httpx
 
 from scholarinboxcli.config import Config, load_config, save_config
+from scholarinboxcli.api import endpoints as ep
 
 
 @dataclass
@@ -106,7 +107,7 @@ class ScholarInboxClient:
             sha_key = None
 
         if sha_key:
-            resp = self.client.get(f"/api/login/{sha_key}/")
+            resp = self.client.get(ep.LOGIN_WITH_SHA_TEMPLATE.format(sha_key=sha_key))
             if resp.status_code >= 400:
                 raise ApiError("Login failed", resp.status_code, resp.text)
             self.save_cookies()
@@ -155,18 +156,18 @@ class ScholarInboxClient:
         raise ApiError("No endpoints tried")
 
     def session_info(self) -> Any:
-        return self._request("GET", "/api/session_info")
+        return self._request("GET", ep.SESSION_INFO)
 
     def get_digest(self, date: str | None = None) -> Any:
         if date:
-            return self._request("GET", f"/api/?date={date}")
-        return self._request("GET", "/api/")
+            return self._request("GET", f"{ep.DIGEST}?date={date}")
+        return self._request("GET", ep.DIGEST)
 
     def get_trending(self, category: str = "ALL", days: int = 7, sort: str = "hype", asc: bool = False) -> Any:
         asc_val = "1" if asc else "0"
         return self._request(
             "GET",
-            f"/api/trending?column={sort}&category={category}&ascending={asc_val}&dates={days}",
+            f"{ep.TRENDING}?column={sort}&category={category}&ascending={asc_val}&dates={days}",
         )
 
     def search(self, query: str, sort: str | None = None, limit: int | None = None, offset: int | None = None) -> Any:
@@ -178,7 +179,7 @@ class ScholarInboxClient:
         }
         if sort:
             payload["orderBy"] = sort
-        return self._request("POST", "/api/get_search_results/", json=payload)
+        return self._request("POST", ep.SEARCH, json=payload)
 
     def semantic_search(self, text: str, limit: int | None = None, offset: int | None = None) -> Any:
         payload: dict[str, Any] = {
@@ -188,52 +189,47 @@ class ScholarInboxClient:
         }
         if limit is not None:
             payload["n_results"] = limit
-        return self._request("POST", "/api/semantic-search", json=payload)
+        return self._request("POST", ep.SEMANTIC_SEARCH, json=payload)
 
     def interactions(self, type_: str = "all", sort: str = "ranking_score", asc: bool = False) -> Any:
         asc_val = "1" if asc else "0"
         return self._request(
             "GET",
-            f"/api/interactions?column={sort}&type={type_}&ascending={asc_val}",
+            f"{ep.INTERACTIONS}?column={sort}&type={type_}&ascending={asc_val}",
         )
 
     def bookmarks(self) -> Any:
-        return self._request("GET", "/api/bookmarks")
+        return self._request("GET", ep.BOOKMARKS)
 
     def bookmark_add(self, paper_id: str) -> Any:
         payload = {"bookmarked": True, "id": paper_id}
         try:
-            return self._request("POST", "/api/bookmark_paper/", json=payload)
+            return self._request("POST", ep.BOOKMARK_PAPER, json=payload)
         except ApiError:
-            return self._request("POST", "/api/bookmark_paper/", data=payload)
+            return self._request("POST", ep.BOOKMARK_PAPER, data=payload)
 
     def bookmark_remove(self, paper_id: str) -> Any:
         payload = {"bookmarked": False, "id": paper_id}
         try:
-            return self._request("POST", "/api/bookmark_paper/", json=payload)
+            return self._request("POST", ep.BOOKMARK_PAPER, json=payload)
         except ApiError:
-            return self._request("POST", "/api/bookmark_paper/", data=payload)
+            return self._request("POST", ep.BOOKMARK_PAPER, data=payload)
 
     def collections_list(self) -> Any:
         try:
-            return self._request("GET", "/api/get_all_user_collections")
+            return self._request("GET", ep.COLLECTIONS_PRIMARY)
         except ApiError:
-            return self._request("GET", "/api/collections")
+            return self._request("GET", ep.COLLECTIONS_FALLBACK)
 
     def collections_expanded(self) -> Any:
-        return self._request("GET", "/api/get_expanded_collections")
+        return self._request("GET", ep.COLLECTIONS_EXPANDED)
 
     def collections_map(self) -> Any:
-        return self._request("GET", "/api/collections")
+        return self._request("GET", ep.COLLECTIONS_FALLBACK)
 
     def collection_create(self, name: str) -> Any:
         payload = {"name": name, "collection_name": name}
-        endpoints = [
-            "/api/create_collection/",
-            "/api/collections",
-            "/api/collection-create/",
-        ]
-        return self._post_first(endpoints, payload)
+        return self._post_first(list(ep.COLLECTION_CREATE_CANDIDATES), payload)
 
     def collection_rename(self, collection_id: str, new_name: str) -> Any:
         payload = {
@@ -242,39 +238,19 @@ class ScholarInboxClient:
             "name": new_name,
             "new_name": new_name,
         }
-        endpoints = [
-            "/api/rename_collection/",
-            "/api/collection-rename/",
-            "/api/collections/rename",
-        ]
-        return self._post_first(endpoints, payload)
+        return self._post_first(list(ep.COLLECTION_RENAME_CANDIDATES), payload)
 
     def collection_delete(self, collection_id: str) -> Any:
         payload = {"collection_id": collection_id, "id": collection_id}
-        endpoints = [
-            "/api/delete_collection/",
-            "/api/collection-delete/",
-            "/api/collections/delete",
-        ]
-        return self._post_first(endpoints, payload)
+        return self._post_first(list(ep.COLLECTION_DELETE_CANDIDATES), payload)
 
     def collection_add_paper(self, collection_id: str, paper_id: str) -> Any:
         payload = {"collection_id": collection_id, "paper_id": paper_id}
-        endpoints = [
-            "/api/add_paper_to_collection/",
-            "/api/collection-add-paper/",
-            "/api/add_to_collection/",
-        ]
-        return self._post_first(endpoints, payload)
+        return self._post_first(list(ep.COLLECTION_ADD_PAPER_CANDIDATES), payload)
 
     def collection_remove_paper(self, collection_id: str, paper_id: str) -> Any:
         payload = {"collection_id": collection_id, "paper_id": paper_id}
-        endpoints = [
-            "/api/remove_paper_from_collection/",
-            "/api/collection-remove-paper/",
-            "/api/remove_from_collection/",
-        ]
-        return self._post_first(endpoints, payload)
+        return self._post_first(list(ep.COLLECTION_REMOVE_PAPER_CANDIDATES), payload)
 
     def collection_papers(self, collection_id: str, limit: int | None = None, offset: int | None = None) -> Any:
         params: dict[str, Any] = {"collection_id": collection_id}
@@ -283,10 +259,10 @@ class ScholarInboxClient:
         if offset is not None:
             params["offset"] = offset
         try:
-            return self._request("GET", "/api/collection-papers", params=params)
+            return self._request("GET", ep.COLLECTION_PAPERS, params=params)
         except ApiError:
             # fallback without paging
-            return self._request("GET", "/api/collection-papers", params={"collection_id": collection_id})
+            return self._request("GET", ep.COLLECTION_PAPERS, params={"collection_id": collection_id})
 
     def collections_similar(self, collection_ids: list[str], limit: int | None = None, offset: int | None = None) -> Any:
         schemas = [
@@ -317,39 +293,39 @@ class ScholarInboxClient:
             payload: dict[str, Any] = {"collectionIds": collection_ids, "p": offset if offset is not None else 0}
             if limit is not None:
                 payload["n_results"] = limit
-            return self._request("POST", "/api/get_collections_similar_papers/", json=payload)
+            return self._request("POST", ep.COLLECTIONS_SIMILAR, json=payload)
         if schema == "json_collection_ids":
             payload: dict[str, Any] = {"collection_ids": collection_ids}
             if limit is not None:
                 payload["limit"] = limit
             if offset is not None:
                 payload["offset"] = offset
-            return self._request("POST", "/api/get_collections_similar_papers/", json=payload)
+            return self._request("POST", ep.COLLECTIONS_SIMILAR, json=payload)
         if schema == "json_collection_id" and len(collection_ids) == 1:
             payload = {"collection_id": collection_ids[0]}
             if limit is not None:
                 payload["limit"] = limit
             if offset is not None:
                 payload["offset"] = offset
-            return self._request("POST", "/api/get_collections_similar_papers/", json=payload)
+            return self._request("POST", ep.COLLECTIONS_SIMILAR, json=payload)
         if schema == "form_collection_ids":
             payload = {"collection_ids": ",".join(collection_ids)}
             if limit is not None:
                 payload["limit"] = limit
             if offset is not None:
                 payload["offset"] = offset
-            return self._request("POST", "/api/get_collections_similar_papers/", data=payload)
+            return self._request("POST", ep.COLLECTIONS_SIMILAR, data=payload)
         if schema == "get_params":
             params = {"collection_id": ",".join(collection_ids)}
             if limit is not None:
                 params["limit"] = limit
             if offset is not None:
                 params["offset"] = offset
-            return self._request("GET", "/api/get_collections_similar_papers/", params=params)
+            return self._request("GET", ep.COLLECTIONS_SIMILAR, params=params)
         raise ApiError("Unknown schema")
 
     def conference_list(self) -> Any:
-        return self._request("GET", "/api/conference_list")
+        return self._request("GET", ep.CONFERENCE_LIST)
 
     def conference_explorer(self) -> Any:
-        return self._request("GET", "/api/conference-explorer")
+        return self._request("GET", ep.CONFERENCE_EXPLORER)

scholarinboxcli-0.1.1/src/scholarinboxcli/api/endpoints.py

@@ -0,0 +1,54 @@
+"""API endpoint constants used by the Scholar Inbox client."""
+
+from __future__ import annotations
+
+# Auth/session
+SESSION_INFO = "/api/session_info"
+LOGIN_WITH_SHA_TEMPLATE = "/api/login/{sha_key}/"
+
+# Feed/search
+DIGEST = "/api/"
+TRENDING = "/api/trending"
+SEARCH = "/api/get_search_results/"
+SEMANTIC_SEARCH = "/api/semantic-search"
+INTERACTIONS = "/api/interactions"
+
+# Bookmarks
+BOOKMARKS = "/api/bookmarks"
+BOOKMARK_PAPER = "/api/bookmark_paper/"
+
+# Collections
+COLLECTIONS_PRIMARY = "/api/get_all_user_collections"
+COLLECTIONS_FALLBACK = "/api/collections"
+COLLECTIONS_EXPANDED = "/api/get_expanded_collections"
+COLLECTION_CREATE_CANDIDATES = (
+    "/api/create_collection/",
+    "/api/collections",
+    "/api/collection-create/",
+)
+COLLECTION_RENAME_CANDIDATES = (
+    "/api/rename_collection/",
+    "/api/collection-rename/",
+    "/api/collections/rename",
+)
+COLLECTION_DELETE_CANDIDATES = (
+    "/api/delete_collection/",
+    "/api/collection-delete/",
+    "/api/collections/delete",
+)
+COLLECTION_ADD_PAPER_CANDIDATES = (
+    "/api/add_paper_to_collection/",
+    "/api/collection-add-paper/",
+    "/api/add_to_collection/",
+)
+COLLECTION_REMOVE_PAPER_CANDIDATES = (
+    "/api/remove_paper_from_collection/",
+    "/api/collection-remove-paper/",
+    "/api/remove_from_collection/",
+)
+COLLECTION_PAPERS = "/api/collection-papers"
+COLLECTIONS_SIMILAR = "/api/get_collections_similar_papers/"
+
+# Conferences
+CONFERENCE_LIST = "/api/conference_list"
+CONFERENCE_EXPLORER = "/api/conference-explorer"

scholarinboxcli-0.1.1/src/scholarinboxcli/cli.py

@@ -0,0 +1,30 @@
+"""Scholar Inbox CLI app composition."""
+
+from __future__ import annotations
+
+import typer
+
+from scholarinboxcli.commands import auth, bookmarks, collections, conferences, papers
+from scholarinboxcli.services.collections import resolve_collection_id as _resolve_collection_id
+
+
+app = typer.Typer(
+    help=(
+        "Scholar Inbox CLI.\n\n"
+        "Examples:\n"
+        "  scholarinboxcli auth login --url \"https://www.scholar-inbox.com/login?sha_key=...&date=MM-DD-YYYY\"\n"
+        "  scholarinboxcli digest --date 01-30-2026 --json\n"
+        "  scholarinboxcli search \"transformers\" --limit 5 --json\n"
+        "  scholarinboxcli collection papers \"AIAgents\" --json\n"
+        "  scholarinboxcli conference explore --json\n"
+    )
+)
+
+# Top-level feed/search commands
+papers.register(app)
+
+# Grouped commands
+app.add_typer(auth.app, name="auth")
+app.add_typer(collections.app, name="collection")
+app.add_typer(bookmarks.app, name="bookmark")
+app.add_typer(conferences.app, name="conference")

scholarinboxcli-0.1.1/src/scholarinboxcli/commands/__init__.py

@@ -0,0 +1 @@
+"""Command groups for scholarinboxcli."""

scholarinboxcli-0.1.1/src/scholarinboxcli/commands/auth.py

@@ -0,0 +1,38 @@
+"""Authentication command group."""
+
+from __future__ import annotations
+
+import typer
+
+from scholarinboxcli.commands.common import print_output, with_client
+
+
+app = typer.Typer(help="Authentication commands", no_args_is_help=True)
+
+
+@app.command("login")
+def auth_login(
+    url: str = typer.Option(..., "--url", help="Magic login URL with sha_key"),
+):
+    def action(client):
+        client.login_with_magic_link(url)
+        typer.echo("Login successful")
+
+    with_client(False, action)
+
+
+@app.command("status")
+def auth_status(json_output: bool = typer.Option(False, "--json", help="Output as JSON")):
+    def action(client):
+        data = client.session_info()
+        print_output(data, json_output, title="Session")
+
+    with_client(False, action)
+
+
+@app.command("logout")
+def auth_logout():
+    from scholarinboxcli.config import Config, save_config
+
+    save_config(Config())
+    typer.echo("Logged out")

scholarinboxcli-0.1.1/src/scholarinboxcli/commands/bookmarks.py

@@ -0,0 +1,48 @@
+"""Bookmark command group."""
+
+from __future__ import annotations
+
+import typer
+
+from scholarinboxcli.commands.common import print_output, with_client
+
+
+app = typer.Typer(help="Bookmark commands", no_args_is_help=True)
+
+
+@app.command("list")
+def bookmark_list(
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
+    no_retry: bool = typer.Option(False, "--no-retry", help="Disable retry on rate limits"),
+):
+    def action(client):
+        data = client.bookmarks()
+        print_output(data, json_output, title="Bookmarks")
+
+    with_client(no_retry, action)
+
+
+@app.command("add")
+def bookmark_add(
+    paper_id: str = typer.Argument(..., help="Paper ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
+    no_retry: bool = typer.Option(False, "--no-retry", help="Disable retry on rate limits"),
+):
+    def action(client):
+        data = client.bookmark_add(paper_id)
+        print_output(data, json_output, title="Bookmark added")
+
+    with_client(no_retry, action)
+
+
+@app.command("remove")
+def bookmark_remove(
+    paper_id: str = typer.Argument(..., help="Paper ID"),
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
+    no_retry: bool = typer.Option(False, "--no-retry", help="Disable retry on rate limits"),
+):
+    def action(client):
+        data = client.bookmark_remove(paper_id)
+        print_output(data, json_output, title="Bookmark removed")
+
+    with_client(no_retry, action)