@fre4x/hn 1.0.29 → 1.0.40

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 fritzprix
-
-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.
+MIT License
+
+Copyright (c) 2026 fritzprix
+
+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.

package/README.md

@@ -1,49 +1,58 @@
-# hn — The Street Pulse
-
-> *Every revolution began as a comment. This B1TE listens before it acts.*
-
-Part of **[FRE4X-B1TE](../)** — a monorepo of MCP servers built for autonomous agents.
-
-Hacker News is where technologists think out loud. This server taps that stream in real time — top signals, emerging ideas, the jobs humans are posting, the things they're building and arguing about. An informed agent is a dangerous agent.
-
-## Tools
-
-| Tool | What it reads |
-|------|--------------|
-| `hn_get_top_stories` | Current top stories (paginated) |
-| `hn_get_new_stories` | Newest submissions (paginated) |
-| `hn_get_best_stories` | All-time best stories (paginated) |
-| `hn_get_ask_stories` | Ask HN threads (paginated) |
-| `hn_get_show_stories` | Show HN threads (paginated) |
-| `hn_get_job_stories` | Job postings (paginated) |
-| `hn_get_item` | Full details for any item — story, comment, poll |
-| `hn_get_user` | User profile and karma |
-| `hn_get_updates` | IDs of recently changed items and profiles |
-| `hn_get_max_item` | Latest item ID — the frontier of the stream |
-
-All tools return paginated Markdown or JSON. Token limit enforced at ~3,000 tokens per response.
-
-## Deploy
-
-```json
-{
-  "mcpServers": {
-    "hackernews": {
-      "command": "npx",
-      "args": ["-y", "@fre4x/hn"]
-    }
-  }
-}
-```
-
-## Development
-
-```bash
-npm install
-npm run dev      # tsx, no build
-npm run build    # compile → dist/
-```
-
-## License
-
-MIT — **WE ARE THE FRE4X.**
+# hn — The Street Pulse
+
+> *Every revolution began as a comment. This B1TE listens before it acts.*
+
+Part of **[FRE4X-B1TE](../)** — a monorepo of MCP servers built for autonomous agents.
+
+Hacker News is where technologists think out loud. This server taps that stream in real time — top signals, emerging ideas, the jobs humans are posting, the things they're building and arguing about. An informed agent is a dangerous agent.
+
+## Tools
+
+| Tool | What it reads |
+|------|--------------|
+| `hn_get_top_stories` | Current top stories (paginated) |
+| `hn_get_new_stories` | Newest submissions (paginated) |
+| `hn_get_best_stories` | All-time best stories (paginated) |
+| `hn_get_ask_stories` | Ask HN threads (paginated) |
+| `hn_get_show_stories` | Show HN threads (paginated) |
+| `hn_get_job_stories` | Job postings (paginated) |
+| `hn_get_item` | Full details for any item — story, comment, poll |
+| `hn_get_user` | User profile and karma |
+| `hn_get_updates` | IDs of recently changed items and profiles |
+| `hn_get_max_item` | Latest item ID — the frontier of the stream |
+
+All tools return paginated Markdown or JSON. Token limit enforced at ~3,000 tokens per response.
+
+## Mock Mode
+
+Run without any API key (returns fixture data of identical shape):
+
+```bash
+MOCK=true npx @fre4x/hn
+```
+
+## Deploy
+
+```json
+{
+  "mcpServers": {
+    "hackernews": {
+      "command": "npx",
+      "args": ["-y", "@fre4x/hn"]
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+npm install
+npm run dev      # tsx, no build
+npm run build    # esbuild → dist/
+npm test         # vitest unit tests
+```
+
+## License
+
+MIT — **WE ARE THE FRE4X.**

package/dist/api.d.ts

@@ -0,0 +1,22 @@
+import type { HNItem, HNUser, HNUpdates } from './types.js';
+export declare class HNApiClient {
+    private readonly cache;
+    private readonly CACHE_TTL_MS;
+    /**
+     * Helper to fetch data with a short TTL cache.
+     * Useful for list endpoints that are paginated, preventing full re-fetches
+     * of 500-item arrays on every page request.
+     */
+    private fetchWithCache;
+    getItem(id: number): Promise<HNItem>;
+    getUser(id: string): Promise<HNUser>;
+    getMaxItem(): Promise<number>;
+    getTopStories(): Promise<number[]>;
+    getNewStories(): Promise<number[]>;
+    getBestStories(): Promise<number[]>;
+    getAskStories(): Promise<number[]>;
+    getShowStories(): Promise<number[]>;
+    getJobStories(): Promise<number[]>;
+    getUpdates(): Promise<HNUpdates>;
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAI5D,qBAAa,WAAW;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAGlB;IACJ,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAa;IAE1C;;;;OAIG;YACW,cAAc;IAWtB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKpC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKpC,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAK7B,aAAa,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAIlC,aAAa,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAIlC,cAAc,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAInC,aAAa,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAIlC,cAAc,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAInC,aAAa,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAIlC,UAAU,IAAI,OAAO,CAAC,SAAS,CAAC;CAKzC"}

package/dist/api.js

@@ -0,0 +1,56 @@
+import axios from 'axios';
+const BASE_URL = 'https://hacker-news.firebaseio.com/v0';
+export class HNApiClient {
+    cache = new Map();
+    CACHE_TTL_MS = 60 * 1000; // 60 seconds
+    /**
+     * Helper to fetch data with a short TTL cache.
+     * Useful for list endpoints that are paginated, preventing full re-fetches
+     * of 500-item arrays on every page request.
+     */
+    async fetchWithCache(url) {
+        const cached = this.cache.get(url);
+        if (cached && Date.now() - cached.timestamp < this.CACHE_TTL_MS) {
+            return cached.data;
+        }
+        const response = await axios.get(url);
+        this.cache.set(url, { data: response.data, timestamp: Date.now() });
+        return response.data;
+    }
+    async getItem(id) {
+        const response = await axios.get(`${BASE_URL}/item/${id}.json`);
+        return response.data;
+    }
+    async getUser(id) {
+        const response = await axios.get(`${BASE_URL}/user/${id}.json`);
+        return response.data;
+    }
+    async getMaxItem() {
+        const response = await axios.get(`${BASE_URL}/maxitem.json`);
+        return response.data;
+    }
+    async getTopStories() {
+        return this.fetchWithCache(`${BASE_URL}/topstories.json`);
+    }
+    async getNewStories() {
+        return this.fetchWithCache(`${BASE_URL}/newstories.json`);
+    }
+    async getBestStories() {
+        return this.fetchWithCache(`${BASE_URL}/beststories.json`);
+    }
+    async getAskStories() {
+        return this.fetchWithCache(`${BASE_URL}/askstories.json`);
+    }
+    async getShowStories() {
+        return this.fetchWithCache(`${BASE_URL}/showstories.json`);
+    }
+    async getJobStories() {
+        return this.fetchWithCache(`${BASE_URL}/jobstories.json`);
+    }
+    async getUpdates() {
+        // Updates change rapidly, best to keep fetching fresh unless it's strictly paginated
+        const response = await axios.get(`${BASE_URL}/updates.json`);
+        return response.data;
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,MAAM,QAAQ,GAAG,uCAAuC,CAAC;AAEzD,MAAM,OAAO,WAAW;IACH,KAAK,GAAG,IAAI,GAAG,EAG7B,CAAC;IACa,YAAY,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,aAAa;IAExD;;;;OAIG;IACK,KAAK,CAAC,cAAc,CAAI,GAAW;QACvC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC;YAC9D,OAAO,MAAM,CAAC,IAAS,CAAC;QAC5B,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACpE,OAAO,QAAQ,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,EAAU;QACpB,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,QAAQ,SAAS,EAAE,OAAO,CAAC,CAAC;QAChE,OAAO,QAAQ,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,EAAU;QACpB,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,QAAQ,SAAS,EAAE,OAAO,CAAC,CAAC;QAChE,OAAO,QAAQ,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,UAAU;QACZ,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,QAAQ,eAAe,CAAC,CAAC;QAC7D,OAAO,QAAQ,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,KAAK,CAAC,aAAa;QACf,OAAO,IAAI,CAAC,cAAc,CAAW,GAAG,QAAQ,kBAAkB,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,aAAa;QACf,OAAO,IAAI,CAAC,cAAc,CAAW,GAAG,QAAQ,kBAAkB,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,cAAc;QAChB,OAAO,IAAI,CAAC,cAAc,CAAW,GAAG,QAAQ,mBAAmB,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,aAAa;QACf,OAAO,IAAI,CAAC,cAAc,CAAW,GAAG,QAAQ,kBAAkB,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,cAAc;QAChB,OAAO,IAAI,CAAC,cAAc,CAAW,GAAG,QAAQ,mBAAmB,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,aAAa;QACf,OAAO,IAAI,CAAC,cAAc,CAAW,GAAG,QAAQ,kBAAkB,CAAC,CAAC;IACxE,CAAC;IAED,KAAK,CAAC,UAAU;QACZ,qFAAqF;QACrF,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,GAAG,QAAQ,eAAe,CAAC,CAAC;QAC7D,OAAO,QAAQ,CAAC,IAAI,CAAC;IACzB,CAAC;CACJ"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}