@leadsetsai/sdk 0.0.0-stage → 0.1.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.
package/CHANGELOG.md ADDED
@@ -0,0 +1,22 @@
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.0] - 2026-11-11
8
+
9
+ ### Added
10
+
11
+ - First release of `@leadsetsai/sdk`.
12
+ - `people.search`, `people.enrich`, `companies.search`, `companies.enrich`, `emails.verify`,
13
+ `scrape.company`, `scrape.jobs`, `jobs.get` and `usage.get`.
14
+ - Pagination with `searchAll` (records) and `searchPages` (pages), with `maxItems` and `maxPages`.
15
+ - Typed errors mapped from `error.type` and status, each with `requestId`.
16
+ - Automatic retries with exponential backoff and jitter on 429 (honouring `Retry-After`), 5xx,
17
+ timeouts and network errors.
18
+ - An auto-generated `Idempotency-Key` on every paid call, reused across retries.
19
+ - Parsed rate-limit headers on `lastResponse.rateLimit`.
20
+ - ESM and CommonJS builds with type declarations; no runtime dependencies.
21
+
22
+ [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
- # Temporary Holding Version
1
+ # Leadsets TypeScript SDK
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm](https://img.shields.io/npm/v/@leadsetsai/sdk.svg)](https://www.npmjs.com/package/@leadsetsai/sdk)
4
+ [![CI](https://github.com/leadsets/sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/leadsets/sdk/actions/workflows/ci.yml)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](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)