nos-private-api 0.1.0__tar.gz

nos_private_api-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 11philip22
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nos_private_api-0.1.0/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: nos-private-api
+Version: 0.1.0
+Summary: Python client for the NOS Android app API
+Author: 11philip22
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/11philip22/nos-private-api
+Project-URL: Repository, https://github.com/11philip22/nos-private-api
+Project-URL: Issues, https://github.com/11philip22/nos-private-api/issues
+Keywords: nos,news,api,client
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx
+Dynamic: license-file
+
+<div align="center">
+
+# nos-private-api
+
+*Python client and notes for the NOS Android app API*
+
+![Python](https://img.shields.io/badge/Python->=3.10-3776ab?style=flat-square&logo=python&logoColor=white)
+![Status](https://img.shields.io/badge/status-alpha-orange?style=flat-square)
+![HTTPX](https://img.shields.io/badge/httpx-client-1f6feb?style=flat-square)
+
+[Features](#features) - [Installation](#installation) - [Usage](#usage) - [API map](#api-map)
+
+</div>
+
+`nos-private-api` is a small Python package for reading NOS app content through the same first-party endpoints used by the Android app. It includes a typed client for article feeds and item details, plus reverse-engineered API notes in [`docs/apis`](https://github.com/11philip22/nos-private-api/tree/main/docs/apis).
+
+> [!IMPORTANT]
+> This project targets an unofficial private API. Endpoints, response shapes, and header requirements can change without notice.
+
+## Features
+
+- Generate the app-style `X-NOS` header automatically.
+- Fetch paginated item feeds with category, subcategory, type, and `before` filters.
+- Fetch full article details by item ID.
+- Parse item summaries, articles, images, videos, links, tags, and categories into dataclasses.
+- Keep the original API payload available on `.raw` for fields that are not modeled yet.
+
+## Installation
+
+Install from the repository root:
+
+```bash
+python -m pip install .
+```
+
+For local development:
+
+```bash
+python -m pip install -e .
+```
+
+## Usage
+
+### List news articles
+
+```python
+from nos_private_api import NosClient
+
+client = NosClient()
+
+page = client.list_items(
+    main_categories="nieuws",
+    types="article",
+)
+
+for item in page.items:
+    print(item.id, item.title)
+```
+
+### Fetch an article
+
+```python
+article = client.get_item(page.items[0].id)
+
+print(article.title)
+print(article.published_at)
+print(article.text)
+
+for image in article.images:
+    print(image.description, image.best_url(width=800, ratio="16:9"))
+
+for video in article.videos:
+    print(video.title, video.best_url())
+
+for link in article.links:
+    print(link.title, link.url)
+```
+
+### Filter by subcategory
+
+```python
+page = client.list_items(
+    main_categories="nieuws",
+    sub_categories="politiek",
+    types="article",
+)
+```
+
+Common news subcategories include `binnenland`, `buitenland`, `cultuur-en-media`, `economie`, `koningshuis`, `opmerkelijk`, `politiek`, and `tech`.
+
+### Follow pagination
+
+```python
+page = client.list_items(main_categories="nieuws")
+
+while page.links.next:
+    page = client.list_items(url=page.links.next)
+
+    for item in page.items:
+        print(item.id, item.title)
+```
+
+## API map
+
+The [`docs/apis`](https://github.com/11philip22/nos-private-api/tree/main/docs/apis) directory documents the Android API research behind the client:
+
+| Area | Notes |
+| --- | --- |
+| [`auth.md`](https://github.com/11philip22/nos-private-api/blob/main/docs/apis/auth.md) | Timestamp endpoint and `X-NOS` header format |
+| [`nos-content.md`](https://github.com/11philip22/nos-private-api/blob/main/docs/apis/nos-content.md) | Items, pages, search, live, weather, soccer, and widget endpoints |
+| [`recommendations.md`](https://github.com/11philip22/nos-private-api/blob/main/docs/apis/recommendations.md) | Content-based and collaborative recommendation endpoints |
+| [`region-and-third-party.md`](https://github.com/11philip22/nos-private-api/blob/main/docs/apis/region-and-third-party.md) | Regional broadcaster APIs and NPO telemetry endpoints |
+
+## Development
+
+This package uses `setuptools` and depends on `httpx`.
+
+```bash
+python -m pip install -e .
+python -c "from nos_private_api import NosClient; print(NosClient.BASE_URL)"
+```

nos_private_api-0.1.0/README.md

@@ -0,0 +1,121 @@
+<div align="center">
+
+# nos-private-api
+
+*Python client and notes for the NOS Android app API*
+
+![Python](https://img.shields.io/badge/Python->=3.10-3776ab?style=flat-square&logo=python&logoColor=white)
+![Status](https://img.shields.io/badge/status-alpha-orange?style=flat-square)
+![HTTPX](https://img.shields.io/badge/httpx-client-1f6feb?style=flat-square)
+
+[Features](#features) - [Installation](#installation) - [Usage](#usage) - [API map](#api-map)
+
+</div>
+
+`nos-private-api` is a small Python package for reading NOS app content through the same first-party endpoints used by the Android app. It includes a typed client for article feeds and item details, plus reverse-engineered API notes in [`docs/apis`](https://github.com/11philip22/nos-private-api/tree/main/docs/apis).
+
+> [!IMPORTANT]
+> This project targets an unofficial private API. Endpoints, response shapes, and header requirements can change without notice.
+
+## Features
+
+- Generate the app-style `X-NOS` header automatically.
+- Fetch paginated item feeds with category, subcategory, type, and `before` filters.
+- Fetch full article details by item ID.
+- Parse item summaries, articles, images, videos, links, tags, and categories into dataclasses.
+- Keep the original API payload available on `.raw` for fields that are not modeled yet.
+
+## Installation
+
+Install from the repository root:
+
+```bash
+python -m pip install .
+```
+
+For local development:
+
+```bash
+python -m pip install -e .
+```
+
+## Usage
+
+### List news articles
+
+```python
+from nos_private_api import NosClient
+
+client = NosClient()
+
+page = client.list_items(
+    main_categories="nieuws",
+    types="article",
+)
+
+for item in page.items:
+    print(item.id, item.title)
+```
+
+### Fetch an article
+
+```python
+article = client.get_item(page.items[0].id)
+
+print(article.title)
+print(article.published_at)
+print(article.text)
+
+for image in article.images:
+    print(image.description, image.best_url(width=800, ratio="16:9"))
+
+for video in article.videos:
+    print(video.title, video.best_url())
+
+for link in article.links:
+    print(link.title, link.url)
+```
+
+### Filter by subcategory
+
+```python
+page = client.list_items(
+    main_categories="nieuws",
+    sub_categories="politiek",
+    types="article",
+)
+```
+
+Common news subcategories include `binnenland`, `buitenland`, `cultuur-en-media`, `economie`, `koningshuis`, `opmerkelijk`, `politiek`, and `tech`.
+
+### Follow pagination
+
+```python
+page = client.list_items(main_categories="nieuws")
+
+while page.links.next:
+    page = client.list_items(url=page.links.next)
+
+    for item in page.items:
+        print(item.id, item.title)
+```
+
+## API map
+
+The [`docs/apis`](https://github.com/11philip22/nos-private-api/tree/main/docs/apis) directory documents the Android API research behind the client:
+
+| Area | Notes |
+| --- | --- |
+| [`auth.md`](https://github.com/11philip22/nos-private-api/blob/main/docs/apis/auth.md) | Timestamp endpoint and `X-NOS` header format |
+| [`nos-content.md`](https://github.com/11philip22/nos-private-api/blob/main/docs/apis/nos-content.md) | Items, pages, search, live, weather, soccer, and widget endpoints |
+| [`recommendations.md`](https://github.com/11philip22/nos-private-api/blob/main/docs/apis/recommendations.md) | Content-based and collaborative recommendation endpoints |
+| [`region-and-third-party.md`](https://github.com/11philip22/nos-private-api/blob/main/docs/apis/region-and-third-party.md) | Regional broadcaster APIs and NPO telemetry endpoints |
+
+## Development
+
+This package uses `setuptools` and depends on `httpx`.
+
+```bash
+python -m pip install -e .
+python -c "from nos_private_api import NosClient; print(NosClient.BASE_URL)"
+```

nos_private_api-0.1.0/nos_private_api/__init__.py

@@ -0,0 +1,14 @@
+from .client import NosClient
+from .types import Article, Category, Image, ItemList, ItemSummary, Links, Tag, Video
+
+__all__ = [
+    "Article",
+    "Category",
+    "Image",
+    "ItemList",
+    "ItemSummary",
+    "Links",
+    "NosClient",
+    "Tag",
+    "Video",
+]

nos_private_api-0.1.0/nos_private_api/client.py

@@ -0,0 +1,117 @@
+import base64
+import hashlib
+import time
+from collections.abc import Iterable
+
+import httpx
+
+from .types import Article, ItemList
+
+
+class NosClient:
+    BASE_URL = "https://api.nos.nl/"
+    TIMESTAMP_URL = BASE_URL + "nosapp/v4//data/timestamp"
+    SECRET = ";UB}7Gaji==JPHtjX3@c"
+
+    def __init__(
+        self,
+        client: httpx.Client | None = None,
+        *,
+        device: str = "generic",
+        model: str = "sdk_gphone64_x86_64",
+        sdk_int: int = 35,
+        incremental: str = "123456",
+        android_release: str = "15",
+    ) -> None:
+        self._client = client or httpx.Client(timeout=20, follow_redirects=True)
+        self.device = device
+        self.model = model
+        self.sdk_int = sdk_int
+        self.incremental = incremental
+        self.android_release = android_release
+        self._server_epoch: int | None = None
+        self._synced_at: float | None = None
+
+    def list_items(
+        self,
+        *,
+        main_categories: str | Iterable[str] | None = None,
+        sub_categories: str | Iterable[str] | None = None,
+        types: str | Iterable[str] | None = ("article",),
+        before: str | None = None,
+        url: str | None = None,
+    ) -> ItemList:
+        """Return a page of items, optionally filtered or fetched by URL."""
+        params = (
+            None
+            if url
+            else self._list_items_params(main_categories, sub_categories, types, before)
+        )
+        data = self._request_json(
+            url or self.BASE_URL + "nosapp/v4/items", params=params
+        )
+        return ItemList.from_json(data)
+
+    def get_item(self, item_id: int) -> Article:
+        """Return the full article for an item ID."""
+        return Article.from_json(
+            self._request_json(f"{self.BASE_URL}nosapp/v4/items/{item_id}")
+        )
+
+    def _request_json(
+        self, url: str, *, params: list[tuple[str, str]] | None = None
+    ) -> dict:
+        response = self._client.get(
+            url, params=params, headers={"X-NOS": self._x_nos_header()}
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def _list_items_params(
+        self,
+        main_categories: str | Iterable[str] | None,
+        sub_categories: str | Iterable[str] | None,
+        types: str | Iterable[str] | None,
+        before: str | None,
+    ) -> list[tuple[str, str]]:
+        params: list[tuple[str, str]] = []
+        params += self._array_params("mainCategories", main_categories)
+        params += self._array_params("subCategories", sub_categories)
+        params += self._array_params("types", types)
+        if before:
+            params.append(("before", before))
+        return params
+
+    def _array_params(
+        self, name: str, values: str | Iterable[str] | None
+    ) -> list[tuple[str, str]]:
+        if values is None:
+            return []
+        if isinstance(values, str):
+            values = (values,)
+        return [(f"{name}[]", value) for value in values]
+
+    def _x_nos_header(self) -> str:
+        epoch = self._timestamp()
+        payload = (
+            f"nos;{epoch};"
+            f"{self.device}/{self.model};"
+            f"Android {self.sdk_int}/{self.incremental};"
+            f"nl.nos.app/{self.android_release}"
+        )
+        signature = hashlib.md5((self.SECRET + payload).encode()).hexdigest()
+        body = base64.b64encode(payload.encode()).decode()
+        return signature + body
+
+    def _timestamp(self) -> int:
+        if self._server_epoch is not None and self._synced_at is not None:
+            return int(self._server_epoch + (time.time() - self._synced_at))
+        try:
+            response = self._client.get(self.TIMESTAMP_URL)
+            response.raise_for_status()
+            data = response.json()
+            self._server_epoch = int(data["timestamp"])
+            self._synced_at = time.time()
+            return self._server_epoch
+        except Exception:
+            return int(time.time())

nos_private_api-0.1.0/nos_private_api/types.py

@@ -0,0 +1,415 @@
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+from types import SimpleNamespace
+from typing import Any
+
+
+JsonDict = dict[str, Any]
+
+
+def _get(data: JsonDict, *names: str, default: Any = None) -> Any:
+    for name in names:
+        if name in data:
+            return data[name]
+    return default
+
+
+def _dict(value: Any) -> JsonDict:
+    return value if isinstance(value, dict) else {}
+
+
+def _list(value: Any) -> list[Any]:
+    return value if isinstance(value, list) else []
+
+
+def _dicts(value: Any) -> list[JsonDict]:
+    return [item for item in _list(value) if isinstance(item, dict)]
+
+
+def _url_map(value: Any) -> dict[str, str]:
+    if isinstance(value, dict):
+        return {str(key): str(url) for key, url in value.items() if url is not None}
+    if isinstance(value, str):
+        return {"url": value}
+    return {}
+
+
+def _first_url(urls: dict[str, str]) -> str | None:
+    for key in ("jpg", "mp4", "url"):
+        if key in urls:
+            return urls[key]
+    return next(iter(urls.values()), None)
+
+
+def _best_url(formats: list[JsonDict], width: int | None) -> str | None:
+    if not formats:
+        return None
+    if width is None:
+        selected = max(formats, key=lambda item: item.get("width") or 0)
+    else:
+        wider = [
+            item for item in formats if item.get("width") and item["width"] >= width
+        ]
+        selected = (
+            min(wider, key=lambda item: item.get("width") or 0)
+            if wider
+            else max(formats, key=lambda item: item.get("width") or 0)
+        )
+    return _first_url(_url_map(selected.get("url")))
+
+
+@dataclass(slots=True)
+class Links:
+    first: str | None = None
+    next: str | None = None
+    prev: str | None = None
+    raw: JsonDict = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, data: JsonDict | None) -> "Links":
+        data = data or {}
+        return cls(
+            first=data.get("first"),
+            next=data.get("next"),
+            prev=data.get("prev"),
+            raw=data,
+        )
+
+
+@dataclass(slots=True)
+class Tag:
+    name: str | None = None
+    label: str | None = None
+    raw: JsonDict = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, data: JsonDict) -> "Tag":
+        return cls(name=data.get("name"), label=data.get("label"), raw=data)
+
+
+@dataclass(slots=True)
+class Category:
+    name: str | None = None
+    label: str | None = None
+    main_category: str | None = None
+    raw: JsonDict = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, data: JsonDict) -> "Category":
+        return cls(
+            name=data.get("name"),
+            label=data.get("label"),
+            main_category=data.get("main_category"),
+            raw=data,
+        )
+
+
+@dataclass(slots=True)
+class Image:
+    copyright: str | None = None
+    copyright_url: str | None = None
+    description: str | None = None
+    display: str | None = None
+    formats: list[JsonDict] = field(default_factory=list)
+    aspect_ratios: list[JsonDict] = field(default_factory=list)
+    raw: JsonDict = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, data: JsonDict | None) -> "Image | None":
+        if not isinstance(data, dict):
+            return None
+        return cls(
+            copyright=data.get("copyright"),
+            copyright_url=data.get("copyright_url"),
+            description=data.get("description"),
+            display=data.get("display"),
+            formats=_dicts(data.get("formats")),
+            aspect_ratios=_dicts(data.get("aspect_ratios")),
+            raw=data,
+        )
+
+    def best_url(
+        self, *, width: int | None = None, ratio: str | None = None
+    ) -> str | None:
+        formats = self.formats
+        if ratio:
+            formats = next(
+                (
+                    _dicts(item.get("formats"))
+                    for item in self.aspect_ratios
+                    if item.get("ratio") == ratio
+                ),
+                formats,
+            )
+        return _best_url(formats, width)
+
+
+@dataclass(slots=True)
+class ItemSummary:
+    id: int
+    type: str | None = None
+    title: str | None = None
+    description: str | None = None
+    image: Image | None = None
+    owner: str | None = None
+    published_at: str | None = None
+    modified_at: str | None = None
+    item_at: str | None = None
+    categories: list[Category] = field(default_factory=list)
+    collections: list[JsonDict] = field(default_factory=list)
+    keywords: list[Tag] = field(default_factory=list)
+    system_tag: Tag | None = None
+    label: str | None = None
+    status: str | None = None
+    has_video: bool = False
+    has_audio: bool = False
+    has_photos: bool = False
+    raw: JsonDict = field(default_factory=dict)
+
+    @staticmethod
+    def _item_fields(data: JsonDict) -> dict[str, Any]:
+        return {
+            "id": int(data["id"]),
+            "type": data.get("type"),
+            "title": data.get("title"),
+            "description": data.get("description"),
+            "image": Image.from_json(data.get("image")),
+            "owner": data.get("owner"),
+            "published_at": _get(data, "published_at", "publishedDate"),
+            "modified_at": _get(data, "modified_at", "modifiedDate"),
+            "item_at": data.get("item_at"),
+            "categories": [
+                Category.from_json(item) for item in _dicts(data.get("categories"))
+            ],
+            "collections": _dicts(data.get("collections")),
+            "keywords": [
+                Tag.from_json(item) for item in _dicts(data.get("keywords"))
+            ],
+            "system_tag": (
+                Tag.from_json(data["system_tag"])
+                if isinstance(data.get("system_tag"), dict)
+                else None
+            ),
+            "raw": data,
+        }
+
+    @classmethod
+    def from_json(cls, data: JsonDict) -> "ItemSummary":
+        return cls(
+            **cls._item_fields(data),
+            label=data.get("label"),
+            status=data.get("status"),
+            has_video=bool(_get(data, "has_video", "hasVideo", default=False)),
+            has_audio=bool(_get(data, "has_audio", "hasAudio", default=False)),
+            has_photos=bool(_get(data, "has_photos", "hasPhotos", default=False)),
+        )
+
+    @property
+    def published_date(self) -> str | None:
+        return self.published_at
+
+    @property
+    def modified_date(self) -> str | None:
+        return self.modified_at
+
+
+@dataclass(slots=True)
+class ItemList:
+    items: list[ItemSummary]
+    links: Links
+    raw: JsonDict = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, data: JsonDict) -> "ItemList":
+        return cls(
+            items=[ItemSummary.from_json(item) for item in _dicts(data.get("items"))],
+            links=Links.from_json(data.get("links")),
+            raw=data,
+        )
+
+
+@dataclass(slots=True)
+class Video:
+    id: int | None = None
+    title: str | None = None
+    description: str | None = None
+    duration: int | None = None
+    geoprotection: bool = False
+    published_at: str | None = None
+    modified_at: str | None = None
+    image: Image | None = None
+    formats: list[JsonDict] = field(default_factory=list)
+    aspect_ratios: JsonDict | None = None
+    pre_roll: str | None = None
+    pre_rolls: JsonDict | None = None
+    related: list[ItemSummary] = field(default_factory=list)
+    system_tag: Tag | None = None
+    raw: JsonDict = field(default_factory=dict)
+
+    @classmethod
+    def from_json(cls, data: JsonDict | None) -> "Video | None":
+        if not isinstance(data, dict):
+            return None
+        return cls(
+            id=data.get("id"),
+            title=data.get("title"),
+            description=data.get("description"),
+            duration=data.get("duration"),
+            geoprotection=bool(data.get("geoprotection", False)),
+            published_at=data.get("published_at"),
+            modified_at=data.get("modified_at"),
+            image=Image.from_json(data.get("image")),
+            formats=_dicts(data.get("formats")),
+            aspect_ratios=(
+                data.get("aspect_ratios")
+                if isinstance(data.get("aspect_ratios"), dict)
+                else None
+            ),
+            pre_roll=data.get("pre_roll"),
+            pre_rolls=(
+                data.get("pre_rolls")
+                if isinstance(data.get("pre_rolls"), dict)
+                else None
+            ),
+            related=[
+                ItemSummary.from_json(item) for item in _dicts(data.get("related"))
+            ],
+            system_tag=(
+                Tag.from_json(data["system_tag"])
+                if isinstance(data.get("system_tag"), dict)
+                else None
+            ),
+            raw=data,
+        )
+
+    def best_url(self, *, width: int | None = None) -> str | None:
+        if self.formats:
+            return _best_url(self.formats, width)
+        profiles = _dicts(_dict(self.aspect_ratios).get("profiles"))
+        return profiles[0].get("url") if profiles else None
+
+
+@dataclass(slots=True)
+class Article(ItemSummary):
+    external_id: str | None = None
+    narration: str | None = None
+    automated_recommendations: bool = False
+    content: JsonDict | None = None
+    bios: list[JsonDict] = field(default_factory=list)
+    push_topics: list[JsonDict] = field(default_factory=list)
+    banners: list[JsonDict] = field(default_factory=list)
+
+    @classmethod
+    def from_json(cls, data: JsonDict) -> "Article":
+        content = data.get("content")
+        return cls(
+            **cls._item_fields(data),
+            external_id=data.get("external_id"),
+            narration=data.get("narration"),
+            automated_recommendations=bool(
+                data.get("automated_recommendations", False)
+            ),
+            content=content if isinstance(content, dict) else None,
+            bios=_dicts(data.get("bios")),
+            push_topics=_dicts(data.get("push_topics")),
+            banners=_dicts(data.get("banners")),
+        )
+
+    @property
+    def text(self) -> str:
+        return "\n\n".join(
+            text
+            for block in _walk_content(self.content)
+            if (text := _content_text(block))
+        ).strip()
+
+    @property
+    def images(self) -> list[Image]:
+        images = [self.image] if self.image else []
+        images.extend(
+            image
+            for block in _walk_content(self.content)
+            if (image := _content_image(block))
+        )
+        return images
+
+    @property
+    def videos(self) -> list[Video]:
+        return [
+            video
+            for block in _walk_content(self.content)
+            if (video := _content_video(block))
+        ]
+
+    @property
+    def links(self) -> list[SimpleNamespace]:
+        return [
+            link
+            for block in _walk_content(self.content)
+            for link in _content_links(block)
+        ]
+
+
+def _walk_content(block: JsonDict | None) -> Iterator[JsonDict]:
+    if block is None:
+        return
+    yield block
+    for child in _dicts(block.get("children")):
+        yield from _walk_content(child)
+
+
+def _content_text(block: JsonDict) -> str | None:
+    block_type = block.get("type")
+    if block_type == "text":
+        return block.get("text")
+    if block_type == "title":
+        return block.get("title")
+    if block_type == "quote":
+        return _dict(block.get("quote")).get("text")
+    if block_type == "table":
+        return "\n".join(
+            " | ".join(str(cell) for cell in row)
+            for row in _list(block.get("data"))
+            if isinstance(row, list)
+        )
+    return None
+
+
+def _content_image(block: JsonDict) -> Image | None:
+    block_type = block.get("type")
+    if block_type == "image":
+        return Image.from_json(block.get("image"))
+    if block_type == "video":
+        return Image.from_json(_dict(block.get("video")).get("image"))
+    if block_type == "external_content":
+        external = _dict(block.get("external_content")) or block
+        return Image.from_json(external.get("image"))
+    return None
+
+
+def _content_video(block: JsonDict) -> Video | None:
+    return Video.from_json(block.get("video")) if block.get("type") == "video" else None
+
+
+def _content_links(block: JsonDict) -> list[SimpleNamespace]:
+    if block.get("type") != "link_container":
+        return []
+    return [_link_view(item) for item in _dicts(block.get("children"))]
+
+
+def _link_view(data: JsonDict) -> SimpleNamespace:
+    link_type = data.get("type")
+    if link_type == "internal_link":
+        link = _dict(data.get("internal_link"))
+    elif link_type == "external_link":
+        link = _dict(data.get("external_link")) or _dict(data.get("link")) or data
+    else:
+        link = data
+    item = link.get("item")
+    return SimpleNamespace(
+        title=link.get("title"),
+        url=link.get("url"),
+        item=ItemSummary.from_json(item) if isinstance(item, dict) else None,
+        type=link_type,
+        raw=data,
+    )

nos_private_api-0.1.0/nos_private_api.egg-info/PKG-INFO

@@ -0,0 +1,142 @@
+Metadata-Version: 2.4
+Name: nos-private-api
+Version: 0.1.0
+Summary: Python client for the NOS Android app API
+Author: 11philip22
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/11philip22/nos-private-api
+Project-URL: Repository, https://github.com/11philip22/nos-private-api
+Project-URL: Issues, https://github.com/11philip22/nos-private-api/issues
+Keywords: nos,news,api,client
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx
+Dynamic: license-file
+
+<div align="center">
+
+# nos-private-api
+
+*Python client and notes for the NOS Android app API*
+
+![Python](https://img.shields.io/badge/Python->=3.10-3776ab?style=flat-square&logo=python&logoColor=white)
+![Status](https://img.shields.io/badge/status-alpha-orange?style=flat-square)
+![HTTPX](https://img.shields.io/badge/httpx-client-1f6feb?style=flat-square)
+
+[Features](#features) - [Installation](#installation) - [Usage](#usage) - [API map](#api-map)
+
+</div>
+
+`nos-private-api` is a small Python package for reading NOS app content through the same first-party endpoints used by the Android app. It includes a typed client for article feeds and item details, plus reverse-engineered API notes in [`docs/apis`](https://github.com/11philip22/nos-private-api/tree/main/docs/apis).
+
+> [!IMPORTANT]
+> This project targets an unofficial private API. Endpoints, response shapes, and header requirements can change without notice.
+
+## Features
+
+- Generate the app-style `X-NOS` header automatically.
+- Fetch paginated item feeds with category, subcategory, type, and `before` filters.
+- Fetch full article details by item ID.
+- Parse item summaries, articles, images, videos, links, tags, and categories into dataclasses.
+- Keep the original API payload available on `.raw` for fields that are not modeled yet.
+
+## Installation
+
+Install from the repository root:
+
+```bash
+python -m pip install .
+```
+
+For local development:
+
+```bash
+python -m pip install -e .
+```
+
+## Usage
+
+### List news articles
+
+```python
+from nos_private_api import NosClient
+
+client = NosClient()
+
+page = client.list_items(
+    main_categories="nieuws",
+    types="article",
+)
+
+for item in page.items:
+    print(item.id, item.title)
+```
+
+### Fetch an article
+
+```python
+article = client.get_item(page.items[0].id)
+
+print(article.title)
+print(article.published_at)
+print(article.text)
+
+for image in article.images:
+    print(image.description, image.best_url(width=800, ratio="16:9"))
+
+for video in article.videos:
+    print(video.title, video.best_url())
+
+for link in article.links:
+    print(link.title, link.url)
+```
+
+### Filter by subcategory
+
+```python
+page = client.list_items(
+    main_categories="nieuws",
+    sub_categories="politiek",
+    types="article",
+)
+```
+
+Common news subcategories include `binnenland`, `buitenland`, `cultuur-en-media`, `economie`, `koningshuis`, `opmerkelijk`, `politiek`, and `tech`.
+
+### Follow pagination
+
+```python
+page = client.list_items(main_categories="nieuws")
+
+while page.links.next:
+    page = client.list_items(url=page.links.next)
+
+    for item in page.items:
+        print(item.id, item.title)
+```
+
+## API map
+
+The [`docs/apis`](https://github.com/11philip22/nos-private-api/tree/main/docs/apis) directory documents the Android API research behind the client:
+
+| Area | Notes |
+| --- | --- |
+| [`auth.md`](https://github.com/11philip22/nos-private-api/blob/main/docs/apis/auth.md) | Timestamp endpoint and `X-NOS` header format |
+| [`nos-content.md`](https://github.com/11philip22/nos-private-api/blob/main/docs/apis/nos-content.md) | Items, pages, search, live, weather, soccer, and widget endpoints |
+| [`recommendations.md`](https://github.com/11philip22/nos-private-api/blob/main/docs/apis/recommendations.md) | Content-based and collaborative recommendation endpoints |
+| [`region-and-third-party.md`](https://github.com/11philip22/nos-private-api/blob/main/docs/apis/region-and-third-party.md) | Regional broadcaster APIs and NPO telemetry endpoints |
+
+## Development
+
+This package uses `setuptools` and depends on `httpx`.
+
+```bash
+python -m pip install -e .
+python -c "from nos_private_api import NosClient; print(NosClient.BASE_URL)"
+```

nos_private_api-0.1.0/nos_private_api.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+nos_private_api/__init__.py
+nos_private_api/client.py
+nos_private_api/types.py
+nos_private_api.egg-info/PKG-INFO
+nos_private_api.egg-info/SOURCES.txt
+nos_private_api.egg-info/dependency_links.txt
+nos_private_api.egg-info/requires.txt
+nos_private_api.egg-info/top_level.txt

nos_private_api-0.1.0/nos_private_api.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nos_private_api-0.1.0/nos_private_api.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx

nos_private_api-0.1.0/nos_private_api.egg-info/top_level.txt

@@ -0,0 +1 @@
+nos_private_api

nos_private_api-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nos-private-api"
+version = "0.1.0"
+description = "Python client for the NOS Android app API"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "11philip22" },
+]
+keywords = ["nos", "news", "api", "client"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+dependencies = ["httpx"]
+
+[project.urls]
+Homepage = "https://github.com/11philip22/nos-private-api"
+Repository = "https://github.com/11philip22/nos-private-api"
+Issues = "https://github.com/11philip22/nos-private-api/issues"
+
+[tool.setuptools]
+packages = ["nos_private_api"]

nos_private_api-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+