gog-cli 0.2.1__tar.gz

gog_cli-0.2.1/LICENSE

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

gog_cli-0.2.1/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: gog-cli
+Version: 0.2.1
+Summary: CLI tool for backing up DRM-free GOG games.
+Author: gog-cli contributors
+License: MIT License
+        
+        Copyright (c) 2026 gog-cli contributors
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/aleksandarristic/gog-cli
+Project-URL: Repository, https://github.com/aleksandarristic/gog-cli
+Project-URL: Bug Tracker, https://github.com/aleksandarristic/gog-cli/issues
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: responses>=0.25; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Dynamic: license-file
+
+# gog-cli
+
+[![CI](https://github.com/aleksandarristic/gog-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/aleksandarristic/gog-cli/actions/workflows/ci.yml)
+
+`gog` is a Python CLI for backing up a user's owned DRM-free GOG game library.
+
+It is focused on safe, scriptable workflows:
+
+- list owned games with filtering and fuzzy search
+- plan and execute backups to a local directory
+- preserve metadata needed to audit and restore backups
+- download installers and related files with resumable behavior
+- verify downloaded files when checksums are available
+
+## Install
+
+Requires Python 3.12 or newer.
+
+```sh
+pip install git+https://github.com/aleksandarristic/gog-cli.git
+```
+
+## Development
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+Run the CLI locally:
+
+```sh
+gog --help
+gog list
+gog plan --destination /path/to/backups --all --summary
+gog backup --destination /path/to/backups --games-from games.txt --dry-run
+```
+
+## Basic Workflow
+
+```sh
+gog auth login
+gog refresh
+gog list purchased
+gog plan --destination /path/to/backups --all --storage --check-free-space
+gog backup --destination /path/to/backups --all --yes
+gog list backed-up --destination /path/to/backups
+gog sync --destination /path/to/backups --all --yes
+```
+
+`gog refresh` updates the local purchased-library and download-metadata caches.
+It does not download game installers. Run it before browsing or filtering newly
+added library metadata.
+
+## Browsing Purchased Games
+
+`gog list purchased` reads the local cache written by `gog refresh`; it does not
+contact GOG. Human output includes ID, title, release year, genre/category, and
+platforms when those fields are available. JSON output also includes scriptable
+metadata such as `owned`, `release_date`, `genres`, and `is_installable`.
+
+Examples:
+
+```sh
+gog list purchased
+gog list purchased --format json
+gog list purchased --search witcher
+gog list purchased --search "baldurs gate"
+gog list purchased --platform windows
+gog list purchased --platform linux --search ftl
+gog list purchased --year 1998..2005
+gog list purchased --year 2010..2020 --include-unknown-year
+gog list purchased --genre strategy
+gog list purchased --genre arcade,rts
+gog list purchased --genre strategy --include-unknown-genre
+gog list purchased --search "baldurs gate" --platform linux --format json
+```
+
+Year filters omit games with unknown years by default; use
+`--include-unknown-year` to keep them. Genre filters similarly omit unknown
+genres by default; use `--include-unknown-genre` to keep those rows.
+
+## Planning Backups
+
+`gog plan` shows the same dry-run plan as `gog backup --dry-run` without
+downloading files or creating backup directories. Use it before long backup runs
+to estimate size, inspect filters, and check destination free space.
+
+Examples:
+
+```sh
+gog plan --destination /path/to/backups --all
+gog plan --destination /path/to/backups --all --summary
+gog plan --destination /path/to/backups --all --storage
+gog plan --destination /path/to/backups --all --check-free-space
+gog plan --destination /path/to/backups --all --format json
+gog plan --destination /path/to/backups cyberpunk_2077
+```
+
+Platform and language filters can reduce backup size:
+
+```sh
+gog plan --destination /path/to/backups --all --platform linux --storage
+gog plan --destination /path/to/backups --all --platform windows --language en --storage
+```
+
+## Selecting Games
+
+Game selectors can be product IDs, slugs, or exact titles. Commands that select
+games accept repeated `--game` flags:
+
+```sh
+gog plan --destination /path/to/backups --game witcher_3 --game cyberpunk_2077
+gog backup --destination /path/to/backups --game 123456789 --yes
+```
+
+For larger curated lists, put selectors in a UTF-8 text file and pass
+`--games-from`. Blank lines and lines whose first non-whitespace character is
+`#` are ignored.
+
+Example `games.txt`:
+
+```text
+# first NAS batch
+witcher_3
+cyberpunk_2077
+123456789
+```
+
+Use the selector file in plan, backup, or sync workflows:
+
+```sh
+gog plan --destination /path/to/backups --games-from games.txt --storage
+gog backup --destination /path/to/backups --games-from games.txt --downloader aria2c --yes
+gog sync --destination /path/to/backups --games-from games.txt --dry-run
+```
+
+`--games-from` is repeatable and combines with repeated `--game` flags. Do not
+combine explicit game selectors with `--all`.
+
+## Downloading
+
+`gog backup` defaults to the built-in direct downloader. To use `aria2c`, install
+`aria2c` and pass `--downloader aria2c` on an executing backup run:
+
+```sh
+gog backup --destination /path/to/backups --games-from games.txt --downloader aria2c --yes
+```
+
+Without `--yes`, backup and sync commands print a dry-run plan and exit without
+downloading or modifying backup files.

gog_cli-0.2.1/README.md

@@ -0,0 +1,153 @@
+# gog-cli
+
+[![CI](https://github.com/aleksandarristic/gog-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/aleksandarristic/gog-cli/actions/workflows/ci.yml)
+
+`gog` is a Python CLI for backing up a user's owned DRM-free GOG game library.
+
+It is focused on safe, scriptable workflows:
+
+- list owned games with filtering and fuzzy search
+- plan and execute backups to a local directory
+- preserve metadata needed to audit and restore backups
+- download installers and related files with resumable behavior
+- verify downloaded files when checksums are available
+
+## Install
+
+Requires Python 3.12 or newer.
+
+```sh
+pip install git+https://github.com/aleksandarristic/gog-cli.git
+```
+
+## Development
+
+```sh
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+Run the CLI locally:
+
+```sh
+gog --help
+gog list
+gog plan --destination /path/to/backups --all --summary
+gog backup --destination /path/to/backups --games-from games.txt --dry-run
+```
+
+## Basic Workflow
+
+```sh
+gog auth login
+gog refresh
+gog list purchased
+gog plan --destination /path/to/backups --all --storage --check-free-space
+gog backup --destination /path/to/backups --all --yes
+gog list backed-up --destination /path/to/backups
+gog sync --destination /path/to/backups --all --yes
+```
+
+`gog refresh` updates the local purchased-library and download-metadata caches.
+It does not download game installers. Run it before browsing or filtering newly
+added library metadata.
+
+## Browsing Purchased Games
+
+`gog list purchased` reads the local cache written by `gog refresh`; it does not
+contact GOG. Human output includes ID, title, release year, genre/category, and
+platforms when those fields are available. JSON output also includes scriptable
+metadata such as `owned`, `release_date`, `genres`, and `is_installable`.
+
+Examples:
+
+```sh
+gog list purchased
+gog list purchased --format json
+gog list purchased --search witcher
+gog list purchased --search "baldurs gate"
+gog list purchased --platform windows
+gog list purchased --platform linux --search ftl
+gog list purchased --year 1998..2005
+gog list purchased --year 2010..2020 --include-unknown-year
+gog list purchased --genre strategy
+gog list purchased --genre arcade,rts
+gog list purchased --genre strategy --include-unknown-genre
+gog list purchased --search "baldurs gate" --platform linux --format json
+```
+
+Year filters omit games with unknown years by default; use
+`--include-unknown-year` to keep them. Genre filters similarly omit unknown
+genres by default; use `--include-unknown-genre` to keep those rows.
+
+## Planning Backups
+
+`gog plan` shows the same dry-run plan as `gog backup --dry-run` without
+downloading files or creating backup directories. Use it before long backup runs
+to estimate size, inspect filters, and check destination free space.
+
+Examples:
+
+```sh
+gog plan --destination /path/to/backups --all
+gog plan --destination /path/to/backups --all --summary
+gog plan --destination /path/to/backups --all --storage
+gog plan --destination /path/to/backups --all --check-free-space
+gog plan --destination /path/to/backups --all --format json
+gog plan --destination /path/to/backups cyberpunk_2077
+```
+
+Platform and language filters can reduce backup size:
+
+```sh
+gog plan --destination /path/to/backups --all --platform linux --storage
+gog plan --destination /path/to/backups --all --platform windows --language en --storage
+```
+
+## Selecting Games
+
+Game selectors can be product IDs, slugs, or exact titles. Commands that select
+games accept repeated `--game` flags:
+
+```sh
+gog plan --destination /path/to/backups --game witcher_3 --game cyberpunk_2077
+gog backup --destination /path/to/backups --game 123456789 --yes
+```
+
+For larger curated lists, put selectors in a UTF-8 text file and pass
+`--games-from`. Blank lines and lines whose first non-whitespace character is
+`#` are ignored.
+
+Example `games.txt`:
+
+```text
+# first NAS batch
+witcher_3
+cyberpunk_2077
+123456789
+```
+
+Use the selector file in plan, backup, or sync workflows:
+
+```sh
+gog plan --destination /path/to/backups --games-from games.txt --storage
+gog backup --destination /path/to/backups --games-from games.txt --downloader aria2c --yes
+gog sync --destination /path/to/backups --games-from games.txt --dry-run
+```
+
+`--games-from` is repeatable and combines with repeated `--game` flags. Do not
+combine explicit game selectors with `--all`.
+
+## Downloading
+
+`gog backup` defaults to the built-in direct downloader. To use `aria2c`, install
+`aria2c` and pass `--downloader aria2c` on an executing backup run:
+
+```sh
+gog backup --destination /path/to/backups --games-from games.txt --downloader aria2c --yes
+```
+
+Without `--yes`, backup and sync commands print a dry-run plan and exit without
+downloading or modifying backup files.

gog_cli-0.2.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gog-cli"
+version = "0.2.1"
+description = "CLI tool for backing up DRM-free GOG games."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { file = "LICENSE" }
+authors = [
+  { name = "gog-cli contributors" }
+]
+
+dependencies = [
+  "requests>=2.32",
+]
+
+[project.urls]
+Homepage = "https://github.com/aleksandarristic/gog-cli"
+Repository = "https://github.com/aleksandarristic/gog-cli"
+"Bug Tracker" = "https://github.com/aleksandarristic/gog-cli/issues"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8",
+  "responses>=0.25",
+  "ruff>=0.4",
+]
+
+[project.scripts]
+gog = "gog_cli.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "N", "B", "UP", "SIM", "S", "PT"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101", "S105", "S107", "S108"]

gog_cli-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gog_cli-0.2.1/src/gog_cli/__init__.py

@@ -0,0 +1,5 @@
+"""gog-cli package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.2.1"

gog_cli-0.2.1/src/gog_cli/api.py

@@ -0,0 +1,143 @@
+"""GOG API client and TokenStore protocol."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Protocol
+
+import requests
+
+from gog_cli import log
+from gog_cli.errors import AuthError, NetworkError
+
+_log = log.get_logger(__name__)
+
+_CLIENT_ID = "46899977096215655"
+_CLIENT_SECRET = "9d85c43b1482497dbbce61f6e4aa173a433796eeae2ca8c5f6129f2dc4de46d9"  # noqa: S105 - Public GOG Galaxy OAuth client credential.
+_TOKEN_URL = "https://auth.gog.com/token"  # noqa: S105 - URL constant, not a secret.
+
+_OWNED_GAMES_URL = "https://embed.gog.com/user/data/games"
+_LIBRARY_URL = "https://embed.gog.com/account/getFilteredProducts"
+_PRODUCT_URL = "https://api.gog.com/products/{product_id}"
+# Unofficial public catalog search endpoint — no authentication required.
+_CATALOG_SEARCH_URL = "https://catalog.gog.com/v1/catalog"
+
+
+class TokenStore(Protocol):
+    def load_tokens(self) -> dict:
+        """Return stored tokens: {"access_token": str, "refresh_token": str, "expires_at": str}"""
+        ...
+
+    def save_tokens(self, tokens: dict) -> None:
+        """Persist updated tokens after a refresh."""
+        ...
+
+
+class GogApiClient:
+    def __init__(self, token_store: TokenStore) -> None:
+        self._token_store = token_store
+        self._session = requests.Session()
+
+    def _access_token(self) -> str:
+        return self._token_store.load_tokens()["access_token"]
+
+    def _auth_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self._access_token()}"}
+
+    def _refresh_tokens(self) -> None:
+        tokens = self._token_store.load_tokens()
+        try:
+            resp = self._session.get(
+                _TOKEN_URL,
+                params={
+                    "client_id": _CLIENT_ID,
+                    "client_secret": _CLIENT_SECRET,
+                    "grant_type": "refresh_token",
+                    "refresh_token": tokens["refresh_token"],
+                },
+                timeout=30,
+            )
+            resp.raise_for_status()
+        except requests.HTTPError as exc:
+            raise AuthError(f"token refresh failed: {exc}") from exc
+        except (requests.ConnectionError, requests.Timeout) as exc:
+            raise AuthError(f"token refresh network error: {exc}") from exc
+
+        data = resp.json()
+        expires_at = datetime.fromtimestamp(
+            datetime.now(tz=UTC).timestamp() + data["expires_in"],
+            tz=UTC,
+        ).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+        self._token_store.save_tokens(
+            {
+                **tokens,
+                "access_token": data["access_token"],
+                "refresh_token": data["refresh_token"],
+                "expires_at": expires_at,
+            }
+        )
+
+    def _get(self, url: str, **kwargs: object) -> requests.Response:
+        try:
+            resp = self._session.get(url, headers=self._auth_headers(), timeout=30, **kwargs)
+        except (requests.ConnectionError, requests.Timeout, ConnectionError) as exc:
+            raise NetworkError(f"network error: {exc}") from exc
+
+        if resp.status_code == 401:
+            self._refresh_tokens()
+            try:
+                resp = self._session.get(
+                    url, headers=self._auth_headers(), timeout=30, **kwargs
+                )
+            except (requests.ConnectionError, requests.Timeout, ConnectionError) as exc:
+                raise NetworkError(f"network error: {exc}") from exc
+            if resp.status_code == 401:
+                raise AuthError("authentication failed after token refresh")
+
+        if not resp.ok:
+            raise NetworkError(f"HTTP {resp.status_code}: {log.redact(url)}")
+
+        return resp
+
+    def get_owned_ids(self) -> list[int]:
+        resp = self._get(_OWNED_GAMES_URL)
+        return resp.json()["owned"]
+
+    def get_library_page(self, page: int) -> dict:
+        resp = self._get(_LIBRARY_URL, params={"mediaType": 1, "page": page})
+        return resp.json()
+
+    def get_product_downloads(self, product_id: int) -> dict:
+        url = _PRODUCT_URL.format(product_id=product_id)
+        resp = self._get(url, params={"expand": "downloads"})
+        return resp.json()
+
+    def resolve_downlink_url(self, downlink_url: str) -> tuple[str, str]:
+        resp = self._get(downlink_url)
+        data = resp.json()
+        return data["downlink"], data.get("checksum", "")
+
+
+def search_catalog(query: str, *, page: int = 1) -> dict:
+    """Search the public GOG catalog without authentication.
+
+    Uses an unofficial reverse-engineered endpoint; no stability guarantees.
+    """
+    try:
+        resp = requests.get(
+            _CATALOG_SEARCH_URL,
+            params={
+                "search": query,
+                "limit": 48,
+                "page": page,
+                "order": "desc:relevance",
+                "productType": "in:game",
+            },
+            timeout=30,
+        )
+        resp.raise_for_status()
+    except requests.HTTPError as exc:
+        raise NetworkError(f"catalog search failed: {exc}") from exc
+    except (requests.ConnectionError, requests.Timeout, ConnectionError) as exc:
+        raise NetworkError(f"catalog search network error: {exc}") from exc
+    return resp.json()