@leadsetsai/sdk 0.0.0-stage → 0.1.1
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.
- package/CHANGELOG.md +28 -0
- package/LICENSE +21 -0
- package/README.md +373 -2
- package/dist/index.cjs +472 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +588 -0
- package/dist/index.d.ts +588 -0
- package/dist/index.js +450 -0
- package/dist/index.js.map +1 -0
- package/package.json +74 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this package are documented here. The format follows
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
|
|
5
|
+
[Semantic Versioning](https://semver.org/).
|
|
6
|
+
|
|
7
|
+
## [0.1.1] - 2026-11-11
|
|
8
|
+
|
|
9
|
+
### Changed
|
|
10
|
+
|
|
11
|
+
- Package homepage is https://www.leadsets.ai/docs, without tracking parameters.
|
|
12
|
+
|
|
13
|
+
## [0.1.0] - 2026-11-11
|
|
14
|
+
|
|
15
|
+
### Added
|
|
16
|
+
|
|
17
|
+
- First release of `@leadsetsai/sdk`.
|
|
18
|
+
- `people.search`, `people.enrich`, `companies.search`, `companies.enrich`, `emails.verify`,
|
|
19
|
+
`scrape.company`, `scrape.jobs`, `jobs.get` and `usage.get`.
|
|
20
|
+
- Pagination with `searchAll` (records) and `searchPages` (pages), with `maxItems` and `maxPages`.
|
|
21
|
+
- Typed errors mapped from `error.type` and status, each with `requestId`.
|
|
22
|
+
- Automatic retries with exponential backoff and jitter on 429 (honouring `Retry-After`), 5xx,
|
|
23
|
+
timeouts and network errors.
|
|
24
|
+
- An auto-generated `Idempotency-Key` on every paid call, reused across retries.
|
|
25
|
+
- Parsed rate-limit headers on `lastResponse.rateLimit`.
|
|
26
|
+
- ESM and CommonJS builds with type declarations; no runtime dependencies.
|
|
27
|
+
|
|
28
|
+
[0.1.0]: https://github.com/leadsets/sdk/releases/tag/v0.1.0
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Mobylogix LLC
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,374 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Leadsets TypeScript SDK
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@leadsetsai/sdk)
|
|
4
|
+
[](https://github.com/leadsets/sdk/actions/workflows/ci.yml)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
|
|
7
|
+
The official TypeScript and JavaScript client for the [Leadsets](https://www.leadsets.ai/?utm_source=github&utm_medium=readme&utm_campaign=sdk-js&utm_content=intro) API.
|
|
8
|
+
|
|
9
|
+
Leadsets is B2B data for AI agents and the developers who build them. Search people and companies, enrich a person or a company, verify emails and scrape company websites and careers pages, over a REST API or an MCP server. Every record says why it matched, every field carries when it was last checked and a confidence score, and emails are only labelled verified when they are.
|
|
10
|
+
|
|
11
|
+
- Typed requests and responses
|
|
12
|
+
- Automatic retries with backoff on 429 (honouring `Retry-After`), 5xx and network errors
|
|
13
|
+
- An Idempotency-Key on every paid call, so a retry never counts records twice
|
|
14
|
+
- Cursor pagination with async iterators
|
|
15
|
+
- Zero runtime dependencies. Uses the native `fetch`, ships ESM and CommonJS, and runs on Node.js 18+, Bun, Deno and edge runtimes
|
|
16
|
+
|
|
17
|
+
## Contents
|
|
18
|
+
|
|
19
|
+
- [Install](#install)
|
|
20
|
+
- [Quickstart](#quickstart)
|
|
21
|
+
- [Authentication](#authentication)
|
|
22
|
+
- [Resources](#resources)
|
|
23
|
+
- [Pagination](#pagination)
|
|
24
|
+
- [Errors and retries](#errors-and-retries)
|
|
25
|
+
- [Limits and usage](#limits-and-usage)
|
|
26
|
+
- [Idempotency](#idempotency)
|
|
27
|
+
- [Configuration](#configuration)
|
|
28
|
+
- [TypeScript](#typescript)
|
|
29
|
+
- [MCP](#mcp)
|
|
30
|
+
- [Support](#support)
|
|
31
|
+
- [License](#license)
|
|
32
|
+
|
|
33
|
+
## Install
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
npm install @leadsetsai/sdk
|
|
37
|
+
# or
|
|
38
|
+
pnpm add @leadsetsai/sdk
|
|
39
|
+
yarn add @leadsetsai/sdk
|
|
40
|
+
bun add @leadsetsai/sdk
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Quickstart
|
|
44
|
+
|
|
45
|
+
[Create a free account](https://www.leadsets.ai/signup?utm_source=github&utm_medium=readme&utm_campaign=sdk-js&utm_content=quickstart) and copy your API key. Keys start with `ls_live_`.
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
export LEADSETS_API_KEY="ls_live_…"
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Ten revenue leaders at US SaaS companies with 20–200 people:
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
import { Leadsets } from '@leadsetsai/sdk'
|
|
55
|
+
|
|
56
|
+
const ls = new Leadsets(process.env.LEADSETS_API_KEY)
|
|
57
|
+
|
|
58
|
+
const res = await ls.people.search({
|
|
59
|
+
function: ['revenue'],
|
|
60
|
+
seniority: ['vp', 'head'],
|
|
61
|
+
employees: '20-200',
|
|
62
|
+
country: 'US',
|
|
63
|
+
industry: 'saas',
|
|
64
|
+
limit: 10,
|
|
65
|
+
})
|
|
66
|
+
|
|
67
|
+
console.log(res.items[0].match_reasons, res.usage)
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Every response carries what the call counted and what is left (`usage`), plus a `request_id`. The [quickstart guide](https://www.leadsets.ai/docs/quickstart?utm_source=github&utm_medium=readme&utm_campaign=sdk-js&utm_content=quickstart) walks through the same call with cURL.
|
|
71
|
+
|
|
72
|
+
## Authentication
|
|
73
|
+
|
|
74
|
+
The API uses bearer keys. Pass the key to the constructor, or leave it out and the SDK reads the `LEADSETS_API_KEY` environment variable (or `LEADSETS_KEY`).
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
const ls = new Leadsets('ls_live_…') // explicit
|
|
78
|
+
const ls = new Leadsets() // from LEADSETS_API_KEY / LEADSETS_KEY
|
|
79
|
+
const ls = new Leadsets({ apiKey: 'ls_live_…' }) // with other options
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Keep the key server-side. Don't ship it to a browser. A free key is available at [leadsets.ai/signup](https://www.leadsets.ai/signup?utm_source=github&utm_medium=readme&utm_campaign=sdk-js&utm_content=authentication).
|
|
83
|
+
|
|
84
|
+
## Resources
|
|
85
|
+
|
|
86
|
+
| Method | Endpoint | Uses |
|
|
87
|
+
| ----------------------------- | --------------------------- | -------------------------------------------------------- |
|
|
88
|
+
| `ls.people.search(params)` | `POST /v1/people/search` | 1 search record per record returned |
|
|
89
|
+
| `ls.people.enrich(params)` | `POST /v1/people/enrich` | 1 enrichment record when found (+1 for a personal email) |
|
|
90
|
+
| `ls.companies.search(params)` | `POST /v1/companies/search` | 1 search record per record returned |
|
|
91
|
+
| `ls.companies.enrich(params)` | `POST /v1/companies/enrich` | 1 enrichment record when found |
|
|
92
|
+
| `ls.emails.verify(params)` | `POST /v1/emails/verify` | 1 enrichment record per email checked |
|
|
93
|
+
| `ls.scrape.company(params)` | `POST /v1/scrape/company` | 1 scrape unit per page read |
|
|
94
|
+
| `ls.scrape.jobs(params)` | `POST /v1/scrape/jobs` | 1 scrape unit per page read |
|
|
95
|
+
| `ls.jobs.get(id)` | `GET /v1/jobs/{id}` | nothing |
|
|
96
|
+
| `ls.usage.get()` | `GET /v1/usage` | nothing |
|
|
97
|
+
|
|
98
|
+
Every method takes an optional last argument with [request options](#per-request-options).
|
|
99
|
+
|
|
100
|
+
### People search
|
|
101
|
+
|
|
102
|
+
Filters: `title`, `seniority` (`c_level`, `vp`, `head`, `director`, `manager`, `ic`), `function` (`revenue`, `marketing`, `engineering`, `product`, `ops`, `finance`, `hr`), `company_domain`, `employees` (`"50-200"`, `"1000+"`, `"<50"`), `industry` (slugs such as `"saas"`), `country` (ISO 3166-1 alpha-2), `has_verified_email`, `max_age_days`, `exclude_stale`, `limit` (1–100, default 25) and `cursor`. A string or an array works wherever a list is accepted.
|
|
103
|
+
|
|
104
|
+
```ts
|
|
105
|
+
const res = await ls.people.search({
|
|
106
|
+
title: ['VP Sales', 'Head of Sales'], // fuzzy: "VP Sales" also finds "Vice President, Sales"
|
|
107
|
+
country: ['US', 'CA'],
|
|
108
|
+
employees: '50-200',
|
|
109
|
+
has_verified_email: true,
|
|
110
|
+
limit: 25,
|
|
111
|
+
})
|
|
112
|
+
|
|
113
|
+
for (const p of res.items) {
|
|
114
|
+
console.log(p.full_name, p.title, p.company?.domain, p.email?.address, p.email?.status)
|
|
115
|
+
console.log(p.match_reasons) // ["title", "size", "country", "verified_email"]
|
|
116
|
+
console.log(p.sources.title) // { seen_at, confidence }
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Each person has `person_id`, names, `title`, `seniority` and `function` (with finer `seniority_detail` and `function_detail`), `linkedin_url`, `location`, `company`, `email` (with `status`, `confidence` and `checked_at`), `refreshed_at`, `stale` and `sources`.
|
|
121
|
+
|
|
122
|
+
### People enrich
|
|
123
|
+
|
|
124
|
+
Look a person up by LinkedIn URL, by work email, or by name plus company domain.
|
|
125
|
+
|
|
126
|
+
```ts
|
|
127
|
+
const { person, matched_by } = await ls.people.enrich({ linkedin_url: 'https://www.linkedin.com/in/example' })
|
|
128
|
+
await ls.people.enrich({ email: 'jane@example.com' })
|
|
129
|
+
await ls.people.enrich({ full_name: 'Jane Doe', company_domain: 'example.com' })
|
|
130
|
+
await ls.people.enrich({
|
|
131
|
+
first_name: 'Jane',
|
|
132
|
+
last_name: 'Doe',
|
|
133
|
+
company_domain: 'example.com',
|
|
134
|
+
include_personal_email: true,
|
|
135
|
+
})
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
No match is a `NotFoundError` and costs nothing.
|
|
139
|
+
|
|
140
|
+
### Companies search
|
|
141
|
+
|
|
142
|
+
```ts
|
|
143
|
+
const res = await ls.companies.search({
|
|
144
|
+
industry: 'saas',
|
|
145
|
+
employees: '50-200',
|
|
146
|
+
country: 'US',
|
|
147
|
+
technology: ['hubspot', 'salesforce'], // matches any
|
|
148
|
+
limit: 50,
|
|
149
|
+
})
|
|
150
|
+
console.log(res.items.map((c) => [c.name, c.domain, c.employees]))
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
### Companies enrich
|
|
154
|
+
|
|
155
|
+
```ts
|
|
156
|
+
const { company } = await ls.companies.enrich({ domain: 'example.com' }) // a URL works too
|
|
157
|
+
await ls.companies.enrich({ linkedin_url: 'https://www.linkedin.com/company/example' })
|
|
158
|
+
|
|
159
|
+
console.log(company.industry, company.naics, company.employee_range, company.revenue_range, company.technologies)
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### Email verification
|
|
163
|
+
|
|
164
|
+
One email or up to 100 per call. Each result has a `status` (`verified`, `catch_all`, `unknown`, `invalid`), a `confidence` and `checked_at`.
|
|
165
|
+
|
|
166
|
+
```ts
|
|
167
|
+
const one = await ls.emails.verify('jane@example.com')
|
|
168
|
+
const many = await ls.emails.verify(['jane@example.com', 'sam@example.org'])
|
|
169
|
+
// or: ls.emails.verify({ emails: [...] })
|
|
170
|
+
|
|
171
|
+
console.log(many.summary) // { verified, catch_all, unknown, invalid, not_checked }
|
|
172
|
+
for (const r of many.results) {
|
|
173
|
+
if (r.status === null) console.log(r.email, r.reason) // not checked, not counted
|
|
174
|
+
}
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
### Scrape a company website
|
|
178
|
+
|
|
179
|
+
A website as structured JSON: name, description, headings, key links (pricing, customers, careers, docs and more), social profiles and page text. `max_pages` (1–10, default 1) adds the about, pricing, customers, product and careers pages. Scraping is available on paid plans with scrape units.
|
|
180
|
+
|
|
181
|
+
```ts
|
|
182
|
+
const site = await ls.scrape.company({ domain: 'example.com', max_pages: 3 })
|
|
183
|
+
console.log(site.name, site.key_links.pricing, site.social.linkedin)
|
|
184
|
+
console.log(
|
|
185
|
+
site.pages.map((p) => p.url),
|
|
186
|
+
site.usage.scrape_units_left,
|
|
187
|
+
)
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
### Scrape open roles
|
|
191
|
+
|
|
192
|
+
Open roles from a company's careers page or job board: title, link, team, location and posted date when shown. `max_pages` defaults to 3.
|
|
193
|
+
|
|
194
|
+
```ts
|
|
195
|
+
const res = await ls.scrape.jobs({ domain: 'example.com' })
|
|
196
|
+
console.log(res.count, res.careers_url)
|
|
197
|
+
for (const job of res.jobs) console.log(job.title, job.team, job.location, job.url)
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
### Async jobs
|
|
201
|
+
|
|
202
|
+
```ts
|
|
203
|
+
const job = await ls.jobs.get('job_123')
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Async jobs are not generally available yet. Until they are, `jobs.get` throws `NotFoundError`. Split large runs across windows instead.
|
|
207
|
+
|
|
208
|
+
### Usage
|
|
209
|
+
|
|
210
|
+
What's left in every meter and when each window resets. Free to call, so call it before a big run.
|
|
211
|
+
|
|
212
|
+
```ts
|
|
213
|
+
const u = await ls.usage.get()
|
|
214
|
+
console.log(u.plan)
|
|
215
|
+
if (u.search && 'records_5h' in u.search) {
|
|
216
|
+
const [used, limit] = u.search.records_5h
|
|
217
|
+
console.log(`${limit - used} search records left; resets at ${u.search.resets_at}`)
|
|
218
|
+
}
|
|
219
|
+
console.log(u.concurrent_searches, u.scrape_units)
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
On the Free plan, `u.free` holds the one-time balances instead.
|
|
223
|
+
|
|
224
|
+
## Pagination
|
|
225
|
+
|
|
226
|
+
Searches return `next_cursor`. `searchAll` follows it for you and yields one record at a time:
|
|
227
|
+
|
|
228
|
+
```ts
|
|
229
|
+
for await (const person of ls.people.searchAll({ title: ['VP Sales'], country: 'US', limit: 100 })) {
|
|
230
|
+
console.log(person.full_name)
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Each record returned counts, so cap a run with `maxItems`. The last page asks only for what's left, so you never pay for more than you take. `maxPages` caps the number of calls.
|
|
235
|
+
|
|
236
|
+
```ts
|
|
237
|
+
for await (const company of ls.companies.searchAll({ industry: 'saas' }, { maxItems: 250 })) {
|
|
238
|
+
/* … */
|
|
239
|
+
}
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
To read `usage` as you go, iterate pages instead:
|
|
243
|
+
|
|
244
|
+
```ts
|
|
245
|
+
for await (const page of ls.people.searchPages({ country: 'US', limit: 100 }, { maxPages: 5 })) {
|
|
246
|
+
console.log(page.items.length, page.usage.search_records_left_5h)
|
|
247
|
+
}
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Breaking out of a loop stops fetching. To page by hand, pass `cursor: res.next_cursor` to the next `search` call.
|
|
251
|
+
|
|
252
|
+
## Errors and retries
|
|
253
|
+
|
|
254
|
+
Every API error has a status, a machine-readable `type`, a message and a `request_id`. The SDK throws a typed error for each:
|
|
255
|
+
|
|
256
|
+
| Class | Status | `type` |
|
|
257
|
+
| --------------------------- | ------ | --------------------------------------------------------------- |
|
|
258
|
+
| `InvalidRequestError` | 400 | `invalid_request` (`param` names the field) |
|
|
259
|
+
| `AuthenticationError` | 401 | `unauthorized` |
|
|
260
|
+
| `FreeRecordsExhaustedError` | 402 | `free_records_exhausted` |
|
|
261
|
+
| `ScrapeUnitsExhaustedError` | 402 | `scrape_units_exhausted` |
|
|
262
|
+
| `PermissionDeniedError` | 403 | `forbidden` (`upgradeUrl` when an upgrade would allow the call) |
|
|
263
|
+
| `NotFoundError` | 404 | `not_found` |
|
|
264
|
+
| `IdempotencyConflictError` | 409 | `idempotency_conflict` |
|
|
265
|
+
| `RateLimitError` | 429 | `window_full`, `weekly_limit`, `too_many_concurrent` |
|
|
266
|
+
| `InternalServerError` | 5xx | `internal_error` |
|
|
267
|
+
| `ServiceUnavailableError` | 503 | `unavailable` |
|
|
268
|
+
| `APIConnectionError` | none | the request got no answer |
|
|
269
|
+
| `APITimeoutError` | none | the request timed out |
|
|
270
|
+
|
|
271
|
+
`FreeRecordsExhaustedError` and `ScrapeUnitsExhaustedError` extend `PaymentRequiredError`. Every HTTP error extends `APIError`, and everything extends `LeadsetsError`. `ConnectionError` and `TimeoutError` are exported as aliases of the last two.
|
|
272
|
+
|
|
273
|
+
```ts
|
|
274
|
+
import { APIError, NotFoundError, RateLimitError } from '@leadsetsai/sdk'
|
|
275
|
+
|
|
276
|
+
try {
|
|
277
|
+
await ls.people.enrich({ email: 'jane@example.com' })
|
|
278
|
+
} catch (err) {
|
|
279
|
+
if (err instanceof NotFoundError) {
|
|
280
|
+
// nothing to enrich; nothing was counted
|
|
281
|
+
} else if (err instanceof RateLimitError) {
|
|
282
|
+
console.log(err.type, err.meter, err.resetsAt, err.retryAfter)
|
|
283
|
+
} else if (err instanceof APIError) {
|
|
284
|
+
console.log(err.status, err.type, err.message, err.requestId)
|
|
285
|
+
} else {
|
|
286
|
+
throw err
|
|
287
|
+
}
|
|
288
|
+
}
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
**Retries.** The SDK retries 429, 5xx, timeouts and network errors up to `maxRetries` times (default 2). It waits for `Retry-After` when the API sends one, and otherwise backs off exponentially with jitter (about 0.5 s, 1 s, 2 s, up to 8 s). A `Retry-After` longer than `maxRetryDelay` (default 60 s), such as a weekly limit, is thrown at once so a run doesn't hang. 400, 401, 402, 403, 404 and 409 are never retried.
|
|
292
|
+
|
|
293
|
+
## Limits and usage
|
|
294
|
+
|
|
295
|
+
- **Records count only when data comes back.** Empty results, misses and errors use no records. Every call counts one request toward its window, hits and misses alike.
|
|
296
|
+
- **Paid plans have rolling five-hour windows** for records and for requests, plus a **weekly** records window, kept separately for search and for enrichment. Scraping uses scrape units.
|
|
297
|
+
- **Free** has 1,000 enrichment records and 100 search records, one time, with no card needed. Paid plans start at $29/month. See [pricing](https://www.leadsets.ai/pricing?utm_source=github&utm_medium=readme&utm_campaign=sdk-js&utm_content=limits).
|
|
298
|
+
|
|
299
|
+
Every response has a `usage` object with what the call counted and what's left, and the SDK parses the rate-limit headers into `res.lastResponse.rateLimit`:
|
|
300
|
+
|
|
301
|
+
```ts
|
|
302
|
+
const res = await ls.people.search({ country: 'US' })
|
|
303
|
+
res.usage // { search_records_counted, search_records_left_5h, search_requests_left_5h, search_records_left_week }
|
|
304
|
+
res.lastResponse.rateLimit // { recordsRemaining, requestsRemaining, weeklyRemaining, freeRemaining, retryAfter }
|
|
305
|
+
res.lastResponse.requestId // also res.request_id
|
|
306
|
+
res.lastResponse.headers // the raw Headers
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
`lastResponse` is non-enumerable, so it stays out of `JSON.stringify(res)`. Read more in the [docs](https://www.leadsets.ai/docs?utm_source=github&utm_medium=readme&utm_campaign=sdk-js&utm_content=limits).
|
|
310
|
+
|
|
311
|
+
## Idempotency
|
|
312
|
+
|
|
313
|
+
The SDK sends an `Idempotency-Key` with every paid call (all POSTs) and reuses it across its own retries, so a retry never counts records twice. Pass your own key to make a call safe to repeat across processes, for example one key per CRM row:
|
|
314
|
+
|
|
315
|
+
```ts
|
|
316
|
+
await ls.people.enrich({ email: row.email }, { idempotencyKey: `crm-${row.id}` })
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
A repeat with the same key and body returns the first result (`res.lastResponse.idempotentReplayed === true`) and counts nothing. The same key with a different body throws `IdempotencyConflictError`. Keys last 24 hours. With `searchAll`/`searchPages`, a key you pass is suffixed per page (`key`, `key-p2`, `key-p3` …).
|
|
320
|
+
|
|
321
|
+
## Configuration
|
|
322
|
+
|
|
323
|
+
```ts
|
|
324
|
+
const ls = new Leadsets({
|
|
325
|
+
apiKey: 'ls_live_…', // default: LEADSETS_API_KEY or LEADSETS_KEY
|
|
326
|
+
baseURL: 'https://api.leadsets.ai', // default; LEADSETS_BASE_URL also works
|
|
327
|
+
maxRetries: 2, // retries on 429, 5xx, timeouts and network errors
|
|
328
|
+
timeout: 120_000, // per attempt, in ms
|
|
329
|
+
maxRetryDelay: 60_000, // longest Retry-After to wait for, in ms
|
|
330
|
+
fetch: customFetch, // default: global fetch
|
|
331
|
+
defaultHeaders: { 'X-My-App': 'crm-sync' },
|
|
332
|
+
})
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
### Per-request options
|
|
336
|
+
|
|
337
|
+
```ts
|
|
338
|
+
await ls.people.search(params, {
|
|
339
|
+
idempotencyKey: 'run-42',
|
|
340
|
+
maxRetries: 5,
|
|
341
|
+
timeout: 30_000,
|
|
342
|
+
signal: AbortSignal.timeout(10_000),
|
|
343
|
+
headers: { 'X-Trace-Id': 'abc' },
|
|
344
|
+
})
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
## TypeScript
|
|
348
|
+
|
|
349
|
+
Every request and response is typed: `PeopleSearchParams`, `PeopleSearchResponse`, `Person`, `Company`, `Email`, `EmailVerification`, `ScrapeCompanyResponse`, `Job`, `UsageResponse`, `Usage` and more, all exported from `@leadsetsai/sdk`.
|
|
350
|
+
|
|
351
|
+
```ts
|
|
352
|
+
import type { Person, PeopleSearchParams } from '@leadsetsai/sdk'
|
|
353
|
+
|
|
354
|
+
const query: PeopleSearchParams = { seniority: ['vp'], function: ['marketing'] }
|
|
355
|
+
```
|
|
356
|
+
|
|
357
|
+
Fields the API may leave empty are typed `T | null`. The package ships ESM and CommonJS builds with declarations, has no runtime dependencies and needs a global `fetch` (Node.js 18+, Bun, Deno and edge runtimes). In the browser, keep your key on a server and proxy requests.
|
|
358
|
+
|
|
359
|
+
## MCP
|
|
360
|
+
|
|
361
|
+
Using an AI agent? Leadsets also runs a hosted MCP server at `https://mcp.leadsets.ai` with the same tools, so Claude, Cursor, ChatGPT and other MCP clients can call it with no code. See [Connect via MCP](https://www.leadsets.ai/docs/mcp?utm_source=github&utm_medium=readme&utm_campaign=sdk-js&utm_content=mcp).
|
|
362
|
+
|
|
363
|
+
## Support
|
|
364
|
+
|
|
365
|
+
- [Docs](https://www.leadsets.ai/docs?utm_source=github&utm_medium=readme&utm_campaign=sdk-js&utm_content=support) and the [quickstart](https://www.leadsets.ai/docs/quickstart?utm_source=github&utm_medium=readme&utm_campaign=sdk-js&utm_content=support)
|
|
366
|
+
- [Support](https://www.leadsets.ai/support?utm_source=github&utm_medium=readme&utm_campaign=sdk-js&utm_content=support): include the `request_id` from the response or error and we can see exactly what happened
|
|
367
|
+
- Bugs and feature requests: [GitHub issues](https://github.com/leadsets/sdk/issues)
|
|
368
|
+
- Security: see [SECURITY.md](SECURITY.md)
|
|
369
|
+
|
|
370
|
+
Contributions are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
371
|
+
|
|
372
|
+
## License
|
|
373
|
+
|
|
374
|
+
[MIT](LICENSE)
|