zeno.id 0.1.0 → 0.3.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/README.md +255 -32
- package/dist/index.cjs +69 -69
- package/dist/index.d.cts +8 -8
- package/dist/index.d.ts +8 -8
- package/dist/index.js +69 -69
- package/dist/server/index.cjs +787 -0
- package/dist/server/index.d.cts +618 -0
- package/dist/server/index.d.ts +618 -0
- package/dist/server/index.js +781 -0
- package/dist/server/node.cjs +88 -0
- package/dist/server/node.d.cts +21 -0
- package/dist/server/node.d.ts +21 -0
- package/dist/server/node.js +87 -0
- package/dist/server/proxy-CUZ-Jwgy.d.cts +36 -0
- package/dist/server/proxy-CUZ-Jwgy.d.ts +36 -0
- package/package.json +36 -5
|
@@ -0,0 +1,618 @@
|
|
|
1
|
+
import { a as ApiOptions, i as ApiKey, n as ProxyOptions, r as createProxy, t as ProxyHandler } from "./proxy-CUZ-Jwgy.js";
|
|
2
|
+
//#region src/server/index.d.ts
|
|
3
|
+
/** Every signal an event checks, the keys of its `signals`. */
|
|
4
|
+
declare const SIGNALS: readonly ['automation', 'headless', 'software-renderer', 'tampering', 'timezone-mismatch', 'privacy-settings', 'vpn', 'proxy', 'tor', 'datacenter', 'abusive-ip', 'incognito', 'virtual-machine', 'developer-tools', 'ai-agent', 'privacy-browser', 'rare-device', 'replayed', 'residential-proxy', 'private-relay', 'forged-payload', 'stored-id-rejected'];
|
|
5
|
+
type Signal = (typeof SIGNALS)[number];
|
|
6
|
+
/** The bot verdict: a known good bot (a search engine's crawler), a bad one (automation, a headless browser), or none. */
|
|
7
|
+
type Bot = 'good' | 'bad' | 'not-detected';
|
|
8
|
+
/**
|
|
9
|
+
* Why a signal's `detected` is `null`: what it reads was missing, so it couldn't be checked. The ip lookup failed or
|
|
10
|
+
* took too long; the browser or the connection gave no time zone; a browser probe timed out, failed or wasn't reported;
|
|
11
|
+
* Chromium's static storage quota, the same in normal and private windows; no WebGL or canvas; the project has too few
|
|
12
|
+
* visitors to call hardware rare; the request carried no nonce.
|
|
13
|
+
*/
|
|
14
|
+
type SignalReason = 'ip-lookup-failed' | 'ip-lookup-timeout' | 'no-time-zone' | 'no-ip-time-zone' | 'probe-timeout' | 'probe-failed' | 'not-collected' | 'no-webgl' | 'no-canvas' | 'too-few-visitors' | 'no-nonce';
|
|
15
|
+
type Confidence = 'high' | 'medium' | 'low';
|
|
16
|
+
/** A contradiction in the device's browser data, in `signals.tampering`. */
|
|
17
|
+
type Contradiction = 'platform-not-user-agent-os' | 'client-hints-not-user-agent-os' | 'gpu-not-user-agent-os' | 'browser-functions-overridden' | 'chromium-without-client-hints' | 'usable-area-larger-than-screen' | 'no-languages' | 'client-hints-blank' | 'client-hints-malformed' | 'clock-offset-not-time-zone' | 'standard-signals-missing' | 'window-larger-than-screen' | 'screen-not-css-screen' | 'codecs-not-claimed-browser' | 'api-surface-not-claimed-browser' | 'api-surface-rare-for-claimed-browser' | 'gpu-output-not-claimed-renderer' | 'canvas-challenge-not-consensus' | 'user-agent-not-request-header';
|
|
18
|
+
/**
|
|
19
|
+
* What gave away a payload the browser SDK didn't send, in `signals['forged-payload']`: fields the SDK reports from
|
|
20
|
+
* every browser were missing (`fields-missing`, named in `missingFields`), no nonce from a browser that always makes
|
|
21
|
+
* one (`nonce-missing`), a canvas challenge without the token it's drawn for (`challenge-without-token`), client hints
|
|
22
|
+
* the SDK's own report on them contradicts (`client-hints-not-probe`), or the request to your proxy route came from a
|
|
23
|
+
* client that isn't a browser (`request-not-from-browser`).
|
|
24
|
+
*/
|
|
25
|
+
type ForgedPayloadIndicator = 'fields-missing' | 'nonce-missing' | 'challenge-without-token' | 'client-hints-not-probe' | 'request-not-from-browser';
|
|
26
|
+
/** What makes a device look like a virtual machine, in `signals['virtual-machine']`. */
|
|
27
|
+
type VirtualMachineIndicator = 'vm-display-adapter' | 'no-gpu' | 'software-renderer' | 'two-cpu-cores-or-fewer' | 'two-gb-memory-or-less' | 'vm-screen-size' | 'no-speech-voices';
|
|
28
|
+
type Velocity = {
|
|
29
|
+
events: number;
|
|
30
|
+
distinctIp: number;
|
|
31
|
+
distinctExternalId: number;
|
|
32
|
+
distinctCountry: number;
|
|
33
|
+
/** The visitor's events with this event's `action`, this one included; 0 when it has none. */
|
|
34
|
+
sameAction: number;
|
|
35
|
+
/** Every visitor's events from the event's ip. */
|
|
36
|
+
ipEvents: number;
|
|
37
|
+
/** The ips and visitors the event's external id was seen with. */
|
|
38
|
+
distinctIpByExternalId: number;
|
|
39
|
+
distinctVisitorIdByExternalId: number;
|
|
40
|
+
};
|
|
41
|
+
/** What owns an ip address or runs its network. */
|
|
42
|
+
type NetworkOwnerType = 'isp' | 'hosting' | 'business' | 'education' | 'government' | 'banking';
|
|
43
|
+
/** Who owns the ip and where it is, from the ip lookup. */
|
|
44
|
+
type IpInfo = {
|
|
45
|
+
/** The country's two-letter code, like `US`. */
|
|
46
|
+
country?: string;
|
|
47
|
+
countryName?: string;
|
|
48
|
+
/** The ip's time zone, like `America/New_York`. */
|
|
49
|
+
timeZone?: string;
|
|
50
|
+
city?: string;
|
|
51
|
+
region?: string;
|
|
52
|
+
postalCode?: string;
|
|
53
|
+
continent?: string;
|
|
54
|
+
latitude?: number;
|
|
55
|
+
longitude?: number;
|
|
56
|
+
/** How precisely the lookup places the network. Behind a VPN it's still the exit's location. */
|
|
57
|
+
locationAccuracy?: 'very-high' | 'high' | 'medium' | 'low' | 'very-low';
|
|
58
|
+
/** The company that owns the address. */
|
|
59
|
+
company?: string;
|
|
60
|
+
/** What owns the address. */
|
|
61
|
+
companyType?: NetworkOwnerType;
|
|
62
|
+
/** 0 to 1: how much of the company's address space abuse reports name. */
|
|
63
|
+
companyAbuseScore?: number;
|
|
64
|
+
/** The hosting provider, when the address is in a datacenter. */
|
|
65
|
+
datacenterName?: string;
|
|
66
|
+
/** The autonomous system, like `AS64500`. */
|
|
67
|
+
asn?: string;
|
|
68
|
+
/** The network operator's name. */
|
|
69
|
+
networkName?: string;
|
|
70
|
+
/** What kind of network it is. */
|
|
71
|
+
networkType?: NetworkOwnerType;
|
|
72
|
+
/** The address range the ip is in, like `203.0.113.0/24`. */
|
|
73
|
+
networkRange?: string;
|
|
74
|
+
/** The VPN service whose exit this is. */
|
|
75
|
+
vpnProvider?: string;
|
|
76
|
+
/** When the ip was last seen as a VPN exit. */
|
|
77
|
+
vpnExitLastSeenAt?: string;
|
|
78
|
+
/** A managed service's exit, like `private-relay` for iCloud Private Relay. */
|
|
79
|
+
exitServiceType?: 'private-relay' | 'secure-web-gateway' | 'satellite' | 'dns-resolver' | 'email-gateway';
|
|
80
|
+
exitServiceProvider?: string;
|
|
81
|
+
mobileNetwork: boolean;
|
|
82
|
+
satelliteNetwork: boolean;
|
|
83
|
+
/** A crawler the lookup knows, like Googlebot's addresses. */
|
|
84
|
+
knownCrawler: boolean;
|
|
85
|
+
/** A private or reserved address that no one on the internet has. */
|
|
86
|
+
reservedAddress: boolean;
|
|
87
|
+
};
|
|
88
|
+
type BrowserDetails = {
|
|
89
|
+
browserName: string;
|
|
90
|
+
browserMajorVersion?: string;
|
|
91
|
+
browserFullVersion?: string;
|
|
92
|
+
os: string;
|
|
93
|
+
osVersion?: string;
|
|
94
|
+
device: string;
|
|
95
|
+
};
|
|
96
|
+
/** What some signals found, on their entry in `signals` when they're detected, each field only when there was one. */
|
|
97
|
+
type SignalDetails = {
|
|
98
|
+
vpn: {
|
|
99
|
+
confidence?: Confidence;
|
|
100
|
+
};
|
|
101
|
+
proxy: {
|
|
102
|
+
confidence?: Confidence;
|
|
103
|
+
};
|
|
104
|
+
'residential-proxy': {
|
|
105
|
+
confidence?: Confidence;
|
|
106
|
+
};
|
|
107
|
+
/** Browser data that contradicts itself; a score above 0.5 detects `tampering`. */
|
|
108
|
+
tampering: {
|
|
109
|
+
contradictionScore?: number;
|
|
110
|
+
antiDetectBrowser?: boolean;
|
|
111
|
+
contradictions?: Contradiction[];
|
|
112
|
+
};
|
|
113
|
+
/** How much the device looks like a virtual machine, 0 to 1, and why; from 0.6 it sets `virtual-machine`. */
|
|
114
|
+
'virtual-machine': {
|
|
115
|
+
score?: number;
|
|
116
|
+
indicators?: VirtualMachineIndicator[];
|
|
117
|
+
};
|
|
118
|
+
/** What gave the payload away, and the always-sent fields it lacked. */
|
|
119
|
+
'forged-payload': {
|
|
120
|
+
indicators?: ForgedPayloadIndicator[];
|
|
121
|
+
missingFields?: string[];
|
|
122
|
+
};
|
|
123
|
+
};
|
|
124
|
+
/**
|
|
125
|
+
* One signal on an event: detected (`true`, with the `points` it added to the risk score when more than 0, and what it
|
|
126
|
+
* found for the signals in `SignalDetails`), not detected (`false`), or `null` when it couldn't be checked, with why in
|
|
127
|
+
* `reason`. A signal that couldn't be checked adds no points, so read it next to the score.
|
|
128
|
+
*/
|
|
129
|
+
type SignalResult<S extends Signal = Signal> = ({
|
|
130
|
+
detected: true;
|
|
131
|
+
points?: number;
|
|
132
|
+
} & (S extends keyof SignalDetails ? SignalDetails[S] : Record<never, never>)) | {
|
|
133
|
+
detected: false;
|
|
134
|
+
} | {
|
|
135
|
+
detected: null;
|
|
136
|
+
reason: SignalReason;
|
|
137
|
+
};
|
|
138
|
+
/**
|
|
139
|
+
* Every signal Zeno checks, by name: the detected ones first, by the points they added (the verdict's `reasons` order),
|
|
140
|
+
* then the rest.
|
|
141
|
+
*/
|
|
142
|
+
type Signals = { [S in Signal]: SignalResult<S>; };
|
|
143
|
+
/**
|
|
144
|
+
* What a verdict's `action` is: let it through, challenge it (a captcha, an emailed code, a second factor) or refuse
|
|
145
|
+
* it.
|
|
146
|
+
*/
|
|
147
|
+
type VerdictAction = 'allow' | 'challenge' | 'block';
|
|
148
|
+
/** Why: the detected signals that scored, strongest first, and `bad-bot` for a bad bot. */
|
|
149
|
+
type VerdictReason = Signal | 'bad-bot';
|
|
150
|
+
/**
|
|
151
|
+
* What to do with the event, from its risk score and bot verdict: `block` for a bad bot or a risk score of 15 or more,
|
|
152
|
+
* `challenge` from 9 to 14, else `allow`.
|
|
153
|
+
*/
|
|
154
|
+
type Verdict = {
|
|
155
|
+
action: VerdictAction;
|
|
156
|
+
reasons: VerdictReason[];
|
|
157
|
+
};
|
|
158
|
+
/** An event's own key-values, as the browser set them: text, numbers or booleans, nothing nested. */
|
|
159
|
+
type Metadata = Record<string, string | number | boolean>;
|
|
160
|
+
type Event = {
|
|
161
|
+
requestId: string;
|
|
162
|
+
visitorId: string;
|
|
163
|
+
/** What to do with it: `allow`, `challenge` or `block`, and why. `client.verify` answers it with its own checks. */
|
|
164
|
+
verdict: Verdict;
|
|
165
|
+
/** 0 to 30: the detected signals' points, capped at 30. */
|
|
166
|
+
riskScore: number;
|
|
167
|
+
bot: Bot;
|
|
168
|
+
/** How sure the visitor id is, 0.1 to 1. */
|
|
169
|
+
confidence: number;
|
|
170
|
+
/**
|
|
171
|
+
* Whether the project had seen this visitor before the event, like the browser's `identify()` result. Not in search
|
|
172
|
+
* results.
|
|
173
|
+
*/
|
|
174
|
+
returning?: boolean;
|
|
175
|
+
externalId?: string;
|
|
176
|
+
/** What the visitor was doing, as the browser's `identify({ action })` named it, like `login`. */
|
|
177
|
+
action?: string;
|
|
178
|
+
/** Your own key-values from the browser's `identify({ metadata })`. Not in search results. */
|
|
179
|
+
metadata?: Metadata;
|
|
180
|
+
/** The id of the API key whose proxy route identified (search filters on it as `apiKeyId`). */
|
|
181
|
+
apiKeyId: string;
|
|
182
|
+
createdAt: string;
|
|
183
|
+
/** When `verify` attached its external id afterwards; that also sends an `update` webhook. */
|
|
184
|
+
updatedAt?: string;
|
|
185
|
+
/** When the project's retention removes it (ISO), 3 years after the event at most. Not in search results. */
|
|
186
|
+
expiresAt?: string;
|
|
187
|
+
origin?: string;
|
|
188
|
+
/** The page as origin and path, or only its origin; left out when the project keeps no page urls (`pageUrls`). */
|
|
189
|
+
url?: string;
|
|
190
|
+
referrer?: string;
|
|
191
|
+
userAgent: string;
|
|
192
|
+
/** Parsed on the server from the user agent and client hints. */
|
|
193
|
+
browserDetails: BrowserDetails;
|
|
194
|
+
ip: string;
|
|
195
|
+
/** Who owns the ip and where it is, with its `country` and `timeZone`; none when the lookup failed. */
|
|
196
|
+
ipInfo?: IpInfo;
|
|
197
|
+
/**
|
|
198
|
+
* Every signal Zeno checks: `detected` true, false, or null when it couldn't be checked (with a `reason`), the
|
|
199
|
+
* `points` a detected one added, and what it found. Read `event.signals.vpn.detected`.
|
|
200
|
+
*/
|
|
201
|
+
signals: Signals;
|
|
202
|
+
/** Only on getEvent and verify, not in webhooks or sealed results. */
|
|
203
|
+
velocity?: Record<'5m' | '1h' | '24h', Velocity>;
|
|
204
|
+
};
|
|
205
|
+
/** A list filter takes one value, or several to match any of. */
|
|
206
|
+
type AnyOf<T> = T | T[];
|
|
207
|
+
type SearchFilters = {
|
|
208
|
+
apiKeyId?: AnyOf<string>;
|
|
209
|
+
visitorId?: string;
|
|
210
|
+
externalId?: string;
|
|
211
|
+
ip?: string;
|
|
212
|
+
requestId?: string;
|
|
213
|
+
country?: AnyOf<string>;
|
|
214
|
+
origin?: AnyOf<string>;
|
|
215
|
+
asn?: AnyOf<string>;
|
|
216
|
+
/** A name and major version as the dashboard shows them, "Chrome 156", or a name alone for every version, "Chrome". */
|
|
217
|
+
browser?: AnyOf<string>;
|
|
218
|
+
os?: AnyOf<string>;
|
|
219
|
+
action?: AnyOf<string>;
|
|
220
|
+
signal?: AnyOf<Signal>;
|
|
221
|
+
bot?: AnyOf<Bot>;
|
|
222
|
+
minRiskScore?: number;
|
|
223
|
+
/**
|
|
224
|
+
* Inclusive. Without it the search covers the 30 days before `end` (or now), unless it looks up a `visitorId`,
|
|
225
|
+
* `externalId`, `ip` or `requestId`, which search everything kept.
|
|
226
|
+
*/
|
|
227
|
+
start?: Date | string | number;
|
|
228
|
+
/** Inclusive; a date alone, like "2026-10-25", takes in that whole UTC day. */
|
|
229
|
+
end?: Date | string | number;
|
|
230
|
+
limit?: number;
|
|
231
|
+
cursor?: string;
|
|
232
|
+
};
|
|
233
|
+
/**
|
|
234
|
+
* An event as the search lists it: a subset of the event's own fields, with the same names. It leaves out `returning`,
|
|
235
|
+
* `metadata`, `updatedAt`, `expiresAt`, `url`, `referrer` and `velocity`; its `signals` list only the detected ones, as
|
|
236
|
+
* `{ detected: true }` (get the event for the rest), its `browserDetails` holds the browser's and the os's name and
|
|
237
|
+
* version, and its `ipInfo` the country, city, asn and company, each left out when the event has none of them.
|
|
238
|
+
*/
|
|
239
|
+
type SearchEvent = Pick<Event, 'requestId' | 'visitorId' | 'verdict' | 'riskScore' | 'bot' | 'confidence' | 'externalId' | 'action' | 'apiKeyId' | 'createdAt' | 'origin' | 'userAgent' | 'ip'> & {
|
|
240
|
+
signals: { [S in Signal]?: {
|
|
241
|
+
detected: true;
|
|
242
|
+
}; };
|
|
243
|
+
browserDetails?: Partial<Pick<BrowserDetails, 'browserName' | 'browserMajorVersion' | 'os' | 'osVersion'>>;
|
|
244
|
+
ipInfo?: Pick<IpInfo, 'country' | 'city' | 'asn' | 'company'>;
|
|
245
|
+
};
|
|
246
|
+
/** A page of a list: pass `cursor` back for the next one; none on the last. */
|
|
247
|
+
type Page<T> = {
|
|
248
|
+
items: T[];
|
|
249
|
+
cursor?: string;
|
|
250
|
+
};
|
|
251
|
+
/**
|
|
252
|
+
* A page of events; the first page (no `cursor` passed) also says how many match, up to 10,000 (`10000` is that many or
|
|
253
|
+
* more).
|
|
254
|
+
*/
|
|
255
|
+
type SearchResult = Page<SearchEvent> & {
|
|
256
|
+
found?: number;
|
|
257
|
+
};
|
|
258
|
+
/**
|
|
259
|
+
* A visitor: `externalIds` the latest 10 external ids seen with it, newest first, and `externalIdCount` how many there
|
|
260
|
+
* are in all; `signals` holds every signal any of its events detected, as `{ detected: true }`, and `recentEvents` its
|
|
261
|
+
* 20 latest events, newest first, each with its detected signals the same way and `ipInfo.country` when known.
|
|
262
|
+
*/
|
|
263
|
+
type Visitor = {
|
|
264
|
+
visitorId: string;
|
|
265
|
+
externalIds: string[];
|
|
266
|
+
externalIdCount: number;
|
|
267
|
+
signals: { [S in Signal]?: {
|
|
268
|
+
detected: true;
|
|
269
|
+
}; };
|
|
270
|
+
eventCount: number;
|
|
271
|
+
firstSeenAt: string;
|
|
272
|
+
lastSeenAt: string;
|
|
273
|
+
recentEvents: (Pick<SearchEvent, 'requestId' | 'externalId' | 'createdAt' | 'ip' | 'signals'> & {
|
|
274
|
+
ipInfo?: Pick<IpInfo, 'country'>;
|
|
275
|
+
})[];
|
|
276
|
+
};
|
|
277
|
+
/**
|
|
278
|
+
* What relates two users: the built-in `visitor-id` (a browser, from events only) and `ip`, or a type of your own like
|
|
279
|
+
* `phone` or `referral` (a lowercase letter, then up to 31 lowercase letters, digits, `_` or `-`).
|
|
280
|
+
*/
|
|
281
|
+
type RelatedType = 'visitor-id' | 'ip' | (string & {});
|
|
282
|
+
/**
|
|
283
|
+
* `identifier`, a value several users can share (a visitor id, a phone number); `relation`, a direct tie between two
|
|
284
|
+
* users (a referral, an invite). A type of your own keeps the kind its first relation gave it.
|
|
285
|
+
*/
|
|
286
|
+
type RelatedKind = 'identifier' | 'relation';
|
|
287
|
+
type ValueDetails = {
|
|
288
|
+
type: RelatedType;
|
|
289
|
+
/** The type's weight, 0 to 1: how much sharing it says two users are one person. */
|
|
290
|
+
weight: number;
|
|
291
|
+
/** Your own word for what happened, like `checkout` or `signup`, when it was added by hand with one. */
|
|
292
|
+
action?: string;
|
|
293
|
+
/** When it happened: the `at` of one added by hand (its latest call's), or when the first event brought it. */
|
|
294
|
+
at: string;
|
|
295
|
+
createdAt: string;
|
|
296
|
+
};
|
|
297
|
+
/** One of a user's values: a value they have, or the other user of a relation. */
|
|
298
|
+
type RelatedValue = (ValueDetails & {
|
|
299
|
+
kind: 'identifier';
|
|
300
|
+
value: string;
|
|
301
|
+
}) | (ValueDetails & {
|
|
302
|
+
kind: 'relation';
|
|
303
|
+
relatedExternalId: string;
|
|
304
|
+
});
|
|
305
|
+
type RelatedValues = {
|
|
306
|
+
externalId: string;
|
|
307
|
+
/**
|
|
308
|
+
* Shares one value weighing 0.5 or more with another user: a visitor id does, a shared ip never. Lesser ties never
|
|
309
|
+
* add up to one, and a relation (a referral) never makes one.
|
|
310
|
+
*/
|
|
311
|
+
duplicate: boolean;
|
|
312
|
+
/** Was ever identified in a browser; treat a user who wasn't as unverified. */
|
|
313
|
+
identified: boolean;
|
|
314
|
+
values: RelatedValue[];
|
|
315
|
+
/** More values than the 500 answered. */
|
|
316
|
+
truncated: boolean;
|
|
317
|
+
};
|
|
318
|
+
/**
|
|
319
|
+
* Another user (`externalId`) who has a value the asked one has, or the other user of a relation (`relatedExternalId`),
|
|
320
|
+
* which needs no value.
|
|
321
|
+
*/
|
|
322
|
+
type Connection = (ValueDetails & {
|
|
323
|
+
kind: 'identifier';
|
|
324
|
+
externalId: string;
|
|
325
|
+
value: string;
|
|
326
|
+
}) | (ValueDetails & {
|
|
327
|
+
kind: 'relation';
|
|
328
|
+
relatedExternalId: string;
|
|
329
|
+
});
|
|
330
|
+
type Related = {
|
|
331
|
+
externalId: string;
|
|
332
|
+
/** The type asked for; none when every type was walked. */
|
|
333
|
+
type?: RelatedType;
|
|
334
|
+
/**
|
|
335
|
+
* Every other user reached, heaviest first, each with its `weight` to the asked one: what the two share combined
|
|
336
|
+
* (`1 - Π(1 - weight)`, so with the default weights two shared ips make 0.64 and a browser and an ip 0.88),
|
|
337
|
+
* multiplied along the strongest path for a user further away. With the users each shares a value with or is
|
|
338
|
+
* related to.
|
|
339
|
+
*/
|
|
340
|
+
externalIds: {
|
|
341
|
+
externalId: string;
|
|
342
|
+
weight: number;
|
|
343
|
+
connections: Connection[];
|
|
344
|
+
}[];
|
|
345
|
+
/** The users the asked one shares a value with or is related to. */
|
|
346
|
+
connections: Connection[];
|
|
347
|
+
};
|
|
348
|
+
/** One of your users who has a value, and since when. */
|
|
349
|
+
type RelatedUser = {
|
|
350
|
+
externalId: string;
|
|
351
|
+
createdAt: string;
|
|
352
|
+
};
|
|
353
|
+
/** A value more than one user shares, or for a relation type the two users it ties and how many times. */
|
|
354
|
+
type SharedValue = {
|
|
355
|
+
type: RelatedType;
|
|
356
|
+
weight: number;
|
|
357
|
+
value: string;
|
|
358
|
+
count: number;
|
|
359
|
+
} | {
|
|
360
|
+
type: RelatedType;
|
|
361
|
+
weight: number;
|
|
362
|
+
externalIds: [string, string];
|
|
363
|
+
count: number;
|
|
364
|
+
};
|
|
365
|
+
/**
|
|
366
|
+
* A relation added by hand: an ip seen by another system (`type: 'ip'`), a value of a type of your own (`{ type:
|
|
367
|
+
* 'phone', value }`), or a tie between two of your users (`{ type: 'referral', relatedExternalId }`). Its weight isn't
|
|
368
|
+
* part of it: the project's settings hold each type's weight, applied when relations are read.
|
|
369
|
+
*/
|
|
370
|
+
type RelationTarget = {
|
|
371
|
+
externalId: string;
|
|
372
|
+
type: RelatedType;
|
|
373
|
+
value: string;
|
|
374
|
+
} | {
|
|
375
|
+
externalId: string;
|
|
376
|
+
type: RelatedType;
|
|
377
|
+
relatedExternalId: string;
|
|
378
|
+
};
|
|
379
|
+
type RelationInput = RelationTarget & {
|
|
380
|
+
/** Your own word for what happened, like `checkout` or `signup`; up to 1024 characters. */
|
|
381
|
+
action?: string;
|
|
382
|
+
/** When it happened (a Date, an ISO string or epoch milliseconds), now by default; never in the future. */
|
|
383
|
+
at?: Date | string | number;
|
|
384
|
+
};
|
|
385
|
+
/**
|
|
386
|
+
* A relation to take back: the value or the other user you added it with (`{ type: 'phone', value }` or `{ type:
|
|
387
|
+
* 'referral', relatedExternalId }`).
|
|
388
|
+
*/
|
|
389
|
+
type RelationRemoval = {
|
|
390
|
+
externalId: string;
|
|
391
|
+
type: RelatedType;
|
|
392
|
+
value: string;
|
|
393
|
+
} | {
|
|
394
|
+
externalId: string;
|
|
395
|
+
type: RelatedType;
|
|
396
|
+
relatedExternalId: string;
|
|
397
|
+
};
|
|
398
|
+
/** The relation as the api stored it: what you sent, with `at` as an ISO string. */
|
|
399
|
+
type Relation = RelationTarget & {
|
|
400
|
+
action?: string;
|
|
401
|
+
at?: string;
|
|
402
|
+
};
|
|
403
|
+
/** A relation as added: `linkWrite` says whether this call made a new link, the billed unit (a link added before isn't). */
|
|
404
|
+
type AddedRelation = Relation & {
|
|
405
|
+
linkWrite: boolean;
|
|
406
|
+
};
|
|
407
|
+
/** A link to one user's Related view for your admin panel to frame, and when it stops working (ISO). */
|
|
408
|
+
type Embed = {
|
|
409
|
+
url: string;
|
|
410
|
+
expiresAt: string;
|
|
411
|
+
};
|
|
412
|
+
type ClientOptions = ApiOptions;
|
|
413
|
+
/**
|
|
414
|
+
* The api's error codes, any other string for one added later. `not_found` (`404`): no such event or visitor in the
|
|
415
|
+
* project. `spend_limit_reached` (`402`): a spend limit you set for the project, its organization or the key stopped a
|
|
416
|
+
* relation added by hand. `account_closed` (`402`): Zeno closed the organization's account, as for unpaid invoices, and
|
|
417
|
+
* every call is refused until it's reopened; contact support. `search_unavailable` (`503`): search is briefly
|
|
418
|
+
* unavailable; the SDK searches again after its `Retry-After`.
|
|
419
|
+
*
|
|
420
|
+
* The SDK's own: `request_failed` for an error answer without a code, or a success answer that isn't what the call
|
|
421
|
+
* returns; `network_error` (status `0`) when the api couldn't be reached or didn't answer within 10 seconds;
|
|
422
|
+
* `invalid_request` with status `0` for an empty id, refused before anything is sent.
|
|
423
|
+
*/
|
|
424
|
+
type ZenoErrorCode = 'invalid_request' | 'invalid_api_key' | 'spend_limit_reached' | 'account_closed' | 'not_found' | 'method_not_allowed' | 'rate_limited' | 'search_unavailable' | 'server_error' | 'request_failed' | 'network_error' | (string & {});
|
|
425
|
+
/**
|
|
426
|
+
* An error answer of the api, with its status and error code like `not_found`, and for a `429 rate_limited` or `503
|
|
427
|
+
* search_unavailable` the seconds to wait from its `Retry-After`. A relation added by hand and refused because a spend
|
|
428
|
+
* limit you set (the project's, its organization's or the key's) is reached is a `402` `spend_limit_reached`. Any call
|
|
429
|
+
* while the organization's account is closed is a `402` `account_closed`: contact support to reopen it.
|
|
430
|
+
*/
|
|
431
|
+
declare class ZenoError extends Error {
|
|
432
|
+
readonly status: number;
|
|
433
|
+
readonly code: ZenoErrorCode;
|
|
434
|
+
readonly retryAfter?: number | undefined;
|
|
435
|
+
constructor(status: number, code: ZenoErrorCode, message?: string, retryAfter?: number | undefined);
|
|
436
|
+
}
|
|
437
|
+
/**
|
|
438
|
+
* Why `verify` answered without the event's verdict: `no-request-id` (a `challenge`: the browser sent none, as when its
|
|
439
|
+
* identification failed or was blocked), else a `block`: `not-found` (a forged or another project's request ID),
|
|
440
|
+
* `already-used` (verified before), `ip-mismatch` (another ip, for IPv6 another /64; an IPv4 and an IPv6 address are
|
|
441
|
+
* never compared), `too-old` (past `maxAge`), `external-id-mismatch` (another user's event).
|
|
442
|
+
*/
|
|
443
|
+
type VerifyCheck = 'no-request-id' | 'not-found' | 'already-used' | 'ip-mismatch' | 'too-old' | 'external-id-mismatch';
|
|
444
|
+
type VerifyOptions = {
|
|
445
|
+
/**
|
|
446
|
+
* The IP address the request that brought the request ID came from, the same your proxy route gets: your
|
|
447
|
+
* framework's client IP. Not your load balancer's or proxy's. Optional: given, a request ID from another ip blocks
|
|
448
|
+
* (`ip-mismatch`); left out (or null or undefined), or of the other family than the event's (IPv4 and IPv6),
|
|
449
|
+
* there's no ip check.
|
|
450
|
+
*/
|
|
451
|
+
ip?: string | null | undefined;
|
|
452
|
+
/** Seconds an event stays good for, 5 minutes (300) by default; an older one blocks. */
|
|
453
|
+
maxAge?: number;
|
|
454
|
+
/**
|
|
455
|
+
* Your own ID for the user, like `user-1042`: an event with another user's blocks (`external-id-mismatch`), and one
|
|
456
|
+
* with none gets it, so the dashboard and related accounts find it by your ID. Call verify after the action
|
|
457
|
+
* succeeded (the password matched, the account exists), with the user's ID, so a failed login attaches nothing.
|
|
458
|
+
*/
|
|
459
|
+
externalId?: string;
|
|
460
|
+
/**
|
|
461
|
+
* Makes sending the same verify again safe: a repeat with this key within 5 minutes answers what the first did,
|
|
462
|
+
* instead of `already-used`. The SDK makes one per call and retries a lost answer with it itself; pass your own (8
|
|
463
|
+
* to 128 characters, such as your request's ID) when your code may send the same verify again.
|
|
464
|
+
*/
|
|
465
|
+
idempotencyKey?: string;
|
|
466
|
+
};
|
|
467
|
+
/**
|
|
468
|
+
* What `verify` says to do: `allow`, `challenge` or `block`, and why: its own check (`VerifyCheck`), else the event's
|
|
469
|
+
* verdict. With the event when it was found.
|
|
470
|
+
*/
|
|
471
|
+
type VerifyResult = {
|
|
472
|
+
action: VerdictAction;
|
|
473
|
+
reasons: (VerifyCheck | VerdictReason)[];
|
|
474
|
+
/**
|
|
475
|
+
* The event, from `verify` with its velocity as `getEvent` has it (`event.velocity['24h'].distinctExternalId`, or
|
|
476
|
+
* `sameAction` without external IDs), its velocity counted before verify attached your `externalId`. Only from
|
|
477
|
+
* `verify`: `unsealResult` runs on your server and has no velocity.
|
|
478
|
+
*/
|
|
479
|
+
event?: Event;
|
|
480
|
+
};
|
|
481
|
+
/**
|
|
482
|
+
* A client for the Zeno API, with the project's `apiKey` from your server's environment (`process.env.ZENO_API_KEY`,
|
|
483
|
+
* undefined accepted). It's checked on each call, so a module that makes one at load still builds without the
|
|
484
|
+
* environment (as Next.js does when it collects page data); a missing one rejects the call with a TypeError saying how
|
|
485
|
+
* to set it. A call answered `429 rate_limited` or `503 search_unavailable` is sent again twice, after the API's
|
|
486
|
+
* `Retry-After`.
|
|
487
|
+
*/
|
|
488
|
+
declare const createClient: (apiKey: ApiKey, options?: ClientOptions) => {
|
|
489
|
+
/**
|
|
490
|
+
* Checks a request ID the browser sent with an action (a login, a signup, a checkout) and says what to do: `{
|
|
491
|
+
* action: 'allow' | 'challenge' | 'block', reasons, event? }`, in one call (`POST /verify`). Each request ID
|
|
492
|
+
* verifies once. No request ID (`undefined`, `null` or empty: the browser's identification failed or was
|
|
493
|
+
* blocked) is a `challenge` with `no-request-id`, so you decide what happens then. It blocks a request ID that
|
|
494
|
+
* isn't this project's (`not-found`), was verified before (`already-used`), came from another ip than `ip` when
|
|
495
|
+
* you pass one (`ip-mismatch`, for IPv6 another /64; IPv4 and IPv6 are never compared), is older than `maxAge`
|
|
496
|
+
* seconds (`too-old`, 5 minutes by default) or belongs to another user than `externalId`
|
|
497
|
+
* (`external-id-mismatch`); otherwise it answers the event's verdict. Call it after the action succeeded (the
|
|
498
|
+
* password matched, the account exists), with the user's ID: `externalId` is attached to an event without one.
|
|
499
|
+
* It writes nothing else. A lost answer (a network error or a 5xx) is sent again twice with the same
|
|
500
|
+
* idempotency key, which answers the first result rather than `already-used`. Other api errors throw.
|
|
501
|
+
*/
|
|
502
|
+
verify: (requestId: string | undefined | null, options?: VerifyOptions) => Promise<VerifyResult>;
|
|
503
|
+
getEvent: (requestId: string) => Promise<Event>;
|
|
504
|
+
/** Events matching every filter, newest first; pass the cursor back for the next page. */
|
|
505
|
+
searchEvents: (filters?: SearchFilters) => Promise<SearchResult>;
|
|
506
|
+
/** A visitor (a browser) with every external id seen with it. */
|
|
507
|
+
getVisitor: (visitorId: string) => Promise<Visitor>;
|
|
508
|
+
/** Deletes a visitor (a browser) and all its events. */
|
|
509
|
+
deleteVisitor: (visitorId: string) => Promise<{
|
|
510
|
+
visitorId: string;
|
|
511
|
+
deletedEvents: number;
|
|
512
|
+
}>;
|
|
513
|
+
/** Deletes everything stored for one of your users: their events, and what relates them to devices and others. */
|
|
514
|
+
deleteExternalId: (externalId: string) => Promise<{
|
|
515
|
+
externalId: string;
|
|
516
|
+
deletedEvents: number;
|
|
517
|
+
}>;
|
|
518
|
+
/**
|
|
519
|
+
* Relates one of your users by hand: to an ip seen by another system, a value of a type of your own (a phone
|
|
520
|
+
* number, your own device id) or another of your users (a referral). Visitor ids only come from events with an
|
|
521
|
+
* external id, so `identified` means the user was seen in a browser.
|
|
522
|
+
*
|
|
523
|
+
* A new link is billed like an identification (`linkWrite: true`); sending one again is free. Once a spend
|
|
524
|
+
* limit you set is reached it throws a `402` `spend_limit_reached` and adds nothing; only a `429` is sent
|
|
525
|
+
* again.
|
|
526
|
+
*/
|
|
527
|
+
addRelation: ({ at, ...relation }: RelationInput) => Promise<AddedRelation>;
|
|
528
|
+
/**
|
|
529
|
+
* Takes back a relation added with `addRelation`: a value, or a relation between two users (both sides go,
|
|
530
|
+
* whichever side you name). What events related (a visitor id, an ip seen with an event) stays. Free.
|
|
531
|
+
*
|
|
532
|
+
* Answers `{ removed: false }` when there was nothing added by hand to take back, so it's safe to repeat.
|
|
533
|
+
*/
|
|
534
|
+
removeRelation: (relation: RelationRemoval) => Promise<{
|
|
535
|
+
removed: boolean;
|
|
536
|
+
}>;
|
|
537
|
+
/**
|
|
538
|
+
* One of your users' values and relations, of one `type` or every type, each with its weight, and whether they
|
|
539
|
+
* share one value weighing 0.5 or more with another user (`duplicate`). At most 500 (`truncated` past them).
|
|
540
|
+
*/
|
|
541
|
+
getRelatedValues: (externalId: string, { type }?: {
|
|
542
|
+
type?: RelatedType;
|
|
543
|
+
}) => Promise<RelatedValues>;
|
|
544
|
+
/**
|
|
545
|
+
* Your users who have one value, like everyone with one phone number, 20 a page by default (`limit` up to 100);
|
|
546
|
+
* pass the cursor back for the next page.
|
|
547
|
+
*/
|
|
548
|
+
lookupRelated: (type: RelatedType, value: string, page?: {
|
|
549
|
+
limit?: number;
|
|
550
|
+
cursor?: string;
|
|
551
|
+
}) => Promise<Page<RelatedUser>>;
|
|
552
|
+
/** The values of a type more than one of your users share, most shared first, with the type's weight. */
|
|
553
|
+
getSharedValues: (type: RelatedType, page?: {
|
|
554
|
+
limit?: number;
|
|
555
|
+
cursor?: string;
|
|
556
|
+
}) => Promise<Page<SharedValue>>;
|
|
557
|
+
/**
|
|
558
|
+
* Your users related to one through shared values or relations of every type, or of one `type`, up to `depth`
|
|
559
|
+
* (1 to 5, 1 by default) hops away, heaviest first, each with its weight.
|
|
560
|
+
*/
|
|
561
|
+
getRelated: (externalId: string, { type, depth }?: {
|
|
562
|
+
type?: RelatedType;
|
|
563
|
+
depth?: number;
|
|
564
|
+
}) => Promise<Related>;
|
|
565
|
+
/**
|
|
566
|
+
* A link to one user's Related view (their values, related users and recent events) for your admin panel at
|
|
567
|
+
* `origin` to frame, working for `ttl` minutes (5 to 60, 15 by default). Make one per page view and never hand
|
|
568
|
+
* the API key to the browser.
|
|
569
|
+
*/
|
|
570
|
+
createEmbed: (embed: {
|
|
571
|
+
externalId: string;
|
|
572
|
+
origin: string;
|
|
573
|
+
ttl?: number;
|
|
574
|
+
}) => Promise<Embed>;
|
|
575
|
+
};
|
|
576
|
+
/** The client `createClient` makes. */
|
|
577
|
+
type Client = ReturnType<typeof createClient>;
|
|
578
|
+
/** A webhook delivery's body: the event, without its velocity. */
|
|
579
|
+
type WebhookEvent = Omit<Event, 'velocity'>;
|
|
580
|
+
/**
|
|
581
|
+
* Checks a webhook delivery's Zeno-Signature header against the project's webhook secret, and that it was signed in the
|
|
582
|
+
* last `tolerance` seconds, so a captured delivery can't be replayed later. Pass the raw body. Resolves to the event
|
|
583
|
+
* when it matched, else to undefined; rejects with a TypeError when the secret is missing, and with an Error for a
|
|
584
|
+
* signed body that isn't an event.
|
|
585
|
+
*/
|
|
586
|
+
declare const verifyWebhook: (body: string, header: string | null | undefined, secret: string | undefined, { tolerance }?: {
|
|
587
|
+
tolerance?: number | undefined;
|
|
588
|
+
}) => Promise<WebhookEvent | undefined>;
|
|
589
|
+
/** What `unsealResult` takes besides the sealed result. */
|
|
590
|
+
type UnsealOptions = {
|
|
591
|
+
/**
|
|
592
|
+
* The project's encryption key, base64 (32 bytes), as the dashboard shows it: `process.env.ZENO_ENCRYPTION_KEY`; or
|
|
593
|
+
* several, tried in order, while you rotate it: `[current, previous]`.
|
|
594
|
+
*/
|
|
595
|
+
key: string | undefined | (string | undefined)[];
|
|
596
|
+
/**
|
|
597
|
+
* The IP address the request came from, as you pass it to `verify`: a sealed result from another ip blocks
|
|
598
|
+
* (`ip-mismatch`, for IPv6 another /64); left out, or of the other family than the event's, there's no ip check.
|
|
599
|
+
*/
|
|
600
|
+
ip?: string | null | undefined;
|
|
601
|
+
/** Your own id for the user: an event with another user's blocks (`external-id-mismatch`); one with none is fine. */
|
|
602
|
+
externalId?: string;
|
|
603
|
+
/** Seconds a sealed result stays good for, 5 minutes (300) by default, as with `verify`; an older one blocks. */
|
|
604
|
+
maxAge?: number;
|
|
605
|
+
};
|
|
606
|
+
/**
|
|
607
|
+
* Opens a sealed result from the browser with the project's encryption key and says what to do, in `verify`'s shape: `{
|
|
608
|
+
* action, reasons, event? }`. No sealed result (`undefined`, `null` or empty) is a `challenge` with `no-request-id`;
|
|
609
|
+
* one that doesn't open with any `key` (changed, sealed with another project's key, or not one at all) is a `block`
|
|
610
|
+
* with `not-found`. An opened one from another ip than `ip` blocks with `ip-mismatch`, compared as `verify` does, one
|
|
611
|
+
* older than `maxAge` seconds with `too-old`, another user's than `externalId` with `external-id-mismatch`; otherwise
|
|
612
|
+
* it answers the event's verdict. It can't tell a sealed result sent twice: where a repeat matters, use `verify`, which
|
|
613
|
+
* allows each request ID once. Rejects with a TypeError for a missing or malformed key. The format: base64(version |
|
|
614
|
+
* iv(12) | ciphertext | tag(16)), AES-256-GCM.
|
|
615
|
+
*/
|
|
616
|
+
declare const unsealResult: (sealed: string | undefined | null, options: UnsealOptions) => Promise<VerifyResult>;
|
|
617
|
+
//#endregion
|
|
618
|
+
export { AddedRelation, type ApiOptions, Bot, BrowserDetails, Client, ClientOptions, Confidence, Connection, Contradiction, Embed, Event, ForgedPayloadIndicator, IpInfo, Metadata, NetworkOwnerType, Page, type ProxyHandler, type ProxyOptions, Related, RelatedKind, RelatedType, RelatedUser, RelatedValue, RelatedValues, Relation, RelationInput, RelationRemoval, SIGNALS, SearchEvent, SearchFilters, SearchResult, SharedValue, Signal, SignalDetails, SignalReason, SignalResult, Signals, UnsealOptions, Velocity, Verdict, VerdictAction, VerdictReason, VerifyCheck, VerifyOptions, VerifyResult, VirtualMachineIndicator, Visitor, WebhookEvent, ZenoError, ZenoErrorCode, createClient, createProxy, unsealResult, verifyWebhook };
|