@goperigon/perigon-ts

Perigon TypeScript SDK

TypeScript client for the Perigon API

A fully-typed, promise-based SDK generated from the official Perigon OpenAPI specification. Works in Node.js, modern browsers, Cloudflare Workers, and Deno.

Table of Contents

• ✨ Features
• 📦 Installation
• 🚀 Quick start
• 🧑‍💻 Endpoint snippets
• 🧪 Running integration tests
• 🤝 Contributing
• 🪪 License

✨ Features

• Type-safe request/response models (goodbye any)
• Ships as both ESM & CommonJS with sourcemaps
• Zero-dependency core – bring your own fetch if needed
• Generated directly from docs.perigon.io, so it’s always in sync
• Runs in Node, browsers, Deno, and edge runtimes

📦 Installation

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

🚀 Quick start

1. Export your API key

# .env
PERIGON_API_KEY=your_key_here

2. Instantiate the client

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

const perigon = new V1Api(
  new Configuration({
    apiKey: process.env.PERIGON_API_KEY!, // or () => 'your_key'
    // basePath: 'https://api.perigon.io',      // override for proxy / dev
  }),
);

3. Make calls

// 🔍 Search recent news articles
const { articles, numResults } = await perigon.searchArticles({
  q: "artificial intelligence",
  size: 5,
});
console.log(numResults, articles[0].title);

// 👤 Look up a journalist by ID
const journalist = await perigon.getJournalistById({ id: "123456" });
console.log(journalist.name);

All SDK methods return typed promises with full IntelliSense support.

🧑‍💻 Endpoint snippets

Articles – search and filter news (/v1/all)

Docs → https://docs.perigon.io/docs/overview

const { articles } = await perigon.searchArticles({
  q: "technology",
  size: 5,
});

Articles – date range filter

Docs → https://docs.perigon.io/docs/overview

await perigon.searchArticles({
  q: "business",
  from: "2025-04-01",
  to: "2025-04-08",
});

Articles – restrict to a source

Docs → https://docs.perigon.io/docs/overview

await perigon.searchArticles({ source: ["nytimes.com"] });

Companies – fetch structured company data (/v1/companies)

Docs → https://docs.perigon.io/docs/company-data

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

Journalists – search and detail look‑up (/v1/journalists)

Docs → https://docs.perigon.io/docs/journalist-data

const { results } = await perigon.searchJournalists1({
  name: "Kevin",
  size: 1,
});
const journalist = await perigon.getJournalistById({ id: results[0].id });

Stories – discover related article clusters (/v1/stories)

Docs → https://docs.perigon.io/docs/stories-overview

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

Vector search – semantic retrieval (/v1/vector)

Docs → https://docs.perigon.io/docs/vector-endpoint

await perigon.vectorSearchArticles({
  articleSearchParams: {
    prompt: "Latest advancements in artificial intelligence",
    size: 5,
  },
});

Summarizer – generate an instant summary (/v1/summarizer)

Docs → https://docs.perigon.io/docs/search-summarizer

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

Topics – explore taxonomy (/v1/topics)

Docs → https://docs.perigon.io/docs/topics

await perigon.searchTopics({ size: 10 });

Action	Code Example
Filter by source	await perigon.searchArticles({ source: ['nytimes.com'] })
Limit by date range	await perigon.searchArticles({ q: 'business', from: '2025‑04‑01', to: '2025‑04‑08' })
Company lookup	await perigon.searchCompanies({ name: 'Apple', size: 5 })
Summarize any query	await perigon.searchSummarizer({ q: 'renewable energy', size: 20 })
Semantic / vector search	await perigon.vectorSearchArticles({ articleSearchParams: { prompt: 'advancements in AI', size: 5 }})
Retrieve available taxonomic topics	await perigon.searchTopics({ size: 10 })

🧪 Running integration tests

The repository ships with Jest tests that hit the live API.

# 1. export your key
echo "PERIGON_API_KEY=..." > .env

# 2. run the suite (15–30 s)
npm test

Set PERIGON_API_KEY in your CI to keep tests green.

🤝 Contributing

• pnpm install
• Make your changes
• Run pnpm test
• Open a pull request – happy to review!

🪪 License

MIT © Perigon