scholarinboxcli 0.1.0__py3-none-any.whl

scholarinboxcli/__init__.py

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

scholarinboxcli/api/client.py

@@ -0,0 +1,355 @@
+"""HTTP client for Scholar Inbox web API."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from urllib.parse import urlparse, parse_qs
+from dataclasses import dataclass
+from http.cookiejar import Cookie
+from typing import Any
+
+import httpx
+
+from scholarinboxcli.config import Config, load_config, save_config
+
+
+@dataclass
+class ApiError(Exception):
+    message: str
+    status_code: int | None = None
+    detail: Any | None = None
+
+
+def _cookie_to_dict(cookie: Cookie) -> dict[str, Any]:
+    return {
+        "name": cookie.name,
+        "value": cookie.value,
+        "domain": cookie.domain,
+        "path": cookie.path,
+        "expires": cookie.expires,
+        "secure": cookie.secure,
+        "httponly": cookie.has_nonstandard_attr("HttpOnly"),
+    }
+
+
+def _cookies_to_list(cookies: httpx.Cookies) -> list[dict[str, Any]]:
+    return [_cookie_to_dict(c) for c in cookies.jar]
+
+
+def _cookies_from_list(items: list[dict[str, Any]] | None) -> httpx.Cookies:
+    jar = httpx.Cookies()
+    if not items:
+        return jar
+    for item in items:
+        jar.set(
+            item.get("name"),
+            item.get("value"),
+            domain=item.get("domain"),
+            path=item.get("path") or "/",
+        )
+    return jar
+
+
+def _normalize_cookie_domains(cookies: httpx.Cookies, api_base: str) -> httpx.Cookies:
+    host = api_base.replace("https://", "").replace("http://", "").split("/")[0]
+    extra: list[tuple[str, str, str]] = []
+    for c in cookies.jar:
+        domain = c.domain or ""
+        if domain.startswith("www."):
+            base = domain[len("www.") :]
+        else:
+            base = domain
+        if base and host.endswith(base) and domain != host:
+            extra.append((c.name, c.value, host))
+        if base and not base.startswith("."):
+            extra.append((c.name, c.value, f".{base}"))
+    for name, value, domain in extra:
+        cookies.set(name, value, domain=domain, path="/")
+    return cookies
+
+
+def _is_paper_list(data: Any) -> bool:
+    if isinstance(data, dict):
+        for key in ("papers", "results", "items", "data", "digest_df"):
+            val = data.get(key)
+            if isinstance(val, list):
+                return True
+    if isinstance(data, list):
+        return True
+    return False
+
+
+class ScholarInboxClient:
+    def __init__(self, api_base: str | None = None, no_retry: bool = False):
+        self.no_retry = no_retry
+        self.cfg = load_config()
+        self.api_base = api_base or os.environ.get("SCHOLAR_INBOX_API_BASE") or self.cfg.api_base
+        cookies = _cookies_from_list(self.cfg.cookies)
+        self.client = httpx.Client(base_url=self.api_base, timeout=30.0, cookies=_normalize_cookie_domains(cookies, self.api_base))
+
+    def close(self) -> None:
+        self.client.close()
+
+    def save_cookies(self) -> None:
+        self.cfg.cookies = _cookies_to_list(self.client.cookies)
+        self.cfg.api_base = self.api_base
+        save_config(self.cfg)
+
+    def login_with_magic_link(self, login_url: str) -> None:
+        sha_key = None
+        try:
+            qs = parse_qs(urlparse(login_url).query)
+            sha_key = qs.get("sha_key", [None])[0]
+        except Exception:
+            sha_key = None
+
+        if sha_key:
+            resp = self.client.get(f"/api/login/{sha_key}/")
+            if resp.status_code >= 400:
+                raise ApiError("Login failed", resp.status_code, resp.text)
+            self.save_cookies()
+            return
+
+        with httpx.Client(follow_redirects=True, timeout=30.0) as client:
+            resp = client.get(login_url)
+            if resp.status_code >= 400:
+                raise ApiError("Login failed", resp.status_code, resp.text)
+            self.client.cookies = _normalize_cookie_domains(client.cookies, self.api_base)
+            self.save_cookies()
+
+    def _request(self, method: str, url: str, **kwargs: Any) -> Any:
+        retries = 0
+        while True:
+            resp = self.client.request(method, url, **kwargs)
+            if 300 <= resp.status_code < 400 and "/api/logout" in resp.headers.get("location", ""):
+                raise ApiError("Not authenticated (redirected to logout)", resp.status_code, resp.text)
+            if resp.status_code == 429 and not self.no_retry and retries < 3:
+                time.sleep(1.5 * (2**retries))
+                retries += 1
+                continue
+            if resp.status_code >= 400:
+                raise ApiError("Request failed", resp.status_code, resp.text)
+            if "application/json" in resp.headers.get("content-type", ""):
+                return resp.json()
+            # try json anyway
+            try:
+                return resp.json()
+            except Exception:
+                return resp.text
+
+    def _post_first(self, endpoints: list[str], payload: dict[str, Any]) -> Any:
+        last_error: ApiError | None = None
+        for ep in endpoints:
+            try:
+                return self._request("POST", ep, json=payload)
+            except ApiError as e:
+                last_error = e
+            try:
+                return self._request("POST", ep, data=payload)
+            except ApiError as e:
+                last_error = e
+        if last_error:
+            raise last_error
+        raise ApiError("No endpoints tried")
+
+    def session_info(self) -> Any:
+        return self._request("GET", "/api/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/")
+
+    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}",
+        )
+
+    def search(self, query: str, sort: str | None = None, limit: int | None = None, offset: int | None = None) -> Any:
+        payload: dict[str, Any] = {
+            "search_prompt": query,
+            "n_results": limit if limit is not None else 10,
+            "p": offset if offset is not None else 0,
+            "correct_search_prompt": True,
+        }
+        if sort:
+            payload["orderBy"] = sort
+        return self._request("POST", "/api/get_search_results/", json=payload)
+
+    def semantic_search(self, text: str, limit: int | None = None, offset: int | None = None) -> Any:
+        payload: dict[str, Any] = {
+            "text_input": text,
+            "embedding": "tfidf",
+            "p": offset if offset is not None else 0,
+        }
+        if limit is not None:
+            payload["n_results"] = limit
+        return self._request("POST", "/api/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}",
+        )
+
+    def bookmarks(self) -> Any:
+        return self._request("GET", "/api/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)
+        except ApiError:
+            return self._request("POST", "/api/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)
+        except ApiError:
+            return self._request("POST", "/api/bookmark_paper/", data=payload)
+
+    def collections_list(self) -> Any:
+        try:
+            return self._request("GET", "/api/get_all_user_collections")
+        except ApiError:
+            return self._request("GET", "/api/collections")
+
+    def collections_expanded(self) -> Any:
+        return self._request("GET", "/api/get_expanded_collections")
+
+    def collections_map(self) -> Any:
+        return self._request("GET", "/api/collections")
+
+    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)
+
+    def collection_rename(self, collection_id: str, new_name: str) -> Any:
+        payload = {
+            "collection_id": collection_id,
+            "id": collection_id,
+            "name": new_name,
+            "new_name": new_name,
+        }
+        endpoints = [
+            "/api/rename_collection/",
+            "/api/collection-rename/",
+            "/api/collections/rename",
+        ]
+        return self._post_first(endpoints, 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)
+
+    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)
+
+    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)
+
+    def collection_papers(self, collection_id: str, limit: int | None = None, offset: int | None = None) -> Any:
+        params: dict[str, Any] = {"collection_id": collection_id}
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+        try:
+            return self._request("GET", "/api/collection-papers", params=params)
+        except ApiError:
+            # fallback without paging
+            return self._request("GET", "/api/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 = [
+            "json_collection_ids_p",
+            "json_collection_ids",
+            "json_collection_id",
+            "form_collection_ids",
+            "get_params",
+        ]
+        if self.cfg.collections_similar_schema:
+            schemas = [self.cfg.collections_similar_schema] + [s for s in schemas if s != self.cfg.collections_similar_schema]
+
+        for schema in schemas:
+            try:
+                data = self._collections_similar_with_schema(schema, collection_ids, limit, offset)
+                if _is_paper_list(data):
+                    self.cfg.collections_similar_schema = schema
+                    save_config(self.cfg)
+                    return data
+            except ApiError:
+                continue
+        raise ApiError("Unable to fetch similar papers for collections")
+
+    def _collections_similar_with_schema(
+        self, schema: str, collection_ids: list[str], limit: int | None, offset: int | None
+    ) -> Any:
+        if schema == "json_collection_ids_p":
+            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)
+        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)
+        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)
+        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)
+        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)
+        raise ApiError("Unknown schema")
+
+    def conference_list(self) -> Any:
+        return self._request("GET", "/api/conference_list")
+
+    def conference_explorer(self) -> Any:
+        return self._request("GET", "/api/conference-explorer")

scholarinboxcli/cli.py

@@ -0,0 +1,524 @@
+"""Scholar Inbox CLI."""
+
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+import typer
+
+from scholarinboxcli.api.client import ApiError, ScholarInboxClient
+from scholarinboxcli.formatters.json_fmt import format_json
+from scholarinboxcli.formatters.table import format_table
+
+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"
+    )
+)
+
+
+auth_app = typer.Typer(help="Authentication commands", no_args_is_help=True)
+collection_app = typer.Typer(help="Collection commands", no_args_is_help=True)
+bookmark_app = typer.Typer(help="Bookmark commands", no_args_is_help=True)
+conference_app = typer.Typer(help="Conference commands", no_args_is_help=True)
+
+app.add_typer(auth_app, name="auth")
+app.add_typer(collection_app, name="collection")
+app.add_typer(bookmark_app, name="bookmark")
+app.add_typer(conference_app, name="conference")
+
+
+def _print_output(data, use_json: bool, title: str | None = None) -> None:
+    if use_json or not sys.stdout.isatty():
+        typer.echo(format_json(data))
+        return
+    table = format_table(data, title=title)
+    if table == "(no results)":
+        typer.echo(table)
+        return
+    typer.echo(table)
+
+
+def _handle_error(err: ApiError) -> None:
+    if not sys.stdout.isatty():
+        typer.echo(format_json({"error": err.message, "status_code": err.status_code, "detail": err.detail}))
+    else:
+        typer.echo(f"Error: {err.message}", err=True)
+        if err.status_code:
+            typer.echo(f"Status: {err.status_code}", err=True)
+    raise typer.Exit(1)
+
+
+def _normalize_name(name: str) -> str:
+    return name.strip().lower()
+
+
+def _resolve_collection_id(client: ScholarInboxClient, identifier: str) -> str:
+    if identifier.isdigit():
+        return identifier
+    data = client.collections_list()
+    items = _collection_items_from_response(data)
+    candidates = _collection_candidates(items)
+    if not _candidates_have_ids(candidates):
+        try:
+            data = client.collections_expanded()
+            items = _collection_items_from_response(data)
+            candidates = _collection_candidates(items)
+        except ApiError:
+            pass
+    if not _candidates_have_ids(candidates):
+        try:
+            data = client.collections_map()
+            mapped = _collection_candidates_from_map(data)
+            if mapped:
+                candidates = mapped
+        except ApiError:
+            pass
+    if not _candidates_have_ids(candidates):
+        matched = _match_collection_name(candidates, identifier)
+        if matched:
+            # Only names are available; fall back to name as identifier.
+            return matched
+        raise ApiError("Unable to resolve collection name (no IDs available)")
+    candidates = [(name, cid) for name, cid in candidates if cid]
+    target = _normalize_name(identifier)
+    for name, cid in candidates:
+        if _normalize_name(name) == target:
+            return cid
+    # prefix match
+    prefix = [c for c in candidates if _normalize_name(c[0]).startswith(target)]
+    if len(prefix) == 1:
+        return prefix[0][1]
+    if len(prefix) > 1:
+        names = ", ".join([f"{n}({cid})" for n, cid in prefix[:10]])
+        raise ApiError(f"Ambiguous collection name. Matches: {names}")
+    # contains match
+    contains = [c for c in candidates if target in _normalize_name(c[0])]
+    if len(contains) == 1:
+        return contains[0][1]
+    if len(contains) > 1:
+        names = ", ".join([f"{n}({cid})" for n, cid in contains[:10]])
+        raise ApiError(f"Ambiguous collection name. Matches: {names}")
+    raise ApiError("Collection name not found")
+
+
+def _collection_candidates(items: object) -> list[tuple[str, str]]:
+    if not isinstance(items, list):
+        return []
+    candidates: list[tuple[str, str]] = []
+    for item in items:
+        if isinstance(item, dict):
+            name = item.get("name") or item.get("collection_name") or ""
+            cid = str(item.get("id") or item.get("collection_id") or "")
+        elif isinstance(item, str):
+            name = item
+            cid = ""
+        else:
+            continue
+        if name:
+            candidates.append((name, cid))
+    return candidates
+
+
+def _collection_items_from_response(data: object) -> object:
+    if isinstance(data, dict):
+        for key in ("collections", "expanded_collections", "collection_names"):
+            if key in data:
+                return data.get(key)
+        return data
+    return data
+
+
+def _collection_candidates_from_map(data: object) -> list[tuple[str, str]]:
+    if not isinstance(data, dict):
+        return []
+    mapping = data.get("collection_names_to_ids_dict")
+    if not isinstance(mapping, dict):
+        return []
+    candidates: list[tuple[str, str]] = []
+    for name, cid in mapping.items():
+        if name and cid is not None:
+            candidates.append((str(name), str(cid)))
+    return candidates
+
+
+def _candidates_have_ids(candidates: list[tuple[str, str]]) -> bool:
+    for _, cid in candidates:
+        if cid:
+            return True
+    return False
+
+
+def _match_collection_name(candidates: list[tuple[str, str]], identifier: str) -> str | None:
+    target = _normalize_name(identifier)
+    names = [(name, cid) for name, cid in candidates if name]
+    for name, _ in names:
+        if _normalize_name(name) == target:
+            return name
+    prefix = [c for c in names if _normalize_name(c[0]).startswith(target)]
+    if len(prefix) == 1:
+        return prefix[0][0]
+    if len(prefix) > 1:
+        names_str = ", ".join([n for n, _ in prefix[:10]])
+        raise ApiError(f"Ambiguous collection name. Matches: {names_str}")
+    contains = [c for c in names if target in _normalize_name(c[0])]
+    if len(contains) == 1:
+        return contains[0][0]
+    if len(contains) > 1:
+        names_str = ", ".join([n for n, _ in contains[:10]])
+        raise ApiError(f"Ambiguous collection name. Matches: {names_str}")
+    return None
+
+
+@auth_app.command("login")
+def auth_login(
+    url: str = typer.Option(..., "--url", help="Magic login URL with sha_key"),
+):
+    client = ScholarInboxClient()
+    try:
+        client.login_with_magic_link(url)
+        typer.echo("Login successful")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@auth_app.command("status")
+def auth_status(json_output: bool = typer.Option(False, "--json", help="Output as JSON")):
+    client = ScholarInboxClient()
+    try:
+        data = client.session_info()
+        _print_output(data, json_output, title="Session")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@auth_app.command("logout")
+def auth_logout():
+    from scholarinboxcli.config import save_config, Config
+
+    save_config(Config())
+    typer.echo("Logged out")
+
+
+@app.command("digest")
+def digest(
+    date: Optional[str] = typer.Option(None, "--date", help="Digest date (MM-DD-YYYY)"),
+    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"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        data = client.get_digest(date)
+        _print_output(data, json_output, title="Digest")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@app.command("trending")
+def trending(
+    category: str = typer.Option("ALL", "--category", help="Category filter"),
+    days: int = typer.Option(7, "--days", help="Lookback window in days"),
+    sort: str = typer.Option("hype", "--sort", help="Sort column"),
+    asc: bool = typer.Option(False, "--asc", help="Sort ascending"),
+    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"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        data = client.get_trending(category=category, days=days, sort=sort, asc=asc)
+        _print_output(data, json_output, title="Trending")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@app.command("search")
+def search(
+    query: str = typer.Argument(..., help="Search query"),
+    sort: Optional[str] = typer.Option(None, "--sort", help="Sort option"),
+    limit: Optional[int] = typer.Option(None, "--limit", "-n", help="Limit results"),
+    offset: Optional[int] = typer.Option(None, "--offset", help="Pagination offset"),
+    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"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        data = client.search(query=query, sort=sort, limit=limit, offset=offset)
+        _print_output(data, json_output, title="Search")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@app.command("semantic")
+def semantic_search(
+    text: Optional[str] = typer.Argument(None, help="Semantic search text"),
+    file: Optional[str] = typer.Option(None, "--file", help="Read query text from file"),
+    limit: Optional[int] = typer.Option(None, "--limit", "-n", help="Limit results"),
+    offset: Optional[int] = typer.Option(None, "--offset", help="Pagination offset"),
+    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"),
+):
+    if not text and not file:
+        typer.echo("Provide text or --file", err=True)
+        raise typer.Exit(1)
+    if file:
+        text = open(file, "r", encoding="utf-8").read()
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        data = client.semantic_search(text=text or "", limit=limit, offset=offset)
+        _print_output(data, json_output, title="Semantic Search")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@app.command("interactions")
+def interactions(
+    type_: str = typer.Option("all", "--type", help="Interaction type (all/up/down)"),
+    sort: str = typer.Option("ranking_score", "--sort", help="Sort column"),
+    asc: bool = typer.Option(False, "--asc", help="Sort ascending"),
+    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"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        data = client.interactions(type_=type_, sort=sort, asc=asc)
+        _print_output(data, json_output, title="Interactions")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@bookmark_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"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        data = client.bookmarks()
+        _print_output(data, json_output, title="Bookmarks")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@bookmark_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"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        data = client.bookmark_add(paper_id)
+        _print_output(data, json_output, title="Bookmark added")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@bookmark_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"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        data = client.bookmark_remove(paper_id)
+        _print_output(data, json_output, title="Bookmark removed")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@collection_app.command("list")
+def collection_list(
+    json_output: bool = typer.Option(False, "--json", help="Output as JSON"),
+    expanded: bool = typer.Option(False, "--expanded", help="Use expanded collection metadata"),
+    no_retry: bool = typer.Option(False, "--no-retry", help="Disable retry on rate limits"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        data = client.collections_expanded() if expanded else client.collections_list()
+        _print_output(data, json_output, title="Collections")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+@collection_app.command("create")
+def collection_create(
+    name: str = typer.Argument(..., help="Collection name"),
+    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"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        data = client.collection_create(name)
+        _print_output(data, json_output, title="Collection created")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@collection_app.command("rename")
+def collection_rename(
+    collection_id: str = typer.Argument(..., help="Collection ID or name"),
+    new_name: str = typer.Argument(..., help="New collection name"),
+    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"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        cid = _resolve_collection_id(client, collection_id)
+        data = client.collection_rename(cid, new_name)
+        _print_output(data, json_output, title="Collection renamed")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@collection_app.command("delete")
+def collection_delete(
+    collection_id: str = typer.Argument(..., help="Collection ID or name"),
+    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"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        cid = _resolve_collection_id(client, collection_id)
+        data = client.collection_delete(cid)
+        _print_output(data, json_output, title="Collection deleted")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@collection_app.command("add")
+def collection_add(
+    collection_id: str = typer.Argument(..., help="Collection ID or name"),
+    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"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        cid = _resolve_collection_id(client, collection_id)
+        data = client.collection_add_paper(cid, paper_id)
+        _print_output(data, json_output, title="Collection add paper")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@collection_app.command("remove")
+def collection_remove(
+    collection_id: str = typer.Argument(..., help="Collection ID or name"),
+    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"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        cid = _resolve_collection_id(client, collection_id)
+        data = client.collection_remove_paper(cid, paper_id)
+        _print_output(data, json_output, title="Collection remove paper")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@collection_app.command("papers")
+def collection_papers(
+    collection_id: str = typer.Argument(..., help="Collection ID or name"),
+    limit: Optional[int] = typer.Option(None, "--limit", "-n", help="Limit results"),
+    offset: Optional[int] = typer.Option(None, "--offset", help="Pagination offset"),
+    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"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        cid = _resolve_collection_id(client, collection_id)
+        data = client.collection_papers(cid, limit=limit, offset=offset)
+        _print_output(data, json_output, title=f"Collection {cid}")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@collection_app.command("similar")
+def collection_similar(
+    collection_ids: list[str] = typer.Argument(..., help="Collection ID(s) or names"),
+    limit: Optional[int] = typer.Option(None, "--limit", "-n", help="Limit results"),
+    offset: Optional[int] = typer.Option(None, "--offset", help="Pagination offset"),
+    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"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        resolved = [_resolve_collection_id(client, cid) for cid in collection_ids]
+        data = client.collections_similar(resolved, limit=limit, offset=offset)
+        _print_output(data, json_output, title="Similar Papers")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@conference_app.command("list")
+def conference_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"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        data = client.conference_list()
+        _print_output(data, json_output, title="Conferences")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()
+
+
+@conference_app.command("explore")
+def conference_explore(
+    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"),
+):
+    client = ScholarInboxClient(no_retry=no_retry)
+    try:
+        data = client.conference_explorer()
+        _print_output(data, json_output, title="Conference Explorer")
+    except ApiError as e:
+        _handle_error(e)
+    finally:
+        client.close()

scholarinboxcli/config.py

@@ -0,0 +1,52 @@
+"""Config and session storage for scholarinboxcli."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+CONFIG_DIR = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config")) / "scholarinboxcli"
+CONFIG_PATH = CONFIG_DIR / "config.json"
+
+
+@dataclass
+class Config:
+    api_base: str = "https://api.scholar-inbox.com"
+    base_url: str = "https://www.scholar-inbox.com"
+    cookies: list[dict[str, Any]] | None = None
+    collections_similar_schema: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "api_base": self.api_base,
+            "base_url": self.base_url,
+            "cookies": self.cookies,
+            "collections_similar_schema": self.collections_similar_schema,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Config":
+        return cls(
+            api_base=data.get("api_base", cls.api_base),
+            base_url=data.get("base_url", cls.base_url),
+            cookies=data.get("cookies"),
+            collections_similar_schema=data.get("collections_similar_schema"),
+        )
+
+
+def load_config() -> Config:
+    if not CONFIG_PATH.exists():
+        return Config()
+    try:
+        data = json.loads(CONFIG_PATH.read_text())
+    except Exception:
+        return Config()
+    return Config.from_dict(data)
+
+
+def save_config(cfg: Config) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_PATH.write_text(json.dumps(cfg.to_dict(), indent=2))

scholarinboxcli/formatters/json_fmt.py

@@ -0,0 +1,10 @@
+"""JSON formatting helpers."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def format_json(data: Any) -> str:
+    return json.dumps(data, indent=2, ensure_ascii=True)

scholarinboxcli/formatters/table.py

@@ -0,0 +1,66 @@
+"""Table output formatting using Rich."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console
+from rich.table import Table
+
+
+def _get_authors(paper: dict[str, Any]) -> str:
+    authors = paper.get("authors") or paper.get("author") or paper.get("authorNames")
+    if isinstance(authors, list):
+        names = []
+        for a in authors:
+            if isinstance(a, str):
+                names.append(a)
+            elif isinstance(a, dict):
+                names.append(a.get("name") or a.get("author") or "")
+        return ", ".join([n for n in names if n])
+    if isinstance(authors, str):
+        return authors
+    return ""
+
+
+def _extract_papers(data: Any) -> list[dict[str, Any]]:
+    if isinstance(data, list):
+        return [d for d in data if isinstance(d, dict)]
+    if isinstance(data, dict):
+        for key in ("papers", "results", "items", "data", "digest_df"):
+            val = data.get(key)
+            if isinstance(val, list):
+                return [d for d in val if isinstance(d, dict)]
+    return []
+
+
+def format_table(data: Any, title: str | None = None) -> str:
+    papers = _extract_papers(data)
+    if not papers:
+        return "(no results)"
+
+    table = Table(title=title)
+    table.add_column("Title", overflow="fold")
+    table.add_column("Authors", overflow="fold")
+    table.add_column("Year", justify="right")
+    table.add_column("Venue", overflow="fold")
+    table.add_column("ID", overflow="fold")
+
+    for p in papers:
+        title_val = str(p.get("title") or p.get("paper_title") or "")
+        authors_val = _get_authors(p)
+        year_val = str(p.get("year") or p.get("publication_year") or "")
+        venue_val = str(p.get("venue") or p.get("conference") or p.get("journal") or "")
+        pid = str(
+            p.get("paper_id")
+            or p.get("paperId")
+            or p.get("id")
+            or p.get("corpusid")
+            or ""
+        )
+        table.add_row(title_val, authors_val, year_val, venue_val, pid)
+
+    console = Console()
+    with console.capture() as capture:
+        console.print(table)
+    return capture.get()

scholarinboxcli-0.1.0.dist-info/METADATA

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: scholarinboxcli
+Version: 0.1.0
+Summary: CLI for Scholar Inbox (authenticated web API)
+License-Expression: MIT
+Keywords: bibliography,cli,research,scholar
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Description-Content-Type: text/markdown
+
+# scholarinboxcli
+
+CLI for Scholar Inbox, for humans and agents alike.
+
+## Installation
+
+```bash
+pip install scholarinboxcli
+```
+
+Or with uv:
+
+```bash
+uv pip install scholarinboxcli
+```
+
+Or run directly with uvx (no install):
+
+```bash
+uvx scholarinboxcli auth login --url "<magic-link-url>"
+```
+
+## Auth
+
+```bash
+# Log in with the magic-link URL from the web app
+scholarinboxcli auth login --url "https://www.scholar-inbox.com/login?sha_key=...&date=MM-DD-YYYY"
+
+# Check current session and user info
+scholarinboxcli auth status
+
+# Clear local session config
+scholarinboxcli auth logout
+```
+
+Note: `auth login` extracts `sha_key` from the URL and authenticates via the API.
+
+Config is stored at `~/.config/scholarinboxcli/config.json`. You can override the API base with `SCHOLAR_INBOX_API_BASE`.
+
+## Command reference
+
+Top-level commands:
+
+- `auth` (login/status/logout)
+- `digest`
+- `trending`
+- `search`
+- `semantic`
+- `interactions`
+- `bookmark` (list/add/remove)
+- `collection` (list/create/rename/delete/add/remove/papers/similar)
+- `conference` (list/explore)
+
+Run `scholarinboxcli --help` or `scholarinboxcli <command> --help` for full options.
+
+## Quickstart
+
+```bash
+# Fetch a daily digest by date (MM-DD-YYYY)
+scholarinboxcli digest --date 01-30-2026 --json
+
+# Trending papers (last 7 days)
+scholarinboxcli trending --category ALL --days 7 --json
+
+# Keyword search
+scholarinboxcli search "transformers" --limit 5 --json
+
+# Semantic search
+scholarinboxcli semantic "graph neural networks" --limit 5 --json
+
+# List your bookmarks
+scholarinboxcli bookmark list --json
+```
+
+## Collections
+
+```bash
+# List collections
+scholarinboxcli collection list
+
+# Expanded collection names (marks which collections are expanded server-side)
+scholarinboxcli collection list --expanded
+
+# Create, rename, delete
+scholarinboxcli collection create "My Collection"
+
+# Rename by ID (or name)
+scholarinboxcli collection rename 10759 "New Name"
+
+# Delete by ID (or name)
+scholarinboxcli collection delete 10759
+
+# Add/remove papers
+scholarinboxcli collection add 10759 4559909
+scholarinboxcli collection remove 10759 4559909
+
+# Show papers in a collection
+scholarinboxcli collection papers 10759
+
+# Similar papers for one or more collections
+scholarinboxcli collection similar 10759 12345
+
+# You can also use collection names (case-insensitive). The CLI will
+# automatically fetch collection ID mappings from the API when needed.
+scholarinboxcli collection papers "AIAgents"
+scholarinboxcli collection similar "AIAgents" "Benchmark"
+```
+
+Collection name matching is exact → prefix → contains. If multiple matches exist, the CLI reports ambiguity and shows candidate IDs.
+
+## Search
+
+```bash
+# Full-text keyword search
+scholarinboxcli search "transformers" --limit 5
+```
+
+## Semantic Search
+
+```bash
+# Semantic similarity search
+scholarinboxcli semantic "graph neural networks" --limit 5
+```
+
+## Other commands
+
+```bash
+# Daily digest view (MM-DD-YYYY)
+scholarinboxcli digest --date 01-30-2026
+
+# Trending papers by category
+scholarinboxcli trending --category ALL --days 7
+
+# Read/like/dislike interactions feed
+scholarinboxcli interactions --type all
+
+# List bookmarks
+scholarinboxcli bookmark list
+
+# List known conferences
+scholarinboxcli conference list
+
+# Explore conference indices
+scholarinboxcli conference explore
+```
+
+## Output modes
+
+- TTY: Rich tables
+- `--json`: pretty JSON
+- Piped: pretty JSON (auto)
+
+Examples for agents/scripting:
+
+```bash
+# Auto-JSON when piped
+scholarinboxcli collection list | jq '.'
+
+# Explicit JSON output
+scholarinboxcli collection papers "AIAgents" --json
+
+# JSON for automation (stable keys)
+scholarinboxcli search "diffusion" --json
+```
+
+## Tested (2026-02-01)
+
+The following commands were exercised against the live API (with a valid magic-link login) to confirm behavior:
+
+```bash
+scholarinboxcli --help
+scholarinboxcli auth status --json
+scholarinboxcli digest --date 01-30-2026 --json
+scholarinboxcli trending --category ALL --days 7 --json
+scholarinboxcli search "transformers" --limit 5 --json
+scholarinboxcli semantic "graph neural networks" --limit 5 --json
+scholarinboxcli interactions --type all --json
+scholarinboxcli bookmark list --json
+scholarinboxcli bookmark add 3302478 --json
+scholarinboxcli bookmark remove 3302478 --json
+scholarinboxcli collection list --json
+scholarinboxcli collection list --expanded --json
+scholarinboxcli collection papers "AIAgents" --json
+scholarinboxcli collection similar "AIAgents" --json
+scholarinboxcli conference list --json
+scholarinboxcli conference explore --json
+```
+
+## Notes
+
+- Some collection mutations (create/rename/delete/add/remove) rely on best-effort endpoints that may change on the service side. If a mutation fails, try again or use the web UI to validate the current behavior.
+- Similar papers for collections uses the server endpoint used by the web UI. Results typically appear under `digest_df` in JSON responses.
+
+## Publish to PyPI
+
+```bash
+# 1) Build sdist + wheel
+uv run --with build python -m build
+
+# 2) Validate metadata/rendering
+uvx twine check dist/*
+
+# 3) (Optional) test publish first
+uvx twine upload --repository testpypi dist/*
+
+# 4) Publish to PyPI
+uvx twine upload dist/*
+```
+
+If using an API token:
+
+```bash
+export TWINE_USERNAME=__token__
+export TWINE_PASSWORD=<your-pypi-token>
+```

scholarinboxcli-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+scholarinboxcli/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+scholarinboxcli/cli.py,sha256=bugBfT66k5EuVPashcG6Pz0IRM0KtRz_c6lNOalm4pk,19242
+scholarinboxcli/config.py,sha256=cxp1RzNwzT6Iu225EPvs8NhH2YTTMg9fQBjaYIRVDoc,1545
+scholarinboxcli/api/client.py,sha256=TE8pIRXh7pHhQGto9CvRpPPT61SJp9SzNhRnQ-2U4M4,13723
+scholarinboxcli/formatters/json_fmt.py,sha256=Ntcp4EqHugCXg79RIF62c7QHa-lexptLDDTT3IEP65U,197
+scholarinboxcli/formatters/table.py,sha256=GnzpmSJ7M_yq-R-c8no8SE9vXbycvWWPUu6hV4tcJAA,2133
+scholarinboxcli-0.1.0.dist-info/METADATA,sha256=JZISdlP49Ezyh-UoLv2FlJIrliHUvZrnj0IvFNWKCMw,6062
+scholarinboxcli-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+scholarinboxcli-0.1.0.dist-info/entry_points.txt,sha256=iescoEMF_CPwSNSmvlzNDl5pT2VpBL9_1bIq_FFIAKc,60
+scholarinboxcli-0.1.0.dist-info/RECORD,,

scholarinboxcli-0.1.0.dist-info/WHEEL

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

scholarinboxcli-0.1.0.dist-info/entry_points.txt

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