@shieldlabs-ai/node 0.0.0-stage → 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,594 @@
+/**
+ * Error hierarchy of the SDK.
+ *
+ * ShieldLabsError
+ *   ApiError (the server answered with an error status or an unusable body)
+ *     BadRequestError (400), AuthenticationError (401, 403), QuotaExceededError (402),
+ *     NotFoundError (404), RateLimitError (429), ServerError (5xx)
+ *   ConnectionError (network failure), TimeoutError (per-attempt timeout)
+ *   SignatureVerificationError, WebhookParseError
+ *   ValidationError (invalid arguments, detected before any HTTP request)
+ */
+/** Minimal view of response headers (a `Headers` object satisfies it). */
+interface HeadersLike {
+    get(name: string): string | null;
+}
+/** Base class of every error thrown by this SDK. */
+declare class ShieldLabsError extends Error {
+    name: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+interface ApiErrorOptions {
+    status: number;
+    /** Parsed response body: a JSON value when the body parses as JSON, the raw text otherwise, null when empty. */
+    body?: unknown;
+    headers?: HeadersLike | undefined;
+    cause?: unknown;
+}
+/** The server answered with an error status (or a success status with an unusable body). */
+declare class ApiError extends ShieldLabsError {
+    name: string;
+    /** HTTP status code. */
+    readonly status: number;
+    /** Parsed response body: JSON value, raw text, or null when the body was empty. */
+    readonly body: unknown;
+    /** Response headers. */
+    readonly headers: HeadersLike;
+    constructor(message: string, options: ApiErrorOptions);
+}
+/** HTTP 400. */
+declare class BadRequestError extends ApiError {
+    name: string;
+}
+/** HTTP 401 or 403: the key, secret or domain is wrong, or the domain is disabled. */
+declare class AuthenticationError extends ApiError {
+    name: string;
+}
+/**
+ * HTTP 402. Neither the History API nor the Management API returns it today: an account over its
+ * included volume keeps working and its profile shows a negative remaining count.
+ */
+declare class QuotaExceededError extends ApiError {
+    name: string;
+}
+/** HTTP 404: usually a wrong base URL or path. */
+declare class NotFoundError extends ApiError {
+    name: string;
+}
+/** HTTP 429. */
+declare class RateLimitError extends ApiError {
+    name: string;
+    /** Seconds to wait, from the Retry-After header, when the server sent one. */
+    readonly retryAfter: number | undefined;
+    constructor(message: string, options: ApiErrorOptions & {
+        retryAfter?: number | undefined;
+    });
+}
+/** HTTP 5xx, including gateway errors from edge proxies. */
+declare class ServerError extends ApiError {
+    name: string;
+}
+/** The request never produced an HTTP response (DNS, TLS, connection reset, and so on). */
+declare class ConnectionError extends ShieldLabsError {
+    name: string;
+}
+/** A request attempt took longer than the configured timeout. */
+declare class TimeoutError extends ShieldLabsError {
+    name: string;
+}
+/** The X-Shield-Signature header is missing, malformed or does not match the body. */
+declare class SignatureVerificationError extends ShieldLabsError {
+    name: string;
+}
+/** The webhook body is authentic but is not a usable ShieldLabs event. */
+declare class WebhookParseError extends ShieldLabsError {
+    name: string;
+}
+/** An argument is invalid. Thrown before any HTTP request is sent. */
+declare class ValidationError extends ShieldLabsError {
+    name: string;
+}
+
+/** Identifier types the History API can search by. */
+type LookupType = 'ip' | 'user_hid' | 'visitor_id' | 'request_id' | 'device_id' | 'session_id' | 'cookie_id';
+/** The three risk bands: trusted 0-29, suspicious 30-59, dangerous 60-100. */
+type RiskBand = 'trusted' | 'suspicious' | 'dangerous';
+/**
+ * Connection type of an identification. Known values are listed; unknown strings are kept as sent.
+ */
+type ConnectionType = 'direct' | 'mobile' | 'vpn' | 'proxy' | 'tor' | 'privacy_relay' | 'browser_vpn_proxy' | 'unknown' | (string & {});
+/** An IP address with its country. */
+interface IpInfo {
+    /** Dotted IPv4 address, or "" when none is known. */
+    ip: string;
+    /** English country name (for example "Germany"), or "" when unknown. */
+    country: string;
+}
+/** Where the visit came from. Every value is a string, "" when absent. */
+interface TrafficSource {
+    channel: string;
+    referrer_domain: string;
+    landing_url: string;
+    click_id_type: string;
+    utm_source: string;
+    utm_medium: string;
+    utm_campaign: string;
+    utm_content: string;
+    utm_term: string;
+}
+/** One weighted risk signal behind the Risk Score. Display and log these; branch on detection_flags. */
+interface IdentificationSignal {
+    /** Signal slug, for example "vpn" or "antidetect_browser". An open set: see SIGNALS for known values. */
+    name: string;
+    /** Weight of the signal. Can be negative. Never sum weights yourself. */
+    weight: number;
+    /** Server description of the signal (History API rows only; null for webhooks). */
+    description: string | null;
+}
+/** The 19 stable detection flags. A flag the server did not send is false. */
+interface DetectionFlags {
+    vpn: boolean;
+    privacy_relay: boolean;
+    browser_vpn_proxy: boolean;
+    tor: boolean;
+    proxy: boolean;
+    datacenter_ip: boolean;
+    abuser: boolean;
+    os_mismatch: boolean;
+    os_not_detected: boolean;
+    timezone_mismatch: boolean;
+    anti_detect_browser: boolean;
+    browser_automation: boolean;
+    ip_mismatch: boolean;
+    incognito: boolean;
+    search_bot: boolean;
+    suspicious_paid_click: boolean;
+    javascript_disabled: boolean;
+    stun_not_checked: boolean;
+    check_incomplete: boolean;
+}
+/**
+ * One identification (one run of the ShieldLabs agent in one browser), normalized from a
+ * webhook `data` object or a History API row. Property names follow the webhook JSON.
+ */
+interface Identification {
+    /** UUID of the identification, created in the browser. */
+    request_id: string;
+    /** Server-side visitor identifier (sticky to the device). */
+    visitor_id: string;
+    /** Server-side device identifier. The all-zero UUID means no usable device signals. */
+    device_id: string;
+    /** One visit on one origin. */
+    session_id: string;
+    /** First-party browser identifier kept by the agent. */
+    cookie_id: string;
+    /** Your User HID as sent by the browser: "anonymous" for anonymous checks, null when it was empty. */
+    user_hid: string | null;
+    /** Registered domain of the site. */
+    domain: string;
+    public_ip: IpInfo;
+    local_ip: IpInfo;
+    connection_type: ConnectionType;
+    os: string;
+    browser: string;
+    /** "desktop", "mobile", "tablet" or "unknown". */
+    device_type: string;
+    traffic_source: TrafficSource;
+    /** Integer 0-100. A value above 100 (999) is a rate-limit marker, never a score. */
+    risk_score: number;
+    signals: IdentificationSignal[];
+    detection_flags: DetectionFlags;
+    /**
+     * When the identification was observed, as an RFC 3339 UTC string with milliseconds
+     * (for example "2026-09-30T12:34:56.123Z"). null only when the server sent a timestamp
+     * that could not be parsed.
+     */
+    observed_at: string | null;
+    /** Which payload this identification was built from. */
+    source: 'webhook' | 'history';
+    /** The original webhook `data` object or History row, including fields this model omits. */
+    raw: Record<string, unknown>;
+}
+/** One page of History API results. */
+interface HistoryPage {
+    /** Identifications, newest first. */
+    data: Identification[];
+    /** Total number of identifications that match the lookup. */
+    total: number;
+}
+/** Domain profile from the Management API. */
+interface DomainProfile {
+    /** The registered domain. */
+    domain: string;
+    /** Remaining included identifications. Negative when the account is over its included volume. */
+    remaining_identifications: number;
+    /** Public Key with every character except the last 4 replaced by "*". */
+    public_key_masked: string;
+    /** Secret Key with every character except the last 4 replaced by "*". */
+    secret_key_masked: string;
+    /** When the domain was created, as an RFC 3339 UTC string with milliseconds, or null. */
+    created_at: string | null;
+    /** The original response object. */
+    raw: Record<string, unknown>;
+}
+declare enum UnknownEventTypeMarker {
+    /** Placeholder member. Never compare against it. */
+    Unknown = "unknown"
+}
+/**
+ * Type of `event_type` for an event this SDK version does not model. At runtime the value is the
+ * plain string the server sent (for example "identification.refined"). This type only exists so
+ * that `switch (event.event_type)` narrows the known event types exactly; it is assignable to
+ * `string`, and `String(event.event_type)` compares it with other strings. A type only: there is
+ * no runtime value to import.
+ */
+type UnknownEventType = UnknownEventTypeMarker;
+/** A verified `identification.scored` delivery. */
+interface IdentificationScoredEvent {
+    event_type: 'identification.scored';
+    schema_version: string;
+    /** Envelope timestamp as sent (RFC 3339). */
+    created_at: string;
+    data: Identification;
+    /** The parsed envelope as received. */
+    raw: Record<string, unknown>;
+}
+/** A verified `webhook.ping` delivery (sent by Verify in the analytics dashboard). */
+interface WebhookPingEvent {
+    event_type: 'webhook.ping';
+    schema_version: string;
+    created_at: string;
+    raw: Record<string, unknown>;
+}
+/** A verified delivery with an event type this SDK version does not model. */
+interface UnknownWebhookEvent {
+    event_type: UnknownEventType;
+    schema_version: string;
+    created_at: string;
+    raw: Record<string, unknown>;
+}
+/** Every event `webhooks.constructEvent` can return. */
+type WebhookEvent = IdentificationScoredEvent | WebhookPingEvent | UnknownWebhookEvent;
+/** Raw webhook body: the exact bytes received, or the same bytes decoded as UTF-8. */
+type WebhookPayload = string | Uint8Array | ArrayBuffer;
+/** Value of the X-Shield-Signature header, as your framework exposes it. */
+type SignatureHeader = string | readonly string[] | null | undefined;
+/** One endpoint signing secret, or several while you rotate secrets. */
+type WebhookSecret = string | readonly string[];
+/** Minimal response shape the SDK needs from a fetch implementation. */
+interface FetchResponseLike {
+    status: number;
+    ok: boolean;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}
+/** Request options the SDK passes to a fetch implementation. */
+interface FetchRequestInit {
+    method: 'GET';
+    headers: Record<string, string>;
+    signal: AbortSignal;
+}
+/** A fetch-compatible function (the global `fetch` satisfies it). */
+type FetchLike = (url: string, init: FetchRequestInit) => Promise<FetchResponseLike>;
+
+/** Webhook signature verification and typed event parsing. */
+interface Webhooks {
+    /**
+     * True when `signatureHeader` (X-Shield-Signature) is a valid signature of `payload` for any
+     * of the given secrets. Returns false for a malformed header, an empty secret or a payload that
+     * is not raw bytes or a string. Needs node:crypto: in edge runtimes use `verifySignatureAsync`.
+     */
+    verifySignature(payload: WebhookPayload, signatureHeader: SignatureHeader, secret: WebhookSecret): boolean;
+    /**
+     * Verifies the signature, then parses the body into a typed event.
+     * Throws SignatureVerificationError or WebhookParseError.
+     * Needs node:crypto: in edge runtimes use `constructEventAsync`.
+     */
+    constructEvent(payload: WebhookPayload, signatureHeader: SignatureHeader, secret: WebhookSecret): WebhookEvent;
+    /** Same as `verifySignature`, using WebCrypto where node:crypto is not available. */
+    verifySignatureAsync(payload: WebhookPayload, signatureHeader: SignatureHeader, secret: WebhookSecret): Promise<boolean>;
+    /** Same as `constructEvent`, using WebCrypto where node:crypto is not available. */
+    constructEventAsync(payload: WebhookPayload, signatureHeader: SignatureHeader, secret: WebhookSecret): Promise<WebhookEvent>;
+}
+
+type ApiName = 'History API' | 'Management API';
+interface TransportOptions {
+    apiName: ApiName;
+    /** Normalized base URL without a trailing slash. */
+    baseUrl: string;
+    /** Credential headers sent with every request. */
+    headers: Record<string, string>;
+    /** Credentials that must never appear in an error message or cause. */
+    secrets: readonly string[];
+    /** Per-attempt timeout in milliseconds. */
+    timeout: number;
+    maxRetries: number;
+    /** False for the Management API: a 429 there starts a 10-minute block, so it is never retried. */
+    retryRateLimited: boolean;
+    fetch: FetchLike | undefined;
+}
+interface RequestOptions {
+    query?: Record<string, string> | undefined;
+    signal?: AbortSignal | undefined;
+    /** Overrides the transport's maxRetries for this call. */
+    maxRetries?: number | undefined;
+    /** Caps the attempt timeout of this call in milliseconds; the client timeout still applies. */
+    timeout?: number | undefined;
+}
+interface JsonResponse {
+    body: unknown;
+    status: number;
+    headers: HeadersLike;
+}
+/** Sends GET requests with timeouts, retries and error mapping. Safe for concurrent use. */
+declare class Transport {
+    #private;
+    constructor(options: TransportOptions);
+    /** The client's per-attempt timeout in milliseconds. */
+    get timeout(): number;
+    getJson(path: string, options?: RequestOptions): Promise<JsonResponse>;
+}
+
+/** Options of the History API client. */
+interface ShieldLabsOptions {
+    /** Private API Key of the domain (sec_...). Keep it on your server. */
+    apiKey: string;
+    /** Origin of the History API. Default https://account.shieldlabs.ai. A trailing /api is removed. */
+    baseUrl?: string | undefined;
+    /** Timeout of one HTTP attempt in milliseconds. Default 10 000. */
+    timeout?: number | undefined;
+    /** Retries for connection errors, timeouts, 429 and 5xx. Default 2. */
+    maxRetries?: number | undefined;
+    /** Custom fetch implementation. Default: the global fetch. */
+    fetch?: FetchLike | undefined;
+    /**
+     * Accept a plain http `baseUrl` on a host other than localhost, 127.0.0.1 or [::1], for a test
+     * server. The key then travels unencrypted. Default false.
+     */
+    allowInsecureHttp?: boolean | undefined;
+}
+/** Options of `history.search`. */
+interface SearchOptions {
+    /** Page size from 1 to 100. Default 20. */
+    limit?: number | undefined;
+    /** Number of rows to skip. Default 0. */
+    offset?: number | undefined;
+    signal?: AbortSignal | undefined;
+}
+/** Options of `history.iterate`. */
+interface IterateOptions {
+    /** Rows per request from 1 to 100. Default 100. */
+    pageSize?: number | undefined;
+    /** Stop after this many identifications. Default: no limit. */
+    maxItems?: number | undefined;
+    signal?: AbortSignal | undefined;
+}
+/** Options of `identifications.get`. */
+interface GetIdentificationOptions {
+    /** Poll until the identification appears (true) or read once (false). Default true. */
+    wait?: boolean | undefined;
+    /**
+     * Total time budget of the wait in milliseconds, counted from the call. Default 10 000. The
+     * last poll runs at this deadline. Each poll is one HTTP attempt whose timeout is the client
+     * timeout, shortened to the time left but never below 1 second, so the last poll can end up
+     * to 1 second after the deadline. Pass `signal` (for example `AbortSignal.timeout(11_000)`)
+     * for a hard limit that also cancels a request in flight.
+     */
+    timeout?: number | undefined;
+    /**
+     * Base wait between polls in milliseconds. The waits are 1, 2, 4 and 6 times this value, then 8
+     * times it for every later wait, each capped at 2 000 or at this value when it is longer.
+     * Default 250, which gives waits of 250, 500, 1 000, 1 500 and then 2 000; 1 000 gives 1 000
+     * and then 2 000; 3 000 gives 3 000 every time.
+     */
+    pollInterval?: number | undefined;
+    signal?: AbortSignal | undefined;
+}
+/** Reads identifications from the History API. */
+declare class HistoryResource {
+    #private;
+    constructor(transport: Transport);
+    /**
+     * One page of identifications for one identifier, newest first.
+     * `GET /api/v1/history/{type}/{value}`.
+     */
+    search(type: LookupType, value: string, options?: SearchOptions): Promise<HistoryPage>;
+    /**
+     * Every identification for one identifier, newest first, fetched page by page. Rows repeated
+     * across pages (new rows can shift offsets) are skipped by request ID. Stops at `total`, at an
+     * empty page or after `maxItems`.
+     */
+    iterate(type: LookupType, value: string, options?: IterateOptions): AsyncGenerator<Identification, void, undefined>;
+}
+/** Reads single identifications by request ID. */
+declare class IdentificationsResource {
+    #private;
+    constructor(transport: Transport);
+    /**
+     * The identification with this request ID, or null when none is found.
+     *
+     * Scoring is asynchronous: the row appears about 1 to 3 seconds after the browser call and can
+     * be refined for up to about 10 seconds while follow-up checks finish; this returns the first
+     * version it sees. With `wait` (the default), `timeout` is the total budget of the call:
+     *
+     * - The first poll runs at once. The waits between polls are `pollInterval` times 1, 2, 4 and 6,
+     *   then 8 times it for every later wait, each capped at max(2 s, `pollInterval`): 250 ms,
+     *   500 ms, 1 s, 1.5 s and then every 2 s by default, and every 3 s for a `pollInterval` of
+     *   3 s. A wait that would pass the deadline is cut short, so the last poll runs at the
+     *   deadline.
+     * - Each poll is one HTTP attempt without retries, with the timeout
+     *   min(client timeout, max(time left, 1 s)).
+     * - 429, 5xx, connection errors and timeouts do not end the wait. After a 429 the next wait is
+     *   the longest of the scheduled wait, 1 s and the Retry-After capped at 10 s (a missing
+     *   Retry-After, 0 or a past date counts as 0), cut short at the deadline like any other wait.
+     *   When the capped Retry-After is longer than the time left, that RateLimitError is thrown at
+     *   once.
+     * - At the deadline, the error of the last poll is thrown if it failed; otherwise the result
+     *   is null.
+     * - 400, 401, 403 and 404 (and any other error that another poll cannot fix) are thrown at once.
+     */
+    get(requestId: string, options?: GetIdentificationOptions): Promise<Identification | null>;
+}
+/**
+ * Client for the History API (`https://account.shieldlabs.ai`), authenticated with the Private
+ * API Key of one domain. Stateless apart from its configuration, so one instance can be shared
+ * by concurrent requests.
+ */
+declare class ShieldLabs {
+    /** Single identifications by request ID, with wait-for-verdict polling. */
+    readonly identifications: IdentificationsResource;
+    /** History lookups by identifier. */
+    readonly history: HistoryResource;
+    constructor(options: ShieldLabsOptions);
+}
+
+/** Options of the Management API client. */
+interface ShieldLabsManagementOptions {
+    /** Secret Key of the domain. Keep it on your server. */
+    secretKey: string;
+    /** The registered domain, for example "example.com". Normalized before it is sent. */
+    domain: string;
+    /** Origin of the Management API. Default https://api.shieldlabs.ai. */
+    baseUrl?: string | undefined;
+    /** Timeout of one HTTP attempt in milliseconds. Default 10 000. */
+    timeout?: number | undefined;
+    /** Retries for connection errors, timeouts and 5xx (never for 429). Default 2. */
+    maxRetries?: number | undefined;
+    /** Custom fetch implementation. Default: the global fetch. */
+    fetch?: FetchLike | undefined;
+    /**
+     * Accept a plain http `baseUrl` on a host other than localhost, 127.0.0.1 or [::1], for a test
+     * server. The Secret Key then travels unencrypted. Default false.
+     */
+    allowInsecureHttp?: boolean | undefined;
+}
+/** Options of `getProfile`. */
+interface GetProfileOptions {
+    signal?: AbortSignal | undefined;
+}
+/**
+ * Client for the Management API (`https://api.shieldlabs.ai`), authenticated with the Secret Key
+ * and the registered domain. The API allows about 15 requests per minute per IP and then blocks
+ * the IP for 10 minutes, so this client never retries a 429: call it sparingly and cache results.
+ * Safe for concurrent use.
+ */
+declare class ShieldLabsManagement {
+    #private;
+    /** The normalized domain sent in X-Shield-Domain. */
+    readonly domain: string;
+    constructor(options: ShieldLabsManagementOptions);
+    /** The domain profile: remaining identifications and masked keys. `GET /v1/profile`. */
+    getProfile(options?: GetProfileOptions): Promise<DomainProfile>;
+}
+
+/**
+ * Risk band for a Risk Score: trusted 0-29, suspicious 30-59, dangerous 60-100.
+ * A score above 100 (the 999 marker) is not a score: it returns "rate_limited".
+ */
+declare function riskBand(score: number): RiskBand | 'rate_limited';
+/** True for the rate-limit marker (a Risk Score above 100, sent as 999). */
+declare function isRateLimited(score: number): boolean;
+/** Why an identification did not pass `evaluateIdentification`. */
+type EvaluationReason = 'missing' | 'replayed' | 'stale' | 'rate_limited' | 'no_device_signals' | 'blocked_flag' | 'blocked_band';
+/** Result of `evaluateIdentification`. */
+interface Evaluation {
+    /** True when every check passed. */
+    ok: boolean;
+    /** The first check that failed, or null when `ok` is true. */
+    reason: EvaluationReason | null;
+    /** Band of the Risk Score ("rate_limited" for the 999 marker), or null when the identification is missing. */
+    band: RiskBand | 'rate_limited' | null;
+    /** The detection flag that failed the check, when `reason` is "blocked_flag". */
+    flag?: keyof DetectionFlags;
+}
+/** Options of `evaluateIdentification`. The defaults are a starting point to tune. */
+interface EvaluateOptions {
+    /**
+     * Maximum age of the identification in milliseconds, measured from `observed_at`. Default
+     * 300 000 (5 minutes). `Infinity` skips the freshness check.
+     */
+    maxAge?: number | undefined;
+    /** Current time (Date or epoch milliseconds). Default: now. */
+    now?: Date | number | undefined;
+    /** Bands that fail the check. Default ["dangerous"]. */
+    blockBands?: readonly RiskBand[] | undefined;
+    /** Detection flags that fail the check. Default ["browser_automation", "javascript_disabled"]. */
+    blockFlags?: readonly (keyof DetectionFlags)[] | undefined;
+    /**
+     * Returns true when this request ID was already used for a protected action. The SDK keeps
+     * no state: claim the request ID in your own store first (an atomic insert-if-absent) and
+     * return the result here. Must return a boolean synchronously.
+     */
+    isReplay?: ((requestId: string) => boolean) | undefined;
+}
+/**
+ * Applies a reusable guard policy to an identification. Checks run in this order and the first
+ * failure wins: missing identification, replayed request ID (`isReplay`), older than `maxAge`,
+ * rate-limit marker, all-zero device ID, a flag in `blockFlags`, a band in `blockBands`.
+ */
+declare function evaluateIdentification(identification: Identification | null | undefined, options?: EvaluateOptions): Evaluation;
+
+/** The all-zero UUID. As a device ID it means "no usable device signals". */
+declare const NIL_UUID = "00000000-0000-0000-0000-000000000000";
+/**
+ * Known risk signal slugs (`IdentificationSignal.name`). Signal names are an open set: new slugs
+ * can appear at any time, so compare against these constants and never treat them as exhaustive.
+ */
+declare const SIGNALS: Readonly<{
+    readonly TOR: "tor";
+    readonly JAVASCRIPT_DISABLED: "javascript_disabled";
+    readonly OS_MISMATCH: "os_mismatch";
+    readonly ANTIDETECT_BROWSER: "antidetect_browser";
+    readonly PROXY_ROUTED_ANTIDETECT: "proxy_routed_antidetect";
+    readonly PORT_SCAN_ROUTED_VIA_PROXY: "port_scan_routed_via_proxy";
+    readonly BROWSER_AUTOMATION: "browser_automation";
+    readonly STUN_NOT_CHECKED: "stun_not_checked";
+    readonly STUN_LATE_CORRECTION: "stun_late_correction";
+    readonly OS_NOT_DETECTED: "os_not_detected";
+    readonly BROWSER_VPN_PROXY: "browser_vpn_proxy";
+    readonly VPN: "vpn";
+    readonly PRIVACY_RELAY: "privacy_relay";
+    readonly PROXY: "proxy";
+    readonly DATACENTER_IP: "datacenter_ip";
+    readonly ABUSER: "abuser";
+    readonly TIMEZONE_MISMATCH: "timezone_mismatch";
+    readonly RATE_LIMITED: "rate_limited";
+}>;
+/** A known signal slug. */
+type KnownSignal = (typeof SIGNALS)[keyof typeof SIGNALS];
+/** Score ranges of the three risk bands (inclusive). */
+declare const RISK_BANDS: Readonly<{
+    readonly trusted: Readonly<{
+        min: 0;
+        max: 29;
+    }>;
+    readonly suspicious: Readonly<{
+        min: 30;
+        max: 59;
+    }>;
+    readonly dangerous: Readonly<{
+        min: 60;
+        max: 100;
+    }>;
+}>;
+
+/** Version of this SDK. Sent in the User-Agent header of every request. */
+declare const VERSION = "1.0.0";
+
+/** Webhook signature verification (X-Shield-Signature) and typed event parsing. */
+declare const webhooks: Webhooks;
+/**
+ * A stable, irreversible User HID for one of your accounts: HMAC-SHA256 of `userId` keyed with
+ * `secret`, as 64 lowercase hex characters. Compute it on your server and pass it to the browser
+ * agent instead of a raw email address or account ID. Throws ValidationError on empty input.
+ * Needs node:crypto: in edge runtimes use `userHidAsync`.
+ */
+declare function userHid(userId: string, secret: string): string;
+/** Same as `userHid`, as a promise (works in every runtime). */
+declare function userHidAsync(userId: string, secret: string): Promise<string>;
+
+export { ApiError, type ApiErrorOptions, AuthenticationError, BadRequestError, ConnectionError, type ConnectionType, type DetectionFlags, type DomainProfile, type EvaluateOptions, type Evaluation, type EvaluationReason, type FetchLike, type FetchRequestInit, type FetchResponseLike, type GetIdentificationOptions, type GetProfileOptions, type HeadersLike, type HistoryPage, type Identification, type IdentificationScoredEvent, type IdentificationSignal, type IpInfo, type IterateOptions, type KnownSignal, type LookupType, NIL_UUID, NotFoundError, QuotaExceededError, RISK_BANDS, RateLimitError, type RiskBand, SIGNALS, type SearchOptions, ServerError, ShieldLabs, ShieldLabsError, ShieldLabsManagement, type ShieldLabsManagementOptions, type ShieldLabsOptions, type SignatureHeader, SignatureVerificationError, TimeoutError, type TrafficSource, type UnknownEventType, type UnknownWebhookEvent, VERSION, ValidationError, type WebhookEvent, WebhookParseError, type WebhookPayload, type WebhookPingEvent, type WebhookSecret, type Webhooks, evaluateIdentification, isRateLimited, riskBand, userHid, userHidAsync, webhooks };