@goperigon/perigon-ts 1.1.2 β†’ 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +74 -136
  2. package/dist/index.cjs +2 -2
  3. package/dist/index.d.ts +3833 -6636
  4. package/dist/index.js +2 -2
  5. package/package.json +9 -4
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  <!-- ---------- Header ---------- -->
2
2
  <p align="center">
3
- <img src="https://goperigon.com/favicon.ico" width="120" alt="Perigon logo" />
3
+ <img src="https://perigon.io/favicon.ico" width="120" alt="Perigon logo" />
4
4
  </p>
5
5
 
6
6
  <h1 align="center">Perigon&nbsp;TypeScript&nbsp;SDK</h1>
@@ -26,32 +26,27 @@
26
26
  </a>
27
27
  </p>
28
28
 
29
- A fully-typed, promise-based SDK generated from the official Perigon OpenAPI specification. Works in Node.js, modern browsers, Cloudflare Workers, and Deno.
30
-
31
- ## Table&nbsp;of&nbsp;Contents
29
+ Fully-typed TypeScript SDK for the Perigon API. Access news articles, AI summaries, entity data, and more with complete type safety.
32
30
 
33
31
  <!-- START doctoc generated TOC please keep comment here to allow auto update -->
34
32
  <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
35
33
 
36
34
  - [✨ Features](#-features)
37
35
  - [πŸ“¦ Installation](#-installation)
38
- - [πŸš€ Quick start](#-quick-start)
39
- - [πŸ§‘β€πŸ’» Endpoint snippets](#-endpoint-snippets)
36
+ - [πŸš€ Quick Start](#-quick-start)
37
+ - [πŸ”‘ Authentication](#-authentication)
38
+ - [πŸ“š Endpoints](#-endpoints)
39
+ - [⚠️ Error Handling](#-error-handling)
40
40
  - [πŸͺͺ License](#-license)
41
41
 
42
42
  <!-- END doctoc generated TOC please keep comment here to allow auto update -->
43
43
 
44
- ---
45
-
46
44
  ## ✨ Features
47
45
 
48
- - **Type-safe** request/response models (goodbye `any`)
49
- - Ships as both **ESM & CommonJS** with sourcemaps
50
- - **Zero-dependency core** – bring your own `fetch` if needed
51
- - Generated directly from [docs.perigon.io](https://docs.perigon.io), so it’s always in sync
52
- - Runs in **Node, browsers, Deno, and edge runtimes**
53
-
54
- ---
46
+ - **Type-safe** – Full TypeScript support with IntelliSense
47
+ - **Universal** – Works in Node.js, browsers, Deno, and edge runtimes
48
+ - **Zero dependencies** – Lightweight core, bring your own fetch
49
+ - **Auto-generated** – Always in sync with the latest API
55
50
 
56
51
  ## πŸ“¦ Installation
57
52
 
@@ -59,182 +54,125 @@ A fully-typed, promise-based SDK generated from the official Perigon OpenAPI spe
59
54
  npm install @goperigon/perigon-ts
60
55
  # yarn add @goperigon/perigon-ts
61
56
  # pnpm add @goperigon/perigon-ts
57
+ # bun add @goperigon/perigon-ts
62
58
  ```
63
59
 
64
- ---
65
-
66
- ## πŸš€ Quick start
67
-
68
- ### 1. Instantiate the client
60
+ ## πŸš€ Quick Start
69
61
 
70
62
  ```ts
71
63
  import { Configuration, V1Api } from "@goperigon/perigon-ts";
72
64
 
73
65
  const perigon = new V1Api(
74
66
  new Configuration({
75
- apiKey: "YOUR_API_KEY", // or () => 'your_key'
76
- // basePath: 'https://api.perigon.io', // override for proxy / dev
67
+ apiKey: process.env.PERIGON_API_KEY,
77
68
  }),
78
69
  );
79
- ```
80
-
81
- ### 2. Make calls
82
-
83
- ```ts
84
- // πŸ” Search recent news articles
85
- const { articles, numResults } = await perigon.searchArticles({
86
- q: "artificial intelligence",
87
- size: 5,
88
- });
89
- console.log(numResults, articles[0].title);
90
-
91
- // πŸ‘€ Look up a journalist by ID
92
- const journalist = await perigon.getJournalistById({ id: "123456" });
93
- console.log(journalist.name);
94
- ```
95
-
96
- > All SDK methods return **typed promises** with full IntelliSense support.
97
70
 
98
- ---
99
-
100
- ## πŸ§‘β€πŸ’» Endpoint snippets
101
-
102
- ### Articles – search and filter news (`/v1/all`)<br>
103
-
104
- **Docs β†’** <https://dev.perigon.io/reference?endpoint=11>
105
-
106
- ```ts
107
- const { articles } = await perigon.searchArticles({
108
- q: "technology",
109
- size: 5,
110
- });
111
- ```
112
-
113
- ### Articles – date range filter<br>
114
-
115
- **Docs β†’** <https://dev.perigon.io/reference?endpoint=11>
116
-
117
- ```ts
118
- await perigon.searchArticles({
119
- q: "business",
120
- from: "2025-04-01",
121
- to: "2025-04-08",
122
- });
71
+ try {
72
+ const { articles } = await perigon.searchArticles({
73
+ q: "artificial intelligence",
74
+ size: 5,
75
+ });
76
+ console.log(`Found ${articles.length} articles`);
77
+ } catch (error) {
78
+ console.error("API Error:", error.message);
79
+ }
123
80
  ```
124
81
 
125
- ### Articles – restrict to a source<br>
82
+ ## πŸ”‘ Authentication
126
83
 
127
- **Docs β†’** <https://dev.perigon.io/reference?endpoint=11>
84
+ Get your API key from [perigon.io](https://perigon.io):
128
85
 
129
- ```ts
130
- await perigon.searchArticles({ source: ["nytimes.com"] });
86
+ ```bash
87
+ # Environment variable (recommended)
88
+ export PERIGON_API_KEY="your_api_key_here"
131
89
  ```
132
90
 
133
- ### Companies – fetch structured company data (`/v1/companies`)<br>
134
-
135
- **Docs β†’** <https://dev.perigon.io/reference?endpoint=2>
136
-
137
91
  ```ts
138
- const { results } = await perigon.searchCompanies({
139
- name: "Apple",
140
- size: 5,
141
- });
92
+ // Or pass directly
93
+ const perigon = new V1Api(
94
+ new Configuration({
95
+ apiKey: "your_api_key_here",
96
+ }),
97
+ );
142
98
  ```
143
99
 
144
- ### Journalists – search and detail look‑up (`/v1/journalists`)<br>
100
+ ## πŸ“š Endpoints
145
101
 
146
- **Docs β†’** <https://dev.perigon.io/reference?endpoint=2>
102
+ ### News & Articles
147
103
 
148
104
  ```ts
149
- const { results } = await perigon.searchJournalists1({
150
- name: "Kevin",
151
- size: 1,
105
+ const { articles, numResults } = await perigon.searchArticles({
106
+ q: "technology AND startups",
107
+ source: ["techcrunch.com"],
108
+ from: "2024-01-01",
109
+ size: 10,
152
110
  });
153
- const journalist = await perigon.getJournalistById({ id: results[0].id });
154
111
  ```
155
112
 
156
- ### Stories – discover related article clusters (`/v1/stories`)<br>
113
+ - [`searchArticles`](https://dev.perigon.io/reference?endpoint=11) – Search news articles with advanced filtering by keywords, sources, dates, and more
114
+ - [`vectorSearchArticles`](https://dev.perigon.io/reference?endpoint=10) – Find semantically similar articles using AI-powered vector search
157
115
 
158
- **Docs β†’** <https://dev.perigon.io/reference?endpoint=7>
116
+ ### Entities
159
117
 
160
118
  ```ts
161
- await perigon.searchStories({ q: "climate change", size: 5 });
119
+ const { results } = await perigon.searchCompanies({ name: "Apple", size: 5 });
162
120
  ```
163
121
 
164
- ### Wikipedia – search Wikipedia pages (`/v1/wikipedia`)<br>
122
+ - [`searchCompanies`](https://dev.perigon.io/reference?endpoint=2) – Find companies with detailed business information, financials, and metadata
123
+ - [`searchPeople`](https://dev.perigon.io/reference?endpoint=5) – Search for notable people and public figures across news and media
124
+ - [`searchJournalists`](https://dev.perigon.io/reference?endpoint=3) – Discover journalists and reporters by name, publication, or expertise
125
+ - [`getJournalistById`](https://dev.perigon.io/reference?endpoint=4) – Get comprehensive profile data for a specific journalist
165
126
 
166
- **Docs β†’** <https://dev.perigon.io/reference?endpoint=13>
127
+ ### Content Discovery
167
128
 
168
129
  ```ts
169
- const { pages } = await perigon.searchWikipedia({
170
- q: "artificial intelligence",
130
+ const { results } = await perigon.searchStories({
131
+ q: "climate change",
171
132
  size: 5,
172
133
  });
173
134
  ```
174
135
 
175
- ### Vector search – semantic retrieval (`/v1/vector`)<br>
136
+ - [`searchStories`](https://dev.perigon.io/reference?endpoint=7) – Find related article clusters and trending story threads
137
+ - [`searchTopics`](https://dev.perigon.io/reference?endpoint=9) – Browse structured topic taxonomy and content categories
138
+ - [`searchSources`](https://dev.perigon.io/reference?endpoint=6) – Discover news sources, publications, and media outlets
176
139
 
177
- **Docs β†’** <https://dev.perigon.io/reference?endpoint=10>
178
-
179
- ```ts
180
- await perigon.vectorSearchArticles({
181
- articleSearchParams: {
182
- prompt: "Latest advancements in artificial intelligence",
183
- size: 5,
184
- },
185
- });
186
- ```
187
-
188
- ### Wikipedia vector search – semantic Wikipedia retrieval (`/v1/vector/wikipedia`)<br>
189
-
190
- **Docs β†’** <https://dev.perigon.io/reference?endpoint=12>
191
-
192
- ```ts
193
- await perigon.vectorSearchWikipedia({
194
- wikipediaSearchParams: {
195
- prompt: "quantum computing breakthroughs",
196
- size: 5,
197
- },
198
- });
199
- ```
200
-
201
- ### Summarizer – generate an instant summary (`/v1/summarizer`)<br>
202
-
203
- **Docs β†’** <https://dev.perigon.io/reference?endpoint=8>
140
+ ### AI Features
204
141
 
205
142
  ```ts
206
143
  const { summary } = await perigon.searchSummarizer({
207
144
  q: "renewable energy",
208
145
  size: 10,
209
146
  });
210
- console.log(summary);
211
147
  ```
212
148
 
213
- ### Topics – explore taxonomy (`/v1/topics`)<br>
149
+ - [`searchSummarizer`](https://dev.perigon.io/reference?endpoint=8) – Generate AI-powered summaries from multiple articles on any topic
214
150
 
215
- **Docs β†’** <https://dev.perigon.io/reference?endpoint=9>
151
+ ### Knowledge Base
216
152
 
217
153
  ```ts
218
- await perigon.searchTopics({ size: 10 });
154
+ const { results } = await perigon.searchWikipedia({
155
+ q: "machine learning",
156
+ size: 10,
157
+ });
219
158
  ```
220
159
 
221
- | Action | Code Example |
222
- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
223
- | Filter by source | `await perigon.searchArticles({ source: ['nytimes.com'] })` |
224
- | Limit by date range | `await perigon.searchArticles({ q: 'business', from: '2025‑04‑01', to: '2025‑04‑08' })` |
225
- | Company lookup | `await perigon.searchCompanies({ name: 'Apple', size: 5 })` |
226
- | Wikipedia page search | `await perigon.searchWikipedia({ q: 'machine learning', size: 5 })` |
227
- | Summarize any query | `await perigon.searchSummarizer({ q: 'renewable energy', size: 20 })` |
228
- | Semantic / vector search | `await perigon.vectorSearchArticles({ articleSearchParams: { prompt: 'advancements in AI', size: 5 }})` |
229
- | Wikipedia semantic search | `await perigon.vectorSearchWikipedia({ wikipediaSearchParams: { prompt: 'quantum physics', size: 5 }})` |
230
- | Retrieve available taxonomic **topics** | `await perigon.searchTopics({ size: 10 })` |
160
+ - [`searchWikipedia`](https://dev.perigon.io/reference?endpoint=13) – Search Wikipedia articles with full-text matching and filtering
161
+ - [`vectorSearchWikipedia`](https://dev.perigon.io/reference?endpoint=12) – Find semantically related Wikipedia content using vector similarity
231
162
 
232
- ---
163
+ ## ⚠️ Error Handling
233
164
 
234
- ## Usage Examples
235
- We have put together basic and advanced examples of accessing and using the Perigon API using the python SDK inside the **examples/** folder.
165
+ All errors extend `ResponseError` and include `status` & `body` properties:
236
166
 
237
- ---
167
+ ```ts
168
+ try {
169
+ const result = await perigon.searchArticles({ q: "test" });
170
+ } catch (error) {
171
+ if (error.status === 401) console.error("Invalid API key");
172
+ else if (error.status === 429) console.error("Rate limit exceeded");
173
+ else console.error("API Error:", error.message);
174
+ }
175
+ ```
238
176
 
239
177
  ## πŸͺͺ License
240
178