@synthient/synthient 1.0.1 → 2.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.
@@ -0,0 +1,341 @@
1
+ /**
2
+ * A Unix time as sent by the API. It is in seconds, except the `timestamp` of anonymizer
3
+ * and Helios HTTP, HTTPS, and DNS stream events, which is in milliseconds. Convert
4
+ * either with {@link toDate}.
5
+ */
6
+ export type UnixTime = number;
7
+ /** New values may be added. */
8
+ export type NetworkType = "MOBILE" | "SATELLITE" | "IN_FLIGHT_WIFI" | "RESIDENTIAL" | "CORPORATE" | "ACADEMIC" | "DATACENTER" | "GOVERNMENT" | (string & {});
9
+ /** New values may be added. */
10
+ export type DeviceOS = "Android" | "Chrome OS" | "FreeBSD" | "iOS" | "Linux" | "Mac OS X" | "Windows" | (string & {});
11
+ /**
12
+ * New values may be added. WHOIS_STREAM, NETWORK_IOCS_FEED, NETWORK_IOCS_STREAM,
13
+ * FILE_IOCS_FEED, and FILE_IOCS_STREAM are reserved for upcoming feeds, and HELIOS is a
14
+ * dashboard permission that authorizes no API operation. ADMIN_PROXIES is deprecated:
15
+ * it never authorized an API operation, the API no longer lists it, and it will be
16
+ * removed in the next major version.
17
+ */
18
+ export type Scope = "BASIC" | "PROXY_FEEDS" | "PROXY_FIREHOSE" | "ANONYMIZERS_FEED" | "ANONYMIZERS_STREAM" | "JA3_FEED" | "JA3_STREAM" | "TORRENTS_FEED" | "TORRENTS_STREAM" | "HONEYPOT_HTTP_FEED" | "HONEYPOT_HTTP_STREAM" | "HONEYPOT_HTTPS_FEED" | "HONEYPOT_HTTPS_STREAM" | "HONEYPOT_ADB_FEED" | "HONEYPOT_ADB_STREAM" | "HONEYPOT_DNS_FEED" | "HONEYPOT_DNS_STREAM" | "JA4_FEED" | "JA4_STREAM" | "JA4T_FEED" | "JA4T_STREAM" | "HELIOS" | "WHOIS_FEED" | "WHOIS_STREAM" | "GEOLOCATION_FEED" | "NETWORK_IOCS_FEED" | "NETWORK_IOCS_STREAM" | "FILE_IOCS_FEED" | "FILE_IOCS_STREAM" | "ADMIN_PROXIES" | (string & {});
19
+ /** The API always sends one of these sentences. */
20
+ export type ActivityCadence = "No activity in the last 30 days." | "Activity is evenly distributed across the day." | "Activity follows a weekday business-hours pattern." | "Activity follows a weekend pattern." | "Activity is burst-driven with significant peaks.";
21
+ /**
22
+ * New values may be added. The datasets also send types such as "double", "date",
23
+ * "timestamp", and "list<string>".
24
+ */
25
+ export type ParquetType = "string" | "int64" | "uint32" | "uint64" | "bool" | "bytes" | (string & {});
26
+ /** Converts a {@link UnixTime} to a Date, reading values of 1e12 or more as milliseconds. */
27
+ export declare function toDate(timestamp: UnixTime): Date;
28
+ /**
29
+ * `network` is absent when the address lies in no known network range or the API's
30
+ * enrichment lookup failed, and `location` is absent along with it. `intelligence` is
31
+ * absent when the API has no data for it.
32
+ */
33
+ export interface IPInfo {
34
+ ip: string;
35
+ network?: Network;
36
+ location?: Location;
37
+ intelligence?: Intelligence;
38
+ }
39
+ /** The network that announces an address. */
40
+ export interface Network {
41
+ /** The autonomous system number, or 0 if the address is not routed. */
42
+ asn: number;
43
+ isp: string;
44
+ type: NetworkType;
45
+ /** The organization the address is registered to. */
46
+ org?: string;
47
+ domain?: string;
48
+ abuse_email?: string;
49
+ abuse_phone?: string;
50
+ }
51
+ export interface Location {
52
+ /** The ISO 3166-1 alpha-2 country code. */
53
+ country: string;
54
+ /** The state or region. */
55
+ state: string;
56
+ city: string;
57
+ /** The IANA time zone name. */
58
+ timezone: string;
59
+ /** The latitude in degrees. */
60
+ latitude: number;
61
+ /** The longitude in degrees. */
62
+ longitude: number;
63
+ geo_hash: string;
64
+ }
65
+ export interface Intelligence {
66
+ /** The risk of the address, from 0 to 100. */
67
+ risk_score: number;
68
+ /** The kinds of services seen on the address, such as "RESIDENTIAL_PROXY". New values may be added. */
69
+ categories: string[];
70
+ /** New values may be added. */
71
+ behavior: string[];
72
+ /**
73
+ * The proxy, VPN, and anonymizer services seen using the address. An empty list does
74
+ * not mean the address is clean.
75
+ */
76
+ providers: Provider[];
77
+ devices: Device[];
78
+ }
79
+ /** A proxy, VPN, or anonymizer service seen using an address. */
80
+ export interface Provider {
81
+ /** The service tag, such as "BRIGHTDATA". */
82
+ provider: string;
83
+ /** The service category. */
84
+ type: string;
85
+ last_seen: UnixTime;
86
+ }
87
+ export interface Device {
88
+ os: DeviceOS;
89
+ /** The operating system version. */
90
+ version: string;
91
+ last_seen: UnixTime;
92
+ }
93
+ /**
94
+ * The honeypot traffic Synthient has observed for a domain.
95
+ *
96
+ * @deprecated Domain lookup was removed from the Synthient API and will stop working when
97
+ * the endpoint is turned off. It will be removed in the next major version.
98
+ */
99
+ export interface DomainInfo {
100
+ domain: string;
101
+ /**
102
+ * "active" when the domain had events in the last 24 hours. A domain that was never
103
+ * observed is "inactive" with zeroed stats.
104
+ */
105
+ status: "active" | "inactive";
106
+ stats: DomainStats;
107
+ unique_ips: UniqueIPs;
108
+ /** Daily event counts. */
109
+ time_series: TimeSeriesPoint[];
110
+ /** The network that sent the most events, absent when there are none. */
111
+ top_asn?: ASNCount;
112
+ top_subdomains: SubdomainCount[];
113
+ top_ports: PortCount[];
114
+ /** Event counts by source country. */
115
+ geo_distribution: CountryCount[];
116
+ /**
117
+ * Event counts over the last 30 days as 7 rows, Monday first, of 24 hourly columns,
118
+ * all in UTC.
119
+ */
120
+ hour_dow_heatmap: number[][];
121
+ activity_stats: ActivityStats;
122
+ /** The most recent events, capped by the `limit` passed to `lookupDomain`. */
123
+ recent_events: DomainEvent[];
124
+ }
125
+ export interface DomainStats {
126
+ events_24h: number;
127
+ total_events_30d: number;
128
+ }
129
+ /** Counts of the distinct source addresses seen for a domain. */
130
+ export interface UniqueIPs {
131
+ value_24h: number;
132
+ value_30d: number;
133
+ /** Hourly counts for the last 24 hours. */
134
+ sparkline_24h: number[];
135
+ }
136
+ /** The event counts for one day. */
137
+ export interface TimeSeriesPoint {
138
+ /** The start of the UTC day. */
139
+ date: UnixTime;
140
+ events: number;
141
+ unique_ips: number;
142
+ }
143
+ export interface ASNCount {
144
+ asn: number;
145
+ events: number;
146
+ }
147
+ export interface SubdomainCount {
148
+ subdomain: string;
149
+ count: number;
150
+ }
151
+ export interface PortCount {
152
+ /** The targeted port. */
153
+ port: number;
154
+ count: number;
155
+ }
156
+ export interface CountryCount {
157
+ /** The ISO 3166-1 alpha-2 country code. */
158
+ country_code: string;
159
+ events: number;
160
+ unique_ips: number;
161
+ }
162
+ export interface ActivityStats {
163
+ cadence: ActivityCadence;
164
+ median_per_hour: number;
165
+ p95_per_hour: number;
166
+ /** The busiest UTC hour, from 0 to 23, over the last 30 days. */
167
+ peak_hour: number;
168
+ /** The quietest UTC hour, from 0 to 23, over the last 30 days. */
169
+ quiet_hour: number;
170
+ }
171
+ export interface DomainEvent {
172
+ timestamp: UnixTime;
173
+ /** The full proxy exit address that carried the event. Despite the name, it is not masked. */
174
+ source_ip_masked: string;
175
+ target_subdomain: string;
176
+ /** The source country. */
177
+ country_code: string;
178
+ /** The targeted port. */
179
+ port: number;
180
+ }
181
+ export interface Account {
182
+ email: string;
183
+ first_name: string;
184
+ last_name: string;
185
+ organization: Organization;
186
+ /** The permissions granted to the key. */
187
+ scopes: Scope[];
188
+ lookup_quota: LookupQuota;
189
+ /** The API key used for the request. */
190
+ api_key?: AccountAPIKey;
191
+ }
192
+ export interface Organization {
193
+ id: string;
194
+ name: string;
195
+ /** The account's role in the organization. */
196
+ relation: "OWNER" | "ADMIN" | "MEMBER";
197
+ }
198
+ export interface LookupQuota {
199
+ credits: number;
200
+ /** Seconds until the credits reset. */
201
+ resets_in: number;
202
+ }
203
+ export interface AccountAPIKey {
204
+ /** The key ID. It is not the secret key. */
205
+ id: string;
206
+ name: string;
207
+ /** When the key was created, as an RFC 3339 string. */
208
+ created_at: string;
209
+ }
210
+ /** Whether an export covers a UTC day or a UTC hour. */
211
+ export type ExportKind = "hourly" | "daily";
212
+ /**
213
+ * The format of an export file. Feeds have only "parquet". The geolocation dataset adds
214
+ * "csv", which is gzip-compressed, and "mmdb", a MaxMind DB. The WHOIS dataset is one
215
+ * "tar.gz" archive of parquet files.
216
+ */
217
+ export type ExportFormat = "parquet" | "csv" | "mmdb" | "tar.gz";
218
+ /**
219
+ * "full" is every sighting. "lite" is the snapshot deduplicated to the latest row in its
220
+ * hour or day, with the same columns: one row per address and provider for proxies, per
221
+ * address, fingerprint, and provider for JA4T, and per range and provider for
222
+ * anonymizers.
223
+ */
224
+ export type ExportVariant = "full" | "lite";
225
+ /** A parquet file inside a WHOIS archive. */
226
+ export type WhoisEntity = "asns" | "networks" | "organisations" | "contacts" | "maintainers" | "transfers" | "delegations";
227
+ /** One page of a feed's exports, newest first. */
228
+ export interface ExportPage {
229
+ /** The feed's stream identifier, such as "proxies". */
230
+ stream: string;
231
+ /** The exports on this page. */
232
+ feeds: Export[];
233
+ /** Pass it as `cursor` to fetch the next page. It is absent, null, or "" on the last page. */
234
+ next_cursor?: string | null;
235
+ }
236
+ /** An export of a feed or dataset. */
237
+ export interface Export {
238
+ /**
239
+ * Identifies the export: "YYYY-MM-DD" for a daily export, "YYYY-MM-DD/H" with an
240
+ * unpadded hour for an hourly one, or "latest" for the newest hourly export on the
241
+ * first page. Pass it to `download`.
242
+ */
243
+ id: string;
244
+ kind: ExportKind;
245
+ /** The UTC day of the export as "YYYY-MM-DD". */
246
+ date: string;
247
+ /** The UTC hour of an hourly export, absent or null for a daily export. */
248
+ hour?: number | null;
249
+ /** The size in bytes of the first file in `formats`. */
250
+ size_bytes: number;
251
+ /** The number of rows. For WHOIS, the sum of its entities' rows. */
252
+ row_count: number;
253
+ /** The hex-encoded SHA-256 of the first file in `formats`. */
254
+ checksum: string;
255
+ created_at: UnixTime;
256
+ /** The API path of the export's download, including the version prefix. */
257
+ download_path: string;
258
+ /** Every file of the export, its own format first. */
259
+ formats: ExportFile[];
260
+ /** The parquet files inside a WHOIS archive, absent for other exports. */
261
+ entities?: ExportEntity[];
262
+ /**
263
+ * "lite" in a lite listing, where the sizes, checksum, and `download_path` describe the
264
+ * lite file, and absent otherwise. `id` is the same for both variants, so pass the
265
+ * variant again to download the lite file.
266
+ */
267
+ variant?: ExportVariant;
268
+ }
269
+ export interface ExportMeta {
270
+ id: string;
271
+ stream: string;
272
+ kind: ExportKind;
273
+ /** The format of the file that `checksum`, `size`, and `schema` describe. */
274
+ format: ExportFormat;
275
+ /** The start of the export: midnight UTC for a daily export, the hour for an hourly one. */
276
+ date: UnixTime;
277
+ /** The UTC hour of an hourly export, absent or null for a daily export. */
278
+ hour?: number | null;
279
+ rows: number;
280
+ /** The size of the file in bytes. */
281
+ size: number;
282
+ /** The hex-encoded SHA-256 of the file. */
283
+ checksum: string;
284
+ created_at: UnixTime;
285
+ /** The file's columns. A WHOIS archive has none; its parquet files list theirs in `entities`. */
286
+ schema: ParquetSchema;
287
+ /** Every file of the export, its own format first. */
288
+ formats: ExportFile[];
289
+ /** The parquet files inside a WHOIS archive, each with its columns, absent for other exports. */
290
+ entities?: ExportEntity[];
291
+ /**
292
+ * "lite" for a lite export, where the checksum, size, rows, schema, and formats describe
293
+ * the lite file, and absent otherwise.
294
+ */
295
+ variant?: ExportVariant;
296
+ }
297
+ /** One file of an export. */
298
+ export interface ExportFile {
299
+ format: ExportFormat;
300
+ size_bytes: number;
301
+ /** The hex-encoded SHA-256 of the file as downloaded, so of the gzip file for "csv". */
302
+ checksum: string;
303
+ }
304
+ /** A parquet file inside a WHOIS archive. */
305
+ export interface ExportEntity {
306
+ entity: WhoisEntity;
307
+ row_count: number;
308
+ size_bytes: number;
309
+ /** The hex-encoded SHA-256 of the parquet file. */
310
+ checksum: string;
311
+ /** The parquet file's columns, present only in `exportMeta` results. */
312
+ schema?: ParquetSchema;
313
+ }
314
+ /** The rows and bytes a feed or dataset exported per UTC day. */
315
+ export interface ExportVolume {
316
+ /** The feed's stream identifier, such as "proxies". */
317
+ stream: string;
318
+ /** Oldest first. Today is included while in progress, and days without exports are left out. */
319
+ days: ExportVolumeDay[];
320
+ }
321
+ export interface ExportVolumeDay {
322
+ /** The UTC day as "YYYY-MM-DD". */
323
+ date: string;
324
+ /**
325
+ * "daily" when the day's rollup is counted. "hourly" when its hourly exports are summed
326
+ * instead, as for today or a day whose rollup is still pending.
327
+ */
328
+ kind: ExportKind;
329
+ /** The number of files counted: 1 for a rollup, otherwise the hourly exports so far, of 24. */
330
+ snapshots: number;
331
+ row_count: number;
332
+ size_bytes: number;
333
+ }
334
+ export interface ParquetSchema {
335
+ /** The columns in file order. */
336
+ fields: ParquetColumn[];
337
+ }
338
+ export interface ParquetColumn {
339
+ name: string;
340
+ type: ParquetType;
341
+ }
package/dist/types.js ADDED
@@ -0,0 +1,4 @@
1
+ /** Converts a {@link UnixTime} to a Date, reading values of 1e12 or more as milliseconds. */
2
+ export function toDate(timestamp) {
3
+ return new Date(timestamp >= 1e12 ? timestamp : timestamp * 1000);
4
+ }
@@ -0,0 +1,2 @@
1
+ /** The client sends it in the User-Agent header. */
2
+ export declare const VERSION = "2.1.0";
@@ -0,0 +1,2 @@
1
+ /** The client sends it in the User-Agent header. */
2
+ export const VERSION = "2.1.0";
package/package.json CHANGED
@@ -1,19 +1,77 @@
1
1
  {
2
2
  "name": "@synthient/synthient",
3
- "version": "1.0.1",
4
- "main": "dist/index.js",
3
+ "version": "2.1.0",
4
+ "description": "The official Node.js client for the Synthient API.",
5
+ "keywords": [
6
+ "synthient",
7
+ "ip intelligence",
8
+ "proxy detection",
9
+ "vpn detection",
10
+ "threat intelligence"
11
+ ],
12
+ "homepage": "https://synthient.com",
13
+ "bugs": "https://github.com/synthient/synthient-node/issues",
14
+ "repository": {
15
+ "type": "git",
16
+ "url": "git+https://github.com/synthient/synthient-node.git"
17
+ },
18
+ "license": "Apache-2.0",
19
+ "author": "Synthient",
20
+ "type": "module",
21
+ "exports": {
22
+ ".": {
23
+ "types": "./dist/index.d.ts",
24
+ "default": "./dist/index.js"
25
+ },
26
+ "./grpcschema": {
27
+ "types": "./dist/grpcschema.d.ts",
28
+ "default": "./dist/grpcschema.js"
29
+ },
30
+ "./package.json": "./package.json"
31
+ },
32
+ "files": [
33
+ "dist"
34
+ ],
35
+ "sideEffects": false,
36
+ "engines": {
37
+ "node": ">=22.12.0"
38
+ },
39
+ "publishConfig": {
40
+ "access": "public"
41
+ },
5
42
  "scripts": {
6
- "build": "tsc"
43
+ "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
44
+ "typecheck": "tsc",
45
+ "test": "node --test \"test/*.test.ts\"",
46
+ "lint": "eslint . && prettier --check .",
47
+ "format": "prettier --write .",
48
+ "check:package": "sh scripts/check-package.sh",
49
+ "prepack": "npm run build"
7
50
  },
8
- "dependencies": {
9
- "axios": "^0.24.0"
51
+ "peerDependencies": {
52
+ "@bufbuild/protobuf": "^2.2.0",
53
+ "@grpc/grpc-js": "^1.10.0"
10
54
  },
11
- "devDependencies": {
12
- "typescript": "^4.5.4",
13
- "@types/node": "^16.11.7"
55
+ "peerDependenciesMeta": {
56
+ "@bufbuild/protobuf": {
57
+ "optional": true
58
+ },
59
+ "@grpc/grpc-js": {
60
+ "optional": true
61
+ }
14
62
  },
15
- "types": "./dist/index.d.ts",
16
- "description": "Node.js client for the Synthient API.",
17
- "author": "",
18
- "license": "ISC"
63
+ "devDependencies": {
64
+ "@arethetypeswrong/cli": "^0.18.5",
65
+ "@bufbuild/protobuf": "^2.16.0",
66
+ "@eslint/js": "^10.0.1",
67
+ "@grpc/grpc-js": "^1.14.5",
68
+ "@grpc/proto-loader": "^0.8.1",
69
+ "@grpc/reflection": "^1.0.4",
70
+ "@types/node": "^22.20.4",
71
+ "eslint": "^10.11.0",
72
+ "prettier": "^3.9.9",
73
+ "publint": "^0.3.24",
74
+ "typescript": "~6.0.3",
75
+ "typescript-eslint": "^8.71.0"
76
+ }
19
77
  }
@@ -1,2 +0,0 @@
1
- export declare const API_URL = "https://api.synthient.com/api/v1/";
2
- export declare const DEFAULT_TIMEOUT = 5000;
package/dist/constants.js DELETED
@@ -1,5 +0,0 @@
1
- "use strict";
2
- Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.DEFAULT_TIMEOUT = exports.API_URL = void 0;
4
- exports.API_URL = "https://api.synthient.com/api/v1/";
5
- exports.DEFAULT_TIMEOUT = 5000;
@@ -1,33 +0,0 @@
1
- /**
2
- * Base exception class
3
- */
4
- export declare class SynthientException extends Error {
5
- /**
6
- * Constructs a new SynthientException.
7
- *
8
- * @param message - The error message.
9
- */
10
- constructor(message: string);
11
- }
12
- /**
13
- * Raised when the server returns a 500.
14
- */
15
- export declare class InternalServerError extends SynthientException {
16
- /**
17
- * Constructs a new InternalServerError.
18
- *
19
- * @param message - The error message.
20
- */
21
- constructor(message: string);
22
- }
23
- /**
24
- * Raised when the server returns a 400 or 401.
25
- */
26
- export declare class ErrorResponse extends SynthientException {
27
- /**
28
- * Constructs a new ErrorResponse.
29
- *
30
- * @param message - The error message.
31
- */
32
- constructor(message: string);
33
- }
@@ -1,48 +0,0 @@
1
- "use strict";
2
- Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.ErrorResponse = exports.InternalServerError = exports.SynthientException = void 0;
4
- /**
5
- * Base exception class
6
- */
7
- class SynthientException extends Error {
8
- /**
9
- * Constructs a new SynthientException.
10
- *
11
- * @param message - The error message.
12
- */
13
- constructor(message) {
14
- super(message);
15
- this.name = "SynthientException";
16
- }
17
- }
18
- exports.SynthientException = SynthientException;
19
- /**
20
- * Raised when the server returns a 500.
21
- */
22
- class InternalServerError extends SynthientException {
23
- /**
24
- * Constructs a new InternalServerError.
25
- *
26
- * @param message - The error message.
27
- */
28
- constructor(message) {
29
- super(message);
30
- this.name = "InternalServerError";
31
- }
32
- }
33
- exports.InternalServerError = InternalServerError;
34
- /**
35
- * Raised when the server returns a 400 or 401.
36
- */
37
- class ErrorResponse extends SynthientException {
38
- /**
39
- * Constructs a new ErrorResponse.
40
- *
41
- * @param message - The error message.
42
- */
43
- constructor(message) {
44
- super(message);
45
- this.name = "ErrorResponse";
46
- }
47
- }
48
- exports.ErrorResponse = ErrorResponse;