zeno.id 0.6.0 → 0.8.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 +105 -126
- package/dist/index.cjs +2 -2
- package/dist/index.d.cts +27 -39
- package/dist/index.d.ts +27 -39
- package/dist/index.js +2 -2
- package/dist/server/index.cjs +1 -2
- package/dist/server/index.d.cts +328 -171
- package/dist/server/index.d.ts +328 -171
- package/dist/server/index.js +1 -2
- package/package.json +1 -14
- package/dist/server/node.cjs +0 -1
- package/dist/server/node.d.cts +0 -21
- package/dist/server/node.d.ts +0 -21
- package/dist/server/node.js +0 -1
- package/dist/server/proxy-CUZ-Jwgy.d.cts +0 -36
- package/dist/server/proxy-CUZ-Jwgy.d.ts +0 -36
package/dist/server/index.d.cts
CHANGED
|
@@ -1,4 +1,70 @@
|
|
|
1
|
-
|
|
1
|
+
//#region src/server/util.d.ts
|
|
2
|
+
/** The project's API key, `sk_...`, from your server's environment: `process.env.ZENO_API_KEY`. */
|
|
3
|
+
type ApiKey = string | undefined;
|
|
4
|
+
/** Options both createClient and createProxyResponse take. */
|
|
5
|
+
type ApiOptions = {
|
|
6
|
+
/** The Zeno API's http(s) origin, for staging or a local Zeno. Zeno's own API by default. */
|
|
7
|
+
apiUrl?: string | undefined;
|
|
8
|
+
};
|
|
9
|
+
//#endregion
|
|
10
|
+
//#region src/server/proxy.d.ts
|
|
11
|
+
/** What `createProxyResponse` takes: the browser's request to your route, the IP it came from and your API key. */
|
|
12
|
+
type ProxyRequest = ApiOptions & {
|
|
13
|
+
/** The browser's request to your proxy route, a web `Request`. */
|
|
14
|
+
request: Request;
|
|
15
|
+
/**
|
|
16
|
+
* The IP address the request came from, your framework's client IP; behind a proxy of your own, turn on your
|
|
17
|
+
* framework's trust-proxy setting so it's the visitor's. Zeno refuses an identification without it (`400`).
|
|
18
|
+
*/
|
|
19
|
+
ip: string | null | undefined;
|
|
20
|
+
/** Your API key, from your server's environment: `process.env.ZENO_API_KEY`. */
|
|
21
|
+
apiKey: ApiKey;
|
|
22
|
+
};
|
|
23
|
+
/**
|
|
24
|
+
* Your proxy route's answer: a route on your own site between the browser SDK and the Zeno API. It forwards the
|
|
25
|
+
* browser's request to Zeno with your API key and the visitor's IP, and returns Zeno's answer: the script, or an
|
|
26
|
+
* identification's request ID with the visitor ID in a first-party cookie. Call it for every request on one path of
|
|
27
|
+
* your choice (the browser SDK's `path`, like `/zeno`); Zeno decides what each gets. The `apiKey` (undefined accepted)
|
|
28
|
+
* is checked on each call, so a module that reads it at load builds without the environment (as Next.js does when it
|
|
29
|
+
* collects page data); a request without it answers `500` and logs it. On Node's `(req, res)`, use `nodeHandler` from
|
|
30
|
+
* `zeno.id/server`.
|
|
31
|
+
*/
|
|
32
|
+
declare const createProxyResponse: (options: ProxyRequest) => Promise<Response>;
|
|
33
|
+
type NodeRequest = AsyncIterable<Uint8Array | string> & {
|
|
34
|
+
method?: string;
|
|
35
|
+
url?: string;
|
|
36
|
+
headers: {
|
|
37
|
+
host?: string;
|
|
38
|
+
};
|
|
39
|
+
rawHeaders: string[];
|
|
40
|
+
readableEnded: boolean;
|
|
41
|
+
socket: {
|
|
42
|
+
remoteAddress?: string;
|
|
43
|
+
encrypted?: boolean;
|
|
44
|
+
};
|
|
45
|
+
};
|
|
46
|
+
type NodeResponse = {
|
|
47
|
+
statusCode: number;
|
|
48
|
+
headersSent: boolean;
|
|
49
|
+
setHeader(name: string, value: string | string[]): unknown;
|
|
50
|
+
end(body?: Uint8Array | string): unknown;
|
|
51
|
+
};
|
|
52
|
+
type FastifyRequest = {
|
|
53
|
+
raw: NodeRequest;
|
|
54
|
+
ip?: unknown;
|
|
55
|
+
};
|
|
56
|
+
type FastifyReply = {
|
|
57
|
+
raw: NodeResponse;
|
|
58
|
+
hijack(): unknown;
|
|
59
|
+
};
|
|
60
|
+
/**
|
|
61
|
+
* Your proxy route on Node's `(req, res)`: Express, Fastify or `http.createServer`. `app.all('/zeno', nodeHandler({
|
|
62
|
+
* apiKey: process.env.ZENO_API_KEY }))`. It passes `createProxyResponse` the request and the IP address it came from:
|
|
63
|
+
* Express's and Fastify's `req.ip` (behind a proxy of your own, set their trust proxy so it's the visitor's), else the
|
|
64
|
+
* socket's address. Mount it before any body parser (`express.json()`): it forwards the body as it came.
|
|
65
|
+
*/
|
|
66
|
+
declare const nodeHandler: (options: Omit<ProxyRequest, 'request' | 'ip'>) => (request: NodeRequest | FastifyRequest, response: NodeResponse | FastifyReply) => Promise<void>;
|
|
67
|
+
//#endregion
|
|
2
68
|
//#region src/server/index.d.ts
|
|
3
69
|
/** Every signal an event checks, the keys of its `signals`. */
|
|
4
70
|
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', 'storage-cleared'];
|
|
@@ -114,8 +180,8 @@ type RawDeviceAttributes = {
|
|
|
114
180
|
math?: string;
|
|
115
181
|
keyboard?: string;
|
|
116
182
|
};
|
|
117
|
-
/** What an event turned out to be, as your backend reports it. */
|
|
118
|
-
type Outcome = 'fraud' | '
|
|
183
|
+
/** What an event turned out to be, as your backend reports it: legitimate, or the type of fraud it was. */
|
|
184
|
+
type Outcome = 'legitimate' | 'payment-fraud' | 'account-takeover' | 'fake-account' | 'promotion-abuse' | 'multi-accounting' | 'platform-abuse' | 'content-abuse' | 'other-fraud';
|
|
119
185
|
/** What kind of bot an event was. */
|
|
120
186
|
type BotType = 'automation' | 'replayed' | 'forged-request' | 'fake-crawler' | 'crawler' | 'ai-agent';
|
|
121
187
|
/** The bot verdict, and what's known of the bot. */
|
|
@@ -177,12 +243,12 @@ type EventIp = {
|
|
|
177
243
|
/** A managed service's exit, like `private-relay` for iCloud Private Relay. */
|
|
178
244
|
exitServiceType?: 'private-relay' | 'secure-web-gateway' | 'satellite' | 'dns-resolver' | 'email-gateway';
|
|
179
245
|
exitServiceProvider?: string;
|
|
180
|
-
mobileNetwork
|
|
181
|
-
satelliteNetwork
|
|
246
|
+
mobileNetwork?: boolean;
|
|
247
|
+
satelliteNetwork?: boolean;
|
|
182
248
|
/** A crawler the lookup knows, like Googlebot's addresses. */
|
|
183
|
-
knownCrawler
|
|
249
|
+
knownCrawler?: boolean;
|
|
184
250
|
/** A private or reserved address that no one on the internet has. */
|
|
185
|
-
reservedAddress
|
|
251
|
+
reservedAddress?: boolean;
|
|
186
252
|
};
|
|
187
253
|
/** The browser, parsed on the server from the user agent and client hints. */
|
|
188
254
|
type EventBrowser = {
|
|
@@ -286,6 +352,8 @@ type Event = {
|
|
|
286
352
|
*/
|
|
287
353
|
returning?: boolean;
|
|
288
354
|
externalId?: string;
|
|
355
|
+
/** The external ID's scope, when your server set one (`verify`). */
|
|
356
|
+
scope?: string;
|
|
289
357
|
/** What the visitor was doing, as the browser's `identify({ action })` named it, like `login`. */
|
|
290
358
|
action?: string;
|
|
291
359
|
/** Your own key-values from the browser's `identify({ metadata })`. Not in search results. */
|
|
@@ -299,7 +367,7 @@ type Event = {
|
|
|
299
367
|
*/
|
|
300
368
|
updatedAt?: string;
|
|
301
369
|
origin?: string;
|
|
302
|
-
/** The page as origin and path,
|
|
370
|
+
/** The page as origin and path, never its query string or fragment. */
|
|
303
371
|
url?: string;
|
|
304
372
|
referrer?: string;
|
|
305
373
|
browser: EventBrowser;
|
|
@@ -322,20 +390,27 @@ type Event = {
|
|
|
322
390
|
radius: number;
|
|
323
391
|
confidence: number;
|
|
324
392
|
};
|
|
325
|
-
/** Only on getEvent and verify, not in webhooks
|
|
393
|
+
/** Only on getEvent and verify, not in webhooks. */
|
|
326
394
|
rawDeviceAttributes?: RawDeviceAttributes;
|
|
327
|
-
/** Only on getEvent and verify, not in webhooks
|
|
395
|
+
/** Only on getEvent and verify, not in webhooks. */
|
|
328
396
|
velocity?: Record<'5m' | '1h' | '24h', Velocity>;
|
|
329
397
|
/**
|
|
330
|
-
* Your other users this event ties to, by external
|
|
398
|
+
* Your other users this event ties to, by external ID and scope: those sharing its `visitorId`, its residential IP
|
|
331
399
|
* (`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
|
|
400
|
+
* enough on its own). Up to 25 of each. Only on getEvent and verify, not in webhooks.
|
|
333
401
|
*/
|
|
334
402
|
related?: {
|
|
335
|
-
visitorId:
|
|
336
|
-
residentialIp:
|
|
337
|
-
broadVisitorId:
|
|
403
|
+
visitorId: ExternalIdRef[];
|
|
404
|
+
residentialIp: ExternalIdRef[];
|
|
405
|
+
broadVisitorId: ExternalIdRef[];
|
|
338
406
|
};
|
|
407
|
+
/**
|
|
408
|
+
* The group of the event's user: one ID that every user tied to it through a shared strong value answers too (a
|
|
409
|
+
* visitor ID with the default weights), directly or through other users. Without an external ID, the group its
|
|
410
|
+
* visitor ID ties. `null` when there is none. It can change when groups join or come apart, so key a counter on it
|
|
411
|
+
* and keep what must last on your own user. Only on getEvent and verify, not in webhooks.
|
|
412
|
+
*/
|
|
413
|
+
groupId?: string | null;
|
|
339
414
|
} & GlobalFields;
|
|
340
415
|
/** A list filter takes one value, or several to match any of. */
|
|
341
416
|
type AnyOf<T> = T | T[];
|
|
@@ -343,6 +418,8 @@ type SearchFilters = {
|
|
|
343
418
|
apiKeyId?: AnyOf<string>;
|
|
344
419
|
visitorId?: string;
|
|
345
420
|
externalId?: string;
|
|
421
|
+
/** The `externalId`'s scope; without one, the user without a scope. */
|
|
422
|
+
scope?: string;
|
|
346
423
|
ip?: string;
|
|
347
424
|
requestId?: string;
|
|
348
425
|
country?: AnyOf<string>;
|
|
@@ -374,7 +451,7 @@ type SearchFilters = {
|
|
|
374
451
|
* version, and its `ip` the address with the country, city, asn and company, each left out when the event has none of
|
|
375
452
|
* them.
|
|
376
453
|
*/
|
|
377
|
-
type SearchEvent = Pick<Event, 'requestId' | 'visitorId' | 'verdict' | 'riskScore' | 'bot' | 'outcome' | 'confidence' | 'externalId' | 'action' | 'apiKeyId' | 'createdAt' | 'origin'> & {
|
|
454
|
+
type SearchEvent = Pick<Event, 'requestId' | 'visitorId' | 'verdict' | 'riskScore' | 'bot' | 'outcome' | 'confidence' | 'externalId' | 'scope' | 'action' | 'apiKeyId' | 'createdAt' | 'origin'> & {
|
|
378
455
|
signals: { [S in Signal]?: {
|
|
379
456
|
detected: true;
|
|
380
457
|
}; };
|
|
@@ -394,139 +471,191 @@ type SearchResult = Page<SearchEvent> & {
|
|
|
394
471
|
found?: number;
|
|
395
472
|
};
|
|
396
473
|
/**
|
|
397
|
-
*
|
|
398
|
-
*
|
|
399
|
-
* 20 latest events, newest first, each with its detected signals the same way and `ip.country` when known.
|
|
474
|
+
* One of your users as Zeno names it in an answer: your external ID and, when you gave it one, its scope. `user-1042`
|
|
475
|
+
* in `tenant-1` and in `tenant-2` are two users.
|
|
400
476
|
*/
|
|
401
|
-
type
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
externalIdCount: number;
|
|
405
|
-
signals: { [S in Signal]?: {
|
|
406
|
-
detected: true;
|
|
407
|
-
}; };
|
|
408
|
-
eventCount: number;
|
|
409
|
-
firstSeenAt: string;
|
|
410
|
-
lastSeenAt: string;
|
|
411
|
-
recentEvents: (Pick<SearchEvent, 'requestId' | 'externalId' | 'createdAt' | 'signals'> & {
|
|
412
|
-
ip: Pick<EventIp, 'address' | 'country'>;
|
|
413
|
-
})[];
|
|
477
|
+
type ExternalIdRef = {
|
|
478
|
+
externalId: string;
|
|
479
|
+
scope?: string;
|
|
414
480
|
};
|
|
481
|
+
/**
|
|
482
|
+
* The scopes a read covers: one, several, or `'*'` for every scope, as when it's left out. Users of two scopes are
|
|
483
|
+
* never related.
|
|
484
|
+
*/
|
|
485
|
+
type Scopes = string | string[];
|
|
415
486
|
/**
|
|
416
487
|
* What relates two users: the built-in `visitor-id` (a browser), `broad-visitor-id` (its hardware), `residential-ip`
|
|
417
488
|
* (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 `
|
|
489
|
+
* of your own like `payment-card` (a lowercase letter, then up to 31 lowercase letters, digits, `_` or `-`).
|
|
419
490
|
*/
|
|
420
491
|
type RelatedType = 'visitor-id' | 'broad-visitor-id' | 'ip' | 'residential-ip' | (string & {});
|
|
421
|
-
/**
|
|
422
|
-
* `identifier`, a value several users can share (a visitor id, a phone number); `relation`, a direct tie between two
|
|
423
|
-
* users (a referral, an invite). A type of your own keeps the kind its first relation gave it.
|
|
424
|
-
*/
|
|
425
|
-
type RelatedKind = 'identifier' | 'relation';
|
|
426
492
|
type ValueDetails = {
|
|
427
493
|
type: RelatedType;
|
|
428
494
|
/** The type's weight, 0 to 1: how much sharing it says two users are one person. */
|
|
429
495
|
weight: number;
|
|
430
|
-
/** Your own word for what happened, like `checkout` or `signup`, when it was added
|
|
496
|
+
/** Your own word for what happened, like `checkout` or `signup`, when it was added as a relation with one. */
|
|
431
497
|
action?: string;
|
|
432
|
-
/** When it happened: the `at` of
|
|
498
|
+
/** When it happened: the `at` of a relation (its latest call's), or when the first event brought it. */
|
|
433
499
|
at: string;
|
|
434
500
|
createdAt: string;
|
|
435
501
|
};
|
|
436
|
-
/** One of
|
|
437
|
-
type
|
|
438
|
-
|
|
502
|
+
/** One of the project's types with its weight and its Match within: a built-in, or one of your own. */
|
|
503
|
+
type RelatedWeight = {
|
|
504
|
+
type: RelatedType;
|
|
505
|
+
/** The weight in force, 0 to 1: the one you set, else the default. */
|
|
506
|
+
weight: number;
|
|
507
|
+
/** The weight the type has until you set one. */
|
|
508
|
+
defaultWeight: number;
|
|
509
|
+
/**
|
|
510
|
+
* Match within: how many days apart two users may have been seen with a value of the type and still share it. The
|
|
511
|
+
* days you set, else the default. `null` is any time apart.
|
|
512
|
+
*/
|
|
513
|
+
matchWithinDays: number | null;
|
|
514
|
+
/** The days the type has until you set them: `null` for a type of your own. */
|
|
515
|
+
defaultMatchWithinDays: number | null;
|
|
516
|
+
/** One of Zeno's own types (`visitor-id`, `ip`, ...), not one of yours. */
|
|
517
|
+
builtIn: boolean;
|
|
518
|
+
};
|
|
519
|
+
/**
|
|
520
|
+
* A user's group: everyone tied to the user through shared strong values, directly or through other users, all in the
|
|
521
|
+
* user's scope.
|
|
522
|
+
*/
|
|
523
|
+
type RelatedGroup = ExternalIdRef & {
|
|
524
|
+
/** The same for every user in the group. `null` for a user Zeno has no values of. */
|
|
525
|
+
groupId: string | null;
|
|
526
|
+
/**
|
|
527
|
+
* How many users the group has, the asked one included, up to 10,000: a larger group is answered as the 10,000
|
|
528
|
+
* users nearest the asked one. 0 without a group ID.
|
|
529
|
+
*/
|
|
530
|
+
size: number;
|
|
531
|
+
/** A page of the group's users, the asked one among them: no weights, no depth. Empty without a group ID. */
|
|
532
|
+
externalIds: ExternalIdRef[];
|
|
533
|
+
/** Pass it back for the next page; none on the last page. */
|
|
534
|
+
cursor?: string;
|
|
535
|
+
};
|
|
536
|
+
/** A group by its ID: every user tied through shared strong values, directly or through other users. */
|
|
537
|
+
type Group = {
|
|
538
|
+
/** The ID you asked for. */
|
|
539
|
+
groupId: string;
|
|
540
|
+
/** How many users the group has, up to 10,000: a larger group is answered as 10,000 of its users. */
|
|
541
|
+
size: number;
|
|
542
|
+
/** A page of the group's users: no weights, no depth. */
|
|
543
|
+
externalIds: ExternalIdRef[];
|
|
544
|
+
/** Pass it back for the next page; none on the last page. */
|
|
545
|
+
cursor?: string;
|
|
546
|
+
};
|
|
547
|
+
/** One of a user's values, like a visitor ID, an ip or a card's fingerprint. */
|
|
548
|
+
type RelatedValue = ValueDetails & {
|
|
439
549
|
value: string;
|
|
440
|
-
}
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
550
|
+
};
|
|
551
|
+
type RelatedValues = ExternalIdRef & {
|
|
552
|
+
/**
|
|
553
|
+
* The user's group, the same on every page. `null` for a user Zeno has no values of, and for a group of more than
|
|
554
|
+
* 10,000 users, which has no ID.
|
|
555
|
+
*/
|
|
556
|
+
groupId: string | null;
|
|
446
557
|
/**
|
|
447
|
-
* Shares one value weighing 0.
|
|
448
|
-
*
|
|
558
|
+
* Shares one value weighing 0.75 or more with another user of its scope: with the default weights a visitor id
|
|
559
|
+
* does, a residential ip or a type of your own only once you weigh it that much. Lesser ties never add up to one.
|
|
449
560
|
*/
|
|
450
561
|
duplicate: boolean;
|
|
451
562
|
/** Was ever identified in a browser; treat a user who wasn't as unverified. */
|
|
452
563
|
identified: boolean;
|
|
564
|
+
/** A page of the user's values, by type name and value. */
|
|
453
565
|
values: RelatedValue[];
|
|
454
|
-
/**
|
|
455
|
-
|
|
566
|
+
/** Pass it back for the next page; none on the last page. */
|
|
567
|
+
cursor?: string;
|
|
568
|
+
};
|
|
569
|
+
/** Another user (`externalId` in `scope`) who shares a `value` with the asked one. */
|
|
570
|
+
type Connection = ValueDetails & ExternalIdRef & {
|
|
571
|
+
value: string;
|
|
572
|
+
};
|
|
573
|
+
/** A value two or more of the users found share, with each of the users who share it and when they got it. */
|
|
574
|
+
type SharedValue = {
|
|
575
|
+
type: RelatedType;
|
|
576
|
+
/** The type's weight, 0 to 1. */
|
|
577
|
+
weight: number;
|
|
578
|
+
value: string;
|
|
579
|
+
externalIds: (ExternalIdRef & {
|
|
580
|
+
at: string;
|
|
581
|
+
createdAt: string;
|
|
582
|
+
})[];
|
|
456
583
|
};
|
|
457
584
|
/**
|
|
458
|
-
*
|
|
459
|
-
*
|
|
585
|
+
* Two of the related users who share values: `a` and `b` are their indexes in `externalIds` (`a` the lower), and
|
|
586
|
+
* `values` the indexes in `sharedValues` of what the two share, ascending.
|
|
460
587
|
*/
|
|
461
|
-
type
|
|
462
|
-
kind: 'identifier';
|
|
463
|
-
externalId: string;
|
|
464
|
-
value: string;
|
|
465
|
-
}) | (ValueDetails & {
|
|
466
|
-
kind: 'relation';
|
|
467
|
-
relatedExternalId: string;
|
|
468
|
-
});
|
|
588
|
+
type RelatedPair = [a: number, b: number, values: number[]];
|
|
469
589
|
type Related = {
|
|
470
590
|
externalId: string;
|
|
591
|
+
/** The scopes asked for; none for every scope. */
|
|
592
|
+
scope?: Scopes;
|
|
471
593
|
/** The type asked for; none when every type was walked. */
|
|
472
594
|
type?: RelatedType;
|
|
473
595
|
/**
|
|
474
596
|
* Every other user reached, heaviest first, each with its `weight` to the asked one: what the two share combined
|
|
475
|
-
* (`1 - Π(1 - weight)`, so with the default weights two shared ips make 0.44 and a
|
|
476
|
-
* multiplied along the strongest path for a user further away.
|
|
477
|
-
* related to.
|
|
597
|
+
* (`1 - Π(1 - weight)`, so with the default weights two shared ips make 0.44 and a visitor id and an ip 0.96),
|
|
598
|
+
* multiplied along the strongest path for a user further away.
|
|
478
599
|
*/
|
|
479
|
-
externalIds: {
|
|
480
|
-
externalId: string;
|
|
600
|
+
externalIds: (ExternalIdRef & {
|
|
481
601
|
weight: number;
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
/** The users the asked one shares a value with or is related to. */
|
|
602
|
+
})[];
|
|
603
|
+
/** What the asked user shares with others: one entry per other user and shared value. */
|
|
485
604
|
connections: Connection[];
|
|
605
|
+
/**
|
|
606
|
+
* Every value two or more of the users found share (the asked one included), each once with the users who share it.
|
|
607
|
+
* A value listing three users doesn't say every two of them share it: two users share a value only when both were
|
|
608
|
+
* seen with it within the type's Match within. `connections` and `pairs` say who shares it with whom.
|
|
609
|
+
*/
|
|
610
|
+
sharedValues: SharedValue[];
|
|
611
|
+
/**
|
|
612
|
+
* Which two of the users in `externalIds` share which of the `sharedValues`. The asked user is in no pair: what it
|
|
613
|
+
* shares is in `connections`. With `connections` this is the whole graph to draw.
|
|
614
|
+
*/
|
|
615
|
+
pairs: RelatedPair[];
|
|
616
|
+
/** The search may have left something unread: see `widelyShared` and `stoppedAt`. */
|
|
617
|
+
truncated: boolean;
|
|
618
|
+
/**
|
|
619
|
+
* The values more users share than the search read (it reads 50 users of a value), each with how many users have it
|
|
620
|
+
* (`users`). Page through all of a value's users with `lookupRelated`.
|
|
621
|
+
*/
|
|
622
|
+
widelyShared: {
|
|
623
|
+
type: RelatedType;
|
|
624
|
+
value: string;
|
|
625
|
+
users?: number;
|
|
626
|
+
}[];
|
|
627
|
+
/**
|
|
628
|
+
* The users the search stopped at: found, but not all of their values were read or followed. Call `getRelated` with
|
|
629
|
+
* one to continue the search from that user. The asked user is in the list when it has more values than one search
|
|
630
|
+
* follows: pass a `type`, or page its values with `getRelatedValues`.
|
|
631
|
+
*/
|
|
632
|
+
stoppedAt: ExternalIdRef[];
|
|
486
633
|
};
|
|
487
634
|
/** One of your users who has a value, and since when. */
|
|
488
|
-
type RelatedUser = {
|
|
489
|
-
externalId: string;
|
|
635
|
+
type RelatedUser = ExternalIdRef & {
|
|
490
636
|
createdAt: string;
|
|
491
637
|
};
|
|
492
638
|
/**
|
|
493
|
-
* A relation
|
|
494
|
-
*
|
|
495
|
-
* part of it: the project's settings hold each type's weight, applied when relations are read.
|
|
639
|
+
* A relation: an ip seen by another system (`type: 'ip'`) or a value of a type of your own (`{ type: 'payment-card',
|
|
640
|
+
* value }`). Its weight isn't part of it: the project holds each type's weight, applied when related users are read.
|
|
496
641
|
*/
|
|
497
|
-
type RelationTarget = {
|
|
498
|
-
externalId: string;
|
|
642
|
+
type RelationTarget = ExternalIdRef & {
|
|
499
643
|
type: RelatedType;
|
|
500
644
|
value: string;
|
|
501
|
-
} | {
|
|
502
|
-
externalId: string;
|
|
503
|
-
type: RelatedType;
|
|
504
|
-
relatedExternalId: string;
|
|
505
645
|
};
|
|
506
646
|
type RelationInput = RelationTarget & {
|
|
507
647
|
/** When it happened (a Date, an ISO string or epoch milliseconds), now by default; never in the future. */
|
|
508
648
|
at?: Date | string | number;
|
|
509
649
|
};
|
|
510
|
-
/**
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
*/
|
|
514
|
-
type RelationRemoval = {
|
|
515
|
-
externalId: string;
|
|
516
|
-
type: RelatedType;
|
|
517
|
-
value: string;
|
|
518
|
-
} | {
|
|
519
|
-
externalId: string;
|
|
520
|
-
type: RelatedType;
|
|
521
|
-
relatedExternalId: string;
|
|
522
|
-
};
|
|
523
|
-
/** The relation as the api stored it: what you sent, with `at` as an ISO string. */
|
|
650
|
+
/** A value to take back, named as you added it. */
|
|
651
|
+
type RelationRemoval = RelationTarget;
|
|
652
|
+
/** The value as the api stored it: what you sent, with `at` as an ISO string. */
|
|
524
653
|
type Relation = RelationTarget & {
|
|
525
654
|
at?: string;
|
|
526
655
|
};
|
|
527
|
-
/** A
|
|
656
|
+
/** A value as added: `created` says whether this call made it (false for one that was there already). */
|
|
528
657
|
type AddedRelation = Relation & {
|
|
529
|
-
|
|
658
|
+
created: boolean;
|
|
530
659
|
};
|
|
531
660
|
/** A link to one user's Related view for your admin panel to frame, and when it stops working (ISO). */
|
|
532
661
|
type Embed = {
|
|
@@ -535,22 +664,21 @@ type Embed = {
|
|
|
535
664
|
};
|
|
536
665
|
type ClientOptions = ApiOptions;
|
|
537
666
|
/**
|
|
538
|
-
* The api's error codes, any other string for one added later. `not_found` (`404`): no such event or
|
|
539
|
-
* project. `
|
|
540
|
-
*
|
|
541
|
-
*
|
|
542
|
-
* unavailable; the SDK searches again after its `Retry-After`.
|
|
667
|
+
* The api's error codes, any other string for one added later. `not_found` (`404`): no such event, visitor or group in
|
|
668
|
+
* the project. `account_closed` (`402`): Zeno closed the organization's account, as for unpaid invoices, and every call
|
|
669
|
+
* is refused until it's reopened; contact support. `search_unavailable` (`503`): search is briefly unavailable; the SDK
|
|
670
|
+
* searches again after its `Retry-After`.
|
|
543
671
|
*
|
|
544
672
|
* The SDK's own: `request_failed` for an error answer without a code, or a success answer that isn't what the call
|
|
545
|
-
* returns; `network_error` (status `0`) when the api couldn't be reached or didn't answer within 10 seconds
|
|
546
|
-
* `invalid_request` with status `0` for an empty id, refused before
|
|
673
|
+
* returns; `network_error` (status `0`) when the api couldn't be reached or didn't answer within 10 seconds (`verify`
|
|
674
|
+
* within 10 seconds in all, its retries included); `invalid_request` with status `0` for an empty id, refused before
|
|
675
|
+
* anything is sent.
|
|
547
676
|
*/
|
|
548
|
-
type ZenoErrorCode = 'invalid_request' | 'invalid_api_key' | '
|
|
677
|
+
type ZenoErrorCode = 'invalid_request' | 'invalid_api_key' | 'account_closed' | 'not_found' | 'method_not_allowed' | 'rate_limited' | 'relation_limit_reached' | 'search_unavailable' | 'server_error' | 'request_failed' | 'network_error' | (string & {});
|
|
549
678
|
/**
|
|
550
679
|
* An error answer of the api, with its status and error code like `not_found`, and for a `429 rate_limited` or `503
|
|
551
|
-
* search_unavailable` the seconds to wait from its `Retry-After`.
|
|
552
|
-
*
|
|
553
|
-
* while the organization's account is closed is a `402` `account_closed`: contact support to reopen it.
|
|
680
|
+
* search_unavailable` the seconds to wait from its `Retry-After`. Any call while the organization's account is closed
|
|
681
|
+
* is a `402` `account_closed`: contact support to reopen it.
|
|
554
682
|
*/
|
|
555
683
|
declare class ZenoError extends Error {
|
|
556
684
|
readonly status: number;
|
|
@@ -581,6 +709,11 @@ type VerifyOptions = {
|
|
|
581
709
|
* succeeded (the password matched, the account exists), with the user's ID, so a failed login attaches nothing.
|
|
582
710
|
*/
|
|
583
711
|
externalId?: string;
|
|
712
|
+
/**
|
|
713
|
+
* The scope the user is in, like `tenant-1`, when your users are in scopes: the same `externalId` in another scope
|
|
714
|
+
* is another user. Only with `externalId`.
|
|
715
|
+
*/
|
|
716
|
+
scope?: string;
|
|
584
717
|
/**
|
|
585
718
|
* Makes sending the same verify again safe: a repeat with this key within 5 minutes answers what the first did,
|
|
586
719
|
* instead of `already-used`. The SDK makes one per call and retries a lost answer with it itself; pass your own (8
|
|
@@ -597,8 +730,7 @@ type VerifyResult = {
|
|
|
597
730
|
reasons: (VerifyCheck | VerdictReason)[];
|
|
598
731
|
/**
|
|
599
732
|
* The event, from `verify` with its velocity as `getEvent` has it (`event.velocity['24h'].distinctExternalId`, or
|
|
600
|
-
* `sameAction` without external IDs), its velocity counted before verify attached your `externalId`.
|
|
601
|
-
* `verify`: `unsealResult` runs on your server and has no velocity.
|
|
733
|
+
* `sameAction` without external IDs), its velocity counted before verify attached your `externalId`.
|
|
602
734
|
*/
|
|
603
735
|
event?: Event;
|
|
604
736
|
};
|
|
@@ -620,18 +752,17 @@ declare const createClient: (apiKey: ApiKey, options?: ClientOptions) => {
|
|
|
620
752
|
* seconds (`too-old`, 5 minutes by default) or belongs to another user than `externalId`
|
|
621
753
|
* (`external-id-mismatch`); otherwise it answers the event's verdict. Call it after the action succeeded (the
|
|
622
754
|
* password matched, the account exists), with the user's ID: `externalId` is attached to an event without one.
|
|
623
|
-
* It writes nothing else. A lost answer (a network error or a 5xx) is sent again twice with the same
|
|
624
|
-
* idempotency key, which answers the first result rather than `already-used`.
|
|
755
|
+
* It writes nothing else. A lost answer (a network error or a 5xx) is sent again, twice at most, with the same
|
|
756
|
+
* idempotency key, which answers the first result rather than `already-used`. It answers or throws within 10
|
|
757
|
+
* seconds, those retries included. Other api errors throw.
|
|
625
758
|
*/
|
|
626
759
|
verify: (requestId: string | undefined | null, options?: VerifyOptions) => Promise<VerifyResult>;
|
|
627
760
|
getEvent: (requestId: string) => Promise<Event>;
|
|
628
761
|
/** Events matching every filter, newest first; pass the cursor back for the next page. */
|
|
629
762
|
searchEvents: (filters?: SearchFilters) => Promise<SearchResult>;
|
|
630
|
-
/** A visitor (a browser) with every external id seen with it. */
|
|
631
|
-
getVisitor: (visitorId: string) => Promise<Visitor>;
|
|
632
763
|
/**
|
|
633
|
-
* Reports what an event turned out to be
|
|
634
|
-
* never changes the event's score.
|
|
764
|
+
* Reports what an event turned out to be: `legitimate`, or the type of fraud it was, like `payment-fraud` after
|
|
765
|
+
* a chargeback. The latest report counts, and it never changes the event's score.
|
|
635
766
|
*/
|
|
636
767
|
reportOutcome: (requestId: string, outcome: Outcome) => Promise<{
|
|
637
768
|
requestId: string;
|
|
@@ -641,60 +772,114 @@ declare const createClient: (apiKey: ApiKey, options?: ClientOptions) => {
|
|
|
641
772
|
visitorId: string;
|
|
642
773
|
deletedEvents: number;
|
|
643
774
|
}>;
|
|
644
|
-
/**
|
|
645
|
-
|
|
646
|
-
|
|
775
|
+
/**
|
|
776
|
+
* Deletes everything stored for one of your users (in its `scope`, when it has one): their events, and what
|
|
777
|
+
* relates them to devices and others.
|
|
778
|
+
*/
|
|
779
|
+
deleteExternalId: (externalId: string, { scope }?: {
|
|
780
|
+
scope?: string;
|
|
781
|
+
}) => Promise<ExternalIdRef & {
|
|
647
782
|
deletedEvents: number;
|
|
648
783
|
}>;
|
|
649
784
|
/**
|
|
650
|
-
*
|
|
651
|
-
*
|
|
785
|
+
* Adds a relation to one of your users (in its `scope`, when it has one): an ip seen by another system, or a
|
|
786
|
+
* value of a type of your own (a card's fingerprint, your own device id). Users who have the same value are
|
|
787
|
+
* related, never across scopes; you never relate two users yourself. Visitor ids only come from events with an
|
|
652
788
|
* external id, so `identified` means the user was seen in a browser.
|
|
653
789
|
*
|
|
654
|
-
*
|
|
655
|
-
*
|
|
656
|
-
* again.
|
|
790
|
+
* Free, like reads. `created` says whether the call added the value; sending one again only brings it up to
|
|
791
|
+
* date.
|
|
657
792
|
*/
|
|
658
793
|
addRelation: ({ at, ...relation }: RelationInput) => Promise<AddedRelation>;
|
|
659
794
|
/**
|
|
660
|
-
* Takes back a
|
|
661
|
-
*
|
|
795
|
+
* Takes back a value added with `addRelation`. What events added (a visitor id, an ip seen with an event)
|
|
796
|
+
* stays. Free.
|
|
662
797
|
*
|
|
663
|
-
* Answers `{ removed: false }` when there was
|
|
798
|
+
* Answers `{ removed: false }` when there was no relation to take back, so it's safe to repeat.
|
|
664
799
|
*/
|
|
665
800
|
removeRelation: (relation: RelationRemoval) => Promise<{
|
|
666
801
|
removed: boolean;
|
|
667
802
|
}>;
|
|
668
803
|
/**
|
|
669
|
-
* One of your users' values
|
|
670
|
-
* share one value weighing 0.
|
|
804
|
+
* One of your users' values (in its `scope`, when it has one), of one `type` or every type, each with its
|
|
805
|
+
* weight, whether they share one value weighing 0.75 or more with another user of the scope (`duplicate`) and
|
|
806
|
+
* their group (`groupId`). 500 a page by default (`limit` up to 500); pass the cursor back for the next page.
|
|
671
807
|
*/
|
|
672
|
-
getRelatedValues: (externalId: string, { type }?: {
|
|
808
|
+
getRelatedValues: (externalId: string, { scope, type, ...page }?: {
|
|
809
|
+
scope?: string;
|
|
673
810
|
type?: RelatedType;
|
|
811
|
+
limit?: number;
|
|
812
|
+
cursor?: string;
|
|
674
813
|
}) => Promise<RelatedValues>;
|
|
675
814
|
/**
|
|
676
|
-
* Your users who have one value, like everyone with one
|
|
677
|
-
* pass the cursor back for
|
|
815
|
+
* Your users who have one value, like everyone who paid with one card, in the `scope` you pass (several, or
|
|
816
|
+
* `'*'` for every scope, as without one), 20 a page by default (`limit` up to 100); pass the cursor back for
|
|
817
|
+
* the next page.
|
|
678
818
|
*/
|
|
679
|
-
lookupRelated: (type: RelatedType, value: string, page?: {
|
|
819
|
+
lookupRelated: (type: RelatedType, value: string, { scope, ...page }?: {
|
|
820
|
+
scope?: Scopes;
|
|
680
821
|
limit?: number;
|
|
681
822
|
cursor?: string;
|
|
682
823
|
}) => Promise<Page<RelatedUser>>;
|
|
683
824
|
/**
|
|
684
|
-
* Your users related to one through shared values
|
|
685
|
-
*
|
|
825
|
+
* Your users related to one through shared values of every type, or of one `type`, up to `depth` (1 or 2, 1 by
|
|
826
|
+
* default) hops away, heaviest first, each with its weight. A deeper search reads more and takes longer. With
|
|
827
|
+
* `scope`, the user in that scope; with several, the user in each of them, related only to users of those
|
|
828
|
+
* scopes; `'*'`, or none, the user in every scope it has, related to users of any scope.
|
|
686
829
|
*/
|
|
687
|
-
getRelated: (externalId: string, { type, depth }?: {
|
|
830
|
+
getRelated: (externalId: string, { scope, type, depth }?: {
|
|
831
|
+
scope?: Scopes;
|
|
688
832
|
type?: RelatedType;
|
|
689
833
|
depth?: number;
|
|
690
834
|
}) => Promise<Related>;
|
|
691
835
|
/**
|
|
692
|
-
*
|
|
693
|
-
*
|
|
694
|
-
*
|
|
836
|
+
* One of your users' group (in its `scope`, when it has one): the ID every user tied to it through shared
|
|
837
|
+
* strong values answers (the event's `groupId`), how many users it has (`size`) and its users, the asked one
|
|
838
|
+
* among them, 500 a page by default (`limit` up to 500); pass the cursor back for the next page. Check a fact
|
|
839
|
+
* that must hold once per group, like a reward, against these users in your own records. A group of more than
|
|
840
|
+
* 10,000 users is answered as the 10,000 nearest the asked one.
|
|
841
|
+
*/
|
|
842
|
+
getRelatedGroup: (externalId: string, { scope, ...page }?: {
|
|
843
|
+
scope?: string;
|
|
844
|
+
limit?: number;
|
|
845
|
+
cursor?: string;
|
|
846
|
+
}) => Promise<RelatedGroup>;
|
|
847
|
+
/**
|
|
848
|
+
* A group by its ID, with its `size` and its users, 500 a page by default (`limit` up to 500; pass the cursor
|
|
849
|
+
* back for the next page): for an event without a user, whose `groupId` is its visitor ID's group. An ID that
|
|
850
|
+
* names no group any more throws `not_found`: when two groups join, the bigger one's ID stays and the other ID
|
|
851
|
+
* stops naming a group. A group past 10,000 users is answered as 10,000 of its users.
|
|
852
|
+
*/
|
|
853
|
+
getGroup: (groupId: string, page?: {
|
|
854
|
+
limit?: number;
|
|
855
|
+
cursor?: string;
|
|
856
|
+
}) => Promise<Group>;
|
|
857
|
+
/**
|
|
858
|
+
* Every type of the project, the built-ins and your own, each with its weight, its Match within and their
|
|
859
|
+
* defaults. A type weighing 0.75 or more makes duplicates and ties groups.
|
|
860
|
+
*/
|
|
861
|
+
getRelatedWeights: () => Promise<{
|
|
862
|
+
items: RelatedWeight[];
|
|
863
|
+
}>;
|
|
864
|
+
/**
|
|
865
|
+
* Sets one type's settings for the project, either or both in one call: its `weight` (0 to 1) and its
|
|
866
|
+
* `matchWithinDays` (how many days apart two users may have been seen with a value and still share it, 1 to
|
|
867
|
+
* 3650), each `null` to go back to the default. Both apply when related users are read, so the change counts
|
|
868
|
+
* for the values you have already; taking a type across 0.75 or changing a strong type's days can change group
|
|
869
|
+
* IDs. Answers the type.
|
|
870
|
+
*/
|
|
871
|
+
setRelatedType: (type: RelatedType, settings: {
|
|
872
|
+
weight?: number | null;
|
|
873
|
+
matchWithinDays?: number | null;
|
|
874
|
+
}) => Promise<RelatedWeight>;
|
|
875
|
+
/**
|
|
876
|
+
* A link to one user's Related view (their values, related users and recent events; in its `scope`, when it has
|
|
877
|
+
* one) for your admin panel at `origin` to frame, working for `ttl` seconds (300 to 3600, 900 by default). Make
|
|
878
|
+
* one per page view and never hand the API key to the browser.
|
|
695
879
|
*/
|
|
696
880
|
createEmbed: (embed: {
|
|
697
881
|
externalId: string;
|
|
882
|
+
scope?: string;
|
|
698
883
|
origin: string;
|
|
699
884
|
ttl?: number;
|
|
700
885
|
}) => Promise<Embed>;
|
|
@@ -706,39 +891,11 @@ type WebhookEvent = Omit<Event, 'broadVisitorId' | 'proximity' | 'rawDeviceAttri
|
|
|
706
891
|
/**
|
|
707
892
|
* Checks a webhook delivery's Zeno-Signature header against the project's webhook secret, and that it was signed in the
|
|
708
893
|
* last `tolerance` seconds, so a captured delivery can't be replayed later. Pass the raw body. Resolves to the event
|
|
709
|
-
* when it matched, else to undefined; rejects with a TypeError when the secret is missing
|
|
710
|
-
* signed body that isn't an event.
|
|
894
|
+
* when it matched, else to undefined; rejects with a TypeError when the secret is missing or the body isn't text (a
|
|
895
|
+
* parsed one), and with an Error for a signed body that isn't an event.
|
|
711
896
|
*/
|
|
712
897
|
declare const verifyWebhook: (body: string, header: string | null | undefined, secret: string | undefined, { tolerance }?: {
|
|
713
898
|
tolerance?: number | undefined;
|
|
714
899
|
}) => Promise<WebhookEvent | undefined>;
|
|
715
|
-
/** What `unsealResult` takes besides the sealed result. */
|
|
716
|
-
type UnsealOptions = {
|
|
717
|
-
/**
|
|
718
|
-
* The project's encryption key, base64 (32 bytes), as the dashboard shows it: `process.env.ZENO_ENCRYPTION_KEY`; or
|
|
719
|
-
* several, tried in order, while you rotate it: `[current, previous]`.
|
|
720
|
-
*/
|
|
721
|
-
key: string | undefined | (string | undefined)[];
|
|
722
|
-
/**
|
|
723
|
-
* The IP address the request came from, as you pass it to `verify`: a sealed result from another ip blocks
|
|
724
|
-
* (`ip-mismatch`, for IPv6 another /64); left out, or of the other family than the event's, there's no ip check.
|
|
725
|
-
*/
|
|
726
|
-
ip?: string | null | undefined;
|
|
727
|
-
/** Your own id for the user: an event with another user's blocks (`external-id-mismatch`); one with none is fine. */
|
|
728
|
-
externalId?: string;
|
|
729
|
-
/** Seconds a sealed result stays good for, 5 minutes (300) by default, as with `verify`; an older one blocks. */
|
|
730
|
-
maxAge?: number;
|
|
731
|
-
};
|
|
732
|
-
/**
|
|
733
|
-
* Opens a sealed result from the browser with the project's encryption key and says what to do, in `verify`'s shape: `{
|
|
734
|
-
* action, reasons, event? }`. No sealed result (`undefined`, `null` or empty) is a `challenge` with `no-request-id`;
|
|
735
|
-
* one that doesn't open with any `key` (changed, sealed with another project's key, or not one at all) is a `block`
|
|
736
|
-
* with `not-found`. An opened one from another ip than `ip` blocks with `ip-mismatch`, compared as `verify` does, one
|
|
737
|
-
* older than `maxAge` seconds with `too-old`, another user's than `externalId` with `external-id-mismatch`; otherwise
|
|
738
|
-
* it answers the event's verdict. It can't tell a sealed result sent twice: where a repeat matters, use `verify`, which
|
|
739
|
-
* allows each request ID once. Rejects with a TypeError for a missing or malformed key. The format: base64(version |
|
|
740
|
-
* iv(12) | ciphertext | tag(16)), AES-256-GCM.
|
|
741
|
-
*/
|
|
742
|
-
declare const unsealResult: (sealed: string | undefined | null, options: UnsealOptions) => Promise<VerifyResult>;
|
|
743
900
|
//#endregion
|
|
744
|
-
export { AddedRelation, type ApiOptions, Bot, BotType, Client, ClientOptions, Confidence, Connection, Contradiction, Embed, Event, EventBot, EventBrowser, EventIp, ForgedPayloadIndicator, GlobalFields, Metadata, NetworkOwnerType, Outcome, Page, type
|
|
901
|
+
export { AddedRelation, type ApiOptions, Bot, BotType, Client, ClientOptions, Confidence, Connection, Contradiction, Embed, Event, EventBot, EventBrowser, EventIp, ExternalIdRef, ForgedPayloadIndicator, GlobalFields, Group, Metadata, NetworkOwnerType, Outcome, Page, type ProxyRequest, RawDeviceAttributes, Related, RelatedGroup, RelatedPair, RelatedType, RelatedUser, RelatedValue, RelatedValues, RelatedWeight, Relation, RelationInput, RelationRemoval, SIGNALS, Scopes, SearchEvent, SearchFilters, SearchResult, SharedValue, Signal, SignalDetails, SignalReason, SignalResult, Signals, Velocity, Verdict, VerdictAction, VerdictReason, VerifyCheck, VerifyOptions, VerifyResult, VirtualMachineIndicator, WebhookEvent, ZenoError, ZenoErrorCode, createClient, createProxyResponse, nodeHandler, verifyWebhook };
|