tech-news-api

tech-news-api is an installable Node.js CLI package that launches a production-ready technology news aggregation platform powered by The Guardian Content API and Hacker News Algolia.

It preserves the existing Express API, frontend, caching behavior, category matching, and article normalization while adding a reusable command-line interface.

Features

• Guardian + Hacker News aggregation
• Four canonical categories:
  • security
  • ai-software
  • mobile-devices
  • cloud-infrastructure
• Legacy category aliases:
  • cybersecurity
  • smartphones
  • networking
  • it
• Keyword scoring and exclusion rules
• Latest-first ranking with freshness prioritization
• Stale-while-revalidate caching
• Startup cache warmup
• Search endpoint
• Pagination
• Article detail endpoints
• Generated fallback thumbnails
• Rate limiting
• Centralized error handling
• Responsive frontend served from /public
• Installable CLI with init, start, doctor, and version

Installation

Global install:

npm install -g tech-news-api

Direct execution without installing globally:

npx tech-news-api

For local development in this repository:

npm install

Quick Start

Initialize a local .env file in your current working directory:

tech-news-api init

Start the server:

tech-news-api start

Or just run the default command:

tech-news-api

The CLI loads .env, validates runtime configuration, and starts the existing server.

CLI Commands

Default command

tech-news-api

Starts the server using your current directory's .env file.

Start

tech-news-api start

Starts the existing Express server without changing any API behavior.

Init

tech-news-api init

Interactive setup that asks for:

• Guardian API key
• server port
• cache TTL in minutes

It writes:

PORT=5500
GUARDIAN_API_KEY=your_guardian_api_key_here
CACHE_TTL=30

If .env already exists, the CLI asks before overwriting it.

Doctor

tech-news-api doctor

Checks:

• Node.js version
• .env presence
• Guardian API key configuration
• installed runtime dependencies
• configured port availability

Version

tech-news-api version
tech-news-api --version

Displays the installed package version.

Local Development

Start the app directly from the repository:

npm start

Development mode with nodemon:

npm run dev

Environment Variables

Required for full Guardian support:

• GUARDIAN_API_KEY

Common:

• PORT
• CACHE_TTL

Optional Open Graph and image tuning:

• OG_CACHE_TTL_SECONDS
• OG_HTTP_TIMEOUT_MS
• OG_BATCH_CONCURRENCY
• OG_USER_AGENT

API Overview

The CLI package does not change existing routes.

Category feeds

• GET /api/news/all?page=1&limit=10
• GET /api/news/security?page=1&limit=10
• GET /api/news/ai-software?page=1&limit=10
• GET /api/news/mobile-devices?page=1&limit=10
• GET /api/news/cloud-infrastructure?page=1&limit=10

Legacy aliases still work:

• GET /api/news/cybersecurity
• GET /api/news/smartphones
• GET /api/news/networking
• GET /api/news/it

Optional query params:

• page
• limit
• refresh=1
• since=<unix-ms>

Search

• GET /api/search?q=iphone&page=1&limit=10

Article details

• GET /api/article/guardian/<encoded-article-path>
• GET /api/article/hn/<hacker-news-id>

Normalized Article Shape

Every article is normalized to a consistent structure:

• articleId
• title
• description
• url
• image
• fallbackImage
• category
• source
• publishedAt
• articleBody

Project Structure

API-master/
├── bin/
│   └── tech-news-api.js
├── cache/
├── commands/
│   ├── doctor.js
│   ├── helpers.js
│   ├── init.js
│   ├── start.js
│   └── version.js
├── config/
├── controllers/
├── middleware/
├── public/
├── routes/
├── scripts/
├── services/
├── utils/
├── .env
├── .env.example
├── package.json
├── server.js
└── README.md

Notes

• The existing business logic, routes, frontend behavior, and API responses are preserved.
• The CLI uses CommonJS and is designed to work on Windows, Linux, and macOS.
• The server still supports startup cache warmup, rate limiting, responsive frontend delivery, and generated image fallbacks.