pyolivetree 2.0.0__py3-none-any.whl

pyolivetree/resources/products.py

@@ -0,0 +1,55 @@
+"""In-app XML endpoints: product registration, info and download links."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyolivetree.constants import XML
+from pyolivetree.resources._base import Resource, ids
+
+
+class Products(Resource):
+    """``www.olivetree.com/store/br5/app/in-app/xml``. Available as ``ot.products``.
+
+    These return XML as ``str``.
+    """
+
+    def _post(self, path: str, **kw: Any) -> Any:
+        return self._c.request("POST", f"{XML}/{path}", **kw)
+
+    def download_links(self, *product_ids: int) -> str:
+        """``<documents>`` XML describing each owned product and its download URLs.
+
+        Purchased book files are encrypted; this returns where to fetch them, not readable text.
+        """
+        return self._post(f"download_products/{ids(product_ids)}")
+
+    def register(self, **data: Any) -> str:
+        """Register products installed on this device."""
+        return self._post("register_products", data=data)
+
+    def info(self, **data: Any) -> str:
+        """Product info for installed products."""
+        return self._post("product_info", data=data)
+
+    def updates(self, body: Any = None) -> str:
+        """Check installed products for updates.
+
+        Args:
+            body: JSON body describing installed products.
+        """
+        return self._post("product_updates", json=body or {}, auth=False)
+
+    def email_signup(self, email: str, bibles: str = "", token: str = "") -> str:
+        """Sign an email up for free Bibles / newsletters."""
+        return self._post("email_signup", data={"email": email, "bibles": bibles, "token": token})
+
+    def reading_templates(self, *template_ids: int) -> str:
+        """Reading-plan template XML.
+
+        Args:
+            *template_ids: Template ids (``reading_template_id`` in your reading plans).
+        """
+        return self._c.request(
+            "GET", f"{XML}/download_reading_templates", params={"templateIds": ids(template_ids)}, auth=False
+        )

pyolivetree/resources/reading.py

@@ -0,0 +1,53 @@
+"""Reading plans, devotionals, recommendations and verse of the day."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyolivetree.constants import SPEECH, VOTD, WWW
+from pyolivetree.resources._base import Resource
+
+
+class Reading(Resource):
+    """Available as ``ot.reading``. No login needed."""
+
+    def daily_reading(self, type: str = "featured", **params: Any) -> Any:
+        """Reading plans and devotionals.
+
+        Args:
+            type: ``"featured"``, ``"template_versions"``, ...
+            **params: ``template_ids``, ``template_id``, ``num_recommended``, ``q``.
+        """
+        return self._c.request(
+            "GET",
+            f"{WWW}/api/daily_reading_v2.php",
+            auth=False,
+            params={"type": type, "supportsDevotionalPlans": "true", **params},
+        )
+
+    def recommended(self, **data: Any) -> Any:
+        """Recommended content for the home screen."""
+        return self._c.request("POST", f"{WWW}/api/recommended.php", data=data, auth=False)
+
+    def verse_of_the_day(self, date: str, version: str | None = None) -> str:
+        """Verse of the day page.
+
+        Args:
+            date: ``YYYY-MM-DD``.
+            version: Optional Bible version code.
+        """
+        return self._c.request(
+            "GET", f"{WWW}/votd/index.php", auth=False, params={"date": date, "version": version}
+        )
+
+    def verse_of_the_day_image(self, month: int, day: int, product_id: int) -> bytes:
+        """Verse of the day image (bytes)."""
+        return self._c.request("GET", f"{VOTD}/{month}/{day}/{product_id}", auth=False)
+
+    def now_reading(self, locale: str, path: str) -> Any:
+        """Text-to-speech audio for an audio reading plan."""
+        return self._c.request("GET", f"{SPEECH}/nowreading/{locale}/{path}", auth=False)
+
+    def completed_message(self, locale: str = "en") -> dict:
+        """Audio played when a reading is completed (``{"urls": [...]}``)."""
+        return self._c.request("GET", f"{SPEECH}/messages/{locale}/completed", auth=False)

pyolivetree/resources/store.py

@@ -0,0 +1,185 @@
+"""Store endpoints: catalog, search, your library and wishlists."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+from pyolivetree.constants import STORE
+from pyolivetree.resources._base import Resource, ids
+
+
+class Store(Resource):
+    """``www.olivetree.com/store/br5/app/json/store``. Available as ``ot.store``.
+
+    Most list endpoints return a ``product_set``: ``{"product_results": [...], "pages": [urls],
+    "total_count": n}``. Use :meth:`all_products` to walk every page.
+    """
+
+    def _post(self, path: str, **data: Any) -> Any:
+        return self._c.request("POST", f"{STORE}/{path}", data=data)
+
+    # --- catalog and feeds ---------------------------------------------------
+
+    def home(self, **kw: Any) -> dict:
+        """Store home feed (``{"rows": [...]}``)."""
+        return self._post("home", **kw)
+
+    def banner(self, **kw: Any) -> dict:
+        """Current promotional banner."""
+        return self._post("banner", **kw)
+
+    def featured_categories(self, **kw: Any) -> dict:
+        """Featured store categories (``{"categories": [...]}``)."""
+        return self._post("featured_categories", **kw)
+
+    def category(self, category_id: int, **kw: Any) -> dict:
+        """Products in a category.
+
+        Args:
+            category_id: Category id (from :meth:`featured_categories` or :meth:`home`).
+        """
+        return self._post(f"cat/{category_id}", **kw)
+
+    def search(self, q: str, **kw: Any) -> dict:
+        """Search the store.
+
+        Args:
+            q: Search text, e.g. ``"study bible"``.
+
+        Returns:
+            A ``product_set``.
+        """
+        return self._c.request("POST", f"{STORE}/search", params={"q": q}, data=kw)
+
+    def product(self, product_id: int) -> dict:
+        """Full details for one product.
+
+        Args:
+            product_id: The ``productId`` field from any product listing.
+        """
+        return self._post(f"product/{product_id}")
+
+    def products(self, *product_ids: int) -> dict:
+        """Details for several products at once, as a ``product_set``."""
+        return self._post(f"product_set/{ids(product_ids)}")
+
+    def path(self, dynamic_path: str, **kw: Any) -> Any:
+        """Open any store page by path (e.g. a home-feed ``path`` value).
+
+        Args:
+            dynamic_path: Path below ``/store/br5/app/json/store/``.
+        """
+        return self._post(dynamic_path.lstrip("/"), **kw)
+
+    def all_products(self, result: dict) -> Iterator[dict]:
+        """Yield every product across all pages of a ``product_set``.
+
+        Args:
+            result: A first page from :meth:`purchased`, :meth:`search`, :meth:`category`, etc.
+
+        Yields:
+            Product dicts (``productId``, ``title``, ``owns_product``, ...).
+        """
+        yield from result.get("product_results") or []
+        for url in (result.get("pages") or [])[1:]:
+            yield from self._c.request("POST", url).get("product_results") or []
+
+    # --- your account ----------------------------------------------------------
+
+    def purchased(self, **kw: Any) -> dict:
+        """Products you own, as a ``product_set``."""
+        return self._post("purchased", **kw)
+
+    def library(self, **kw: Any) -> Any:
+        """Library listing shown on first run."""
+        return self._post("library", **kw)
+
+    def library_details(self, *product_ids: int) -> Any:
+        """Library metadata for owned products."""
+        return self._post(f"library_details/{ids(product_ids)}")
+
+    def wishlists(self, **kw: Any) -> Any:
+        """Your wishlists (``{"lists": [...]}``)."""
+        return self._post("user_wishlists", **kw)
+
+    def wishlist_add(self, product_id: int, wishlist_id: int | None = None) -> Any:
+        """Add a product to a wishlist. Changes your account."""
+        return self._post("modify_wishlist/add", productId=product_id, wishlistId=wishlist_id)
+
+    def wishlist_remove(self, product_id: int, wishlist_id: int | None = None) -> Any:
+        """Remove a product from a wishlist. Changes your account."""
+        return self._post("modify_wishlist/remove", productId=product_id, wishlistId=wishlist_id)
+
+    # --- onboarding and marketing ---------------------------------------------
+
+    def first_run_subscriptions(self, **kw: Any) -> Any:
+        """Subscriptions offered on first launch."""
+        return self._post("first_run_subscriptions", **kw)
+
+    def first_run_interests(self, **kw: Any) -> Any:
+        """Interest topics offered on first launch."""
+        return self._post("first_run_interests", **kw)
+
+    def first_run_bible_list(self, **kw: Any) -> Any:
+        """Free Bibles offered on first launch."""
+        return self._post("first_run_bible_list", **kw)
+
+    def need_interests(self, **kw: Any) -> Any:
+        """Whether to ask the user for interests."""
+        return self._post("need_interests", **kw)
+
+    def paid_features(self, **kw: Any) -> Any:
+        """Paid features unlocked on your account."""
+        return self._post("paid_features", **kw)
+
+    def paid_features_marketing(self, **kw: Any) -> Any:
+        """Marketing copy for paid features."""
+        return self._post("paid_features_marketing", **kw)
+
+    def ads(self, **kw: Any) -> Any:
+        """In-app ads."""
+        return self._post("ads", **kw)
+
+    def product_manifest(self, **kw: Any) -> Any:
+        """Product manifest used to check for updates."""
+        return self._post("product_manifest", **kw)
+
+    def giveaway(self, code: str) -> Any:
+        """Look up or redeem a giveaway code.
+
+        Args:
+            code: The giveaway code.
+        """
+        return self._post(f"giveaway/{code}")
+
+    # --- subscriptions and purchases (change your account) --------------------
+
+    def subscriptions_available(self, **kw: Any) -> Any:
+        """Subscriptions you can buy."""
+        return self._post("subscriptions_available", **kw)
+
+    def allow_subscription_purchase(self, base_plan_id: str) -> Any:
+        """Check whether a subscription plan can be bought."""
+        return self._post(f"allow_subscription_purchase/{base_plan_id}")
+
+    def subscription_variable_product_selection(self, subscription_id: int) -> Any:
+        """Products to choose from for a pick-your-books subscription."""
+        return self._post(f"subscription_variable_product_selection/{subscription_id}")
+
+    def register_subscription(self, **data: Any) -> Any:
+        """Register a store purchase receipt. Changes your account.
+
+        Args:
+            **data: ``signupSource``, ``receiptData``, ``subscriptionProductId``,
+                ``platformToken``, ``packageName``.
+        """
+        return self._post("register_subscription", **data)
+
+    def validate_google_in_app_purchase(self, **data: Any) -> Any:
+        """Validate a Google Play purchase. Changes your account."""
+        return self._post("validate_google_in_app_purchase", **data)
+
+    def support_delete_account(self, **data: Any) -> Any:
+        """Request deletion of your Olive Tree account. **Irreversible.**"""
+        return self._post("support_delete_account", **data)

pyolivetree/resources/sync.py

@@ -0,0 +1,156 @@
+"""Sync endpoints: your notes, highlights, library and reading-plan data."""
+
+from __future__ import annotations
+
+import platform
+from collections.abc import Iterator
+from typing import Any
+
+from pyolivetree.constants import PLATFORM_ID, SYNC, SYNC_PROTOCOL, DataSet, data_set_name
+from pyolivetree.resources._base import Resource
+
+
+class Sync(Resource):
+    """``sync.olivetree.com``. Available as ``ot.sync``.
+
+    Data is split into data sets (:class:`~pyolivetree.DataSet`; plain strings also work). Each row looks like
+    ``{"id", "table_name", "table_version", "sequence_number", "deleted", "datum": {...}}``.
+    Every change gets a higher ``sequence_number``, so you can fetch only what's new.
+
+    Main tables in ``annotations``: ``annotations`` (notes, highlights, clips; text in
+    ``datum.content``), ``annotation_locations``, ``annotation_categories``, ``highlighters``.
+    """
+
+    def _q(self, **kw: Any) -> dict[str, Any]:
+        return {"device_id": self._c.device_id, "sync_client_protocol_version": SYNC_PROTOCOL, **kw}
+
+    def status(self, lock: bool = False, data_set: DataSet | str | None = None) -> dict:
+        """Server status and the latest sequence number per data set.
+
+        Args:
+            lock: Take the write lock (needed before :meth:`push`). Default leaves it alone.
+            data_set: Optional data set to scope the lock to.
+
+        Returns:
+            ``{"customer": {"user_id", "master_sequence_numbers": {...}}, "server": {...}}``.
+        """
+        q = self._q(
+            managed_data_set=_managed(data_set) if data_set else None,
+            do_not_lock=None if lock else "true",
+            reader_version=self._c.reader_version,
+        )
+        return self._c.request("GET", f"{SYNC}/syncables/status.json", params=q)
+
+    def page(self, data_set: DataSet | str = DataSet.ANNOTATIONS, above: int = 0) -> list[dict]:
+        """One page of rows changed after sequence number ``above``.
+
+        Args:
+            data_set: A :class:`~pyolivetree.DataSet` or its name, e.g. ``"library"``.
+            above: Return rows with a higher sequence number than this.
+        """
+        q = self._q(
+            platform_id=PLATFORM_ID,
+            above=above,
+            managed_data_set=_managed(data_set),
+            reader_version=self._c.reader_version,
+        )
+        return self._c.request("GET", f"{SYNC}/syncables.json", params=q).get("syncables") or []
+
+    def pull(self, data_set: DataSet | str = DataSet.ANNOTATIONS, above: int = 0) -> Iterator[dict]:
+        """Yield every row changed after ``above``, fetching pages until caught up.
+
+        Args:
+            data_set: Data set to read (:class:`~pyolivetree.DataSet` or name).
+            above: Start after this sequence number (0 = everything).
+
+        Yields:
+            Sync rows. Rows with ``deleted == 1`` were removed on another device.
+        """
+        latest = self.status()["customer"]["master_sequence_numbers"].get(data_set_name(data_set), 0)
+        while above < latest:
+            page = self.page(data_set, above)
+            if not page:
+                break
+            yield from page
+            top = max(int(i["sequence_number"]) for i in page)
+            if top <= above:  # server didn't advance; stop instead of looping
+                break
+            above = top
+
+    def table_schema(self, data_set: DataSet | str, table: str, version: int = 0) -> dict:
+        """The server's SQLite schema for a synced table.
+
+        Returns:
+            ``{"managed_data_set", "table_name", "table_version", "sqlite3_schema"}``.
+        """
+        return self._c.request(
+            "GET",
+            f"{SYNC}/syncables/get_table_schema/{_managed(data_set)}/{table}/{version}.json",
+            params={"sync_client_protocol_version": SYNC_PROTOCOL},
+        )
+
+    def push(
+        self,
+        table: str,
+        datum: dict,
+        *,
+        data_set: DataSet | str = DataSet.ANNOTATIONS,
+        item_id: int = -1,
+        sequence_number: int = -1,
+        deleted: bool = False,
+        customer_id: int | None = None,
+        release_lock: bool = True,
+    ) -> dict:
+        """Create or update one row on the server. **Changes your real account.**
+
+        The expected flow is ``status(lock=True)``, then one ``push`` per row, with
+        ``release_lock=True`` on the last one.
+
+        Args:
+            table: Table name, e.g. ``"annotations"``.
+            datum: Row fields, shaped like ``datum`` from :meth:`pull` (``client_id`` = local id).
+            data_set: Data set the table belongs to.
+            item_id: Server row id; ``-1`` creates a new row.
+            sequence_number: Current sequence number of the row; ``-1`` for new rows.
+            deleted: Mark the row deleted.
+            customer_id: Your user id. Looked up via :meth:`status` if omitted.
+            release_lock: Release the write lock after this push.
+
+        Returns:
+            ``{"syncable": {...}}`` with the saved row, or ``{"exception": {...}}``.
+        """
+        if customer_id is None:
+            customer_id = self.status()["customer"]["user_id"]
+        body = {
+            "device_id": self._c.device_id,
+            "device_model": "pyolivetree",
+            "device_os": platform.release(),
+            "sync_client_protocol_version": SYNC_PROTOCOL,
+            "managed_data_set": _managed(data_set),
+            "table_name": table,
+            "deleted": int(deleted),
+            "id": item_id,
+            "customer_id": customer_id,
+            "sequence_number": sequence_number,
+            "datum": datum,
+        }
+        q = {"sync_client_protocol_version": SYNC_PROTOCOL, "release_lock": "true" if release_lock else None}
+        return self._c.request("POST", f"{SYNC}/syncables/syncitem.json", params=q, json=body)
+
+    def release_lock(self, data_set: DataSet | str = DataSet.ANNOTATIONS) -> Any:
+        """Release the write lock taken by ``status(lock=True)``."""
+        return self._c.request(
+            "PUT", f"{SYNC}/syncables/release_lock", params=self._q(managed_data_set=_managed(data_set))
+        )
+
+    def possibly_bad_annotation_data(self) -> Any:
+        """Annotations the server flagged as possibly corrupt.
+
+        The server currently rejects this request (HTTP 401 with a token, 410 Gone with Basic auth).
+        """
+        return self._c.request("GET", f"{SYNC}/syncables/get_possibly_bad_annotation_data.json")
+
+
+def _managed(data_set: DataSet | str) -> str:
+    """Server form of a data set name: ``"managed_annotations"``."""
+    return f"managed_{data_set_name(data_set)}"

pyolivetree/resources/telemetry.py

@@ -0,0 +1,63 @@
+"""Analytics, experiments, consent and session endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyolivetree.constants import ANALYTICS, PRIVACY
+from pyolivetree.resources._base import Resource
+
+
+class Telemetry(Resource):
+    """``analytics.olivetree.com`` and ``privacy.olivetree.com``. Available as ``ot.telemetry``.
+
+    The POST/PUT methods send data to Olive Tree; wrapped for completeness.
+    """
+
+    def event_manifest(self, from_date: str | None = None, to_date: str | None = None) -> dict:
+        """Analytics event definitions, optionally for a date range (``YYYY-MM-DD``)."""
+        url = (
+            f"{ANALYTICS}/event_manifests/from/{from_date}/to/{to_date}"
+            if from_date
+            else f"{ANALYTICS}/event_manifest"
+        )
+        return self._c.request("GET", url, auth=False)
+
+    def get_variant(self, experiment_id: str, customer_id: int | None = None) -> Any:
+        """A/B experiment variant assigned to this device."""
+        return self._c.request(
+            "GET",
+            f"{ANALYTICS}/variant",
+            auth=False,
+            params={
+                "experiment_id": experiment_id,
+                "install_id": self._c.device_id,
+                "customer_id": customer_id,
+            },
+        )
+
+    def set_variant(self, **body: Any) -> Any:
+        """Set an experiment variant."""
+        return self._c.request("PUT", f"{ANALYTICS}/variant", json=body, auth=False)
+
+    def events(self, events: Any) -> Any:
+        """Send analytics events (signed)."""
+        return self._c.request("POST", f"{ANALYTICS}/events", json=events, sign="telemetry", auth=False)
+
+    def session_start(self, **body: Any) -> Any:
+        """Report an app session start (signed)."""
+        return self._c.request("POST", f"{PRIVACY}/session/start", json=body, sign="telemetry", auth=False)
+
+    def consent_receipt(self, **body: Any) -> Any:
+        """Record a consent receipt."""
+        return self._c.request("POST", f"{PRIVACY}/consent/receipt", json=body, auth=False)
+
+    def location_settings(self, **body: Any) -> dict:
+        """Read location-based consent settings; pass fields to change them."""
+        if body:
+            return self._c.request("POST", f"{PRIVACY}/consent/location/settings", json=body, auth=False)
+        return self._c.request("GET", f"{PRIVACY}/consent/location/settings", auth=False)
+
+    def subscription_log_usage(self, **body: Any) -> Any:
+        """Log subscription content usage."""
+        return self._c.request("POST", f"{PRIVACY}/subscription/log_usage", json=body, auth=False)

pyolivetree/resources/web.py

@@ -0,0 +1,61 @@
+"""Olive Tree web pages and client config files."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pyolivetree.constants import HELP, WWW
+from pyolivetree.resources._base import Resource
+
+
+class Web(Resource):
+    """Available as ``ot.web``. Returns HTML (``str``) or JSON."""
+
+    def _get(self, url: str, **params: Any) -> Any:
+        return self._c.request("GET", url, params=params, auth=False)
+
+    def timeouts(self) -> dict:
+        """Recommended network timeouts."""
+        return self._get(f"{WWW}/static/app_assets/timeouts.json")
+
+    def appirater_config(self) -> dict:
+        """Rate-this-app prompt settings."""
+        return self._get(f"{WWW}/api/appirater_config.json")
+
+    def app_to_web_bridge(self, **params: Any) -> str:
+        """Open a store page in the browser, optionally logged in.
+
+        Args:
+            **params: ``platform``, ``ReaderVersion``, ``OEM``, ``clickId``, ``productid``,
+                ``login_handoff_token`` (from
+                :meth:`~pyolivetree.resources.account.Account.web_handoff_token`).
+        """
+        return self._get(f"{WWW}/store/br5/app_to_web_bridge.php", **params)
+
+    def product_page(self, product_id: int) -> str:
+        """Store web page for a product (HTML)."""
+        return self._get(f"{WWW}/store/product.php", productid=product_id)
+
+    def bible_study_packs(self) -> str:
+        """Bible study packs page (HTML)."""
+        return self._get(f"{WWW}/store/biblestudypacks.php")
+
+    def manage_subscriptions(self) -> str:
+        """Manage-subscriptions page (HTML)."""
+        return self._get(f"{WWW}/store/manage_subscriptions.php")
+
+    def eula(self) -> str:
+        """End-user license agreement (HTML)."""
+        return self._get(f"{WWW}/eula")
+
+    def privacy_policy(self) -> str:
+        """Privacy policy (HTML)."""
+        return self._get(f"{WWW}/privacy_policy")
+
+    def help_articles(self) -> str:
+        """Help-center section for the mobile app (HTML)."""
+        return self._get(f"{HELP}/hc/en-us/sections/360000034263-Android-OLIVE-TREE-BIBLE-APP-7-1")
+
+    def help_login(self) -> str:
+        """Help article on logging in (HTML)."""
+        return self._get(f"{HELP}/hc/en-us/articles/210270643-Get-Started-Logging-In")