Perigon TypeScript SDK
TypeScript client for the Perigon API
Fully-typed TypeScript SDK for the Perigon API. Access news articles, AI summaries, entity data, and more with complete type safety.
- [✨ Features](#-features)
- [📦 Installation](#-installation)
- [🚀 Quick Start](#-quick-start)
- [🔑 Authentication](#-authentication)
- [📚 Endpoints](#-endpoints)
- [⚠️ Error Handling](#-error-handling)
- [🪪 License](#-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
```bash
npm install @goperigon/perigon-ts
# yarn add @goperigon/perigon-ts
# pnpm add @goperigon/perigon-ts
# bun add @goperigon/perigon-ts
```
## 🚀 Quick Start
```ts
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](https://perigon.io):
```bash
# Environment variable (recommended)
export PERIGON_API_KEY="your_api_key_here"
```
```ts
// Or pass directly
const perigon = new V1Api(
new Configuration({
apiKey: "your_api_key_here",
}),
);
```
## 📚 Endpoints
### News & Articles
```ts
const { articles, numResults } = await perigon.searchArticles({
q: "technology AND startups",
source: ["techcrunch.com"],
from: "2024-01-01",
size: 10,
});
```
- [`searchArticles`](https://dev.perigon.io/reference?endpoint=11) – Search news articles with advanced filtering by keywords, sources, dates, and more
- [`vectorSearchArticles`](https://dev.perigon.io/reference?endpoint=10) – Find semantically similar articles using AI-powered vector search
### Entities
```ts
const { results } = await perigon.searchCompanies({ name: "Apple", size: 5 });
```
- [`searchCompanies`](https://dev.perigon.io/reference?endpoint=2) – Find companies with detailed business information, financials, and metadata
- [`searchPeople`](https://dev.perigon.io/reference?endpoint=5) – Search for notable people and public figures across news and media
- [`searchJournalists`](https://dev.perigon.io/reference?endpoint=3) – Discover journalists and reporters by name, publication, or expertise
- [`getJournalistById`](https://dev.perigon.io/reference?endpoint=4) – Get comprehensive profile data for a specific journalist
### Content Discovery
```ts
const { results } = await perigon.searchStories({
q: "climate change",
size: 5,
});
```
- [`searchStories`](https://dev.perigon.io/reference?endpoint=7) – Find related article clusters and trending story threads
- [`searchTopics`](https://dev.perigon.io/reference?endpoint=9) – Browse structured topic taxonomy and content categories
- [`searchSources`](https://dev.perigon.io/reference?endpoint=6) – Discover news sources, publications, and media outlets
### AI Features
```ts
const { summary } = await perigon.searchSummarizer({
q: "renewable energy",
size: 10,
});
```
- [`searchSummarizer`](https://dev.perigon.io/reference?endpoint=8) – Generate AI-powered summaries from multiple articles on any topic
### Knowledge Base
```ts
const { results } = await perigon.searchWikipedia({
q: "machine learning",
size: 10,
});
```
- [`searchWikipedia`](https://dev.perigon.io/reference?endpoint=13) – Search Wikipedia articles with full-text matching and filtering
- [`vectorSearchWikipedia`](https://dev.perigon.io/reference?endpoint=12) – Find semantically related Wikipedia content using vector similarity
## ⚠️ Error Handling
All errors extend `ResponseError` and include `status` & `body` properties:
```ts
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