zeno.id 0.3.2 → 0.5.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.
@@ -1,17 +1,17 @@
1
1
  import { a as ApiOptions, i as ApiKey, n as ProxyOptions, r as createProxy, t as ProxyHandler } from "./proxy-CUZ-Jwgy.cjs";
2
2
  //#region src/server/index.d.ts
3
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'];
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', 'high-activity', 'replayed', 'residential-proxy', 'private-relay', 'forged-payload', 'stored-id-rejected'];
5
5
  type Signal = (typeof SIGNALS)[number];
6
6
  /** The bot verdict: a known good bot (a search engine's crawler), a bad one (automation, a headless browser), or none. */
7
7
  type Bot = 'good' | 'bad' | 'not-detected';
8
8
  /**
9
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
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.
11
+ * Chromium's static storage quota, the same in normal and private windows; no WebGL or canvas; too few devices were
12
+ * seen yet to call hardware rare; the request carried no nonce.
13
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';
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' | 'no-nonce';
15
15
  type Confidence = 'high' | 'medium' | 'low';
16
16
  /** A contradiction in the device's browser data, in `signals.tampering`. */
17
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';
@@ -38,10 +38,109 @@ type Velocity = {
38
38
  distinctIpByExternalId: number;
39
39
  distinctVisitorIdByExternalId: number;
40
40
  };
41
+ /**
42
+ * What's global about an event, up to the event: its device and ip across every project using Zeno, as numbers and
43
+ * coarse network facts. Only on getEvent and verify; none when the project turned it off.
44
+ */
45
+ type GlobalFields = {
46
+ /** The device's history across every project, from its latest 1,000 events. */
47
+ history?: {
48
+ /** The month any project first saw the device, among the events still kept. */
49
+ firstSeenAt?: string;
50
+ events: number;
51
+ /** Its events' risk scores; the event's own `riskScore` is this request's. */
52
+ riskScore: {
53
+ highest: number;
54
+ average: number;
55
+ };
56
+ badBotEvents: number;
57
+ /**
58
+ * The visitor's latest residential connections in your project, up to 10, newest first. Never another
59
+ * project's.
60
+ */
61
+ residentialIps: EventIp[];
62
+ /**
63
+ * The device's residential networks on every project, up to 10, latest first. Never an address or what locates
64
+ * someone.
65
+ */
66
+ residentialNetworks: Omit<EventIp, 'address' | 'city' | 'postalCode' | 'latitude' | 'longitude' | 'locationAccuracy' | 'networkRange'>[];
67
+ };
68
+ globalVelocity?: Record<'5m' | '1h' | '24h', Pick<Velocity, 'events' | 'distinctIp' | 'distinctExternalId' | 'distinctCountry'> & {
69
+ /** Every device's events from the event's ip, on every project. */
70
+ ipEvents: number;
71
+ }>;
72
+ };
73
+ /**
74
+ * What the browser reported. Values that could identify a device on their own are hashes of your project's own, so you
75
+ * can compare your events, but they never match another project's; ones many devices share, like the screen, are as
76
+ * reported. Each is left out when the browser didn't report it.
77
+ */
78
+ type RawDeviceAttributes = {
79
+ canvas?: string;
80
+ canvasText?: string;
81
+ audio?: string;
82
+ webgl?: {
83
+ vendor: string;
84
+ renderer: string;
85
+ extensions: string;
86
+ parameters: string;
87
+ };
88
+ screen?: {
89
+ width: number;
90
+ height: number;
91
+ colorDepth: number;
92
+ pixelRatio: number;
93
+ };
94
+ hardwareConcurrency?: number;
95
+ deviceMemory?: number;
96
+ maxTouchPoints?: number;
97
+ platform?: string;
98
+ architecture?: number;
99
+ vendor?: string;
100
+ oscpu?: string;
101
+ deviceModel?: string;
102
+ timeZone?: string;
103
+ timezoneOffsets?: number[];
104
+ languages?: string[];
105
+ dateTimeLocale?: string;
106
+ cookies?: boolean;
107
+ localStorage?: boolean;
108
+ sessionStorage?: boolean;
109
+ indexedDb?: boolean;
110
+ plugins?: string;
111
+ fonts?: string;
112
+ emoji?: string;
113
+ fontPreferences?: string;
114
+ math?: string;
115
+ keyboard?: string;
116
+ };
117
+ /** What an event turned out to be, as your backend reports it. */
118
+ type Outcome = 'fraud' | 'legitimate';
119
+ /** What kind of bot an event was. */
120
+ type BotType = 'automation' | 'replayed' | 'forged-request' | 'fake-crawler' | 'crawler' | 'ai-agent';
121
+ /** The bot verdict, and what's known of the bot. */
122
+ type EventBot = {
123
+ result: Bot;
124
+ /** Absent when no bot was detected. */
125
+ type?: BotType;
126
+ /** How sure the type is: `low` for an AI agent that only says what it is. */
127
+ confidence?: Confidence;
128
+ /** Who runs it, like `Google`, when it gives a name we know. */
129
+ provider?: string;
130
+ /** The name it goes by, like `Googlebot`, when it gives one. */
131
+ name?: string;
132
+ /** Whether its network confirmed that name: true for a real crawler, false for one pretending. */
133
+ verified?: boolean;
134
+ };
41
135
  /** What owns an ip address or runs its network. */
42
136
  type NetworkOwnerType = 'isp' | 'hosting' | 'business' | 'education' | 'government' | 'banking';
43
- /** Who owns the ip and where it is, from the ip lookup. */
44
- type IpInfo = {
137
+ /**
138
+ * The connection: its ip address and, from the ip lookup, who owns it and where it is. Only the address when the lookup
139
+ * failed.
140
+ */
141
+ type EventIp = {
142
+ /** The ip address, as the proxy route passed it. Behind a VPN or proxy, the exit's. */
143
+ address: string;
45
144
  /** The country's two-letter code, like `US`. */
46
145
  country?: string;
47
146
  countryName?: string;
@@ -85,18 +184,32 @@ type IpInfo = {
85
184
  /** A private or reserved address that no one on the internet has. */
86
185
  reservedAddress: boolean;
87
186
  };
88
- type BrowserDetails = {
89
- browserName: string;
90
- browserMajorVersion?: string;
91
- browserFullVersion?: string;
187
+ /** The browser, parsed on the server from the user agent and client hints. */
188
+ type EventBrowser = {
189
+ name: string;
190
+ /** The major version, like `157`. */
191
+ version?: string;
192
+ fullVersion?: string;
92
193
  os: string;
93
194
  osVersion?: string;
94
195
  device: string;
196
+ /** The browser's user agent string, as it sent it. */
197
+ userAgent: string;
95
198
  };
96
199
  /** What some signals found, on their entry in `signals` when they're detected, each field only when there was one. */
97
200
  type SignalDetails = {
98
201
  vpn: {
99
202
  confidence?: Confidence;
203
+ /** Why it's a VPN: a known exit, iCloud Private Relay or a time zone that doesn't fit. */
204
+ methods?: {
205
+ knownVpnExit: boolean;
206
+ privateRelay: boolean;
207
+ timeZoneMismatch: boolean;
208
+ };
209
+ /** The browser's own time zone, likely where the person really is. */
210
+ originTimeZone?: string;
211
+ /** The country of that time zone, like `DE`: a hint, not proof. */
212
+ originCountry?: string;
100
213
  };
101
214
  proxy: {
102
215
  confidence?: Confidence;
@@ -164,7 +277,7 @@ type Event = {
164
277
  verdict: Verdict;
165
278
  /** 0 to 30: the detected signals' points, capped at 30. */
166
279
  riskScore: number;
167
- bot: Bot;
280
+ bot: EventBot;
168
281
  /** How sure the visitor id is, 0.1 to 1. */
169
282
  confidence: number;
170
283
  /**
@@ -180,28 +293,50 @@ type Event = {
180
293
  /** The id of the API key whose proxy route identified (search filters on it as `apiKeyId`). */
181
294
  apiKeyId: string;
182
295
  createdAt: string;
183
- /** When `verify` attached its external id afterwards; that also sends an `update` webhook. */
296
+ /**
297
+ * When `verify` attached its external id or an outcome was reported afterwards; that also sends an `update`
298
+ * webhook.
299
+ */
184
300
  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
301
  origin?: string;
188
302
  /** The page as origin and path, or only its origin; left out when the project keeps no page urls (`pageUrls`). */
189
303
  url?: string;
190
304
  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;
305
+ browser: EventBrowser;
306
+ ip: EventIp;
197
307
  /**
198
308
  * Every signal Zeno checks: `detected` true, false, or null when it couldn't be checked (with a `reason`), the
199
309
  * `points` a detected one added, and what it found. Read `event.signals.vpn.detected`.
200
310
  */
201
311
  signals: Signals;
312
+ /** What your backend reported the event turned out to be (`reportOutcome`). */
313
+ outcome?: Outcome;
314
+ /** A looser id than `visitorId`: the hardware alone, shared by identical devices. Only on getEvent and verify. */
315
+ broadVisitorId?: string;
316
+ /**
317
+ * The approximate area, as an id per project, with a radius in km. None behind a VPN or proxy. Only on getEvent and
318
+ * verify.
319
+ */
320
+ proximity?: {
321
+ id: string;
322
+ radius: number;
323
+ confidence: number;
324
+ };
325
+ /** Only on getEvent and verify, not in webhooks or sealed results. */
326
+ rawDeviceAttributes?: RawDeviceAttributes;
202
327
  /** Only on getEvent and verify, not in webhooks or sealed results. */
203
328
  velocity?: Record<'5m' | '1h' | '24h', Velocity>;
204
- };
329
+ /**
330
+ * Your other users this event ties to, by external id: those sharing its `visitorId`, its residential IP
331
+ * (`residentialIp`), and both its `broadVisitorId` and its IP (`broadVisitorId`, as a broad visitor ID isn't strong
332
+ * enough on its own). Up to 25 of each. Only on getEvent and verify, not in webhooks or sealed results.
333
+ */
334
+ related?: {
335
+ visitorId: string[];
336
+ residentialIp: string[];
337
+ broadVisitorId: string[];
338
+ };
339
+ } & GlobalFields;
205
340
  /** A list filter takes one value, or several to match any of. */
206
341
  type AnyOf<T> = T | T[];
207
342
  type SearchFilters = {
@@ -219,6 +354,8 @@ type SearchFilters = {
219
354
  action?: AnyOf<string>;
220
355
  signal?: AnyOf<Signal>;
221
356
  bot?: AnyOf<Bot>;
357
+ /** What your backend reported, among the events with a report. */
358
+ outcome?: AnyOf<Outcome>;
222
359
  minRiskScore?: number;
223
360
  /**
224
361
  * Inclusive. Without it the search covers the 30 days before `end` (or now), unless it looks up a `visitorId`,
@@ -232,16 +369,17 @@ type SearchFilters = {
232
369
  };
233
370
  /**
234
371
  * 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.
372
+ * `metadata`, `updatedAt`, `url`, `referrer` and `velocity`; its `signals` list only the detected ones, as `{ detected:
373
+ * true }` (get the event for the rest), its `browser` holds the user agent, and the browser's and the os's name and
374
+ * version, and its `ip` the address with the country, city, asn and company, each left out when the event has none of
375
+ * them.
238
376
  */
239
- type SearchEvent = Pick<Event, 'requestId' | 'visitorId' | 'verdict' | 'riskScore' | 'bot' | 'confidence' | 'externalId' | 'action' | 'apiKeyId' | 'createdAt' | 'origin' | 'userAgent' | 'ip'> & {
377
+ type SearchEvent = Pick<Event, 'requestId' | 'visitorId' | 'verdict' | 'riskScore' | 'bot' | 'outcome' | 'confidence' | 'externalId' | 'action' | 'apiKeyId' | 'createdAt' | 'origin'> & {
240
378
  signals: { [S in Signal]?: {
241
379
  detected: true;
242
380
  }; };
243
- browserDetails?: Partial<Pick<BrowserDetails, 'browserName' | 'browserMajorVersion' | 'os' | 'osVersion'>>;
244
- ipInfo?: Pick<IpInfo, 'country' | 'city' | 'asn' | 'company'>;
381
+ browser: Pick<EventBrowser, 'userAgent'> & Partial<Pick<EventBrowser, 'name' | 'version' | 'os' | 'osVersion'>>;
382
+ ip: Pick<EventIp, 'address' | 'country' | 'city' | 'asn' | 'company'>;
245
383
  };
246
384
  /** A page of a list: pass `cursor` back for the next one; none on the last. */
247
385
  type Page<T> = {
@@ -258,7 +396,7 @@ type SearchResult = Page<SearchEvent> & {
258
396
  /**
259
397
  * A visitor: `externalIds` the latest 10 external ids seen with it, newest first, and `externalIdCount` how many there
260
398
  * 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.
399
+ * 20 latest events, newest first, each with its detected signals the same way and `ip.country` when known.
262
400
  */
263
401
  type Visitor = {
264
402
  visitorId: string;
@@ -270,15 +408,16 @@ type Visitor = {
270
408
  eventCount: number;
271
409
  firstSeenAt: string;
272
410
  lastSeenAt: string;
273
- recentEvents: (Pick<SearchEvent, 'requestId' | 'externalId' | 'createdAt' | 'ip' | 'signals'> & {
274
- ipInfo?: Pick<IpInfo, 'country'>;
411
+ recentEvents: (Pick<SearchEvent, 'requestId' | 'externalId' | 'createdAt' | 'signals'> & {
412
+ ip: Pick<EventIp, 'address' | 'country'>;
275
413
  })[];
276
414
  };
277
415
  /**
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 `-`).
416
+ * What relates two users: the built-in `visitor-id` (a browser), `broad-visitor-id` (its hardware), `residential-ip`
417
+ * (an ip of an internet provider, not a VPN, proxy or mobile network), all three from events only, and `ip`, or a type
418
+ * of your own like `phone` or `referral` (a lowercase letter, then up to 31 lowercase letters, digits, `_` or `-`).
280
419
  */
281
- type RelatedType = 'visitor-id' | 'ip' | (string & {});
420
+ type RelatedType = 'visitor-id' | 'broad-visitor-id' | 'ip' | 'residential-ip' | (string & {});
282
421
  /**
283
422
  * `identifier`, a value several users can share (a visitor id, a phone number); `relation`, a direct tie between two
284
423
  * users (a referral, an invite). A type of your own keeps the kind its first relation gave it.
@@ -333,7 +472,7 @@ type Related = {
333
472
  type?: RelatedType;
334
473
  /**
335
474
  * 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),
475
+ * (`1 - Π(1 - weight)`, so with the default weights two shared ips make 0.44 and a browser and an ip 0.93),
337
476
  * multiplied along the strongest path for a user further away. With the users each shares a value with or is
338
477
  * related to.
339
478
  */
@@ -350,18 +489,6 @@ type RelatedUser = {
350
489
  externalId: string;
351
490
  createdAt: string;
352
491
  };
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
492
  /**
366
493
  * A relation added by hand: an ip seen by another system (`type: 'ip'`), a value of a type of your own (`{ type:
367
494
  * 'phone', value }`), or a tie between two of your users (`{ type: 'referral', relatedExternalId }`). Its weight isn't
@@ -377,8 +504,6 @@ type RelationTarget = {
377
504
  relatedExternalId: string;
378
505
  };
379
506
  type RelationInput = RelationTarget & {
380
- /** Your own word for what happened, like `checkout` or `signup`; up to 1024 characters. */
381
- action?: string;
382
507
  /** When it happened (a Date, an ISO string or epoch milliseconds), now by default; never in the future. */
383
508
  at?: Date | string | number;
384
509
  };
@@ -397,7 +522,6 @@ type RelationRemoval = {
397
522
  };
398
523
  /** The relation as the api stored it: what you sent, with `at` as an ISO string. */
399
524
  type Relation = RelationTarget & {
400
- action?: string;
401
525
  at?: string;
402
526
  };
403
527
  /** A relation as added: `linkWrite` says whether this call made a new link, the billed unit (a link added before isn't). */
@@ -505,7 +629,14 @@ declare const createClient: (apiKey: ApiKey, options?: ClientOptions) => {
505
629
  searchEvents: (filters?: SearchFilters) => Promise<SearchResult>;
506
630
  /** A visitor (a browser) with every external id seen with it. */
507
631
  getVisitor: (visitorId: string) => Promise<Visitor>;
508
- /** Deletes a visitor (a browser) and all its events. */
632
+ /**
633
+ * Reports what an event turned out to be, like after a chargeback or a review. The latest report counts, and it
634
+ * never changes the event's score.
635
+ */
636
+ reportOutcome: (requestId: string, outcome: Outcome) => Promise<{
637
+ requestId: string;
638
+ outcome: Outcome;
639
+ }>;
509
640
  deleteVisitor: (visitorId: string) => Promise<{
510
641
  visitorId: string;
511
642
  deletedEvents: number;
@@ -549,11 +680,6 @@ declare const createClient: (apiKey: ApiKey, options?: ClientOptions) => {
549
680
  limit?: number;
550
681
  cursor?: string;
551
682
  }) => 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
683
  /**
558
684
  * Your users related to one through shared values or relations of every type, or of one `type`, up to `depth`
559
685
  * (1 to 5, 1 by default) hops away, heaviest first, each with its weight.
@@ -576,7 +702,7 @@ declare const createClient: (apiKey: ApiKey, options?: ClientOptions) => {
576
702
  /** The client `createClient` makes. */
577
703
  type Client = ReturnType<typeof createClient>;
578
704
  /** A webhook delivery's body: the event, without its velocity. */
579
- type WebhookEvent = Omit<Event, 'velocity'>;
705
+ type WebhookEvent = Omit<Event, 'broadVisitorId' | 'proximity' | 'rawDeviceAttributes' | 'velocity' | 'related' | keyof GlobalFields>;
580
706
  /**
581
707
  * Checks a webhook delivery's Zeno-Signature header against the project's webhook secret, and that it was signed in the
582
708
  * last `tolerance` seconds, so a captured delivery can't be replayed later. Pass the raw body. Resolves to the event
@@ -615,4 +741,4 @@ type UnsealOptions = {
615
741
  */
616
742
  declare const unsealResult: (sealed: string | undefined | null, options: UnsealOptions) => Promise<VerifyResult>;
617
743
  //#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 };
744
+ export { AddedRelation, type ApiOptions, Bot, BotType, Client, ClientOptions, Confidence, Connection, Contradiction, Embed, Event, EventBot, EventBrowser, EventIp, ForgedPayloadIndicator, GlobalFields, Metadata, NetworkOwnerType, Outcome, Page, type ProxyHandler, type ProxyOptions, RawDeviceAttributes, Related, RelatedKind, RelatedType, RelatedUser, RelatedValue, RelatedValues, Relation, RelationInput, RelationRemoval, SIGNALS, SearchEvent, SearchFilters, SearchResult, Signal, SignalDetails, SignalReason, SignalResult, Signals, UnsealOptions, Velocity, Verdict, VerdictAction, VerdictReason, VerifyCheck, VerifyOptions, VerifyResult, VirtualMachineIndicator, Visitor, WebhookEvent, ZenoError, ZenoErrorCode, createClient, createProxy, unsealResult, verifyWebhook };