A TypeScript SDK for the NewsCatcher News API v3, offering full type safety, modern async/await patterns, and seamless integration with Node.js and browser environments.

Requirements

  • Node.js 14 or higher
  • TypeScript 4.5 or higher

Installation

Core features

Initialize client

import { Newscatcher } from "newscatcherapi-typescript-sdk";

const newscatcher = new Newscatcher({
  apiKey: "YOUR_API_KEY",
});

Search articles

// Regular search
const searchResults = await newscatcher.search.get({
  q: "technology",
  lang: "en",
  includeNlpData: true, // optional, adds NLP analysis layer
});

// Clustered search
const clusterResults = await newscatcher.search.get({
  q: "AI technology",
  lang: "en",
  clusteringEnabled: true,
  clusteringThreshold: 0.6,
  includeNlpData: true,
});

Latest headlines

const headlines = await newscatcher.latestHeadlines.get({
  lang: "en",
  countries: "US",
  clusteringEnabled: true,
  includeNlpData: true,
});
const authorArticles = await newscatcher.authors.get({
  authorName: "Sam Altman",
  includeNlpData: true,
});

Similar articles

const similar = await newscatcher.searchSimilar.get({
  q: "SpaceX launch",
  includeNlpData: true,
});

Sources

const sources = await newscatcher.sources.get({
  lang: "en",
});

Subscription

const subscription = await newscatcher.subscription.get();

Error handling

The SDK provides typed error handling using the NewscatcherError class:

try {
  const response = await newscatcher.search.get({
    q: "tech news",
  });
} catch (error) {
  if (error instanceof NewscatcherError) {
    console.error(`Status: ${error.status}`);
    console.error(`Message: ${error.message}`);
    console.error(`Response Body:`, error.responseBody);
  }
}

Utilities

Rate limit handler

async function withRetry<T>(
  operation: () => Promise<T>,
  maxRetries = 3,
  delay = 1000
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await operation();
    } catch (error) {
      if (
        error instanceof NewscatcherError &&
        error.status === 429 &&
        i < maxRetries - 1
      ) {
        await new Promise((resolve) =>
          setTimeout(resolve, delay * Math.pow(2, i))
        );
        continue;
      }
      throw error;
    }
  }
  throw new Error("Max retries exceeded");
}

Pagination handler

async function getAllResults(
  newscatcher: Newscatcher,
  query: string,
  maxPages = 5
) {
  const results = [];

  for (let page = 1; page <= maxPages; page++) {
    const response = await newscatcher.search.get({
      q: query,
      page,
      pageSize: 100,
    });

    const data = response.data;
    if ("clusters" in data && Array.isArray(data.clusters)) {
      data.clusters.forEach((cluster) => {
        if (cluster.articles) {
          results.push(...cluster.articles);
        }
      });
    } else if ("articles" in data) {
      results.push(...data.articles);
    }

    if (page >= data.total_pages) break;
  }

  return results;
}

Additional resources