From f5ee64cb6d4056e2259ba91918217d3842f88163 Mon Sep 17 00:00:00 2001
From: ^_^ <8480595+ballaballaballa@users.noreply.github.com>
Date: Tue, 28 Oct 2025 22:28:30 +0100
Subject: [PATCH 01/11] Update README with correct paths for config file

---
 README.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 4fa2135..87cf544 100644
--- a/README.md
+++ b/README.md
@@ -54,7 +54,10 @@ grawlix --username "user@example.com" --password "SuperSecretPassword" <url>
 username = "user@example.com"
 password = "SuperSecretPassword"
 ```
-Config file should be placed in `~/.config/grawlix/grawlix.toml`
+Config file should be placed in:
+- Linux: `~/.config/grawlix/grawlix.toml`
+- macOS: `~/Library/Application Support/grawlix/grawlix.toml`
+- Windows: `%LOCALAPPDATA%\jo1gi\grawlix\grawlix.toml`
 
 ### Cookies
 Some sources can be authenticated with Netscape cookie files. I use

From ea7ca71408c0c8dd1c9b3afadea9ab6cc09733d6 Mon Sep 17 00:00:00 2001
From: ^_^ <8480595+ballaballaballa@users.noreply.github.com>
Date: Wed, 29 Oct 2025 00:06:50 +0100
Subject: [PATCH 02/11] Added functionality to write metadata to epub. Only for
 Storytel for now. Can be triggered with parameter or set in config. Added
 option to add output path to config file.

---
 README.md                        | 109 ++++++++++-
 grawlix/__main__.py              |  59 +++++-
 grawlix/arguments.py             |   7 +
 grawlix/book.py                  |   3 +-
 grawlix/config.py                |  22 ++-
 grawlix/epub_metadata.py         | 303 +++++++++++++++++++++++++++++++
 grawlix/epub_metadata_writers.py |  71 ++++++++
 grawlix/output/__init__.py       |  72 +++++++-
 grawlix/sources/storytel.py      |  70 ++++++-
 9 files changed, 691 insertions(+), 25 deletions(-)
 create mode 100644 grawlix/epub_metadata.py
 create mode 100644 grawlix/epub_metadata_writers.py

diff --git a/README.md b/README.md
index 87cf544..b327f00 100644
--- a/README.md
+++ b/README.md
@@ -50,10 +50,15 @@ grawlix --username "user@example.com" --password "SuperSecretPassword" <url>
 
 **Config file example**
 ```toml
-[sources.name]
+# Global settings
+write_metadata_to_epub = true
+output = "~/ebooks/{series}/{index} - {title}.{ext}"
+
+[sources.storytel]
 username = "user@example.com"
 password = "SuperSecretPassword"
 ```
+
 Config file should be placed in:
 - Linux: `~/.config/grawlix/grawlix.toml`
 - macOS: `~/Library/Application Support/grawlix/grawlix.toml`
@@ -61,14 +66,112 @@ Config file should be placed in:
 
 ### Cookies
 Some sources can be authenticated with Netscape cookie files. I use
-[this extension](https://github,com/rotemdan/ExportCookies) to export my
+[this extension](https://github.com/rotemdan/ExportCookies) to export my
 cookies from my browser.
 
 Cookies can be placed in current dir as `cookies.txt` or be given with the
-`--cookie` argument.
+`--cookies` argument.
+
+## Configuration
+
+### Global Settings
+
+The following settings can be added to your config file (before any `[sources.*]` sections):
+
+| Setting | Type | Description | Example |
+|---------|------|-------------|---------|
+| `write_metadata_to_epub` | boolean | Automatically write metadata to EPUB files (currently supports Storytel) | `true` or `false` |
+| `output` | string | Default output path template (supports `~`, environment variables, and template variables) | `"~/ebooks/{title}.{ext}"` |
+
+### Output Templates
+
+The `output` setting supports template variables that are replaced with book metadata:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `{title}` | Book title | "The Witcher" |
+| `{series}` | Series name | "The Witcher Saga" |
+| `{index}` | Series index/number | "1" |
+| `{authors}` | Authors (semicolon-separated) | "Andrzej Sapkowski" |
+| `{publisher}` | Publisher name | "Orbit" |
+| `{language}` | Language code | "en" |
+| `{release_date}` | Release date | "2020-01-15" |
+| `{ext}` | File extension | "epub" |
+
+**Example templates:**
+```toml
+# Simple
+output = "~/books/{title}.{ext}"
+
+# Organized by series
+output = "~/books/{series}/{index} - {title}.{ext}"
+
+# With author
+output = "~/books/{authors}/{series}/{title}.{ext}"
+```
+
+**Path expansion:**
+- `~` expands to home directory
+- Environment variables work: `$HOME` (Unix) or `%USERPROFILE%` (Windows)
+- Absolute paths: `/path/to/books` or `C:\Books`
+- Relative paths: `downloads/{title}.{ext}` (relative to current directory)
 
 ## Download books
+
 To download a book run:
 ```shell
 grawlix [options] <book url>
 ```
+
+### Command Line Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--version` | `-v` | Show version number |
+| `--file <path>` | `-f` | File with URLs (one per line) |
+| `--username <email>` | `-u` | Username for authentication |
+| `--password <password>` | `-p` | Password for authentication |
+| `--library <name>` | | Library name (for sources that require it) |
+| `--cookies <path>` | `-c` | Path to Netscape cookie file |
+| `--output <template>` | `-o` | Output path template (overrides config) |
+| `--write-metadata-to-epub` | | Write metadata to EPUB files (overrides config) |
+| `--debug` | | Enable debug messages |
+
+**Examples:**
+```shell
+# Download to specific location
+grawlix -o "~/downloads/{title}.{ext}" <url>
+
+# Download with metadata writing
+grawlix --write-metadata-to-epub <url>
+
+# Batch download from file
+grawlix -f urls.txt
+
+# With authentication
+grawlix -u user@example.com -p password <url>
+
+# Debug mode
+grawlix --debug <url>
+```
+
+## Metadata Writing
+
+For supported sources (currently Storytel), grawlix can write rich metadata to EPUB files including:
+
+- Title and original title
+- Authors and translators
+- Series information (Calibre-compatible)
+- Publisher, ISBN, language
+- Description and categories
+- Release date
+
+Enable globally in config:
+```toml
+write_metadata_to_epub = true
+```
+
+Or use the CLI flag for one-time use:
+```shell
+grawlix --write-metadata-to-epub <url>
+```
diff --git a/grawlix/__main__.py b/grawlix/__main__.py
index 7ebd75f..da49a32 100644
--- a/grawlix/__main__.py
+++ b/grawlix/__main__.py
@@ -12,6 +12,10 @@ from functools import partial
 import os
 import asyncio
 import traceback
+import warnings
+
+# Suppress deprecation warnings from dependencies
+warnings.filterwarnings("ignore", category=UserWarning, module="google.protobuf")
 
 
 def get_or_ask(attr: str, hidden: bool, source_config: Optional[SourceConfig], options) -> str:
@@ -107,10 +111,13 @@ async def main() -> None:
             result = await source.download(url)
             if isinstance(result, Book):
                 with logging.progress(result.metadata.title, source.name) as progress:
-                    template: str = args.output or "{title}.{ext}"
-                    await download_with_progress(result, progress, template)
+                    # Check CLI flag first, then config file, then default
+                    template: str = args.output or config.output or "{title}.{ext}"
+                    # Check both CLI flag and config file
+                    write_metadata = args.write_metadata_to_epub or config.write_metadata_to_epub
+                    await download_with_progress(result, progress, template, write_metadata)
             elif isinstance(result, Series):
-                await download_series(source, result, args)
+                await download_series(source, result, args, config)
             logging.info("")
         except GrawlixError as error:
             error.print_error()
@@ -119,34 +126,72 @@ async def main() -> None:
             exit(1)
 
 
-async def download_series(source: Source, series: Series, args) -> None:
+async def download_series(source: Source, series: Series, args, config: Config) -> None:
     """
     Download books in series
 
     :param series: Series to download
+    :param args: CLI arguments
+    :param config: Configuration
     """
-    template = args.output or "{series}/{title}.{ext}"
+    # Check CLI flag first, then config file, then default
+    template = args.output or config.output or "{series}/{title}.{ext}"
+    # Check both CLI flag and config file
+    write_metadata = args.write_metadata_to_epub or config.write_metadata_to_epub
     with logging.progress(series.title, source.name, len(series.book_ids)) as progress:
         for book_id in series.book_ids:
             try:
                 book: Book = await source.download_book_from_id(book_id)
-                await download_with_progress(book, progress, template)
+                await download_with_progress(book, progress, template, write_metadata)
             except AccessDenied as error:
                 logging.info("Skipping - Access Denied")
 
 
 
-async def download_with_progress(book: Book, progress: Progress, template: str):
+async def download_with_progress(book: Book, progress: Progress, template: str, write_metadata: bool = False):
     """
     Download book with progress bar in cli
 
     :param book: Book to download
     :param progress: Progress object
     :param template: Output template
+    :param write_metadata: Whether to write metadata to EPUB files
     """
     task = logging.add_book(progress, book)
     update_function = partial(progress.advance, task)
+
+    # Download the book
     await download_book(book, update_function, template)
+
+    # Write metadata if requested and available
+    if write_metadata and book.source_data:
+        from .output import format_output_location, get_default_format, find_output_format
+        from . import epub_metadata, epub_metadata_writers
+
+        # Determine output file location
+        _, ext = os.path.splitext(template)
+        ext = ext[1:]
+        if ext:
+            output_format = find_output_format(book, ext)()
+        else:
+            output_format = get_default_format(book)
+
+        location = format_output_location(book, output_format, template)
+
+        # Write metadata if it's an EPUB file
+        if location.endswith('.epub') and os.path.exists(location):
+            # Get source-specific data and transformer
+            source_name = book.source_data.get('source_name')
+            source_details = book.source_data.get('details')
+
+            if source_name and source_details:
+                transformer = epub_metadata_writers.get_transformer(source_name)
+                if transformer:
+                    transformed_metadata = transformer(source_details)
+                    epub_metadata.write_metadata_to_epub(transformed_metadata, location)
+                else:
+                    logging.debug(f"No metadata transformer found for source: {source_name}")
+
     progress.advance(task, 1)
 
 
diff --git a/grawlix/arguments.py b/grawlix/arguments.py
index 9ad5810..5e74851 100644
--- a/grawlix/arguments.py
+++ b/grawlix/arguments.py
@@ -59,4 +59,11 @@ def parse_arguments() -> argparse.Namespace:
         dest = "debug",
         action="store_true",
     )
+    # Metadata
+    parser.add_argument(
+        '--write-metadata-to-epub',
+        help = "Write metadata to EPUB files when downloading",
+        dest = "write_metadata_to_epub",
+        action="store_true",
+    )
     return parser.parse_args()
diff --git a/grawlix/book.py b/grawlix/book.py
index 1fe6da6..7c24369 100644
--- a/grawlix/book.py
+++ b/grawlix/book.py
@@ -20,7 +20,7 @@ class Metadata:
         return {
             "title": self.title,
             "series": self.series or "UNKNOWN",
-            "index": self.index or "UNKNOWN",
+            "index": str(self.index) if self.index is not None else "UNKNOWN",
             "publisher": self.publisher or "UNKNOWN",
             "identifier": self.identifier or "UNKNOWN",
             "language": self.language or "UNKNOWN",
@@ -97,6 +97,7 @@ class Book:
     metadata: Metadata
     data: BookData
     overwrite: bool = False
+    source_data: Optional[dict] = None  # For storing source-specific data
 
 T = TypeVar("T")
 
diff --git a/grawlix/config.py b/grawlix/config.py
index 7b053a9..68b9caa 100644
--- a/grawlix/config.py
+++ b/grawlix/config.py
@@ -16,6 +16,8 @@ class SourceConfig:
 class Config:
     """Grawlix configuration"""
     sources: dict[str, SourceConfig]
+    write_metadata_to_epub: bool = False
+    output: Optional[str] = None
 
 
 def load_config() -> Config:
@@ -27,8 +29,17 @@ def load_config() -> Config:
     config_dir = appdirs.user_config_dir("grawlix", "jo1gi")
     config_file = os.path.join(config_dir, "grawlix.toml")
     if os.path.exists(config_file):
-        with open(config_file, "rb") as f:
-            config_dict = tomli.load(f)
+        try:
+            with open(config_file, "rb") as f:
+                config_dict = tomli.load(f)
+        except tomli.TOMLDecodeError as e:
+            print(f"Error parsing config file: {config_file}")
+            print(f"  {e}")
+            print("\nPlease check your TOML syntax. Common issues:")
+            print("  - Strings must be quoted: output = \"{title}.{ext}\" not output = {title}.{ext}")
+            print("  - Booleans are lowercase: write_metadata_to_epub = true (not True)")
+            print("  - Use double quotes for strings containing special characters")
+            raise
     else:
         config_dict = {}
     sources = {}
@@ -38,4 +49,9 @@ def load_config() -> Config:
                 username = values.get("username"),
                 password = values.get("password"),
             )
-    return Config(sources)
+
+    # Load general settings
+    write_metadata_to_epub = config_dict.get("write_metadata_to_epub", False)
+    output = config_dict.get("output")
+
+    return Config(sources, write_metadata_to_epub, output)
diff --git a/grawlix/epub_metadata.py b/grawlix/epub_metadata.py
new file mode 100644
index 0000000..62e7abd
--- /dev/null
+++ b/grawlix/epub_metadata.py
@@ -0,0 +1,303 @@
+"""
+Generic EPUB metadata writer
+
+Handles writing standardized metadata to EPUB files from any source
+"""
+
+from grawlix import logging
+import zipfile
+import tempfile
+import os
+import shutil
+
+
+def write_metadata_to_epub(metadata: dict, epub_path: str) -> None:
+    """
+    Write standardized metadata to EPUB file
+
+    Expected metadata format:
+    {
+        "title": str,
+        "original_title": Optional[str],
+        "authors": List[str],
+        "translators": List[str],
+        "description": Optional[str],
+        "language": Optional[str],
+        "publisher": Optional[str],
+        "isbn": Optional[str],
+        "release_date": Optional[str],  # YYYY-MM-DD format
+        "category": Optional[str],
+        "tags": List[str],
+        "series_name": Optional[str],
+        "series_index": Optional[int]
+    }
+
+    :param metadata: Standardized metadata dict
+    :param epub_path: Path to the EPUB file
+    """
+    try:
+        from lxml import etree as ET
+        using_lxml = True
+    except ImportError:
+        import xml.etree.ElementTree as ET
+        using_lxml = False
+
+    # EPUB namespaces
+    NAMESPACES = {
+        'opf': 'http://www.idpf.org/2007/opf',
+        'dc': 'http://purl.org/dc/elements/1.1/',
+        'dcterms': 'http://purl.org/dc/terms/',
+    }
+
+    # Register namespaces for ElementTree
+    if not using_lxml:
+        for prefix, uri in NAMESPACES.items():
+            ET.register_namespace(prefix, uri)
+
+    # Create temporary directory for EPUB extraction
+    temp_dir = tempfile.mkdtemp()
+
+    try:
+        # Extract EPUB
+        with zipfile.ZipFile(epub_path, 'r') as zip_ref:
+            zip_ref.extractall(temp_dir)
+
+        # Find OPF file
+        opf_path = _find_opf_file(temp_dir)
+        if not opf_path:
+            logging.debug("Could not find OPF file in EPUB")
+            return
+
+        # Parse OPF file
+        if using_lxml:
+            parser = ET.XMLParser(recover=True, encoding='utf-8')
+            tree = ET.parse(opf_path, parser)
+        else:
+            tree = ET.parse(opf_path)
+
+        root = tree.getroot()
+
+        # Find metadata element
+        if using_lxml:
+            metadata_elem = root.find('.//opf:metadata', NAMESPACES)
+        else:
+            metadata_elem = root.find('opf:metadata', NAMESPACES)
+
+        if metadata_elem is None:
+            logging.debug("Could not find metadata element in OPF")
+            return
+
+        # Update metadata
+        _update_epub_metadata(metadata_elem, metadata, NAMESPACES, using_lxml)
+
+        # Write updated OPF
+        if using_lxml:
+            tree.write(opf_path, encoding='utf-8', xml_declaration=True, pretty_print=True)
+        else:
+            tree.write(opf_path, encoding='utf-8', xml_declaration=True)
+
+        # Repack EPUB
+        _repack_epub(temp_dir, epub_path)
+
+        logging.debug("Successfully wrote metadata to EPUB")
+
+    finally:
+        # Cleanup
+        shutil.rmtree(temp_dir)
+
+
+def _find_opf_file(epub_dir: str) -> str:
+    """Find the OPF file in extracted EPUB directory"""
+    container_path = os.path.join(epub_dir, 'META-INF', 'container.xml')
+
+    if os.path.exists(container_path):
+        try:
+            from lxml import etree as ET
+        except ImportError:
+            import xml.etree.ElementTree as ET
+
+        tree = ET.parse(container_path)
+        root = tree.getroot()
+        rootfile = root.find('.//{urn:oasis:names:tc:opendocument:xmlns:container}rootfile')
+        if rootfile is not None:
+            opf_relative_path = rootfile.get('full-path')
+            return os.path.join(epub_dir, opf_relative_path)
+
+    # Fallback: search for .opf file
+    for root_dir, dirs, files in os.walk(epub_dir):
+        for file in files:
+            if file.endswith('.opf'):
+                return os.path.join(root_dir, file)
+
+    return None
+
+
+def _update_epub_metadata(metadata_elem, metadata: dict, ns: dict, using_lxml: bool) -> None:
+    """Update EPUB metadata elements with standardized metadata"""
+
+    # Helper function to create/update element
+    def update_or_create_element(tag: str, text: str, attribs: dict = None):
+        if not text:
+            return
+
+        # Remove existing elements with this tag
+        for elem in list(metadata_elem.findall(tag, ns)):
+            metadata_elem.remove(elem)
+
+        # Create new element
+        if using_lxml:
+            from lxml import etree as ET
+            elem = ET.SubElement(metadata_elem, tag)
+        else:
+            import xml.etree.ElementTree as ET
+            elem = ET.SubElement(metadata_elem, tag)
+
+        elem.text = str(text)
+        if attribs:
+            for key, value in attribs.items():
+                elem.set(key, value)
+
+    # Helper to create meta element
+    def create_meta(name: str, content: str):
+        if not content:
+            return
+
+        if using_lxml:
+            from lxml import etree as ET
+            meta = ET.SubElement(metadata_elem, f"{{{ns['opf']}}}meta")
+        else:
+            import xml.etree.ElementTree as ET
+            meta = ET.SubElement(metadata_elem, f"{{{ns['opf']}}}meta")
+
+        meta.set('name', name)
+        meta.set('content', str(content))
+
+    # Title
+    update_or_create_element(f"{{{ns['dc']}}}title", metadata.get("title"))
+
+    # Original Title (EPUB 3 with refinements)
+    if metadata.get("original_title"):
+        # Create title with ID for main title
+        for elem in list(metadata_elem.findall(f"{{{ns['dc']}}}title", ns)):
+            elem.set('id', 'main-title')
+
+        # Add original title
+        if using_lxml:
+            from lxml import etree as ET
+            orig_title = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}title")
+        else:
+            import xml.etree.ElementTree as ET
+            orig_title = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}title")
+
+        orig_title.set('id', 'original-title')
+        orig_title.text = metadata["original_title"]
+
+        # Add meta refinement for original title
+        if using_lxml:
+            meta = ET.SubElement(metadata_elem, f"{{{ns['opf']}}}meta")
+        else:
+            meta = ET.SubElement(metadata_elem, f"{{{ns['opf']}}}meta")
+        meta.set('refines', '#original-title')
+        meta.set('property', 'title-type')
+        meta.text = 'original'
+
+    # Authors
+    for author in metadata.get("authors", []):
+        if using_lxml:
+            from lxml import etree as ET
+            creator = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}creator")
+        else:
+            import xml.etree.ElementTree as ET
+            creator = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}creator")
+        creator.text = author
+        creator.set(f"{{{ns['opf']}}}role", "aut")
+
+    # Translators
+    for translator in metadata.get("translators", []):
+        if using_lxml:
+            from lxml import etree as ET
+            contributor = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}contributor")
+        else:
+            import xml.etree.ElementTree as ET
+            contributor = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}contributor")
+        contributor.text = translator
+        contributor.set(f"{{{ns['opf']}}}role", "trl")
+
+    # Description (Unicode is automatically handled by lxml/ET)
+    update_or_create_element(f"{{{ns['dc']}}}description", metadata.get("description"))
+
+    # Language
+    update_or_create_element(f"{{{ns['dc']}}}language", metadata.get("language"))
+
+    # Publisher
+    update_or_create_element(f"{{{ns['dc']}}}publisher", metadata.get("publisher"))
+
+    # ISBN
+    isbn = metadata.get("isbn")
+    if isbn:
+        # Remove existing ISBN identifiers
+        for elem in list(metadata_elem.findall(f"{{{ns['dc']}}}identifier", ns)):
+            scheme = elem.get(f"{{{ns['opf']}}}scheme")
+            if scheme and scheme.upper() == "ISBN":
+                metadata_elem.remove(elem)
+
+        # Add new ISBN
+        if using_lxml:
+            from lxml import etree as ET
+            identifier = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}identifier")
+        else:
+            import xml.etree.ElementTree as ET
+            identifier = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}identifier")
+        identifier.text = isbn
+        identifier.set(f"{{{ns['opf']}}}scheme", "ISBN")
+
+    # Release Date (already formatted as YYYY-MM-DD)
+    update_or_create_element(f"{{{ns['dc']}}}date", metadata.get("release_date"))
+
+    # Category
+    category = metadata.get("category")
+    if category:
+        if using_lxml:
+            from lxml import etree as ET
+            subject = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}subject")
+        else:
+            import xml.etree.ElementTree as ET
+            subject = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}subject")
+        subject.text = category
+
+    # Tags
+    for tag in metadata.get("tags", []):
+        if using_lxml:
+            from lxml import etree as ET
+            subject = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}subject")
+        else:
+            import xml.etree.ElementTree as ET
+            subject = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}subject")
+        subject.text = tag
+
+    # Series info (Calibre format)
+    if metadata.get("series_name"):
+        create_meta("calibre:series", metadata.get("series_name"))
+        create_meta("calibre:series_index", metadata.get("series_index"))
+
+
+def _repack_epub(epub_dir: str, output_path: str) -> None:
+    """Repack EPUB directory into ZIP file"""
+    # Remove old EPUB
+    if os.path.exists(output_path):
+        os.remove(output_path)
+
+    with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as epub_zip:
+        # mimetype must be first and uncompressed
+        mimetype_path = os.path.join(epub_dir, 'mimetype')
+        if os.path.exists(mimetype_path):
+            epub_zip.write(mimetype_path, 'mimetype', compress_type=zipfile.ZIP_STORED)
+
+        # Add all other files
+        for root, dirs, files in os.walk(epub_dir):
+            for file in files:
+                if file == 'mimetype':
+                    continue
+                file_path = os.path.join(root, file)
+                arcname = os.path.relpath(file_path, epub_dir)
+                epub_zip.write(file_path, arcname)
diff --git a/grawlix/epub_metadata_writers.py b/grawlix/epub_metadata_writers.py
new file mode 100644
index 0000000..fb202fb
--- /dev/null
+++ b/grawlix/epub_metadata_writers.py
@@ -0,0 +1,71 @@
+"""
+Source-specific EPUB metadata transformers
+
+Each source can provide a transformer function that converts their source_data
+into a standardized metadata format for EPUB writing.
+"""
+
+from datetime import datetime
+from typing import Optional
+
+
+def storytel_transformer(details: dict) -> dict:
+    """
+    Transform Storytel book details JSON into standardized EPUB metadata format
+
+    :param details: Storytel book details JSON
+    :return: Standardized metadata dict
+    """
+    # Extract ebook format
+    ebook_format = None
+    for fmt in details.get("formats", []):
+        if fmt.get("type") == "ebook":
+            ebook_format = fmt
+            break
+
+    metadata = {
+        "title": details.get("title"),
+        "original_title": details.get("originalTitle"),
+        "authors": [author.get("name", "") for author in details.get("authors", [])],
+        "translators": [translator.get("name", "") for translator in details.get("translators", [])],
+        "description": details.get("description"),
+        "language": details.get("language"),
+        "category": details.get("category", {}).get("name"),
+        "tags": [tag.get("name", "") for tag in details.get("tags", [])[:10]],  # Max 10
+    }
+
+    # Ebook-specific metadata
+    if ebook_format:
+        metadata["publisher"] = ebook_format.get("publisher", {}).get("name")
+        metadata["isbn"] = ebook_format.get("isbn")
+
+        release_date = ebook_format.get("releaseDate")
+        if release_date:
+            # Format as YYYY-MM-DD
+            date_obj = datetime.fromisoformat(release_date.replace("Z", "+00:00"))
+            metadata["release_date"] = date_obj.strftime("%Y-%m-%d")
+
+    # Series info
+    series_info = details.get("seriesInfo")
+    if series_info:
+        metadata["series_name"] = series_info.get("name")
+        metadata["series_index"] = series_info.get("orderInSeries")
+
+    return metadata
+
+
+# Registry of transformers by source name
+TRANSFORMERS = {
+    "storytel": storytel_transformer,
+    # Add more sources here as they're implemented
+}
+
+
+def get_transformer(source_name: str):
+    """
+    Get the metadata transformer for a given source
+
+    :param source_name: Name of the source (lowercase)
+    :return: Transformer function or None if not found
+    """
+    return TRANSFORMERS.get(source_name.lower())
diff --git a/grawlix/output/__init__.py b/grawlix/output/__init__.py
index 234fc61..0444170 100644
--- a/grawlix/output/__init__.py
+++ b/grawlix/output/__init__.py
@@ -41,11 +41,21 @@ def format_output_location(book: Book, output_format: OutputFormat, template: st
 
     :param book: Book to download
     :param output_format: Output format of book
-    :param template: Template for output path
+    :param template: Template for output path (supports ~, environment variables, and absolute paths)
     :returns: Output path
     """
     values = { key: remove_unwanted_chars(value) for key, value in book.metadata.as_dict().items() }
     path = template.format(**values, ext = output_format.extension)
+
+    # Expand user home directory (~/... or ~user/...)
+    path = os.path.expanduser(path)
+
+    # Expand environment variables ($VAR or %VAR% depending on OS)
+    path = os.path.expandvars(path)
+
+    # Normalize path separators for current OS
+    path = os.path.normpath(path)
+
     return path
 
 
@@ -64,15 +74,65 @@ def remove_strings(input: str, strings: Iterable[str]) -> str:
 
 def remove_unwanted_chars(input: str) -> str:
     """
-    Remove chars from string that are not supported in output path
+    Sanitize string for use in file paths across all operating systems.
+    Replaces forbidden characters with safe alternatives and handles edge cases.
 
-    :param input: The string to remove chars from
-    :returns: input without unsupported chars
+    :param input: The string to sanitize
+    :returns: Safe filename string
     """
+    import re
+
+    # Replace null bytes and control characters
+    output = re.sub(r'[\x00-\x1f\x7f]', '', input)
+
+    # Platform-specific forbidden characters - replace with underscore
     if platform.system() == "Windows":
-        return remove_strings(input, "<>:\"/\\|?*")
+        # Windows forbidden: < > : " / \ | ? *
+        forbidden_chars = '<>:"|?*'
+        for char in forbidden_chars:
+            output = output.replace(char, '_')
+        # Replace slashes with dash for better readability
+        output = output.replace('/', '-')
+        output = output.replace('\\', '-')
+
+        # Windows reserved names (case-insensitive)
+        reserved_names = {
+            'CON', 'PRN', 'AUX', 'NUL',
+            'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
+            'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9'
+        }
+        # Check if the name (without extension) is reserved
+        name_part = output.split('.')[0].upper()
+        if name_part in reserved_names:
+            output = f"_{output}"
+
+        # Remove trailing spaces and periods (Windows doesn't allow these)
+        output = output.rstrip('. ')
+
     else:
-        return remove_strings(input, "/")
+        # Unix-like systems (macOS, Linux)
+        # Only / is truly forbidden, but : can cause issues on macOS
+        output = output.replace('/', '-')
+        # Some versions of macOS have issues with :
+        output = output.replace(':', '-')
+
+    # Remove leading/trailing whitespace
+    output = output.strip()
+
+    # Limit filename length (most filesystems have 255 byte limit)
+    # Reserve some space for extensions and numbering
+    max_length = 200
+    if len(output.encode('utf-8')) > max_length:
+        # Truncate while respecting UTF-8 character boundaries
+        output_bytes = output.encode('utf-8')[:max_length]
+        # Decode, ignoring partial characters at the end
+        output = output_bytes.decode('utf-8', errors='ignore').rstrip()
+
+    # Ensure we don't return an empty string
+    if not output:
+        output = "untitled"
+
+    return output
 
 
 def get_default_format(book: Book) -> OutputFormat:
diff --git a/grawlix/sources/storytel.py b/grawlix/sources/storytel.py
index a1f6c39..a4ab5bd 100644
--- a/grawlix/sources/storytel.py
+++ b/grawlix/sources/storytel.py
@@ -9,6 +9,7 @@ from urllib3.util import parse_url
 from Crypto.Cipher import AES
 from Crypto.Util.Padding import pad
 from typing import Any
+from datetime import datetime
 
 class Storytel(Source):
     name: str = "Storytel"
@@ -48,18 +49,77 @@ class Storytel(Source):
             f"https://api.storytel.net/book-details/consumables/{book_id}?kidsMode=false&configVariant=default"
         )
         details = response.json()
+        logging.debug(f"Full book details JSON: {json.dumps(details, indent=2)}")
 
-        return Book(
-            metadata = Metadata(
-                title = details["title"]
-            ),
+        # Extract metadata from details
+        metadata = self._extract_metadata(details)
+
+        book = Book(
+            metadata = metadata,
             data = SingleFile(
                 OnlineFile(
                     url = epub_url,
                     extension = "epub",
                     headers = self._client.headers
                 )
-            )
+            ),
+            source_data = {
+                "source_name": "storytel",
+                "details": details
+            }
+        )
+        return book
+
+
+    def _extract_metadata(self, details: dict) -> Metadata:
+        """
+        Extract metadata from Storytel book details JSON
+
+        :param details: Book details from Storytel API
+        :return: Metadata object
+        """
+        from datetime import datetime
+
+        # Extract ebook-specific format data
+        ebook_format = None
+        for fmt in details.get("formats", []):
+            if fmt.get("type") == "ebook":
+                ebook_format = fmt
+                break
+
+        # Extract basic metadata
+        title = details.get("title", "Unknown")
+        authors = [author["name"] for author in details.get("authors", [])]
+        language = details.get("language")
+        description = details.get("description")
+
+        # Extract ebook-specific publisher and release date
+        publisher = None
+        release_date = None
+        if ebook_format:
+            publisher = ebook_format.get("publisher", {}).get("name")
+            release_date_str = ebook_format.get("releaseDate")
+            if release_date_str:
+                # Parse ISO format date
+                release_date = datetime.fromisoformat(release_date_str.replace("Z", "+00:00")).date()
+
+        # Extract series information
+        series = None
+        index = None
+        series_info = details.get("seriesInfo")
+        if series_info:
+            series = series_info.get("name")
+            index = series_info.get("orderInSeries")
+
+        return Metadata(
+            title=title,
+            authors=authors,
+            language=language,
+            publisher=publisher,
+            description=description,
+            release_date=release_date,
+            series=series,
+            index=index
         )
 
 

From 4efb9631688e2574124cf40e22cd3a8319cd6707 Mon Sep 17 00:00:00 2001
From: ^_^ <8480595+ballaballaballa@users.noreply.github.com>
Date: Wed, 29 Oct 2025 10:11:20 +0100
Subject: [PATCH 03/11] feat: add metadata writing support for Nextory and
 refactor source files

- Fix Nextory SSL certificate error (api.nextory.se -> api.nextory.com)
- Add missing X-OS-INFO header for Nextory API compatibility
- Implement full metadata writing for Nextory (title, authors, translators, series, publisher, ISBN, language, description, release date)
- Remove debug JSON output from Nextory authentication
- Fix exit() call in epub.py that prevented metadata writing for EpubInParts

Refactoring improvements:
- Reorganize functions in nextory.py and storytel.py by execution flow
- Add section comments for better code organization (Authentication, Main download, Book path, Series path)
- Remove duplicate imports (OnlineFile in nextory.py, datetime in storytel.py)
- Remove duplicate header update in storytel.py
- Improve pagination logic in storytel.py with clearer variable names
- Optimize API calls in nextory.py (eliminate redundant call)
- Use list comprehensions for cleaner code

Documentation:
- Update README with Nextory metadata support
- Add supported sources comparison table for metadata fields
- Include Nextory configuration example
---
 README.md                                     |  38 +++-
 grawlix/__main__.py                           |   7 +-
 .../errors/unsupported_output_format.txt      |   5 +
 grawlix/book.py                               |   2 +
 grawlix/epub_metadata_writers.py              |  45 +++++
 grawlix/output/epub.py                        |   1 -
 grawlix/sources/nextory.py                    | 175 +++++++++---------
 grawlix/sources/storytel.py                   | 155 ++++++++--------
 8 files changed, 259 insertions(+), 169 deletions(-)
 create mode 100644 grawlix/assets/errors/unsupported_output_format.txt

diff --git a/README.md b/README.md
index b327f00..c76e524 100644
--- a/README.md
+++ b/README.md
@@ -80,7 +80,7 @@ The following settings can be added to your config file (before any `[sources.*]
 
 | Setting | Type | Description | Example |
 |---------|------|-------------|---------|
-| `write_metadata_to_epub` | boolean | Automatically write metadata to EPUB files (currently supports Storytel) | `true` or `false` |
+| `write_metadata_to_epub` | boolean | Automatically write metadata to EPUB files (supports Storytel and Nextory) | `true` or `false` |
 | `output` | string | Default output path template (supports `~`, environment variables, and template variables) | `"~/ebooks/{title}.{ext}"` |
 
 ### Output Templates
@@ -96,20 +96,35 @@ The `output` setting supports template variables that are replaced with book met
 | `{publisher}` | Publisher name | "Orbit" |
 | `{language}` | Language code | "en" |
 | `{release_date}` | Release date | "2020-01-15" |
-| `{ext}` | File extension | "epub" |
+| `{source}` | Source/service name | "Storytel", "Marvel", etc. |
+| `{ext}` | File extension (auto-detected from source) | "epub" |
 
 **Example templates:**
 ```toml
-# Simple
+# Simple (auto-detect format)
 output = "~/books/{title}.{ext}"
 
-# Organized by series
+# Force EPUB format
+output = "~/books/{title}.epub"
+
+# Organized by source
+output = "~/books/{source}/{title}.{ext}"
+
+# Organized by series (auto-detect format)
 output = "~/books/{series}/{index} - {title}.{ext}"
 
-# With author
-output = "~/books/{authors}/{series}/{title}.{ext}"
+# Force EPUB with series organization
+output = "~/books/{series}/{index} - {title}.epub"
+
+# Organized by source and series
+output = "~/books/{source}/{series}/{index} - {title}.epub"
 ```
 
+**Note:** The file extension in your template determines the output format:
+- Use `.epub` to force EPUB output
+- Use `.cbz` to force CBZ (comic book) output
+- Use `{ext}` to auto-detect the best format for each source
+
 **Path expansion:**
 - `~` expands to home directory
 - Environment variables work: `$HOME` (Unix) or `%USERPROFILE%` (Windows)
@@ -157,15 +172,22 @@ grawlix --debug <url>
 
 ## Metadata Writing
 
-For supported sources (currently Storytel), grawlix can write rich metadata to EPUB files including:
+For supported sources (Storytel and Nextory), grawlix can write rich metadata to EPUB files including:
 
 - Title and original title
 - Authors and translators
 - Series information (Calibre-compatible)
 - Publisher, ISBN, language
-- Description and categories
+- Description and categories/tags
 - Release date
 
+### Supported Sources
+
+| Source | Title | Authors | Translators | Series | Publisher | ISBN | Language | Description | Release Date |
+|--------|-------|---------|-------------|--------|-----------|------|----------|-------------|--------------|
+| Storytel | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Nextory | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+
 Enable globally in config:
 ```toml
 write_metadata_to_epub = true
diff --git a/grawlix/__main__.py b/grawlix/__main__.py
index da49a32..5ad8b7e 100644
--- a/grawlix/__main__.py
+++ b/grawlix/__main__.py
@@ -165,18 +165,21 @@ async def download_with_progress(book: Book, progress: Progress, template: str,
 
     # Write metadata if requested and available
     if write_metadata and book.source_data:
-        from .output import format_output_location, get_default_format, find_output_format
+        from .output import format_output_location, get_default_format, find_output_format, get_valid_extensions
         from . import epub_metadata, epub_metadata_writers
 
         # Determine output file location
         _, ext = os.path.splitext(template)
         ext = ext[1:]
-        if ext:
+
+        # Handle {ext} placeholder - use default format for the book type
+        if ext and ext not in ['{ext}', 'ext'] and ext in get_valid_extensions():
             output_format = find_output_format(book, ext)()
         else:
             output_format = get_default_format(book)
 
         location = format_output_location(book, output_format, template)
+        logging.debug(f"Output location: {location}, exists={os.path.exists(location)}, ends_with_epub={location.endswith('.epub')}")
 
         # Write metadata if it's an EPUB file
         if location.endswith('.epub') and os.path.exists(location):
diff --git a/grawlix/assets/errors/unsupported_output_format.txt b/grawlix/assets/errors/unsupported_output_format.txt
new file mode 100644
index 0000000..7b6a192
--- /dev/null
+++ b/grawlix/assets/errors/unsupported_output_format.txt
@@ -0,0 +1,5 @@
+[red]ERROR: Unsupported output format[/red]
+
+The requested output format is not compatible with the downloaded content type.
+Please check your output template or try using {{ext}} to auto-detect the correct format.
+If this error persists, please create an issue at {issue}
diff --git a/grawlix/book.py b/grawlix/book.py
index 7c24369..981e5a7 100644
--- a/grawlix/book.py
+++ b/grawlix/book.py
@@ -15,6 +15,7 @@ class Metadata:
     identifier: Optional[str] = None
     description: Optional[str] = None
     release_date: Optional[date] = None
+    source: Optional[str] = None
 
     def as_dict(self) -> dict:
         return {
@@ -27,6 +28,7 @@ class Metadata:
             "authors": "; ".join(self.authors),
             "description": self.description or "UNKNOWN",
             "release_date": self.release_date.isoformat() if self.release_date else "UNKNOWN",
+            "source": self.source or "UNKNOWN",
         }
 
 
diff --git a/grawlix/epub_metadata_writers.py b/grawlix/epub_metadata_writers.py
index fb202fb..5a8b063 100644
--- a/grawlix/epub_metadata_writers.py
+++ b/grawlix/epub_metadata_writers.py
@@ -54,9 +54,54 @@ def storytel_transformer(details: dict) -> dict:
     return metadata
 
 
+def nextory_transformer(details: dict) -> dict:
+    """
+    Transform Nextory book details JSON into standardized EPUB metadata format
+
+    :param details: Nextory book details JSON
+    :return: Standardized metadata dict
+    """
+    # Extract epub format
+    epub_format = None
+    for fmt in details.get("formats", []):
+        if fmt.get("type") == "epub":
+            epub_format = fmt
+            break
+
+    metadata = {
+        "title": details.get("title"),
+        "authors": [author.get("name", "") for author in details.get("authors", [])],
+        "translators": [translator.get("name", "") for translator in epub_format.get("translators", []) if epub_format],
+        "description": details.get("description_full"),
+        "language": details.get("language"),
+    }
+
+    # Epub-specific metadata
+    if epub_format:
+        metadata["publisher"] = epub_format.get("publisher", {}).get("name")
+        metadata["isbn"] = epub_format.get("isbn")
+
+        publication_date = epub_format.get("publication_date")
+        if publication_date:
+            # Already in YYYY-MM-DD format
+            metadata["release_date"] = publication_date
+
+    # Series info
+    series_info = details.get("series")
+    if series_info:
+        metadata["series_name"] = series_info.get("name")
+        # Nextory uses "volume" at top level, not in series info
+        volume = details.get("volume")
+        if volume:
+            metadata["series_index"] = volume
+
+    return metadata
+
+
 # Registry of transformers by source name
 TRANSFORMERS = {
     "storytel": storytel_transformer,
+    "nextory": nextory_transformer,
     # Add more sources here as they're implemented
 }
 
diff --git a/grawlix/output/epub.py b/grawlix/output/epub.py
index a73a23e..333ebc4 100644
--- a/grawlix/output/epub.py
+++ b/grawlix/output/epub.py
@@ -135,4 +135,3 @@ class Epub(OutputFormat):
         output.add_item(epub.EpubNcx())
         output.add_item(epub.EpubNav())
         epub.write_epub(location, output)
-        exit()
diff --git a/grawlix/sources/nextory.py b/grawlix/sources/nextory.py
index b68761d..9f09861 100644
--- a/grawlix/sources/nextory.py
+++ b/grawlix/sources/nextory.py
@@ -1,11 +1,10 @@
-from grawlix.book import Book, Metadata, OnlineFile, BookData, OnlineFile, SingleFile, EpubInParts, Result, Series
+from grawlix.book import Book, Metadata, OnlineFile, BookData, EpubInParts, Result, Series
 from grawlix.encryption import AESEncryption
 from grawlix.exceptions import InvalidUrl
 from .source import Source
 
 from typing import Optional
 import uuid
-import rich
 import base64
 
 LOCALE = "en_GB"
@@ -17,12 +16,7 @@ class Nextory(Source):
     ]
     _authentication_methods = [ "login" ]
 
-
-    @staticmethod
-    def _create_device_id() -> str:
-        """Create unique device id"""
-        return str(uuid.uuid3(uuid.NAMESPACE_DNS, "audiobook-dl"))
-
+    # Authentication methods
 
     async def login(self, url: str, username: str, password: str) -> None:
         # Set permanent headers
@@ -30,11 +24,13 @@ class Nextory(Source):
         self._client.headers.update(
             {
                 "X-Application-Id": "200",
-                "X-App-Version": "5.4.1",
+                "X-App-Version": "5.47.0",
                 "X-Locale": LOCALE,
                 "X-Model": "Personal Computer",
                 "X-Device-Id": device_id,
-                "X-Os-Info": "Android",
+                "X-OS-INFO": "Personal Computer",
+                "locale": LOCALE,
+                "device": device_id,
                 "appid": "200",
             }
         )
@@ -47,7 +43,6 @@ class Nextory(Source):
             },
         )
         session_response = session_response.json()
-        rich.print(session_response)
         login_token = session_response["login_token"]
         country = session_response["country"]
         self._client.headers.update(
@@ -62,7 +57,6 @@ class Nextory(Source):
             "https://api.nextory.com/user/v1/me/profiles",
         )
         profiles_response = profiles_response.json()
-        rich.print(profiles_response)
         profile = profiles_response["profiles"][0]
         login_key = profile["login_key"]
         authorize_response = await self._client.post(
@@ -72,19 +66,24 @@ class Nextory(Source):
             }
         )
         authorize_response = authorize_response.json()
-        rich.print(authorize_response)
         profile_token = authorize_response["profile_token"]
         self._client.headers.update({"X-Profile-Token": profile_token})
-        self._client.headers.update({"X-Profile-Token": profile_token})
 
 
     @staticmethod
-    def _find_epub_id(product_data) -> str:
-        """Find id of book format of type epub for given book"""
-        for format in product_data["formats"]:
-            if format["type"] == "epub":
-                return format["identifier"]
-        raise InvalidUrl
+    def _create_device_id() -> str:
+        """Create unique device id"""
+        return str(uuid.uuid3(uuid.NAMESPACE_DNS, "audiobook-dl"))
+
+
+    # Main download methods
+
+    async def download(self, url: str) -> Result:
+        url_id = self._extract_id_from_url(url)
+        if "serier" in url:
+            return await self._download_series(url_id)
+        else:
+            return await self._download_book(url_id)
 
 
     @staticmethod
@@ -107,64 +106,15 @@ class Nextory(Source):
             return await self._download_book(url_id)
 
 
+
     async def download_book_from_id(self, book_id: str) -> Book:
         return await self._download_book(book_id)
 
 
-    async def _download_series(self, series_id: str) -> Series:
-        """
-        Download series from Nextory
-
-        :param series_id: Id of series on Nextory
-        :returns: Series data
-        """
-        response = await self._client.get(
-            f"https://api.nextory.com/discovery/v1/series/{series_id}/products",
-            params = {
-                "content_type": "book",
-                "page": 0,
-                "per": 100,
-            }
-        )
-        series_data = response.json()
-        book_ids = []
-        for book in series_data["products"]:
-            book_id = book["id"]
-            book_ids.append(book_id)
-        return Series(
-            title = series_data["products"][0]["series"]["name"],
-            book_ids = book_ids,
-        )
-
-
-    @staticmethod
-    def _extract_series_name(product_info: dict) -> Optional[str]:
-        if not "series" in product_info:
-            return None
-        return product_info["series"]["name"]
-
-
-    async def _get_book_id_from_url_id(self, url_id: str) -> str:
-        """
-        Download book id from url id
-
-        :param url_id: Id of book from url
-        :return: Book id
-        """
-        response = await self._client.get(
-            f"https://api.nextory.se/api/app/product/7.5/bookinfo",
-            params = { "id": url_id },
-        )
-        rich.print(response.url)
-        rich.print(response.content)
-        exit()
-
+    # Book download path
 
     async def _download_book(self, book_id: str) -> Book:
-        product_data = await self._client.get(
-            f"https://api.nextory.com/library/v1/products/{book_id}"
-        )
-        product_data = product_data.json()
+        product_data = await self._get_product_data(book_id)
         epub_id = self._find_epub_id(product_data)
         pages = await self._get_pages(epub_id)
         return Book(
@@ -173,14 +123,41 @@ class Nextory(Source):
                 title = product_data["title"],
                 authors = [author["name"] for author in product_data["authors"]],
                 series = self._extract_series_name(product_data),
-            )
+            ),
+            source_data = {
+                "source_name": "nextory",
+                "details": product_data
+            }
         )
 
 
+    async def _get_product_data(self, book_id: str) -> dict:
+        """
+        Fetch product data from Nextory API
+
+        :param book_id: Id of book (can be URL id or internal id)
+        :return: Product data dictionary
+        """
+        response = await self._client.get(
+            f"https://api.nextory.com/library/v1/products/{book_id}",
+        )
+        return response.json()
+
+
     @staticmethod
-    def _fix_key(value: str) -> bytes:
-        """Remove unused data and decode key"""
-        return base64.b64decode(value[:-1])
+    def _find_epub_id(product_data) -> str:
+        """Find id of book format of type epub for given book"""
+        for format in product_data["formats"]:
+            if format["type"] == "epub":
+                return format["identifier"]
+        raise InvalidUrl
+
+
+    @staticmethod
+    def _extract_series_name(product_info: dict) -> Optional[str]:
+        if "series" not in product_info:
+            return None
+        return product_info["series"]["name"]
 
 
     async def _get_pages(self, epub_id: str) -> BookData:
@@ -204,15 +181,14 @@ class Nextory(Source):
             key = self._fix_key(epub_data["crypt_key"]),
             iv = self._fix_key(epub_data["crypt_iv"])
         )
-        files = []
-        for part in epub_data["spines"]:
-            files.append(
-                OnlineFile(
-                    url = part["spine_url"],
-                    extension = "epub",
-                    encryption = encryption
-                )
+        files = [
+            OnlineFile(
+                url = part["spine_url"],
+                extension = "epub",
+                encryption = encryption
             )
+            for part in epub_data["spines"]
+        ]
         files_in_toc = {}
         for item in epub_data["toc"]["childrens"]: # Why is it "childrens"?
             files_in_toc[item["src"]] = item["name"]
@@ -220,3 +196,34 @@ class Nextory(Source):
             files,
             files_in_toc
         )
+
+
+    @staticmethod
+    def _fix_key(value: str) -> bytes:
+        """Remove unused data and decode key"""
+        return base64.b64decode(value[:-1])
+
+
+    # Series download path
+
+    async def _download_series(self, series_id: str) -> Series:
+        """
+        Download series from Nextory
+
+        :param series_id: Id of series on Nextory
+        :returns: Series data
+        """
+        response = await self._client.get(
+            f"https://api.nextory.com/discovery/v1/series/{series_id}/products",
+            params = {
+                "content_type": "book",
+                "page": 0,
+                "per": 100,
+            }
+        )
+        series_data = response.json()
+        book_ids = [book["id"] for book in series_data["products"]]
+        return Series(
+            title = series_data["products"][0]["series"]["name"],
+            book_ids = book_ids,
+        )
diff --git a/grawlix/sources/storytel.py b/grawlix/sources/storytel.py
index a4ab5bd..23af290 100644
--- a/grawlix/sources/storytel.py
+++ b/grawlix/sources/storytel.py
@@ -19,6 +19,57 @@ class Storytel(Source):
     _authentication_methods = [ "login" ]
     __download_counter = 0
 
+    # Authentication methods
+
+    async def login(self, username: str, password: str, **kwargs) -> None:
+        self.__username = username
+        self.__password = self.encrypt_password(password)
+        self._client.headers.update({"User-Agent": "Storytel/23.49 (Android 13; Pixel 6) Release/2288481"})
+        await self.authenticate()
+
+
+    @staticmethod
+    def encrypt_password(password: str) -> str:
+        """
+        Encrypt password with predefined keys.
+        This encrypted password is used for login.
+
+        :param password: User defined password
+        :returns: Encrypted password
+        """
+        # Thanks to https://github.com/javsanpar/storytel-tui
+        key = b"VQZBJ6TD8M9WBUWT"
+        iv = b"joiwef08u23j341a"
+        msg = pad(password.encode(), AES.block_size)
+        cipher = AES.new(key, AES.MODE_CBC, iv)
+        cipher_text = cipher.encrypt(msg)
+        return cipher_text.hex()
+
+
+    async def authenticate(self) -> None:
+        """Authenticate with storytel"""
+        response = await self._client.post(
+            f"https://www.storytel.com/api/login.action?m=1&token=guestsv&userid=-1&version=23.49&terminal=android&locale=sv&deviceId=995f2562-0e44-4410-b1b9-8d08261f33c4&kidsMode=false",
+            data = {
+                "uid": self.__username,
+                "pwd": self.__password
+            }
+        )
+        if response.status_code != 200:
+            raise SourceNotAuthenticated
+        user_data = response.json()
+        jwt = user_data["accountInfo"]["jwt"]
+        self._client.headers.update({"authorization": f"Bearer {jwt}"})
+
+
+    async def reauthenticate(self) -> None:
+        """Reauthenticate if required"""
+        if self.__download_counter > 0 and self.__download_counter % 10 == 0:
+            await self.authenticate()
+
+
+    # Main download methods
+
     async def download(self, url: str) -> Result:
         await self.reauthenticate()
 
@@ -36,6 +87,22 @@ class Storytel(Source):
         raise InvalidUrl
 
 
+    @staticmethod
+    def extract_id_from_url(url: str) -> str:
+        """
+        Extract id from url
+
+        :param url: Url containing id
+        :return: Id
+        """
+        parsed = parse_url(url)
+        if parsed.path is None:
+            raise DataNotFound
+        return parsed.path.split("-")[-1]
+
+
+    # Book download path
+
     async def download_book_from_id(self, book_id: str) -> Book:
         # Epub location
         response = await self._client.get(
@@ -78,8 +145,6 @@ class Storytel(Source):
         :param details: Book details from Storytel API
         :return: Metadata object
         """
-        from datetime import datetime
-
         # Extract ebook-specific format data
         ebook_format = None
         for fmt in details.get("formats", []):
@@ -119,10 +184,13 @@ class Storytel(Source):
             description=description,
             release_date=release_date,
             series=series,
-            index=index
+            index=index,
+            source="Storytel"
         )
 
 
+    # List download path
+
     async def download_list(self, url: str, list_type: str, language: str) -> Series:
         """
         Download list of books
@@ -157,23 +225,22 @@ class Storytel(Source):
     ) -> dict[str, Any]:
         """Download details about book list
 
-        :param formats: comma serapted list of formats (abook,ebook,podcast)
-        :param languages: comma seperated list of languages (en,de,tr,ar,ru,pl,it,es,sv,fr,nl)
+        :param formats: comma separated list of formats (abook,ebook,podcast)
+        :param languages: comma separated list of languages (en,de,tr,ar,ru,pl,it,es,sv,fr,nl)
         """
-        nextPageToken = 0
+        # API returns only 10 items per request, so we need to paginate
+        # Start with None to ensure we enter the loop and make the first request
+        result: dict[str, Any] = {"nextPageToken": None}
+        is_first_page = True
 
-        # API returns only 10 items per request
-        # if the nextPageToken
-        result: dict[str, Any] = {"nextPageToken": False}
-
-        while result["nextPageToken"] is not None:
+        while result["nextPageToken"] is not None or is_first_page:
             params: dict[str, str] = {
                 "includeListDetails": "true",  # include listMetadata,filterOptions,sortOption sections
                 "includeFormats": formats,
                 "includeLanguages": languages,
                 "kidsMode": "false",
             }
-            if result["nextPageToken"]:
+            if result.get("nextPageToken"):
                 params["nextPageToken"] = result["nextPageToken"]
 
             response = await self._client.get(
@@ -182,72 +249,12 @@ class Storytel(Source):
             )
 
             data = response.json()
-            if result["nextPageToken"] == 0:
+            if is_first_page:
                 result = data
+                is_first_page = False
             else:
                 result["items"].extend(data["items"])
                 result["nextPageToken"] = data["nextPageToken"]
             logging.debug(f"{result=}")
 
         return result
-
-
-    @staticmethod
-    def extract_id_from_url(url: str) -> str:
-        """
-        Extract id from url
-
-        :param url: Url containing id
-        :return: Id
-        """
-        parsed = parse_url(url)
-        if parsed.path is None:
-            raise DataNotFound
-        return parsed.path.split("-")[-1]
-
-
-    @staticmethod
-    def encrypt_password(password: str) -> str:
-        """
-        Encrypt password with predefined keys.
-        This encrypted password is used for login.
-
-        :param password: User defined password
-        :returns: Encrypted password
-        """
-        # Thanks to https://github.com/javsanpar/storytel-tui
-        key = b"VQZBJ6TD8M9WBUWT"
-        iv = b"joiwef08u23j341a"
-        msg = pad(password.encode(), AES.block_size)
-        cipher = AES.new(key, AES.MODE_CBC, iv)
-        cipher_text = cipher.encrypt(msg)
-        return cipher_text.hex()
-
-
-    async def reauthenticate(self) -> None:
-        """Reauthenticate if required"""
-        if self.__download_counter > 0 and self.__download_counter % 10 == 0:
-            await self.authenticate()
-
-
-    async def authenticate(self) -> None:
-        """Authenticate with storytel"""
-        response = await self._client.post(
-            f"https://www.storytel.com/api/login.action?m=1&token=guestsv&userid=-1&version=23.49&terminal=android&locale=sv&deviceId=995f2562-0e44-4410-b1b9-8d08261f33c4&kidsMode=false",
-            data = {
-                "uid": self.__username,
-                "pwd": self.__password
-            }
-        )
-        if response.status_code != 200:
-            raise SourceNotAuthenticated
-        user_data = response.json()
-        jwt = user_data["accountInfo"]["jwt"]
-        self._client.headers.update({"authorization": f"Bearer {jwt}"})
-
-
-    async def login(self, username: str, password: str, **kwargs) -> None:
-        self.__username = username
-        self.__password = self.encrypt_password(password)
-        self._client.headers.update({"User-Agent": "Storytel/23.49 (Android 13; Pixel 6) Release/2288481"})
-        await self.authenticate()

From 08af04ab326747f58a7bc974a401d4c2f09d4420 Mon Sep 17 00:00:00 2001
From: ^_^ <8480595+ballaballaballa@users.noreply.github.com>
Date: Wed, 29 Oct 2025 12:39:41 +0100
Subject: [PATCH 04/11] feat: migrate to bbpb and platformdirs, add dependency
 version constraints - Migrate from blackboxprotobuf to bbpb (new PyPI package
 name)   - Update pyproject.toml and shell.nix dependencies   - Import name
 remains 'blackboxprotobuf' (no code changes) - Migrate from appdirs to
 platformdirs   - Replace deprecated appdirs with actively maintained
 platformdirs   - Update grawlix/config.py to use platformdirs.user_config_dir
   - Update dependency declarations in pyproject.toml and shell.nix - Add
 minimum version constraints for all dependencies   - Set requires-python =
 ">=3.9" (required by httpx and importlib.resources.files())   - Add Python
 version classifiers (3.9-3.13)   - Specify minimum versions:
 beautifulsoup4>=4.9.0, bbpb>=1.0.0,     EbookLib>=0.17, httpx>=0.23.0,
 importlib-resources>=5.0,     lxml>=4.6.0, platformdirs>=3.0.0,
 pycryptodome>=3.10.0, rich>=10.0.0   - Make tomli conditional: only required
 for Python < 3.11 - Update shell.nix with correct SHA256 hash for bbpb 1.4.2
 These changes ensure all dependencies meet minimum version requirements for
 Python 3.9+ compatibility and replace deprecated packages with actively
 maintained alternatives.

---
 grawlix/config.py |  4 ++--
 pyproject.toml    | 26 ++++++++++++++++----------
 2 files changed, 18 insertions(+), 12 deletions(-)

diff --git a/grawlix/config.py b/grawlix/config.py
index 68b9caa..12c19ee 100644
--- a/grawlix/config.py
+++ b/grawlix/config.py
@@ -1,7 +1,7 @@
 from dataclasses import dataclass
 from typing import Optional
 import tomli
-import appdirs
+from platformdirs import user_config_dir
 import os
 
 
@@ -26,7 +26,7 @@ def load_config() -> Config:
 
     :returns: Config object
     """
-    config_dir = appdirs.user_config_dir("grawlix", "jo1gi")
+    config_dir = user_config_dir("grawlix", "jo1gi")
     config_file = os.path.join(config_dir, "grawlix.toml")
     if os.path.exists(config_file):
         try:
diff --git a/pyproject.toml b/pyproject.toml
index 83ffec8..0dd718f 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -6,21 +6,27 @@ authors = [
 description = "CLI tool for downloading ebooks"
 readme = "README.md"
 keywords = ["ebook", "cli", "downloader"]
+requires-python = ">=3.9"
 classifiers = [
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
 ]
 dependencies = [
-    "appdirs",
-    "beautifulsoup4",
-    "blackboxprotobuf",
-    "EbookLib",
-    "httpx",
-    "importlib-resources",
-    "lxml",
-    "pycryptodome",
-    "rich",
-    "tomli",
+    "beautifulsoup4>=4.9.0",
+    "bbpb>=1.0.0",
+    "EbookLib>=0.17",
+    "httpx>=0.23.0",
+    "importlib-resources>=5.0",
+    "lxml>=4.6.0",
+    "platformdirs>=3.0.0",
+    "pycryptodome>=3.10.0",
+    "rich>=10.0.0",
+    "tomli>=1.0.0; python_version<'3.11'",
 ]
 dynamic = ["version"]
 

From 6199e02b9b2ca0b3b1b99b5a4929fb3e331936bc Mon Sep 17 00:00:00 2001
From: ^_^ <8480595+ballaballaballa@users.noreply.github.com>
Date: Thu, 18 Dec 2025 12:25:37 +0100
Subject: [PATCH 05/11] feat: fix Nextory series null handling and add PDF book
 support

- Fix _extract_series_name to handle null series values
- Add PDF book support for Nextory (served via epub endpoint)
- Convert PDF-in-epub to merged PDF after download
- Add pypdf dependency for PDF merging
- Add Pdf output format (unused but available)
- Update metadata transformer to handle both epub and pdf formats
---
 grawlix/__main__.py              | 12 ++++++
 grawlix/epub_metadata_writers.py | 25 ++++++------
 grawlix/output/__init__.py       |  2 +
 grawlix/output/pdf.py            | 10 +++++
 grawlix/pdf_converter.py         | 68 ++++++++++++++++++++++++++++++++
 grawlix/sources/nextory.py       | 38 +++++++++---------
 pyproject.toml                   |  1 +
 7 files changed, 127 insertions(+), 29 deletions(-)
 create mode 100644 grawlix/output/pdf.py
 create mode 100644 grawlix/pdf_converter.py

diff --git a/grawlix/__main__.py b/grawlix/__main__.py
index 5ad8b7e..6370d4e 100644
--- a/grawlix/__main__.py
+++ b/grawlix/__main__.py
@@ -163,6 +163,18 @@ async def download_with_progress(book: Book, progress: Progress, template: str,
     # Download the book
     await download_book(book, update_function, template)
 
+    # Convert PDF-in-epub to PDF if needed
+    if book.source_data and book.source_data.get('format_type') == 'pdf':
+        from .output import format_output_location, get_default_format
+        from .pdf_converter import convert_pdf_epub_to_pdf, is_pdf_in_epub
+
+        output_format = get_default_format(book)
+        location = format_output_location(book, output_format, template)
+
+        if location.endswith('.epub') and os.path.exists(location) and is_pdf_in_epub(location):
+            convert_pdf_epub_to_pdf(location)
+            logging.debug(f"Converted PDF-in-epub to PDF: {location}")
+
     # Write metadata if requested and available
     if write_metadata and book.source_data:
         from .output import format_output_location, get_default_format, find_output_format, get_valid_extensions
diff --git a/grawlix/epub_metadata_writers.py b/grawlix/epub_metadata_writers.py
index 5a8b063..0f3dc3a 100644
--- a/grawlix/epub_metadata_writers.py
+++ b/grawlix/epub_metadata_writers.py
@@ -61,27 +61,30 @@ def nextory_transformer(details: dict) -> dict:
     :param details: Nextory book details JSON
     :return: Standardized metadata dict
     """
-    # Extract epub format
-    epub_format = None
-    for fmt in details.get("formats", []):
-        if fmt.get("type") == "epub":
-            epub_format = fmt
+    # Extract ebook format (epub or pdf - Nextory serves both as epub)
+    ebook_format = None
+    for fmt_type in ("epub", "pdf"):
+        for fmt in details.get("formats", []):
+            if fmt.get("type") == fmt_type:
+                ebook_format = fmt
+                break
+        if ebook_format:
             break
 
     metadata = {
         "title": details.get("title"),
         "authors": [author.get("name", "") for author in details.get("authors", [])],
-        "translators": [translator.get("name", "") for translator in epub_format.get("translators", []) if epub_format],
+        "translators": [translator.get("name", "") for translator in ebook_format.get("translators", [])] if ebook_format else [],
         "description": details.get("description_full"),
         "language": details.get("language"),
     }
 
-    # Epub-specific metadata
-    if epub_format:
-        metadata["publisher"] = epub_format.get("publisher", {}).get("name")
-        metadata["isbn"] = epub_format.get("isbn")
+    # Format-specific metadata
+    if ebook_format:
+        metadata["publisher"] = ebook_format.get("publisher", {}).get("name")
+        metadata["isbn"] = ebook_format.get("isbn")
 
-        publication_date = epub_format.get("publication_date")
+        publication_date = ebook_format.get("publication_date")
         if publication_date:
             # Already in YYYY-MM-DD format
             metadata["release_date"] = publication_date
diff --git a/grawlix/output/__init__.py b/grawlix/output/__init__.py
index 0444170..1a88936 100644
--- a/grawlix/output/__init__.py
+++ b/grawlix/output/__init__.py
@@ -6,6 +6,7 @@ from .output_format import OutputFormat
 from .acsm import Acsm
 from .cbz import Cbz
 from .epub import Epub
+from .pdf import Pdf
 
 from typing import Callable, Iterable
 from pathlib import Path
@@ -184,4 +185,5 @@ def get_output_formats() -> list[type[OutputFormat]]:
         Acsm,
         Cbz,
         Epub,
+        Pdf,
     ]
diff --git a/grawlix/output/pdf.py b/grawlix/output/pdf.py
new file mode 100644
index 0000000..17468fd
--- /dev/null
+++ b/grawlix/output/pdf.py
@@ -0,0 +1,10 @@
+from grawlix.book import Book, SingleFile
+from .output_format import OutputFormat, Update
+
+
+class Pdf(OutputFormat):
+    extension = "pdf"
+    input_types = [SingleFile]
+
+    async def download(self, book: Book, location: str, update_func: Update) -> None:
+        await self._download_single_file(book, location, update_func)
diff --git a/grawlix/pdf_converter.py b/grawlix/pdf_converter.py
new file mode 100644
index 0000000..a352e3c
--- /dev/null
+++ b/grawlix/pdf_converter.py
@@ -0,0 +1,68 @@
+"""
+Convert PDF-in-epub files to proper PDF format.
+Some sources (like Nextory) wrap PDF pages in epub containers.
+"""
+
+import os
+import re
+import zipfile
+from io import BytesIO
+from pypdf import PdfWriter, PdfReader
+
+
+def convert_pdf_epub_to_pdf(epub_path: str) -> str:
+    """
+    Extract embedded PDFs from an epub and merge them into a single PDF.
+
+    :param epub_path: Path to the epub file containing embedded PDFs
+    :return: Path to the created PDF file
+    """
+    pdf_path = epub_path.rsplit('.', 1)[0] + '.pdf'
+
+    with zipfile.ZipFile(epub_path, 'r') as zf:
+        # Find all PDF files in the epub
+        pdf_files = [f for f in zf.namelist() if f.endswith('.pdf')]
+
+        if not pdf_files:
+            raise ValueError("No PDF files found in epub")
+
+        # Sort by numeric order (1.pdf, 2.pdf, ..., 10.pdf, 11.pdf, ...)
+        def extract_number(path: str) -> int:
+            match = re.search(r'/(\d+)\.pdf$', path)
+            return int(match.group(1)) if match else 0
+
+        pdf_files.sort(key=extract_number)
+
+        # Merge all PDFs
+        writer = PdfWriter()
+        for pdf_file in pdf_files:
+            pdf_data = zf.read(pdf_file)
+            reader = PdfReader(BytesIO(pdf_data))
+            for page in reader.pages:
+                writer.add_page(page)
+
+        # Write merged PDF
+        with open(pdf_path, 'wb') as out_file:
+            writer.write(out_file)
+
+    # Remove the original epub
+    os.remove(epub_path)
+
+    return pdf_path
+
+
+def is_pdf_in_epub(epub_path: str) -> bool:
+    """
+    Check if an epub contains embedded PDF files instead of HTML.
+
+    :param epub_path: Path to the epub file
+    :return: True if the epub contains PDF files
+    """
+    try:
+        with zipfile.ZipFile(epub_path, 'r') as zf:
+            for name in zf.namelist():
+                if name.endswith('.pdf'):
+                    return True
+    except (zipfile.BadZipFile, FileNotFoundError):
+        pass
+    return False
diff --git a/grawlix/sources/nextory.py b/grawlix/sources/nextory.py
index 9f09861..4fe89f9 100644
--- a/grawlix/sources/nextory.py
+++ b/grawlix/sources/nextory.py
@@ -3,7 +3,7 @@ from grawlix.encryption import AESEncryption
 from grawlix.exceptions import InvalidUrl
 from .source import Source
 
-from typing import Optional
+from typing import Optional, Tuple
 import uuid
 import base64
 
@@ -24,14 +24,12 @@ class Nextory(Source):
         self._client.headers.update(
             {
                 "X-Application-Id": "200",
-                "X-App-Version": "5.47.0",
+                "X-App-Version": "2025.12.1",
                 "X-Locale": LOCALE,
                 "X-Model": "Personal Computer",
                 "X-Device-Id": device_id,
                 "X-OS-INFO": "Personal Computer",
                 "locale": LOCALE,
-                "device": device_id,
-                "appid": "200",
             }
         )
         # Login for account
@@ -115,10 +113,12 @@ class Nextory(Source):
 
     async def _download_book(self, book_id: str) -> Book:
         product_data = await self._get_product_data(book_id)
-        epub_id = self._find_epub_id(product_data)
-        pages = await self._get_pages(epub_id)
+        format_type, format_id = self._find_format(product_data)
+        # Nextory serves all books via epub endpoint regardless of original format
+        data = await self._get_epub_data(format_id)
+
         return Book(
-            data = pages,
+            data = data,
             metadata = Metadata(
                 title = product_data["title"],
                 authors = [author["name"] for author in product_data["authors"]],
@@ -126,6 +126,7 @@ class Nextory(Source):
             ),
             source_data = {
                 "source_name": "nextory",
+                "format_type": format_type,
                 "details": product_data
             }
         )
@@ -145,27 +146,29 @@ class Nextory(Source):
 
 
     @staticmethod
-    def _find_epub_id(product_data) -> str:
-        """Find id of book format of type epub for given book"""
-        for format in product_data["formats"]:
-            if format["type"] == "epub":
-                return format["identifier"]
+    def _find_format(product_data) -> Tuple[str, str]:
+        """Find a supported book format (epub or pdf)"""
+        for format_type in ("epub", "pdf"):
+            for fmt in product_data["formats"]:
+                if fmt["type"] == format_type:
+                    return (format_type, fmt["identifier"])
         raise InvalidUrl
 
 
     @staticmethod
     def _extract_series_name(product_info: dict) -> Optional[str]:
-        if "series" not in product_info:
+        series = product_info.get("series")
+        if series is None:
             return None
-        return product_info["series"]["name"]
+        return series["name"]
 
 
-    async def _get_pages(self, epub_id: str) -> BookData:
+    async def _get_epub_data(self, epub_id: str) -> BookData:
         """
-        Download page information for book
+        Download epub data for book
 
         :param epub_id: Id of epub file
-        :return: Page data
+        :return: Epub data
         """
         # Nextory books are for some reason split up into multiple epub files -
         # one for each chapter file. All of these files has to be decrypted and
@@ -197,7 +200,6 @@ class Nextory(Source):
             files_in_toc
         )
 
-
     @staticmethod
     def _fix_key(value: str) -> bytes:
         """Remove unused data and decode key"""
diff --git a/pyproject.toml b/pyproject.toml
index 0dd718f..db548bd 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -25,6 +25,7 @@ dependencies = [
     "lxml>=4.6.0",
     "platformdirs>=3.0.0",
     "pycryptodome>=3.10.0",
+    "pypdf>=3.0.0",
     "rich>=10.0.0",
     "tomli>=1.0.0; python_version<'3.11'",
 ]

From cf2bb5d7c48630ab212333f71eb53c63a59abc5c Mon Sep 17 00:00:00 2001
From: ^_^ <8480595+ballaballaballa@users.noreply.github.com>
Date: Thu, 18 Dec 2025 12:27:13 +0100
Subject: [PATCH 06/11] chore: bump version to 0.2.2

---
 grawlix/__init__.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/grawlix/__init__.py b/grawlix/__init__.py
index 68c81ab..4df125f 100644
--- a/grawlix/__init__.py
+++ b/grawlix/__init__.py
@@ -1,4 +1,4 @@
 from .encryption import Encryption, AESEncryption
 from .book import Book, SingleFile, OnlineFile, Metadata
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"

From 533536ec4367253df92d12b0ad218c1d53d72a3e Mon Sep 17 00:00:00 2001
From: ^_^ <8480595+ballaballaballa@users.noreply.github.com>
Date: Mon, 22 Dec 2025 20:50:21 +0100
Subject: [PATCH 07/11] fix: detect PDF-in-epub by content instead of API
 format type

---
 grawlix/__main__.py        | 4 ++--
 grawlix/sources/nextory.py | 3 +--
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/grawlix/__main__.py b/grawlix/__main__.py
index 6370d4e..89bcbf6 100644
--- a/grawlix/__main__.py
+++ b/grawlix/__main__.py
@@ -163,8 +163,8 @@ async def download_with_progress(book: Book, progress: Progress, template: str,
     # Download the book
     await download_book(book, update_function, template)
 
-    # Convert PDF-in-epub to PDF if needed
-    if book.source_data and book.source_data.get('format_type') == 'pdf':
+    # Convert PDF-in-epub to PDF if needed (Nextory wraps PDFs in epub containers)
+    if book.source_data and book.source_data.get('source_name') == 'nextory':
         from .output import format_output_location, get_default_format
         from .pdf_converter import convert_pdf_epub_to_pdf, is_pdf_in_epub
 
diff --git a/grawlix/sources/nextory.py b/grawlix/sources/nextory.py
index 4fe89f9..04fa309 100644
--- a/grawlix/sources/nextory.py
+++ b/grawlix/sources/nextory.py
@@ -113,7 +113,7 @@ class Nextory(Source):
 
     async def _download_book(self, book_id: str) -> Book:
         product_data = await self._get_product_data(book_id)
-        format_type, format_id = self._find_format(product_data)
+        _, format_id = self._find_format(product_data)
         # Nextory serves all books via epub endpoint regardless of original format
         data = await self._get_epub_data(format_id)
 
@@ -126,7 +126,6 @@ class Nextory(Source):
             ),
             source_data = {
                 "source_name": "nextory",
-                "format_type": format_type,
                 "details": product_data
             }
         )

From ece2d95845f0ae31f96cf6f9923fbb29da9cbfa3 Mon Sep 17 00:00:00 2001
From: ^_^ <8480595+ballaballaballa@users.noreply.github.com>
Date: Tue, 13 Jan 2026 12:50:12 +0100
Subject: [PATCH 08/11] refactor: move output-related modules to output folder

- Move pdf_converter.py to output/
- Move epub_metadata.py and epub_metadata_writers.py to output/metadata/
- Update imports in __main__.py
---
 grawlix/__main__.py                                    | 4 ++--
 grawlix/{ => output/metadata}/epub_metadata.py         | 0
 grawlix/{ => output/metadata}/epub_metadata_writers.py | 0
 grawlix/{ => output}/pdf_converter.py                  | 0
 4 files changed, 2 insertions(+), 2 deletions(-)
 rename grawlix/{ => output/metadata}/epub_metadata.py (100%)
 rename grawlix/{ => output/metadata}/epub_metadata_writers.py (100%)
 rename grawlix/{ => output}/pdf_converter.py (100%)

diff --git a/grawlix/__main__.py b/grawlix/__main__.py
index 89bcbf6..0b4341f 100644
--- a/grawlix/__main__.py
+++ b/grawlix/__main__.py
@@ -166,7 +166,7 @@ async def download_with_progress(book: Book, progress: Progress, template: str,
     # Convert PDF-in-epub to PDF if needed (Nextory wraps PDFs in epub containers)
     if book.source_data and book.source_data.get('source_name') == 'nextory':
         from .output import format_output_location, get_default_format
-        from .pdf_converter import convert_pdf_epub_to_pdf, is_pdf_in_epub
+        from .output.pdf_converter import convert_pdf_epub_to_pdf, is_pdf_in_epub
 
         output_format = get_default_format(book)
         location = format_output_location(book, output_format, template)
@@ -178,7 +178,7 @@ async def download_with_progress(book: Book, progress: Progress, template: str,
     # Write metadata if requested and available
     if write_metadata and book.source_data:
         from .output import format_output_location, get_default_format, find_output_format, get_valid_extensions
-        from . import epub_metadata, epub_metadata_writers
+        from .output.metadata import epub_metadata, epub_metadata_writers
 
         # Determine output file location
         _, ext = os.path.splitext(template)
diff --git a/grawlix/epub_metadata.py b/grawlix/output/metadata/epub_metadata.py
similarity index 100%
rename from grawlix/epub_metadata.py
rename to grawlix/output/metadata/epub_metadata.py
diff --git a/grawlix/epub_metadata_writers.py b/grawlix/output/metadata/epub_metadata_writers.py
similarity index 100%
rename from grawlix/epub_metadata_writers.py
rename to grawlix/output/metadata/epub_metadata_writers.py
diff --git a/grawlix/pdf_converter.py b/grawlix/output/pdf_converter.py
similarity index 100%
rename from grawlix/pdf_converter.py
rename to grawlix/output/pdf_converter.py

From 476d4608462706de40fabbf67f944ca53379af21 Mon Sep 17 00:00:00 2001
From: ^_^ <8480595+ballaballaballa@users.noreply.github.com>
Date: Wed, 14 Jan 2026 19:25:37 +0100
Subject: [PATCH 09/11] refactor: simplify EPUB metadata architecture

- Remove source_data/transformer pattern in favor of direct Metadata population
- Extend Metadata with new fields: original_title, translators, category, tags
- Rename identifier field to isbn for clarity
- Delete epub_metadata_writers.py (transformers no longer needed)
- Update epub_metadata.py to accept Metadata object instead of dict
- Update Storytel and Nextory sources to populate extended metadata
---
 grawlix/__main__.py                           |  20 +--
 grawlix/book.py                               |  13 +-
 grawlix/output/metadata/epub_metadata.py      |  79 +++++-------
 .../output/metadata/epub_metadata_writers.py  | 119 ------------------
 grawlix/sources/flipp.py                      |   1 -
 grawlix/sources/nextory.py                    |  84 ++++++++++---
 grawlix/sources/storytel.py                   |  19 ++-
 7 files changed, 125 insertions(+), 210 deletions(-)
 delete mode 100644 grawlix/output/metadata/epub_metadata_writers.py

diff --git a/grawlix/__main__.py b/grawlix/__main__.py
index 0b4341f..7208327 100644
--- a/grawlix/__main__.py
+++ b/grawlix/__main__.py
@@ -164,7 +164,7 @@ async def download_with_progress(book: Book, progress: Progress, template: str,
     await download_book(book, update_function, template)
 
     # Convert PDF-in-epub to PDF if needed (Nextory wraps PDFs in epub containers)
-    if book.source_data and book.source_data.get('source_name') == 'nextory':
+    if book.metadata.source == "Nextory":
         from .output import format_output_location, get_default_format
         from .output.pdf_converter import convert_pdf_epub_to_pdf, is_pdf_in_epub
 
@@ -175,10 +175,10 @@ async def download_with_progress(book: Book, progress: Progress, template: str,
             convert_pdf_epub_to_pdf(location)
             logging.debug(f"Converted PDF-in-epub to PDF: {location}")
 
-    # Write metadata if requested and available
-    if write_metadata and book.source_data:
+    # Write metadata if requested
+    if write_metadata:
         from .output import format_output_location, get_default_format, find_output_format, get_valid_extensions
-        from .output.metadata import epub_metadata, epub_metadata_writers
+        from .output.metadata import epub_metadata
 
         # Determine output file location
         _, ext = os.path.splitext(template)
@@ -195,17 +195,7 @@ async def download_with_progress(book: Book, progress: Progress, template: str,
 
         # Write metadata if it's an EPUB file
         if location.endswith('.epub') and os.path.exists(location):
-            # Get source-specific data and transformer
-            source_name = book.source_data.get('source_name')
-            source_details = book.source_data.get('details')
-
-            if source_name and source_details:
-                transformer = epub_metadata_writers.get_transformer(source_name)
-                if transformer:
-                    transformed_metadata = transformer(source_details)
-                    epub_metadata.write_metadata_to_epub(transformed_metadata, location)
-                else:
-                    logging.debug(f"No metadata transformer found for source: {source_name}")
+            epub_metadata.write_metadata_to_epub(book.metadata, location)
 
     progress.advance(task, 1)
 
diff --git a/grawlix/book.py b/grawlix/book.py
index 981e5a7..726eaf8 100644
--- a/grawlix/book.py
+++ b/grawlix/book.py
@@ -12,10 +12,14 @@ class Metadata:
     authors: list[str] = field(default_factory=list)
     language: Optional[str] = None
     publisher: Optional[str] = None
-    identifier: Optional[str] = None
+    isbn: Optional[str] = None
     description: Optional[str] = None
     release_date: Optional[date] = None
     source: Optional[str] = None
+    original_title: Optional[str] = None
+    translators: list[str] = field(default_factory=list)
+    category: Optional[str] = None
+    tags: list[str] = field(default_factory=list)
 
     def as_dict(self) -> dict:
         return {
@@ -23,12 +27,16 @@ class Metadata:
             "series": self.series or "UNKNOWN",
             "index": str(self.index) if self.index is not None else "UNKNOWN",
             "publisher": self.publisher or "UNKNOWN",
-            "identifier": self.identifier or "UNKNOWN",
+            "isbn": self.isbn or "UNKNOWN",
             "language": self.language or "UNKNOWN",
             "authors": "; ".join(self.authors),
             "description": self.description or "UNKNOWN",
             "release_date": self.release_date.isoformat() if self.release_date else "UNKNOWN",
             "source": self.source or "UNKNOWN",
+            "original_title": self.original_title or "UNKNOWN",
+            "translators": "; ".join(self.translators),
+            "category": self.category or "UNKNOWN",
+            "tags": "; ".join(self.tags),
         }
 
 
@@ -99,7 +107,6 @@ class Book:
     metadata: Metadata
     data: BookData
     overwrite: bool = False
-    source_data: Optional[dict] = None  # For storing source-specific data
 
 T = TypeVar("T")
 
diff --git a/grawlix/output/metadata/epub_metadata.py b/grawlix/output/metadata/epub_metadata.py
index 62e7abd..626027c 100644
--- a/grawlix/output/metadata/epub_metadata.py
+++ b/grawlix/output/metadata/epub_metadata.py
@@ -1,38 +1,22 @@
 """
 Generic EPUB metadata writer
 
-Handles writing standardized metadata to EPUB files from any source
+Handles writing metadata to EPUB files from book.Metadata
 """
 
 from grawlix import logging
+from grawlix.book import Metadata
 import zipfile
 import tempfile
 import os
 import shutil
 
 
-def write_metadata_to_epub(metadata: dict, epub_path: str) -> None:
+def write_metadata_to_epub(metadata: Metadata, epub_path: str) -> None:
     """
-    Write standardized metadata to EPUB file
+    Write metadata to EPUB file
 
-    Expected metadata format:
-    {
-        "title": str,
-        "original_title": Optional[str],
-        "authors": List[str],
-        "translators": List[str],
-        "description": Optional[str],
-        "language": Optional[str],
-        "publisher": Optional[str],
-        "isbn": Optional[str],
-        "release_date": Optional[str],  # YYYY-MM-DD format
-        "category": Optional[str],
-        "tags": List[str],
-        "series_name": Optional[str],
-        "series_index": Optional[int]
-    }
-
-    :param metadata: Standardized metadata dict
+    :param metadata: Metadata object from book
     :param epub_path: Path to the EPUB file
     """
     try:
@@ -132,8 +116,8 @@ def _find_opf_file(epub_dir: str) -> str:
     return None
 
 
-def _update_epub_metadata(metadata_elem, metadata: dict, ns: dict, using_lxml: bool) -> None:
-    """Update EPUB metadata elements with standardized metadata"""
+def _update_epub_metadata(metadata_elem, metadata: Metadata, ns: dict, using_lxml: bool) -> None:
+    """Update EPUB metadata elements from Metadata object"""
 
     # Helper function to create/update element
     def update_or_create_element(tag: str, text: str, attribs: dict = None):
@@ -158,8 +142,8 @@ def _update_epub_metadata(metadata_elem, metadata: dict, ns: dict, using_lxml: b
                 elem.set(key, value)
 
     # Helper to create meta element
-    def create_meta(name: str, content: str):
-        if not content:
+    def create_meta(name: str, content):
+        if content is None:
             return
 
         if using_lxml:
@@ -173,10 +157,10 @@ def _update_epub_metadata(metadata_elem, metadata: dict, ns: dict, using_lxml: b
         meta.set('content', str(content))
 
     # Title
-    update_or_create_element(f"{{{ns['dc']}}}title", metadata.get("title"))
+    update_or_create_element(f"{{{ns['dc']}}}title", metadata.title)
 
     # Original Title (EPUB 3 with refinements)
-    if metadata.get("original_title"):
+    if metadata.original_title:
         # Create title with ID for main title
         for elem in list(metadata_elem.findall(f"{{{ns['dc']}}}title", ns)):
             elem.set('id', 'main-title')
@@ -190,7 +174,7 @@ def _update_epub_metadata(metadata_elem, metadata: dict, ns: dict, using_lxml: b
             orig_title = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}title")
 
         orig_title.set('id', 'original-title')
-        orig_title.text = metadata["original_title"]
+        orig_title.text = metadata.original_title
 
         # Add meta refinement for original title
         if using_lxml:
@@ -202,7 +186,7 @@ def _update_epub_metadata(metadata_elem, metadata: dict, ns: dict, using_lxml: b
         meta.text = 'original'
 
     # Authors
-    for author in metadata.get("authors", []):
+    for author in metadata.authors:
         if using_lxml:
             from lxml import etree as ET
             creator = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}creator")
@@ -213,7 +197,7 @@ def _update_epub_metadata(metadata_elem, metadata: dict, ns: dict, using_lxml: b
         creator.set(f"{{{ns['opf']}}}role", "aut")
 
     # Translators
-    for translator in metadata.get("translators", []):
+    for translator in metadata.translators:
         if using_lxml:
             from lxml import etree as ET
             contributor = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}contributor")
@@ -223,18 +207,17 @@ def _update_epub_metadata(metadata_elem, metadata: dict, ns: dict, using_lxml: b
         contributor.text = translator
         contributor.set(f"{{{ns['opf']}}}role", "trl")
 
-    # Description (Unicode is automatically handled by lxml/ET)
-    update_or_create_element(f"{{{ns['dc']}}}description", metadata.get("description"))
+    # Description
+    update_or_create_element(f"{{{ns['dc']}}}description", metadata.description)
 
     # Language
-    update_or_create_element(f"{{{ns['dc']}}}language", metadata.get("language"))
+    update_or_create_element(f"{{{ns['dc']}}}language", metadata.language)
 
     # Publisher
-    update_or_create_element(f"{{{ns['dc']}}}publisher", metadata.get("publisher"))
+    update_or_create_element(f"{{{ns['dc']}}}publisher", metadata.publisher)
 
-    # ISBN
-    isbn = metadata.get("isbn")
-    if isbn:
+    # ISBN (from identifier field)
+    if metadata.isbn:
         # Remove existing ISBN identifiers
         for elem in list(metadata_elem.findall(f"{{{ns['dc']}}}identifier", ns)):
             scheme = elem.get(f"{{{ns['opf']}}}scheme")
@@ -248,25 +231,25 @@ def _update_epub_metadata(metadata_elem, metadata: dict, ns: dict, using_lxml: b
         else:
             import xml.etree.ElementTree as ET
             identifier = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}identifier")
-        identifier.text = isbn
+        identifier.text = metadata.isbn
         identifier.set(f"{{{ns['opf']}}}scheme", "ISBN")
 
-    # Release Date (already formatted as YYYY-MM-DD)
-    update_or_create_element(f"{{{ns['dc']}}}date", metadata.get("release_date"))
+    # Release Date (convert date to string)
+    release_date_str = metadata.release_date.isoformat() if metadata.release_date else None
+    update_or_create_element(f"{{{ns['dc']}}}date", release_date_str)
 
     # Category
-    category = metadata.get("category")
-    if category:
+    if metadata.category:
         if using_lxml:
             from lxml import etree as ET
             subject = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}subject")
         else:
             import xml.etree.ElementTree as ET
             subject = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}subject")
-        subject.text = category
+        subject.text = metadata.category
 
     # Tags
-    for tag in metadata.get("tags", []):
+    for tag in metadata.tags:
         if using_lxml:
             from lxml import etree as ET
             subject = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}subject")
@@ -275,10 +258,10 @@ def _update_epub_metadata(metadata_elem, metadata: dict, ns: dict, using_lxml: b
             subject = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}subject")
         subject.text = tag
 
-    # Series info (Calibre format)
-    if metadata.get("series_name"):
-        create_meta("calibre:series", metadata.get("series_name"))
-        create_meta("calibre:series_index", metadata.get("series_index"))
+    # Series info (Calibre format) - using series and index fields
+    if metadata.series:
+        create_meta("calibre:series", metadata.series)
+        create_meta("calibre:series_index", metadata.index)
 
 
 def _repack_epub(epub_dir: str, output_path: str) -> None:
diff --git a/grawlix/output/metadata/epub_metadata_writers.py b/grawlix/output/metadata/epub_metadata_writers.py
deleted file mode 100644
index 0f3dc3a..0000000
--- a/grawlix/output/metadata/epub_metadata_writers.py
+++ /dev/null
@@ -1,119 +0,0 @@
-"""
-Source-specific EPUB metadata transformers
-
-Each source can provide a transformer function that converts their source_data
-into a standardized metadata format for EPUB writing.
-"""
-
-from datetime import datetime
-from typing import Optional
-
-
-def storytel_transformer(details: dict) -> dict:
-    """
-    Transform Storytel book details JSON into standardized EPUB metadata format
-
-    :param details: Storytel book details JSON
-    :return: Standardized metadata dict
-    """
-    # Extract ebook format
-    ebook_format = None
-    for fmt in details.get("formats", []):
-        if fmt.get("type") == "ebook":
-            ebook_format = fmt
-            break
-
-    metadata = {
-        "title": details.get("title"),
-        "original_title": details.get("originalTitle"),
-        "authors": [author.get("name", "") for author in details.get("authors", [])],
-        "translators": [translator.get("name", "") for translator in details.get("translators", [])],
-        "description": details.get("description"),
-        "language": details.get("language"),
-        "category": details.get("category", {}).get("name"),
-        "tags": [tag.get("name", "") for tag in details.get("tags", [])[:10]],  # Max 10
-    }
-
-    # Ebook-specific metadata
-    if ebook_format:
-        metadata["publisher"] = ebook_format.get("publisher", {}).get("name")
-        metadata["isbn"] = ebook_format.get("isbn")
-
-        release_date = ebook_format.get("releaseDate")
-        if release_date:
-            # Format as YYYY-MM-DD
-            date_obj = datetime.fromisoformat(release_date.replace("Z", "+00:00"))
-            metadata["release_date"] = date_obj.strftime("%Y-%m-%d")
-
-    # Series info
-    series_info = details.get("seriesInfo")
-    if series_info:
-        metadata["series_name"] = series_info.get("name")
-        metadata["series_index"] = series_info.get("orderInSeries")
-
-    return metadata
-
-
-def nextory_transformer(details: dict) -> dict:
-    """
-    Transform Nextory book details JSON into standardized EPUB metadata format
-
-    :param details: Nextory book details JSON
-    :return: Standardized metadata dict
-    """
-    # Extract ebook format (epub or pdf - Nextory serves both as epub)
-    ebook_format = None
-    for fmt_type in ("epub", "pdf"):
-        for fmt in details.get("formats", []):
-            if fmt.get("type") == fmt_type:
-                ebook_format = fmt
-                break
-        if ebook_format:
-            break
-
-    metadata = {
-        "title": details.get("title"),
-        "authors": [author.get("name", "") for author in details.get("authors", [])],
-        "translators": [translator.get("name", "") for translator in ebook_format.get("translators", [])] if ebook_format else [],
-        "description": details.get("description_full"),
-        "language": details.get("language"),
-    }
-
-    # Format-specific metadata
-    if ebook_format:
-        metadata["publisher"] = ebook_format.get("publisher", {}).get("name")
-        metadata["isbn"] = ebook_format.get("isbn")
-
-        publication_date = ebook_format.get("publication_date")
-        if publication_date:
-            # Already in YYYY-MM-DD format
-            metadata["release_date"] = publication_date
-
-    # Series info
-    series_info = details.get("series")
-    if series_info:
-        metadata["series_name"] = series_info.get("name")
-        # Nextory uses "volume" at top level, not in series info
-        volume = details.get("volume")
-        if volume:
-            metadata["series_index"] = volume
-
-    return metadata
-
-
-# Registry of transformers by source name
-TRANSFORMERS = {
-    "storytel": storytel_transformer,
-    "nextory": nextory_transformer,
-    # Add more sources here as they're implemented
-}
-
-
-def get_transformer(source_name: str):
-    """
-    Get the metadata transformer for a given source
-
-    :param source_name: Name of the source (lowercase)
-    :return: Transformer function or None if not found
-    """
-    return TRANSFORMERS.get(source_name.lower())
diff --git a/grawlix/sources/flipp.py b/grawlix/sources/flipp.py
index 9bd16a1..cf2fa76 100644
--- a/grawlix/sources/flipp.py
+++ b/grawlix/sources/flipp.py
@@ -122,7 +122,6 @@ class Flipp(Source):
             metadata = Metadata(
                 title = f"{metadata['series_name']} {metadata['issueName']}",
                 series = metadata["series_name"],
-                identifier = issue_id
             ),
         )
 
diff --git a/grawlix/sources/nextory.py b/grawlix/sources/nextory.py
index 04fa309..433a3ec 100644
--- a/grawlix/sources/nextory.py
+++ b/grawlix/sources/nextory.py
@@ -3,7 +3,8 @@ from grawlix.encryption import AESEncryption
 from grawlix.exceptions import InvalidUrl
 from .source import Source
 
-from typing import Optional, Tuple
+from typing import Tuple
+from datetime import date
 import uuid
 import base64
 
@@ -36,7 +37,7 @@ class Nextory(Source):
         session_response = await self._client.post(
             "https://api.nextory.com/user/v1/sessions",
             json = {
-                "identifier": username,
+                "isbn": username,
                 "password": password
             },
         )
@@ -116,18 +117,11 @@ class Nextory(Source):
         _, format_id = self._find_format(product_data)
         # Nextory serves all books via epub endpoint regardless of original format
         data = await self._get_epub_data(format_id)
+        metadata = self._extract_metadata(product_data)
 
         return Book(
             data = data,
-            metadata = Metadata(
-                title = product_data["title"],
-                authors = [author["name"] for author in product_data["authors"]],
-                series = self._extract_series_name(product_data),
-            ),
-            source_data = {
-                "source_name": "nextory",
-                "details": product_data
-            }
+            metadata = metadata,
         )
 
 
@@ -150,16 +144,70 @@ class Nextory(Source):
         for format_type in ("epub", "pdf"):
             for fmt in product_data["formats"]:
                 if fmt["type"] == format_type:
-                    return (format_type, fmt["identifier"])
+                    return (format_type, fmt["isbn"])
         raise InvalidUrl
 
 
-    @staticmethod
-    def _extract_series_name(product_info: dict) -> Optional[str]:
-        series = product_info.get("series")
-        if series is None:
-            return None
-        return series["name"]
+    def _extract_metadata(self, product_data: dict) -> Metadata:
+        """
+        Extract metadata from Nextory product data
+
+        :param product_data: Product data from Nextory API
+        :return: Metadata object
+        """
+        # Find epub or pdf format for format-specific metadata
+        ebook_format = None
+        for fmt_type in ("epub", "pdf"):
+            for fmt in product_data.get("formats", []):
+                if fmt.get("type") == fmt_type:
+                    ebook_format = fmt
+                    break
+            if ebook_format:
+                break
+
+        # Basic metadata
+        title = product_data.get("title", "Unknown")
+        authors = [author["name"] for author in product_data.get("authors", [])]
+        description = product_data.get("description_full")
+        language = product_data.get("language")
+
+        # Format-specific metadata
+        publisher = None
+        isbn = None
+        release_date = None
+        translators = []
+        if ebook_format:
+            publisher = ebook_format.get("publisher", {}).get("name") if ebook_format.get("publisher") else None
+            isbn = ebook_format.get("isbn")
+            translators = [t["name"] for t in ebook_format.get("translators", [])]
+            pub_date = ebook_format.get("publication_date")
+            if pub_date:
+                # Format is YYYY-MM-DD
+                release_date = date.fromisoformat(pub_date)
+
+        # Series info
+        series = None
+        index = None
+        series_info = product_data.get("series")
+        if series_info:
+            series = series_info.get("name")
+        volume = product_data.get("volume")
+        if volume:
+            index = volume
+
+        return Metadata(
+            title=title,
+            authors=authors,
+            translators=translators,
+            language=language,
+            publisher=publisher,
+            isbn=isbn,
+            description=description,
+            release_date=release_date,
+            series=series,
+            index=index,
+            source="Nextory"
+        )
 
 
     async def _get_epub_data(self, epub_id: str) -> BookData:
diff --git a/grawlix/sources/storytel.py b/grawlix/sources/storytel.py
index 23af290..f5f2566 100644
--- a/grawlix/sources/storytel.py
+++ b/grawlix/sources/storytel.py
@@ -129,11 +129,7 @@ class Storytel(Source):
                     extension = "epub",
                     headers = self._client.headers
                 )
-            ),
-            source_data = {
-                "source_name": "storytel",
-                "details": details
-            }
+            )
         )
         return book
 
@@ -154,15 +150,21 @@ class Storytel(Source):
 
         # Extract basic metadata
         title = details.get("title", "Unknown")
+        original_title = details.get("originalTitle")
         authors = [author["name"] for author in details.get("authors", [])]
+        translators = [translator["name"] for translator in details.get("translators", [])]
         language = details.get("language")
         description = details.get("description")
+        category = details.get("category", {}).get("name") if details.get("category") else None
+        tags = [tag["name"] for tag in details.get("tags", [])[:10]]
 
-        # Extract ebook-specific publisher and release date
+        # Extract ebook-specific publisher, ISBN, and release date
         publisher = None
+        isbn = None
         release_date = None
         if ebook_format:
             publisher = ebook_format.get("publisher", {}).get("name")
+            isbn = ebook_format.get("isbn")
             release_date_str = ebook_format.get("releaseDate")
             if release_date_str:
                 # Parse ISO format date
@@ -178,13 +180,18 @@ class Storytel(Source):
 
         return Metadata(
             title=title,
+            original_title=original_title,
             authors=authors,
+            translators=translators,
             language=language,
             publisher=publisher,
+            isbn=isbn,
             description=description,
             release_date=release_date,
             series=series,
             index=index,
+            category=category,
+            tags=tags,
             source="Storytel"
         )
 

From ed8fe9eafabc321f8c6dea7abb087e3fd9b2246b Mon Sep 17 00:00:00 2001
From: ^_^ <8480595+ballaballaballa@users.noreply.github.com>
Date: Thu, 15 Jan 2026 10:59:17 +0100
Subject: [PATCH 10/11] fix: resolve compatibility issues from upstream rebase

- Fix f-string quote syntax in ereolen.py for Python < 3.12
- Fix Storytel login signature to match new url parameter
- Fix Nextory API field names (identifier vs isbn confusion)
---
 grawlix/sources/ereolen.py  | 2 +-
 grawlix/sources/nextory.py  | 4 ++--
 grawlix/sources/storytel.py | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/grawlix/sources/ereolen.py b/grawlix/sources/ereolen.py
index 5b88afd..42aea5d 100644
--- a/grawlix/sources/ereolen.py
+++ b/grawlix/sources/ereolen.py
@@ -23,7 +23,7 @@ class Ereolen(Source):
         .read_text("utf8") \
         .split("\n")
     match: list[str] = [
-        rf"https://(www.)?({"|".join(library_domains)})/reader\?orderid=.+$",
+        rf"https://(www.)?({'|'.join(library_domains)})/reader\?orderid=.+$",
     ]
     _authentication_methods = [ "login" ]
 
diff --git a/grawlix/sources/nextory.py b/grawlix/sources/nextory.py
index 433a3ec..16ddae2 100644
--- a/grawlix/sources/nextory.py
+++ b/grawlix/sources/nextory.py
@@ -37,7 +37,7 @@ class Nextory(Source):
         session_response = await self._client.post(
             "https://api.nextory.com/user/v1/sessions",
             json = {
-                "isbn": username,
+                "identifier": username,
                 "password": password
             },
         )
@@ -144,7 +144,7 @@ class Nextory(Source):
         for format_type in ("epub", "pdf"):
             for fmt in product_data["formats"]:
                 if fmt["type"] == format_type:
-                    return (format_type, fmt["isbn"])
+                    return (format_type, fmt["identifier"])
         raise InvalidUrl
 
 
diff --git a/grawlix/sources/storytel.py b/grawlix/sources/storytel.py
index f5f2566..a4d1cae 100644
--- a/grawlix/sources/storytel.py
+++ b/grawlix/sources/storytel.py
@@ -21,7 +21,7 @@ class Storytel(Source):
 
     # Authentication methods
 
-    async def login(self, username: str, password: str, **kwargs) -> None:
+    async def login(self, url: str, username: str, password: str) -> None:
         self.__username = username
         self.__password = self.encrypt_password(password)
         self._client.headers.update({"User-Agent": "Storytel/23.49 (Android 13; Pixel 6) Release/2288481"})

From 08ddad3a74794ad6d47cd5d8aa29e2604abe0b68 Mon Sep 17 00:00:00 2001
From: ^_^ <8480595+ballaballaballa@users.noreply.github.com>
Date: Fri, 16 Jan 2026 11:05:33 +0100
Subject: [PATCH 11/11] feat: add fixed-layout support for split EPUB sources

- Add rendition properties to Metadata (layout, spread, orientation)
- Extract and preserve rendition properties when merging EPUB parts
- Fix viewport meta tags for fixed-layout pages
- Use EpubItem instead of EpubHtml to preserve original content

Fix EPUB validation errors in merged output:
- Skip directory entries, mimetype, and META-INF from manifest
- Exclude nav/toc from spine for fixed-layout books

Improve CSS merging across parts:
- Keep longer version of duplicate selectors (more complete rules)
- Return None from _get_css_rule_key for invalid font-faces

Add cover detection fallback:
- Detect cover from largest image on first page when OPF lacks cover info
- Optimize lookup with dict instead of nested loops

Clean up redundant imports in epub_metadata.py
---
 grawlix/book.py                          |   4 +
 grawlix/output/epub.py                   | 362 ++++++++++++++++++++++-
 grawlix/output/metadata/epub_metadata.py |  89 +++---
 3 files changed, 383 insertions(+), 72 deletions(-)

diff --git a/grawlix/book.py b/grawlix/book.py
index 726eaf8..64d2933 100644
--- a/grawlix/book.py
+++ b/grawlix/book.py
@@ -20,6 +20,10 @@ class Metadata:
     translators: list[str] = field(default_factory=list)
     category: Optional[str] = None
     tags: list[str] = field(default_factory=list)
+    # EPUB 3 rendition properties (fixed-layout support)
+    rendition_layout: Optional[str] = None      # "pre-paginated" or "reflowable"
+    rendition_spread: Optional[str] = None      # "none", "auto", "landscape", "portrait", "both"
+    rendition_orientation: Optional[str] = None # "auto", "landscape", "portrait"
 
     def as_dict(self) -> dict:
         return {
diff --git a/grawlix/output/epub.py b/grawlix/output/epub.py
index 333ebc4..faf6dce 100644
--- a/grawlix/output/epub.py
+++ b/grawlix/output/epub.py
@@ -3,12 +3,162 @@ from grawlix.exceptions import UnsupportedOutputFormat
 from .output_format import OutputFormat, Update
 
 import asyncio
-from bs4 import BeautifulSoup
 import os
-from ebooklib import epub
+import re
+import xml.etree.ElementTree as ET
 from zipfile import ZipFile
+
+from bs4 import BeautifulSoup
+from ebooklib import epub
 import rich
 
+
+def _fix_fixed_layout_page(html_content: bytes, css_content: bytes = None) -> bytes:
+    """
+    Fix fixed-layout XHTML pages by adding viewport and fixing broken styles.
+
+    Extracts dimensions from CSS and applies them to viewport and inline styles.
+    """
+    try:
+        html_str = html_content.decode('utf-8')
+    except UnicodeDecodeError:
+        return html_content
+
+    # Extract dimensions from CSS if provided
+    width = None
+    height = None
+    if css_content:
+        try:
+            css_str = css_content.decode('utf-8')
+            # Look for body width/height
+            width_match = re.search(r'body\s*\{[^}]*width:\s*(\d+)px', css_str)
+            height_match = re.search(r'body\s*\{[^}]*height:\s*(\d+)px', css_str)
+            if width_match:
+                width = width_match.group(1)
+            if height_match:
+                height = height_match.group(1)
+        except UnicodeDecodeError:
+            pass
+
+    if not width or not height:
+        return html_content
+
+    # Add viewport meta tag if missing
+    if 'name="viewport"' not in html_str and '<head>' in html_str:
+        viewport_tag = f'<meta name="viewport" content="width={width}, height={height}"/>'
+        html_str = html_str.replace('<head>', f'<head>\n    {viewport_tag}', 1)
+
+    # Fix broken inline styles (width:px; height:px;)
+    html_str = re.sub(
+        r'style="width:px;\s*height:px;"',
+        f'style="width:{width}px; height:{height}px;"',
+        html_str
+    )
+
+    return html_str.encode('utf-8')
+
+
+def _get_css_rule_key(rule_text: str) -> str | None:
+    """Get unique key for a CSS rule. For @font-face, include font-family."""
+    selector = rule_text.split('{')[0].strip()
+    if selector == '@font-face':
+        # Extract font-family to distinguish different font-faces
+        match = re.search(r'font-family:\s*["\']?([^"\';}]+)', rule_text)
+        if match:
+            return f'@font-face:{match.group(1).strip()}'
+        return None  # Skip font-face without font-family
+    return selector if selector else None
+
+
+def _extract_opf_metadata(opf_content: bytes) -> dict:
+    """
+    Extract rendition properties, cover info, and spine properties from OPF content.
+
+    Returns dict with keys: rendition_layout, rendition_spread,
+    rendition_orientation, cover_id, cover_href, spine_properties
+    """
+    result = {
+        'rendition_layout': None,
+        'rendition_spread': None,
+        'rendition_orientation': None,
+        'cover_id': None,
+        'cover_href': None,
+        'spine_properties': {},  # Maps href -> properties (e.g., 'page-spread-left')
+    }
+
+    try:
+        root = ET.fromstring(opf_content)
+        ns = {
+            'opf': 'http://www.idpf.org/2007/opf',
+            'dc': 'http://purl.org/dc/elements/1.1/',
+        }
+
+        # Find metadata element
+        metadata = root.find('opf:metadata', ns)
+        if metadata is None:
+            metadata = root.find('{http://www.idpf.org/2007/opf}metadata')
+        if metadata is None:
+            return result
+
+        # Extract rendition properties from <meta property="rendition:X">
+        for meta in metadata.iter():
+            if meta.tag.endswith('}meta') or meta.tag == 'meta':
+                prop = meta.get('property', '')
+                if prop == 'rendition:layout':
+                    result['rendition_layout'] = meta.text
+                elif prop == 'rendition:spread':
+                    result['rendition_spread'] = meta.text
+                elif prop == 'rendition:orientation':
+                    result['rendition_orientation'] = meta.text
+
+                # Cover reference: <meta name="cover" content="image-id"/>
+                name = meta.get('name', '')
+                if name == 'cover':
+                    result['cover_id'] = meta.get('content')
+
+        # Parse manifest once for cover info and id->href mapping
+        manifest = root.find('opf:manifest', ns)
+        if manifest is None:
+            manifest = root.find('{http://www.idpf.org/2007/opf}manifest')
+
+        id_to_href = {}
+        if manifest is not None:
+            for item in manifest.iter():
+                item_id = item.get('id')
+                item_href = item.get('href')
+                if item_id and item_href:
+                    id_to_href[item_id] = item_href
+
+                # Check for cover by ID match
+                if result['cover_id'] and item_id == result['cover_id'] and not result['cover_href']:
+                    result['cover_href'] = item_href
+
+                # Check for cover-image property
+                props = item.get('properties', '')
+                if 'cover-image' in props and not result['cover_href']:
+                    result['cover_href'] = item_href
+                    result['cover_id'] = item_id
+
+        # Extract spine properties (page-spread-left, page-spread-right)
+        spine = root.find('opf:spine', ns)
+        if spine is None:
+            spine = root.find('{http://www.idpf.org/2007/opf}spine')
+        if spine is not None:
+            # Extract spine itemref properties
+            for itemref in spine.iter():
+                if itemref.tag.endswith('}itemref') or itemref.tag == 'itemref':
+                    idref = itemref.get('idref')
+                    props = itemref.get('properties')
+                    if idref and props and idref in id_to_href:
+                        href = id_to_href[idref]
+                        result['spine_properties'][href] = props
+
+    except ET.ParseError:
+        pass
+
+    return result
+
+
 class Epub(OutputFormat):
     extension = "epub"
     input_types = [SingleFile, HtmlFiles, EpubInParts]
@@ -88,22 +238,102 @@ class Epub(OutputFormat):
         progress = 1/(file_count)
         temporary_file_location = f"{location}.tmp"
 
-        added_files: set[str] = set()
-        def get_new_files(zipfile: ZipFile):
-            """Returns files in zipfile not already added to file"""
-            for filename in zipfile.namelist():
-                if filename in added_files or filename.endswith(".opf") or filename.endswith(".ncx"):
-                    continue
-                yield filename
+        added_files: dict[str, int] = {}  # Track filepath -> content size
+        opf_metadata: dict = {}
+        css_cache: dict[str, bytes] = {}  # Store CSS content for fixing HTML pages
+        cover_href: str = None  # Store cover image path from OPF
+        spine_properties: dict[str, str] = {}  # Store spine properties (href -> properties)
+
+        def should_add_file(zipfile: ZipFile, filename: str) -> bool:
+            """Check if file should be added (new or larger than existing)"""
+            # Skip directory entries, container files (ebooklib handles these), and OPF/NCX
+            if filename.endswith("/"):
+                return False
+            if filename == "mimetype" or filename.startswith("META-INF/"):
+                return False
+            if filename.endswith(".opf") or filename.endswith(".ncx"):
+                return False
+            if filename not in added_files:
+                return True
+            # If file exists, only replace if new version is larger (non-empty beats empty)
+            new_size = zipfile.getinfo(filename).file_size
+            return new_size > added_files[filename]
 
         output = epub.EpubBook()
+        opf_extracted = False
         for file in files:
             await self._download_and_write_file(file, temporary_file_location)
             with ZipFile(temporary_file_location, "r") as zipfile:
-                for filepath in get_new_files(zipfile):
+                # Extract OPF metadata from first OPF file (before skipping)
+                if not opf_extracted:
+                    for filename in zipfile.namelist():
+                        if filename.endswith(".opf"):
+                            opf_content = zipfile.read(filename)
+                            opf_metadata = _extract_opf_metadata(opf_content)
+                            # Store rendition properties in metadata
+                            if opf_metadata.get('rendition_layout'):
+                                metadata.rendition_layout = opf_metadata['rendition_layout']
+                            if opf_metadata.get('rendition_spread'):
+                                metadata.rendition_spread = opf_metadata['rendition_spread']
+                            if opf_metadata.get('rendition_orientation'):
+                                metadata.rendition_orientation = opf_metadata['rendition_orientation']
+                            if opf_metadata.get('cover_href'):
+                                cover_href = opf_metadata['cover_href']
+                            if opf_metadata.get('spine_properties'):
+                                spine_properties.update(opf_metadata['spine_properties'])
+                            opf_extracted = True
+                            break
+
+                # Collect CSS files, merging content from all parts
+                for filepath in zipfile.namelist():
+                    if filepath.endswith(".css"):
+                        content = zipfile.read(filepath)
+                        if not content:
+                            continue  # Skip empty files
+                        if filepath not in css_cache:
+                            css_cache[filepath] = content
+                        else:
+                            # Merge: combine rules, keeping the longer version for duplicate selectors
+                            existing_str = css_cache[filepath].decode('utf-8', errors='ignore')
+                            new_str = content.decode('utf-8', errors='ignore')
+
+                            # Parse existing rules into dict: key -> full rule
+                            existing_rules = {}
+                            for rule in existing_str.split('}'):
+                                if '{' in rule:
+                                    rule_key = _get_css_rule_key(rule)
+                                    if rule_key:
+                                        existing_rules[rule_key] = rule.strip() + '}'
+
+                            # Process new rules: add new ones, replace if longer
+                            for rule in new_str.split('}'):
+                                if '{' in rule:
+                                    rule_key = _get_css_rule_key(rule)
+                                    if rule_key:
+                                        new_rule = rule.strip() + '}'
+                                        if rule_key not in existing_rules or len(new_rule) > len(existing_rules[rule_key]):
+                                            existing_rules[rule_key] = new_rule
+
+                            # Rebuild CSS from merged rules
+                            css_cache[filepath] = '\n'.join(existing_rules.values()).encode('utf-8')
+
+                for filepath in zipfile.namelist():
+                    # Skip CSS files here - they'll be added after all parts are merged
+                    if filepath.endswith(".css"):
+                        continue
+                    if not should_add_file(zipfile, filepath):
+                        continue
                     content = zipfile.read(filepath)
+                    file_size = len(content)
                     if filepath.endswith("html"):
                         filename = os.path.basename(filepath)
+                        # Fix fixed-layout pages if we have rendition:layout
+                        if metadata.rendition_layout == 'pre-paginated':
+                            # Find matching CSS (e.g., page1.xhtml -> page1.css)
+                            css_path = filepath.replace('.xhtml', '.css').replace('.html', '.css')
+                            css_content = css_cache.get(css_path)
+                            if css_content:
+                                content = _fix_fixed_layout_page(content, css_content)
                         is_in_toc = False
                         title = None
                         for key, value in data.files_in_toc.items():
@@ -112,13 +342,28 @@ class Epub(OutputFormat):
                                 title = value
                                 is_in_toc = True
                                 break
-                        epub_file = epub.EpubHtml(
-                            title = title,
+                        # Use EpubItem to preserve original content (link tags, viewport, etc.)
+                        # EpubHtml parses and regenerates HTML, stripping these
+                        epub_file = epub.EpubItem(
                             file_name = filepath,
-                            content = content
+                            content = content,
+                            media_type = 'application/xhtml+xml'
                         )
                         output.add_item(epub_file)
-                        output.spine.append(epub_file)
+                        # Skip nav.xhtml from spine for fixed-layout (causes blank first page)
+                        is_nav = any(x in filepath.lower() for x in ['nav.xhtml', 'nav.html', 'toc.xhtml', 'toc.html'])
+                        if not (is_nav and metadata.rendition_layout == 'pre-paginated'):
+                            # Check for spine properties (page-spread-left/right)
+                            # Try matching with different path variations
+                            props = None
+                            for href, prop_value in spine_properties.items():
+                                if filepath.endswith(href) or href.endswith(os.path.basename(filepath)):
+                                    props = prop_value
+                                    break
+                            if props:
+                                output.spine.append((epub_file, props))
+                            else:
+                                output.spine.append(epub_file)
                         if is_in_toc:
                             output.toc.append(epub_file)
                     else:
@@ -127,11 +372,96 @@ class Epub(OutputFormat):
                             content = content
                         )
                         output.add_item(epub_file)
-                    added_files.add(filepath)
+                    added_files[filepath] = file_size
             if update:
                 update(progress)
         os.remove(temporary_file_location)
 
+        # Add merged CSS files after all parts have been processed
+        for css_path, css_content in css_cache.items():
+            css_item = epub.EpubItem(
+                file_name=css_path,
+                content=css_content,
+                media_type='text/css'
+            )
+            output.add_item(css_item)
+
+        # Set cover image if found in source OPF, or detect from first page for fixed-layout
+        if not cover_href and metadata.rendition_layout == 'pre-paginated':
+            # Find first content page from spine (excluding nav/toc)
+            first_page = None
+            for spine_item in output.spine:
+                item = spine_item[0] if isinstance(spine_item, tuple) else spine_item
+                if hasattr(item, 'file_name') and item.file_name:
+                    fname = item.file_name.lower()
+                    # Skip nav and toc files
+                    if 'nav.' in fname or 'toc.' in fname:
+                        continue
+                    if fname.endswith('.xhtml') or fname.endswith('.html'):
+                        first_page = item
+                        break
+
+            if first_page and hasattr(first_page, 'content') and first_page.content:
+                # Parse HTML to find all images and pick the largest one
+                try:
+                    content = first_page.content.decode('utf-8') if isinstance(first_page.content, bytes) else first_page.content
+                    img_matches = re.findall(r'<img[^>]+src=["\']([^"\']+)["\']', content)
+                    if img_matches:
+                        page_dir = os.path.dirname(first_page.file_name)
+                        # Build lookup dict for item sizes
+                        item_sizes = {
+                            item.file_name: len(item.content)
+                            for item in output.items
+                            if hasattr(item, 'file_name') and item.file_name
+                            and hasattr(item, 'content') and item.content
+                        }
+                        best_img = None
+                        best_size = 0
+                        for img_src in img_matches:
+                            img_path = os.path.normpath(os.path.join(page_dir, img_src))
+                            # Find matching item by suffix
+                            for file_name, size in item_sizes.items():
+                                if file_name.endswith(img_path):
+                                    if size > best_size:
+                                        best_size = size
+                                        best_img = img_path
+                                    break
+                        if best_img:
+                            cover_href = best_img
+                except (UnicodeDecodeError, AttributeError):
+                    pass
+
+        if cover_href:
+            # Find the cover image item and mark it as cover
+            for item in output.items:
+                if hasattr(item, 'file_name') and item.file_name and item.file_name.endswith(cover_href):
+                    # Get or create item ID
+                    item_id = item.id if hasattr(item, 'id') and item.id else os.path.basename(cover_href).replace('.', '-')
+                    if not item.id:
+                        item.id = item_id
+                    # Add EPUB 2 cover metadata: <meta name="cover" content="image-id"/>
+                    output.add_metadata('OPF', 'meta', '', {'name': 'cover', 'content': item_id})
+                    # Mark item with EPUB 3 cover-image property
+                    if not hasattr(item, 'properties') or item.properties is None:
+                        item.properties = []
+                    if 'cover-image' not in item.properties:
+                        item.properties.append('cover-image')
+                    break
+
+        # Apply rendition properties to output (fixed-layout support)
+        if metadata.rendition_layout:
+            output.add_metadata(None, 'meta', metadata.rendition_layout, {'property': 'rendition:layout'})
+        if metadata.rendition_spread:
+            output.add_metadata(None, 'meta', metadata.rendition_spread, {'property': 'rendition:spread'})
+        if metadata.rendition_orientation:
+            output.add_metadata(None, 'meta', metadata.rendition_orientation, {'property': 'rendition:orientation'})
+
         output.add_item(epub.EpubNcx())
-        output.add_item(epub.EpubNav())
+        nav = epub.EpubNav()
+        output.add_item(nav)
+
+        # For fixed-layout, remove nav from spine (it shouldn't be in reading order)
+        if metadata.rendition_layout == 'pre-paginated':
+            output.spine = [item for item in output.spine if item != nav and not (isinstance(item, tuple) and item[0] == nav)]
+
         epub.write_epub(location, output)
diff --git a/grawlix/output/metadata/epub_metadata.py b/grawlix/output/metadata/epub_metadata.py
index 626027c..3212b18 100644
--- a/grawlix/output/metadata/epub_metadata.py
+++ b/grawlix/output/metadata/epub_metadata.py
@@ -118,6 +118,10 @@ def _find_opf_file(epub_dir: str) -> str:
 
 def _update_epub_metadata(metadata_elem, metadata: Metadata, ns: dict, using_lxml: bool) -> None:
     """Update EPUB metadata elements from Metadata object"""
+    if using_lxml:
+        from lxml import etree as ET
+    else:
+        import xml.etree.ElementTree as ET
 
     # Helper function to create/update element
     def update_or_create_element(tag: str, text: str, attribs: dict = None):
@@ -129,13 +133,7 @@ def _update_epub_metadata(metadata_elem, metadata: Metadata, ns: dict, using_lxm
             metadata_elem.remove(elem)
 
         # Create new element
-        if using_lxml:
-            from lxml import etree as ET
-            elem = ET.SubElement(metadata_elem, tag)
-        else:
-            import xml.etree.ElementTree as ET
-            elem = ET.SubElement(metadata_elem, tag)
-
+        elem = ET.SubElement(metadata_elem, tag)
         elem.text = str(text)
         if attribs:
             for key, value in attribs.items():
@@ -145,14 +143,7 @@ def _update_epub_metadata(metadata_elem, metadata: Metadata, ns: dict, using_lxm
     def create_meta(name: str, content):
         if content is None:
             return
-
-        if using_lxml:
-            from lxml import etree as ET
-            meta = ET.SubElement(metadata_elem, f"{{{ns['opf']}}}meta")
-        else:
-            import xml.etree.ElementTree as ET
-            meta = ET.SubElement(metadata_elem, f"{{{ns['opf']}}}meta")
-
+        meta = ET.SubElement(metadata_elem, f"{{{ns['opf']}}}meta")
         meta.set('name', name)
         meta.set('content', str(content))
 
@@ -166,44 +157,25 @@ def _update_epub_metadata(metadata_elem, metadata: Metadata, ns: dict, using_lxm
             elem.set('id', 'main-title')
 
         # Add original title
-        if using_lxml:
-            from lxml import etree as ET
-            orig_title = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}title")
-        else:
-            import xml.etree.ElementTree as ET
-            orig_title = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}title")
-
+        orig_title = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}title")
         orig_title.set('id', 'original-title')
         orig_title.text = metadata.original_title
 
         # Add meta refinement for original title
-        if using_lxml:
-            meta = ET.SubElement(metadata_elem, f"{{{ns['opf']}}}meta")
-        else:
-            meta = ET.SubElement(metadata_elem, f"{{{ns['opf']}}}meta")
+        meta = ET.SubElement(metadata_elem, f"{{{ns['opf']}}}meta")
         meta.set('refines', '#original-title')
         meta.set('property', 'title-type')
         meta.text = 'original'
 
     # Authors
     for author in metadata.authors:
-        if using_lxml:
-            from lxml import etree as ET
-            creator = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}creator")
-        else:
-            import xml.etree.ElementTree as ET
-            creator = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}creator")
+        creator = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}creator")
         creator.text = author
         creator.set(f"{{{ns['opf']}}}role", "aut")
 
     # Translators
     for translator in metadata.translators:
-        if using_lxml:
-            from lxml import etree as ET
-            contributor = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}contributor")
-        else:
-            import xml.etree.ElementTree as ET
-            contributor = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}contributor")
+        contributor = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}contributor")
         contributor.text = translator
         contributor.set(f"{{{ns['opf']}}}role", "trl")
 
@@ -225,12 +197,7 @@ def _update_epub_metadata(metadata_elem, metadata: Metadata, ns: dict, using_lxm
                 metadata_elem.remove(elem)
 
         # Add new ISBN
-        if using_lxml:
-            from lxml import etree as ET
-            identifier = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}identifier")
-        else:
-            import xml.etree.ElementTree as ET
-            identifier = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}identifier")
+        identifier = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}identifier")
         identifier.text = metadata.isbn
         identifier.set(f"{{{ns['opf']}}}scheme", "ISBN")
 
@@ -240,22 +207,12 @@ def _update_epub_metadata(metadata_elem, metadata: Metadata, ns: dict, using_lxm
 
     # Category
     if metadata.category:
-        if using_lxml:
-            from lxml import etree as ET
-            subject = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}subject")
-        else:
-            import xml.etree.ElementTree as ET
-            subject = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}subject")
+        subject = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}subject")
         subject.text = metadata.category
 
     # Tags
     for tag in metadata.tags:
-        if using_lxml:
-            from lxml import etree as ET
-            subject = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}subject")
-        else:
-            import xml.etree.ElementTree as ET
-            subject = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}subject")
+        subject = ET.SubElement(metadata_elem, f"{{{ns['dc']}}}subject")
         subject.text = tag
 
     # Series info (Calibre format) - using series and index fields
@@ -263,6 +220,26 @@ def _update_epub_metadata(metadata_elem, metadata: Metadata, ns: dict, using_lxm
         create_meta("calibre:series", metadata.series)
         create_meta("calibre:series_index", metadata.index)
 
+    # EPUB 3 rendition properties (fixed-layout support)
+    # These use <meta property="...">value</meta> format, not name/content
+    def create_meta_property(property_name: str, value: str):
+        if not value:
+            return
+        # Remove existing property if present
+        for elem in list(metadata_elem):
+            if elem.get('property') == property_name:
+                metadata_elem.remove(elem)
+        meta = ET.SubElement(metadata_elem, 'meta')
+        meta.set('property', property_name)
+        meta.text = value
+
+    if metadata.rendition_layout:
+        create_meta_property('rendition:layout', metadata.rendition_layout)
+    if metadata.rendition_spread:
+        create_meta_property('rendition:spread', metadata.rendition_spread)
+    if metadata.rendition_orientation:
+        create_meta_property('rendition:orientation', metadata.rendition_orientation)
+
 
 def _repack_epub(epub_dir: str, output_path: str) -> None:
     """Repack EPUB directory into ZIP file"""