pyolivetree 2.0.0__py3-none-any.whl

pyolivetree/constants.py

@@ -0,0 +1,101 @@
+"""Hosts, protocol values and signing keys for the Olive Tree APIs."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+#: Main site: store, account, legacy APIs, in-app message center.
+WWW = "https://www.olivetree.com"
+#: Store JSON API (catalog, library, purchases).
+STORE = f"{WWW}/store/br5/app/json/store"
+#: Account JSON API (login, tokens, subscriptions).
+ACCOUNT = f"{WWW}/store/br5/app/json/account"
+#: In-app XML API (product registration and download links).
+XML = f"{WWW}/store/br5/app/in-app/xml"
+#: Sync server for notes, highlights, library and reading-plan data.
+SYNC = "https://sync.olivetree.com"
+#: Smart Search AI.
+AI_API = "https://biblesearch-ai.olivetree.com/api/v1"
+#: Smart Search AI staging host (serves the model list).
+AI_STAGING_API = "https://staging-biblesearch-ai.olivetree.com/api/v1"
+#: Event analytics and A/B experiments.
+ANALYTICS = "https://analytics.olivetree.com/api/v1"
+#: Consent, privacy and session telemetry.
+PRIVACY = "https://privacy.olivetree.com/api/v1"
+#: Text-to-speech for audio reading plans.
+SPEECH = "https://speech.olivetree.com/api"
+#: Static images (covers, reading-plan art).
+CDN = "https://cdn.olivetree.com"
+#: Legacy product images.
+MEDIA = "https://media.olivetree.com"
+#: Verse-of-the-day images.
+VOTD = "https://votd.olivetree.com"
+#: Help center.
+HELP = "https://help.olivetree.com"
+#: Firebase Realtime Database.
+FIREBASE = "https://biblereader-android-df00f.firebaseio.com"
+
+#: Sync protocol version for token-based accounts (4 otherwise).
+SYNC_PROTOCOL = 6
+#: Client platform id.
+PLATFORM_ID = 26
+#: Server ``errorCode`` values that mean the token is missing or expired.
+TOKEN_ERRORS = frozenset({1018, 1020})
+
+
+class DataSet(str, Enum):
+    """Sync data sets. Every method that takes a data set accepts a member or its string value.
+
+    Members are strings, so ``DataSet.ANNOTATIONS == "annotations"``.
+    """
+
+    #: Notes, highlights, clips, categories and highlighters.
+    ANNOTATIONS = "annotations"
+    #: Library categories, document details and last-read locations.
+    LIBRARY = "library"
+    #: Reading plans and their progress.
+    DAILY_READING = "daily_reading"
+    #: Recently opened text and audio locations.
+    BOOKSHELF = "bookshelf"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+#: All data sets, in backup order.
+DATA_SETS = tuple(DataSet)
+
+
+def data_set_name(data_set: DataSet | str) -> str:
+    """Return the plain name of a data set.
+
+    Args:
+        data_set: A :class:`DataSet`, its value (``"annotations"``), or the server form
+            (``"managed_annotations"``). Other strings pass through unchanged.
+
+    Returns:
+        e.g. ``"annotations"``.
+    """
+    name = data_set.value if isinstance(data_set, DataSet) else str(data_set)
+    return name.removeprefix("managed_")
+
+
+#: HMAC-SHA512 client keys for signed endpoints, by service.
+HMAC_KEYS = {
+    "telemetry": bytes.fromhex(
+        "483136e789e9781c4bf4b94a405da7b4c3109a559d1429883e71eb032cfcdc9"
+        "ceb3f76381639321b4890449ac0093c3c103e9b4b19e213d3c34f02dc4106a87e"
+    ),
+    "ai": bytes.fromhex(
+        "c69b54518884da105554f4dda9ac30b16d14f1d084318bbc389f00debaa0f37c"
+        "3f29b7494afdbe41abb7eab9c7eb5bb234cb02b2f9355cc8997c105756d580a6"
+    ),
+    "consent": bytes.fromhex(
+        "f91c94eb56d2e0ae31b902828b931243b5a0956c8f99a4ace778655d39f65511"
+        "f4f6123046516609630241a879d705c6f02b3d197bbbe78e16265eeaac87f875"
+    ),
+    "features": bytes.fromhex(
+        "d11bde62682b4b41253c4f6eec12d2a0095aa1802f92343e703af16a29168617"
+        "081c6859384f960d7680989c0600ba596e2a5d17d0444424fdd4b367ce75402b"
+    ),
+}

pyolivetree/exceptions.py

@@ -0,0 +1,35 @@
+"""Exceptions raised by pyolivetree.
+
+All of them derive from :class:`OliveTreeError`, so ``except OliveTreeError`` catches everything.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class OliveTreeError(Exception):
+    """Base error for pyolivetree.
+
+    Attributes:
+        status: HTTP status code (0 if no request was made).
+        code: Olive Tree ``errorCode`` from the body, if any (e.g. 1018 = invalid token).
+        body: Parsed response body, for inspection.
+    """
+
+    def __init__(self, message: str, status: int = 0, code: int | None = None, body: Any = None) -> None:
+        super().__init__(message)
+        self.status, self.code, self.body = status, code, body
+
+    @property
+    def status_code(self) -> int:
+        """Same as :attr:`status`."""
+        return self.status
+
+
+class OliveTreeAPIError(OliveTreeError):
+    """The server returned an HTTP error (status >= 400 other than 401)."""
+
+
+class OliveTreeAuthError(OliveTreeError):
+    """Login failed, credentials are missing, the token was rejected, or signing failed."""

pyolivetree/notes.py

@@ -0,0 +1,174 @@
+"""Back up your sync data to SQLite and export notes and highlights as Markdown.
+
+The backup is a plain SQLite file with one table, ``syncables``, holding every synced row
+(``data_set``, ``table_name``, ``id``, ``sequence_number``, ``deleted``, ``datum`` as JSON),
+plus a ``cursor`` table so later runs only fetch changes.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import os
+import sqlite3
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any
+
+from pyolivetree.constants import DATA_SETS, DataSet, data_set_name
+from pyolivetree.exceptions import OliveTreeError
+
+if TYPE_CHECKING:
+    from pyolivetree.client import OliveTree
+
+# annotation_type_id is a bit flag on the server. NOTE: mapped from a real account's data
+# (1 = typed note text, 16 = has highlighter_id, 256 = copied verse text); other bits may exist.
+#: ``annotation_type_id`` -> kind name.
+ANNOTATION_TYPES = {1: "note", 16: "highlight", 256: "clip"}
+#: Book names in canonical order; ``book_begin`` is a 1-based index into this.
+BOOKS = (
+    "Genesis Exodus Leviticus Numbers Deuteronomy Joshua Judges Ruth 1Samuel 2Samuel 1Kings "
+    "2Kings 1Chronicles 2Chronicles Ezra Nehemiah Esther Job Psalms Proverbs Ecclesiastes "
+    "SongOfSolomon Isaiah Jeremiah Lamentations Ezekiel Daniel Hosea Joel Amos Obadiah Jonah "
+    "Micah Nahum Habakkuk Zephaniah Haggai Zechariah Malachi Matthew Mark Luke John Acts Romans "
+    "1Corinthians 2Corinthians Galatians Ephesians Philippians Colossians 1Thessalonians "
+    "2Thessalonians 1Timothy 2Timothy Titus Philemon Hebrews James 1Peter 2Peter 1John 2John "
+    "3John Jude Revelation"
+).split()
+
+
+def verse_ref(d: dict[str, Any]) -> str:
+    """Format a row's verse range.
+
+    Args:
+        d: A ``datum`` with ``book_begin``/``chapter_begin``/``verse_begin`` (and optional ``_end``).
+
+    Returns:
+        e.g. ``"John 3:16-18"`` or ``"Psalms 1:1 - 2:3"``; ``""`` if there is no book.
+    """
+    b = d.get("book_begin")
+    if not b:
+        return ""
+    name = BOOKS[b - 1] if 0 < b <= len(BOOKS) else f"Book{b}"
+    ref = f"{name} {d.get('chapter_begin', '?')}:{d.get('verse_begin', '?')}"
+    end = (d.get("book_end"), d.get("chapter_end"), d.get("verse_end"))
+    if end[2] and end != (b, d.get("chapter_begin"), d.get("verse_begin")):
+        ref += f"-{end[2]}" if end[:2] == (b, d.get("chapter_begin")) else f" - {end[1]}:{end[2]}"
+    return ref
+
+
+def backup(
+    ot: OliveTree, db_path: str = "olivetree.db", data_sets: Iterable[DataSet | str] = DATA_SETS
+) -> dict[str, int]:
+    """Mirror your sync data into a SQLite file, fetching only what changed since the last run.
+
+    Args:
+        ot: A client.
+        db_path: SQLite file to create or update.
+        data_sets: Data sets to back up (:class:`~pyolivetree.DataSet` members or names).
+
+    Returns:
+        Rows fetched per data set, e.g. ``{"annotations": 12, "library": 0, ...}``.
+    """
+    db = sqlite3.connect(db_path)
+    db.executescript("""CREATE TABLE IF NOT EXISTS syncables(
+             data_set TEXT, table_name TEXT, id INTEGER, sequence_number INTEGER,
+             table_version INTEGER, deleted INTEGER, datum TEXT,
+             PRIMARY KEY(table_name, id));
+           CREATE TABLE IF NOT EXISTS cursor(data_set TEXT PRIMARY KEY, above INTEGER);""")
+    counts = {}
+    try:
+        for ds in map(data_set_name, data_sets):
+            row = db.execute("SELECT above FROM cursor WHERE data_set=?", (ds,)).fetchone()
+            above, n = (row[0] if row else 0), 0
+            for item in ot.sync.pull(ds, above):
+                seq = int(item["sequence_number"])
+                db.execute(
+                    "INSERT OR REPLACE INTO syncables VALUES(?,?,?,?,?,?,?)",
+                    (
+                        ds,
+                        item["table_name"],
+                        int(item["id"]),
+                        seq,
+                        item.get("table_version"),
+                        int(item.get("deleted") or 0),
+                        json.dumps(item.get("datum") or {}),
+                    ),
+                )
+                above, n = max(above, seq), n + 1
+            # Commit per data set so an interrupted run keeps what it already downloaded.
+            db.execute("INSERT OR REPLACE INTO cursor VALUES(?,?)", (ds, above))
+            db.commit()
+            counts[ds] = n
+    finally:
+        db.close()
+    return counts
+
+
+def annotations(db_path: str = "olivetree.db", kind: str | None = "note") -> list[dict[str, Any]]:
+    """Read annotations from a backup, in Bible order. Deleted rows are skipped.
+
+    Args:
+        db_path: SQLite file made by :func:`backup`.
+        kind: ``"note"``, ``"highlight"``, ``"clip"``, or ``None`` for all.
+
+    Returns:
+        Each row's ``datum`` plus ``type``, ``ref`` (see :func:`verse_ref`) and ``color``
+        (highlighter name). Text is in ``content``, the verse label in ``title``.
+
+    Raises:
+        OliveTreeError: If ``db_path`` is not a backup yet (run :func:`backup` first).
+    """
+    if not os.path.isfile(db_path):
+        raise OliveTreeError(f"No backup at {db_path!r}; run backup() first.")
+    db = sqlite3.connect(db_path)
+    if not db.execute("SELECT 1 FROM sqlite_master WHERE name='syncables'").fetchone():
+        db.close()
+        raise OliveTreeError(f"{db_path!r} is not a pyolivetree backup; run backup() first.")
+    try:
+        rows = db.execute(
+            "SELECT datum FROM syncables WHERE table_name='annotations' AND deleted=0"
+            " ORDER BY json_extract(datum,'$.book_begin'), json_extract(datum,'$.chapter_begin'),"
+            " json_extract(datum,'$.verse_begin'), json_extract(datum,'$.created_date')"
+        ).fetchall()
+        colors = dict(
+            db.execute(
+                "SELECT json_extract(datum,'$.client_id'), json_extract(datum,'$.name')"
+                " FROM syncables WHERE table_name='highlighters'"
+            ).fetchall()
+        )
+    finally:
+        db.close()
+    out = []
+    for (datum,) in rows:
+        d = json.loads(datum)
+        kind_of = ANNOTATION_TYPES.get(d.get("annotation_type_id"), str(d.get("annotation_type_id")))
+        if kind is None or kind_of == kind:
+            out.append(
+                {
+                    **d,
+                    "type": kind_of,
+                    "ref": verse_ref(d),
+                    "color": colors.get(d.get("highlighter_id")),
+                }
+            )
+    return out
+
+
+def to_markdown(items: list[dict[str, Any]]) -> str:
+    """Render annotations as Markdown, one ``#`` section per Bible book.
+
+    Args:
+        items: Output of :func:`annotations`.
+    """
+    parts, book = [], None
+    for it in items:
+        b = it["ref"].split(" ")[0] or "Other"
+        if b != book:
+            book = b
+            parts.append(f"# {book}\n")
+        when = dt.datetime.fromtimestamp(it["created_date"]).date() if it.get("created_date") else ""
+        meta = " · ".join(str(x) for x in (it["type"], it.get("color"), when) if x)
+        title = f"*{it['title']}* — " if it.get("title") else ""
+        parts.append(f"## {it['ref'] or it.get('title') or 'Untitled'}\n{title}{meta}\n")
+        parts.append((it.get("content") or "").strip() + "\n")
+    return "\n".join(parts)

pyolivetree/resources/__init__.py

@@ -0,0 +1,27 @@
+"""Endpoint groups. Each is attached to :class:`~pyolivetree.OliveTree` as an attribute."""
+
+from pyolivetree.resources.account import Account
+from pyolivetree.resources.ai import AI
+from pyolivetree.resources.firebase import Firebase
+from pyolivetree.resources.media import Media
+from pyolivetree.resources.messages import Messages
+from pyolivetree.resources.products import Products
+from pyolivetree.resources.reading import Reading
+from pyolivetree.resources.store import Store
+from pyolivetree.resources.sync import Sync
+from pyolivetree.resources.telemetry import Telemetry
+from pyolivetree.resources.web import Web
+
+__all__ = [
+    "AI",
+    "Account",
+    "Firebase",
+    "Media",
+    "Messages",
+    "Products",
+    "Reading",
+    "Store",
+    "Sync",
+    "Telemetry",
+    "Web",
+]

pyolivetree/resources/_base.py

@@ -0,0 +1,20 @@
+"""Base class shared by every resource group."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pyolivetree.client import OliveTree
+
+
+class Resource:
+    """A group of related endpoints bound to one :class:`~pyolivetree.OliveTree` client."""
+
+    def __init__(self, client: OliveTree) -> None:
+        self._c = client
+
+
+def ids(product_ids: tuple[int, ...]) -> str:
+    """Join ids the way the API expects in paths: ``"1,2,3"``."""
+    return ",".join(map(str, product_ids))

pyolivetree/resources/account.py

@@ -0,0 +1,117 @@
+"""Account endpoints: login, tokens, signup and subscriptions."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyolivetree.constants import ACCOUNT
+from pyolivetree.resources._base import Resource
+
+
+class Account(Resource):
+    """``www.olivetree.com/store/br5/app/json/account``. Available as ``ot.account``."""
+
+    def _creds(self, **kw: Any) -> dict[str, Any]:
+        c = self._c
+        return {
+            "user": c.username,
+            "pass": c.password,
+            "install_id": c.device_id,
+            "supportsAccessToken": 1,
+            **kw,
+        }
+
+    def login(self, **kw: Any) -> dict:
+        """Log in with the client's username and password and store the tokens.
+
+        Args:
+            **kw: Extra form fields (e.g. ``subscribe_to_newsletter``).
+
+        Returns:
+            ``{"authenticated", "user_id", "authentication_token", "expires", "refresh_token"}``.
+        """
+        data = self._c.request("POST", f"{ACCOUNT}/account_login", data=self._creds(**kw), auth=False)
+        self._c._take_tokens(data)
+        return data
+
+    def access_token(self, **kw: Any) -> dict:
+        """Exchange credentials for an access token (older login flow). Stores the tokens.
+
+        Returns:
+            Same shape as :meth:`login`.
+        """
+        data = self._c.request("POST", f"{ACCOUNT}/access_token", data=self._creds(**kw), auth=False)
+        self._c._take_tokens(data)
+        return data
+
+    def refresh_token(self) -> dict:
+        """Swap the stored refresh token for a new access token. Stores the new tokens.
+
+        Returns:
+            Same shape as :meth:`login`.
+        """
+        data = self._c.request(
+            "POST",
+            f"{ACCOUNT}/refresh_token",
+            auth=False,
+            headers={"OTAuthorization": f"Bearer {self._c.refresh_token}"},
+        )
+        self._c._take_tokens(data)
+        return data
+
+    def signup(self, email: str, password: str, first_name: str = "", **kw: Any) -> dict:
+        """Create a new Olive Tree account.
+
+        Args:
+            email: Account email.
+            password: Account password.
+            first_name: Optional first name.
+            **kw: Extra fields such as ``subscribe_to_newsletter``.
+        """
+        return self._c.request(
+            "POST",
+            f"{ACCOUNT}/account_signup",
+            auth=False,
+            data={**self._creds(**kw), "user": email, "pass": password, "first_name": first_name},
+        )
+
+    def forgot_password(self, email: str) -> dict:
+        """Send a password-reset email.
+
+        Args:
+            email: Account email.
+        """
+        return self._c.request("POST", f"{ACCOUNT}/forgot_password", data={"email": email}, auth=False)
+
+    def web_handoff_token(self, storefront_code: str | None = None) -> dict:
+        """Get a one-time token for opening olivetree.com already logged in.
+
+        Args:
+            storefront_code: Optional storefront code.
+
+        Returns:
+            ``{"token": ...}``; pass it to :meth:`~pyolivetree.resources.web.Web.app_to_web_bridge`
+            as ``login_handoff_token``.
+        """
+        return self._c.request(
+            "POST", f"{ACCOUNT}/generate_web_handoff_token", data={"storefront_code": storefront_code}
+        )
+
+    def subscription(self, subscription_id: int) -> dict:
+        """Details of one of your subscriptions.
+
+        Args:
+            subscription_id: Subscription id.
+        """
+        return self._c.request("POST", f"{ACCOUNT}/subscription/{subscription_id}")
+
+    def add_variable_subscription_selections(self, selection_id: int, **data: Any) -> dict:
+        """Save product choices for a pick-your-books subscription.
+
+        Args:
+            selection_id: Selection id.
+            **data: Form fields the store expects.
+        """
+        return self._c.request(
+            "POST", f"{ACCOUNT}/add_variable_subscription_selections/{selection_id}", data=data
+        )

pyolivetree/resources/ai.py

@@ -0,0 +1,41 @@
+"""Smart Search AI endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyolivetree.constants import AI_API, AI_STAGING_API
+from pyolivetree.resources._base import Resource
+
+
+class AI(Resource):
+    """``biblesearch-ai.olivetree.com``. Available as ``ot.ai``. Requests are HMAC-signed."""
+
+    def query(self, query: str, books: list[str] | None = None) -> Any:
+        """Ask Smart Search a question. Uses your Smart Search quota.
+
+        Args:
+            query: Question or topic, e.g. ``"verses about patience"``.
+            books: Limit results to these books, e.g. ``["Romans", "James"]``.
+        """
+        body: dict[str, Any] = {"query": query}
+        if books:
+            body["filters"] = {"books": books}
+        return self._c.request("POST", f"{AI_API}/query", json=body, sign="ai")
+
+    def status(self) -> dict:
+        """Your Smart Search usage and limits (``user_limits``, ``status``, ...)."""
+        return self._c.request("GET", f"{AI_API}/status")
+
+    def set_usage(self, input_tokens: int, output_tokens: int, requests: int) -> Any:
+        """Report Smart Search usage. Changes your usage record."""
+        return self._c.request(
+            "PUT",
+            f"{AI_API}/set-my-usage",
+            sign="ai",
+            json={"input_tokens": input_tokens, "output_tokens": output_tokens, "requests": requests},
+        )
+
+    def models(self) -> list:
+        """Available AI models."""
+        return self._c.request("GET", f"{AI_STAGING_API}/models", auth=False)

pyolivetree/resources/firebase.py

@@ -0,0 +1,24 @@
+"""Firebase Realtime Database."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyolivetree.constants import FIREBASE
+from pyolivetree.resources._base import Resource
+
+
+class Firebase(Resource):
+    """Available as ``ot.firebase``. Requests are unauthenticated."""
+
+    def get(self, path: str = "") -> Any:
+        """Read a node, e.g. ``get("config")``. The server may refuse access (HTTP 423 or 401).
+
+        Args:
+            path: Node path; empty for the root.
+        """
+        return self._c.request("GET", f"{FIREBASE}/{path.strip('/')}.json", auth=False)
+
+    def root(self) -> Any:
+        """Read the database root (``/.json``)."""
+        return self.get()

pyolivetree/resources/media.py

@@ -0,0 +1,44 @@
+"""Images and media streams."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyolivetree.constants import CDN, MEDIA, WWW
+from pyolivetree.resources._base import Resource
+
+
+class Media(Resource):
+    """Available as ``ot.media``. Image methods return ``bytes``."""
+
+    def _get(self, url: str) -> Any:
+        return self._c.request("GET", url, auth=False)
+
+    def cover(self, product_id: int) -> bytes:
+        """Product cover (JPEG)."""
+        return self._get(f"{CDN}/images/covers/{product_id}.jpg")
+
+    def cover_stack(self, product_id: int) -> bytes:
+        """Stacked cover for book sets (PNG). 404 for single products."""
+        return self._get(f"{CDN}/images/covers/{product_id}_stack.png")
+
+    def product_image(self, product_id: int) -> bytes:
+        """Legacy product image (JPEG)."""
+        return self._get(f"{MEDIA}/store/images40/{product_id}.jpg")
+
+    def reading_plan_image(self, template_id: int, size: str = "hero") -> bytes:
+        """Reading-plan artwork.
+
+        Args:
+            template_id: Reading-plan template id.
+            size: ``hero``, ``carousel``, ``grid``, ``list`` or ``portrait``.
+        """
+        return self._get(f"{CDN}/images/reading_plans/{template_id}_{size}.jpg")
+
+    def reading_plan_list_image(self, template_id: int) -> bytes:
+        """Reading-plan list thumbnail (JPEG)."""
+        return self._get(f"{WWW}/store/images/reading_plans/{template_id}_list.jpg")
+
+    def stream(self, content_id: int, name: str) -> Any:
+        """MPEG-DASH manifest for audio/video content you own."""
+        return self._c.request("GET", f"{WWW}/media/content/{content_id}/{name}/stream.mpd")

pyolivetree/resources/messages.py

@@ -0,0 +1,46 @@
+"""In-app message center."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyolivetree.constants import WWW
+from pyolivetree.resources._base import Resource
+
+_BASE = f"{WWW}/api/messages/v1"
+
+
+class Messages(Resource):
+    """Available as ``ot.messages``. Requests are HMAC-signed.
+
+    The server answers 401 until the device is registered with :meth:`register_device`.
+    """
+
+    def list(self) -> Any:
+        """Messages for this device."""
+        return self._c.request(
+            "POST",
+            f"{_BASE}/messages.php",
+            sign="telemetry",
+            auth=False,
+            json={"install_id": self._c.device_id},
+        )
+
+    def register_device(self, **body: Any) -> Any:
+        """Register this device for messages. Body fields are not documented."""
+        return self._c.request("POST", f"{_BASE}/devices.php", json=body, sign="telemetry", auth=False)
+
+    def metrics(self, message_id: int, metrics: dict) -> Any:
+        """Report that a message was seen/clicked.
+
+        Args:
+            message_id: Message id from :meth:`list`.
+            metrics: Metric values to report.
+        """
+        return self._c.request(
+            "POST",
+            f"{_BASE}/metrics.php",
+            sign="telemetry",
+            auth=False,
+            json={"install_id": self._c.device_id, "message_id": message_id, "metrics": metrics},
+        )