zeno.id 0.3.2 → 0.4.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 CHANGED
@@ -12,7 +12,7 @@ One package for the browser and the server. `zeno.id/server` holds your API key,
12
12
 
13
13
  ## How it fits together
14
14
 
15
- 1. Make a project and an API key in the dashboard, and put the key in your server's environment:
15
+ 1. Make a project and an API key in the app, and put the key in your server's environment:
16
16
 
17
17
  ```sh
18
18
  ZENO_API_KEY=sk_...
@@ -369,6 +369,7 @@ const { url } = await client.createEmbed({
369
369
  | `getVisitor(visitorId)` | `GET /visitors/{visitorId}` |
370
370
  | `deleteVisitor(visitorId)` | `DELETE /visitors/{visitorId}` |
371
371
  | `deleteExternalId(externalId)` | `DELETE /external-ids?externalId=...` |
372
+ | `reportOutcome(requestId, outcome)` | `POST /outcomes`, `fraud` or `legitimate`, the latest counts |
372
373
  | `addRelation({ externalId, type, value or relatedExternalId, action?, at? })` | `POST /related` |
373
374
  | `removeRelation({ externalId, type, value or relatedExternalId })` | `DELETE /related?externalId=...&type=...`, `{ removed }`, free |
374
375
  | `getRelated(externalId, { type?, depth? })` | `GET /related?externalId=...`, every type unless `type` names one |
@@ -397,6 +397,7 @@ const SIGNALS = [
397
397
  "ai-agent",
398
398
  "privacy-browser",
399
399
  "rare-device",
400
+ "high-activity",
400
401
  "replayed",
401
402
  "residential-proxy",
402
403
  "private-relay",
@@ -448,7 +449,7 @@ const defineShape = (name, fields) => ({
448
449
  const EVENT = defineShape("an event", {
449
450
  requestId: "string",
450
451
  visitorId: "string",
451
- ip: "string",
452
+ ip: "object",
452
453
  createdAt: "string",
453
454
  riskScore: "number",
454
455
  signals: "object",
@@ -461,6 +462,10 @@ const VISITOR = defineShape("a visitor", {
461
462
  externalIdCount: "number",
462
463
  recentEvents: "array"
463
464
  });
465
+ const REPORTED_OUTCOME = defineShape("a reported outcome", {
466
+ requestId: "string",
467
+ outcome: "string"
468
+ });
464
469
  const DELETED_VISITOR = defineShape("an erasure", {
465
470
  visitorId: "string",
466
471
  deletedEvents: "number"
@@ -599,7 +604,16 @@ const createClient = (apiKey, options = {}) => {
599
604
  },
600
605
  /** A visitor (a browser) with every external id seen with it. */
601
606
  getVisitor: async (visitorId) => callApi("GET", `/visitors/${toPathSegment("visitorId", visitorId)}`, VISITOR),
602
- /** Deletes a visitor (a browser) and all its events. */
607
+ /**
608
+ * Reports what an event turned out to be, like after a chargeback or a review. The latest report counts, and it
609
+ * never changes the event's score.
610
+ */
611
+ reportOutcome: (requestId, outcome) => {
612
+ return callApi("POST", "/outcomes", REPORTED_OUTCOME, {
613
+ requestId,
614
+ outcome
615
+ });
616
+ },
603
617
  deleteVisitor: async (visitorId) => {
604
618
  return callApi("DELETE", `/visitors/${toPathSegment("visitorId", visitorId)}`, DELETED_VISITOR);
605
619
  },
@@ -735,8 +749,8 @@ const MISSING_KEY = "unsealResult needs the project's encryption key as key (is
735
749
  const keyBytesOf = (secret) => {
736
750
  const trimmedKey = requireSecret(secret, MISSING_KEY).trim();
737
751
  const keyBytes = /^[A-Za-z0-9+/]+={0,2}$/.test(trimmedKey) ? fromBase64(trimmedKey) : void 0;
738
- if (!keyBytes) throw new TypeError("unsealResult's key isn't base64: pass the project's encryption key as the dashboard shows it");
739
- if (keyBytes.length !== 32) throw new TypeError(/^[0-9a-f]{64}$/i.test(trimmedKey) ? "unsealResult's key looks like hex: pass the project's encryption key as the dashboard shows it, in base64" : `unsealResult's key is ${keyBytes.length} bytes, not 32: pass the project's encryption key as the dashboard shows it`);
752
+ if (!keyBytes) throw new TypeError("unsealResult's key isn't base64: pass the project's encryption key as the app shows it");
753
+ if (keyBytes.length !== 32) throw new TypeError(/^[0-9a-f]{64}$/i.test(trimmedKey) ? "unsealResult's key looks like hex: pass the project's encryption key as the app shows it, in base64" : `unsealResult's key is ${keyBytes.length} bytes, not 32: pass the project's encryption key as the app shows it`);
740
754
  return keyBytes;
741
755
  };
742
756
  const decryptWithAnyKey = async (keys, data) => {
@@ -781,7 +795,7 @@ const unsealResult = async (sealed, options) => {
781
795
  if (!EVENT.is(event)) throw new Error("The sealed result opened but isn't an event; update zeno.id/server");
782
796
  const failedChecks = [];
783
797
  const maxAge = options.maxAge ?? UNSEAL_MAX_AGE;
784
- if (options.ip && isIpMismatch(event.ip, options.ip)) failedChecks.push("ip-mismatch");
798
+ if (options.ip && isIpMismatch(event.ip.address, options.ip)) failedChecks.push("ip-mismatch");
785
799
  if (Date.now() - Date.parse(event.createdAt) > maxAge * 1e3) failedChecks.push("too-old");
786
800
  if (options.externalId !== void 0 && event.externalId !== void 0 && event.externalId !== options.externalId) failedChecks.push("external-id-mismatch");
787
801
  if (failedChecks.length > 0) return {
@@ -1,15 +1,15 @@
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', 'rare-device', '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
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
15
  type Confidence = 'high' | 'medium' | 'low';
@@ -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,40 @@ 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
+ } & GlobalFields;
205
330
  /** A list filter takes one value, or several to match any of. */
206
331
  type AnyOf<T> = T | T[];
207
332
  type SearchFilters = {
@@ -219,6 +344,8 @@ type SearchFilters = {
219
344
  action?: AnyOf<string>;
220
345
  signal?: AnyOf<Signal>;
221
346
  bot?: AnyOf<Bot>;
347
+ /** What your backend reported, among the events with a report. */
348
+ outcome?: AnyOf<Outcome>;
222
349
  minRiskScore?: number;
223
350
  /**
224
351
  * Inclusive. Without it the search covers the 30 days before `end` (or now), unless it looks up a `visitorId`,
@@ -232,16 +359,17 @@ type SearchFilters = {
232
359
  };
233
360
  /**
234
361
  * 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.
362
+ * `metadata`, `updatedAt`, `url`, `referrer` and `velocity`; its `signals` list only the detected ones, as `{ detected:
363
+ * true }` (get the event for the rest), its `browser` holds the user agent, and the browser's and the os's name and
364
+ * version, and its `ip` the address with the country, city, asn and company, each left out when the event has none of
365
+ * them.
238
366
  */
239
- type SearchEvent = Pick<Event, 'requestId' | 'visitorId' | 'verdict' | 'riskScore' | 'bot' | 'confidence' | 'externalId' | 'action' | 'apiKeyId' | 'createdAt' | 'origin' | 'userAgent' | 'ip'> & {
367
+ type SearchEvent = Pick<Event, 'requestId' | 'visitorId' | 'verdict' | 'riskScore' | 'bot' | 'outcome' | 'confidence' | 'externalId' | 'action' | 'apiKeyId' | 'createdAt' | 'origin'> & {
240
368
  signals: { [S in Signal]?: {
241
369
  detected: true;
242
370
  }; };
243
- browserDetails?: Partial<Pick<BrowserDetails, 'browserName' | 'browserMajorVersion' | 'os' | 'osVersion'>>;
244
- ipInfo?: Pick<IpInfo, 'country' | 'city' | 'asn' | 'company'>;
371
+ browser: Pick<EventBrowser, 'userAgent'> & Partial<Pick<EventBrowser, 'name' | 'version' | 'os' | 'osVersion'>>;
372
+ ip: Pick<EventIp, 'address' | 'country' | 'city' | 'asn' | 'company'>;
245
373
  };
246
374
  /** A page of a list: pass `cursor` back for the next one; none on the last. */
247
375
  type Page<T> = {
@@ -258,7 +386,7 @@ type SearchResult = Page<SearchEvent> & {
258
386
  /**
259
387
  * A visitor: `externalIds` the latest 10 external ids seen with it, newest first, and `externalIdCount` how many there
260
388
  * 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.
389
+ * 20 latest events, newest first, each with its detected signals the same way and `ip.country` when known.
262
390
  */
263
391
  type Visitor = {
264
392
  visitorId: string;
@@ -270,8 +398,8 @@ type Visitor = {
270
398
  eventCount: number;
271
399
  firstSeenAt: string;
272
400
  lastSeenAt: string;
273
- recentEvents: (Pick<SearchEvent, 'requestId' | 'externalId' | 'createdAt' | 'ip' | 'signals'> & {
274
- ipInfo?: Pick<IpInfo, 'country'>;
401
+ recentEvents: (Pick<SearchEvent, 'requestId' | 'externalId' | 'createdAt' | 'signals'> & {
402
+ ip: Pick<EventIp, 'address' | 'country'>;
275
403
  })[];
276
404
  };
277
405
  /**
@@ -350,7 +478,10 @@ type RelatedUser = {
350
478
  externalId: string;
351
479
  createdAt: string;
352
480
  };
353
- /** A value more than one user shares, or for a relation type the two users it ties and how many times. */
481
+ /**
482
+ * A value more than one user shares, or for a relation type the two users it ties; `count` is how many users share it
483
+ * (2 for a relation).
484
+ */
354
485
  type SharedValue = {
355
486
  type: RelatedType;
356
487
  weight: number;
@@ -505,7 +636,14 @@ declare const createClient: (apiKey: ApiKey, options?: ClientOptions) => {
505
636
  searchEvents: (filters?: SearchFilters) => Promise<SearchResult>;
506
637
  /** A visitor (a browser) with every external id seen with it. */
507
638
  getVisitor: (visitorId: string) => Promise<Visitor>;
508
- /** Deletes a visitor (a browser) and all its events. */
639
+ /**
640
+ * Reports what an event turned out to be, like after a chargeback or a review. The latest report counts, and it
641
+ * never changes the event's score.
642
+ */
643
+ reportOutcome: (requestId: string, outcome: Outcome) => Promise<{
644
+ requestId: string;
645
+ outcome: Outcome;
646
+ }>;
509
647
  deleteVisitor: (visitorId: string) => Promise<{
510
648
  visitorId: string;
511
649
  deletedEvents: number;
@@ -576,7 +714,7 @@ declare const createClient: (apiKey: ApiKey, options?: ClientOptions) => {
576
714
  /** The client `createClient` makes. */
577
715
  type Client = ReturnType<typeof createClient>;
578
716
  /** A webhook delivery's body: the event, without its velocity. */
579
- type WebhookEvent = Omit<Event, 'velocity'>;
717
+ type WebhookEvent = Omit<Event, 'broadVisitorId' | 'proximity' | 'rawDeviceAttributes' | 'velocity' | keyof GlobalFields>;
580
718
  /**
581
719
  * Checks a webhook delivery's Zeno-Signature header against the project's webhook secret, and that it was signed in the
582
720
  * last `tolerance` seconds, so a captured delivery can't be replayed later. Pass the raw body. Resolves to the event
@@ -615,4 +753,4 @@ type UnsealOptions = {
615
753
  */
616
754
  declare const unsealResult: (sealed: string | undefined | null, options: UnsealOptions) => Promise<VerifyResult>;
617
755
  //#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 };
756
+ 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, SharedValue, Signal, SignalDetails, SignalReason, SignalResult, Signals, UnsealOptions, Velocity, Verdict, VerdictAction, VerdictReason, VerifyCheck, VerifyOptions, VerifyResult, VirtualMachineIndicator, Visitor, WebhookEvent, ZenoError, ZenoErrorCode, createClient, createProxy, unsealResult, verifyWebhook };
@@ -1,15 +1,15 @@
1
1
  import { a as ApiOptions, i as ApiKey, n as ProxyOptions, r as createProxy, t as ProxyHandler } from "./proxy-CUZ-Jwgy.js";
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', 'rare-device', '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
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
15
  type Confidence = 'high' | 'medium' | 'low';
@@ -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,40 @@ 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
+ } & GlobalFields;
205
330
  /** A list filter takes one value, or several to match any of. */
206
331
  type AnyOf<T> = T | T[];
207
332
  type SearchFilters = {
@@ -219,6 +344,8 @@ type SearchFilters = {
219
344
  action?: AnyOf<string>;
220
345
  signal?: AnyOf<Signal>;
221
346
  bot?: AnyOf<Bot>;
347
+ /** What your backend reported, among the events with a report. */
348
+ outcome?: AnyOf<Outcome>;
222
349
  minRiskScore?: number;
223
350
  /**
224
351
  * Inclusive. Without it the search covers the 30 days before `end` (or now), unless it looks up a `visitorId`,
@@ -232,16 +359,17 @@ type SearchFilters = {
232
359
  };
233
360
  /**
234
361
  * 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.
362
+ * `metadata`, `updatedAt`, `url`, `referrer` and `velocity`; its `signals` list only the detected ones, as `{ detected:
363
+ * true }` (get the event for the rest), its `browser` holds the user agent, and the browser's and the os's name and
364
+ * version, and its `ip` the address with the country, city, asn and company, each left out when the event has none of
365
+ * them.
238
366
  */
239
- type SearchEvent = Pick<Event, 'requestId' | 'visitorId' | 'verdict' | 'riskScore' | 'bot' | 'confidence' | 'externalId' | 'action' | 'apiKeyId' | 'createdAt' | 'origin' | 'userAgent' | 'ip'> & {
367
+ type SearchEvent = Pick<Event, 'requestId' | 'visitorId' | 'verdict' | 'riskScore' | 'bot' | 'outcome' | 'confidence' | 'externalId' | 'action' | 'apiKeyId' | 'createdAt' | 'origin'> & {
240
368
  signals: { [S in Signal]?: {
241
369
  detected: true;
242
370
  }; };
243
- browserDetails?: Partial<Pick<BrowserDetails, 'browserName' | 'browserMajorVersion' | 'os' | 'osVersion'>>;
244
- ipInfo?: Pick<IpInfo, 'country' | 'city' | 'asn' | 'company'>;
371
+ browser: Pick<EventBrowser, 'userAgent'> & Partial<Pick<EventBrowser, 'name' | 'version' | 'os' | 'osVersion'>>;
372
+ ip: Pick<EventIp, 'address' | 'country' | 'city' | 'asn' | 'company'>;
245
373
  };
246
374
  /** A page of a list: pass `cursor` back for the next one; none on the last. */
247
375
  type Page<T> = {
@@ -258,7 +386,7 @@ type SearchResult = Page<SearchEvent> & {
258
386
  /**
259
387
  * A visitor: `externalIds` the latest 10 external ids seen with it, newest first, and `externalIdCount` how many there
260
388
  * 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.
389
+ * 20 latest events, newest first, each with its detected signals the same way and `ip.country` when known.
262
390
  */
263
391
  type Visitor = {
264
392
  visitorId: string;
@@ -270,8 +398,8 @@ type Visitor = {
270
398
  eventCount: number;
271
399
  firstSeenAt: string;
272
400
  lastSeenAt: string;
273
- recentEvents: (Pick<SearchEvent, 'requestId' | 'externalId' | 'createdAt' | 'ip' | 'signals'> & {
274
- ipInfo?: Pick<IpInfo, 'country'>;
401
+ recentEvents: (Pick<SearchEvent, 'requestId' | 'externalId' | 'createdAt' | 'signals'> & {
402
+ ip: Pick<EventIp, 'address' | 'country'>;
275
403
  })[];
276
404
  };
277
405
  /**
@@ -350,7 +478,10 @@ type RelatedUser = {
350
478
  externalId: string;
351
479
  createdAt: string;
352
480
  };
353
- /** A value more than one user shares, or for a relation type the two users it ties and how many times. */
481
+ /**
482
+ * A value more than one user shares, or for a relation type the two users it ties; `count` is how many users share it
483
+ * (2 for a relation).
484
+ */
354
485
  type SharedValue = {
355
486
  type: RelatedType;
356
487
  weight: number;
@@ -505,7 +636,14 @@ declare const createClient: (apiKey: ApiKey, options?: ClientOptions) => {
505
636
  searchEvents: (filters?: SearchFilters) => Promise<SearchResult>;
506
637
  /** A visitor (a browser) with every external id seen with it. */
507
638
  getVisitor: (visitorId: string) => Promise<Visitor>;
508
- /** Deletes a visitor (a browser) and all its events. */
639
+ /**
640
+ * Reports what an event turned out to be, like after a chargeback or a review. The latest report counts, and it
641
+ * never changes the event's score.
642
+ */
643
+ reportOutcome: (requestId: string, outcome: Outcome) => Promise<{
644
+ requestId: string;
645
+ outcome: Outcome;
646
+ }>;
509
647
  deleteVisitor: (visitorId: string) => Promise<{
510
648
  visitorId: string;
511
649
  deletedEvents: number;
@@ -576,7 +714,7 @@ declare const createClient: (apiKey: ApiKey, options?: ClientOptions) => {
576
714
  /** The client `createClient` makes. */
577
715
  type Client = ReturnType<typeof createClient>;
578
716
  /** A webhook delivery's body: the event, without its velocity. */
579
- type WebhookEvent = Omit<Event, 'velocity'>;
717
+ type WebhookEvent = Omit<Event, 'broadVisitorId' | 'proximity' | 'rawDeviceAttributes' | 'velocity' | keyof GlobalFields>;
580
718
  /**
581
719
  * Checks a webhook delivery's Zeno-Signature header against the project's webhook secret, and that it was signed in the
582
720
  * last `tolerance` seconds, so a captured delivery can't be replayed later. Pass the raw body. Resolves to the event
@@ -615,4 +753,4 @@ type UnsealOptions = {
615
753
  */
616
754
  declare const unsealResult: (sealed: string | undefined | null, options: UnsealOptions) => Promise<VerifyResult>;
617
755
  //#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 };
756
+ 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, SharedValue, Signal, SignalDetails, SignalReason, SignalResult, Signals, UnsealOptions, Velocity, Verdict, VerdictAction, VerdictReason, VerifyCheck, VerifyOptions, VerifyResult, VirtualMachineIndicator, Visitor, WebhookEvent, ZenoError, ZenoErrorCode, createClient, createProxy, unsealResult, verifyWebhook };
@@ -396,6 +396,7 @@ const SIGNALS = [
396
396
  "ai-agent",
397
397
  "privacy-browser",
398
398
  "rare-device",
399
+ "high-activity",
399
400
  "replayed",
400
401
  "residential-proxy",
401
402
  "private-relay",
@@ -447,7 +448,7 @@ const defineShape = (name, fields) => ({
447
448
  const EVENT = defineShape("an event", {
448
449
  requestId: "string",
449
450
  visitorId: "string",
450
- ip: "string",
451
+ ip: "object",
451
452
  createdAt: "string",
452
453
  riskScore: "number",
453
454
  signals: "object",
@@ -460,6 +461,10 @@ const VISITOR = defineShape("a visitor", {
460
461
  externalIdCount: "number",
461
462
  recentEvents: "array"
462
463
  });
464
+ const REPORTED_OUTCOME = defineShape("a reported outcome", {
465
+ requestId: "string",
466
+ outcome: "string"
467
+ });
463
468
  const DELETED_VISITOR = defineShape("an erasure", {
464
469
  visitorId: "string",
465
470
  deletedEvents: "number"
@@ -598,7 +603,16 @@ const createClient = (apiKey, options = {}) => {
598
603
  },
599
604
  /** A visitor (a browser) with every external id seen with it. */
600
605
  getVisitor: async (visitorId) => callApi("GET", `/visitors/${toPathSegment("visitorId", visitorId)}`, VISITOR),
601
- /** Deletes a visitor (a browser) and all its events. */
606
+ /**
607
+ * Reports what an event turned out to be, like after a chargeback or a review. The latest report counts, and it
608
+ * never changes the event's score.
609
+ */
610
+ reportOutcome: (requestId, outcome) => {
611
+ return callApi("POST", "/outcomes", REPORTED_OUTCOME, {
612
+ requestId,
613
+ outcome
614
+ });
615
+ },
602
616
  deleteVisitor: async (visitorId) => {
603
617
  return callApi("DELETE", `/visitors/${toPathSegment("visitorId", visitorId)}`, DELETED_VISITOR);
604
618
  },
@@ -734,8 +748,8 @@ const MISSING_KEY = "unsealResult needs the project's encryption key as key (is
734
748
  const keyBytesOf = (secret) => {
735
749
  const trimmedKey = requireSecret(secret, MISSING_KEY).trim();
736
750
  const keyBytes = /^[A-Za-z0-9+/]+={0,2}$/.test(trimmedKey) ? fromBase64(trimmedKey) : void 0;
737
- if (!keyBytes) throw new TypeError("unsealResult's key isn't base64: pass the project's encryption key as the dashboard shows it");
738
- if (keyBytes.length !== 32) throw new TypeError(/^[0-9a-f]{64}$/i.test(trimmedKey) ? "unsealResult's key looks like hex: pass the project's encryption key as the dashboard shows it, in base64" : `unsealResult's key is ${keyBytes.length} bytes, not 32: pass the project's encryption key as the dashboard shows it`);
751
+ if (!keyBytes) throw new TypeError("unsealResult's key isn't base64: pass the project's encryption key as the app shows it");
752
+ if (keyBytes.length !== 32) throw new TypeError(/^[0-9a-f]{64}$/i.test(trimmedKey) ? "unsealResult's key looks like hex: pass the project's encryption key as the app shows it, in base64" : `unsealResult's key is ${keyBytes.length} bytes, not 32: pass the project's encryption key as the app shows it`);
739
753
  return keyBytes;
740
754
  };
741
755
  const decryptWithAnyKey = async (keys, data) => {
@@ -780,7 +794,7 @@ const unsealResult = async (sealed, options) => {
780
794
  if (!EVENT.is(event)) throw new Error("The sealed result opened but isn't an event; update zeno.id/server");
781
795
  const failedChecks = [];
782
796
  const maxAge = options.maxAge ?? UNSEAL_MAX_AGE;
783
- if (options.ip && isIpMismatch(event.ip, options.ip)) failedChecks.push("ip-mismatch");
797
+ if (options.ip && isIpMismatch(event.ip.address, options.ip)) failedChecks.push("ip-mismatch");
784
798
  if (Date.now() - Date.parse(event.createdAt) > maxAge * 1e3) failedChecks.push("too-old");
785
799
  if (options.externalId !== void 0 && event.externalId !== void 0 && event.externalId !== options.externalId) failedChecks.push("external-id-mismatch");
786
800
  if (failedChecks.length > 0) return {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "zeno.id",
3
- "version": "0.3.2",
3
+ "version": "0.4.0",
4
4
  "description": "Zeno's SDK for device identification: the browser SDK, and the proxy route and API client for your server",
5
5
  "license": "MIT",
6
6
  "files": [