Fully-typed TypeScript SDK for the Perigon API. Access news articles, AI summaries, entity data, and more with complete type safety.

• ✨ Features
• 📦 Installation
• 🚀 Quick Start
• 🔑 Authentication
• 📚 Endpoints
• ⚠️ Error Handling
• 🪪 License

✨ Features

• Type-safe – Full TypeScript support with IntelliSense
• Universal – Works in Node.js, browsers, Deno, and edge runtimes
• Zero dependencies – Lightweight core, bring your own fetch
• Auto-generated – Always in sync with the latest API

📦 Installation

npm install @goperigon/perigon-ts
# yarn add @goperigon/perigon-ts
# pnpm add @goperigon/perigon-ts
# bun add @goperigon/perigon-ts

🚀 Quick Start

import { Configuration, V1Api } from "@goperigon/perigon-ts";

const perigon = new V1Api(
  new Configuration({
    apiKey: process.env.PERIGON_API_KEY,
  }),
);

try {
  const { articles } = await perigon.searchArticles({
    q: "artificial intelligence",
    size: 5,
  });
  console.log(`Found ${articles.length} articles`);
} catch (error) {
  console.error("API Error:", error.message);
}

🔑 Authentication

Get your API key from perigon.io:

# Environment variable (recommended)
export PERIGON_API_KEY="your_api_key_here"

// Or pass directly
const perigon = new V1Api(
  new Configuration({
    apiKey: "your_api_key_here",
  }),
);

📚 Endpoints

News & Articles

const { articles, numResults } = await perigon.searchArticles({
  q: "technology AND startups",
  source: ["techcrunch.com"],
  from: "2024-01-01",
  size: 10,
});

• searchArticles – Search news articles with advanced filtering by keywords, sources, dates, and more
• vectorSearchArticles – Find semantically similar articles using AI-powered vector search

Entities

const { results } = await perigon.searchCompanies({ name: "Apple", size: 5 });

• searchCompanies – Find companies with detailed business information, financials, and metadata
• searchPeople – Search for notable people and public figures across news and media
• searchJournalists – Discover journalists and reporters by name, publication, or expertise
• getJournalistById – Get comprehensive profile data for a specific journalist

Content Discovery

const { results } = await perigon.searchStories({
  q: "climate change",
  size: 5,
});

• searchStories – Find related article clusters and trending story threads
• searchTopics – Browse structured topic taxonomy and content categories
• searchSources – Discover news sources, publications, and media outlets

AI Features

const { summary } = await perigon.searchSummarizer({
  q: "renewable energy",
  size: 10,
});

• searchSummarizer – Generate AI-powered summaries from multiple articles on any topic

Knowledge Base

const { results } = await perigon.searchWikipedia({
  q: "machine learning",
  size: 10,
});

• searchWikipedia – Search Wikipedia articles with full-text matching and filtering
• vectorSearchWikipedia – Find semantically related Wikipedia content using vector similarity

⚠️ Error Handling

All errors extend ResponseError and include status & body properties:

try {
  const result = await perigon.searchArticles({ q: "test" });
} catch (error) {
  if (error.status === 401) console.error("Invalid API key");
  else if (error.status === 429) console.error("Rate limit exceeded");
  else console.error("API Error:", error.message);
}

🪪 License

MIT © Perigon