README.md

NewsAPI Client

NewsAPI Client is a TypeScript-based client for interacting with the NewsAPI service. It simplifies fetching news articles, top headlines, and news sources while handling API errors gracefully.

Features

• Configurable with an API key for authentication.
• Fetch top headlines using /v2/top-headlines.
• Search for articles across millions of sources with /v2/everything.
• Retrieve available news sources using /v2/top-headlines/sources.
• Fully typed responses for enhanced developer experience.
• Robust error handling for API and network issues.

Installation

This package is hosted on the GitHub Package Registry. To install it, ensure you have the following prerequisites:

Prerequisites

1. Node.js: v20 or higher
2. NPM: v10 or higher
3. Create a .npmrc file in the root directory of your app, then add the following

@owner=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GH_TOKEN}

Optional

Login from the terminal with the below command.

Authenticate to GitHub by running:

    npm login --scope=@<your-github-username> --auth-type=legacy --registry=https://npm.pkg.github.com

Note

Use your GitHub credentials (or a personal access token with the read:packages scope) for login.

To install the package, run:

    npm install @josh-uvi/newsapi-client

Usage

1. Import the Client:

import { NewsAPIClient } from "@josh-uvi/newsapi-client";

2. Provide Your API Key: You can pass your NewsAPI key via the constructor:

const client = new NewsAPIClient("<YOUR_NEWSAPI_KEY>");

Example Usage in Real Applications

import { NewsAPIClient } from "@josh-uvi/newsapi-client";

(async () => {
  const client = new NewsAPIClient("<YOUR_NEWSAPI_KEY>");
  try {
    const headlines = await client.getTopHeadlines({ country: "us" });
    console.log("Top Headlines:", headlines.articles);
  } catch (error) {
    if (error.response) {
      // API responded with a status code outside 2xx range
      console.error("API Error:", error.response.data);
    } else {
      // Network or other error
      console.error("Error:", error.message);
    }
  }
})();

Fetching Top Headlines

To get the latest top headlines:

const headlines = await client.getTopHeadlines({ country: "us" });
console.log(headlines.articles);

Parameters

Parameter	Type	Description
country	string	Filter by country (e.g., us, uk).
category	string	Filter by category (e.g., sports).
sources	string	Filter by source IDs.

Searching Everything

To search across all articles:

const everything = await client.getEverything({ q: "technology" });
console.log(everything.articles);

Parameters

Parameter	Type	Description
q	string	Search keywords or phrases.
from	string	Start date for the search (YYYY-MM-DD).
to	string	End date for the search (YYYY-MM-DD).
language	string	Language of the articles (e.g., en).

Fetching Sources

To fetch available news sources:

const sources = await client.getSources();
console.log(sources.sources);

Parameters

Parameter	Type	Description
category	string	Filter by category (e.g., sports).
language	string	Language of the sources (e.g., en).
country	string	Country of the sources (e.g., us).

Testing

The package contains Jest tests for all functions, utilizing Jest's mocking capabilities to simulate API calls without interacting with the actual NewsAPI service.

To execute the tests:

    npm run test

Update Package

It is essential to follow the steps below in the specified order to initiate a new release of the package. The following command will update or increment the version number in the package.json and package-lock.json files.

1. Bump the package version with this command:

    npm run bumpVersion

2. Add git changes

    git add -A

3. Commit changes:

    git commit -s -m "Add new changes"

4. Push changes:

    git push