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.
@@ -1,4 +1,70 @@
1
- import { a as ApiOptions, i as ApiKey, n as ProxyOptions, r as createProxy, t as ProxyHandler } from "./proxy-CUZ-Jwgy.cjs";
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' | 'legitimate';
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: boolean;
181
- satelliteNetwork: boolean;
246
+ mobileNetwork?: boolean;
247
+ satelliteNetwork?: boolean;
182
248
  /** A crawler the lookup knows, like Googlebot's addresses. */
183
- knownCrawler: boolean;
249
+ knownCrawler?: boolean;
184
250
  /** A private or reserved address that no one on the internet has. */
185
- reservedAddress: boolean;
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, or only its origin; left out when the project keeps no page urls (`pageUrls`). */
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 or sealed results. */
393
+ /** Only on getEvent and verify, not in webhooks. */
326
394
  rawDeviceAttributes?: RawDeviceAttributes;
327
- /** Only on getEvent and verify, not in webhooks or sealed results. */
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 id: those sharing its `visitorId`, its residential IP
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 or sealed results.
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: string[];
336
- residentialIp: string[];
337
- broadVisitorId: string[];
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
- * A visitor: `externalIds` the latest 10 external ids seen with it, newest first, and `externalIdCount` how many there
398
- * are in all; `signals` holds every signal any of its events detected, as `{ detected: true }`, and `recentEvents` its
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 Visitor = {
402
- visitorId: string;
403
- externalIds: string[];
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 `phone` or `referral` (a lowercase letter, then up to 31 lowercase letters, digits, `_` or `-`).
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 by hand with one. */
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 one added by hand (its latest call's), or when the first event brought it. */
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 a user's values: a value they have, or the other user of a relation. */
437
- type RelatedValue = (ValueDetails & {
438
- kind: 'identifier';
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
- }) | (ValueDetails & {
441
- kind: 'relation';
442
- relatedExternalId: string;
443
- });
444
- type RelatedValues = {
445
- externalId: string;
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.5 or more with another user: a visitor id does, a shared ip never. Lesser ties never
448
- * add up to one, and a relation (a referral) never makes one.
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
- /** More values than the 500 answered. */
455
- truncated: boolean;
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
- * Another user (`externalId`) who has a value the asked one has, or the other user of a relation (`relatedExternalId`),
459
- * which needs no value.
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 Connection = (ValueDetails & {
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 browser and an ip 0.93),
476
- * multiplied along the strongest path for a user further away. With the users each shares a value with or is
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
- connections: Connection[];
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 added by hand: an ip seen by another system (`type: 'ip'`), a value of a type of your own (`{ type:
494
- * 'phone', value }`), or a tie between two of your users (`{ type: 'referral', relatedExternalId }`). Its weight isn't
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
- * A relation to take back: the value or the other user you added it with (`{ type: 'phone', value }` or `{ type:
512
- * 'referral', relatedExternalId }`).
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 relation as added: `linkWrite` says whether this call made a new link, the billed unit (a link added before isn't). */
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
- linkWrite: boolean;
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 visitor in the
539
- * project. `spend_limit_reached` (`402`): a spend limit you set for the project, its organization or the key stopped a
540
- * relation added by hand. `account_closed` (`402`): Zeno closed the organization's account, as for unpaid invoices, and
541
- * every call is refused until it's reopened; contact support. `search_unavailable` (`503`): search is briefly
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 anything is sent.
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' | 'spend_limit_reached' | 'account_closed' | 'not_found' | 'method_not_allowed' | 'rate_limited' | 'search_unavailable' | 'server_error' | 'request_failed' | 'network_error' | (string & {});
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`. A relation added by hand and refused because a spend
552
- * limit you set (the project's, its organization's or the key's) is reached is a `402` `spend_limit_reached`. Any call
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`. Only from
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`. Other api errors throw.
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, like after a chargeback or a review. The latest report counts, and it
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
- /** Deletes everything stored for one of your users: their events, and what relates them to devices and others. */
645
- deleteExternalId: (externalId: string) => Promise<{
646
- externalId: string;
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
- * Relates one of your users by hand: to an ip seen by another system, a value of a type of your own (a phone
651
- * number, your own device id) or another of your users (a referral). Visitor ids only come from events with an
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
- * A new link is billed like an identification (`linkWrite: true`); sending one again is free. Once a spend
655
- * limit you set is reached it throws a `402` `spend_limit_reached` and adds nothing; only a `429` is sent
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 relation added with `addRelation`: a value, or a relation between two users (both sides go,
661
- * whichever side you name). What events related (a visitor id, an ip seen with an event) stays. Free.
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 nothing added by hand to take back, so it's safe to repeat.
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 and relations, of one `type` or every type, each with its weight, and whether they
670
- * share one value weighing 0.5 or more with another user (`duplicate`). At most 500 (`truncated` past them).
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 phone number, 20 a page by default (`limit` up to 100);
677
- * pass the cursor back for the next page.
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 or relations of every type, or of one `type`, up to `depth`
685
- * (1 to 5, 1 by default) hops away, heaviest first, each with its weight.
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
- * A link to one user's Related view (their values, related users and recent events) for your admin panel at
693
- * `origin` to frame, working for `ttl` minutes (5 to 60, 15 by default). Make one per page view and never hand
694
- * the API key to the browser.
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, and with an Error for a
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 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 };
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 };