devnet: hackernews source

src/devnet/sources/hackernews.py

@@ -0,0 +1,61 @@
+"""Hacker News via the public Algolia HN Search API. No key, no auth."""
+from __future__ import annotations
+
+from ..core import Resource, UpstreamError, get, strip_html
+
+API = "https://hn.algolia.com/api/v1/search"
+_KIND_TAGS = {"story": "story", "comment": "comment", "show_hn": "show_hn", "ask_hn": "ask_hn"}
+
+
+def search(query: str, limit: int = 20, kind: str = "all") -> dict:
+    """Search HN stories or comments. kind: all, story, comment, show_hn, ask_hn."""
+    query = (query or "").strip()
+    if not query:
+        raise UpstreamError("query is required")
+    if kind != "all" and kind not in _KIND_TAGS:
+        raise UpstreamError("kind must be all, story, comment, show_hn or ask_hn")
+    limit = max(1, min(int(limit), 50))
+
+    params: dict = {"query": query, "hitsPerPage": limit}
+    if kind != "all":
+        params["tags"] = _KIND_TAGS[kind]
+    payload = get(API, params, ttl=300)
+
+    items: list[dict] = []
+    for hit in payload.get("hits") or []:
+        object_id = hit.get("objectID")
+        url = hit.get("url") or (
+            f"https://news.ycombinator.com/item?id={object_id}" if object_id else None
+        )
+        items.append(
+            Resource(
+                id=f"hn:{object_id}",
+                type="comment" if kind == "comment" else "story",
+                source="hackernews",
+                title=hit.get("title") or hit.get("story_title") or f"HN {object_id}",
+                url=url,
+                description=strip_html(hit.get("story_text") or hit.get("comment_text")),
+                author={"name": hit.get("author")},
+                timestamps={"published_at": hit.get("created_at")},
+                metrics={"points": hit.get("points"), "comments": hit.get("num_comments")},
+                tags=[t for t in (hit.get("_tags") or []) if isinstance(t, str)][:8],
+                metadata={
+                    "object_id": object_id,
+                    "story_id": hit.get("story_id"),
+                    "kind": kind,
+                },
+                provenance={"provider": "hn_algolia"},
+            ).dict()
+        )
+
+    total = payload.get("nbHits") or len(items)
+    return {
+        "kind": "search",
+        "source": "hackernews",
+        "query": query,
+        "filter": kind,
+        "count": len(items),
+        "total_hits": total,
+        "pagination": {"has_more": len(items) < total, "next_cursor": None},
+        "items": items,
+    }