ebookerr-sdk 3.7.1__tar.gz → 3.7.2__tar.gz

{ebookerr_sdk-3.7.1 → ebookerr_sdk-3.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebookerr-sdk
-Version: 3.7.1
+Version: 3.7.2
 Summary: The ebookerr plugin SDK: the plugin contract, the plugin host, a test kit, the pack tool and helper kits.
 Author: ArcCdr
 License-Expression: MIT
@@ -98,6 +98,14 @@ ebookerr's; otherwise it shows the plugin as incompatible and offers a compatibl
 
 ## Release notes
 
+### 3.7.2
+
+The wire decoders fail closed: a flag (`delete`, `upsert`, `emit_followup`, `relinked`, an asset's
+or custom value's `delete`, `needs_update`, a view item's `selected`/`locked`/`fixed`) is true only
+for the JSON literal `true`; a patch's `book_id` must be a non-empty string and its `fields` an
+object with string keys; malformed custom values and assets are dropped; a story entry that is not
+an object, and a read position whose progress is not a finite number between 0 and 1, are refused.
+
 ### 3.7.1
 
 A title page's summary keeps its paragraphs: `TitlePageDocument.description()` — and so

{ebookerr_sdk-3.7.1 → ebookerr_sdk-3.7.2}/README.md

@@ -69,6 +69,14 @@ ebookerr's; otherwise it shows the plugin as incompatible and offers a compatibl
 
 ## Release notes
 
+### 3.7.2
+
+The wire decoders fail closed: a flag (`delete`, `upsert`, `emit_followup`, `relinked`, an asset's
+or custom value's `delete`, `needs_update`, a view item's `selected`/`locked`/`fixed`) is true only
+for the JSON literal `true`; a patch's `book_id` must be a non-empty string and its `fields` an
+object with string keys; malformed custom values and assets are dropped; a story entry that is not
+an object, and a read position whose progress is not a finite number between 0 and 1, are refused.
+
 ### 3.7.1
 
 A title page's summary keeps its paragraphs: `TitlePageDocument.description()` — and so

{ebookerr_sdk-3.7.1 → ebookerr_sdk-3.7.2}/ebookerr_sdk/__init__.py

@@ -44,4 +44,4 @@ ruff D, pdoc, mutmut and the traceability gate all cover the SDK; it has its own
   ``pack/``, so a fetched index and a built one are validated by exactly the same rules.
 """
 
-__version__ = "3.7.1"
+__version__ = "3.7.2"

{ebookerr_sdk-3.7.1 → ebookerr_sdk-3.7.2}/ebookerr_sdk/readpos.py

@@ -17,6 +17,7 @@ bookmark back stay in each provider plugin (``RPH-ARCH-3``).
 from __future__ import annotations
 
 import logging
+import math
 import re
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
@@ -102,8 +103,9 @@ def read_position_from_dict(data: Mapping[str, Any] | None) -> ReadPosition | No
     Returns:
         The reconstructed ``ReadPosition``, or ``None`` when ``data`` is ``None``,
         not a mapping, or missing/mistyped one of the required keys
-        (``captured_at``, ``chapter_index``, ``chapter_progress``). Optional keys
-        default per the ``ReadPosition`` dataclass when absent.
+        (``captured_at``, ``chapter_index``, ``chapter_progress``), or ``chapter_index`` is
+        a bool or negative, or ``chapter_progress`` is a bool, not finite or outside 0..1.
+        Optional keys default per the ``ReadPosition`` dataclass when absent.
     """
     if data is None or not isinstance(data, Mapping):
         return None
@@ -117,10 +119,19 @@ def read_position_from_dict(data: Mapping[str, Any] | None) -> ReadPosition | No
         # Check required fields exist and have correct types
         if captured_at is None or not isinstance(captured_at, str):
             return None
-        if chapter_index is None or not isinstance(chapter_index, int):
+        if (
+            not isinstance(chapter_index, int)
+            or isinstance(chapter_index, bool)
+            or chapter_index < 0
+        ):
             return None
         # Accept int for float (will be coerced by dataclass)
-        if chapter_progress is None or not isinstance(chapter_progress, (int, float)):
+        if (
+            not isinstance(chapter_progress, (int, float))
+            or isinstance(chapter_progress, bool)
+            or not math.isfinite(chapter_progress)
+            or not 0 <= chapter_progress <= 1
+        ):
             return None
 
         # Extract optional fields with defaults

{ebookerr_sdk-3.7.1 → ebookerr_sdk-3.7.2}/ebookerr_sdk/spi/types.py

@@ -592,11 +592,13 @@ class BookPatch:
 
     Attributes:
         book_id: For a Source, derived from the URL (the upsert key).
-        fields: Any native ``Book`` column, including every user-editable field (``title``,
-            ``author``, ``author_url``, ``series``, ``series_url``, ``category``,
+        fields: Any native ``Book`` column the core does not own, including every user-editable
+            field (``title``, ``author``, ``author_url``, ``series``, ``series_url``, ``category``,
             ``tags``, ``status``, ``site``, ``language``, ``date_published``,
             ``description``, ``story_url``, ``rating``, ``auto_pull``, ``synopsis``) — no
-            whitelist (``DEC-4``). A write lands in the ``books`` column, except for a field the
+            whitelist (``DEC-4``). A key naming a core-owned or unknown column, or a value that
+            does not fit its column, is left out with one WARNING and the rest of the patch
+            applies (``TR-DATA-9``). A write lands in the ``books`` column, except for a field the
             user has locked by editing it: their value stays and the incoming value is recorded
             as the lock's source value, what a revert restores (``LIB-D2``).
         custom_values: This plugin's own custom-value writes, namespaced to its manifest id at

{ebookerr_sdk-3.7.1 → ebookerr_sdk-3.7.2}/ebookerr_sdk/wire.py

@@ -16,6 +16,7 @@ from __future__ import annotations
 import base64
 import binascii
 import logging
+import math
 from collections.abc import Mapping, Sequence
 from datetime import datetime
 from pathlib import Path
@@ -226,20 +227,65 @@ def _wire_meta(raw: Any) -> dict[str, str]:
     return {str(k): str(v) for k, v in raw.items() if v is not None}
 
 
+def _flag(value: object, name: str) -> bool:
+    """A wire boolean: ``True`` only for the JSON literal ``true`` (``value is True``).
+
+    Args:
+        value: The decoded wire value (``None`` when the key was absent).
+        name: The wire key, used only for the DEBUG line.
+
+    Returns:
+        ``True`` only when *value* is the boolean ``True``.
+    """
+    if value is not True and value is not False and value is not None:
+        logger.debug("Wire flag %s=%r is not a JSON boolean; read as false", name, value)
+    return value is True
+
+
+def _wire_int(value: object, default: int) -> int:
+    """A wire integer: a non-bool int, or a finite float with an integral value; else default.
+
+    Args:
+        value: The decoded wire value.
+        default: The result when *value* is not a usable integer.
+
+    Returns:
+        The integer, or *default*.
+    """
+    if isinstance(value, bool):
+        return default
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float) and math.isfinite(value) and value.is_integer():
+        return int(value)
+    return default
+
+
+def _str_or_none(value: object) -> str | None:
+    """Return *value* when it is a string, else ``None``."""
+    return value if isinstance(value, str) else None
+
+
 def _wire_patch_assets(assets_raw: Any) -> list[AssetWrite]:
     """Decode patch assets from the wire, dropping malformed entries and invalid base64 data.
 
+    An entry whose ``kind`` or ``name`` is not a non-empty string is dropped; ``path`` and
+    ``media_type`` are kept only when strings; ``delete`` is true only for JSON ``true``.
+
     Args:
-        assets_raw: The raw assets list from the patch dict.
+        assets_raw: The raw assets list from the patch dict (anything but a list is empty).
 
     Returns:
         A list of decoded `AssetWrite` objects, with invalid entries dropped.
     """
+    if not isinstance(assets_raw, list):
+        return []
     assets = []
-    for asset_dict in assets_raw or []:
+    for asset_dict in assets_raw:
         if not isinstance(asset_dict, dict):
             continue
-        if "kind" not in asset_dict or "name" not in asset_dict:
+        kind, name = asset_dict.get("kind"), asset_dict.get("name")
+        if not isinstance(kind, str) or not kind or not isinstance(name, str) or not name:
             continue
         data_decoded: bytes | None = None
         data_raw = asset_dict.get("data")
@@ -249,17 +295,17 @@ def _wire_patch_assets(assets_raw: Any) -> list[AssetWrite]:
             except (binascii.Error, ValueError):
                 logger.warning(
                     "Dropped an exec plugin asset with invalid base64 data: kind=%s name=%s",
-                    asset_dict["kind"],
-                    asset_dict["name"],
+                    kind,
+                    name,
                 )
                 continue
         assets.append(
             AssetWrite(
-                kind=asset_dict["kind"],
-                name=asset_dict["name"],
-                path=asset_dict.get("path"),
-                media_type=asset_dict.get("media_type"),
-                delete=bool(asset_dict.get("delete", False)),
+                kind=kind,
+                name=name,
+                path=_str_or_none(asset_dict.get("path")),
+                media_type=_str_or_none(asset_dict.get("media_type")),
+                delete=_flag(asset_dict.get("delete"), "asset delete"),
                 data=data_decoded,
                 meta=_wire_meta(asset_dict.get("meta")),
             )
@@ -530,23 +576,24 @@ def decode_book_patch(data: Mapping[str, Any]) -> BookPatch:
 
     | Wire key | Notes |
     |---|---|
-    | `book_id` | Required; raises `WireError` if absent |
-    | `fields` | Any native `Book` column |
-    | `custom_values` | Bare keys (no prefix); `{value, value_type, updated_at?, delete?}` |
-    | `delete`, `upsert`, `emit_followup` | Boolean, default `False` |
+    | `book_id` | Required string (`""` for a conversion patch); `WireError` if absent or not one |
+    | `fields` | Object with string keys, any native `Book` column; else `WireError` |
+    | `custom_values` | Bare keys (no prefix); `{value, value_type, updated_at?, delete?}`; |
+    | | | malformed entries are dropped |
+    | `delete`, `upsert`, `emit_followup` | JSON `true` only, default `False` |
     | `assets` | Top-level (never inside `fields`); `{kind, name, path?, media_type?, |
     | | | delete?, data? (base64, SPI 2.25), meta? (object of strings, SPI 2.25)}` |
     | `chapters` | Top-level; `{url, title?, ordinal?}` (SPI 2.22) |
     | `read_position` | Via `read_position_from_dict` |
-    | `relinked` | Boolean, default False (SPI 2.19) |
+    | `relinked` | JSON `true` only, default False (SPI 2.19) |
     | `superseded_by` | Optional non-empty string (SPI 2.23); any other value is dropped to |
     | | | `None` |
     | `logs` | Optional; entries `{"level", "message"}` bridged by `parse_response`, |
     | | | never stored |
 
-    An `assets` entry missing `kind`/`name`, or a `chapters` entry with a missing or
-    blank `url`, is silently dropped rather than raising. For `ordinal`: kept as int when ≥0,
-    dropped (set to `None`) for non-int values, bools, or negatives.
+    An `assets` entry whose `kind`/`name` is not a non-empty string, or a `chapters` entry with a
+    missing or blank `url`, is silently dropped rather than raising. For `ordinal`: kept as int
+    when ≥0, dropped (set to `None`) for non-int values, bools, or negatives.
     An asset whose `data` is not valid base64 is dropped with a WARNING.
 
     Args:
@@ -556,58 +603,96 @@ def decode_book_patch(data: Mapping[str, Any]) -> BookPatch:
         The parsed `BookPatch`.
 
     Raises:
-        WireError: If `book_id` is missing.
+        WireError: If `book_id` is missing or not a string, or `fields` is not an
+            object with string keys.
     """
     if "book_id" not in data:
         raise WireError("book_id is required")
+    book_id = data["book_id"]
+    # A conversion patch carries ``""`` (no book exists yet): only a non-string is refused.
+    if not isinstance(book_id, str):
+        raise WireError("book_id must be a string")
 
-    custom_values_raw = data.get("custom_values", {})
-    custom_values = {
-        k: CustomValueWrite(
-            value=v["value"],
-            value_type=v["value_type"],
-            updated_at=v.get("updated_at"),
-            delete=bool(v.get("delete", False)),
-        )
-        for k, v in custom_values_raw.items()
-    }
-
+    fields = _wire_fields(data.get("fields"))
+    custom_values = _wire_custom_values(data.get("custom_values"))
     assets = _wire_patch_assets(data.get("assets", []))
-
-    chapters_raw = data.get("chapters", [])
-    chapters = []
-    if isinstance(chapters_raw, list):
-        for entry in chapters_raw:
-            if not isinstance(entry, dict):
-                continue
-            url = entry.get("url")
-            if not isinstance(url, str) or not url:
-                logger.debug("Dropped invalid chapter entry: %r", entry)
-                continue
-            title = entry.get("title")
-            if title is not None:
-                title = str(title)
-            ordinal = _parse_chapter_ordinal(entry.get("ordinal"))
-            chapters.append(ChapterLink(url=url, title=title, ordinal=ordinal))
+    chapters = _wire_chapters(data.get("chapters", []))
 
     superseded_raw = data.get("superseded_by")
     superseded_by = superseded_raw if isinstance(superseded_raw, str) and superseded_raw else None
 
     return BookPatch(
-        book_id=data["book_id"],
-        fields=dict(data.get("fields", {})),
+        book_id=book_id,
+        fields=fields,
         custom_values=custom_values,
-        delete=bool(data.get("delete", False)),
-        upsert=bool(data.get("upsert", False)),
-        emit_followup=bool(data.get("emit_followup", False)),
+        delete=_flag(data.get("delete"), "delete"),
+        upsert=_flag(data.get("upsert"), "upsert"),
+        emit_followup=_flag(data.get("emit_followup"), "emit_followup"),
         assets=tuple(assets),
         chapters=tuple(chapters),
         read_position=read_position_from_dict(data.get("read_position")),
-        relinked=bool(data.get("relinked", False)),
+        relinked=_flag(data.get("relinked"), "relinked"),
         superseded_by=superseded_by,
     )
 
 
+def _wire_fields(raw: object) -> dict[str, Any]:
+    """Decode a patch's ``fields``: absent or null is empty, else an object with string keys."""
+    if raw is None:
+        return {}
+    if not isinstance(raw, Mapping):
+        raise WireError("fields must be an object")
+    if not all(isinstance(k, str) for k in raw):
+        raise WireError("fields keys must be strings")
+    return dict(raw)
+
+
+def _wire_custom_values(raw: object) -> dict[str, CustomValueWrite]:
+    """Decode a patch's ``custom_values``, dropping every malformed entry."""
+    if not isinstance(raw, Mapping):
+        if raw is not None:
+            logger.debug("Dropped invalid custom_values: %r", raw)
+        return {}
+    custom_values: dict[str, CustomValueWrite] = {}
+    for key, entry in raw.items():
+        if (
+            not isinstance(key, str)
+            or not key
+            or not isinstance(entry, Mapping)
+            or "value" not in entry
+            or "value_type" not in entry
+        ):
+            logger.debug("Dropped invalid custom value %r", key)
+            continue
+        custom_values[key] = CustomValueWrite(
+            value=entry["value"],
+            value_type=entry["value_type"],
+            updated_at=entry.get("updated_at"),
+            delete=_flag(entry.get("delete"), "custom value delete"),
+        )
+    return custom_values
+
+
+def _wire_chapters(raw: object) -> list[ChapterLink]:
+    """Decode a patch's ``chapters``, dropping entries without a usable url."""
+    chapters: list[ChapterLink] = []
+    if not isinstance(raw, list):
+        return chapters
+    for entry in raw:
+        if not isinstance(entry, dict):
+            continue
+        url = entry.get("url")
+        if not isinstance(url, str) or not url:
+            logger.debug("Dropped invalid chapter entry: %r", entry)
+            continue
+        title = entry.get("title")
+        if title is not None:
+            title = str(title)
+        ordinal = _parse_chapter_ordinal(entry.get("ordinal"))
+        chapters.append(ChapterLink(url=url, title=title, ordinal=ordinal))
+    return chapters
+
+
 def encode_book_patch(patch: BookPatch) -> dict[str, Any]:
     """Serialize a ``BookPatch`` to the wire object :func:`decode_book_patch` reads.
 
@@ -688,7 +773,7 @@ def decode_update_check(data: Mapping[str, Any]) -> UpdateCheck:
 
     | Wire key | Type | Notes |
     |---|---|---|
-    | `needs_update` | bool | Coerced with `bool()`; absent means `False` |
+    | `needs_update` | bool | JSON `true` only; anything else, or absent, means `False` |
     | `meta` | object or null | Kept only when it is a mapping; anything else becomes `None` |
     | `book_id` | string or null | — |
     | `error` | string or null | Set by the plugin when its own check failed |
@@ -707,7 +792,7 @@ def decode_update_check(data: Mapping[str, Any]) -> UpdateCheck:
     fields_raw = data.get("fields")
     fields = dict(fields_raw) if isinstance(fields_raw, Mapping) else {}
     return UpdateCheck(
-        needs_update=bool(data.get("needs_update", False)),
+        needs_update=_flag(data.get("needs_update"), "needs_update"),
         meta=meta,
         book_id=str(book_id_raw) if book_id_raw is not None else None,
         error=str(error_raw) if error_raw is not None else None,
@@ -729,13 +814,18 @@ def encode_read_state_changes(changes: ReadStateChanges) -> dict[str, Any]:
 
 
 def decode_read_state_changes(data: Mapping[str, Any]) -> ReadStateChanges:
-    """Rebuild ReadStateChanges; a missing list is empty; a non-string marker is ``None``."""
+    """Rebuild ReadStateChanges; a missing or non-list list is empty, a non-string marker ``None``.
+
+    ``more`` is true only for the JSON literal ``true``.
+    """
     marker = data.get("marker")
+    items = data.get("items")
+    collections = data.get("collections")
     return ReadStateChanges(
-        items=tuple(str(i) for i in data.get("items") or ()),
-        collections=tuple(str(c) for c in data.get("collections") or ()),
+        items=tuple(str(i) for i in items) if isinstance(items, list) else (),
+        collections=tuple(str(c) for c in collections) if isinstance(collections, list) else (),
         marker=marker if isinstance(marker, str) else None,
-        more=bool(data.get("more", False)),
+        more=_flag(data.get("more"), "more"),
     )
 
 
@@ -797,8 +887,10 @@ def decode_story_patch(data: Mapping[str, Any]) -> StoryPatch:  # noqa: C901
         The parsed `StoryPatch`.
 
     Raises:
-        WireError: If ``url`` is missing or blank.
+        WireError: If ``data`` is not an object, or ``url`` is missing or blank.
     """
+    if not isinstance(data, Mapping):
+        raise WireError("story entry must be an object")
     url = data.get("url")
     if not isinstance(url, str) or not url:
         raise WireError("story url is required")
@@ -900,9 +992,9 @@ def _decode_view_items(items_data: Any) -> tuple[ViewItem, ...]:
         item_label = str(item_raw.get("label", ""))
         sublabel = str(item_raw.get("sublabel", ""))
         badges = tuple(str(b) for b in item_raw.get("badges", []))
-        selected = bool(item_raw.get("selected", True))
-        locked = bool(item_raw.get("locked", False))
-        fixed = bool(item_raw.get("fixed", False))
+        selected = True if "selected" not in item_raw else _flag(item_raw["selected"], "selected")
+        locked = _flag(item_raw.get("locked"), "locked")
+        fixed = _flag(item_raw.get("fixed"), "fixed")
         fixed_reason = str(item_raw.get("fixed_reason", ""))
 
         items.append(
@@ -944,6 +1036,10 @@ def _decode_view_fields(fields_data: Any) -> tuple[SettingsField, ...]:
 def decode_plugin_view(raw: Mapping[str, Any]) -> PluginView:
     """Rebuild a ``PluginView`` from an exec plugin's ``op: "view"`` frame (``PV-FR-4``).
 
+    Fail-closed: a section or item flag is true only for JSON ``true`` (an item without
+    ``selected`` is selected), and ``min_selected`` that is not a usable integer is ``0``.
+    A truthy non-boolean ``danger`` is read as dangerous (the safe direction).
+
     Args:
         raw: The frame's ``view`` object.
 
@@ -980,10 +1076,10 @@ def decode_plugin_view(raw: Mapping[str, Any]) -> PluginView:
 
         label = str(section_raw.get("label", ""))
         text = str(section_raw.get("text", ""))
-        selectable = bool(section_raw.get("selectable", False))
-        reorderable = bool(section_raw.get("reorderable", False))
-        min_selected = int(section_raw.get("min_selected", 0))
-        select_all = bool(section_raw.get("select_all", False))
+        selectable = _flag(section_raw.get("selectable"), "selectable")
+        reorderable = _flag(section_raw.get("reorderable"), "reorderable")
+        min_selected = _wire_int(section_raw.get("min_selected", 0), 0)
+        select_all = _flag(section_raw.get("select_all"), "select_all")
         item_verb = str(section_raw.get("item_verb", "Select"))
 
         items = _decode_view_items(section_raw.get("items", []))

{ebookerr_sdk-3.7.1 → ebookerr_sdk-3.7.2}/ebookerr_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ebookerr-sdk
-Version: 3.7.1
+Version: 3.7.2
 Summary: The ebookerr plugin SDK: the plugin contract, the plugin host, a test kit, the pack tool and helper kits.
 Author: ArcCdr
 License-Expression: MIT
@@ -98,6 +98,14 @@ ebookerr's; otherwise it shows the plugin as incompatible and offers a compatibl
 
 ## Release notes
 
+### 3.7.2
+
+The wire decoders fail closed: a flag (`delete`, `upsert`, `emit_followup`, `relinked`, an asset's
+or custom value's `delete`, `needs_update`, a view item's `selected`/`locked`/`fixed`) is true only
+for the JSON literal `true`; a patch's `book_id` must be a non-empty string and its `fields` an
+object with string keys; malformed custom values and assets are dropped; a story entry that is not
+an object, and a read position whose progress is not a finite number between 0 and 1, are refused.
+
 ### 3.7.1
 
 A title page's summary keeps its paragraphs: `TitlePageDocument.description()` — and so

{ebookerr_sdk-3.7.1 → ebookerr_sdk-3.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ebookerr-sdk"
-version = "3.7.1"
+version = "3.7.2"
 description = "The ebookerr plugin SDK: the plugin contract, the plugin host, a test kit, the pack tool and helper kits."
 readme = "README.md"
 requires-python = ">=3.11"