@goperigon/perigon-ts/README.md

Typescript client for Perigon API

<!-- ----------  Header  ---------- -->
<p align="center">
  <img src="https://perigon.io/favicon.ico" width="120" alt="Perigon logo" />
</p>

<h1 align="center">Perigon&nbsp;TypeScript&nbsp;SDK</h1>
<p align="center">TypeScript client for the <strong>Perigon&nbsp;API</strong></p>

<!-- ----------  Badges  ---------- -->
<p align="center">
  <!-- npm -->
  <a href="https://www.npmjs.com/package/@goperigon/perigon-ts">
    <img src="https://img.shields.io/npm/v/@goperigon/perigon-ts?style=for-the-badge" alt="npm version">
  </a>
  <!-- tests -->
  <a href="https://github.com/goperigon/perigon-ts/actions/workflows/test.yml">
    <img src="https://img.shields.io/github/actions/workflow/status/goperigon/perigon-ts/test.yml?label=tests%20%E2%9C%85&style=for-the-badge" alt="tests status">
  </a>
  <!-- docs -->
  <a href="https://docs.perigon.io">
    <img src="https://img.shields.io/badge/docs-perigon.io-informational?style=for-the-badge&logo=readthedocs" alt="documentation">
  </a>
  <!-- license -->
  <a href="LICENSE">
    <img src="https://img.shields.io/github/license/goperigon/perigon-ts?style=for-the-badge" alt="license">
  </a>
</p>

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

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

- [✨ Features](#-features)
- [📦 Installation](#-installation)
- [🚀 Quick Start](#-quick-start)
- [🔑 Authentication](#-authentication)
- [📚 Endpoints](#-endpoints)
- [⚠️ Error Handling](#-error-handling)
- [🪪 License](#-license)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## ✨ 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