storycli 0.1.0__tar.gz

storycli-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.3
+Name: storycli
+Version: 0.1.0
+Summary: StoryCLI: CLI tool for downloading audiobooks from Storytel.
+Author: degD
+Author-email: degD <degd@degd.net>
+Requires-Dist: cryptography>=50.0.1
+Requires-Dist: python-dotenv>=1.2.3
+Requires-Dist: requests>=2.34.2
+Requires-Dist: tqdm>=4.70.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+
+# StoryCLI
+
+StoryCLI is an unofficial CLI tool for downloading your favourite audiobooks
+from Storytel without leaving your terminal. An active Storytel account is 
+required for using this tool.
+
+I am not responsible for any issues that this tool could cause, including
+but not limited to account blocking, temporary or permanent bans, loss of 
+time or monet. I built this tool only as a learning experience, and making
+it open-source so other people can see the source code and learn. Use it 
+at your own risk.
+
+- Download from PyPI: `pipx install storycli`
+
+## Authentication
+
+Create `~/.storycli` and fill it with your login credentials:
+
+```
+STORYCLI_MAIL=<your-storytel-email>
+STORYCLI_PASS=<your-storytel-password>
+```
+
+## Usage
+
+```
+usage: storycli [-h] (-q QUERY | -D BOOK_ID) [-o PATH] [-H]
+
+Search and download Storytel audiobooks.
+
+options:
+  -h, --help            show this help message and exit
+  -q QUERY, --query QUERY
+                        search for audiobooks
+  -D BOOK_ID, --download BOOK_ID
+                        download an audiobook
+  -o PATH, --output PATH
+                        MP3 output path (required with --download)
+  -H, --human-readable  do not format query lengths as hours:minutes:seconds
+
+```
+
+**Search an Audiobook:**
+
+    storycli -q <search-query>
+    storycli -q Dune
+    storycli --query Dune
+
+    ID       LENGTH    TITLE 
+    -------  --------  ---------------
+    ...
+    2759046   18:36:1  Paul of Dune
+    2836812  17:19:18  The Winds of Dune
+    2835170  19:31:19  Sandworms of Dune
+    ...
+
+**Download an Audiobook:**
+
+    storycli -D <book-id> -o <mp3-save-path>
+    storycli -D 2759046 -o ~/Downloads/2759046.mp3
+    storycli --download 2759046 -o ~/Downloads/2759046.mp3
+
+## Development
+
+* Install the `uv` project manager.
+* Clone the project and run `uv sync`.
+
+## Future Improvements
+
+* Prevent logging in everytime by storing login tokens.
+* Add book description preview.
+* Better UX.
+* Standalone Storytel TUI with builtin player.
+* Better error message management.
+
+## License 
+
+MIT

storycli-0.1.0/README.md

@@ -0,0 +1,79 @@
+
+# StoryCLI
+
+StoryCLI is an unofficial CLI tool for downloading your favourite audiobooks
+from Storytel without leaving your terminal. An active Storytel account is 
+required for using this tool.
+
+I am not responsible for any issues that this tool could cause, including
+but not limited to account blocking, temporary or permanent bans, loss of 
+time or monet. I built this tool only as a learning experience, and making
+it open-source so other people can see the source code and learn. Use it 
+at your own risk.
+
+- Download from PyPI: `pipx install storycli`
+
+## Authentication
+
+Create `~/.storycli` and fill it with your login credentials:
+
+```
+STORYCLI_MAIL=<your-storytel-email>
+STORYCLI_PASS=<your-storytel-password>
+```
+
+## Usage
+
+```
+usage: storycli [-h] (-q QUERY | -D BOOK_ID) [-o PATH] [-H]
+
+Search and download Storytel audiobooks.
+
+options:
+  -h, --help            show this help message and exit
+  -q QUERY, --query QUERY
+                        search for audiobooks
+  -D BOOK_ID, --download BOOK_ID
+                        download an audiobook
+  -o PATH, --output PATH
+                        MP3 output path (required with --download)
+  -H, --human-readable  do not format query lengths as hours:minutes:seconds
+
+```
+
+**Search an Audiobook:**
+
+    storycli -q <search-query>
+    storycli -q Dune
+    storycli --query Dune
+
+    ID       LENGTH    TITLE 
+    -------  --------  ---------------
+    ...
+    2759046   18:36:1  Paul of Dune
+    2836812  17:19:18  The Winds of Dune
+    2835170  19:31:19  Sandworms of Dune
+    ...
+
+**Download an Audiobook:**
+
+    storycli -D <book-id> -o <mp3-save-path>
+    storycli -D 2759046 -o ~/Downloads/2759046.mp3
+    storycli --download 2759046 -o ~/Downloads/2759046.mp3
+
+## Development
+
+* Install the `uv` project manager.
+* Clone the project and run `uv sync`.
+
+## Future Improvements
+
+* Prevent logging in everytime by storing login tokens.
+* Add book description preview.
+* Better UX.
+* Standalone Storytel TUI with builtin player.
+* Better error message management.
+
+## License 
+
+MIT

storycli-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "storycli"
+version = "0.1.0"
+description = "StoryCLI: CLI tool for downloading audiobooks from Storytel."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "cryptography>=50.0.1",
+    "python-dotenv>=1.2.3",
+    "requests>=2.34.2",
+    "tqdm>=4.70.0",
+]
+
+[[project.authors]]
+name = "degD"
+email = "degd@degd.net"
+
+[project.scripts]
+storycli = "storycli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13.0"]
+build-backend = "uv_build"

storycli-0.1.0/pyproject.toml.orig

@@ -0,0 +1,22 @@
+[project]
+name = "storycli"
+version = "0.1.0"
+description = "StoryCLI: CLI tool for downloading audiobooks from Storytel."
+readme = "README.md"
+authors = [
+    { name = "degD", email = "degd@degd.net" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "cryptography>=50.0.1",
+    "python-dotenv>=1.2.3",
+    "requests>=2.34.2",
+    "tqdm>=4.70.0",
+]
+
+[project.scripts]
+storycli = "storycli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.9,<0.13.0"]
+build-backend = "uv_build"

storycli-0.1.0/src/storycli/__init__.py

@@ -0,0 +1 @@
+from .main import main

storycli-0.1.0/src/storycli/main.py

@@ -0,0 +1,231 @@
+
+"""
+StoryCLI: CLI tool for downloading audiobooks from Storytel. Requires an active Storytel
+account. To use this tool, create the file "~/.storycli" and put your login credentials
+here. 
+"""
+
+from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+from cryptography.hazmat.primitives import padding
+from pathlib import Path
+from tqdm import tqdm
+import argparse
+import dotenv
+import os
+import requests
+import sys
+
+
+class LoginInfo:
+    """Manage login credentials and required password hashing."""
+
+    KEY = b"VQZBJ6TD8M9WBUWT"
+    IV = b"joiwef08u23j341a"
+
+    def __init__(self, email: str, password: str):
+        self.email = email
+        self.password = self.__hashPassword(password)
+
+    def __hashPassword(self, password: str) -> str:
+        padder = padding.PKCS7(algorithms.AES.block_size).padder()  # type: ignore
+        padded_password = padder.update(password.encode("utf-8"))
+        padded_password += padder.finalize()
+        cipher = Cipher(algorithms.AES(LoginInfo.KEY), modes.CBC(LoginInfo.IV))
+        encryptor = cipher.encryptor()
+        ciphertext = encryptor.update(padded_password)
+        ciphertext += encryptor.finalize()
+        return ciphertext.hex().upper()
+
+
+class AccountInfo:
+    """Helper class for managing tokens."""
+
+    def __init__(self, jwt: str, sst: str):
+        self.jwt = jwt
+        self.sst = sst
+
+
+class BookData:
+    """Helper class for managing and representing book objects."""
+
+    def __init__(self, id: int, title: str, authors: str, length: int, description: str):
+        self.id = id
+        self.title = title
+        self.authors = authors
+        self.length = length
+        self.description = description
+
+
+class StoryAPI:
+    """Manage access to Storytel API endpoints."""
+
+    CHUNK_SIZE = 1048576  # 1 MB
+
+    def __init__(self):
+        self.accountInfo: AccountInfo | None = None
+
+    def login(self, loginInfo: LoginInfo) -> bool:
+        """
+        Login to Storytel using given `LoginInfo` object.
+        Returns True if login successful. Returns False if something fails.
+        """
+        url = f"https://www.storytel.com/api/login.action?m=1&uid={loginInfo.email.strip()}&pwd={loginInfo.password}"
+        try:
+            response = requests.get(url)
+            if response.status_code == 200:
+                data = response.json()
+                self.accountInfo = AccountInfo(
+                    data["accountInfo"]["jwt"],
+                    data["accountInfo"]["singleSignToken"],
+                )
+                return True
+        except (requests.RequestException, KeyError, ValueError):
+            pass
+        return False
+
+    def searchBook(self, query: str) -> tuple[bool, list[BookData]]:
+        """
+        Search by given query. Returns a tuple with a bool representing status
+        and a list of `BookData` objects. Doesn't work if not logged in.
+        Bool is True if everything is successful. False otherwise.
+        """
+        if self.accountInfo is None:
+            return (False, [])
+        try:
+            url = f"https://www.storytel.com/api/search.action?q={query}&token={self.accountInfo.sst}"
+            response = requests.get(url)
+            if response.status_code != 200:
+                return (False, [])
+            books = [book for book in response.json()["books"] if book["abook"] is not None]
+            return (True, [
+                BookData(
+                    book["abook"]["id"],
+                    book["book"]["name"],
+                    book["book"]["authorsAsString"],
+                    book["abook"]["length"],
+                    book["abook"]["description"],
+                )
+                for book in books
+            ])
+        except (requests.RequestException, KeyError, TypeError, ValueError):
+            return (False, [])
+
+    def downloadBook(self, bookId: int, path: Path) -> bool:
+        """
+        Download the audiobook represented by the `bookId` to `path`.
+        Returns False if something fails or not logged in. True if
+        successful.
+        """
+        if self.accountInfo is None:
+            return False
+        url = f"https://www.storytel.com/mp3streamRangeReq?startposition=0&programId={bookId}&token={self.accountInfo.sst}"
+        try:
+            response = requests.get(url, stream=True)
+            if response.status_code == 200:
+                with open(path, "wb") as file:
+                    total_size = int(response.headers.get("content-length", 0)) or None
+                    with tqdm(total=total_size, unit="B", unit_scale=True, desc="Downloading") as progress:
+                        for chunk in response.iter_content(chunk_size=self.CHUNK_SIZE):
+                            if chunk:
+                                file.write(chunk)
+                                progress.update(len(chunk))
+                return True
+        except (OSError, TypeError, ValueError, requests.RequestException):
+            pass
+        return False
+
+
+class StoryCLI:
+    """Represents the CLI command/tool."""
+
+    LOGIN_FILE_PATH = Path("~/.storycli")
+
+    def __init__(self):
+        self.api = StoryAPI()
+        login_info = self.__loadLoginInfo()
+
+        # self.status represents the status of the login procedure.
+        # 0: LoginInfo loaded and logged in correctly.
+        # 1: Unable to load LoginInfo. File could be missing.
+        # 2: Login failed. Credentials could be wrong.
+        self.status = 0 
+        if login_info is None:
+            self.status = 1
+        elif not self.api.login(login_info):
+            self.status = 2
+
+    def __loadLoginInfo(self) -> LoginInfo | None:
+        """
+        Try loading the `LOGIN_FILE_PATH` file, which contains credentials
+        in `.env` file format. If successful, return `LoginInfo`. Return
+        None otherwise.
+        """
+        dotenv.load_dotenv(self.LOGIN_FILE_PATH.expanduser())
+        email = os.getenv("STORYCLI_MAIL")
+        password = os.getenv("STORYCLI_PASS")
+        if email is not None and password is not None:
+            return LoginInfo(email, password)
+        return None
+
+    def search(self, query: str) -> tuple[bool, list[BookData]]:
+        """
+        Search by given query. Returns a tuple with a bool representing status
+        and a list of `BookData` objects. Doesn't work if not logged in.
+        Bool is True if everything is successful. False otherwise.
+        """
+        return self.api.searchBook(query) if self.status == 0 else (False, [])
+
+    def download(self, bookId: int, path: Path) -> bool:
+        """
+        Download the audiobook represented by the `bookId` to `path`.
+        Returns False if something fails or not logged in. True if
+        successful.
+        """
+        return self.status == 0 and self.api.downloadBook(bookId, path)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Main CLI command function."""
+
+    def format_length(length: int) -> str:
+        """Return milliseconds `length` in human-readable format."""
+        seconds = length // 1000
+        hours = seconds // 3600
+        minutes = (seconds % 3600) // 60
+        return f"{hours}:{minutes}:{seconds % 60}"
+
+    parser = argparse.ArgumentParser(description="Search and download Storytel audiobooks.")
+    operations = parser.add_mutually_exclusive_group(required=True)
+    operations.add_argument("-q", "--query", metavar="QUERY", help="search for audiobooks")
+    operations.add_argument("-D", "--download", type=int, metavar="BOOK_ID", help="download an audiobook")
+    parser.add_argument("-o", "--output", type=Path, metavar="PATH", help="MP3 output path (required with --download)")
+    parser.add_argument("-H", "--human-readable", action="store_true", help="do not format query lengths as hours:minutes:seconds")
+    args = parser.parse_args(argv)
+
+    if args.download is not None and args.output is None:
+        parser.error("--output is required with --download")
+    if args.download is None and args.output is not None:
+        parser.error("--output may only be used with --download")
+
+    cli = StoryCLI()
+    if cli.status == 1:
+        print("error: credentials missing; set STORYCLI_MAIL and STORYCLI_PASS in ~/.storycli", file=sys.stderr)
+        return 1
+    if cli.status == 2:
+        print("error: login failed; check the credentials in ~/.storycli", file=sys.stderr)
+        return 2
+
+    if args.query is not None:
+        success, books = cli.search(args.query)
+        if not success:
+            print("error: search failed", file=sys.stderr)
+            return 3
+        for book in books:
+            length = format_length(book.length) if not args.human_readable else str(book.length)
+            print(f"{str(book.id).rjust(10)}  {length.rjust(8)}  {book.title}")
+        return 0
+
+    if cli.download(args.download, args.output): # type: ignore
+        return 0
+    print(f"error: download failed for book {args.download}", file=sys.stderr)
+    return 3