Skip to main content

fetchium_core/social/
hackernews.rs

1//! HackerNews intelligence via the official Firebase API + Algolia search.
2//!
3//! 100% free, no API key, very fast (~10-50ms per request).
4//!
5//! ## Endpoints
6//! - Firebase: `https://hacker-news.firebaseio.com/v0/`
7//! - Algolia: `https://hn.algolia.com/api/v1/search?query=...`
8
9use crate::error::{FetchiumError, FetchiumResult};
10use crate::http::client::HttpClient;
11use crate::social::types::{score_sentiment, EngagementMetrics, SocialPlatform, SocialPost};
12use serde::{Deserialize, Serialize};
13use serde_json::Value;
14use std::time::Duration;
15
16/// A HackerNews story.
17#[derive(Debug, Clone, Serialize, Deserialize)]
18pub struct HnStory {
19    pub id: u64,
20    pub title: String,
21    pub url: Option<String>,
22    pub author: String,
23    pub score: u64,
24    pub descendants: u64, // comment count
25    pub published: u64,   // unix timestamp
26    pub story_type: HnStoryType,
27}
28
29/// HN story type.
30#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
31#[serde(rename_all = "snake_case")]
32pub enum HnStoryType {
33    #[default]
34    Story,
35    Ask,
36    Show,
37    Job,
38}
39
40/// A HN comment.
41#[derive(Debug, Clone, Serialize, Deserialize)]
42pub struct HnComment {
43    pub id: u64,
44    pub author: String,
45    pub text: String,
46    pub score: Option<i64>,
47    pub children: Vec<HnComment>,
48}
49
50/// Search HN via Algolia (fastest, full-text).
51pub async fn search_stories(
52    query: &str,
53    max: usize,
54    http: &HttpClient,
55    timeout_secs: u64,
56) -> FetchiumResult<Vec<HnStory>> {
57    let encoded: String = url::form_urlencoded::byte_serialize(query.as_bytes()).collect();
58    // Sort by relevance, only stories
59    let url = format!(
60        "https://hn.algolia.com/api/v1/search?query={encoded}&tags=story&hitsPerPage={max}"
61    );
62
63    let body = tokio::time::timeout(Duration::from_secs(timeout_secs), http.fetch_text(&url))
64        .await
65        .map_err(|_| FetchiumError::Internal("Request timeout".into()))?
66        .map_err(|e| FetchiumError::Search(e.to_string()))?;
67
68    let v: Value = serde_json::from_str(&body)
69        .map_err(|e| FetchiumError::Internal(format!("HN Algolia JSON: {e}")))?;
70
71    let hits = match v["hits"].as_array() {
72        Some(h) => h,
73        None => return Ok(Vec::new()),
74    };
75
76    Ok(hits
77        .iter()
78        .filter_map(|h| {
79            let title = h["title"].as_str()?.to_string();
80            let id = h["objectID"].as_str()?.parse::<u64>().ok()?;
81            Some(HnStory {
82                id,
83                title,
84                url: h["url"].as_str().map(|s| s.to_string()),
85                author: h["author"].as_str().unwrap_or("").to_string(),
86                score: h["points"].as_u64().unwrap_or(0),
87                descendants: h["num_comments"].as_u64().unwrap_or(0),
88                published: h["created_at_i"].as_u64().unwrap_or(0),
89                story_type: HnStoryType::Story,
90            })
91        })
92        .collect())
93}
94
95/// Fetch top/new/best/ask/show stories by category.
96pub async fn fetch_category(
97    category: HnCategory,
98    max: usize,
99    http: &HttpClient,
100    timeout_secs: u64,
101) -> FetchiumResult<Vec<HnStory>> {
102    let cat_str = category.as_str();
103    let url = format!("https://hacker-news.firebaseio.com/v0/{cat_str}.json");
104
105    let body = tokio::time::timeout(Duration::from_secs(timeout_secs), http.fetch_text(&url))
106        .await
107        .map_err(|_| FetchiumError::Internal("Request timeout".into()))?
108        .map_err(|e| FetchiumError::Search(e.to_string()))?;
109
110    let ids: Vec<u64> =
111        serde_json::from_str(&body).map_err(|e| FetchiumError::Internal(format!("HN IDs: {e}")))?;
112
113    // Fetch top `max` items in parallel
114    let ids = ids.into_iter().take(max).collect::<Vec<_>>();
115    let mut handles = Vec::with_capacity(ids.len());
116    for id in ids {
117        let http2 = http.clone();
118        let to = timeout_secs;
119        handles.push(tokio::spawn(
120            async move { fetch_item(id, &http2, to).await },
121        ));
122    }
123
124    let mut stories = Vec::new();
125    for h in handles {
126        if let Ok(Ok(story)) = h.await {
127            stories.push(story);
128        }
129    }
130    Ok(stories)
131}
132
133/// HN story category.
134#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
135#[serde(rename_all = "snake_case")]
136pub enum HnCategory {
137    Top,
138    New,
139    Best,
140    Ask,
141    Show,
142    Job,
143}
144
145impl HnCategory {
146    fn as_str(self) -> &'static str {
147        match self {
148            Self::Top => "topstories",
149            Self::New => "newstories",
150            Self::Best => "beststories",
151            Self::Ask => "askstories",
152            Self::Show => "showstories",
153            Self::Job => "jobstories",
154        }
155    }
156}
157
158/// Fetch a single HN item by ID.
159pub async fn fetch_item(id: u64, http: &HttpClient, timeout_secs: u64) -> FetchiumResult<HnStory> {
160    let url = format!("https://hacker-news.firebaseio.com/v0/item/{id}.json");
161    let body = tokio::time::timeout(Duration::from_secs(timeout_secs), http.fetch_text(&url))
162        .await
163        .map_err(|_| FetchiumError::Internal("Request timeout".into()))?
164        .map_err(|e| FetchiumError::Search(e.to_string()))?;
165
166    let v: Value = serde_json::from_str(&body)
167        .map_err(|e| FetchiumError::Internal(format!("HN item {id}: {e}")))?;
168
169    let story_type = match v["type"].as_str() {
170        Some("ask") => HnStoryType::Ask,
171        Some("show") => HnStoryType::Show,
172        Some("job") => HnStoryType::Job,
173        _ => HnStoryType::Story,
174    };
175
176    Ok(HnStory {
177        id,
178        title: v["title"].as_str().unwrap_or("").to_string(),
179        url: v["url"].as_str().map(|s| s.to_string()),
180        author: v["by"].as_str().unwrap_or("").to_string(),
181        score: v["score"].as_u64().unwrap_or(0),
182        descendants: v["descendants"].as_u64().unwrap_or(0),
183        published: v["time"].as_u64().unwrap_or(0),
184        story_type,
185    })
186}
187
188/// Convert HN story to normalised SocialPost.
189pub fn to_social_post(story: &HnStory) -> SocialPost {
190    let content = format!(
191        "{} — {} points, {} comments",
192        story.title, story.score, story.descendants
193    );
194    let sentiment = score_sentiment(&story.title);
195    let mut engagement = EngagementMetrics {
196        likes: story.score,
197        shares: 0,
198        comments: story.descendants,
199        views: None,
200        score: 0.0,
201    };
202    engagement.compute_score();
203
204    SocialPost {
205        platform: SocialPlatform::HackerNews,
206        id: story.id.to_string(),
207        url: story
208            .url
209            .clone()
210            .unwrap_or_else(|| format!("https://news.ycombinator.com/item?id={}", story.id)),
211        author: story.author.clone(),
212        content,
213        published: story.published.to_string(),
214        engagement,
215        media: Vec::new(),
216        hashtags: Vec::new(),
217        mentions: Vec::new(),
218        sentiment,
219        authenticity: 0.9, // HN has strong moderation
220    }
221}
222
223#[cfg(test)]
224mod tests {
225    use super::*;
226
227    #[test]
228    fn hn_category_strings() {
229        assert_eq!(HnCategory::Top.as_str(), "topstories");
230        assert_eq!(HnCategory::Ask.as_str(), "askstories");
231    }
232
233    #[test]
234    fn to_social_post_basic() {
235        let story = HnStory {
236            id: 12345,
237            title: "Amazing new Rust framework".into(),
238            url: Some("https://example.com".into()),
239            author: "rustacean".into(),
240            score: 500,
241            descendants: 120,
242            published: 1700000000,
243            story_type: HnStoryType::Story,
244        };
245        let post = to_social_post(&story);
246        assert_eq!(post.platform, SocialPlatform::HackerNews);
247        assert!(post.content.contains("500 points"));
248    }
249
250    #[test]
251    fn to_social_post_no_url_fallback() {
252        let story = HnStory {
253            id: 99999,
254            title: "Ask HN: Favourite tool?".into(),
255            url: None,
256            author: "curious".into(),
257            score: 300,
258            descendants: 80,
259            published: 1700001000,
260            story_type: HnStoryType::Ask,
261        };
262        let post = to_social_post(&story);
263        assert!(
264            post.url.contains("news.ycombinator.com"),
265            "fallback should point to YC: {}",
266            post.url
267        );
268        assert!(post.url.contains("99999"));
269    }
270
271    #[test]
272    fn to_social_post_engagement_computed() {
273        let story = HnStory {
274            id: 1,
275            title: "Great story".into(),
276            url: Some("https://example.com".into()),
277            author: "user".into(),
278            score: 1000,
279            descendants: 300,
280            published: 1700000000,
281            story_type: HnStoryType::Story,
282        };
283        let post = to_social_post(&story);
284        assert!(post.engagement.score > 0.0);
285    }
286
287    #[test]
288    fn to_social_post_authenticity_high() {
289        let story = HnStory {
290            id: 2,
291            title: "HN has moderation".into(),
292            url: None,
293            author: "mod".into(),
294            score: 50,
295            descendants: 10,
296            published: 0,
297            story_type: HnStoryType::Story,
298        };
299        let post = to_social_post(&story);
300        assert!(post.authenticity >= 0.8, "HN authenticity should be high");
301    }
302
303    #[test]
304    fn hn_story_type_default_is_story() {
305        assert_eq!(HnStoryType::default(), HnStoryType::Story);
306    }
307
308    #[test]
309    fn hn_category_all_str_variants() {
310        assert_eq!(HnCategory::Top.as_str(), "topstories");
311        assert_eq!(HnCategory::New.as_str(), "newstories");
312        assert_eq!(HnCategory::Best.as_str(), "beststories");
313        assert_eq!(HnCategory::Ask.as_str(), "askstories");
314        assert_eq!(HnCategory::Show.as_str(), "showstories");
315        assert_eq!(HnCategory::Job.as_str(), "jobstories");
316    }
317}