@synthient/synthient 1.0.1 → 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.
- package/LICENSE +198 -11
- package/README.md +407 -84
- package/dist/client.d.ts +98 -39
- package/dist/client.js +141 -90
- package/dist/errors.d.ts +72 -0
- package/dist/errors.js +122 -0
- package/dist/events.d.ts +217 -0
- package/dist/events.js +1 -0
- package/dist/feed.d.ts +75 -0
- package/dist/feed.js +192 -0
- package/dist/grpcschema.d.ts +56 -0
- package/dist/grpcschema.js +278 -0
- package/dist/index.d.ts +23 -5
- package/dist/index.js +20 -21
- package/dist/options.d.ts +5 -0
- package/dist/options.js +23 -0
- package/dist/transport.d.ts +76 -0
- package/dist/transport.js +328 -0
- package/dist/types.d.ts +248 -0
- package/dist/types.js +4 -0
- package/dist/version.d.ts +2 -0
- package/dist/version.js +2 -0
- package/package.json +70 -12
- package/dist/constants.d.ts +0 -2
- package/dist/constants.js +0 -5
- package/dist/exceptions.d.ts +0 -33
- package/dist/exceptions.js +0 -48
- package/dist/models.d.ts +0 -191
- package/dist/models.js +0 -221
- package/dist/utils.d.ts +0 -15
- package/dist/utils.js +0 -29
- package/src/client.ts +0 -106
- package/src/constants.ts +0 -2
- package/src/exceptions.ts +0 -44
- package/src/index.ts +0 -5
- package/src/models.ts +0 -276
- package/src/utils.ts +0 -28
- package/tsconfig.json +0 -15
package/README.md
CHANGED
|
@@ -1,148 +1,471 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://synthient.com">
|
|
3
|
+
<img src="assets/logo.svg" height="96" alt="Synthient logo">
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
6
|
+
<h3 align="center">Synthient</h3>
|
|
7
|
+
<p align="center">High-fidelity data on residential proxies, VPNs, and other anonymized IPs.</p>
|
|
8
|
+
<p align="center">
|
|
9
|
+
<a href="https://docs.synthient.com">Documentation</a> ·
|
|
10
|
+
<a href="https://www.npmjs.com/package/@synthient/synthient">npm</a> ·
|
|
11
|
+
<a href="https://docs.synthient.com/misc/support">Support</a>
|
|
12
|
+
</p>
|
|
13
|
+
|
|
14
|
+
# synthient-node
|
|
15
|
+
|
|
16
|
+
`@synthient/synthient` is the official Node.js SDK for the [Synthient API](https://docs.synthient.com): IP and domain intelligence, account details, and real-time and bulk data feeds. It is written in TypeScript and ships with type definitions.
|
|
17
|
+
|
|
18
|
+
[](https://www.npmjs.com/package/@synthient/synthient)
|
|
19
|
+
[](https://github.com/synthient/synthient-node/actions/workflows/test.yml)
|
|
20
|
+
[](https://github.com/synthient/synthient-node/actions/workflows/lint.yml)
|
|
21
|
+
[](LICENSE)
|
|
22
|
+
|
|
23
|
+
## Table of Contents
|
|
24
|
+
|
|
25
|
+
- [synthient-node](#synthient-node)
|
|
26
|
+
- [SDK Installation](#sdk-installation)
|
|
27
|
+
- [Requirements](#requirements)
|
|
28
|
+
- [API Keys](#api-keys)
|
|
29
|
+
- [Authentication](#authentication)
|
|
30
|
+
- [SDK Example Usage](#sdk-example-usage)
|
|
31
|
+
- [Available Resources and Operations](#available-resources-and-operations)
|
|
32
|
+
- [Streaming](#streaming)
|
|
33
|
+
- [Pagination](#pagination)
|
|
34
|
+
- [Downloads](#downloads)
|
|
35
|
+
- [Retries](#retries)
|
|
36
|
+
- [Timeouts](#timeouts)
|
|
37
|
+
- [Error Handling](#error-handling)
|
|
38
|
+
- [Server Selection](#server-selection)
|
|
39
|
+
- [Custom HTTP Client](#custom-http-client)
|
|
40
|
+
- [Debugging](#debugging)
|
|
41
|
+
- [gRPC Schema](#grpc-schema)
|
|
42
|
+
- [Development](#development)
|
|
43
|
+
- [Maturity](#maturity)
|
|
44
|
+
- [Contributions](#contributions)
|
|
45
|
+
- [License](#license)
|
|
46
|
+
|
|
47
|
+
## SDK Installation
|
|
48
|
+
|
|
49
|
+
The SDK can be installed with [npm](https://www.npmjs.com/), [pnpm](https://pnpm.io/), [bun](https://bun.sh/), or [yarn](https://yarnpkg.com/).
|
|
50
|
+
|
|
51
|
+
### NPM
|
|
52
|
+
|
|
53
|
+
```sh
|
|
54
|
+
npm add @synthient/synthient
|
|
55
|
+
```
|
|
2
56
|
|
|
3
|
-
|
|
57
|
+
### PNPM
|
|
4
58
|
|
|
5
|
-
|
|
59
|
+
```sh
|
|
60
|
+
pnpm add @synthient/synthient
|
|
61
|
+
```
|
|
6
62
|
|
|
7
|
-
|
|
63
|
+
### Bun
|
|
8
64
|
|
|
9
|
-
```
|
|
10
|
-
|
|
65
|
+
```sh
|
|
66
|
+
bun add @synthient/synthient
|
|
11
67
|
```
|
|
12
68
|
|
|
13
|
-
|
|
69
|
+
### Yarn
|
|
14
70
|
|
|
15
|
-
```
|
|
71
|
+
```sh
|
|
16
72
|
yarn add @synthient/synthient
|
|
17
73
|
```
|
|
18
74
|
|
|
19
|
-
|
|
75
|
+
> [!NOTE]
|
|
76
|
+
> This package is an ES module. CommonJS code can also load it with `require()`.
|
|
77
|
+
|
|
78
|
+
The [gRPC schema fetcher](#grpc-schema) is the `@synthient/synthient/grpcschema` subpath of the same package.
|
|
79
|
+
|
|
80
|
+
## Requirements
|
|
81
|
+
|
|
82
|
+
Node.js 22.12 or later. Other runtimes, such as Bun and Deno, are not tested. The SDK is for server-side code and has no runtime dependencies. Its types are tested with TypeScript 5.8 and later.
|
|
83
|
+
|
|
84
|
+
## API Keys
|
|
85
|
+
|
|
86
|
+
Every request needs a Synthient API key. Keys are issued from the Synthient dashboard; if you don't have one, [contact us](mailto:contact@synthient.com). A key's scopes decide what it can call: `BASIC` covers the lookups and `account`, and each feed has its own scopes, listed under [Feeds](#feeds).
|
|
20
87
|
|
|
21
|
-
|
|
88
|
+
If a request fails even though you are sending a key:
|
|
22
89
|
|
|
23
|
-
|
|
90
|
+
- **401 Unauthorized**: the key is malformed, unknown, or revoked.
|
|
91
|
+
- **402 Payment Required**: the team is out of lookup credits.
|
|
92
|
+
- **403 Forbidden**: the key lacks the scope for that endpoint or feed.
|
|
24
93
|
|
|
25
|
-
|
|
26
|
-
const { Client } = require('@synthient/synthient');
|
|
94
|
+
`account` shows the key's scopes and the team's remaining credits.
|
|
27
95
|
|
|
28
|
-
|
|
29
|
-
|
|
96
|
+
## Authentication
|
|
97
|
+
|
|
98
|
+
This SDK supports the following security scheme:
|
|
99
|
+
|
|
100
|
+
| Name | Type | Scheme | Environment Variable |
|
|
101
|
+
| -------- | ------- | ------------------ | -------------------- |
|
|
102
|
+
| `apiKey` | API key | `x-api-key` header | `SYNTHIENT_API_KEY` |
|
|
103
|
+
|
|
104
|
+
By default, the client reads the key from the `SYNTHIENT_API_KEY` environment variable:
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
import { Synthient } from "@synthient/synthient";
|
|
108
|
+
|
|
109
|
+
const client = new Synthient();
|
|
30
110
|
```
|
|
31
111
|
|
|
32
|
-
|
|
112
|
+
To use a key from somewhere else, such as a secret manager, pass it as `apiKey`:
|
|
33
113
|
|
|
34
|
-
```
|
|
35
|
-
const client = new
|
|
114
|
+
```ts
|
|
115
|
+
const client = new Synthient({ apiKey: await getSecret("synthient-api-key") });
|
|
36
116
|
```
|
|
37
117
|
|
|
38
|
-
|
|
118
|
+
The constructor makes no network calls. To check a key, call `account`, which costs no credits.
|
|
39
119
|
|
|
40
|
-
|
|
120
|
+
## SDK Example Usage
|
|
41
121
|
|
|
42
|
-
|
|
122
|
+
### Look up an IP address
|
|
43
123
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
124
|
+
Get the network, location, and risk intelligence for an IPv4 or IPv6 address. Each lookup costs one credit; failed lookups are free.
|
|
125
|
+
|
|
126
|
+
```ts
|
|
127
|
+
import { Synthient } from "@synthient/synthient";
|
|
128
|
+
|
|
129
|
+
const client = new Synthient();
|
|
130
|
+
|
|
131
|
+
const info = await client.lookupIP("8.8.8.8");
|
|
132
|
+
if (info.intelligence) {
|
|
133
|
+
console.log(info.intelligence.risk_score, info.intelligence.categories);
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
`network`, `location`, and `intelligence` are absent when the API has no data for them. Response fields keep the API's snake_case names. The examples below reuse `client`, and runnable programs are in [examples](examples).
|
|
138
|
+
|
|
139
|
+
### Look up many IP addresses
|
|
140
|
+
|
|
141
|
+
Look up as many as 1000 addresses in one request for `ceil(n * 0.9)` credits. Private and reserved addresses are skipped and duplicates are merged, so match results by `ip`.
|
|
142
|
+
|
|
143
|
+
```ts
|
|
144
|
+
const results = await client.lookupIPs(["8.8.8.8", "1.1.1.1"]);
|
|
145
|
+
for (const result of results) {
|
|
146
|
+
if (result.intelligence) {
|
|
147
|
+
console.log(result.ip, result.intelligence.risk_score);
|
|
52
148
|
}
|
|
53
149
|
}
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### Look up a domain
|
|
153
|
+
|
|
154
|
+
Get the honeypot traffic observed for a domain and its most recent events. Each lookup costs one credit.
|
|
155
|
+
|
|
156
|
+
```ts
|
|
157
|
+
import { toDate } from "@synthient/synthient";
|
|
158
|
+
|
|
159
|
+
const domain = await client.lookupDomain("example.com", { limit: 10 });
|
|
160
|
+
console.log(domain.status, domain.stats.events_24h);
|
|
161
|
+
for (const event of domain.recent_events) {
|
|
162
|
+
console.log(toDate(event.timestamp), event.target_subdomain, event.port);
|
|
163
|
+
}
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
### Check your account
|
|
167
|
+
|
|
168
|
+
Get the key's account, scopes, and remaining lookup credits, at no cost.
|
|
54
169
|
|
|
55
|
-
|
|
170
|
+
```ts
|
|
171
|
+
const account = await client.account();
|
|
172
|
+
console.log(account.organization.name, account.scopes, account.lookup_quota.credits);
|
|
56
173
|
```
|
|
57
174
|
|
|
58
|
-
|
|
175
|
+
## Available Resources and Operations
|
|
176
|
+
|
|
177
|
+
<details open>
|
|
178
|
+
<summary>Available methods</summary>
|
|
179
|
+
|
|
180
|
+
### Synthient
|
|
181
|
+
|
|
182
|
+
- `lookupIP` - Look up an IPv4 or IPv6 address
|
|
183
|
+
- `lookupIPs` - Look up as many as 1000 addresses in one request
|
|
184
|
+
- `lookupDomain` - Look up the honeypot traffic observed for a domain
|
|
185
|
+
- `account` - Get the key's account, scopes, and remaining lookup credits
|
|
186
|
+
- `health` - Check that the API and its dependencies are healthy
|
|
187
|
+
|
|
188
|
+
### Feeds
|
|
189
|
+
|
|
190
|
+
Each feed is a property of the client, such as `client.proxies`, and has the same methods:
|
|
191
|
+
|
|
192
|
+
- `stream` - Iterate over the feed's real-time events
|
|
193
|
+
- `listExports` - List one page of the feed's Parquet exports, newest first
|
|
194
|
+
- `allExports` - Iterate over every export, fetching pages as needed
|
|
195
|
+
- `exportMeta` - Get an export's checksum, size, row count, and Parquet schema
|
|
196
|
+
- `download` - Download an export's Parquet file
|
|
197
|
+
- `downloadURL` - Get a presigned URL for an export's Parquet file, valid for 24 hours
|
|
59
198
|
|
|
60
|
-
|
|
199
|
+
| Property | Data | Event type | Stream scope | Export scope |
|
|
200
|
+
| ------------- | --------------------------------------------- | ------------------ | ----------------------- | --------------------- |
|
|
201
|
+
| `proxies` | Residential, mobile, and datacenter proxies | `ProxyEvent` | `PROXY_FIREHOSE` | `PROXY_FEEDS` |
|
|
202
|
+
| `anonymizers` | VPN and anonymizer IP ranges | `AnonymizerEvent` | `ANONYMIZERS_STREAM` | `ANONYMIZERS_FEED` |
|
|
203
|
+
| `torrents` | BitTorrent DHT and tracker peers | `TorrentEvent` | `TORRENTS_STREAM` | `TORRENTS_FEED` |
|
|
204
|
+
| `ja4t` | JA4T TCP fingerprints | `JA4TEvent` | `JA4T_STREAM` | `JA4T_FEED` |
|
|
205
|
+
| `heliosHTTP` | Helios honeypot HTTP requests | `HeliosHTTPEvent` | `HONEYPOT_HTTP_STREAM` | `HONEYPOT_HTTP_FEED` |
|
|
206
|
+
| `heliosHTTPS` | Helios honeypot TLS ClientHellos | `HeliosHTTPSEvent` | `HONEYPOT_HTTPS_STREAM` | `HONEYPOT_HTTPS_FEED` |
|
|
207
|
+
| `heliosDNS` | Helios honeypot tunnel destinations | `HeliosDNSEvent` | `HONEYPOT_DNS_STREAM` | `HONEYPOT_DNS_FEED` |
|
|
208
|
+
| `heliosADB` | Helios honeypot Android Debug Bridge commands | `HeliosADBEvent` | `HONEYPOT_ADB_STREAM` | `HONEYPOT_ADB_FEED` |
|
|
61
209
|
|
|
62
|
-
|
|
63
|
-
|
|
210
|
+
</details>
|
|
211
|
+
|
|
212
|
+
## Streaming
|
|
213
|
+
|
|
214
|
+
`stream` returns an async iterator over a feed's real-time events. Each `for await` loop opens a connection, and breaking out of the loop closes it:
|
|
215
|
+
|
|
216
|
+
```ts
|
|
217
|
+
import { setTimeout as sleep } from "node:timers/promises";
|
|
218
|
+
import { APIError } from "@synthient/synthient";
|
|
219
|
+
|
|
220
|
+
for (;;) {
|
|
64
221
|
try {
|
|
65
|
-
const
|
|
66
|
-
|
|
67
|
-
|
|
222
|
+
for await (const event of client.proxies.stream()) {
|
|
223
|
+
console.log(event.ip, event.provider, event.type);
|
|
224
|
+
}
|
|
68
225
|
} catch (error) {
|
|
69
|
-
|
|
226
|
+
if (error instanceof APIError && (error.status === 401 || error.status === 403)) {
|
|
227
|
+
throw error;
|
|
228
|
+
}
|
|
229
|
+
console.error("proxy stream:", error);
|
|
230
|
+
// Avoid reconnecting in a tight loop.
|
|
231
|
+
await sleep(2000);
|
|
70
232
|
}
|
|
71
233
|
}
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
- The server closes each stream after up to 30 minutes. That ends the inner loop without an error, and the outer loop reconnects at once.
|
|
237
|
+
- A 401 or 403 stops the loop, because reconnecting can't fix a rejected key or a missing scope.
|
|
238
|
+
- Any other failure is thrown from the inner loop, and the outer loop waits 2 seconds before reconnecting.
|
|
239
|
+
- Events sent while disconnected are missed. The API has no resume cursor.
|
|
72
240
|
|
|
73
|
-
|
|
241
|
+
## Pagination
|
|
242
|
+
|
|
243
|
+
`listExports` returns one page of a feed's exports, newest first. Pass `page.next_cursor` as `cursor` to get the next page; it is absent, `null`, or empty on the last one.
|
|
244
|
+
|
|
245
|
+
```ts
|
|
246
|
+
const page = await client.proxies.listExports({ limit: 50 });
|
|
247
|
+
for (const item of page.feeds) {
|
|
248
|
+
console.log(item.id, item.kind, item.row_count);
|
|
249
|
+
}
|
|
74
250
|
```
|
|
75
251
|
|
|
76
|
-
|
|
252
|
+
`allExports` fetches the pages for you as the loop needs them:
|
|
77
253
|
|
|
78
|
-
|
|
254
|
+
```ts
|
|
255
|
+
for await (const item of client.proxies.allExports()) {
|
|
256
|
+
console.log(item.id, item.kind, item.row_count);
|
|
257
|
+
}
|
|
258
|
+
```
|
|
79
259
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
260
|
+
On the first page, the newest hourly export has the ID `latest`, a moving alias for the freshest export. Its `date` and `hour` give its stable ID, such as `2026-10-14/21`.
|
|
261
|
+
|
|
262
|
+
## Downloads
|
|
263
|
+
|
|
264
|
+
Exports are Parquet files. `download` returns a file's contents as a web `ReadableStream`, which you must read to the end or cancel:
|
|
265
|
+
|
|
266
|
+
```ts
|
|
267
|
+
import { createWriteStream } from "node:fs";
|
|
268
|
+
import { Readable } from "node:stream";
|
|
269
|
+
import { pipeline } from "node:stream/promises";
|
|
270
|
+
|
|
271
|
+
const body = await client.proxies.download("latest");
|
|
272
|
+
await pipeline(Readable.fromWeb(body), createWriteStream("proxies.parquet"));
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
- Name an export by its `id` from a listing, by `"latest"`, or by `dailyExport(date)` or `hourlyExport(date)` for a UTC day or hour.
|
|
276
|
+
- `exportMeta` returns the file's SHA-256 checksum. Use a fixed ID for both calls, because `latest` can move between them.
|
|
277
|
+
- `downloadURL` returns a presigned URL that works without a key for 24 hours, so treat it as a secret. Your API key is never sent to the storage host.
|
|
278
|
+
- Hourly exports roll into the daily export shortly after 00:30 UTC the next day. After that, the hour returns a 400.
|
|
279
|
+
|
|
280
|
+
## Retries
|
|
281
|
+
|
|
282
|
+
The client retries a failed request up to twice, backing off exponentially with jitter and honoring `Retry-After`:
|
|
283
|
+
|
|
284
|
+
| Requests | Retried on |
|
|
285
|
+
| --------------------------- | -------------------------------------------------------------------------------------------- |
|
|
286
|
+
| Account and feed requests | 500, 502, 503, and 504, timeouts, most connection failures, and 429 with `Retry-After` |
|
|
287
|
+
| Billed lookups and `health` | Only 429 with `Retry-After`, which comes before any work, so a lookup is never charged twice |
|
|
288
|
+
|
|
289
|
+
A 429 without `Retry-After` means the monthly request budget is spent or too many streams are open, so the call fails at once. Downloads from the storage host are never retried.
|
|
290
|
+
|
|
291
|
+
Set the number of retries with `maxRetries`. Zero disables them:
|
|
292
|
+
|
|
293
|
+
```ts
|
|
294
|
+
const client = new Synthient({ maxRetries: 4 });
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
## Timeouts
|
|
298
|
+
|
|
299
|
+
The `timeout` option, in milliseconds (60,000 by default), limits how long the client waits for response headers or for the next part of a body. It doesn't limit a whole call, because streams and downloads are long-lived. Bound a call with an `AbortSignal`:
|
|
300
|
+
|
|
301
|
+
```ts
|
|
302
|
+
const client = new Synthient({ timeout: 30_000 });
|
|
303
|
+
|
|
304
|
+
const info = await client.lookupIP("8.8.8.8", { signal: AbortSignal.timeout(10_000) });
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
Every method takes a `signal` option. An aborted call rejects with the signal's reason.
|
|
308
|
+
|
|
309
|
+
## Error Handling
|
|
310
|
+
|
|
311
|
+
A request that fails with a non-success status rejects with an `APIError`:
|
|
312
|
+
|
|
313
|
+
| Property | Type | Description |
|
|
314
|
+
| ------------ | -------------------------- | --------------------------------------------------------- |
|
|
315
|
+
| `status` | `number` | HTTP status code, such as `404` |
|
|
316
|
+
| `type` | `string` | URI identifying the problem type, or `""` |
|
|
317
|
+
| `title` | `string` | Short summary of the problem type, or `""` |
|
|
318
|
+
| `detail` | `string` | Explanation of this occurrence, or `""` |
|
|
319
|
+
| `errors` | `Record<string, string[]>` | Validation messages by request field |
|
|
320
|
+
| `requestID` | `string` | Request ID to give Synthient support, or `""` |
|
|
321
|
+
| `retryAfter` | `number \| undefined` | Milliseconds the server asked you to wait, or `undefined` |
|
|
322
|
+
|
|
323
|
+
`message` holds only the HTTP status, so it is safe to log. The other properties hold untrusted server data.
|
|
324
|
+
|
|
325
|
+
### Example
|
|
326
|
+
|
|
327
|
+
```ts
|
|
328
|
+
import { APIError } from "@synthient/synthient";
|
|
329
|
+
|
|
330
|
+
try {
|
|
331
|
+
await client.lookupIP("8.8.8.8");
|
|
332
|
+
} catch (error) {
|
|
333
|
+
if (!(error instanceof APIError)) {
|
|
334
|
+
throw error;
|
|
335
|
+
}
|
|
336
|
+
switch (error.status) {
|
|
337
|
+
case 402:
|
|
338
|
+
console.log("out of lookup credits");
|
|
339
|
+
break;
|
|
340
|
+
case 429:
|
|
341
|
+
if (error.retryAfter === undefined) {
|
|
342
|
+
console.log("monthly request budget spent");
|
|
343
|
+
} else {
|
|
344
|
+
console.log(`rate limited, retry after ${error.retryAfter} ms`);
|
|
345
|
+
}
|
|
346
|
+
break;
|
|
347
|
+
default:
|
|
348
|
+
console.log("request", error.requestID, "failed:", error.detail || error.title);
|
|
88
349
|
}
|
|
89
350
|
}
|
|
90
|
-
|
|
91
|
-
deleteToken();
|
|
92
351
|
```
|
|
93
352
|
|
|
94
|
-
###
|
|
353
|
+
### Error Types
|
|
354
|
+
|
|
355
|
+
- `SynthientError`: the base class of the errors the SDK throws for failed requests and invalid responses.
|
|
356
|
+
- `APIError`: the API, or the storage host during `download`, returned a non-success status.
|
|
357
|
+
- `APIConnectionError`: the connection failed, such as a DNS or TLS failure or a dropped stream.
|
|
358
|
+
- `APITimeoutError`: no data arrived within the client's `timeout`.
|
|
359
|
+
- `TypeError` and `RangeError`: an argument or option is invalid, such as a missing API key or a malformed IP address.
|
|
360
|
+
- Aborted calls: a call whose `signal` aborts rejects with the signal's reason.
|
|
361
|
+
|
|
362
|
+
<details><summary>Status codes</summary>
|
|
363
|
+
|
|
364
|
+
<br />
|
|
365
|
+
|
|
366
|
+
| Status | Meaning |
|
|
367
|
+
| ------ | ----------------------------------------------------------------------------------------------- |
|
|
368
|
+
| 400 | The request is invalid, such as an hourly export that was rolled up |
|
|
369
|
+
| 401 | The API key is malformed, unknown, or revoked |
|
|
370
|
+
| 402 | The team is out of lookup credits |
|
|
371
|
+
| 403 | The key lacks the scope for the endpoint or feed |
|
|
372
|
+
| 404 | The export doesn't exist, or a daily export is still rolling up (`retryAfter` is set) |
|
|
373
|
+
| 422 | The input is invalid, such as a private address or a malformed domain |
|
|
374
|
+
| 429 | Rate limited if `retryAfter` is set; otherwise the budget is spent or too many streams are open |
|
|
375
|
+
| 5xx | The server failed |
|
|
376
|
+
|
|
377
|
+
</details>
|
|
378
|
+
|
|
379
|
+
## Server Selection
|
|
380
|
+
|
|
381
|
+
### Override Server URL Per-Client
|
|
382
|
+
|
|
383
|
+
The default server is `https://api.synthient.com/api/v4`, exported as `DEFAULT_BASE_URL`. Use `baseURL` to send requests elsewhere, such as a mock server in tests:
|
|
95
384
|
|
|
96
|
-
|
|
385
|
+
```ts
|
|
386
|
+
const client = new Synthient({ baseURL: "http://localhost:8080/api/v4" });
|
|
387
|
+
```
|
|
388
|
+
|
|
389
|
+
## Custom HTTP Client
|
|
97
390
|
|
|
98
|
-
|
|
391
|
+
The client uses the global `fetch`. Pass your own with the `fetch` option, for example to use a proxy or to answer requests with fixtures in tests:
|
|
99
392
|
|
|
100
|
-
|
|
393
|
+
```ts
|
|
394
|
+
import { Synthient } from "@synthient/synthient";
|
|
101
395
|
|
|
102
|
-
|
|
103
|
-
|
|
396
|
+
const client = new Synthient({
|
|
397
|
+
apiKey: "test-key",
|
|
398
|
+
fetch: async () => Response.json({ ip: "8.8.8.8" }),
|
|
399
|
+
});
|
|
104
400
|
|
|
105
|
-
const
|
|
106
|
-
console.log('Token is valid:', isValid);
|
|
401
|
+
const info = await client.lookupIP("8.8.8.8");
|
|
107
402
|
```
|
|
108
403
|
|
|
109
|
-
|
|
404
|
+
- Your `fetch` also downloads exports from the storage host, without the API key.
|
|
405
|
+
- It must not follow redirects, because the client handles each one to keep the API key away from other hosts.
|
|
406
|
+
- It must not replay requests, so a billed lookup is never sent twice.
|
|
407
|
+
- It must honor `init.signal`, which carries the `timeout` and the call's `signal`.
|
|
408
|
+
|
|
409
|
+
`userAgent: "my-app/1.2"` adds your product token to the `User-Agent` header.
|
|
110
410
|
|
|
111
|
-
|
|
411
|
+
## Debugging
|
|
112
412
|
|
|
113
|
-
|
|
114
|
-
const { determineAction, TokenType, ActionType } = require('@synthient/synthient');
|
|
413
|
+
`onResponse` is called after every API response, including retries, pages, and stream handshakes, with the status, request ID, and headers:
|
|
115
414
|
|
|
116
|
-
|
|
117
|
-
|
|
415
|
+
```ts
|
|
416
|
+
const client = new Synthient({
|
|
417
|
+
onResponse: ({ status, requestID, headers }) => {
|
|
418
|
+
console.log(`status=${status} request_id=${requestID}`);
|
|
419
|
+
const remaining = headers.get("ratelimit-remaining");
|
|
420
|
+
if (remaining !== null) {
|
|
421
|
+
console.log(`rate limit: ${remaining} of ${headers.get("ratelimit-limit")} left`);
|
|
422
|
+
}
|
|
423
|
+
},
|
|
424
|
+
});
|
|
118
425
|
```
|
|
119
426
|
|
|
120
|
-
|
|
427
|
+
The hook must be synchronous. An error it throws is emitted as a process warning, and the call continues.
|
|
428
|
+
|
|
429
|
+
> [!WARNING]
|
|
430
|
+
> Response headers can contain secrets, such as presigned download URLs. Avoid logging `headers` in production.
|
|
431
|
+
|
|
432
|
+
## gRPC Schema
|
|
433
|
+
|
|
434
|
+
The `@synthient/synthient/grpcschema` subpath fetches the protobuf schema of the [Synthient gRPC API](https://docs.synthient.com/grpc) through server reflection. It needs two optional peer dependencies:
|
|
121
435
|
|
|
122
|
-
|
|
436
|
+
```sh
|
|
437
|
+
npm add @grpc/grpc-js @bufbuild/protobuf
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
```ts
|
|
441
|
+
import { SchemaError, explain, fetchSchema } from "@synthient/synthient/grpcschema";
|
|
123
442
|
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
443
|
+
try {
|
|
444
|
+
const schema = await fetchSchema();
|
|
445
|
+
for (const file of schema.descriptorSet.file) {
|
|
446
|
+
console.log(file.name, file.package);
|
|
447
|
+
}
|
|
448
|
+
} catch (error) {
|
|
449
|
+
const explanation = explain(error);
|
|
450
|
+
if (error instanceof SchemaError && explanation !== "") {
|
|
451
|
+
throw new Error(`${explanation} ${error.message}`, { cause: error });
|
|
452
|
+
}
|
|
453
|
+
throw error;
|
|
454
|
+
}
|
|
455
|
+
```
|
|
128
456
|
|
|
129
|
-
|
|
457
|
+
`fetchSchema` reads the key from `SYNTHIENT_API_KEY` unless you pass `apiKey`. `schema.descriptorSet` is a `FileDescriptorSet` from `@bufbuild/protobuf`. `explain` describes common gRPC errors in plain language.
|
|
130
458
|
|
|
131
|
-
|
|
132
|
-
- `ALLOW`: Allow the visitor to continue.
|
|
133
|
-
- `REDIRECT`: Redirect the visitor to a different page or have them perform another form of verification.
|
|
134
|
-
- `BLOCK`: Block the visitor from accessing.
|
|
459
|
+
# Development
|
|
135
460
|
|
|
136
|
-
|
|
461
|
+
## Maturity
|
|
137
462
|
|
|
138
|
-
The
|
|
139
|
-
- `LOW`: Low risk.
|
|
140
|
-
- `MEDIUM`: Medium risk.
|
|
141
|
-
- `HIGH`: High risk.
|
|
463
|
+
This SDK follows [Semantic Versioning](https://semver.org). Breaking changes ship only in a new major version. The 1.x versions on npm are an older, deprecated client with a different API.
|
|
142
464
|
|
|
465
|
+
## Contributions
|
|
143
466
|
|
|
144
|
-
|
|
467
|
+
Bug reports and feature requests are welcome as [GitHub issues](https://github.com/synthient/synthient-node/issues). For questions about the API or your account, contact [Synthient support](https://docs.synthient.com/misc/support).
|
|
145
468
|
|
|
469
|
+
## License
|
|
146
470
|
|
|
147
|
-
|
|
148
|
-
For any issues or feature requests, please open an issue on the GitHub repository
|
|
471
|
+
[Apache 2.0](LICENSE)
|